diff --git a/docs/specification.md b/docs/specification.md index 68a5ee2b7..3c5b118e3 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -33,7 +33,7 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt ## Glossary (Terms Used Precisely) * **Plan**: A tracked lifecycle for a single unit-of-work (which may spawn child plans). Plans follow the same namespace rules as actors. -* **Action**: A reusable plan template not tied to any project yet. Created via CLI commands (not YAML files). Actions follow the same namespace rules as actors. +* **Action**: A reusable plan template not tied to any project yet. Created via CLI commands with a required `--config` YAML configuration file that fully defines the action. CLI options provided alongside the config act as optional overrides. Actions follow the same namespace rules as actors. * **Strategize**: Read-only planning phase that produces a strategy and child plan blueprint. **All decisions are made during this phase.** * **Execute**: Phase that performs work in a sandbox; **spawns child plans** (based on decisions made in Strategize); produces artifacts/diffs. * **Apply**: Phase that commits sandbox results into the real project (and records an "applied" plan state). @@ -50,172 +50,171 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt * **Actor**: Anything conversational; may be a single agent/LLM or an entire graph of actors/tools. Defined via **YAML configuration files** (LangGraph definitions). Always named using `/` format. * **Session**: A user interaction context and conversation thread that can span multiple plans. * **Server**: Optional shared service for multi-user storage, permissions, and orchestration. Plans on remote projects can execute on the server. -* **Namespace**: Scoping mechanism for actors, tools, skills, resources, resource types, actions, plans, etc. `local/` is reserved for local-only items. User namespaces (`/`) and organization namespaces (`/`) are stored on the server. Built-in LLM actors use provider namespaces (e.g., `openai/`, `anthropic/`). Built-in resource types use no namespace prefix (e.g., `git`, `git-checkout`, `fs-mount`, `fs-directory`, `file`, `commit`). +* **Namespace**: Scoping mechanism for actors, tools, skills, resources, resource types, actions, plans, automation profiles, etc. `local/` is reserved for local-only items. User namespaces (`/`) and organization namespaces (`/`) are stored on the server. Built-in LLM actors use provider namespaces (e.g., `openai/`, `anthropic/`). Built-in resource types use no namespace prefix (e.g., `git`, `git-checkout`, `fs-mount`, `fs-directory`, `file`, `commit`). * **Decision**: A recorded choice point made during Strategize that affects downstream work. Decisions form a tree structure that enables correction and replay. * **Invariant**: A named constraint or rule that applies to plan execution. Invariants can be attached at four scopes: **global** (applies to all plans), **project** (applies to all plans targeting that project), **plan** (applies to a specific plan and its child plans), or **action** (carried forward as plan-level invariants when the action is used). Managed via the unified `agents invariant add/list/remove` command, or attached at creation time via `--invariant` flags on `agents project create`, `agents action create`, and `agents plan use`. **Precedence**: plan-level invariants override project-level, which override global-level, when conflicts exist. An **Invariant Reconciliation Actor** (set via `--invariant-actor` on actions, plans, and projects, or globally via `agents config set invariant-actor`) resolves conflicts and computes the effective invariant view when a plan enters Strategize. During Strategize, the effective invariants are recorded as `invariant_enforced` decisions in the decision tree. When a top-level plan spawns child plans, the parent's effective invariant view is passed down to each child plan. +* **Automation Profile**: A named collection of boolean flags that controls which tasks are automated vs. require human approval during plan execution. Built-in profiles (`locked-down`, `manual`, `supervised`, `trusted`, `autonomous`, `full-auto`) cover the spectrum from maximum human control to full automation. Custom profiles are defined in YAML configuration files, registered via `agents automation-profile add`, and follow the same `/` naming convention as other entities. Profiles control phase transitions, decision automation, validation self-fix behavior, strategy revision, child plan spawning, and safety requirements. * **ULID**: Universally Unique Lexicographically Sortable Identifier. Preferred over UUID for plan and decision IDs due to time-sortability. ## CLI Commands ### Command Synopsis -```text -agents|cleveragents [--data-dir PATH] [--config-path PATH] [--help] [--version] - [--install-completion [SHELL]] [--show-completion [SHELL]] - [args] +

+agents|cleveragents [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>]
+                     [--format (rich|color|table|plain|json|yaml)]
+                     [--help|-h] [--version]
+                     [--install-completion [<INST_SHELL>]] [--show-completion [<SHOW_SHELL>]]
+                     [-v...] <COMMAND> [<ARGS>...]
 
-agents version
-agents info
-agents diagnostics
-agents init [--yes]
+agents version
+agents info
+agents diagnostics
+agents init [--yes|-y]
 
-agents session create [--name NAME] [--actor ACTOR] [--metadata KEY=VALUE ...]
-agents session list [--format table|json]
-agents session show 
-agents session delete  [--yes]
-agents session export  --output FILE
-agents session import --input FILE [--name NAME]
-agents session tell "" [--session SESSION_ID|NAME] [--actor ACTOR] [--stream]
+agents session create [--actor <ACTOR>]
+agents session list
+agents session show <SESSION_ID>
+agents session delete [--yes|-y] <SESSION_ID>
+agents session export [(--output|-o) <FILE>] <SESSION_ID>
+agents session import (--input|-i) <FILE>
+agents session tell --session <SESSION_ID> [--actor <ACTOR>] [--stream] <PROMPT>
 
-agents project create --name/-n NAME [--description/-d TEXT]
-                     [--invariant TEXT ...] [--invariant-actor ACTOR]
-agents project link-resource --project/-p PROJECT --resource/-r RESOURCE [--read-only] [--alias ALIAS]
-agents project unlink-resource --project/-p PROJECT --resource/-r RESOURCE [--yes]
-agents project list [--namespace/-n NS] [--format table|json]
-agents project show  [--format rich|json]
-agents project set-validation --project/-p PROJECT [--resource NAME]
-                          [--test-command CMD] [--lint-command CMD]
-                          [--type-check-command CMD] [--build-command CMD]
-                          [--timeout SECONDS] [--clear]
-agents project delete  [--force/-f] [--yes]
-agents project context set --project PROJECT
-                          [--view strategize|execute|apply|default]
-                          [--include-resource NAME ...]
-                          [--exclude-resource NAME ...]
-                          [--include-path GLOB ...]
-                          [--exclude-path GLOB ...]
-                          [--hot-max-tokens N]
-                          [--warm-max-decisions N]
-                          [--cold-max-decisions N]
-                          [--query-limit N]
-                          [--max-file-size BYTES]
-                          [--max-total-size BYTES]
-                          [--summarize/--no-summarize]
-                          [--summary-max-tokens N]
-                          [--clear]
-agents project context show --project PROJECT [--view strategize|execute|apply|default]
-                          [--format table|json]
+agents project create [(--description|-d) <DESC>] [--resource <RESOURCE>]...
+                     [--invariant <INVARIANT>]... [--invariant-actor <ACTOR>] <NAME>
+agents project link-resource [--read-only] <PROJECT> <RESOURCE>
+agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE>
+agents project list [(--namespace|-n) NS] [<REGEX>]
+agents project show <PROJECT>
+agents project validation add [(--description|-d) <DESC>] [--required|--informational]
+                              [--timeout <SECONDS>] [--resource <RESOURCE>] <PROJECT> <COMMAND>
+agents project validation remove [--yes|-y] <PROJECT> <VALIDATION_ID>
+agents project validation list <PROJECT>
+agents project delete [--force|-f] [--yes|-y] <NAME>
+agents project context set[--view (strategize|execute|apply|default)]
+                          [--include-resource <INCLUDE_RESOURCE>]...
+                          [--exclude-resource <EXCLUDE_RESOURCE>]...
+                          [--include-path <INCLUDE_GLOB>]...
+                          [--exclude-path <EXCLUDE_GLOB>]...
+                          [--hot-max-tokens <N>]
+                          [--warm-max-decisions <N_WARM_MAX>]
+                          [--cold-max-decisions <N_COLD_MAX>]
+                          [--query-limit <N>]
+                          [--max-file-size <MAX_FILE_BYTES>]
+                          [--max-total-size <MAX_TOTAL_BYTES>]
+                          [--summarize|--no-summarize]
+                          [--summary-max-tokens <N>]
+                          [--clear] <PROJECT>
+agents project context show [--view (strategize|execute|apply|default)]
+                            <PROJECT>
 
-agents actor run --config/-c FILE... --prompt/-p TEXT [--output/-o FILE]
-                [--verbose/-v] [--unsafe/-u] [--context NAME]
-                [--context-dir PATH] [--load-context FILE]
-                [--temperature/-t FLOAT] [--allow-rxpy-in-run-mode]
-agents actor add  --config/-c FILE [--unsafe] [--set-default] [--option/-o key=value ...]
-agents actor update  [--config/-c FILE] [--unsafe|--safe] [--set-default]
-                 [--option/-o key=value ...]
-agents actor remove 
-agents actor list
-agents actor show 
-agents actor set-default 
-agents actor context add --name NAME  [-r/--recursive]
-agents actor context load --name NAME  [-r/--recursive]
-agents actor context rm --name NAME 
-agents actor context list [NAME] [--format table|json]
-agents actor context show --name NAME [PATH]
-agents actor context export --name NAME --output FILE
-agents actor context import --name NAME --input FILE
-agents actor context delete --name NAME [--yes]
-agents actor context clear --name NAME [--yes]
+agents actor run [(--output|-o) <OUTPUT_FILE>]
+                 [-v...] [--unsafe|-u] [--context <CONTEXT_NAME>]
+                 [--context-dir <CONTEXT_PATH>] [--load-context <LOAD_CONTEXT_NAME>]
+                 [(--temperature|-t) <TEMP>] [--allow-rxpy-in-run-mode]
+                 [--skill <SKILL>]... <NAME> <PROMPT>
+agents actor add (--config|-c) <FILE> [--unsafe] [(--option|-o) <key>=<value>]...
+                [--type (graph|agent)] [--update]
+                [--skill <SKILL>]... [(--description|-d) <DESC>] [<NAME>]
+agents actor remove <NAME>
+agents actor list
+agents actor show <NAME>
+agents actor context rm [--yes|-y] (--all|-a|<NAME>)
+agents actor context list [<REGEX>]
+agents actor context show <NAME>
+agents actor context export (--output|-o) <FILE> <NAME>
+agents actor context import [--update] (--input|-i) <FILE> [<NAME>]
+agents actor context delete [--yes|-y] (--all|-a|<NAME>)
+agents actor context clear [--yes|-y] (--all|-a|<NAME>)
 
-agents skill add  --config/-c FILE [--description/-d TEXT] [--upgrade]
-agents skill remove  [--yes]
-agents skill list [--namespace/-n NS] [--source SOURCE] [--format table|json]
-agents skill show  [--format rich|json]
-agents skill tools  [--format table|json]
+agents skill add (--config|-c) <FILE> [(--description|-d) <DESC>] [--update]
+                [--tool <TOOL>]... [--include-skill <INCLUDE_SKILL>]... [--mcp-server <SPEC>]... [<NAME>]
+agents skill remove [--yes|-y] <NAME>
+agents skill list [(--namespace|-n) <NS>] [--source <SOURCE>]
+agents skill show  <NAME>
+agents skill tools <NAME>
 
-agents tool add  --config/-c FILE [--description/-d TEXT] [--upgrade]
-agents tool remove  [--yes]
-agents tool list [--namespace/-n NS] [--source SOURCE] [--format table|json]
-agents tool show  [--format rich|json]
+agents tool add (--config|-c) <FILE> [(--description|-d) <DESC>] [--update]
+               [--source <SOURCE>] [--input-schema <JSON>] [--code <CODE>]
+               [--writes|--no-writes] [--checkpointable|--no-checkpointable] [<NAME>]
+agents tool remove [--yes|-y] <NAME>
+agents tool list [(--namespace|-n) <NS>] [--source <SOURCE>] [<REGEX>]
+agents tool show <NAME>
 
-agents resource type add  --config/-c FILE [--upgrade]
-agents resource type remove  [--yes]
-agents resource type list [--format table|json]
-agents resource type show  [--format rich|json]
+agents resource type add (--config|-c) <FILE> [--update]
+                       [--physical|--virtual] [--user-addable|--no-user-addable]
+                       [--sandbox-strategy <STRATEGY>] [--handler <NAME>]
+                       [--child-type spec]... [--cli-arg spec]... [<NAME>]
+agents resource type remove [--yes|-y] <NAME>
+agents resource type list [<REGEX>]
+agents resource type show <NAME>
 
-agents resource add [--description/-d TEXT] [--upgrade]   [type-specific-flags...]
-agents resource remove  [--yes]
-agents resource list [--namespace/-n NS] [--type/-t TYPE] [--format table|json]
-agents resource show  [--format rich|json]
-agents resource tree  [--depth/-d N] [--type/-t TYPE] [--format tree|json]
-agents resource link-child --parent/-p RESOURCE --child/-c RESOURCE
-agents resource unlink-child --parent/-p RESOURCE --child/-c RESOURCE [--yes]
+agents resource add [(--description|-d) <DESC>] [--update] <TYPE> <NAME> [type-specific-flags...]
+agents resource remove [--yes|-y] <NAME>
+agents resource list [(--namespace|-n) <NS>] [(--type|-t) <TYPE>] [<REGEX>]
+agents resource show <NAME>
+agents resource tree [(--depth|-d) <N>] [(--type|-t) <TYPE>] <NAME>
+agents resource link-child <PARENT> <CHILD>
+agents resource unlink-child [--yes|-y] <PARENT> <CHILD>
 
-agents plan list [--phase PHASE] [--state STATE] [--project PROJECT]
-                [--action ACTION] [--format table|json]
-agents plan use  --project/-p PROJECT [--project/-p PROJECT ...]
-               [--arg/-a name=value ...]
-               [--automation-level manual|review|auto]
-               [--safety-profile NAME]
-               [--require-sandbox/--no-require-sandbox]
-               [--require-checkpoints/--no-require-checkpoints]
-               [--require-apply-approval/--no-require-apply-approval]
-               [--allow-skill-category NAME ...]
-               [--deny-skill-category NAME ...]
-               [--invariant TEXT ...]
-               [--strategy-actor/-s ACTOR]
-               [--execution-actor/-e ACTOR]
-               [--estimation-actor ACTOR]
-               [--invariant-actor ACTOR]
-agents plan execute [PLAN_ID]
-agents plan apply  [--yes]
-agents plan status [PLAN_ID]
-agents plan cancel  [--reason/-r TEXT]
-agents plan tree [PLAN_ID] [--format tree|json|flat] [--show-superseded]
-agents plan explain  [--show-context] [--show-reasoning]
-agents plan correct  --mode revert|append --guidance/-g TEXT
-                   [--dry-run] [--yes]
-agents plan diff --plan 
-agents plan diff --correction 
-agents plan artifacts 
-agents plan prompt  ""
-agents plan resume 
-agents plan rollback   [--yes]
+agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
+                [--action <ACTION>] [<REGEX>]
+agents plan use [--automation-profile <PROFILE>]
+                [--invariant <INVARIANT>]...
+                [--strategy-actor <STRATEGY_ACTOR>]
+                [--execution-actor <EXEC_ACTOR>]
+                [--estimation-actor <EST_ACTOR>]
+                [--invariant-actor <INV_ACTOR>]
+                [--arg/-a name=value]...
+                <ACTION> <PROJECT>...
+agents plan execute <PLAN_ID>
+agents plan apply [--yes|-y] <PLAN_ID>
+agents plan status <PLAN_ID>
+agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>
+agents plan tree [--show-superseded] <PLAN_ID>
+agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>
+agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE>
+                   [--dry-run] [--yes|-y] <DECISION_ID>
+agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>)
+agents plan artifacts <PLAN_ID>
+agents plan prompt <PLAN_ID> <GUIDANCE>
+agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>
 
-agents action create 
-  --strategy-actor/-s ACTOR
-  --execution-actor/-e ACTOR
-  --definition-of-done/-d TEXT
-  [--description TEXT]
-  [--long-description TEXT]
-  [--arg/-a spec ...]
-  [--reusable/--no-reusable]
-  [--read-only]
-  [--available]
-  [--estimation-actor ACTOR]
-  [--invariant-actor ACTOR]
-  [--safety-profile NAME]
-  [--require-sandbox/--no-require-sandbox]
-  [--require-checkpoints/--no-require-checkpoints]
-  [--require-apply-approval/--no-require-apply-approval]
-  [--allow-skill-category NAME ...]
-  [--deny-skill-category NAME ...]
-  [--invariant TEXT ...]
-agents action list [--namespace/-n NS] [--state/-s STATE] [--available]
-agents action show 
-agents action available 
-agents action archive 
+agents action create (--config|-c) <CFG_FILE>
+                     [--strategy-actor <STRATEGY_ACTOR>]
+                     [--execution-actor <EXEC_ACTOR>]
+                     [--definition-of-done <DOD>]
+                     [(--description|-d) <DESC>]
+                     [--long-description <LONG_DESC>]
+                     [--reusable|--no-reusable]
+                     [--read-only]
+                     [--available]
+                     [--estimation-actor <EST_ACTOR>]
+                     [--invariant-actor <INV_ACTOR>]
+                     [--automation-profile <PROFILE>]
+                     [--invariant <INVARIANT>]...
+                     [--arg <ARG_SPEC>]...
+                     [<NAME>]
+agents action list [(--namespace|-n) <NS>] [(--state|-s) <STATE>] [--available] [<REGEX>]
+agents action show <ACTION_NAME>
+agents action available <ACTION_NAME>
+agents action archive <ACTION_NAME>
 
-agents config set  
-agents config get 
-agents config list
-agents providers list
+agents automation-profile add (--config|-c) <FILE> [--update] [<NAME>]
+agents automation-profile remove [--yes|-y] <NAME>
+agents automation-profile list [<REGEX>]
+agents automation-profile show <NAME>
 
-agents invariant add "" [--global] [--project/-p PROJECT] [--plan PLAN_ID] [--action ACTION]
-agents invariant list [--global] [--project/-p PROJECT] [--plan PLAN_ID] [--action ACTION]
-                     [--effective] [--format table|json]
-agents invariant remove  [--yes]
-```
+agents config set <key> <value>
+agents config get <key>
+agents config list [--filter-values <REGEX>] [<REGEX>]
+
+agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]...
+                     [--action ACTION]... <INVARIANT_TEXT>
+agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID] [--action ACTION]
+                     [--effective] [<REGEX>]
+agents invariant remove [--yes|-y] <INVARIANT_ID>
+
### Command Reference @@ -228,6 +227,13 @@ Configure global state locations and shell integration for every command. - `--data-dir PATH`: Overrides the global data directory (database, caches, sessions, logs). When omitted, the default data location is used. - `--config-path PATH`: Overrides the global configuration file path. When omitted, the default config path is used. +- `--format rich|color|table|plain|json|yaml`: Set the output rendering format for all subcommands. When omitted, the value is read from the global config key `format`. If not set in config either, defaults to `rich`. See **Output Rendering Framework** for full details on each format. The available formats are: + - `rich` (default): Uses modern rich CLI elements with dynamic effects, animated spinners, progress bars, and generous color. Best for interactive terminal use. + - `color`: Plain scrolling text with ANSI color codes. Good for terminals that support color but not advanced rendering. + - `table`: ASCII box-drawing characters to create structured tables and panels with color. Similar to the examples shown throughout this document. + - `plain`: Plain text with no color codes or non-ASCII characters. Suitable for piping into files, logs, or non-terminal consumers. + - `json`: Structured JSON output for programmatic consumption. No color except within verbatim text values. + - `yaml`: Structured YAML output for programmatic consumption. No color except within verbatim text values. - `--help`, `-h`: Print help for the current command. - `--version`, `-V`: Print the version and exit. - `--install-completion [SHELL]`: Install shell completion for the given shell. @@ -236,40 +242,39 @@ Configure global state locations and shell integration for every command. **Examples** 

-$ agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info
+$ agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info
 
 ╭─ System Snapshot ─────────────────╮
 │ CleverAgents 1.0.0                │
-│ Mode: local                       │
+│ Mode: local                       │
 │ Automation: review                │
-│ Default Actor: local/orchestrator │
-│ Status: ready                     │
+│ Status: ready                     │
 ╰───────────────────────────────────╯
 
 ╭─ Paths ───────────────────────────────╮
-│ Data Dir: /srv/cleveragents           │
-│ Config: /srv/cleveragents/config.toml │
-│ Logs: /srv/cleveragents/logs          │
-│ Cache: /srv/cleveragents/cache        │
-│ Database: /srv/cleveragents/agents.db │
+│ Data Dir: /srv/cleveragents           │
+│ Config: /srv/cleveragents/config.toml │
+│ Logs: /srv/cleveragents/logs          │
+│ Cache: /srv/cleveragents/cache        │
+│ Database: /srv/cleveragents/agents.db │
 ╰───────────────────────────────────────╯
 
 ╭─ Runtime ──────────╮
 │ PID: 4127          │
-│ Uptime: 00:14:32   │
-│ Python: 3.13.1     │
-│ Host: devbox.local │
-│ Platform: linux    │
+│ Uptime: 00:14:32   │
+│ Python: 3.13.1     │
+│ Host: devbox.local │
+│ Platform: linux    │
 ╰────────────────────╯
 
 ╭─ Projects & Sessions ─╮
-│ Projects: 2          │
-│ Sessions: 1 active  │
-│ Active Plans: 0     │
-│ Actors: 3           │
+│ Projects: 2           │
+│ Sessions: 1 active    │
+│ Active Plans: 0       │
+│ Actors: 3             │
 ╰───────────────────────╯
 
-✓ OK Environment loaded
+✓ OK Environment loaded
#### agents version @@ -284,30 +289,30 @@ None. **Examples** 

-$ agents version
+$ agents version
 
 ╭─ CLI Version ────╮
 │ CleverAgents CLI │
-│ Version: 1.0.0   │
-│ Channel: stable  │
-│ Python: 3.13     │
+│ Version: 1.0.0   │
+│ Channel: stable  │
+│ Python: 3.13     │
 ╰──────────────────╯
 
 ╭─ Build ────────────────╮
-│ Build Date: 2026-02-08 │
+│ Build Date: 2026-02-08 │
 │ Commit: a17c3f9        │
-│ Schema: v3             │
-│ Platform: linux-x86_64 │
+│ Schema: v3             │
+│ Platform: linux-x86_64 │
 ╰────────────────────────╯
 
 ╭─ Dependencies ─────────────────╮
-│ LangGraph: 0.2.60           │
-│ LangChain: 0.3.18          │
-│ MCP SDK: 1.4.0             │
-│ Pydantic: 2.10.4           │
+│ LangGraph: 0.2.60              │
+│ LangChain: 0.3.18              │
+│ MCP SDK: 1.4.0                 │
+│ Pydantic: 2.10.4               │
 ╰────────────────────────────────╯
 
-✓ OK Version reported
+✓ OK Version reported
#### agents info @@ -322,39 +327,38 @@ None. **Examples** 

-$ agents info
+$ agents info
 
 ╭─ Environment ───────────────────────────────────────────────╮
-│ Data Dir: /home/alex/.cleveragents                          │
-│ Config: /home/alex/.cleveragents/config.toml                │
-│ Database: sqlite:///home/alex/.cleveragents/cleveragents.db │
+│ Data Dir: /home/alex/.cleveragents                          │
+│ Config: /home/alex/.cleveragents/config.toml                │
+│ Database: sqlite:///home/alex/.cleveragents/cleveragents.db │
 │ Server Mode: disabled                                       │
-│ Platform: Linux 6.8.0 (x86_64)                              │
+│ Platform: Linux 6.8.0 (x86_64)                              │
 ╰─────────────────────────────────────────────────────────────╯
 
 ╭─ Runtime ─────────────────────────╮
-│ Default Actor: local/orchestrator │
 │ Automation: review                │
-│ Providers: 3 configured           │
+│ Providers: 3 configured           │
 │ Sessions: 2 active                │
-│ Active Plans: 1                   │
+│ Active Plans: 1                   │
 ╰───────────────────────────────────╯
 
 ╭─ Storage ─────╮
-│ Cache: 118 MB │
-│ Logs: 42 MB   │
+│ Cache: 118 MB │
+│ Logs: 42 MB   │
 │ Backups: 3    │
-│ DB Size: 8 MB │
+│ DB Size: 8 MB │
 ╰───────────────╯
 
 ╭─ Indexing ─────────────╮
-│ Text Index: ready     │
-│ Vector Index: ready   │
-│ Graph Store: disabled │
-│ Indexed Files: 1,247  │
+│ Text Index: ready      │
+│ Vector Index: ready    │
+│ Graph Store: disabled  │
+│ Indexed Files: 1,247   │
 ╰────────────────────────╯
 
-✓ OK Environment details ready
+✓ OK Environment details ready
#### agents diagnostics @@ -369,39 +373,78 @@ None. **Examples** 

-$ agents diagnostics
+$ agents diagnostics
 
 ╭─ Checks ────────────────────────────────╮
 │ Check            Status  Details        │
 │ ───────────────  ──────  ────────────── │
-│ Config file      OK      readable       │
-│ Database         OK      writable       │
+│ Config file      OK      readable       │
+│ Database         OK      writable       │
 │ OPENAI_API_KEY   WARN    missing        │
-│ Anthropic key    OK      configured     │
-│ Disk space       OK      2.1 GB free    │
-│ Text index       OK      tantivy 0.22   │
-│ Vector index     OK      faiss (CPU)    │
+│ Anthropic key    OK      configured     │
+│ Disk space       OK      2.1 GB free    │
+│ Text index       OK      tantivy 0.22   │
+│ Vector index     OK      faiss (CPU)    │
 │ Graph store      WARN    not configured │
-│ File permissions OK      data dir r/w   │
-│ Git              OK      git 2.43.0     │
-╰────────────────────────────────────────╯
+│ File permissions OK      data dir r/w   │
+│ Git              OK      git 2.43.0     │
+╰─────────────────────────────────────────╯
 
-╭─ Summary ────────╮
-│ Checks: 10 total │
-│ Warnings: 2      │
-│ Errors: 0         │
-│ Duration: 0.6s   │
-╰──────────────────╯
+╭─ Summary ─────────╮
+│ Checks: 10 total  │
+│ Warnings: 2       │
+│ Errors: 0         │
+│ Duration: 0.6s    │
+╰───────────────────╯
 
 ╭─ Recommendations ─────────────────────────────────────────────╮
 │ - Set OPENAI_API_KEY to enable OpenAI models                  │
 │ - Configure a graph store backend for structural code queries │
-│ - Run agents providers list to verify credentials             │
+│ - Verify provider credentials via config                      │
 ╰───────────────────────────────────────────────────────────────╯
 
 ⚠ WARN 2 warnings require attention
+When critical checks fail, diagnostics reports errors: + +

+$ agents diagnostics
+
+╭─ Checks ────────────────────────────────────────────╮
+│ Check            Status   Details                   │
+│ ───────────────  ───────  ────────────────────      │
+│ Config file      OK       readable                  │
+│ Database         ERROR    locked by another process │
+│ OPENAI_API_KEY   OK       configured                │
+│ Anthropic key    ERROR    invalid key format        │
+│ Disk space       WARN     312 MB free (low)         │
+│ Text index       OK       tantivy 0.22              │
+│ Vector index     ERROR    FAISS library not found   │
+│ Graph store      OK       neo4j 5.15                │
+│ File permissions OK       data dir r/w              │
+│ Git              OK       git 2.43.0                │
+╰─────────────────────────────────────────────────────╯
+
+╭─ Summary ─────────╮
+│ Checks: 10 total  │
+│ Warnings: 1       │
+│ Errors: 3         │
+│ Duration: 1.2s    │
+╰───────────────────╯
+
+╭─ Errors (must fix) ─────────────────────────────────────────────────╮
+│ 1. Database is locked by PID 12847 — stop the other process or      │
+│    delete the lock file at ~/.cleveragents/agents.db-lock           │
+│ 2. Anthropic key starts with "pk-" — expected "sk-ant-" prefix      │
+│    Run: agents config set anthropic-api-key                         │
+│ 3. FAISS library not installed — vector search will not work        │
+│    Run: pip install faiss-cpu                                       │
+╰─────────────────────────────────────────────────────────────────────╯
+
+✗ ERROR 3 errors must be resolved before CleverAgents can operate
+
+ #### agents init **Purpose** @@ -414,41 +457,53 @@ Initialize or reset the global CleverAgents environment. This wipes any existing **Examples** 

-$ agents init
+$ agents init
 
 Warning: This will remove all data in /home/alex/.cleveragents
 Continue? [y/N]: y
 
 ╭─ Environment Reset ────────────────────────────────╮
-│ Config: /home/alex/.cleveragents/config.toml       │
-│ Database: /home/alex/.cleveragents/cleveragents.db │
+│ Config: /home/alex/.cleveragents/config.toml       │
+│ Database: /home/alex/.cleveragents/cleveragents.db │
 │ Backup: /home/alex/.cleveragents.backup-2026-02-08 │
-│ Status: ready                                      │
+│ Status: ready                                      │
 ╰────────────────────────────────────────────────────╯
 
-╭─ Defaults ────────────────────────╮
-│ Default Actor: local/orchestrator │
-│ Automation: review                │
-│ Sandbox: required                 │
-│ Checkpoints: enabled              │
-│ Apply Approval: required          │
-╰───────────────────────────────────╯
+╭─ Defaults ──────────────────────────────────╮
+│ Automation Profile: supervised              │
+│ Built-in Profiles: 6 loaded                 │
+╰─────────────────────────────────────────────╯
 
 ╭─ Created ─────────────────╮
-│ Config: config.toml       │
-│ Database: cleveragents.db │
-│ Logs: logs/               │
-│ Cache: cache/             │
-│ Backups: backups/         │
+│ Config: config.toml       │
+│ Database: cleveragents.db │
+│ Logs: logs/               │
+│ Cache: cache/             │
+│ Backups: backups/         │
 ╰───────────────────────────╯
 
 ╭─ Schema ───────────────────────╮
-│ Version: v3                   │
-│ Tables: 12 created            │
-│ Migrations: up to date        │
+│ Version: v3                    │
+│ Tables: 12 created             │
+│ Migrations: up to date         │
 ╰────────────────────────────────╯
 
-✓ OK Environment initialized
+✓ OK Environment initialized
+
+ +Non-interactive initialization using `--yes` (useful in scripts and CI): + +

+$ agents init --yes
+
+╭─ Initialized ──────────────────────────────────────────╮
+│ Data Dir: /home/alex/.cleveragents (created)           │
+│ Config: /home/alex/.cleveragents/config.toml           │
+│ Database: initialized (schema v3)                      │
+│ Directories: logs, cache, sessions, contexts           │
+╰────────────────────────────────────────────────────────╯
+
+✓ OK Initialized (non-interactive)
#### agents session @@ -463,44 +518,36 @@ Create a new session for interactive work. **Arguments** -- `--name NAME`: Human-friendly session name. -- `--actor ACTOR`: Orchestrator actor to use for `session tell` (defaults to configured default). -- `--metadata KEY=VALUE`: Attach metadata to the session (repeatable). +- `--actor ACTOR`: Orchestrator actor to use for `session tell`. **Examples** 

-$ agents session create --name weekly-planning --actor local/orchestrator --metadata team=platform
+$ agents session create --actor local/orchestrator
 
-╭─ Session ──────────────────────╮
-│ Name: weekly-planning          │
-│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
-│ Actor: local/orchestrator      │
-│ Created: 2026-02-08 12:44      │
-│ Namespace: local                │
-╰────────────────────────────────╯
+╭─ Session ───────────────────────╮
+│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z  │
+│ Actor: local/orchestrator       │
+│ Created: 2026-02-08 12:44       │
+│ Namespace: local                │
+╰─────────────────────────────────╯
 
 ╭─ Settings ─────────────╮
 │ Automation: review     │
-│ Streaming: off         │
-│ Context: default       │
-│ Memory: enabled        │
-│ Max History: 50 turns │
+│ Streaming: off         │
+│ Context: default       │
+│ Memory: enabled        │
+│ Max History: 50 turns  │
 ╰────────────────────────╯
 
 ╭─ Actor Details ───────────────────╮
-│ Provider: anthropic              │
-│ Model: claude-3.5                │
-│ Temperature: 0.7                 │
-│ Context Window: 200K tokens      │
+│ Provider: anthropic               │
+│ Model: claude-3.5                 │
+│ Temperature: 0.7                  │
+│ Context Window: 200K tokens       │
 ╰───────────────────────────────────╯
 
-╭─ Metadata ──────╮
-│ - team=platform │
-│ - quarter=Q1    │
-╰─────────────────╯
-
-✓ OK Session created
+✓ OK Session created
##### agents session list @@ -510,29 +557,29 @@ List sessions available on the local machine. **Arguments** -- `--format table|json`: Output format. +None. **Examples** 

-$ agents session list --format table
+$ agents --format table session list
 
 ╭─ Sessions ───────────────────────────────────────────────────────────────────╮
-│ ID        Name             Actor               Messages  Updated          │
-│ ────────  ───────────────  ──────────────────  ────────  ──────────────── │
-│ 01HXM2A6  weekly-planning  local/orchestrator  6         2026-02-08 12:44 │
-│ 01HXM1F2  refactor-sprint  local/orchestrator  14        2026-02-07 18:11 │
+│ ID        Name             Actor               Messages  Updated             │
+│ ────────  ───────────────  ──────────────────  ────────  ────────────────    │
+│ 01HXM2A6  weekly-planning  local/orchestrator  6         2026-02-08 12:44    │
+│ 01HXM1F2  refactor-sprint  local/orchestrator  14        2026-02-07 18:11    │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ────────────────────╮
 │ Total: 2                     │
-│ Most Recent: weekly-planning │
-│ Oldest: refactor-sprint      │
-│ Total Messages: 20           │
-│ Storage: 42 KB               │
+│ Most Recent: weekly-planning │
+│ Oldest: refactor-sprint      │
+│ Total Messages: 20           │
+│ Storage: 42 KB               │
 ╰──────────────────────────────╯
 
-✓ OK 2 sessions listed
+✓ OK 2 sessions listed
##### agents session show @@ -542,22 +589,21 @@ Show details and recent messages for a session. **Arguments** -- ``: The session identifier or name. +- ``: The session identifier. **Examples** 

-$ agents session show weekly-planning
+$ agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
-╭─ Session Summary ──────────────╮
-│ Name: weekly-planning          │
-│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
-│ Actor: local/orchestrator      │
-│ Messages: 6                    │
-│ Created: 2026-02-08 12:30      │
-│ Updated: 2026-02-08 12:44      │
-│ Automation: review              │
-╰────────────────────────────────╯
+╭─ Session Summary ───────────────╮
+│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z  │
+│ Actor: local/orchestrator       │
+│ Messages: 6                     │
+│ Created: 2026-02-08 12:30       │
+│ Updated: 2026-02-08 12:44       │
+│ Automation: review              │
+╰─────────────────────────────────╯
 
 ╭─ Recent Messages ──────────────────────────────────╮
 │ user  Create an action to refresh dependency locks │
@@ -565,19 +611,19 @@ $ agents session show weekly-planning
 │ assistant  Completed 2 commands                    │
 ╰────────────────────────────────────────────────────╯
 
-╭─ Linked Plans ──────────────────────────────╮
-│ Plan ID                     Phase   State    │
-│ ──────────────────────────  ──────  ──────── │
+╭─ Linked Plans ────────────────────────────────╮
+│ Plan ID                     Phase   State     │
+│ ──────────────────────────  ──────  ────────  │
 │ 01HXM8C2ZK4Q7C2B3F2R4VYV6J  execute  complete │
-╰─────────────────────────────────────────────╯
+╰───────────────────────────────────────────────╯
 
 ╭─ Token Usage ──────────────╮
-│ Input Tokens: 3,420       │
-│ Output Tokens: 1,185     │
-│ Estimated Cost: $0.0184  │
+│ Input Tokens: 3,420        │
+│ Output Tokens: 1,185       │
+│ Estimated Cost: $0.0184    │
 ╰────────────────────────────╯
 
-✓ OK Session details loaded
+✓ OK Session details loaded
##### agents session delete @@ -587,32 +633,32 @@ Delete a session and its stored conversation history. **Arguments** -- ``: The session identifier or name. -- `--yes`: Skip the confirmation prompt. +- ``: The session identifier. +- `--yes, -y`: Skip the confirmation prompt. **Examples** 

-$ agents session delete weekly-planning
+$ agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
-Delete session weekly-planning? [y/N]: y
+Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
 
-╭─ Deletion Summary ─────────────╮
-│ Session: weekly-planning       │
-│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
-│ Messages: 6 removed            │
-│ Storage: 18 KB freed           │
-│ Plans Orphaned: 0              │
-╰────────────────────────────────╯
+╭─ Deletion Summary ──────────────────╮
+│ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
+│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z      │
+│ Messages: 6 removed                 │
+│ Storage: 18 KB freed                │
+│ Plans Orphaned: 0                   │
+╰─────────────────────────────────────╯
 
 ╭─ Cleanup ───────────╮
-│ Backups: none       │
-│ Logs: preserved     │
-│ Context: cleared    │
-│ Checkpoints: none  │
+│ Backups: none       │
+│ Logs: preserved     │
+│ Context: cleared    │
+│ Checkpoints: none   │
 ╰─────────────────────╯
 
-✓ OK Session deleted
+✓ OK Session deleted
##### agents session export @@ -622,28 +668,28 @@ Export a session as a portable JSON file. **Arguments** -- ``: The session identifier or name. -- `--output FILE`: Output file path. +- ``: The session identifier. +- `--output/-o FILE`: Output file path (optional). **Examples** 

-$ agents session export weekly-planning --output /tmp/weekly-planning.json
+$ agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
-╭─ Session Export ──────────────────╮
-│ Session: weekly-planning          │
-│ Output: /tmp/weekly-planning.json │
-│ Messages: 6                       │
-│ Size: 24 KB                       │
-│ Format: JSON                      │
-╰───────────────────────────────────╯
+╭─ Session Export ────────────────────╮
+│ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
+│ Output: /tmp/weekly-planning.json   │
+│ Messages: 6                         │
+│ Size: 24 KB                         │
+│ Format: JSON                        │
+╰─────────────────────────────────────╯
 
 ╭─ Contents ─────────────────╮
-│ Messages: 6               │
-│ Plan References: 1       │
-│ Metadata Keys: 2         │
-│ Actor Config: included   │
-│ Schema Version: v3       │
+│ Messages: 6                │
+│ Plan References: 1         │
+│ Metadata Keys: 2           │
+│ Actor Config: included     │
+│ Schema Version: v3         │
 ╰────────────────────────────╯
 
 ╭─ Integrity ──────────────────╮
@@ -651,7 +697,7 @@ $ agents session export weekly-planning --output /tmp/weekly-planning.json
 │ Encrypted: no                │
 ╰──────────────────────────────╯
 
-✓ OK Export completed
+✓ OK Export completed
##### agents session import @@ -661,34 +707,32 @@ Import a session JSON file. **Arguments** -- `--input FILE`: Input JSON file. -- `--name NAME`: Optional override for the session name. +- `--input/-i FILE`: Input JSON file. **Examples** 

-$ agents session import --input /tmp/weekly-planning.json --name weekly-planning-restored
+$ agents session import --input /tmp/weekly-planning.json
 
-╭─ Session Import ───────────────────────╮
-│ Input: /tmp/weekly-planning.json       │
-│ Name: weekly-planning-restored         │
-│ Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1 │
-│ Messages: 6                            │
-│ Schema: v3                              │
-╰────────────────────────────────────────╯
+╭─ Session Import ────────────────────────╮
+│ Input: /tmp/weekly-planning.json        │
+│ Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1  │
+│ Messages: 6                             │
+│ Schema: v3                              │
+╰─────────────────────────────────────────╯
 
 ╭─ Validation ────────────╮
-│ Checksum: verified     │
-│ Schema: compatible     │
-│ Actor Ref: resolved    │
+│ Checksum: verified      │
+│ Schema: compatible      │
+│ Actor Ref: resolved     │
 ╰─────────────────────────╯
 
 ╭─ Merge ──────────────╮
-│ Existing: none       │
-│ Strategy: create new │
+│ Existing: none       │
+│ Strategy: create new │
 ╰──────────────────────╯
 
-✓ OK Import completed
+✓ OK Import completed
##### agents session tell @@ -698,45 +742,76 @@ Send a natural-language request to the orchestrator. The orchestrator can create **Arguments** -- `""`: Instruction text. -- `--session SESSION_ID|NAME`: Session to use (defaults to the most recent session). +- ``: Instruction text (positional argument). +- `--session SESSION_ID`: Session to use (required). - `--actor ACTOR`: Override the session actor for this request. - `--stream`: Stream progress as the orchestrator works. **Examples** 

-$ agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
-  --session weekly-planning
+$ agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
+  --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
 ╭─ Plan Request ──────────────────────────────────────────╮
 │ Actor: local/orchestrator                               │
-│ Session: weekly-planning                                │
+│ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z                     │
 │ Automation: review                                      │
-│ Prompt: Create an action to refresh dependency locks... │
+│ Prompt: Create an action to refresh dependency locks... │
 ╰─────────────────────────────────────────────────────────╯
 
-╭─ Commands Executed ────────────────────────────────────────────────────────────────────────────────────────╮
-│ - agents action create local/refresh-locks --strategy-actor local/planner --execution-actor local/executor │
+╭─ Commands Executed ─────────────────────────────────────────────────────────────────────────────────────────╮
+│ - agents action create --config ./actions/refresh-locks.yaml local/refresh-locks                            │
 │ - agents resource add git-checkout local/platform-repo --path /repos/platform                               │
-│ - agents project link-resource --project local/platform --resource local/platform-repo                     │
-╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+│ - agents project link-resource local/platform local/platform-repo                                           │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Result ────────────────────────────╮
-│ Action: local/refresh-locks (draft) │
-│ Project: local/platform             │
+│ Action: local/refresh-locks (draft) │
+│ Project: local/platform             │
 │ Resource: repo                      │
 ╰─────────────────────────────────────╯
 
 ╭─ Usage ─────────────────────╮
-│ Input Tokens: 1,842       │
-│ Output Tokens: 624       │
-│ Cost: $0.0094             │
-│ Duration: 3.2s             │
-│ Tool Calls: 2             │
+│ Input Tokens: 1,842         │
+│ Output Tokens: 624          │
+│ Cost: $0.0094               │
+│ Duration: 3.2s              │
+│ Tool Calls: 3               │
 ╰─────────────────────────────╯
 
-✓ OK Orchestrator completed 2 commands
+✓ OK Orchestrator completed 3 commands
+
+ +Using `--stream` to see the response as it is generated (token by token): + +

+$ agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?"
+
+╭─ Session ──────────────────────────╮
+│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z     │
+│ Actor: local/orchestrator          │
+│ Mode: streaming                    │
+╰────────────────────────────────────╯
+
+▍ The last plan (01HXM8C2ZK) modified 6 files in the auth module:
+
+  1. `src/auth/session.py` — refactored session validation
+  2. `src/auth/tokens.py` — updated token expiry to 7200s
+  3. `src/auth/__init__.py` — updated exports
+  4. `tests/test_auth.py` — added 12 new test cases
+  5. `tests/test_session.py` — updated session fixtures
+  6. `docs/auth.md` — updated API documentation
+
+All changes passed validation (24/24 tests, lint clean).
+
+╭─ Usage ──────────────────╮
+│ Tokens: 1,240 (stream)   │
+│ Duration: 3.1s           │
+│ Tool Calls: 2            │
+╰──────────────────────────╯
+
+✓ OK Stream complete
#### agents project @@ -751,44 +826,77 @@ Create a new project record. **Arguments** -- `--name/-n NAME`: Namespaced project name. +- ``: Namespaced project name (positional argument). - `--description/-d TEXT`: Optional description. +- `--resource RESOURCE`: Resource to link to the project at creation time (repeatable). - `--invariant TEXT`: Invariant to attach to this project (repeatable). These invariants apply to all plans targeting this project. - `--invariant-actor ACTOR`: Invariant Reconciliation Actor for this project. Used to reconcile project-level invariants against global invariants for all plans targeting this project (unless the plan overrides it). **Examples** 

-$ agents project create --name local/api-service --description "Backend API"
+$ agents project create --description "Backend API" local/api-service
 
 ╭─ Project ──────────────────────╮
 │ Name: local/api-service        │
-│ ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1 │
-│ Description: Backend API       │
-│ Type: local                    │
-│ Created: 2026-02-08 12:46      │
+│ ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1 │
+│ Description: Backend API       │
+│ Type: local                    │
+│ Created: 2026-02-08 12:46      │
 ╰────────────────────────────────╯
 
 ╭─ Paths ────────────────────────────────────╮
-│ Root: /repos/api-service                   │
-│ Data Dir: /repos/api-service/.cleveragents │
+│ Root: /repos/api-service                   │
+│ Data Dir: /repos/api-service/.cleveragents │
 ╰────────────────────────────────────────────╯
 
-╭─ Defaults ────────────────────╮
-│ Sandbox: git_worktree         │
-│ Validation: unset             │
-│ Context Filters: none         │
-│ Automation: (inherits global) │
-│ Apply Approval: required      │
-╰───────────────────────────────╯
+╭─ Defaults ──────────────────────────────╮
+│ Sandbox: git_worktree                   │
+│ Validations: 0                          │
+│ Context Filters: none                   │
+│ Automation Profile: (inherits global)   │
+╰─────────────────────────────────────────╯
 
 ╭─ Resources ──────╮
-│ Total: 0        │
-│ Indexed: 0      │
-│ Sandboxable: 0 │
+│ Total: 0         │
+│ Indexed: 0       │
+│ Sandboxable: 0   │
 ╰──────────────────╯
 
-✓ OK Project created
+✓ OK Project created
+
+ +Creating a project with resources and invariants in one command: + +

+$ agents project create -d "Frontend web application" \
+  --resource local/web-repo --resource local/staging-db \
+  --invariant "All components must have unit tests" \
+  --invariant "CSS must pass stylelint checks" \
+  --invariant-actor local/invariant-resolver \
+  local/web-app
+
+╭─ Project Created ─────────────────────╮
+│ Name: local/web-app                   │
+│ ID: 01HXM4V19Z0N5R9VZ4QX4BPTZ1        │
+│ Description: Frontend web app         │
+│ Remote: no                            │
+╰───────────────────────────────────────╯
+
+╭─ Linked Resources ─────────────────────────────╮
+│ Resource           Type          Read-Only     │
+│ ───────────────────  ──────────────  ───────── │
+│ local/web-repo       git-checkout    no        │
+│ local/staging-db     local/database  no        │
+╰────────────────────────────────────────────────╯
+
+╭─ Invariants ────────────────────────────────────╮
+│ 1. All components must have unit tests          │
+│ 2. CSS must pass stylelint checks               │
+│ Reconciliation Actor: local/invariant-resolver  │
+╰─────────────────────────────────────────────────╯
+
+✓ OK Project created
##### agents project link-resource @@ -798,39 +906,37 @@ Link a registered resource to a project. The resource must already be registered **Arguments** -- `--project/-p PROJECT`: Project name. -- `--resource/-r RESOURCE`: Registered resource name. +- ``: Project name (positional argument). +- ``: Registered resource name (positional argument). - `--read-only`: Mark the resource as read-only within this project (even if the resource itself is writable). -- `--alias ALIAS`: Optional short alias for referencing this resource within the project. **Examples** 

-$ agents resource add git-checkout local/api-repo --path /repos/api --branch main
-$ agents project link-resource --project local/api-service --resource local/api-repo
+$ agents resource add git-checkout local/api-repo --path /repos/api --branch main
+$ agents project link-resource local/api-service local/api-repo
 
-╭─ Resource Linked ──────────────────────╮
-│ Project: local/api-service            │
-│ Resource: local/api-repo               │
-│ Type: git-checkout                     │
-│ Read-Only: no                           │
-│ Alias: (none)                           │
-╰────────────────────────────────────────╯
+╭─ Resource Linked ───────────────────────╮
+│ Project: local/api-service              │
+│ Resource: local/api-repo                │
+│ Type: git-checkout                      │
+│ Read-Only: no                           │
+╰─────────────────────────────────────────╯
 
 ╭─ Permissions ────────────╮
-│ Read: allowed            │
+│ Read: allowed            │
 │ Write: allowed           │
-│ Apply: requires approval │
+│ Apply: requires approval │
 ╰──────────────────────────╯
 
 ╭─ Indexing ─────────────────────╮
-│ Status: indexing...          │
-│ Files Found: 347             │
-│ Language: Python (primary)   │
-│ Estimated Time: ~20 seconds  │
+│ Status: indexing...            │
+│ Files Found: 347               │
+│ Language: Python (primary)     │
+│ Estimated Time: ~20 seconds    │
 ╰────────────────────────────────╯
 
-✓ OK Resource linked to project
+✓ OK Resource linked to project
##### agents project unlink-resource @@ -840,37 +946,37 @@ Unlink a resource from a project. The resource itself remains registered in the **Arguments** -- `--project/-p PROJECT`: Project name. -- `--resource/-r RESOURCE`: Resource name. -- `--yes`: Skip confirmation prompt. +- ``: Project name (positional argument). +- ``: Resource name (positional argument). +- `--yes, -y`: Skip confirmation prompt. **Examples** 

-$ agents project unlink-resource --project local/api-service --resource local/api-repo
+$ agents project unlink-resource local/api-service local/api-repo
 
 Unlink local/api-repo from local/api-service? [y/N]: y
 
 ╭─ Resource Unlinked ────────────────────╮
-│ Project: local/api-service            │
-│ Resource: local/api-repo               │
-│ Type: git-checkout                     │
+│ Project: local/api-service             │
+│ Resource: local/api-repo               │
+│ Type: git-checkout                     │
 ╰────────────────────────────────────────╯
 
 ╭─ Index Cleanup ──────────╮
-│ Text Index: 347 removed │
-│ Vectors: 892 removed    │
-│ Graph Triples: cleared  │
-│ Duration: 0.3s          │
+│ Text Index: 347 removed  │
+│ Vectors: 892 removed     │
+│ Graph Triples: cleared   │
+│ Duration: 0.3s           │
 ╰──────────────────────────╯
 
 ╭─ Project Summary ──────────────╮
 │ Linked Resources: 1 remaining  │
-│ Last Updated: 2026-02-09 10:30 │
-│ Active Plans: 0                │
+│ Last Updated: 2026-02-09 10:30 │
+│ Active Plans: 0                │
 ╰────────────────────────────────╯
 
-✓ OK Resource unlinked from project
+✓ OK Resource unlinked from project
##### agents project list @@ -881,30 +987,29 @@ List projects with optional filters. **Arguments** - `--namespace/-n NS`: Filter by namespace. -- `--format table|json`: Output format. **Examples** 

-$ agents project list --format table
+$ agents --format table project list
 
 ╭─ Projects ────────────────────────────────────────────────────────╮
-│ ID        Name               Resources  Remote  Active Plans │
-│ ────────  ─────────────────  ─────────  ──────  ──────────── │
-│ 01HXM4T0  local/api-service  2          No      1            │
-│ 01HXM4B9  local/docs         1          No      0            │
+│ ID        Name               Resources  Remote  Active Plans      │
+│ ────────  ─────────────────  ─────────  ──────  ────────────      │
+│ 01HXM4T0  local/api-service  2          No      1                 │
+│ 01HXM4B9  local/docs         1          No      0                 │
 ╰───────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ──────────────────╮
 │ Total: 2                   │
-│ With Resources: 2          │
-│ Remote: 0                  │
-│ Total Resources: 3         │
-│ Indexed Files: 1,247       │
+│ With Resources: 2          │
+│ Remote: 0                  │
+│ Total Resources: 3         │
+│ Indexed Files: 1,247       │
 │ Active Plans: 1            │
 ╰────────────────────────────╯
 
-✓ OK 2 projects listed
+✓ OK 2 projects listed
##### agents project show @@ -915,111 +1020,183 @@ Show full project details. **Arguments** - ``: Project name. -- `--format rich|json`: Output format. **Examples** 

-$ agents project show local/api-service
+$ agents project show local/api-service
 
 ╭─ Project Details ──────────────╮
 │ Name: local/api-service        │
-│ ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1 │
-│ Description: Backend API       │
+│ ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1 │
+│ Description: Backend API       │
 │ Resources: 2                   │
-│ Remote: no                     │
-│ Created: 2026-02-08 12:46      │
+│ Remote: no                     │
+│ Created: 2026-02-08 12:46      │
 ╰────────────────────────────────╯
 
 ╭─ Linked Resources ──────────────────────────────────────────────────────╮
-│ Resource          Type            Sandbox              Read-Only       │
+│ Resource          Type            Sandbox              Read-Only        │
 │ ────────────────  ──────────────  ────────────────────  ─────────       │
-│ local/api-repo   git-checkout    git_worktree         no              │
-│ local/staging-db local/database  transaction_rollback yes             │
+│ local/api-repo   git-checkout    git_worktree         no                │
+│ local/staging-db local/database  transaction_rollback yes               │
 ╰─────────────────────────────────────────────────────────────────────────╯
 
-╭─ Validation ────────╮
-│ Test: pytest        │
-│ Lint: ruff check .  │
-│ Type Check: pyright │
-│ Build: (none)       │
-│ Timeout: 300s       │
-╰─────────────────────╯
+╭─ Validations (3) ───────────────────────────────────────────╮
+│ val_01HXM5A  pytest --cov=src --cov-fail-under=80  required │
+│ val_01HXM5B  ruff check .                          required │
+│ val_01HXM5C  node scripts/check-bundle-size.js     info     │
+╰─────────────────────────────────────────────────────────────╯
 
 ╭─ Context ───────────────────╮
-│ Include: repo               │
+│ Include: repo               │
 │ Exclude: **/node_modules/** │
-│ Max File Size: 1 MB        │
+│ Max File Size: 1 MB         │
 ╰─────────────────────────────╯
 
 ╭─ Indexing Status ──────────╮
-│ Text Index: ready         │
-│ Vector Index: ready       │
-│ Graph Store: disabled     │
-│ Indexed Files: 347        │
-│ Last Indexed: 12:48       │
+│ Text Index: ready          │
+│ Vector Index: ready        │
+│ Graph Store: disabled      │
+│ Indexed Files: 347         │
+│ Last Indexed: 12:48        │
 ╰────────────────────────────╯
 
 ╭─ Active Plans ──────────────────────────╮
 │ Plan ID   Action               Phase    │
-│ ────────  ───────────────────  ─────── │
-│ 01HXM7A9  local/code-coverage  execute │
+│ ────────  ───────────────────  ───────  │
+│ 01HXM7A9  local/code-coverage  execute  │
 ╰─────────────────────────────────────────╯
 
-✓ OK Project loaded
+✓ OK Project loaded
-##### agents project set-validation +##### agents project validation **Purpose** -Set or update validation commands for a project or a specific resource. +Manage validations for a project. Validations are commands that run during the Execute phase to verify the correctness of changes. Each validation has an optional description, a command to execute, and a mode (required or informational). Required validations must pass for execution to proceed; informational validations are included in the summary but do not block execution. + +###### agents project validation add + +**Purpose** +Add a validation to a project. **Arguments** -- `--project/-p PROJECT`: Project name. -- `--resource NAME`: Optional resource name. -- `--test-command CMD`: Test command. -- `--lint-command CMD`: Lint command. -- `--type-check-command CMD`: Type-check command. -- `--build-command CMD`: Build command. -- `--timeout SECONDS`: Timeout per command. -- `--clear`: Clear validation config. +- ``: Project name (positional argument). +- ``: The shell command to run (positional argument, quoted string). +- `--description/-d TEXT`: Optional description of what this validation checks. +- `--required/--informational`: Whether the validation must pass (default: `--required`). Required validations block execution on failure; informational validations report results without blocking. +- `--timeout SECONDS`: Timeout for this validation command (default: 300). +- `--resource RESOURCE`: Scope this validation to a specific linked resource. **Examples** 

-$ agents project set-validation --project local/api-service --resource repo \
-  --test-command "pytest" --lint-command "ruff check ." --type-check-command "pyright"
+$ agents project validation add --description "Run unit tests with coverage" \
+  --required --timeout 600 --resource repo local/api-service "pytest --cov=src --cov-fail-under=80"
 
-╭─ Validation Commands ╮
-│ Test: pytest         │
-│ Lint: ruff check .   │
-│ Type Check: pyright  │
-│ Build: (none)        │
-│ Timeout: 300s        │
-╰──────────────────────╯
+╭─ Validation Added ──────────────────────────────────────────╮
+│ ID: val_01HXM5A                                             │
+│ Project: local/api-service                                  │
+│ Command: pytest --cov=src --cov-fail-under=80               │
+│ Description: Run unit tests with coverage                   │
+│ Mode: required                                              │
+│ Resource: repo                                              │
+│ Timeout: 600s                                               │
+╰─────────────────────────────────────────────────────────────╯
 
-╭─ Scope ─────────────────────╮
-│ Project: local/api-service  │
-│ Resource: repo              │
-│ Applies To: sandbox + apply │
-╰─────────────────────────────╯
+✓ OK Validation added
+
-╭─ Execution Order ─────────────────╮ -│ 1. Type Check → pyright │ -│ 2. Lint → ruff check . │ -│ 3. Test → pytest │ -│ On Failure: iterate up to 3 tries │ -│ Then: escalate to user │ -╰───────────────────────────────────╯ +

+$ agents project validation add --description "Lint check" \
+  --required local/api-service "ruff check ."
 
-╭─ Notes ──────────────────────╮
-│ - Commands run after Execute │
-│ - Failures block Apply phase │
-│ - Actor can auto-fix issues  │
-╰──────────────────────────────╯
+╭─ Validation Added ───────────────────╮
+│ ID: val_01HXM5B                      │
+│ Project: local/api-service           │
+│ Command: ruff check .                │
+│ Description: Lint check              │
+│ Mode: required                       │
+│ Timeout: 300s                        │
+╰──────────────────────────────────────╯
 
-✓ OK Validation updated
+✓ OK Validation added
+
+ +

+$ agents project validation add --description "Check bundle size (advisory)" \
+  --informational local/api-service "node scripts/check-bundle-size.js"
+
+╭─ Validation Added ───────────────────────────────╮
+│ ID: val_01HXM5C                                  │
+│ Project: local/api-service                       │
+│ Command: node scripts/check-bundle-size.js       │
+│ Description: Check bundle size (advisory)        │
+│ Mode: informational                              │
+│ Timeout: 300s                                    │
+╰──────────────────────────────────────────────────╯
+
+✓ OK Validation added
+
+ +###### agents project validation remove + +**Purpose** +Remove a validation from a project. + +**Arguments** + +- ``: Project name (positional argument). +- ``: Validation identifier (positional argument). +- `--yes, -y`: Skip confirmation prompt. + +**Examples** + +

+$ agents project validation remove local/api-service val_01HXM5C
+
+Remove validation val_01HXM5C from local/api-service? [y/N]: y
+
+╭─ Validation Removed ──────────────────────────────╮
+│ ID: val_01HXM5C                                   │
+│ Command: node scripts/check-bundle-size.js        │
+│ Description: Check bundle size (advisory)         │
+╰───────────────────────────────────────────────────╯
+
+✓ OK Validation removed
+
+ +###### agents project validation list + +**Purpose** +List all validations for a project. + +**Arguments** + +- ``: Project name (positional argument). + +**Examples** + +

+$ agents project validation list local/api-service
+
+╭─ Validations ─────────────────────────────────────────────────────────────────────────╮
+│ ID           Command                              Mode          Timeout  Resource     │
+│ ───────────  ───────────────────────────────────  ────────────  ───────  ────────     │
+│ val_01HXM5A  pytest --cov=src --cov-fail-under=80  required      600s     repo        │
+│ val_01HXM5B  ruff check .                          required      300s     (all)       │
+│ val_01HXM5C  node scripts/check-bundle-size.js     informational 300s     (all)       │
+╰───────────────────────────────────────────────────────────────────────────────────────╯
+
+╭─ Summary ──────────────╮
+│ Total: 3               │
+│ Required: 2            │
+│ Informational: 1       │
+╰────────────────────────╯
+
+✓ OK 3 validations listed
##### agents project delete @@ -1036,30 +1213,74 @@ Delete a project and all associated resources. **Examples** 

-$ agents project delete local/docs
+$ agents project delete local/docs
 
 Delete project local/docs? This cannot be undone. [y/N]: y
 
 ╭─ Deletion Summary ──────────────────╮
 │ Project: local/docs                 │
-│ ID: 01HXM4B9F2C1V8X2N6Q7K9L0M1      │
+│ ID: 01HXM4B9F2C1V8X2N6Q7K9L0M1      │
 │ Resources: 1 removed                │
-│ Data Dir: /repos/docs/.cleveragents │
+│ Data Dir: /repos/docs/.cleveragents │
 ╰─────────────────────────────────────╯
 
 ╭─ Index Cleanup ────────╮
-│ Text Index: cleared   │
-│ Vectors: 240 removed  │
-│ Graph Triples: none  │
-│ Storage Freed: 12 MB │
+│ Text Index: cleared    │
+│ Vectors: 240 removed   │
+│ Graph Triples: none    │
+│ Storage Freed: 12 MB   │
 ╰────────────────────────╯
 
 ╭─ Backups ────────────────────────────────────╮
-│ Snapshot: /backups/local-docs-2026-02-08.tgz │
+│ Snapshot: /backups/local-docs-2026-02-08.tgz │
 │ Retention: 7 days                            │
 ╰──────────────────────────────────────────────╯
 
-✓ OK Project deleted
+✓ OK Project deleted
+
+ +Attempting to delete a project that has active plans (without `--force`): + +

+$ agents project delete local/api-service
+
+Delete project local/api-service? [y/N]: y
+
+╭─ Delete Blocked ──────────────────────────────────────────╮
+│ Cannot delete: project has active plans                   │
+│ Active Plans: 2                                           │
+│   01HXM7A9 — execute/processing (local/code-coverage)     │
+│   01HXM4J1 — strategize/processing (local/refactor-api)   │
+╰───────────────────────────────────────────────────────────╯
+
+╭─ Resolution ──────────────────────────────────────────────────────╮
+│ - Cancel or complete active plans first, or                       │
+│ - Use --force to cancel all active plans and delete the project   │
+╰───────────────────────────────────────────────────────────────────╯
+
+✗ ERROR Delete blocked — 2 active plans
+
+ +Force-deleting a project with active plans: + +

+$ agents project delete --force --yes local/api-service
+
+╭─ Force Delete ─────────────────────────────────────────╮
+│ Cancelling: 2 active plans                             │
+│   01HXM7A9 — cancelled (was execute/processing)        │
+│   01HXM4J1 — cancelled (was strategize/processing)     │
+╰────────────────────────────────────────────────────────╯
+
+╭─ Deleted ────────────────────╮
+│ Project: local/api-service   │
+│ Resources Unlinked: 2        │
+│ Validations Removed: 3       │
+│ Plans Cancelled: 2           │
+│ Context Policies: cleared    │
+╰──────────────────────────────╯
+
+✓ OK Project force-deleted
##### agents project context @@ -1074,7 +1295,7 @@ Set the context policy for a project and (optionally) a specific view. **Arguments** -- `--project PROJECT`: Project name. +- ``: Project name (positional argument, at end of command). - `--view strategize|execute|apply|default`: Which view this policy applies to. - `--include-resource NAME`: Resource allowlist (repeatable). - `--exclude-resource NAME`: Resource denylist (repeatable). @@ -1093,15 +1314,15 @@ Set the context policy for a project and (optionally) a specific view. **Examples** 

-$ agents project context set --project local/api-service --view strategize \
-  --include-resource repo --exclude-path "**/node_modules/**" \
-  --hot-max-tokens 12000 --warm-max-decisions 50 --cold-max-decisions 200 \
-  --summarize --summary-max-tokens 800
+$ agents project context set --view strategize \
+  --include-resource repo --exclude-path "**/node_modules/**" \
+  --hot-max-tokens 12000 --warm-max-decisions 50 --cold-max-decisions 200 \
+  --summarize --summary-max-tokens 800 local/api-service
 
 ╭─ Context Policy ────────────╮
 │ Project: local/api-service  │
-│ View: strategize            │
-│ Include: repo               │
+│ View: strategize            │
+│ Include: repo               │
 │ Exclude: **/node_modules/** │
 ╰─────────────────────────────╯
 
@@ -1109,23 +1330,23 @@ $ agents project context set --project local/api-service --view strategize \
 │ Hot Tokens: 12000 (soft cap) │
 │ Warm Decisions: 50           │
 │ Cold Decisions: 200          │
-│ Query Limit: 20              │
-│ Max File Size: 1 MB          │
-│ Max Total Size: 50 MB        │
+│ Query Limit: 20              │
+│ Max File Size: 1 MB          │
+│ Max Total Size: 50 MB        │
 ╰──────────────────────────────╯
 
 ╭─ Summarization ─╮
-│ Enabled: yes    │
-│ Max Tokens: 800 │
+│ Enabled: yes    │
+│ Max Tokens: 800 │
 ╰─────────────────╯
 
 ╭─ Other Views ────────╮
-│ execute: (default) │
-│ apply: (default)   │
-│ default: (unset)   │
+│ execute: (default)   │
+│ apply: (default)     │
+│ default: (unset)     │
 ╰──────────────────────╯
 
-✓ OK Context policy updated
+✓ OK Context policy updated
###### agents project context show @@ -1135,19 +1356,18 @@ Show the active context policy for a project. **Arguments** -- `--project PROJECT`: Project name. +- ``: Project name (positional argument, at end of command). - `--view strategize|execute|apply|default`: View to display. -- `--format table|json`: Output format. **Examples** 

-$ agents project context show --project local/api-service --view strategize
+$ agents project context show --view strategize local/api-service
 
 ╭─ Context Policy ────────────╮
 │ Project: local/api-service  │
-│ View: strategize            │
-│ Include: repo               │
+│ View: strategize            │
+│ Include: repo               │
 │ Exclude: **/node_modules/** │
 ╰─────────────────────────────╯
 
@@ -1155,24 +1375,24 @@ $ agents project context show --project local/api-service --view strategize
 │ Hot Tokens: 12000 (soft cap) │
 │ Warm Decisions: 50           │
 │ Cold Decisions: 200          │
-│ Query Limit: 20              │
-│ Max File Size: 1 MB          │
-│ Max Total Size: 50 MB        │
+│ Query Limit: 20              │
+│ Max File Size: 1 MB          │
+│ Max Total Size: 50 MB        │
 ╰──────────────────────────────╯
 
 ╭─ Summarization ─╮
-│ Enabled: yes    │
-│ Max Tokens: 800 │
+│ Enabled: yes    │
+│ Max Tokens: 800 │
 ╰─────────────────╯
 
 ╭─ Current Usage ──────────────╮
-│ Hot Context: 8,420 / 12,000  │
-│ Warm Entries: 12 / 50        │
-│ Cold Entries: 47 / 200       │
-│ Indexed Resources: 1        │
+│ Hot Context: 8,420 / 12,000  │
+│ Warm Entries: 12 / 50        │
+│ Cold Entries: 47 / 200       │
+│ Indexed Resources: 1         │
 ╰──────────────────────────────╯
 
-✓ OK Context policy loaded
+✓ OK Context policy loaded
#### agents actor @@ -1183,12 +1403,12 @@ Manage actors and run actor configurations directly. ##### agents actor run **Purpose** -Run an actor configuration in isolation with simple, manual context. +Run a named actor in isolation with simple, manual context. **Arguments** -- `--config/-c FILE...`: YAML or JSON config files. -- `--prompt/-p TEXT`: Prompt to send. +- ``: The name of the actor to run (required). +- ``: Prompt text (positional argument). - `--output/-o FILE`: Output file path. - `--verbose/-v`: Increase verbosity (repeatable). - `--unsafe/-u`: Allow unsafe configs. @@ -1196,73 +1416,130 @@ Run an actor configuration in isolation with simple, manual context. - `--context-dir PATH`: Context storage location. - `--load-context FILE`: Load context from JSON. - `--temperature/-t FLOAT`: Override temperature. +- `--skill NAME`: Skill to attach (repeatable). - `--allow-rxpy-in-run-mode`: Allow RxPy routes in run mode. **Examples** 

-$ agents actor run -c ./actors/code_reader.yaml -p "Summarize the README" --context docs
+$ agents actor run --context docs local/code_reader "Summarize the README"
 
-╭─ Run Summary ─────────────────────╮
-│ Actor: local/code_reader          │
-│ Context: docs                     │
-│ Config: ./actors/code_reader.yaml │
-│ Temperature: 0.2                  │
-│ Provider: anthropic               │
-│ Model: claude-3.5                  │
-╰───────────────────────────────────╯
+╭─ Run Summary ─────────────────╮
+│ Actor: local/code_reader      │
+│ Context: docs                 │
+│ Temperature: 0.2              │
+│ Provider: anthropic           │
+│ Model: claude-3.5             │
+╰───────────────────────────────╯
 
 ╭─ Inputs ─────────────────────╮
-│ Prompt: Summarize the README │
-│ Context Files: 3             │
-│ Context Size: 12.4 KB       │
+│ Prompt: Summarize the README │
+│ Context Files: 3             │
+│ Context Size: 12.4 KB        │
 ╰──────────────────────────────╯
 
-╭─ Result Metrics ──────╮
-│ Output: stdout         │
-│ Input Tokens: 1,524   │
-│ Output Tokens: 842    │
-│ Duration: 1.8s         │
+╭─ Result Metrics ───────╮
+│ Output: stdout         │
+│ Input Tokens: 1,524    │
+│ Output Tokens: 842     │
+│ Duration: 1.8s         │
 │ Cost: $0.0021          │
-│ Tool Calls: 0          │
-╰───────────────────────╯
+│ Tool Calls: 0          │
+╰────────────────────────╯
 
-✓ OK Summary generated
+✓ OK Summary generated
+
+ +Running an actor with a custom temperature and skill attachment: + +

+$ agents actor run --temperature 0.2 --skill local/code-analysis \
+  local/reviewer "Review the auth module for security issues"
+
+╭─ Actor Run ─────────────────────────╮
+│ Actor: local/reviewer               │
+│ Type: agent                         │
+│ Temperature: 0.2                    │
+│ Skill: local/code-analysis          │
+╰─────────────────────────────────────╯
+
+╭─ Response ────────────────────────────────────────────────────────╮
+│ I identified 3 potential security concerns in the auth module:    │
+│                                                                   │
+│ 1. Token expiry not validated in `validate_session()` at          │
+│    src/auth/session.py:42. The JWT expiry claim is decoded but    │
+│    not checked against current time.                              │
+│                                                                   │
+│ 2. Missing rate limiting on the `/auth/refresh` endpoint.         │
+│    An attacker could brute-force refresh tokens.                  │
+│                                                                   │
+│ 3. Low severity: Password hashing uses bcrypt with cost=10.       │
+│    Consider cost=12 for production deployments.                   │
+╰───────────────────────────────────────────────────────────────────╯
+
+╭─ Usage ──────────────╮
+│ Tokens: 2,840        │
+│ Duration: 4.2s       │
+│ Cost: $0.009         │
+│ Tool Calls: 6        │
+╰──────────────────────╯
+
+✓ OK Actor run completed
+
+ +Saving actor output to a file: + +

+$ agents actor run --output review.md local/reviewer "Write a code review report"
+
+╭─ Actor Run ───────────────╮
+│ Actor: local/reviewer     │
+│ Output: review.md         │
+│ Tokens: 4,120             │
+│ Duration: 6.8s            │
+╰───────────────────────────╯
+
+✓ OK Output written to review.md (2.4 KB)
##### agents actor add **Purpose** -Add a new actor configuration. +Add a new actor configuration, or replace an existing one with `--update`. An actor can be defined via a YAML configuration file, entirely from CLI options, or a combination of both. When both a `--config` file and CLI options are provided, the CLI options act as overrides for values defined in the configuration file. If a local actor with the same name already exists, the command fails unless the `--update` flag is provided, which replaces the existing actor. **Arguments** -- ``: Actor name. -- `--config/-c FILE`: Actor config file. +- `[]`: Actor name (optional). When provided via a config file, the name can be omitted from the command line. +- `--config/-c FILE`: Actor config file. When provided, values from the file serve as defaults. When omitted, the actor is defined entirely from CLI options. +- `--type graph|agent`: Actor type. +- `--skill NAME`: Skill to attach to the actor (repeatable). +- `--description/-d TEXT`: Actor description. - `--unsafe`: Mark actor as unsafe. -- `--set-default`: Set as default actor. - `--option/-o key=value`: Option override (repeatable). +- `--update`: Replace an existing local actor with the same name. Without this flag, attempting to add an actor whose name is already registered will fail. + +When `--config` is provided alongside CLI options, the CLI options override the corresponding values from the config file. **Examples** 

-$ agents actor add local/reviewer --config ./actors/reviewer.yaml --set-default
+$ agents actor add --config ./actors/reviewer.yaml local/reviewer
 
 ╭─ Actor Added ────────╮
 │ Name: local/reviewer │
-│ Provider: openai     │
+│ Provider: openai     │
 │ Model: gpt-4         │
 │ Default: yes         │
-│ Unsafe: no           │
-│ Type: graph          │
+│ Unsafe: no           │
+│ Type: graph          │
 ╰──────────────────────╯
 
 ╭─ Config ─────────────────────╮
-│ Path: ./actors/reviewer.yaml │
+│ Path: ./actors/reviewer.yaml │
 │ Hash: 8b3f3d2                │
-│ Options: 4                   │
-│ Nodes: 3                     │
-│ Edges: 4                     │
+│ Options: 4                   │
+│ Nodes: 3                     │
+│ Edges: 4                     │
 ╰──────────────────────────────╯
 
 ╭─ Capabilities ───────╮
@@ -1272,53 +1549,48 @@ $ agents actor add local/reviewer --config ./actors/reviewer.yaml --set-default
 ╰──────────────────────╯
 
 ╭─ Tools ────────────────────────╮
-│ Tool          Read-Only  Safe │
-│ ────────────  ─────────  ──── │
-│ read_file     yes        yes  │
-│ search_files  yes        yes  │
-│ git_diff      yes        yes  │
+│ Tool          Read-Only  Safe  │
+│ ────────────  ─────────  ────  │
+│ read_file     yes        yes   │
+│ search_files  yes        yes   │
+│ git_diff      yes        yes   │
 ╰────────────────────────────────╯
 
-✓ OK Actor added
+✓ OK Actor added
-##### agents actor update - -**Purpose** -Update an existing actor configuration. - -**Arguments** - -- ``: Actor name. -- `--config/-c FILE`: Updated config file. -- `--unsafe`: Mark actor as unsafe. -- `--safe`: Mark actor as safe. -- `--set-default`: Set as default actor. -- `--option/-o key=value`: Option override (repeatable). - -**Examples** +Attempting to register an actor that already exists (without `--update`): 

-$ agents actor update local/reviewer --option temperature=0.2
+$ agents actor add --config ./actors/reviewer.yaml
 
-╭─ Actor Updated ───────────╮
-│ Name: local/reviewer      │
-│ Change: temperature → 0.2 │
-│ Updated: 2026-02-08 13:02 │
-│ Config Hash: 9c4e2a1     │
-╰───────────────────────────╯
+╭─ Error ─────────────────────────────────────────────────╮
+│ Actor already exists: local/reviewer                    │
+│ Registered: 2026-02-07 14:22                            │
+│ Use --update to replace the existing actor definition.  │
+╰─────────────────────────────────────────────────────────╯
 
-╭─ Effective Options ╮
-│ - temperature: 0.2 │
-│ - max_tokens: 2048 │
-│ - top_p: 1.0       │
-╰────────────────────╯
+✗ ERROR Actor already registered — use --update to replace
+
-╭─ Previous Value ───────╮ -│ temperature: 0.7 → 0.2 │ -╰────────────────────────╯ +Updating an existing actor with `--update` and adding a skill: -✓ OK Actor updated +

+$ agents actor add --config ./actors/reviewer.yaml --update --skill local/code-analysis
+
+╭─ Actor Updated ─────────────────────╮
+│ Name: local/reviewer                │
+│ Type: agent                         │
+│ Status: updated                     │
+╰─────────────────────────────────────╯
+
+╭─ Changes ────────────────────────────╮
+│ Skills: +1 (local/code-analysis)     │
+│ Model: unchanged                     │
+│ Graph: updated                       │
+╰──────────────────────────────────────╯
+
+✓ OK Actor updated
##### agents actor remove @@ -1333,27 +1605,26 @@ Remove a custom actor. **Examples** 

-$ agents actor remove local/reviewer
+$ agents actor remove local/reviewer
 
 ╭─ Actor Removed ──────╮
 │ Name: local/reviewer │
-│ Provider: openai     │
+│ Provider: openai     │
 │ Model: gpt-4         │
 ╰──────────────────────╯
 
 ╭─ Impact ───────────────────────────────────╮
-│ Default Actor: reset to local/orchestrator │
-│ Sessions: 0 affected                       │
-│ Active Plans: 0 affected                   │
-│ Actions Referencing: 0                     │
+│ Sessions: 0 affected                       │
+│ Active Plans: 0 affected                   │
+│ Actions Referencing: 0                     │
 ╰────────────────────────────────────────────╯
 
 ╭─ Cleanup ──────────────╮
-│ Config: kept on disk  │
-│ Contexts: 1 orphaned  │
+│ Config: kept on disk   │
+│ Contexts: 1 orphaned   │
 ╰────────────────────────╯
 
-✓ OK Actor removed
+✓ OK Actor removed
##### agents actor list @@ -1368,25 +1639,25 @@ None. **Examples** 

-$ agents actor list
+$ agents actor list
 
 ╭─ Actors ──────────────────────────────────────────────────────────────╮
-│ Name            Provider   Model       Default  Built-in  Unsafe │
-│ ──────────────  ─────────  ──────────  ───────  ────────  ────── │
-│ local/reviewer  openai     gpt-4       ✓                  no     │
-│ openai/gpt-4    openai     gpt-4                ✓         no     │
-│ anthropic/3.5   anthropic  claude-3.5           ✓         no     │
-╰──────────────────────────────────────────────────────────────────────╯
+│ Name            Provider   Model       Default  Built-in  Unsafe      │
+│ ──────────────  ─────────  ──────────  ───────  ────────  ──────      │
+│ local/reviewer  openai     gpt-4       ✓                  no          │
+│ openai/gpt-4    openai     gpt-4                ✓         no          │
+│ anthropic/3.5   anthropic  claude-3.5           ✓         no          │
+╰───────────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ──────────────╮
 │ Total: 3               │
-│ Built-in: 2            │
-│ Custom: 1              │
-│ Unsafe: 0              │
-│ Providers Used: 2     │
+│ Built-in: 2            │
+│ Custom: 1              │
+│ Unsafe: 0              │
+│ Providers Used: 2      │
 ╰────────────────────────╯
 
-✓ OK 3 actors listed
+✓ OK 3 actors listed
##### agents actor show @@ -1401,20 +1672,20 @@ Show details for a single actor. **Examples** 

-$ agents actor show local/reviewer
+$ agents actor show local/reviewer
 
 ╭─ Actor Details ────────────────────╮
 │ Name: local/reviewer               │
-│ Provider: openai                   │
+│ Provider: openai                   │
 │ Model: gpt-4                       │
 │ Default: yes                       │
-│ Built-in: no                       │
-│ Unsafe: no                         │
-│ Type: graph                        │
-│ Created: 2026-02-08 12:35          │
-│ Updated: 2026-02-08 12:40          │
-│ Config: ./actors/reviewer.yaml     │
-│ Config Hash: 9c4e2a1              │
+│ Built-in: no                       │
+│ Unsafe: no                         │
+│ Type: graph                        │
+│ Created: 2026-02-08 12:35          │
+│ Updated: 2026-02-08 12:40          │
+│ Config: ./actors/reviewer.yaml     │
+│ Config Hash: 9c4e2a1               │
 ╰────────────────────────────────────╯
 
 ╭─ Options ──────────╮
@@ -1424,69 +1695,34 @@ $ agents actor show local/reviewer
 ╰────────────────────╯
 
 ╭─ Graph Structure ─╮
-│ Nodes: 3          │
-│ Edges: 4          │
-│ Entry: analyze    │
-│ Exit: report      │
+│ Nodes: 3          │
+│ Edges: 4          │
+│ Entry: analyze    │
+│ Exit: report      │
 ╰───────────────────╯
 
 ╭─ Tools ────────────────────────╮
-│ Tool          Read-Only  Safe │
-│ ────────────  ─────────  ──── │
-│ read_file     yes        yes  │
-│ search_files  yes        yes  │
-│ git_diff      yes        yes  │
+│ Tool          Read-Only  Safe  │
+│ ────────────  ─────────  ────  │
+│ read_file     yes        yes   │
+│ search_files  yes        yes   │
+│ git_diff      yes        yes   │
 ╰────────────────────────────────╯
 
 ╭─ Permissions ───────╮
-│ Unsafe: no          │
-│ Filesystem: allowed │
+│ Unsafe: no          │
+│ Filesystem: allowed │
 │ Network: restricted │
 ╰─────────────────────╯
 
 ╭─ Usage ─────────────────────────────────────────╮
-│ Referenced by Actions: 1 (local/code-coverage) │
-│ Active in Sessions: 0                          │
-│ Total Runs: 14                                 │
-│ Avg Cost/Run: $0.0032                          │
+│ Referenced by Actions: 1 (local/code-coverage)  │
+│ Active in Sessions: 0                           │
+│ Total Runs: 14                                  │
+│ Avg Cost/Run: $0.0032                           │
 ╰─────────────────────────────────────────────────╯
 
-✓ OK Actor loaded
-
- -##### agents actor set-default - -**Purpose** -Set the default actor. - -**Arguments** - -- ``: Actor name. - -**Examples** - -

-$ agents actor set-default local/reviewer
-
-╭─ Default Actor ──────────────╮
-│ Current: local/reviewer      │
-│ Previous: local/orchestrator │
-│ Provider: openai             │
-│ Model: gpt-4                 │
-╰──────────────────────────────╯
-
-╭─ Impact ──────────────────────────────────╮
-│ Sessions: new sessions use local/reviewer │
-│ Existing Sessions: unchanged              │
-│ Active Plans: unchanged                   │
-╰───────────────────────────────────────────╯
-
-╭─ Saved To ──────────────────────────╮
-│ File: ~/.cleveragents/config.toml │
-│ Key: default-actor                │
-╰─────────────────────────────────────╯
-
-✓ OK Default actor updated
+✓ OK Actor loaded
##### agents actor context @@ -1494,78 +1730,6 @@ $ agents actor set-default local/reviewer **Purpose** Manage manual context for actor runs. These commands mirror the legacy context behavior but are scoped to an actor context name. -###### agents actor context add - -**Purpose** -Add files or directories to an actor context. - -**Arguments** - -- `--name NAME`: Context name. -- ``: Files or directories to add. -- `-r/--recursive`: Add directories recursively. - -**Examples** - -

-$ agents actor context add --name docs README.md docs/
-
-╭─ Context Files Added ╮
-│ Context: docs        │
-│ Added: 12 items      │
-│ Total: 12 items      │
-│ Total Size: 52 KB   │
-╰──────────────────────╯
-
-╭─ Added Items ───────────╮
-│ Name       Type  Size   │
-│ ─────────  ────  ────── │
-│ README.md  file  4.2 KB │
-│ docs/      dir   48 KB  │
-╰─────────────────────────╯
-
-╭─ Limits ────────╮
-│ Max Files: 500  │
-│ Max Size: 25 MB │
-│ Used: 0.2%      │
-╰─────────────────╯
-
-╭─ Skipped ─────────────────────────╮
-│ Binary Files: 2 (not text)       │
-│ Over Size Limit: 0              │
-╰───────────────────────────────────╯
-
-✓ OK Context updated
-
- -###### agents actor context load - -**Purpose** -Alias for `context add`. - -**Arguments** - -Same as `context add`. - -**Examples** - -

-$ agents actor context load --name docs README.md
-
-╭─ Context Files Added ╮
-│ Context: docs        │
-│ Added: 1 item        │
-│ Total: 13 items      │
-╰──────────────────────╯
-
-╭─ Recent Item ───╮
-│ Name: README.md │
-│ Size: 4.2 KB    │
-╰─────────────────╯
-
-✓ OK Context updated
-
- ###### agents actor context rm **Purpose** @@ -1573,26 +1737,26 @@ Remove files or directories from an actor context. **Arguments** -- `--name NAME`: Context name. -- ``: Paths to remove. +- ``: Context name (positional argument). Use --all/-a to target all contexts. +- `--all, -a`: Target all contexts instead of a named one. +- `--yes, -y`: Skip confirmation prompt. **Examples** 

-$ agents actor context rm --name docs README.md
+$ agents actor context rm docs
 
-╭─ Context Files Removed ╮
-│ Context: docs          │
-│ Removed: README.md     │
-│ Total: 12 items        │
-╰────────────────────────╯
+╭─ Context Removed ───────────╮
+│ Context: docs               │
+│ Status: removed             │
+╰─────────────────────────────╯
 
 ╭─ Stats ───────────────────╮
-│ Remaining Size: 48 KB     │
-│ Updated: 2026-02-08 13:06 │
+│ Remaining Size: 48 KB     │
+│ Updated: 2026-02-08 13:06 │
 ╰───────────────────────────╯
 
-✓ OK Context updated
+✓ OK Context updated
###### agents actor context list @@ -1602,30 +1766,29 @@ List files stored in an actor context. **Arguments** -- `[NAME]`: Context name (optional to list all contexts). -- `--format table|json`: Output format. +- `[REGEX]`: Optional regex filter for context names. **Examples** 

-$ agents actor context list docs
+$ agents actor context list docs
 
 ╭─ Context Files ──────────────────────────────╮
-│ Name              Type  Size     Added      │
-│ ────────────────  ────  ───────  ────────── │
+│ Name              Type  Size     Added       │
+│ ────────────────  ────  ───────  ──────────  │
 │ README.md         file  4.2 KB   02-08 12:10 │
 │ docs/overview.md  file  12.8 KB  02-08 12:10 │
 │ docs/cli.md       file  9.5 KB   02-08 12:10 │
 ╰──────────────────────────────────────────────╯
 
 ╭─ Stats ───────────────────────╮
-│ Total Files: 3               │
-│ Total Size: 26.5 KB          │
-│ Estimated Tokens: ~6,600    │
-│ Languages: Markdown          │
+│ Total Files: 3                │
+│ Total Size: 26.5 KB           │
+│ Estimated Tokens: ~6,600      │
+│ Languages: Markdown           │
 ╰───────────────────────────────╯
 
-✓ OK 3 files listed
+✓ OK 3 files listed
###### agents actor context show @@ -1635,31 +1798,22 @@ Show content of a file in an actor context. **Arguments** -- `--name NAME`: Context name. -- `[PATH]`: File path (optional for summary). +- ``: Context name (positional argument). **Examples** 

-$ agents actor context show --name docs README.md
+$ agents actor context show docs
 
-╭─ Metadata ──────────────────╮
-│ Path: README.md             │
-│ Size: 4.2 KB                │
-│ Added: 2026-02-08 12:10     │
-│ Language: Markdown           │
-│ Estimated Tokens: ~1,050   │
-│ Lines: 87                    │
-╰────────────────────────────╯
+╭─ Context Summary ───────────╮
+│ Context: docs               │
+│ Files: 3                    │
+│ Total Size: 26.5 KB         │
+│ Estimated Tokens: ~6,600    │
+│ Created: 2026-02-08 12:10   │
+╰─────────────────────────────╯
 
-╭─ Preview ─────────────────────────────────────────╮
-│ # CleverAgents                                    │
-│                                                   │
-│ CleverAgents is your command center for agents... │
-│ ...                                               │
-╰───────────────────────────────────────────────────╯
-
-✓ OK Content displayed
+✓ OK Context displayed
###### agents actor context export @@ -1669,27 +1823,27 @@ Export a context as JSON. **Arguments** -- `--name NAME`: Context name. -- `--output FILE`: Output file path. +- ``: Context name (positional argument). +- `--output/-o FILE`: Output file path (required). **Examples** 

-$ agents actor context export --name docs --output /tmp/docs-context.json
+$ agents actor context export --output /tmp/docs-context.json docs
 
 ╭─ Context Export ───────────────╮
 │ Context: docs                  │
-│ Output: /tmp/docs-context.json │
+│ Output: /tmp/docs-context.json │
 │ Items: 12                      │
-│ Size: 48 KB                    │
+│ Size: 48 KB                    │
 ╰────────────────────────────────╯
 
 ╭─ Integrity ──────────────────╮
 │ Checksum: sha256:19b2...a7d0 │
-│ Compressed: no               │
+│ Compressed: no               │
 ╰──────────────────────────────╯
 
-✓ OK Export completed
+✓ OK Export completed
###### agents actor context import @@ -1699,26 +1853,27 @@ Import a context from JSON. **Arguments** -- `--name NAME`: Context name. -- `--input FILE`: Input JSON file. +- `[NAME]`: Context name (optional, inferred from file if omitted). +- `--input/-i FILE`: Input JSON file (required). +- `--update`: Replace an existing context with the same name. **Examples** 

-$ agents actor context import --name docs --input /tmp/docs-context.json
+$ agents actor context import --input /tmp/docs-context.json docs
 
 ╭─ Context Import ──────────────╮
 │ Context: docs                 │
-│ Input: /tmp/docs-context.json │
+│ Input: /tmp/docs-context.json │
 │ Items: 12                     │
 ╰───────────────────────────────╯
 
 ╭─ Merge ───────────╮
-│ Strategy: replace │
+│ Strategy: replace │
 │ Conflicts: 0      │
 ╰───────────────────╯
 
-✓ OK Import completed
+✓ OK Import completed
###### agents actor context delete @@ -1728,28 +1883,29 @@ Delete an entire context. **Arguments** -- `--name NAME`: Context name. -- `--yes`: Skip confirmation. +- ``: Context name (positional argument). Use --all/-a to target all contexts. +- `--all, -a`: Target all contexts instead of a named one. +- `--yes, -y`: Skip confirmation. **Examples** 

-$ agents actor context delete --name docs
+$ agents actor context delete docs
 
 Delete context docs? [y/N]: y
 
 ╭─ Context Deleted ────╮
 │ Context: docs        │
 │ Items: 12 removed    │
-│ Storage: 48 KB freed │
+│ Storage: 48 KB freed │
 ╰──────────────────────╯
 
 ╭─ Cleanup ───────╮
-│ Backups: none   │
-│ Logs: preserved │
+│ Backups: none   │
+│ Logs: preserved │
 ╰─────────────────╯
 
-✓ OK Context deleted
+✓ OK Context deleted
###### agents actor context clear @@ -1759,28 +1915,29 @@ Clear all files from a context but keep the context itself. **Arguments** -- `--name NAME`: Context name. -- `--yes`: Skip confirmation. +- ``: Context name (positional argument). Use --all/-a to target all contexts. +- `--all, -a`: Target all contexts instead of a named one. +- `--yes, -y`: Skip confirmation. **Examples** 

-$ agents actor context clear --name docs
+$ agents actor context clear docs
 
 Clear context docs? [y/N]: y
 
 ╭─ Context Cleared ────╮
 │ Context: docs        │
 │ Items: 12 removed    │
-│ Storage: 48 KB freed │
+│ Storage: 48 KB freed │
 ╰──────────────────────╯
 
 ╭─ Retention ────────╮
-│ Context: preserved │
+│ Context: preserved │
 │ Files: removed     │
 ╰────────────────────╯
 
-✓ OK Context cleared
+✓ OK Context cleared
#### agents skill @@ -1791,93 +1948,98 @@ Manage skills — reusable, namespaced collections of tools. Skills are defined ##### agents skill add **Purpose** -Register a new skill from a YAML configuration file. If a skill with the same name already exists, the command fails unless the `--upgrade` flag is provided, which allows overwriting the existing registration with the new configuration. +Register a new skill. A skill can be defined via a YAML configuration file, entirely from CLI options, or a combination of both. When both a `--config` file and CLI options are provided, the CLI options act as overrides for values defined in the configuration file. If a skill with the same name already exists, the command fails unless the `--update` flag is provided, which allows overwriting the existing registration with the new configuration. **Arguments** -- ``: Namespaced skill name. -- `--config/-c FILE`: Path to the skill YAML configuration file. -- `--description/-d TEXT`: Optional description override (overrides what's in the YAML). -- `--upgrade`: Allow overwriting an existing skill registration. Without this flag, attempting to add a skill whose name is already registered will fail. +- `[]`: Namespaced skill name (optional). When provided via a config file, the name can be omitted from the command line. +- `--config/-c FILE`: Path to the skill YAML configuration file. When provided, values from the file serve as defaults. When omitted, the skill is defined entirely from CLI options. +- `--description/-d TEXT`: Optional description (overrides what's in the YAML when both are provided). +- `--tool NAME`: Named tool to include in the skill (repeatable). References tools from the Tool Registry. +- `--include-skill NAME`: Include another skill's tools (repeatable). References skills by fully-qualified name. +- `--mcp-server spec`: MCP server specification to expose tools from (repeatable). +- `--update`: Allow overwriting an existing skill registration. Without this flag, attempting to add a skill whose name is already registered will fail. + +When `--config` is provided alongside CLI options (`--tool`, `--include-skill`, `--mcp-server`, `--description`), the CLI options override or extend the corresponding values from the config file. **Examples** Registering a new skill: 

-$ agents skill add local/devops-toolkit --config ./skills/devops-toolkit.yaml
+$ agents skill add --config ./skills/devops-toolkit.yaml local/devops-toolkit
 
-╭─ Skill Registered ──────────────────────╮
-│ Name: local/devops-toolkit              │
-│ ID: 01HXMC4T08Y0N5R9VZ4QX4BPTZ1        │
-│ Description: Full-stack development tools │
-│ Config: ./skills/devops-toolkit.yaml      │
-│ Created: 2026-02-08 13:10                 │
-╰─────────────────────────────────────────╯
+╭─ Skill Registered ────────────────────────╮
+│ Name: local/devops-toolkit                │
+│ ID: 01HXMC4T08Y0N5R9VZ4QX4BPTZ1           │
+│ Description: Full-stack development tools │
+│ Config: ./skills/devops-toolkit.yaml      │
+│ Created: 2026-02-08 13:10                 │
+╰───────────────────────────────────────────╯
 
 ╭─ Includes ────────────────────╮
-│ local/file-ops (registered) │
-│ local/git-ops (registered)  │
-│ local/github (registered)   │
+│ local/file-ops (registered)   │
+│ local/git-ops (registered)    │
+│ local/github (registered)     │
 ╰───────────────────────────────╯
 
-╭─ Tool Sources ─────────────────────────────╮
-│ Source         Count  Details              │
-│ ─────────────  ─────  ───────────────────  │
-│ builtin        16     file, dir, search, git │
-│ mcp            4      github (4 tools)       │
-│ agent_skill    2      deploy, code-review    │
-│ custom         1      run_migrations         │
-│ ─────────────  ─────  ───────────────────  │
-│ Total:         23                            │
-╰────────────────────────────────────────────╯
+╭─ Tool Sources ────────────────────────────────╮
+│ Source         Count  Details                 │
+│ ─────────────  ─────  ───────────────────     │
+│ builtin        14     file, dir, git, shell   │
+│ mcp            6      github (4), linear (2)  │
+│ agent_skill    2      deploy, code-review     │
+│ custom         1      run_migrations          │
+│ ─────────────  ─────  ───────────────────     │
+│ Total:         23                             │
+╰───────────────────────────────────────────────╯
 
 ╭─ MCP Servers ────────────────────╮
-│ linear: validated (4 tools)    │
+│ linear: validated (2 tools)      │
 ╰──────────────────────────────────╯
 
-✓ OK Skill registered with 23 tools
+✓ OK Skill registered with 23 tools
-Attempting to add a skill that already exists (without `--upgrade`): +Attempting to add a skill that already exists (without `--update`): 

-$ agents skill add local/devops-toolkit --config ./skills/devops-toolkit-v2.yaml
+$ agents skill add --config ./skills/devops-toolkit-v2.yaml local/devops-toolkit
 
-✗ Error: Skill 'local/devops-toolkit' is already registered.
+✗ Error: Skill 'local/devops-toolkit' is already registered.
 
-To overwrite the existing configuration, re-run with --upgrade:
+To overwrite the existing configuration, re-run with --update:
 
-  agents skill add local/devops-toolkit --config ./skills/devops-toolkit-v2.yaml --upgrade
+  agents skill add --config ./skills/devops-toolkit-v2.yaml --update local/devops-toolkit
-Upgrading an existing skill with `--upgrade`: +Updating an existing skill with `--update`: 

-$ agents skill add local/devops-toolkit --config ./skills/devops-toolkit-v2.yaml --upgrade
+$ agents skill add --config ./skills/devops-toolkit-v2.yaml --update local/devops-toolkit
 
-╭─ Skill Upgraded ─────────────────────────╮
-│ Name: local/devops-toolkit              │
-│ Description: Full-stack development tools │
-│ Upgraded: 2026-02-08 14:22               │
-╰─────────────────────────────────────────╯
+╭─ Skill Updated ───────────────────────────╮
+│ Name: local/devops-toolkit                │
+│ Description: Full-stack development tools │
+│ Updated: 2026-02-08 14:22                 │
+╰───────────────────────────────────────────╯
 
 ╭─ Changes ─────────────────────╮
-│ Tools Added: 2              │
-│ Tools Removed: 0           │
-│ Tools Modified: 1          │
-│ Includes Changed: no      │
-│ MCP Servers Changed: no   │
+│ Tools Added: 2                │
+│ Tools Removed: 0              │
+│ Tools Modified: 1             │
+│ Includes Changed: no          │
+│ MCP Servers Changed: no       │
 ╰───────────────────────────────╯
 
-╭─ Affected Actors ────────────────────────────╮
-│ Warning: 2 actors reference this skill:     │
+╭─ Affected Actors ─────────────────────────────╮
+│ Warning: 2 actors reference this skill:       │
 │ - local/code-assistant                        │
 │ - local/full-stack-assistant                  │
 │ These actors will pick up changes on next use │
-╰──────────────────────────────────────────────╯
+╰───────────────────────────────────────────────╯
 
-✓ OK Skill upgraded (23 → 25 tools)
+✓ OK Skill updated (23 → 25 tools)
##### agents skill remove @@ -1893,25 +2055,25 @@ Remove a registered skill. **Examples** 

-$ agents skill remove local/devops-toolkit
+$ agents skill remove local/devops-toolkit
 
 Remove skill local/devops-toolkit? [y/N]: y
 
 ╭─ Skill Removed ──────────────────────╮
 │ Name: local/devops-toolkit           │
 │ Tools: 23 removed from registry      │
-│ MCP Servers: 1 connection closed     │
+│ MCP Servers: 1 connection closed     │
 ╰──────────────────────────────────────╯
 
-╭─ Dependency Check ───────────────────────────────╮
-│ Warning: 1 skill includes this skill:             │
-│ - local/full-stack-dev (will lose devops tools)   │
+╭─ Dependency Check ─────────────────────────────────╮
+│ Warning: 1 skill includes this skill:              │
+│ - local/full-stack-dev (will lose devops tools)    │
 │ Warning: 2 actors reference this skill:            │
 │ - local/code-assistant                             │
 │ - local/full-stack-assistant                       │
-╰──────────────────────────────────────────────────╯
+╰────────────────────────────────────────────────────╯
 
-✓ OK Skill removed
+✓ OK Skill removed
##### agents skill list @@ -1923,31 +2085,30 @@ List registered skills with optional filters. - `--namespace/-n NS`: Filter by namespace. - `--source SOURCE`: Filter by tool source type (mcp, agent_skill, builtin, custom). -- `--format table|json`: Output format. **Examples** 

-$ agents skill list --format table
+$ agents skill list
 
 ╭─ Skills ────────────────────────────────────────────────────────────╮
-│ Name                    Tools  Includes  Sources                │
-│ ──────────────────────  ─────  ────────  ────────────────────── │
-│ local/file-ops          9      0         builtin                │
-│ local/git-ops           4      0         builtin                │
-│ local/github            4      0         mcp                    │
-│ local/devops-toolkit    23     3         builtin, mcp, custom   │
-│ local/full-stack-dev    28     4         builtin, mcp, custom   │
+│ Name                    Tools  Includes  Sources                    │
+│ ──────────────────────  ─────  ────────  ──────────────────────     │
+│ local/file-ops          9      0         builtin                    │
+│ local/git-ops           4      0         builtin                    │
+│ local/github            4      0         mcp                        │
+│ local/devops-toolkit    23     3         builtin, mcp, custom       │
+│ local/full-stack-dev    25     4         builtin, mcp, custom       │
 ╰─────────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ─────────╮
 │ Total: 5          │
-│ Local: 5          │
-│ Server: 0         │
-│ Total Tools: 28  │
+│ Local: 5          │
+│ Server: 0         │
+│ Total Tools: 28   │
 ╰───────────────────╯
 
-✓ OK 5 skills listed
+✓ OK 5 skills listed
##### agents skill show @@ -1958,58 +2119,57 @@ Show full details for a registered skill, including its includes, tool sources, **Arguments** - ``: Skill name. -- `--format rich|json`: Output format. **Examples** 

-$ agents skill show local/devops-toolkit
+$ agents skill show local/devops-toolkit
 
-╭─ Skill Details ─────────────────────────────╮
-│ Name: local/devops-toolkit                 │
-│ ID: 01HXMC4T08Y0N5R9VZ4QX4BPTZ1           │
-│ Description: Full-stack development tools    │
-│ Config: ./skills/devops-toolkit.yaml         │
-│ Created: 2026-02-08 13:10                    │
-│ Updated: 2026-02-08 14:22                    │
-╰─────────────────────────────────────────────╯
+╭─ Skill Details ──────────────────────────────╮
+│ Name: local/devops-toolkit                   │
+│ ID: 01HXMC4T08Y0N5R9VZ4QX4BPTZ1              │
+│ Description: Full-stack development tools    │
+│ Config: ./skills/devops-toolkit.yaml         │
+│ Created: 2026-02-08 13:10                    │
+│ Updated: 2026-02-08 14:22                    │
+╰──────────────────────────────────────────────╯
 
 ╭─ Includes (3) ────────────────────────────╮
-│ local/file-ops  → 9 tools (builtin)     │
-│ local/git-ops   → 4 tools (builtin)     │
-│ local/github    → 4 tools (mcp)          │
+│ local/file-ops  → 9 tools (builtin)       │
+│ local/git-ops   → 4 tools (builtin)       │
+│ local/github    → 4 tools (mcp)           │
 ╰───────────────────────────────────────────╯
 
 ╭─ Direct Tools (6) ────────────────────────────────────────╮
-│ Name              Source       Writes  Checkpoint │
-│ ────────────────  ───────────  ──────  ────────── │
-│ create_issue      mcp:linear   yes     no         │
-│ list_issues       mcp:linear   no      —          │
-│ deploy-to-staging agent_skill  yes     composite  │
-│ code-review       agent_skill  no      —          │
-│ run_migrations    custom       yes     transaction │
-│ shell_execute     builtin      yes     snapshot   │
+│ Name              Source       Writes  Checkpoint         │
+│ ────────────────  ───────────  ──────  ──────────         │
+│ create_issue      mcp:linear   yes     no                 │
+│ list_issues       mcp:linear   no      —                  │
+│ deploy-to-staging agent_skill  yes     composite          │
+│ code-review       agent_skill  no      —                  │
+│ run_migrations    custom       yes     transaction        │
+│ shell_execute     builtin      yes     snapshot           │
 ╰───────────────────────────────────────────────────────────╯
 
 ╭─ MCP Servers (1) ───────────────────╮
-│ linear: stdio, 2 tools, connected │
+│ linear: stdio, 2 tools, connected   │
 ╰─────────────────────────────────────╯
 
 ╭─ Capability Summary ──────────╮
-│ Total Tools: 23              │
-│ Read-Only: 14               │
-│ Writes: 9                   │
-│ Checkpointable: 17         │
-│ Has Side Effects: 3        │
-│ Requires Approval: 1       │
+│ Total Tools: 23               │
+│ Read-Only: 10                 │
+│ Writes: 13                    │
+│ Checkpointable: 10            │
+│ Has Side Effects: 3           │
+│ Requires Approval: 1          │
 ╰───────────────────────────────╯
 
 ╭─ Referenced By ───────────────────╮
-│ Actors: local/code-assistant    │
-│ Skills: local/full-stack-dev    │
+│ Actors: local/code-assistant      │
+│ Skills: local/full-stack-dev      │
 ╰───────────────────────────────────╯
 
-✓ OK Skill loaded
+✓ OK Skill loaded
##### agents skill tools @@ -2020,51 +2180,50 @@ List all tools provided by a skill, including those inherited from included skil **Arguments** - ``: Skill name. -- `--format table|json`: Output format. **Examples** 

-$ agents skill tools local/devops-toolkit
+$ agents skill tools local/devops-toolkit
 
 ╭─ Tools for local/devops-toolkit ─────────────────────────────────────────────────────────╮
-│ Tool               Source       From Skill      Read-Only  Writes  Checkpoint │
-│ ─────────────────  ───────────  ──────────────  ─────────  ──────  ────────── │
-│ read_file          builtin      local/file-ops  ✓          —       —          │
-│ write_file         builtin      local/file-ops  —          ✓       file       │
-│ edit_file          builtin      local/file-ops  —          ✓       file       │
-│ delete_file        builtin      local/file-ops  —          ✓       file       │
-│ move_file          builtin      local/file-ops  —          ✓       file       │
-│ copy_file          builtin      local/file-ops  —          ✓       file       │
-│ create_directory   builtin      local/file-ops  —          ✓       file       │
-│ list_directory     builtin      local/file-ops  ✓          —       —          │
-│ delete_directory   builtin      local/file-ops  —          ✓       file       │
-│ search_files       builtin      local/file-ops  ✓          —       —          │
-│ find_definition    builtin      local/file-ops  ✓          —       —          │
-│ find_references    builtin      local/file-ops  ✓          —       —          │
-│ git_status         builtin      local/git-ops   ✓          —       —          │
-│ git_diff           builtin      local/git-ops   ✓          —       —          │
-│ git_log            builtin      local/git-ops   ✓          —       —          │
-│ git_blame          builtin      local/git-ops   ✓          —       —          │
-│ create_issue       mcp:github   local/github    —          ✓       no         │
-│ create_pr          mcp:github   local/github    —          ✓       no         │
-│ list_repos         mcp:github   local/github    ✓          —       —          │
-│ get_file_contents  mcp:github   local/github    ✓          —       —          │
-│ create_issue       mcp:linear   (direct)        —          ✓       no         │
-│ list_issues        mcp:linear   (direct)        ✓          —       —          │
-│ run_migrations     custom       (direct)        —          ✓       transaction │
+│ Tool               Source       From Skill      Read-Only  Writes  Checkpoint            │
+│ ─────────────────  ───────────  ──────────────  ─────────  ──────  ──────────            │
+│ read_file          builtin      local/file-ops  ✓          —       —                     │
+│ write_file         builtin      local/file-ops  —          ✓       file                  │
+│ edit_file          builtin      local/file-ops  —          ✓       file                  │
+│ delete_file        builtin      local/file-ops  —          ✓       file                  │
+│ move_file          builtin      local/file-ops  —          ✓       file                  │
+│ copy_file          builtin      local/file-ops  —          ✓       file                  │
+│ create_directory   builtin      local/file-ops  —          ✓       file                  │
+│ list_directory     builtin      local/file-ops  ✓          —       —                     │
+│ delete_directory   builtin      local/file-ops  —          ✓       file                  │
+│ git_status         builtin      local/git-ops   ✓          —       —                     │
+│ git_diff           builtin      local/git-ops   ✓          —       —                     │
+│ git_log            builtin      local/git-ops   ✓          —       —                     │
+│ git_blame          builtin      local/git-ops   ✓          —       —                     │
+│ create_issue       mcp:github   local/github    —          ✓       no                    │
+│ create_pr          mcp:github   local/github    —          ✓       no                    │
+│ list_repos         mcp:github   local/github    ✓          —       —                     │
+│ get_file_contents  mcp:github   local/github    ✓          —       —                     │
+│ create_issue       mcp:linear   (direct)        —          ✓       no                    │
+│ list_issues        mcp:linear   (direct)        ✓          —       —                     │
+│ run_migrations     custom       (direct)        —          ✓       transaction           │
+│ deploy-to-staging  agent_skill  (direct)        —          ✓       composite             │
+│ code-review        agent_skill  (direct)        ✓          —       —                     │
+│ shell_execute      builtin      (direct)        —          ✓       snapshot              │
 ╰──────────────────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ──────────────────╮
-│ Total: 23                 │
-│ From Includes: 17        │
-│ Direct: 6                │
-│ Read-Only: 14            │
-│ Writes: 9                │
-│ Checkpointable: 17      │
+│ Total: 23                  │
+│ From Includes: 17          │
+│ Direct: 6                  │
+│ Read-Only: 10              │
+│ Writes: 13                 │
+│ Checkpointable: 10         │
 ╰────────────────────────────╯
 
-✓ OK 23 tools listed
+✓ OK 23 tools listed
#### agents tool @@ -2075,52 +2234,86 @@ Manage tools — namespaced, independently registered, callable operations. Tool ##### agents tool add **Purpose** -Register a new tool from a YAML configuration file. If a tool with the same name already exists, the command fails unless the `--upgrade` flag is provided, which allows overwriting the existing registration with the new configuration. +Register a new tool. A tool can be defined via a YAML configuration file, entirely from CLI options, or a combination of both. When both a `--config` file and CLI options are provided, the CLI options act as overrides for values defined in the configuration file. If a tool with the same name already exists, the command fails unless the `--update` flag is provided, which allows overwriting the existing registration with the new configuration. **Arguments** -- ``: Namespaced tool name. -- `--config/-c FILE`: Path to the tool YAML configuration file. -- `--description/-d TEXT`: Optional description override (overrides what's in the YAML). -- `--upgrade`: Allow overwriting an existing tool registration. Without this flag, attempting to add a tool whose name is already registered will fail. +- ``: Namespaced tool name (appears at the end of the command). +- `--config/-c FILE`: Path to the tool YAML configuration file. When provided, values from the file serve as defaults. When omitted, the tool is defined entirely from CLI options. +- `--description/-d TEXT`: Optional description (overrides what's in the YAML when both are provided). +- `--source SOURCE`: Tool source type (custom, mcp, agent_skill, builtin). +- `--input-schema JSON`: JSON Schema for tool inputs. +- `--code TEXT`: Inline Python code for custom tools. +- `--writes/--no-writes`: Whether the tool performs write operations. +- `--checkpointable/--no-checkpointable`: Whether the tool supports checkpointing. +- `--update`: Allow overwriting an existing tool registration. Without this flag, attempting to add a tool whose name is already registered will fail. + +When `--config` is provided alongside CLI options, the CLI options override the corresponding values from the config file. **Examples** Registering a new tool: 

-$ agents tool add local/run-migrations --config ./tools/run-migrations.yaml
+$ agents tool add --config ./tools/run-migrations.yaml local/run-migrations
 
-╭─ Tool Registered ───────────────────────────╮
-│ Name: local/run-migrations                  │
-│ ID: 01HXMC5T09Z1N6S0WZ5RY5CQUZ2          │
-│ Description: Run database migrations         │
-│ Source: custom                               │
-│ Config: ./tools/run-migrations.yaml          │
-│ Created: 2026-02-09 10:15                   │
-╰─────────────────────────────────────────────╯
+╭─ Tool Registered ────────────────────────────╮
+│ Name: local/run-migrations                   │
+│ ID: 01HXMC5T09Z1N6S0WZ5RY5CQUZ2              │
+│ Description: Run database migrations         │
+│ Source: custom                               │
+│ Config: ./tools/run-migrations.yaml          │
+│ Created: 2026-02-09 10:15                    │
+╰──────────────────────────────────────────────╯
 
-╭─ Capability ──────────────────╮
-│ Writes: true                 │
-│ Write Scope: database:migrations │
-│ Checkpointable: true        │
-│ Checkpoint Scope: transaction │
-│ Side Effects: schema_mutation  │
-╰───────────────────────────────╯
+╭─ Capability ─────────────────────╮
+│ Writes: true                     │
+│ Write Scope: database:migrations │
+│ Checkpointable: true             │
+│ Checkpoint Scope: transaction    │
+│ Side Effects: schema_mutation    │
+╰──────────────────────────────────╯
 
-✓ OK Tool registered
+✓ OK Tool registered
-Attempting to add a tool that already exists (without `--upgrade`): +Attempting to add a tool that already exists (without `--update`): 

-$ agents tool add local/run-migrations --config ./tools/run-migrations-v2.yaml
+$ agents tool add --config ./tools/run-migrations-v2.yaml local/run-migrations
 
-✗ Error: Tool 'local/run-migrations' is already registered.
+✗ Error: Tool 'local/run-migrations' is already registered.
 
-To overwrite the existing configuration, re-run with --upgrade:
+To overwrite the existing configuration, re-run with --update:
 
-  agents tool add local/run-migrations --config ./tools/run-migrations-v2.yaml --upgrade
+  agents tool add --config ./tools/run-migrations-v2.yaml --update local/run-migrations
+
+ +Updating an existing tool with `--update`: + +

+$ agents tool add --config ./tools/db-migrate.yaml --update
+
+╭─ Tool Updated ─────────────────────────────╮
+│ Name: local/db-migrate                     │
+│ Source: custom (Python)                    │
+│ Status: updated (was version 1 → now 2)    │
+╰────────────────────────────────────────────╯
+
+╭─ Changes ─────────────────────────────────────╮
+│ Input Schema: modified (added batch_size)     │
+│ Capabilities: unchanged (writes, checkpoint)  │
+│ Description: updated                          │
+╰───────────────────────────────────────────────╯
+
+╭─ References ──────────────────╮
+│ Skills: 1 (local/db-tools)    │
+│ Actors: 0                     │
+│ Referencing skills will use   │
+│ the updated definition.       │
+╰───────────────────────────────╯
+
+✓ OK Tool updated
##### agents tool remove @@ -2136,13 +2329,13 @@ Remove a registered tool. **Examples** 

-$ agents tool remove local/run-migrations
+$ agents tool remove local/run-migrations
 
 Remove tool local/run-migrations? [y/N]: y
 
 ╭─ Tool Removed ────────────────────╮
-│ Name: local/run-migrations       │
-│ Source: custom                    │
+│ Name: local/run-migrations        │
+│ Source: custom                    │
 ╰───────────────────────────────────╯
 
 ╭─ References ──────────────────────────────────────╮
@@ -2152,7 +2345,7 @@ Remove tool local/run-migrations? [y/N]: y
 │ These references will break until resolved.       │
 ╰───────────────────────────────────────────────────╯
 
-✓ OK Tool removed
+✓ OK Tool removed
##### agents tool list @@ -2164,29 +2357,28 @@ List registered tools with optional filters. - `--namespace/-n NS`: Filter by namespace. - `--source SOURCE`: Filter by tool source type (mcp, agent_skill, builtin, custom). -- `--format table|json`: Output format. **Examples** 

-$ agents tool list --namespace local --format table
+$ agents tool list --namespace local
 
 ╭─ Tools ──────────────────────────────────────────────────╮
-│ Name                       Source   Read-Only  Writes │
-│ ─────────────────────────  ───────  ─────────  ────── │
-│ local/run-migrations       custom   —          ✓      │
-│ local/validate-api-compat  custom   —          ✓      │
-│ local/create-subplan       custom   —          ✓      │
-│ local/deploy-staging       agent    —          ✓      │
+│ Name                       Source   Read-Only  Writes    │
+│ ─────────────────────────  ───────  ─────────  ──────    │
+│ local/run-migrations       custom   —          ✓         │
+│ local/validate-api-compat  custom   —          ✓         │
+│ local/create-subplan       custom   —          ✓         │
+│ local/deploy-staging       agent    —          ✓         │
 ╰──────────────────────────────────────────────────────────╯
 
 ╭─ Summary ────────╮
-│ Total: 4        │
-│ Read-Only: 0    │
-│ Writes: 4       │
+│ Total: 4         │
+│ Read-Only: 0     │
+│ Writes: 4        │
 ╰──────────────────╯
 
-✓ OK 4 tools listed
+✓ OK 4 tools listed
##### agents tool show @@ -2197,44 +2389,43 @@ Show full details for a registered tool, including its schema, capability metada **Arguments** - ``: Tool name. -- `--format rich|json`: Output format. **Examples** 

-$ agents tool show local/run-migrations
+$ agents tool show local/run-migrations
 
-╭─ Tool Details ──────────────────────────────╮
-│ Name: local/run-migrations                  │
-│ Description: Run database migrations         │
-│ Source: custom                               │
-│ Config: ./tools/run-migrations.yaml          │
-│ Registered: 2026-02-09 10:15                 │
-╰─────────────────────────────────────────────╯
+╭─ Tool Details ───────────────────────────────╮
+│ Name: local/run-migrations                   │
+│ Description: Run database migrations         │
+│ Source: custom                               │
+│ Config: ./tools/run-migrations.yaml          │
+│ Registered: 2026-02-09 10:15                 │
+╰──────────────────────────────────────────────╯
 
-╭─ Input Schema ────────────────────────────────╮
-│ direction: string (required) enum: [up, down] │
-│ count: integer (default: 1)                    │
-╰───────────────────────────────────────────────╯
+╭─ Input Schema ─────────────────────────────────╮
+│ direction: string (required) enum: [up, down]  │
+│ count: integer (default: 1)                    │
+╰────────────────────────────────────────────────╯
 
 ╭─ Capability ──────────────────────╮
-│ Read-Only: false                  │
-│ Writes: true                     │
-│ Write Scope: database:migrations  │
-│ Checkpointable: true             │
-│ Checkpoint Scope: transaction    │
+│ Read-Only: false                  │
+│ Writes: true                      │
+│ Write Scope: database:migrations  │
+│ Checkpointable: true              │
+│ Checkpoint Scope: transaction     │
 │ Side Effects: schema_mutation     │
-│ Idempotent: false                │
+│ Idempotent: false                 │
 ╰───────────────────────────────────╯
 
 ╭─ Referenced By ───────────────────────╮
-│ Skills:                             │
+│ Skills:                               │
 │   - local/devops-toolkit              │
-│ Actor Graph Nodes:                  │
+│ Actor Graph Nodes:                    │
 │   - code_executor.run_db_migrate      │
 ╰───────────────────────────────────────╯
 
-✓ OK Tool details loaded
+✓ OK Tool details loaded
#### agents resource type @@ -2245,44 +2436,52 @@ Manage resource type definitions. Resource types are schema-level definitions th ##### agents resource type add **Purpose** -Register a new custom resource type from a YAML configuration file. +Register a new custom resource type. A resource type can be defined via a YAML configuration file, entirely from CLI options, or a combination of both. When both a `--config` file and CLI options are provided, the CLI options act as overrides for values defined in the configuration file. **Arguments** -- ``: Namespaced resource type name (e.g., `local/svn`, `cleverthis/s3-bucket`). -- `--config/-c FILE`: Path to the resource type YAML configuration file. -- `--upgrade`: If the type name already exists, overwrite it. Without this flag, adding a duplicate name fails with an error. +- `[]`: Namespaced resource type name (e.g., `local/svn`, `cleverthis/s3-bucket`). Optional when provided via a config file. +- `--config/-c FILE`: Path to the resource type YAML configuration file. When provided, values from the file serve as defaults. When omitted, the resource type is defined entirely from CLI options. +- `--physical/--virtual`: Whether instances of this type are physical or virtual. +- `--user-addable/--no-user-addable`: Whether instances can be created directly by users. +- `--sandbox-strategy NAME`: Sandbox strategy for instances of this type (e.g., `copy_on_write`, `transaction_rollback`, `none`). +- `--handler NAME`: Resource handler implementation. +- `--child-type spec`: Allowed child resource type specification (repeatable). +- `--cli-arg spec`: CLI argument definition for `agents resource add ` (repeatable). +- `--update`: If the type name already exists, overwrite it. Without this flag, adding a duplicate name fails with an error. + +When `--config` is provided alongside CLI options, the CLI options override the corresponding values from the config file. **Examples** 

-$ agents resource type add local/svn --config ./resource-types/svn.yaml
+$ agents resource type add --config ./resource-types/svn.yaml local/svn
 
 ╭─ Resource Type ────────────────────╮
 │ Name: local/svn                    │
-│ Physical/Virtual: physical         │
-│ User Addable: yes                  │
-│ Registered: 2026-02-09 10:15       │
+│ Physical/Virtual: physical         │
+│ User Addable: yes                  │
+│ Registered: 2026-02-09 10:15       │
 ╰────────────────────────────────────╯
 
 ╭─ CLI Arguments ────────────────────────╮
 │ Argument      Required  Description    │
-│ ────────────  ────────  ───────────── │
+│ ────────────  ────────  ─────────────  │
 │ --url         yes       Repository URL │
 │ --checkout    no        Local checkout │
 ╰────────────────────────────────────────╯
 
 ╭─ Child Types ──────────────────────────╮
-│ Auto-discover: svn-revision, svn-file │
-│ Manual link: fs-mount                 │
+│ Auto-discover: svn-revision, svn-file  │
+│ Manual link: fs-mount                  │
 ╰────────────────────────────────────────╯
 
 ╭─ Sandbox ──────────────────────╮
-│ Strategy: copy_on_write        │
-│ Handler: SVNHandler (custom)   │
+│ Strategy: copy_on_write        │
+│ Handler: SVNHandler (custom)   │
 ╰────────────────────────────────╯
 
-✓ OK Resource type registered
+✓ OK Resource type registered
 ℹ New subcommand available: agents resource add local/svn
@@ -2299,17 +2498,17 @@ Remove a custom resource type. Built-in types cannot be removed. Fails if any re **Examples** 

-$ agents resource type remove local/svn
+$ agents resource type remove local/svn
 
 Remove resource type local/svn? [y/N]: y
 
 ╭─ Resource Type Removed ───────╮
 │ Name: local/svn               │
-│ Resources Using: 0           │
-│ Subcommand Removed: yes      │
+│ Resources Using: 0            │
+│ Subcommand Removed: yes       │
 ╰───────────────────────────────╯
 
-✓ OK Resource type removed
+✓ OK Resource type removed
##### agents resource type list @@ -2319,52 +2518,52 @@ List all registered resource types (built-in and custom). **Arguments** -- `--format table|json`: Output format. +None (use the global `--format` option to control output format). **Examples** 

-$ agents resource type list
+$ agents resource type list
 
 ╭─ Resource Types ──────────────────────────────────────────────────────────────────────────────────╮
-│ Name                 Source    Phys/Virt  Addable  Auto-children                          │
-│ ───────────────────  ────────  ─────────  ───────  ────────────────────────────────────── │
-│ git-checkout        built-in  physical   yes      git, fs-directory                       │
-│ git                 built-in  physical   yes      git-remote, git-branch, git-tag,       │
-│                                                    git-commit, git-stash, git-submodule   │
-│ git-remote          built-in  physical   no       (none)                                 │
-│ git-branch          built-in  physical   no       git-commit                             │
-│ git-tag             built-in  physical   no       (none)                                 │
-│ git-commit          built-in  physical   no       git-tree                               │
-│ git-tree            built-in  physical   no       git-tree-entry                         │
-│ git-tree-entry      built-in  physical   no       (none)                                 │
-│ git-stash           built-in  physical   no       (none)                                 │
-│ git-submodule       built-in  physical   no       (none)                                 │
-│ fs-mount            built-in  physical   yes      fs-directory                            │
-│ fs-directory        built-in  physical   yes      fs-file, fs-directory,                  │
-│                                                    fs-symlink, fs-hardlink                │
-│ fs-file             built-in  physical   no       (none)                                 │
-│ fs-symlink          built-in  physical   no       (none)                                 │
-│ fs-hardlink         built-in  physical   no       (none)                                 │
-│ file                built-in  virtual    no       (none)                                 │
-│ directory           built-in  virtual    no       (none)                                 │
-│ symlink             built-in  virtual    no       (none)                                 │
-│ commit              built-in  virtual    no       (none)                                 │
-│ branch              built-in  virtual    no       (none)                                 │
-│ tag                 built-in  virtual    no       (none)                                 │
-│ remote              built-in  virtual    no       (none)                                 │
-│ submodule           built-in  virtual    no       (none)                                 │
-│ tree                built-in  virtual    no       (none)                                 │
-│ local/svn           custom    physical   yes      svn-revision, svn-file                 │
-╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+│ Name                 Source    Phys/Virt  Addable  Auto-children                                  │
+│ ───────────────────  ────────  ─────────  ───────  ──────────────────────────────────────         │
+│ git-checkout        built-in  physical   yes      git, fs-directory                               │
+│ git                 built-in  physical   yes      git-remote, git-branch, git-tag,                │
+│                                                    git-commit, git-stash, git-submodule           │
+│ git-remote          built-in  physical   no       (none)                                          │
+│ git-branch          built-in  physical   no       git-commit                                      │
+│ git-tag             built-in  physical   no       (none)                                          │
+│ git-commit          built-in  physical   no       git-tree                                        │
+│ git-tree            built-in  physical   no       git-tree-entry                                  │
+│ git-tree-entry      built-in  physical   no       (none)                                          │
+│ git-stash           built-in  physical   no       (none)                                          │
+│ git-submodule       built-in  physical   no       (none)                                          │
+│ fs-mount            built-in  physical   yes      fs-directory                                    │
+│ fs-directory        built-in  physical   yes      fs-file, fs-directory,                          │
+│                                                    fs-symlink, fs-hardlink                        │
+│ fs-file             built-in  physical   no       (none)                                          │
+│ fs-symlink          built-in  physical   no       (none)                                          │
+│ fs-hardlink         built-in  physical   no       (none)                                          │
+│ file                built-in  virtual    no       (none)                                          │
+│ directory           built-in  virtual    no       (none)                                          │
+│ symlink             built-in  virtual    no       (none)                                          │
+│ commit              built-in  virtual    no       (none)                                          │
+│ branch              built-in  virtual    no       (none)                                          │
+│ tag                 built-in  virtual    no       (none)                                          │
+│ remote              built-in  virtual    no       (none)                                          │
+│ submodule           built-in  virtual    no       (none)                                          │
+│ tree                built-in  virtual    no       (none)                                          │
+│ local/svn           custom    physical   yes      svn-revision, svn-file                          │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ─────────────────╮
-│ Built-in: 24            │
-│ Custom: 1               │
-│ User Addable: 4        │
+│ Built-in: 24              │
+│ Custom: 1                 │
+│ User Addable: 4           │
 ╰───────────────────────────╯
 
-✓ OK 25 resource types listed
+✓ OK 25 resource types listed
##### agents resource type show @@ -2375,24 +2574,23 @@ Show detailed information about a resource type, including its full schema. **Arguments** - ``: Resource type name. -- `--format rich|json`: Output format. **Examples** 

-$ agents resource type show git-checkout
+$ agents resource type show git-checkout
 
 ╭─ Resource Type ──────────────────────────────────────────────────────╮
-│ Name: git-checkout                                                  │
-│ Source: built-in                                                    │
-│ Description: A locally checked-out git repository with worktree      │
-│ Physical/Virtual: physical                                          │
-│ User Addable: yes                                                  │
+│ Name: git-checkout                                                   │
+│ Source: built-in                                                     │
+│ Description: A locally checked-out git repository with worktree      │
+│ Physical/Virtual: physical                                           │
+│ User Addable: yes                                                    │
 ╰──────────────────────────────────────────────────────────────────────╯
 
 ╭─ CLI Arguments (agents resource add git-checkout) ─────────────────╮
-│ Argument    Required  Type    Description                      │
-│ ──────────  ────────  ──────  ──────────────────────────────  │
+│ Argument    Required  Type    Description                          │
+│ ──────────  ────────  ──────  ──────────────────────────────       │
 │ --path      yes       path    Local checkout directory             │
 │ --branch    no        string  Default branch (default: main)       │
 ╰────────────────────────────────────────────────────────────────────╯
@@ -2402,19 +2600,19 @@ $ agents resource type show git-checkout
 ╰──────────────────────────────╯
 
 ╭─ Child Types ────────────────────────────────────────────────────╮
-│ Type           Auto  Manual Link  Description              │
-│ ─────────────  ────  ───────────  ──────────────────────────  │
+│ Type           Auto  Manual Link  Description                    │
+│ ─────────────  ────  ───────────  ──────────────────────────     │
 │ git            yes   no           Repo object DB and history     │
 │ fs-directory   yes   no           Worktree root directory        │
 ╰──────────────────────────────────────────────────────────────────╯
 
 ╭─ Sandbox ──────────────────────╮
-│ Strategy: git_worktree         │
-│ Checkpointable: yes           │
-│ Handler: GitCheckoutHandler   │
+│ Strategy: git_worktree         │
+│ Checkpointable: yes            │
+│ Handler: GitCheckoutHandler    │
 ╰────────────────────────────────╯
 
-✓ OK Resource type details loaded
+✓ OK Resource type details loaded
#### agents resource @@ -2430,7 +2628,7 @@ Register a new resource. The `add` command uses type-specific subcommands — ea **Arguments** - `--description/-d TEXT`: Optional resource description. -- `--upgrade`: If the resource name already exists, overwrite it. Without this flag, adding a duplicate name fails with an error. +- `--update`: If the resource name already exists, replace it. Without this flag, adding a duplicate name fails with an error. - ``: Resource type name (e.g., `git-checkout`, `git`, `fs-mount`, `fs-directory`, `local/svn`). Determines type-specific flags. - ``: Namespaced resource name (e.g., `local/api-repo`, `cleverthis/staging-db`). @@ -2439,51 +2637,51 @@ Type-specific flags depend on the resource type. See `agents resource type show **Examples** 

-$ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
+$ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
 
-╭─ Resource ────────────────────────────╮
-│ Name: local/api-repo                 │
-│ Type: git-checkout                    │
-│ Physical/Virtual: physical            │
-│ Path: /home/user/projects/api-service  │
-│ Branch: main                          │
-│ Created: 2026-02-09 10:20             │
-╰───────────────────────────────────────╯
+╭─ Resource ─────────────────────────────╮
+│ Name: local/api-repo                   │
+│ Type: git-checkout                     │
+│ Physical/Virtual: physical             │
+│ Path: /home/user/projects/api-service  │
+│ Branch: main                           │
+│ Created: 2026-02-09 10:20              │
+╰────────────────────────────────────────╯
 
 ╭─ Auto-discovered Children ───────────────────────────────────────╮
-│ Name                         Type            Status             │
-│ ───────────────────────────  ──────────────  ───────────────── │
-│ local/api-repo:repo        git             created            │
-│ local/api-repo:repo:origin git-remote      created            │
-│ local/api-repo:repo:main   git-branch      created            │
-│ local/api-repo:repo:dev    git-branch      created            │
-│ local/api-repo:worktree    fs-directory    created            │
-│   + 47 git-commit resources                                    │
-│   + 312 git-tree-entry resources                               │
-│   + 3 fs-directory + 28 fs-file                                │
+│ Name                         Type            Status              │
+│ ───────────────────────────  ──────────────  ─────────────────   │
+│ local/api-repo:repo        git             created               │
+│ local/api-repo:repo:origin git-remote      created               │
+│ local/api-repo:repo:main   git-branch      created               │
+│ local/api-repo:repo:dev    git-branch      created               │
+│ local/api-repo:worktree    fs-directory    created               │
+│   + 47 git-commit resources                                      │
+│   + 312 git-tree-entry resources                                 │
+│   + 3 fs-directory + 28 fs-file                                  │
 ╰──────────────────────────────────────────────────────────────────╯
 
 ╭─ Capabilities ─────────────────╮
-│ Readable: yes                 │
-│ Writable: yes                 │
-│ Sandboxable: yes              │
-│ Checkpointable: yes           │
-│ Sandbox Strategy: git_worktree │
+│ Readable: yes                  │
+│ Writable: yes                  │
+│ Sandboxable: yes               │
+│ Checkpointable: yes            │
+│ Sandbox Strategy: git_worktree │
 ╰────────────────────────────────╯
 
-✓ OK Resource registered (395 child resources discovered)
+✓ OK Resource registered (395 child resources discovered)
 

-$ agents resource add fs-mount local/docs --mount-path /docs/api-reference
+$ agents resource add fs-mount local/docs --mount-path /docs/api-reference
 
-╭─ Resource ──────────────────────────╮
-│ Name: local/docs                    │
-│ Type: fs-mount                      │
-│ Physical/Virtual: physical          │
-│ Mount Path: /docs/api-reference      │
-│ Created: 2026-02-09 10:22           │
-╰─────────────────────────────────────╯
+╭─ Resource ───────────────────────────╮
+│ Name: local/docs                     │
+│ Type: fs-mount                       │
+│ Physical/Virtual: physical           │
+│ Mount Path: /docs/api-reference      │
+│ Created: 2026-02-09 10:22            │
+╰──────────────────────────────────────╯
 
 ╭─ Auto-discovered Children ────────────────────╮
 │   + 1 fs-directory (root)                     │
@@ -2492,23 +2690,23 @@ $ agents resource add fs-mount local/docs --mount-path /docs/api-reference
 ╰───────────────────────────────────────────────╯
 
 ╭─ Capabilities ──────────────────────╮
-│ Readable: yes                      │
-│ Writable: yes                      │
-│ Sandboxable: yes                   │
-│ Checkpointable: yes                │
-│ Sandbox Strategy: copy_on_write     │
+│ Readable: yes                       │
+│ Writable: yes                       │
+│ Sandboxable: yes                    │
+│ Checkpointable: yes                 │
+│ Sandbox Strategy: copy_on_write     │
 ╰─────────────────────────────────────╯
 
-✓ OK Resource registered (31 child resources discovered)
+✓ OK Resource registered (31 child resources discovered)
**Duplicate name error:** 

-$ agents resource add git-checkout local/api-repo --path /repos/api-service
+$ agents resource add git-checkout local/api-repo --path /repos/api-service
 
-✗ Error: Resource local/api-repo already exists.
-  Use --upgrade to overwrite: agents resource add --upgrade git-checkout local/api-repo --path /repos/api-service
+✗ Error: Resource local/api-repo already exists.
+  Use --update to replace: agents resource add --update git-checkout local/api-repo --path /repos/api-service
##### agents resource remove @@ -2524,18 +2722,18 @@ Remove a registered resource and all its auto-discovered child resources. Fails **Examples** 

-$ agents resource remove local/api-repo
+$ agents resource remove local/api-repo
 
-Remove resource local/api-repo and 362 child resources? [y/N]: y
+Remove resource local/api-repo and 395 child resources? [y/N]: y
 
-╭─ Resource Removed ────────────────╮
-│ Name: local/api-repo              │
-│ Type: git-checkout                  │
-│ Children Removed: 395             │
-│ Projects Unlinked: 0              │
-╰───────────────────────────────────╯
+╭─ Resource Removed ──────────────────╮
+│ Name: local/api-repo                │
+│ Type: git-checkout                  │
+│ Children Removed: 395               │
+│ Projects Unlinked: 0                │
+╰─────────────────────────────────────╯
 
-✓ OK Resource removed
+✓ OK Resource removed
##### agents resource list @@ -2547,30 +2745,29 @@ List registered resources with optional filters. - `--namespace/-n NS`: Filter by namespace. - `--type/-t TYPE`: Filter by resource type. -- `--format table|json`: Output format. **Examples** 

-$ agents resource list
+$ agents resource list
 
 ╭─ Resources ──────────────────────────────────────────────────────────────────╮
-│ Name                Type        Phys/Virt  Children  Projects       │
-│ ──────────────────  ──────────  ─────────  ────────  ──────────────── │
-│ local/api-repo    git-checkout physical   395       local/api-service │
-│ local/docs        fs-mount     physical   32        local/api-service │
-│ local/staging-db  database    physical   12        local/api-service,│
-│                                                     local/staging    │
+│ Name                Type        Phys/Virt  Children  Projects                │
+│ ──────────────────  ──────────  ─────────  ────────  ────────────────        │
+│ local/api-repo    git-checkout physical   395       local/api-service        │
+│ local/docs        fs-mount     physical   32        local/api-service        │
+│ local/staging-db  database    physical   12        local/api-service,        │
+│                                                     local/staging            │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ───────────╮
-│ Total: 3            │
-│ Physical: 3        │
-│ Virtual: 0         │
-│ Total Children: 405 │
+│ Total: 3            │
+│ Physical: 3         │
+│ Virtual: 0          │
+│ Total Children: 405 │
 ╰─────────────────────╯
 
-✓ OK 3 resources listed
+✓ OK 3 resources listed
##### agents resource show @@ -2581,39 +2778,38 @@ Show detailed information about a registered resource including its type, capabi **Arguments** - ``: Resource name. -- `--format rich|json`: Output format. **Examples** 

-$ agents resource show local/api-repo
+$ agents resource show local/api-repo
 
-╭─ Resource ──────────────────────────────╮
-│ Name: local/api-repo                   │
-│ Type: git-checkout                      │
-│ Physical/Virtual: physical              │
-│ Path: /home/user/projects/api-service    │
-│ Branch: main                            │
-│ Created: 2026-02-09 10:20               │
-╰─────────────────────────────────────────╯
+╭─ Resource ───────────────────────────────╮
+│ Name: local/api-repo                     │
+│ Type: git-checkout                       │
+│ Physical/Virtual: physical               │
+│ Path: /home/user/projects/api-service    │
+│ Branch: main                             │
+│ Created: 2026-02-09 10:20                │
+╰──────────────────────────────────────────╯
 
-╭─ Capabilities ──────────────────╮
-│ Readable: yes                    │
-│ Writable: yes                    │
-│ Sandboxable: yes                 │
-│ Checkpointable: yes              │
-│ Sandbox Strategy: git_worktree    │
-╰─────────────────────────────────╯
+╭─ Capabilities ────────────────────╮
+│ Readable: yes                     │
+│ Writable: yes                     │
+│ Sandboxable: yes                  │
+│ Checkpointable: yes               │
+│ Sandbox Strategy: git_worktree    │
+╰───────────────────────────────────╯
 
 ╭─ Parents ────╮
 │ (top-level)  │
 ╰──────────────╯
 
 ╭─ Direct Children ────────────────────────────────────────────╮
-│ Name                       Type          Auto  Children  │
-│ ─────────────────────────  ────────────  ────  ────────  │
-│ local/api-repo:repo      git           yes   363       │
-│ local/api-repo:worktree  fs-directory  yes   32        │
+│ Name                       Type          Auto  Children      │
+│ ─────────────────────────  ────────────  ────  ────────      │
+│ local/api-repo:repo      git           yes   363             │
+│ local/api-repo:worktree  fs-directory  yes   32              │
 ╰──────────────────────────────────────────────────────────────╯
 
 ╭─ Linked Projects ─────────────╮
@@ -2621,15 +2817,15 @@ $ agents resource show local/api-repo
 ╰───────────────────────────────╯
 
 ╭─ Tool Bindings ────────────────────────────────╮
-│ Tool                      Slot   Access       │
-│ ────────────────────────  ─────  ───────────  │
-│ (builtin) git_status     repo   read_only     │
-│ (builtin) git_diff       repo   read_only     │
-│ (builtin) git_log        repo   read_only     │
-│ local/run-migrations     db     (not bound)   │
+│ Tool                      Slot   Access        │
+│ ────────────────────────  ─────  ───────────   │
+│ (builtin) git_status     repo   read_only      │
+│ (builtin) git_diff       repo   read_only      │
+│ (builtin) git_log        repo   read_only      │
+│ local/run-migrations     db     (not bound)    │
 ╰────────────────────────────────────────────────╯
 
-✓ OK Resource details loaded
+✓ OK Resource details loaded
##### agents resource tree @@ -2642,37 +2838,36 @@ Display the resource DAG as a tree starting from a given resource, showing paren - ``: Root resource name. - `--depth/-d N`: Maximum depth to display (default: 3). - `--type/-t TYPE`: Filter to only show children of a specific type. -- `--format tree|json`: Output format. **Examples** 

-$ agents resource tree local/api-repo --depth 2
+$ agents resource tree local/api-repo --depth 2
 
-╭─ Resource Tree: local/api-repo ──────────────────────────────╮
-│                                                               │
-│ local/api-repo (git-checkout, physical)                      │
-│ ├── local/api-repo:repo (git, physical)                       │
-│ │   ├── local/api-repo:repo:origin (git-remote)               │
-│ │   ├── local/api-repo:repo:main (git-branch)                 │
-│ │   │   ├── ...repo:main:a1b2c3d (git-commit)                 │
-│ │   │   └── ... 22 more git-commit resources                 │
-│ │   └── local/api-repo:repo:dev (git-branch)                  │
-│ │       └── ... 26 git-commit resources                       │
-│ └── local/api-repo:worktree (fs-directory, physical)          │
-│     ├── ...worktree:src/ (fs-directory)                         │
-│     ├── ...worktree:tests/ (fs-directory)                       │
-│     └── ... 28 more fs-file resources                          │
-│                                                               │
-╰───────────────────────────────────────────────────────────────╯
+╭─ Resource Tree: local/api-repo ─────────────────────────────────╮
+│                                                                 │
+│ local/api-repo (git-checkout, physical)                         │
+│ ├── local/api-repo:repo (git, physical)                         │
+│ │   ├── local/api-repo:repo:origin (git-remote)                 │
+│ │   ├── local/api-repo:repo:main (git-branch)                   │
+│ │   │   ├── ...repo:main:a1b2c3d (git-commit)                   │
+│ │   │   └── ... 22 more git-commit resources                    │
+│ │   └── local/api-repo:repo:dev (git-branch)                    │
+│ │       └── ... 26 git-commit resources                         │
+│ └── local/api-repo:worktree (fs-directory, physical)            │
+│     ├── ...worktree:src/ (fs-directory)                         │
+│     ├── ...worktree:tests/ (fs-directory)                       │
+│     └── ... 28 more fs-file resources                           │
+│                                                                 │
+╰─────────────────────────────────────────────────────────────────╯
 
 ╭─ Summary ──────────────╮
-│ Total shown: 14       │
-│ Total in subtree: 395 │
-│ Max depth: 2          │
+│ Total shown: 14        │
+│ Total in subtree: 395  │
+│ Max depth: 2           │
 ╰────────────────────────╯
 
-✓ OK Resource tree displayed
+✓ OK Resource tree displayed
##### agents resource link-child @@ -2688,16 +2883,16 @@ Manually link one resource as a child of another. The child resource must alread **Examples** 

-$ agents resource link-child --parent local/api-repo --child local/docs
+$ agents resource link-child --parent local/api-repo --child local/docs
 
 ╭─ Child Linked ────────────────────────╮
-│ Parent: local/api-repo              │
-│ Child: local/docs                    │
-│ Child Type: fs-mount                 │
-│ Status: linked                       │
+│ Parent: local/api-repo                │
+│ Child: local/docs                     │
+│ Child Type: fs-mount                  │
+│ Status: linked                        │
 ╰───────────────────────────────────────╯
 
-✓ OK Child resource linked
+✓ OK Child resource linked
##### agents resource unlink-child @@ -2714,17 +2909,17 @@ Remove a manual parent/child link between two resources. Auto-discovered links c **Examples** 

-$ agents resource unlink-child --parent local/api-repo --child local/docs
+$ agents resource unlink-child --parent local/api-repo --child local/docs
 
 Unlink local/docs from parent local/api-repo? [y/N]: y
 
 ╭─ Child Unlinked ──────────────────────╮
-│ Parent: local/api-repo              │
-│ Child: local/docs                    │
-│ Status: unlinked                     │
+│ Parent: local/api-repo                │
+│ Child: local/docs                     │
+│ Status: unlinked                      │
 ╰───────────────────────────────────────╯
 
-✓ OK Child resource unlinked
+✓ OK Child resource unlinked
#### agents plan @@ -2743,34 +2938,80 @@ List plans with optional filtering. - `--state STATE`: Filter by processing state. - `--project PROJECT`: Filter by project. - `--action ACTION`: Filter by action name. -- `--format table|json`: Output format. **Examples** 

-$ agents plan list --phase execute --format table
+$ agents --format table plan list --phase execute
 
 ╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
-│ ID        Phase    State       Action               Project            Elapsed  │
-│ ────────  ───────  ──────────  ───────────────────  ─────────────────  ───────── │
-│ 01HXM7A9  execute  processing  local/code-coverage  local/api-service  00:01:12  │
+│ ID        Phase    State       Action               Project            Elapsed       │
+│ ────────  ───────  ──────────  ───────────────────  ─────────────────  ─────────     │
+│ 01HXM7A9  execute  processing  local/code-coverage  local/api-service  00:01:12      │
 ╰──────────────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Filters ──────╮
 │ Phase: execute │
 │ State: (any)   │
-│ Project: (any) │
-│ Action: (any)  │
+│ Project: (any) │
+│ Action: (any)  │
 ╰────────────────╯
 
 ╭─ Summary ─────────╮
 │ Total: 1          │
-│ Processing: 1    │
-│ Completed: 0     │
-│ Errored: 0        │
+│ Processing: 1     │
+│ Completed: 0      │
+│ Errored: 0        │
 ╰───────────────────╯
 
-✓ OK 1 plan listed
+✓ OK 1 plan listed
+
+ +Listing all plans without filters shows plans across all phases and states: + +

+$ agents plan list
+
+╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────╮
+│ ID        Phase       State       Action               Project            Elapsed            │
+│ ────────  ──────────  ──────────  ───────────────────  ─────────────────  ─────────          │
+│ 01HXM7A9  execute     processing  local/code-coverage  local/api-service  00:01:12           │
+│ 01HXM6R3  applied     complete    local/add-auth       local/api-service  00:07:14           │
+│ 01HXM5K2  execute     errored     local/migrate-db     local/api-service  00:04:33           │
+│ 01HXM4J1  strategize  processing  local/refactor-api   local/web-app      00:00:45           │
+│ 01HXM3H8  cancelled   cancelled   local/add-logging    local/api-service  00:02:10           │
+╰──────────────────────────────────────────────────────────────────────────────────────────────╯
+
+╭─ Summary ─────────────╮
+│ Total: 5              │
+│ Processing: 2         │
+│ Completed: 1          │
+│ Errored: 1            │
+│ Cancelled: 1          │
+╰───────────────────────╯
+
+✓ OK 5 plans listed
+
+ +Filtering by project with `--project`: + +

+$ agents plan list --project local/web-app
+
+╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
+│ ID        Phase       State       Action               Project        Elapsed        │
+│ ────────  ──────────  ──────────  ───────────────────  ─────────────  ─────────      │
+│ 01HXM4J1  strategize  processing  local/refactor-api   local/web-app  00:00:45       │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+
+╭─ Filters ─────────────────╮
+│ Phase: (any)              │
+│ State: (any)              │
+│ Project: local/web-app    │
+│ Action: (any)             │
+╰───────────────────────────╯
+
+✓ OK 1 plan listed
##### agents plan use @@ -2781,19 +3022,13 @@ Apply an action to one or more projects and start the Strategize phase. **Arguments** - ``: Action name. -- `--project/-p PROJECT`: Project name (repeatable). +- ``: One or more project names (positional arguments, repeatable). - `--arg/-a name=value`: Action argument (repeatable). -- `--automation-level manual|review|auto`: Automation level. -- `--strategy-actor/-s ACTOR`: Override the action's strategy actor for this plan. -- `--execution-actor/-e ACTOR`: Override the action's execution actor for this plan. +- `--automation-profile PROFILE`: Automation profile name (e.g., `trusted`, `autonomous`, `local/careful-auto`). Overrides the profile inherited from the action, project, or global config. +- `--strategy-actor ACTOR`: Override the action's strategy actor for this plan. +- `--execution-actor ACTOR`: Override the action's execution actor for this plan. - `--estimation-actor ACTOR`: Override the action's estimation actor for this plan. - `--invariant-actor ACTOR`: Override the action's Invariant Reconciliation Actor for this plan. -- `--safety-profile NAME`: Named safety profile. -- `--require-sandbox/--no-require-sandbox`: Enforce sandboxing. -- `--require-checkpoints/--no-require-checkpoints`: Enforce checkpoints. -- `--require-apply-approval/--no-require-apply-approval`: Require human approval before apply. -- `--allow-skill-category NAME`: Allow skill categories (repeatable). -- `--deny-skill-category NAME`: Deny skill categories (repeatable). - `--invariant TEXT`: Invariant to attach to the created plan (repeatable). These are added as plan-level invariants in addition to any invariants inherited from the action, project, or global scope. All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-actor`, `--invariant-actor`) are optional overrides. When provided, they replace whatever was set when creating the action. When omitted, the action's configured actors are used. @@ -2801,41 +3036,40 @@ All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-acto **Examples** 

-$ agents plan use local/code-coverage --project local/api-service \
-  --arg target_coverage_percent=85 --automation-level review
+$ agents plan use local/code-coverage local/api-service \
+  --arg target_coverage_percent=85 --automation-profile trusted
 
 ╭─ Plan Created ──────────────────────╮
 │ Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
 │ Phase: strategize                   │
 │ Action: local/code-coverage         │
-│ Project: local/api-service          │
-│ Automation: review                  │
-│ Attempt: 1                          │
+│ Project: local/api-service          │
+│ Automation: review                  │
+│ Attempt: 1                          │
 ╰─────────────────────────────────────╯
 
-╭─ Inputs ─────────────────────╮
-│ - target_coverage_percent=85 │
-│ - safety_profile=default     │
-╰──────────────────────────────╯
+╭─ Inputs ──────────────────────╮
+│ - target_coverage_percent=85  │
+│ - automation_profile=trusted  │
+╰───────────────────────────────╯
 
 ╭─ Actors ────────────────────────╮
 │ Strategy: local/strategist      │
 │ Execution: local/executor       │
-│ Estimation: (none)              │
+│ Estimation: (none)              │
 ╰─────────────────────────────────╯
 
-╭─ Safety ──────────────────╮
-│ Sandbox: required         │
-│ Apply Approval: required  │
-│ Checkpoints: enabled      │
-│ Read-Only: no             │
-╰───────────────────────────╯
+╭─ Automation ─────────────────────────╮
+│ Profile: supervised                  │
+│ Source: project default              │
+│ Read-Only: no                        │
+╰──────────────────────────────────────╯
 
 ╭─ Context ───────────────────────╮
-│ Resources: 2 (repo, db)        │
-│ Indexed Files: 347             │
-│ View: strategize               │
-│ Hot Token Budget: 12,000       │
+│ Resources: 2 (repo, db)         │
+│ Indexed Files: 347              │
+│ View: strategize                │
+│ Hot Token Budget: 12,000        │
 ╰─────────────────────────────────╯
 
 ╭─ Next Steps ─────────────────────────────────────╮
@@ -2844,7 +3078,67 @@ $ agents plan use local/code-coverage --project local/api-service \
 │ - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
 ╰──────────────────────────────────────────────────╯
 
-✓ OK Plan created
+✓ OK Plan created
+
+ +Applying an action to multiple projects simultaneously, with plan-level invariants: + +

+$ agents plan use local/security-audit local/api-service local/web-app \
+  --invariant "Never modify production database schemas" \
+  --invariant "All changes must include test coverage" \
+  --automation-profile supervised
+
+╭─ Plan Created ──────────────────────────────────────╮
+│ Plan: 01HXM9D2ZK4Q7C2B3F2R4VYV6J                    │
+│ Action: local/security-audit                        │
+│ Phase: strategize (running)                         │
+│ Automation: supervised                              │
+╰─────────────────────────────────────────────────────╯
+
+╭─ Target Projects ───────────────────╮
+│ 1. local/api-service (3 resources)  │
+│ 2. local/web-app (2 resources)      │
+╰─────────────────────────────────────╯
+
+╭─ Plan Invariants ──────────────────────────────────────────╮
+│ Scope     Source   Invariant                               │
+│ ────────  ───────  ──────────────────────────────────      │
+│ plan      CLI      Never modify production DB schemas      │
+│ plan      CLI      All changes must include test coverage  │
+│ project   config   API responses must be backward-compat   │
+│ global    config   Follow Python PEP 8 style guide         │
+╰────────────────────────────────────────────────────────────╯
+
+✓ OK Plan created — strategize in progress
+
+ +Using an action with custom actor overrides: + +

+$ agents plan use local/code-coverage local/api-service \
+  --strategy-actor local/senior-planner \
+  --execution-actor local/fast-executor \
+  --arg target_coverage_percent=95
+
+╭─ Plan Created ──────────────────────────────────────╮
+│ Plan: 01HXM9E3ZK4Q7C2B3F2R4VYV6J                    │
+│ Action: local/code-coverage                         │
+│ Phase: strategize (running)                         │
+│ Automation: trusted                                 │
+╰─────────────────────────────────────────────────────╯
+
+╭─ Actor Overrides ────────────────────╮
+│ Strategy: local/senior-planner       │
+│ Execution: local/fast-executor       │
+│ (Estimation: action default)         │
+╰──────────────────────────────────────╯
+
+╭─ Arguments ─────────────────╮
+│ target_coverage_percent: 95 │
+╰─────────────────────────────╯
+
+✓ OK Plan created — strategize in progress
##### agents plan execute @@ -2854,35 +3148,35 @@ Start or resume execution for a plan. **Arguments** -- `[PLAN_ID]`: Plan ID (optional if the most recent plan is unambiguous). +- ``: Plan ID (required). **Examples** 

-$ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+$ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
 ╭─ Execution ──────────────────────╮
 │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
 │ Phase: execute                   │
 │ Sandbox: git_worktree            │
-│ Worker: local/executor           │
-│ Started: 12:58:10                │
-│ Attempt: 1                       │
+│ Worker: local/executor           │
+│ Started: 12:58:10                │
+│ Attempt: 1                       │
 ╰──────────────────────────────────╯
 
 ╭─ Sandbox ──────────────────────────────────╮
-│ Strategy: git_worktree                   │
-│ Path: /repos/api/.worktrees/plan-01HXM8 │
-│ Branch: cleveragents/plan-01HXM8C2      │
-│ Status: active                           │
+│ Strategy: git_worktree                     │
+│ Path: /repos/api/.worktrees/plan-01HXM8    │
+│ Branch: cleveragents/plan-01HXM8C2         │
+│ Status: active                             │
 ╰────────────────────────────────────────────╯
 
 ╭─ Strategy Summary ─────────────────────╮
-│ Decisions: 8                          │
-│ Invariants: 2                         │
-│ Planned Child Plans: 2+               │
-│ Estimated Files: ~12                  │
-│ Risk: low                              │
+│ Decisions: 8                           │
+│ Invariants: 2                          │
+│ Planned Child Plans: 2+                │
+│ Estimated Files: ~12                   │
+│ Risk: low                              │
 ╰────────────────────────────────────────╯
 
 ╭─ Progress ────────╮
@@ -2892,7 +3186,37 @@ $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 │ • Validate        │
 ╰───────────────────╯
 
-✓ OK Execution started
+✓ OK Execution started
+
+ +Resuming execution of a plan that was previously paused or errored: + +

+$ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
+
+╭─ Execution Resumed ─────────────────╮
+│ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J    │
+│ Phase: execute (resumed)            │
+│ Sandbox: git_worktree               │
+│ Worker: local/executor              │
+│ Checkpoint: cp_01HXM8C2 (loaded)    │
+│ Resumed From: step 4 of 6           │
+╰─────────────────────────────────────╯
+
+╭─ Previous Progress ──────────────────────╮
+│ ✓ Step 1: Collect context (0.8s)         │
+│ ✓ Step 2: Analyze codebase (4.2s)        │
+│ ✓ Step 3: Generate migrations (6.1s)     │
+│ ✗ Step 4: Apply migrations (errored)     │
+│ ○ Step 5: Update models (pending)        │
+│ ○ Step 6: Run validations (pending)      │
+╰──────────────────────────────────────────╯
+
+╭─ Guidance Applied ──────────────────────────────────────────────╮
+│ "Use smaller batch sizes for the migration to avoid timeouts"   │
+╰─────────────────────────────────────────────────────────────────╯
+
+✓ OK Execution resumed from checkpoint cp_01HXM8C2
##### agents plan apply @@ -2908,38 +3232,38 @@ Apply sandboxed changes to real resources. **Examples** 

-$ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+$ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
 Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
 
 ╭─ Apply Summary ─────────────────────╮
 │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
-│ Artifacts: 6 files updated          │
+│ Artifacts: 6 files updated          │
 │ Changes: 42 insertions, 9 deletions │
-│ Project: local/api-service          │
-│ Applied At: 2026-02-08 13:04        │
+│ Project: local/api-service          │
+│ Applied At: 2026-02-08 13:04        │
 ╰─────────────────────────────────────╯
 
 ╭─ Validation ───────────────────╮
-│ Tests: passed (24/24)          │
-│ Lint: passed (0 warnings)      │
-│ Type Check: passed (0 errors)  │
-│ Duration: 12.4s                │
+│ Tests: passed (24/24)          │
+│ Lint: passed (0 warnings)      │
+│ Type Check: passed (0 errors)  │
+│ Duration: 12.4s                │
 ╰────────────────────────────────╯
 
 ╭─ Sandbox Cleanup ─────────╮
-│ Worktree: removed        │
-│ Branch: merged to main   │
-│ Checkpoint: archived     │
+│ Worktree: removed         │
+│ Branch: merged to main    │
+│ Checkpoint: archived      │
 ╰───────────────────────────╯
 
 ╭─ Plan Lifecycle ────────────────────────╮
-│ Phase: applied                         │
-│ State: complete                        │
-│ Total Duration: 00:06:14              │
-│ Total Cost: $0.0847                    │
-│ Decisions Made: 8                     │
-│ Child Plans: 2 (completed)              │
+│ Phase: applied                          │
+│ State: complete                         │
+│ Total Duration: 00:06:14                │
+│ Total Cost: $0.0847                     │
+│ Decisions Made: 8                       │
+│ Child Plans: 2 (completed)              │
 ╰─────────────────────────────────────────╯
 
 ╭─ Next Steps ──────╮
@@ -2947,7 +3271,44 @@ Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
 │ - Commit changes  │
 ╰───────────────────╯
 
-✓ OK Changes applied
+✓ OK Changes applied
+
+ +When validations fail during apply, the changes are not committed and the plan enters a recoverable error state: + +

+$ agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+
+╭─ Apply Summary ─────────────────────╮
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
+│ Artifacts: 6 files updated          │
+│ Changes: 42 insertions, 9 deletions │
+│ Project: local/api-service          │
+╰─────────────────────────────────────╯
+
+╭─ Validation ───────────────────────────────────────────────╮
+│ ✗ Tests: FAILED (22/24 passed, 2 failed)                   │
+│   FAIL test_auth.py::test_session_refresh — AssertionError │
+│   FAIL test_auth.py::test_token_expiry — TimeoutError      │
+│ ✓ Lint: passed (0 warnings)                                │
+│ ✓ Type Check: passed (0 errors)                            │
+│ Duration: 14.8s                                            │
+╰────────────────────────────────────────────────────────────╯
+
+╭─ Sandbox Status ─────────────────────────────────────────────╮
+│ Worktree: preserved (changes NOT committed)                  │
+│ Checkpoint: cp_01HXM8C2 (pre-apply state available)          │
+│ The sandbox is preserved for correction or manual review.    │
+╰──────────────────────────────────────────────────────────────╯
+
+╭─ Recovery Options ──────────────────────────────────────────────────╮
+│ - agents plan prompt — provide guidance to fix test failures        │
+│ - agents plan correct — revert and re-execute with guidance         │
+│ - agents plan rollback — restore to a previous checkpoint           │
+│ - agents plan cancel — abort the plan entirely                      │
+╰─────────────────────────────────────────────────────────────────────╯
+
+✗ ERROR Apply failed — 2 required validations did not pass
##### agents plan status @@ -2957,50 +3318,155 @@ Show detailed status for a plan. **Arguments** -- `[PLAN_ID]`: Plan ID (optional if the most recent plan is unambiguous). +- ``: Plan ID (required). **Examples** 

-$ agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+$ agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
 ╭─ Plan Status ────────────────────╮
 │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
 │ Phase: execute                   │
 │ State: processing                │
-│ Action: local/code-coverage      │
-│ Project: local/api-service       │
-│ Automation: review               │
-│ Attempt: 1                       │
+│ Action: local/code-coverage      │
+│ Project: local/api-service       │
+│ Automation: review               │
+│ Attempt: 1                       │
 ╰──────────────────────────────────╯
 
 ╭─ Progress ───────╮
-│ ✓ Strategize     │
+│ ✓ Strategize     │
 │ ⏳ Execute        │
 │ • Apply (queued) │
 ╰──────────────────╯
 
 ╭─ Timing ──────────╮
-│ Started: 12:57:01 │
+│ Started: 12:57:01 │
 │ Elapsed: 00:01:12 │
-│ ETA: 00:03:45     │
+│ ETA: 00:03:45     │
 ╰───────────────────╯
 
 ╭─ Execution Detail ──────────╮
-│ Sandbox: git_worktree       │
-│ Tool Calls: 8              │
-│ Files Modified: 3          │
-│ Child Plans: 1/2 complete  │
-│ Checkpoints: 2 created     │
+│ Sandbox: git_worktree       │
+│ Tool Calls: 8               │
+│ Files Modified: 3           │
+│ Child Plans: 1/2 complete   │
+│ Checkpoints: 2 created      │
 ╰─────────────────────────────╯
 
 ╭─ Cost ───────────────╮
-│ Tokens Used: 12,420 │
-│ Cost So Far: $0.041 │
-│ Estimated: $0.085   │
+│ Tokens Used: 12,420  │
+│ Cost So Far: $0.041  │
+│ Estimated: $0.085    │
 ╰──────────────────────╯
 
-✓ OK Status refreshed
+✓ OK Status refreshed
+
+ +Status of a plan that has completed successfully: + +

+$ agents plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J
+
+╭─ Plan Status ─────────────────────╮
+│ Plan: 01HXM6R3ZK4Q7C2B3F2R4VYV6J  │
+│ Phase: applied                    │
+│ State: complete                   │
+│ Action: local/add-auth            │
+│ Project: local/api-service        │
+│ Automation: trusted               │
+│ Attempt: 1                        │
+╰───────────────────────────────────╯
+
+╭─ Progress ───────────╮
+│ ✓ Strategize         │
+│ ✓ Execute            │
+│ ✓ Apply (committed)  │
+╰──────────────────────╯
+
+╭─ Timing ─────────────────────────╮
+│ Started: 2026-02-08 12:57:01     │
+│ Finished: 2026-02-08 13:04:15    │
+│ Total Duration: 00:07:14         │
+╰──────────────────────────────────╯
+
+╭─ Result ────────────────────────────╮
+│ Decisions Made: 8                   │
+│ Child Plans: 2/2 complete           │
+│ Artifacts: 6 files updated          │
+│ Validations: 3/3 passed             │
+│ Total Cost: $0.085                  │
+╰─────────────────────────────────────╯
+
+✓ OK Plan completed successfully
+
+ +Status of a plan in the strategize phase: + +

+$ agents plan status 01HXM9F2ZK4Q7C2B3F2R4VYV6J
+
+╭─ Plan Status ────────────────────╮
+│ Plan: 01HXM9F2ZK4Q7C2B3F2R4VYV6J │
+│ Phase: strategize                │
+│ State: processing                │
+│ Action: local/refactor-auth      │
+│ Project: local/api-service       │
+│ Automation: supervised           │
+╰──────────────────────────────────╯
+
+╭─ Progress ───────────────╮
+│ ⏳ Strategize (running)   │
+│ ○ Execute (waiting)      │
+│ ○ Apply (waiting)        │
+╰──────────────────────────╯
+
+╭─ Strategy Progress ────────╮
+│ Decisions Made: 4          │
+│ Invariants Enforced: 2     │
+│ Child Plans Planned: 3     │
+│ Elapsed: 00:00:28          │
+╰────────────────────────────╯
+
+✓ OK Strategize in progress
+
+ +Status of a plan that encountered an error: + +

+$ agents plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
+
+╭─ Plan Status ────────────────────╮
+│ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
+│ Phase: execute                   │
+│ State: errored                   │
+│ Action: local/migrate-db         │
+│ Project: local/api-service       │
+│ Automation: supervised           │
+│ Attempt: 1                       │
+╰──────────────────────────────────╯
+
+╭─ Progress ───────────╮
+│ ✓ Strategize         │
+│ ✗ Execute            │
+│ ○ Apply (skipped)    │
+╰──────────────────────╯
+
+╭─ Error Detail ──────────────────────────────────────────────────╮
+│ Error: Tool invocation failed: connection refused               │
+│ Tool: local/db-migrate                                          │
+│ Step: 4 of 6                                                    │
+│ Checkpoint: cp_01HXM8C2 (sandbox state preserved)               │
+│ Recoverable: yes — use "agents plan prompt" to provide guidance │
+╰─────────────────────────────────────────────────────────────────╯
+
+╭─ Cost ───────────────╮
+│ Tokens Used: 8,340   │
+│ Cost So Far: $0.028  │
+╰──────────────────────╯
+
+✗ ERROR Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort
##### agents plan cancel @@ -3016,34 +3482,34 @@ Cancel a plan that is not terminal. **Examples** 

-$ agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
+$ agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
 
 ╭─ Plan Cancelled ─────────────────╮
 │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
 │ Phase: execute                   │
 │ Reason: blocked on credentials   │
-│ State: cancelled                 │
-│ Cancelled At: 13:02:15          │
+│ State: cancelled                 │
+│ Cancelled At: 13:02:15           │
 ╰──────────────────────────────────╯
 
 ╭─ Sandbox ────────────────╮
 │ Status: preserved        │
-│ Files Modified: 3       │
-│ Checkpoints: 2          │
+│ Files Modified: 3        │
+│ Checkpoints: 2           │
 ╰──────────────────────────╯
 
 ╭─ Child Plans ─────────────╮
-│ Completed: 1             │
-│ Cancelled: 1             │
-│ Artifacts Preserved: yes │
+│ Completed: 1              │
+│ Cancelled: 1              │
+│ Artifacts Preserved: yes  │
 ╰───────────────────────────╯
 
-╭─ Recovery ────────────────────────────────────────╮
-│ - Resolve credentials                             │
-│ - Run agents plan resume 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-╰───────────────────────────────────────────────────╯
+╭─ Recovery ───────────────────────────────────────────╮
+│ - Resolve credentials                                │
+│ - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+╰──────────────────────────────────────────────────────╯
 
-✓ OK Plan cancelled
+✓ OK Plan cancelled
##### agents plan tree @@ -3053,55 +3519,54 @@ Render the decision tree for a plan. **Arguments** -- `[PLAN_ID]`: Plan ID (optional if a current plan exists). -- `--format tree|json|flat`: Output format. +- ``: Plan ID (required). - `--show-superseded`: Include superseded decisions. **Examples** 

-$ agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+$ agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
 ╭─ Decision Tree ──────────────────────────────────────────────────────────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J                                                       │
-│ ├─ [prompt_definition] "Increase test coverage to 85%"                                │
-│ ├─ [invariant_enforced] "Prioritize financial transaction and user mgmt code"       │
-│ ├─ [invariant_enforced] "All API calls over TCP must be mocked"                     │
-│ ├─ [strategy_choice] "Prioritize auth and payments" (confidence: 0.82)           │
-│ ├─ [subplan_parallel_spawn] "Implement auth and payment modules, in parallel"        │
-│ │  ├─ [subplan_spawn] "Write auth tests" → Plan: 01HXM9F1A                          │
-│ │  └─ [subplan_spawn] "Write payment tests" → Plan: 01HXM9F2B                       │
-│ └─ [subplan_parallel_spawn] "Write tests for remaining modules"                      │
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J                                                         │
+│ ├─ [prompt_definition] "Increase test coverage to 85%"                                   │
+│ ├─ [invariant_enforced] "Prioritize financial transaction and user mgmt code"            │
+│ ├─ [invariant_enforced] "All API calls over TCP must be mocked"                          │
+│ ├─ [strategy_choice] "Prioritize auth and payments" (confidence: 0.82)                   │
+│ ├─ [subplan_parallel_spawn] "Implement auth and payment modules, in parallel"            │
+│ │  ├─ [subplan_spawn] "Write auth tests" → Plan: 01HXM9F1A                               │
+│ │  └─ [subplan_spawn] "Write payment tests" → Plan: 01HXM9F2B                            │
+│ └─ [subplan_parallel_spawn] "Write tests for remaining modules"                          │
 │    └─ ...                                                                                │
 ╰──────────────────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Tree Summary ─────────────╮
-│ Nodes: 9                  │
-│ Depth: 3                  │
-│ Child Plans: 2+           │
-│ Invariants: 2            │
-│ Superseded: 0 (hidden)     │
+│ Nodes: 9                   │
+│ Depth: 3                   │
+│ Child Plans: 2+            │
+│ Invariants: 2              │
+│ Superseded: 0 (hidden)     │
 ╰────────────────────────────╯
 
 ╭─ Child Plans ──────────────────────────────────────╮
-│ ID          Name           Phase    State     │
-│ ──────────  ─────────────  ───────  ───────── │
-│ 01HXM9F1A   auth-tests     execute  processing │
-│ 01HXM9F2B   payment-tests  execute  queued     │
+│ ID          Name           Phase    State          │
+│ ──────────  ─────────────  ───────  ─────────      │
+│ 01HXM9F1A   auth-tests     execute  processing     │
+│ 01HXM9F2B   payment-tests  execute  queued         │
 ╰────────────────────────────────────────────────────╯
 
 ╭─ Decision IDs (for correction) ──────────────────╮
-│ Root: 01HXM9A0B1Q2W3R5G8Z0P4Q1X8             │
-│ Invariant 1: 01HXM9A0C1R3X4S6G9Z1P5Q2Y9    │
-│ Invariant 2: 01HXM9A0D2S4Y5T7H0Z2P6Q3Z0    │
-│ Strategy: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9         │
-│ Parallel 1: 01HXM9A1D3R8X5S7H1Z2P5Q2Y0     │
-│ Spawn Auth: 01HXM9A2D3Q8W4R6H9Z1P5Q2X0      │
-│ Spawn Payment: 01HXM9A3E4Q9W5R7I0Z2P6Q3X1   │
-│ Parallel 2: 01HXM9A4F5Q0W6R8J1Z3P7Q4X2     │
+│ Root: 01HXM9A0B1Q2W3R5G8Z0P4Q1X8                 │
+│ Invariant 1: 01HXM9A0C1R3X4S6G9Z1P5Q2Y9          │
+│ Invariant 2: 01HXM9A0D2S4Y5T7H0Z2P6Q3Z0          │
+│ Strategy: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9             │
+│ Parallel 1: 01HXM9A1D3R8X5S7H1Z2P5Q2Y0           │
+│ Spawn Auth: 01HXM9A2D3Q8W4R6H9Z1P5Q2X0           │
+│ Spawn Payment: 01HXM9A3E4Q9W5R7I0Z2P6Q3X1        │
+│ Parallel 2: 01HXM9A4F5Q0W6R8J1Z3P7Q4X2           │
 ╰──────────────────────────────────────────────────╯
 
-✓ OK Decision tree rendered
+✓ OK Decision tree rendered
##### agents plan explain @@ -3118,30 +3583,30 @@ Show a detailed explanation for a decision. **Examples** 

-$ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
+$ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --show-context
 
 ╭─ Decision ─────────────────────────────────────╮
 │ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9                 │
-│ Type: strategy_choice                          │
+│ Type: strategy_choice                          │
 │ Question: Which modules should be prioritized? │
-│ Chosen: Auth and payments                      │
+│ Chosen: Auth and payments                      │
 │ Confidence: 0.82                               │
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J              │
-│ Sequence: 2 of 5                               │
-│ Created: 2026-02-08 12:58                     │
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J               │
+│ Sequence: 2 of 5                               │
+│ Created: 2026-02-08 12:58                      │
 ╰────────────────────────────────────────────────╯
 
 ╭─ Alternatives Considered ──────────────────────╮
-│ 1. Auth and payments (chosen)                 │
-│ 2. User module first (coverage 71%, med risk) │
-│ 3. All modules equally (spread thin)          │
+│ 1. Auth and payments (chosen)                  │
+│ 2. User module first (coverage 71%, med risk)  │
+│ 3. All modules equally (spread thin)           │
 ╰────────────────────────────────────────────────╯
 
 ╭─ Impact ──────────────────────╮
-│ Downstream Decisions: 3     │
-│ Downstream Child Plans: 2  │
-│ Artifacts Produced: 5      │
-│ Correction Impact: medium  │
+│ Downstream Decisions: 3       │
+│ Downstream Child Plans: 2     │
+│ Artifacts Produced: 5         │
+│ Correction Impact: medium     │
 ╰───────────────────────────────╯
 
 ╭─ Context Snapshot ───────────────╮
@@ -3149,7 +3614,7 @@ $ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
 │ - Payments failures last release │
 │ - Auth: 12 files, 45% coverage   │
 │ - Payments: 8 files, 52% cover.  │
-│ Hot Context Hash: sha256:4b2e... │
+│ Hot Context Hash: sha256:4b2e... │
 ╰──────────────────────────────────╯
 
 ╭─ Rationale ───────────────────────────────────────╮
@@ -3160,11 +3625,54 @@ $ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
 ╰───────────────────────────────────────────────────╯
 
 ╭─ Correction ──────────────────────────────────────────────╮
-│ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9           │
+│ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9            │
 │   --mode revert --guidance "Prioritize payments first..." │
 ╰───────────────────────────────────────────────────────────╯
 
-✓ OK Decision explained
+✓ OK Decision explained
+
+ +Including the raw model reasoning with `--show-reasoning`: + +

+$ agents plan explain --show-reasoning 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
+
+╭─ Decision ──────────────────────────────╮
+│ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9          │
+│ Type: strategy_choice                   │
+│ Choice: Convert to async/await          │
+│ Alternatives: 3                         │
+╰─────────────────────────────────────────╯
+
+╭─ Alternatives Considered ────────────────────────────────────╮
+│ 1. Convert to async/await patterns (chosen)                  │
+│    2. Keep synchronous with thread pool                      │
+│    3. Use callback-based approach                            │
+╰──────────────────────────────────────────────────────────────╯
+
+╭─ Rationale ──────────────────────────────────────────────────╮
+│ Async/await is the modern Python standard for I/O-bound      │
+│ operations. The project already uses asyncio in 3 modules.   │
+│ Thread pools would add complexity without native support.    │
+╰──────────────────────────────────────────────────────────────╯
+
+╭─ Model Reasoning (raw) ───────────────────────────────────────╮
+│ I need to decide on the concurrency pattern for the payment   │
+│ processing module. Let me analyze the current codebase:       │
+│                                                               │
+│ 1. src/payments/api.py uses synchronous requests.             │
+│ 2. src/core/scheduler.py already uses asyncio.                │
+│ 3. The database driver (asyncpg) supports async natively.     │
+│ 4. Project invariant says "prefer modern Python patterns".    │
+│                                                               │
+│ Given that 3/5 core modules already use asyncio, and the      │
+│ database driver supports it, converting to async/await is     │
+│ the most consistent choice. Thread pools would work but       │
+│ add unnecessary complexity and don't integrate well with      │
+│ the existing asyncio event loop in scheduler.py.              │
+╰───────────────────────────────────────────────────────────────╯
+
+✓ OK Decision explained
##### agents plan correct @@ -3183,42 +3691,102 @@ Correct a decision either by reverting and re-executing or by appending a fix. **Examples** 

-$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert \
-  --guidance "Prioritize payments first" --yes
+$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert \
+  --guidance "Prioritize payments first" --yes
 
-╭─ Correction ─────────────────────────────────────╮
-│ Mode: revert                                     │
+╭─ Correction ────────────────────────────────────────╮
+│ Mode: revert                                        │
 │ Impact: 3 decisions, 2 child plans, 5 artifacts     │
-│ New Decision: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8         │
-│ Corrects: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9            │
-│ Attempt: 2                                       │
-╰──────────────────────────────────────────────────╯
+│ New Decision: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8            │
+│ Corrects: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9                │
+│ Attempt: 2                                          │
+╰─────────────────────────────────────────────────────╯
 
 ╭─ Affected Subtree ──────────────╮
-│ Decisions Invalidated: 3      │
-│ Child Plans Rolled Back: 2   │
-│ Artifacts Archived: 5        │
-│ Unaffected Decisions: 2      │
+│ Decisions Invalidated: 3        │
+│ Child Plans Rolled Back: 2      │
+│ Artifacts Archived: 5           │
+│ Unaffected Decisions: 2         │
 ╰─────────────────────────────────╯
 
 ╭─ Sandbox Rollback ─────────────╮
-│ Checkpoint: cp_01HXM8C2       │
-│ Files Reverted: 5             │
-│ Status: restored              │
+│ Checkpoint: cp_01HXM8C2        │
+│ Files Reverted: 5              │
+│ Status: restored               │
 ╰────────────────────────────────╯
 
 ╭─ Recompute ──────────────╮
-│ Queued: 2 child plans   │
-│ ETA: 4m                  │
+│ Queued: 2 child plans    │
+│ ETA: 4m                  │
 ╰──────────────────────────╯
 
-╭─ History ──────────────────────────────────────────╮
+╭─ History ───────────────────────────────────────────╮
 │ - Original decision superseded                      │
 │ - Prior artifacts archived for comparison           │
-│ - agents plan diff --correction 01HXM9B7Z3Q1Q8K2.. │
+│ - agents plan diff --correction 01HXM9B7Z3Q1Q8K2..  │
 ╰─────────────────────────────────────────────────────╯
 
-✓ OK Correction applied
+✓ OK Correction applied
+
+ +Using `--mode append` to add a corrective decision without reverting existing work (useful when the original decision was partially correct): + +

+$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode append \
+  --guidance "Also add rate limiting to the auth endpoints"
+
+╭─ Correction ─────────────────────────────────────╮
+│ Mode: append                                     │
+│ Impact: adds to existing subtree, no rollback    │
+│ New Decision: 01HXM9C3Z5T2Q8K2E9H7K3W2M8         │
+│ Appended After: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9       │
+│ Attempt: 2                                       │
+╰──────────────────────────────────────────────────╯
+
+╭─ Append Detail ─────────────────────────────────────────────────╮
+│ Original decision preserved: yes                                │
+│ Existing artifacts kept: yes                                    │
+│ Additional work: appended as new child plan                     │
+│ The original 5 artifacts remain; a new child plan will add      │
+│ rate-limiting code on top of the existing auth changes.         │
+╰─────────────────────────────────────────────────────────────────╯
+
+╭─ Queued ──────────╮
+│ New child: 1      │
+│ ETA: 2m           │
+╰───────────────────╯
+
+✓ OK Append correction queued
+
+ +Using `--dry-run` to preview the impact of a correction before committing to it: + +

+$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert \
+  --guidance "Use async/await pattern instead" --dry-run
+
+╭─ Dry Run — Correction Preview ─────────────────────────────────────╮
+│ ⚠  This is a preview only. No changes will be made.                │
+╰────────────────────────────────────────────────────────────────────╯
+
+╭─ Would Revert ───────────────────────────────────────╮
+│ Decisions to invalidate: 3                           │
+│   01HXM9A1..  strategy_choice    "sync pattern"      │
+│   01HXM9A2..  implementation_choice  "requests"      │
+│   01HXM9A3..  tool_invocation    write_file ×4       │
+│ Child plans to roll back: 2                          │
+│ Artifacts to archive: 5 files                        │
+│ Unaffected decisions: 2 (will be kept)               │
+╰──────────────────────────────────────────────────────╯
+
+╭─ Estimated Cost ──────────╮
+│ Re-strategize: ~$0.012    │
+│ Re-execute: ~$0.035       │
+│ Total: ~$0.047            │
+│ ETA: ~4 minutes           │
+╰───────────────────────────╯
+
+To execute this correction, remove --dry-run and add --yes
##### agents plan diff @@ -3228,52 +3796,88 @@ Show diffs for a plan or a correction attempt. **Arguments** -- `--plan `: Show diff for a plan. -- `--correction `: Compare correction outputs. +- ``: Show diff for a plan (positional argument). Mutually exclusive with --correction. +- `--correction CORRECTION_ATTEMPT_ID`: Show diff for a correction attempt instead. **Examples** 

-$ agents plan diff --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+$ agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
 ╭─ Diff Summary ─────────────────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J            │
-│ Project: local/api-service                  │
-│ Files Changed: 2                             │
-│ Insertions: 12                               │
-│ Deletions: 4                                 │
-│ Net Change: +8 lines                         │
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J               │
+│ Project: local/api-service                     │
+│ Files Changed: 2                               │
+│ Insertions: 12                                 │
+│ Deletions: 4                                   │
+│ Net Change: +8 lines                           │
 ╰────────────────────────────────────────────────╯
 
 ╭─ Files ───────────────────────────────╮
 │ Path                 Change  Status   │
 │ ───────────────────  ──────  ──────── │
-│ src/auth/session.py  +8 -2   modified │
-│ src/auth/tokens.py   +4 -2   modified │
+│ src/auth/session.py  +8 -2   modified │
+│ src/auth/tokens.py   +4 -2   modified │
 ╰───────────────────────────────────────╯
 
-╭─ Patch Preview ─────────────────────────╮
-│ --- a/src/auth/session.py              │
-│ +++ b/src/auth/session.py              │
-│ @@ -12,4 +12,10 @@                      │
-│ - import jwt                            │
-│ + import sessionlib                     │
-│ - def validate_token(...)               │
-│ + def validate_session(...)             │
-│ --- a/src/auth/tokens.py               │
-│ +++ b/src/auth/tokens.py               │
-│ @@ -5,3 +5,7 @@                         │
-│ - TOKEN_EXPIRY = 3600                    │
-│ + TOKEN_EXPIRY = 7200                    │
-╰─────────────────────────────────────────╯
+╭─ Patch Preview ──────────────────────────╮
+│ --- a/src/auth/session.py                │
+│ +++ b/src/auth/session.py                │
+│ @@ -12,4 +12,10 @@                       │
+│ - import jwt                             │
+│ + import sessionlib                      │
+│ - def validate_token(...)                │
+│ + def validate_session(...)              │
+│ --- a/src/auth/tokens.py                 │
+│ +++ b/src/auth/tokens.py                 │
+│ @@ -5,3 +5,7 @@                          │
+│ - TOKEN_EXPIRY = 3600                    │
+│ + TOKEN_EXPIRY = 7200                    │
+╰──────────────────────────────────────────╯
 
 ╭─ Risk Assessment ────────────────╮
-│ API Compatibility: preserved    │
-│ Test Coverage: maintained       │
-│ Breaking Changes: none detected │
+│ API Compatibility: preserved     │
+│ Test Coverage: maintained        │
+│ Breaking Changes: none detected  │
 ╰──────────────────────────────────╯
 
-✓ OK Diff generated
+✓ OK Diff generated
+
+ +Showing the diff for a specific correction attempt, comparing what changed between the original and corrected execution: + +

+$ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
+
+╭─ Correction Diff ───────────────────────────────╮
+│ Correction: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8          │
+│ Original Decision: 01HXM9A1C2Q7W3R5..           │
+│ Mode: revert                                    │
+│ Files Changed: 3                                │
+│ New Insertions: 18                              │
+│ New Deletions: 6                                │
+╰─────────────────────────────────────────────────╯
+
+╭─ Comparison ─────────────────────────────────────────────────────╮
+│ File                  Before (original)  After (corrected)       │
+│ ────────────────────  ────────────────  ────────────────────     │
+│ src/payments/api.py   +12 -4            +18 -6 (expanded)        │
+│ src/auth/tokens.py    +8 -2             (unchanged)              │
+│ tests/test_payments.py  (new file)      (new file, larger)       │
+╰──────────────────────────────────────────────────────────────────╯
+
+╭─ Patch Preview (corrected vs original) ───────────╮
+│ --- a/src/payments/api.py (original)              │
+│ +++ b/src/payments/api.py (corrected)             │
+│ @@ -1,12 +1,18 @@                                 │
+│ - # sync payment processing                       │
+│ + # async payment processing (corrected)          │
+│ + import asyncio                                  │
+│ + from aiohttp import ClientSession               │
+│   ...                                             │
+╰───────────────────────────────────────────────────╯
+
+✓ OK Correction diff generated
##### agents plan artifacts @@ -3288,32 +3892,32 @@ List artifacts produced by a plan. **Examples** 

-$ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+$ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
-╭─ Artifacts ──────────────────────────────────────────────╮
+╭─ Artifacts ─────────────────────────────────────────────────╮
 │ Path                   Type   Size    Change     Child Plan │
-│ ─────────────────────  ─────  ──────  ─────────  ─────── │
-│ src/auth/session.py    write  2.1 KB  +8 -2      root    │
-│ tests/test_session.py  write  4.7 KB  +47 -0     root    │
-│ src/auth/tokens.py     edit   1.8 KB  +4 -2      root    │
-│ tests/test_tokens.py   write  3.2 KB  +32 -0     auth    │
-╰──────────────────────────────────────────────────────────╯
+│ ─────────────────────  ─────  ──────  ─────────  ───────    │
+│ src/auth/session.py    write  2.1 KB  +8 -2      root       │
+│ tests/test_session.py  write  4.7 KB  +47 -0     root       │
+│ src/auth/tokens.py     edit   1.8 KB  +4 -2      root       │
+│ tests/test_tokens.py   write  3.2 KB  +32 -0     auth       │
+╰─────────────────────────────────────────────────────────────╯
 
-╭─ Summary ──────────╮
-│ Total: 4           │
-│ Writes: 2 (new)    │
-│ Edits: 2 (modified) │
-│ Deletes: 0         │
-│ Total Size: 11.8 KB │
-╰────────────────────╯
+╭─ Summary ───────────╮
+│ Total: 4            │
+│ Writes: 2 (new)     │
+│ Edits: 2 (modified) │
+│ Deletes: 0          │
+│ Total Size: 11.8 KB │
+╰─────────────────────╯
 
 ╭─ By Plan ─────────────────╮
-│ Root Plan: 3 artifacts    │
-│ auth-tests: 1 artifact   │
-│ payment-tests: (pending) │
+│ Root Plan: 3 artifacts    │
+│ auth-tests: 1 artifact    │
+│ payment-tests: (pending)  │
 ╰───────────────────────────╯
 
-✓ OK 4 artifacts listed
+✓ OK 4 artifacts listed
##### agents plan prompt @@ -3329,64 +3933,28 @@ Provide additional guidance to a plan, typically when it is errored or awaiting **Examples** 

-$ agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
+$ agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
 
-╭─ Guidance Added ───────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J       │
-│ Guidance: Use mocks for database tests │
-│ Scope: next execution step             │
-│ Phase: execute                          │
-│ State: errored → processing            │
-╰────────────────────────────────────────╯
+╭─ Guidance Added ────────────────────────╮
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J        │
+│ Guidance: Use mocks for database tests  │
+│ Scope: next execution step              │
+│ Phase: execute                          │
+│ State: errored → processing             │
+╰─────────────────────────────────────────╯
 
 ╭─ Decision Created ────────────────────────╮
-│ Type: user_intervention                 │
-│ ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3        │
-│ Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9     │
+│ Type: user_intervention                   │
+│ ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3            │
+│ Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9        │
 ╰───────────────────────────────────────────╯
 
 ╭─ Queue ────╮
 │ Pending: 1 │
-│ Applied: 0 │
+│ Applied: 0 │
 ╰────────────╯
 
-✓ OK Guidance queued
-
- -##### agents plan resume - -**Purpose** -Resume an interrupted plan from its last checkpoint. - -**Arguments** - -- ``: Plan ID. - -**Examples** - -

-$ agents plan resume 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
-╭─ Plan Resumed ───────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Checkpoint: cp_01HXM8C2          │
-│ Phase: execute                   │
-│ State: processing                │
-│ Attempt: 2                       │
-╰──────────────────────────────────╯
-
-╭─ Checkpoint Details ──────────────╮
-│ Label: before auth refactor     │
-│ Created: 2026-02-08 13:04       │
-│ Files at Checkpoint: 3          │
-│ Decisions at Checkpoint: 2      │
-╰───────────────────────────────────╯
-
-╭─ Pending Guidance ─────────────────╮
-│ 1. Use mocks for database tests │
-╰────────────────────────────────────╯
-
-✓ OK Plan resumed
+✓ OK Guidance queued
##### agents plan rollback @@ -3403,7 +3971,7 @@ Rollback a plan sandbox to a checkpoint. **Examples** 

-$ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
+$ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
 
 Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
 
@@ -3415,30 +3983,30 @@ Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
 ╰──────────────────────────────────╯
 
 ╭─ Changes Reverted ──────────────────╮
-│ File                    Action     │
-│ ──────────────────────  ────────── │
-│ src/auth/session.py     restored   │
-│ src/auth/tokens.py      restored   │
-│ tests/test_session.py   removed    │
-│ tests/test_tokens.py    removed    │
-│ src/auth/fixtures.py    restored   │
-│ src/auth/__init__.py    restored   │
+│ File                    Action      │
+│ ──────────────────────  ──────────  │
+│ src/auth/session.py     restored    │
+│ src/auth/tokens.py      restored    │
+│ tests/test_session.py   removed     │
+│ tests/test_tokens.py    removed     │
+│ src/auth/fixtures.py    restored    │
+│ src/auth/__init__.py    restored    │
 ╰─────────────────────────────────────╯
 
 ╭─ Impact ──────────────────────────────╮
-│ Child Plans Invalidated: 2          │
-│ Sandbox: restored to cp_01HXM8C2   │
-│ Decisions After CP: 2 discarded     │
-│ Tool Calls After CP: 5 undone      │
+│ Child Plans Invalidated: 2            │
+│ Sandbox: restored to cp_01HXM8C2      │
+│ Decisions After CP: 2 discarded       │
+│ Tool Calls After CP: 5 undone         │
 ╰───────────────────────────────────────╯
 
-╭─ Post-Rollback State ─────────╮
-│ Phase: execute                │
-│ State: queued (awaiting input) │
-│ Checkpoints Remaining: 2     │
-╰───────────────────────────────╯
+╭─ Post-Rollback State ──────────╮
+│ Phase: execute                 │
+│ State: queued (awaiting input) │
+│ Checkpoints Remaining: 2       │
+╰────────────────────────────────╯
 
-✓ OK Rollback complete
+✓ OK Rollback complete
#### agents action @@ -3449,14 +4017,15 @@ Manage reusable actions. ##### agents action create **Purpose** -Create a new action template. +Create a new action template from a YAML configuration file. The `--config` file is required and must fully define the action. CLI options provided alongside `--config` act as optional overrides for values defined in the configuration file. **Arguments** -- ``: Namespaced action name. -- `--strategy-actor/-s ACTOR`: Strategize actor. -- `--execution-actor/-e ACTOR`: Execution actor. -- `--definition-of-done/-d TEXT`: Completion criteria. +- `[]`: Namespaced action name (optional when provided in config file). +- `--config/-c FILE`: YAML configuration file defining the action (required). The file must fully define the action. Any CLI options provided alongside `--config` override the corresponding values in the file. +- `--strategy-actor ACTOR`: Override the Strategize actor from config. +- `--execution-actor ACTOR`: Override the Execution actor from config. +- `--definition-of-done TEXT`: Override the completion criteria from config. - `--description TEXT`: Short description. - `--long-description TEXT`: Long description. - `--arg/-a spec`: Argument definition (repeatable). @@ -3465,33 +4034,26 @@ Create a new action template. - `--available`: Make action available immediately. - `--estimation-actor ACTOR`: Optional estimation actor. - `--invariant-actor ACTOR`: Invariant Reconciliation Actor for this action. Carried forward to plans created from this action (can be overridden via `agents plan use --invariant-actor`). -- `--safety-profile NAME`: Named safety profile. -- `--require-sandbox/--no-require-sandbox`: Enforce sandboxing. -- `--require-checkpoints/--no-require-checkpoints`: Enforce checkpoints. -- `--require-apply-approval/--no-require-apply-approval`: Require approval before apply. -- `--allow-skill-category NAME`: Allow skill categories. -- `--deny-skill-category NAME`: Deny skill categories. +- `--automation-profile PROFILE`: Default automation profile for plans created from this action. - `--invariant TEXT`: Invariant to attach to this action (repeatable). These invariants are carried forward as plan-level invariants when the action is used. +The `--config` file must define `strategy-actor`, `execution-actor`, and `definition-of-done`. Any of these can be overridden via CLI flags. + **Examples** 

-$ agents action create local/code-coverage \
-  --strategy-actor local/strategist \
-  --execution-actor local/executor \
-  --definition-of-done "Coverage reaches 85%" \
-  --arg "target_coverage_percent:int:required:Target coverage percentage" \
-  --available
+$ agents action create --config ./actions/code-coverage.yaml \
+  --available local/code-coverage
 
 ╭─ Action Created ──────────────────────╮
 │ Name: local/code-coverage             │
-│ ID: 01HXMAY3D1JQ0C3G1H0Q7B2W7M        │
+│ ID: 01HXMAY3D1JQ0C3G1H0Q7B2W7M        │
 │ State: available                      │
 │ Strategy Actor: local/strategist      │
 │ Execution Actor: local/executor       │
-│ Reusable: yes                         │
-│ Read Only: no                         │
-│ Created: 2026-02-08 12:20             │
+│ Reusable: yes                         │
+│ Read Only: no                         │
+│ Created: 2026-02-08 12:20             │
 ╰───────────────────────────────────────╯
 
 ╭─ Definition of Done ─╮
@@ -3499,26 +4061,91 @@ $ agents action create local/code-coverage \
 ╰──────────────────────╯
 
 ╭─ Arguments ──────────────────────────────────────────────────────╮
-│ Name                     Type    Required  Description          │
+│ Name                     Type    Required  Description           │
 │ ───────────────────────  ──────  ────────  ───────────────────── │
-│ target_coverage_percent  int     yes       Target coverage %    │
+│ target_coverage_percent  int     yes       Target coverage %     │
 │ test_command             string  no        Test framework to use │
 ╰──────────────────────────────────────────────────────────────────╯
 
-╭─ Safety ──────────────────╮
-│ Sandbox: required         │
-│ Apply Approval: required  │
-│ Checkpoints: enabled      │
-│ Skill Allow: (all)        │
-│ Skill Deny: (none)        │
-╰───────────────────────────╯
+╭─ Automation ──────────────────────────╮
+│ Profile: supervised                   │
+│ Source: default                       │
+╰───────────────────────────────────────╯
 
-╭─ Usage ─────────────────────────────────────────────────────────────────╮
-│ agents plan use local/code-coverage --project local/api-service         │
-│   --arg target_coverage_percent=85                                      │
-╰─────────────────────────────────────────────────────────────────────────╯
+╭─ Usage ──────────────────────────────────────────────────────────────────╮
+│ agents plan use local/code-coverage local/api-service                    │
+│   --arg target_coverage_percent=85                                       │
+╰──────────────────────────────────────────────────────────────────────────╯
 
-✓ OK Action created
+✓ OK Action created
+
+ +Creating an action entirely from a YAML configuration file: + +

+$ agents action create local/code-coverage --config ./actions/code-coverage.yaml
+
+╭─ Action Created ────────────────────────╮
+│ Name: local/code-coverage               │
+│ ID: 01HXMAY3D1JQ0C3G1H0Q7B2W7M          │
+│ State: draft                            │
+│ Strategy Actor: local/strategist        │
+│ Execution Actor: local/executor         │
+│ Reusable: yes                           │
+│ Read Only: no                           │
+│ Config: ./actions/code-coverage.yaml    │
+│ Created: 2026-02-08 12:20               │
+╰─────────────────────────────────────────╯
+
+╭─ Definition of Done ─╮
+│ Coverage reaches 85% │
+╰──────────────────────╯
+
+╭─ Arguments ──────────────────────────────────────────────────────╮
+│ Name                     Type    Required  Description           │
+│ ───────────────────────  ──────  ────────  ───────────────────── │
+│ target_coverage_percent  int     yes       Target coverage %     │
+│ test_command             string  no        Test framework to use │
+╰──────────────────────────────────────────────────────────────────╯
+
+╭─ Automation ──────────────────────────╮
+│ Profile: supervised                   │
+│ Source: default                       │
+╰───────────────────────────────────────╯
+
+✓ OK Action created
+
+ +Creating an action from a config file with CLI overrides (the `--execution-actor` overrides the value from the YAML, and `--available` is added): + +

+$ agents action create local/code-coverage \
+  --config ./actions/code-coverage.yaml \
+  --execution-actor local/fast-executor \
+  --available
+
+╭─ Action Created ────────────────────────╮
+│ Name: local/code-coverage               │
+│ ID: 01HXMAY3D1JQ0C3G1H0Q7B2W7M          │
+│ State: available                        │
+│ Strategy Actor: local/strategist        │
+│ Execution Actor: local/fast-executor    │
+│ Reusable: yes                           │
+│ Read Only: no                           │
+│ Config: ./actions/code-coverage.yaml    │
+│ Created: 2026-02-08 12:20               │
+╰─────────────────────────────────────────╯
+
+╭─ Overrides Applied ──────────────────────────────────────╮
+│ execution_actor: local/executor → local/fast-executor    │
+│ available: false → true                                  │
+╰──────────────────────────────────────────────────────────╯
+
+╭─ Definition of Done ─╮
+│ Coverage reaches 85% │
+╰──────────────────────╯
+
+✓ OK Action created
##### agents action list @@ -3535,28 +4162,28 @@ List actions with optional filters. **Examples** 

-$ agents action list --available
+$ agents action list --available
 
 ╭─ Actions ──────────────────────────────────────────────────────────────────────────────────╮
-│ Name                 State      Strategy Actor    Execution Actor  Reusable  Plans │
-│ ───────────────────  ─────────  ────────────────  ───────────────  ────────  ───── │
-│ local/code-coverage  available  local/strategist  local/executor   ✓         3     │
-╰──────────────────────────────────────────────────────────────────────────────────────────╯
+│ Name                 State      Strategy Actor    Execution Actor  Reusable  Plans         │
+│ ───────────────────  ─────────  ────────────────  ───────────────  ────────  ─────         │
+│ local/code-coverage  available  local/strategist  local/executor   ✓         3             │
+╰────────────────────────────────────────────────────────────────────────────────────────────╯
 
 ╭─ Filters ────────╮
 │ State: available │
-│ Namespace: (any) │
+│ Namespace: (any) │
 ╰──────────────────╯
 
-╭─ Summary ────────────╮
-│ Total: 1             │
-│ Available: 1         │
-│ Draft: 0              │
-│ Archived: 0          │
-│ Total Plans Created: 3 │
-╰──────────────────────╯
+╭─ Summary ──────────────╮
+│ Total: 1               │
+│ Available: 1           │
+│ Draft: 0               │
+│ Archived: 0            │
+│ Total Plans Created: 3 │
+╰────────────────────────╯
 
-✓ OK 1 action listed
+✓ OK 1 action listed
##### agents action show @@ -3566,22 +4193,22 @@ Show details for an action. **Arguments** -- ``: Action ID or name. +- ``: Action name. **Examples** 

-$ agents action show local/code-coverage
+$ agents action show local/code-coverage
 
 ╭─ Action Details ──────────────────────╮
 │ Name: local/code-coverage             │
-│ ID: 01HXMAY3D1JQ0C3G1H0Q7B2W7M        │
+│ ID: 01HXMAY3D1JQ0C3G1H0Q7B2W7M        │
 │ State: available                      │
 │ Strategy Actor: local/strategist      │
 │ Execution Actor: local/executor       │
-│ Reusable: yes                         │
-│ Read Only: no                         │
-│ Created: 2026-02-08 12:20             │
+│ Reusable: yes                         │
+│ Read Only: no                         │
+│ Created: 2026-02-08 12:20             │
 ╰───────────────────────────────────────╯
 
 ╭─ Definition of Done ─╮
@@ -3589,32 +4216,31 @@ $ agents action show local/code-coverage
 ╰──────────────────────╯
 
 ╭─ Arguments ──────────────────────────────────────────────────────╮
-│ Name                     Type    Required  Description          │
+│ Name                     Type    Required  Description           │
 │ ───────────────────────  ──────  ────────  ───────────────────── │
-│ target_coverage_percent  int     yes       Target coverage %    │
+│ target_coverage_percent  int     yes       Target coverage %     │
 │ test_command             string  no        Test framework to use │
 ╰──────────────────────────────────────────────────────────────────╯
 
-╭─ Safety ──────────────────╮
-│ Sandbox: required         │
-│ Apply Approval: required  │
-│ Checkpoints: enabled      │
-╰───────────────────────────╯
+╭─ Automation ──────────────────────────╮
+│ Profile: supervised                   │
+│ Source: default                       │
+╰───────────────────────────────────────╯
 
 ╭─ History ────────────────────╮
-│ Plans Created: 3           │
-│ Plans Completed: 2        │
-│ Plans Failed: 0            │
-│ Avg Duration: 00:04:30    │
-│ Avg Cost: $0.072           │
+│ Plans Created: 3             │
+│ Plans Completed: 2           │
+│ Plans Failed: 0              │
+│ Avg Duration: 00:04:30       │
+│ Avg Cost: $0.072             │
 ╰──────────────────────────────╯
 
 ╭─ Usage ───────────────────────────────────────────────────────────╮
-│ - agents plan use local/code-coverage --project local/api-service │
+│ - agents plan use local/code-coverage local/api-service           │
 │     --arg target_coverage_percent=85                              │
 ╰───────────────────────────────────────────────────────────────────╯
 
-✓ OK Action loaded
+✓ OK Action loaded
##### agents action available @@ -3624,33 +4250,33 @@ Mark a draft action as available. **Arguments** -- ``: Action ID or name. +- ``: Action name. **Examples** 

-$ agents action available 01HXMAY3D1JQ0C3G1H0Q7B2W7M
+$ agents action available 01HXMAY3D1JQ0C3G1H0Q7B2W7M
 
 ╭─ Action Available ─────────────╮
 │ ID: 01HXMAY3D1JQ0C3G1H0Q7B2W7M │
 │ State: draft → available       │
-│ Name: local/code-coverage      │
+│ Name: local/code-coverage      │
 ╰────────────────────────────────╯
 
 ╭─ Visibility ─────╮
-│ Namespace: local │
-│ Listed: yes      │
-│ Usable: yes      │
+│ Namespace: local │
+│ Listed: yes      │
+│ Usable: yes      │
 ╰──────────────────╯
 
 ╭─ Validation ────────────────────────╮
-│ Strategy Actor: resolved           │
-│ Execution Actor: resolved          │
-│ Definition of Done: present        │
-│ Arguments: valid schema            │
+│ Strategy Actor: resolved            │
+│ Execution Actor: resolved           │
+│ Definition of Done: present         │
+│ Arguments: valid schema             │
 ╰─────────────────────────────────────╯
 
-✓ OK Action marked available
+✓ OK Action marked available
##### agents action archive @@ -3660,33 +4286,187 @@ Archive an action. **Arguments** -- ``: Action ID or name. +- ``: Action name. **Examples** 

-$ agents action archive local/old-action
+$ agents action archive local/old-action
 
-╭─ Action Archived ──────────╮
-│ Name: local/old-action     │
+╭─ Action Archived ───────────╮
+│ Name: local/old-action      │
 │ State: available → archived │
-│ Archived: 2026-02-08 12:22 │
-╰────────────────────────────╯
+│ Archived: 2026-02-08 12:22  │
+╰─────────────────────────────╯
 
 ╭─ Impact ───────────────────────╮
 │ Availability: hidden from list │
-│ Existing Plans: unchanged      │
-│ Active Plans: 0 affected       │
+│ Existing Plans: unchanged      │
+│ Active Plans: 0 affected       │
 ╰────────────────────────────────╯
 
 ╭─ History ─────────────────╮
-│ Total Plans: 5          │
-│ Completed: 4            │
-│ Failed: 1               │
-│ Last Used: 2026-02-06  │
+│ Total Plans: 5            │
+│ Completed: 4              │
+│ Failed: 1                 │
+│ Last Used: 2026-02-06     │
 ╰───────────────────────────╯
 
-✓ OK Action archived
+✓ OK Action archived
+
+ +#### agents automation-profile + +**Purpose** +Manage automation profiles — named collections of boolean flags that control which tasks are automated vs. require human approval. Built-in profiles (`locked-down`, `manual`, `supervised`, `trusted`, `autonomous`, `full-auto`) are always available. Custom profiles follow the same `/` naming convention as other entities. + +##### agents automation-profile add + +**Purpose** +Register a new custom automation profile from a YAML configuration file. If a profile with the same name already exists, the command fails unless the `--update` flag is provided. + +**Arguments** + +- `[]`: Profile name (optional when provided in config file). +- `--config/-c FILE`: YAML configuration file defining the profile (required). +- `--update`: Replace an existing profile with the same name. + +**Examples** + +

+$ agents automation-profile add --config ./profiles/careful-auto.yaml
+
+╭─ Profile Registered ─────────────────────────────────────────────╮
+│ Name: local/careful-auto                                         │
+│ Description: Autonomous execution with mandatory sandbox         │
+│              and manual apply                                    │
+│ Created: 2026-02-08 14:30                                        │
+╰──────────────────────────────────────────────────────────────────╯
+
+╭─ Flags ────────────────────────────────╮
+│ auto_strategize: true                  │
+│ auto_execute: true                     │
+│ auto_apply: false                      │
+│ auto_decisions_strategize: true        │
+│ auto_decisions_execute: true           │
+│ auto_validation_fix: true              │
+│ auto_strategy_revision: false          │
+│ auto_child_plans: true                 │
+│ auto_retry_transient: true             │
+│ auto_checkpoint_restore: true          │
+│ require_sandbox: true                  │
+│ require_checkpoints: true              │
+│ allow_unsafe_tools: false              │
+╰────────────────────────────────────────╯
+
+✓ OK Profile registered
+
+ +##### agents automation-profile remove + +**Purpose** +Remove a custom automation profile. Built-in profiles cannot be removed. + +**Arguments** + +- ``: Profile name. +- `--yes, -y`: Skip confirmation prompt. + +**Examples** + +

+$ agents automation-profile remove local/careful-auto
+
+Remove automation profile local/careful-auto? [y/N]: y
+
+╭─ Profile Removed ──────────╮
+│ Name: local/careful-auto   │
+╰────────────────────────────╯
+
+✓ OK Profile removed
+
+ +##### agents automation-profile list + +**Purpose** +List all available automation profiles (built-in and custom). + +**Arguments** + +- `[REGEX]`: Optional filter pattern. + +**Examples** + +

+$ agents automation-profile list
+
+╭─ Automation Profiles ─────────────────────────────────────────────────────────╮
+│ Name                Source    Auto-Apply  Sandbox  Description                │
+│ ──────────────────  ────────  ──────────  ───────  ────────────────────────   │
+│ locked-down        built-in  no          yes      Maximum human control       │
+│ manual             built-in  no          yes      Human-driven (default)      │
+│ supervised         built-in  no          yes      Auto-plan, manual exec      │
+│ trusted            built-in  no          yes      Auto-exec, manual apply     │
+│ autonomous         built-in  no          yes      Full auto except apply      │
+│ full-auto          built-in  yes         no       Complete automation         │
+│ local/careful-auto custom    no          yes      Custom careful profile      │
+╰───────────────────────────────────────────────────────────────────────────────╯
+
+╭─ Summary ───────────╮
+│ Built-in: 6         │
+│ Custom: 1           │
+│ Total: 7            │
+╰─────────────────────╯
+
+✓ OK 7 profiles listed
+
+ +##### agents automation-profile show + +**Purpose** +Show full details for an automation profile, including all flag values. + +**Arguments** + +- ``: Profile name. + +**Examples** + +

+$ agents automation-profile show trusted
+
+╭─ Automation Profile ───────────────────────────────────────────╮
+│ Name: trusted                                                  │
+│ Source: built-in                                               │
+│ Description: Auto-exec, manual apply. Day-to-day development   │
+╰────────────────────────────────────────────────────────────────╯
+
+╭─ Phase Transitions ──────────────────╮
+│ auto_strategize: true                │
+│ auto_execute: true                   │
+│ auto_apply: false                    │
+╰──────────────────────────────────────╯
+
+╭─ Decision Automation ────────────────╮
+│ auto_decisions_strategize: true      │
+│ auto_decisions_execute: true         │
+╰──────────────────────────────────────╯
+
+╭─ Self-Repair ────────────────────────╮
+│ auto_validation_fix: true            │
+│ auto_strategy_revision: false        │
+│ auto_retry_transient: true           │
+│ auto_checkpoint_restore: false       │
+╰──────────────────────────────────────╯
+
+╭─ Execution Controls ─────────────────╮
+│ auto_child_plans: true               │
+│ require_sandbox: true                │
+│ require_checkpoints: true            │
+│ allow_unsafe_tools: false            │
+╰──────────────────────────────────────╯
+
+✓ OK Profile loaded
#### agents config @@ -3701,36 +4481,68 @@ Set a configuration key. **Arguments** -- ``: automation-level, default-actor, log-level, invariant-actor. +- ``: automation-profile, log-level, invariant-actor, format. - ``: Value to set. The `invariant-actor` key sets the default Invariant Reconciliation Actor used globally. This actor is used to reconcile invariant conflicts when neither the plan nor the project specifies one. +The `format` key sets the default output rendering format used by all commands. Accepted values are `rich`, `color`, `table`, `plain`, `json`, `yaml`. When set, this value is used unless overridden by the `--format` CLI flag. See **Output Rendering Framework** for details. + **Examples** 

-$ agents config set automation-level review
+$ agents config set automation-profile trusted
 
-╭─ Config Updated ──────────────╮
-│ Key: automation-level         │
-│ Value: review                 │
-│ Previous: manual              │
-│ Source: config                │
-│ Scope: global                 │
-╰──────────────────────────────╯
+╭─ Config Updated ───────────────╮
+│ Key: automation-profile        │
+│ Value: trusted                 │
+│ Previous: manual               │
+│ Source: config                 │
+│ Scope: global                  │
+╰────────────────────────────────╯
 
 ╭─ Effective ────────────────────────╮
-│ Sessions: new sessions           │
-│ Plans: future plans (unless set) │
-│ Existing: unchanged              │
+│ Sessions: new sessions             │
+│ Plans: future plans (unless set)   │
+│ Existing: unchanged                │
 ╰────────────────────────────────────╯
 
 ╭─ Saved To ──────────────────────────╮
-│ File: ~/.cleveragents/config.toml │
-│ Line: 8                           │
+│ File: ~/.cleveragents/config.toml   │
+│ Line: 8                             │
 ╰─────────────────────────────────────╯
 
-✓ OK Config updated
+✓ OK Config updated
+
+ +Setting the default output format: + +

+$ agents config set format table
+
+╭─ Config Updated ─────────────────╮
+│ Key: format                      │
+│ Previous: rich                   │
+│ New Value: table                 │
+│ Scope: user (~/.cleveragents)    │
+╰──────────────────────────────────╯
+
+✓ OK Set format = table
+
+ +Setting a global invariant actor: + +

+$ agents config set invariant-actor local/invariant-resolver
+
+╭─ Config Updated ──────────────────────────╮
+│ Key: invariant-actor                      │
+│ Previous: (not set)                       │
+│ New Value: local/invariant-resolver       │
+│ Scope: user (~/.cleveragents)             │
+╰───────────────────────────────────────────╯
+
+✓ OK Set invariant-actor = local/invariant-resolver
##### agents config get @@ -3745,31 +4557,31 @@ Get a configuration value. **Examples** 

-$ agents config get default-actor
+$ agents config get automation-profile
 
-╭─ Config ──────────────────╮
-│ Key: default-actor        │
-│ Value: local/orchestrator │
-│ Source: config            │
-│ Overridden: no            │
-│ Type: string              │
-╰───────────────────────────╯
+╭─ Config ───────────────────╮
+│ Key: automation-profile    │
+│ Value: trusted             │
+│ Source: config             │
+│ Overridden: no             │
+│ Type: string               │
+╰────────────────────────────╯
 
 ╭─ Origin ──────────────────────────╮
-│ File: ~/.cleveragents/config.toml │
-│ Line: 12                          │
-│ Default: local/orchestrator      │
+│ File: ~/.cleveragents/config.toml │
+│ Line: 8                           │
+│ Default: full                     │
 ╰───────────────────────────────────╯
 
 ╭─ Resolution Chain ──────────────╮
 │ 1. CLI flag: (not set)          │
 │ 2. Env var: (not set)           │
-│ 3. Config file: local/orchestra │
-│ 4. Default: local/orchestrator  │
-│ Winner: config file (level 3)   │
+│ 3. Config file: review          │
+│ 4. Default: full                │
+│ Winner: config file (level 3)   │
 ╰─────────────────────────────────╯
 
-✓ OK Config read
+✓ OK Config read
##### agents config list @@ -3784,84 +4596,28 @@ None. **Examples** 

-$ agents config list
+$ agents config list
 
-╭─ Config ───────────────────────────────────────────────╮
-│ Key               Value               Source   Modified  │
-│ ────────────────  ──────────────────  ───────  ──────── │
-│ automation-level  review              config   yes       │
-│ default-actor     local/orchestrator  config   yes       │
-│ invariant-actor   local/reconciler    config   yes       │
-│ log-level         INFO                default  no        │
-│ sandbox-required  true                default  no        │
-│ apply-approval    true                default  no        │
-╰────────────────────────────────────────────────────────╯
+╭─ Config ──────────────────────────────────────────────────╮
+│ Key               Value               Source   Modified   │
+│ ────────────────  ──────────────────  ───────  ────────   │
+│ automation-profile trusted             config   yes       │
+│ invariant-actor   local/reconciler    config   yes        │
+│ log-level         INFO                default  no         │
+╰───────────────────────────────────────────────────────────╯
 
 ╭─ Overrides ─────╮
 │ Env: none       │
-│ CLI Flags: none │
+│ CLI Flags: none │
 ╰─────────────────╯
 
 ╭─ Config File ───────────────────────╮
-│ Path: ~/.cleveragents/config.toml │
-│ Size: 284 bytes                   │
-│ Valid: yes                        │
+│ Path: ~/.cleveragents/config.toml   │
+│ Size: 284 bytes                     │
+│ Valid: yes                          │
 ╰─────────────────────────────────────╯
 
-✓ OK 6 settings listed
-
- -#### agents providers - -**Purpose** -Inspect provider availability. - -##### agents providers list - -**Purpose** -List available providers and whether credentials are configured. - -**Arguments** - -None. - -**Examples** - -

-$ agents providers list
-
-╭─ Providers ───────────────────────────────────────────────────────╮
-│ Provider    Status       Default Model  Models Available │
-│ ──────────  ───────────  ─────────────  ──────────────── │
-│ openai      missing key  gpt-4          4                │
-│ anthropic   configured   claude-3.5     3                │
-│ openrouter  configured   gpt-4o         12               │
-│ google      missing key  gemini-2.0     2                │
-╰──────────────────────────────────────────────────────────────────╯
-
-╭─ Credentials ─╮
-│ Configured: 2 │
-│ Missing: 2    │
-╰───────────────╯
-
-╭─ Routing ──────────────────────╮
-│ Default: anthropic/claude-3.5  │
-│ Fallback: openrouter/gpt-4o   │
-╰────────────────────────────────╯
-
-╭─ Key Sources ─────────────────────╮
-│ anthropic: ANTHROPIC_API_KEY     │
-│ openrouter: OPENROUTER_API_KEY   │
-│ openai: OPENAI_API_KEY (missing) │
-│ google: GOOGLE_API_KEY (missing) │
-╰───────────────────────────────────╯
-
-╭─ Rate Limits ───────────────╮
-│ anthropic: 1M tokens/min  │
-│ openrouter: 500K tok/min │
-╰─────────────────────────────╯
-
-✓ OK Providers listed
+✓ OK 6 settings listed
#### agents invariant @@ -3876,59 +4632,59 @@ Add an invariant at the specified scope. **Arguments** -- `""`: The invariant text. +- ``: The invariant text (positional argument at end of command). - `--global`: Attach as a global invariant (applies to all plans). - `--project/-p PROJECT`: Attach to a project (applies to all plans targeting this project). -- `--plan PLAN_ID`: Attach to a plan (applies to this plan and its child plans). -- `--action ACTION`: Attach to an action (carried forward when the action is used via `agents plan use`). +- `--plan PLAN_ID`: Attach to a plan (plan-level invariant). Repeatable. +- `--action ACTION`: Attach to an action (action-level invariant). Repeatable. -Exactly one of `--global`, `--project`, `--plan`, or `--action` must be provided. +At least one scope flag (`--global`, `--project`, `--plan`, or `--action`) must be provided. `--plan` and `--action` can be repeated to attach the same invariant to multiple plans or actions. **Examples** 

-$ agents invariant add --global "All public APIs must maintain backward compatibility"
+$ agents invariant add --global "All public APIs must maintain backward compatibility"
 
 ╭─ Invariant Added ──────────────────────────────────────────────────────╮
-│ Invariant: All public APIs must maintain backward compatibility      │
-│ Scope: global                                                       │
-│ ID: inv_01HXM9A1B                                                  │
+│ Invariant: All public APIs must maintain backward compatibility        │
+│ Scope: global                                                          │
+│ ID: inv_01HXM9A1B                                                      │
 ╰────────────────────────────────────────────────────────────────────────╯
 
-✓ OK Invariant added
+✓ OK Invariant added
 
-$ agents invariant add --project local/api-service "All endpoints must validate auth tokens"
+$ agents invariant add --project local/api-service "All endpoints must validate auth tokens"
 
 ╭─ Invariant Added ──────────────────────────────────────────────╮
-│ Project: local/api-service                                   │
-│ Invariant: All endpoints must validate auth tokens           │
-│ Scope: project                                              │
-│ ID: inv_01HXM9A2C                                           │
+│ Project: local/api-service                                     │
+│ Invariant: All endpoints must validate auth tokens             │
+│ Scope: project                                                 │
+│ ID: inv_01HXM9A2C                                              │
 ╰────────────────────────────────────────────────────────────────╯
 
-✓ OK Invariant added
+✓ OK Invariant added
 
-$ agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
+$ agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
 
 ╭─ Invariant Added ─────────────────────────────────────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J                                    │
-│ Invariant: All database queries must use parameterized statements    │
-│ Scope: plan                                                        │
-│ ID: inv_01HXM9G3A                                                  │
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J                                      │
+│ Invariant: All database queries must use parameterized statements     │
+│ Scope: plan                                                           │
+│ ID: inv_01HXM9G3A                                                     │
 ╰───────────────────────────────────────────────────────────────────────╯
 
-✓ OK Invariant added
+✓ OK Invariant added
 
-$ agents invariant add --action local/code-coverage "Test files must not import production secrets"
+$ agents invariant add --action local/code-coverage "Test files must not import production secrets"
 
 ╭─ Invariant Added ──────────────────────────────────────────────────────╮
-│ Action: local/code-coverage                                        │
-│ Invariant: Test files must not import production secrets             │
-│ Scope: action                                                      │
-│ ID: inv_01HXM9H4B                                                  │
+│ Action: local/code-coverage                                            │
+│ Invariant: Test files must not import production secrets               │
+│ Scope: action                                                          │
+│ ID: inv_01HXM9H4B                                                      │
 ╰────────────────────────────────────────────────────────────────────────╯
 
-✓ OK Invariant added
+✓ OK Invariant added
##### agents invariant list @@ -3943,37 +4699,36 @@ List invariants at a given scope. Use `--effective` with `--plan` to show the fi - `--plan PLAN_ID`: List invariants attached to a plan. - `--action ACTION`: List invariants attached to an action. - `--effective`: (Only with `--plan`) Show the reconciled invariant view after precedence resolution across all scopes. -- `--format table|json`: Output format (default: table). **Examples** 

-$ agents invariant list --global
+$ agents invariant list --global
 
 ╭─ Global Invariants ──────────────────────────────────────────────────────╮
-│ ID              Text                                                  │
-│ ──────────────  ────────────────────────────────────────────────────   │
-│ inv_01HXM9A1B  All public APIs must maintain backward compatibility     │
-│ inv_01HXM9A1C  Payment processing must be idempotent                    │
+│ ID              Text                                                     │
+│ ──────────────  ────────────────────────────────────────────────────     │
+│ inv_01HXM9A1B  All public APIs must maintain backward compatibility      │
+│ inv_01HXM9A1C  Payment processing must be idempotent                     │
 ╰──────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 2 invariants
+✓ OK 2 invariants
 
-$ agents invariant list --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J --effective
+$ agents invariant list --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J --effective
 
-╭─ Effective Invariants (Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J) ─────────────────────────────────╮
-│ ID              Source   Text                                                   │
-│ ──────────────  ───────  ──────────────────────────────────────────────────────   │
-│ inv_01HXM9A1B  global   All public APIs must maintain backward compatibility      │
-│ inv_01HXM9A2C  project  All endpoints must validate auth tokens                   │
-│ inv_01HXM9G3A  plan     All database queries must use parameterized statements    │
+╭─ Effective Invariants (Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J) ──────────────────────────────────╮
+│ ID              Source   Text                                                             │
+│ ──────────────  ───────  ──────────────────────────────────────────────────────           │
+│ inv_01HXM9A1B  global   All public APIs must maintain backward compatibility              │
+│ inv_01HXM9A2C  project  All endpoints must validate auth tokens                           │
+│ inv_01HXM9G3A  plan     All database queries must use parameterized statements            │
 ╰───────────────────────────────────────────────────────────────────────────────────────────╯
 
 │ Conflicts Resolved: 1                                                              │
 │   Global "Use shared DB pool" overridden by plan "All database queries must use    │
 │   parameterized statements"                                                         │
 
-✓ OK 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
+✓ OK 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
##### agents invariant remove @@ -3989,17 +4744,17 @@ Remove an invariant by ID. The invariant is removed from whichever scope it was **Examples** 

-$ agents invariant remove inv_01HXM9A1C
+$ agents invariant remove inv_01HXM9A1C
 
 Remove invariant inv_01HXM9A1C ("Payment processing must be idempotent", scope: global)? [y/N]: y
 
 ╭─ Invariant Removed ──────────────────────────────────────────────╮
-│ Removed: Payment processing must be idempotent                 │
-│ Scope: global                                                  │
-│ ID: inv_01HXM9A1C                                             │
+│ Removed: Payment processing must be idempotent                   │
+│ Scope: global                                                    │
+│ ID: inv_01HXM9A1C                                                │
 ╰──────────────────────────────────────────────────────────────────╯
 
-✓ OK Invariant removed
+✓ OK Invariant removed
## Core Concepts @@ -4035,7 +4790,7 @@ This four-stage model is explicitly called out as the new architecture replacing | Execute | `apply` | Applied | **Important behavioral rule:** -CleverAgents must support multiple "automation levels" that can automatically progress through these verbs without the user explicitly issuing them, but the verbs remain the conceptual contract. +CleverAgents uses **automation profiles** to control which of these phase transitions happen automatically. The profile determines whether each transition requires explicit user action or proceeds autonomously, but the verbs remain the conceptual contract. #### Plan States (Per Phase) @@ -4110,67 +4865,67 @@ At each level, only the relevant context is loaded. The persistent decision grap In the actor definition for the execution actor, tool nodes can directly invoke registered tools to trigger child plans. The `local/create-subplan` tool is independently registered and referenced by name in the actor graph node. During execution, `subplan_spawn` decisions are realized as actual child plans, and `subplan_parallel_spawn` groups trigger concurrent spawning of all enclosed child plans. -```yaml -# Example: Execution actor with subplan spawning capability. -# The graph uses a tool node referencing a named registered tool. -actors: - code_executor: - type: graph - config: - actor: anthropic/claude-3-opus - skills: +

+# Example: Execution actor with subplan spawning capability.
+# The graph uses a tool node referencing a named registered tool.
+actors:
+  code_executor:
+    type: graph
+    config:
+      actor: anthropic/claude-3-opus
+    skills:
       - local/plan-tools          # Skill containing create_subplan for LLM tool-calling
       - local/file-ops
-    routes:
-      execute_workflow:
-        nodes:
-          - name: spawn_test_subplan
-            type: tool
-            tool: local/create-subplan   # Named tool from Tool Registry
-```
+    routes:
+      execute_workflow:
+        nodes:
+          - name: spawn_test_subplan
+            type: tool
+            tool: local/create-subplan # Named tool from Tool Registry
+
The `local/create-subplan` tool is independently registered via its own YAML configuration file: -```yaml -# File: tools/create-subplan.yaml -cleveragents: - version: "3.0" +

+# File: tools/create-subplan.yaml
+cleveragents:
+  version: "3.0"
 
-tool:
-  name: local/create-subplan
-  description: "Spawn a subplan for a given action"
-  source: custom
+tool:
+  name: local/create-subplan
+  description: "Spawn a subplan for a given action"
+  source: custom
 
-  input_schema:
-    type: object
-    properties:
-      action: { type: string }
-      target_files: { type: array, items: { type: string } }
-    required: [action]
+  input_schema:
+    type: object
+    properties:
+      action: { type: string }
+      target_files: { type: array, items: { type: string } }
+    required: [action]
 
-  capability:
-    writes: true
-    checkpointable: false
-    side_effects: [spawn_subplan]
+  capability:
+    writes: true
+    checkpointable: false
+    side_effects: [spawn_subplan]
 
-  code: |
+  code: |
     subplan = ctx.spawn_subplan(
-        action=params["action"],
-        target_files=params.get("target_files", [])
+        action=params["action"],
+        target_files=params.get("target_files", [])
     )
-    return {"subplan_id": subplan.id}
-```
+    return {"subplan_id": subplan.id}
+
The `local/plan-tools` skill references this tool (and others) by name: -```yaml -# File: skills/plan-tools.yaml -skill: - name: local/plan-tools - description: "Tools for spawning and managing subplans" - tools: +

+# File: skills/plan-tools.yaml
+skill:
+  name: local/plan-tools
+  description: "Tools for spawning and managing subplans"
+  tools:
     - local/create-subplan
-```
+
##### Child Plan Execution Modes @@ -4225,19 +4980,20 @@ For example: ##### Decision Making Based on Autonomy Level -Who makes decisions depends on the plan's **automation level**: +Who makes decisions depends on the plan's **automation profile**: -| Automation Level | Who Makes Decisions | -|-----------------|---------------------| -| **Manual** | User is prompted for each decision point | -| **Review-before-apply** | Actor makes decisions automatically during Strategize, user reviews before Apply | -| **Full automation** | Actor makes all decisions automatically | +| Profile Flag | Who Makes Decisions | +|-------------|---------------------| +| `auto_decisions_strategize = false` | User is prompted for each decision point during Strategize | +| `auto_decisions_strategize = true` | Strategy actor makes decisions autonomously, records reasoning | +| `auto_decisions_execute = false` | User is prompted for each decision point during Execute | +| `auto_decisions_execute = true` | Execution actor makes decisions autonomously | When **automation allows automatic decisions**, the strategy actor uses its best judgment based on context, and records its reasoning in the decision's `rationale` field. When **user input is required**, the system pauses and prompts the user: -``` +

 Decision required: Which modules should be prioritized for test coverage?
 
 Options identified by the strategy actor:
@@ -4246,7 +5002,7 @@ Options identified by the strategy actor:
   3. user module (currently 71% coverage, medium risk)
 
 Your choice (or provide custom guidance): _
-```
+
##### The Prompt as the Root Decision @@ -4262,33 +5018,33 @@ This is important because: 4. **Unified correction mechanism**: Since the prompt, invariants, and all other decisions are part of the same tree, correcting any of them uses the same `agents plan correct` command. -```text +

 Plan: 01KH29QDEE6DZTXKWNKCV8VP0F
-├── [prompt_definition] "Increase test coverage to 85% for the whole project."
-├── [invariant_enforced] "Prioritize all functionality related to financial transactions and user management"
-├── [invariant_enforced] "All API calls over TCP must be mocked"
-├── [strategy_choice] "Prioritize auth and payment modules, implement them in parallel before the rest"
-├── [subplan_parallel_spawn] "Implement auth and payment modules, in parallel"
-│   ├── [subplan_spawn] "Write tests for auth module"
+├── [prompt_definition] "Increase test coverage to 85% for the whole project."
+├── [invariant_enforced] "Prioritize all functionality related to financial transactions and user management"
+├── [invariant_enforced] "All API calls over TCP must be mocked"
+├── [strategy_choice] "Prioritize auth and payment modules, implement them in parallel before the rest"
+├── [subplan_parallel_spawn] "Implement auth and payment modules, in parallel"
+│   ├── [subplan_spawn] "Write tests for auth module"
 │   │   └── Plan: 01KH29R8WPKPBHRY7Q0NA9XW86
-│   │       ├── [prompt_definition] "Write unit tests for auth module using mocks for the remote API calls"
-│   │       ├── [implementation_choice] "Test login flow first"
+│   │       ├── [prompt_definition] "Write unit tests for auth module using mocks for the remote API calls"
+│   │       ├── [implementation_choice] "Test login flow first"
 │   │       └── ...
-│   └── [subplan_spawn] "Write tests for payment module"
+│   └── [subplan_spawn] "Write tests for payment module"
 │       └── Plan: 01KH29RN2YKSXMTBDG82AKRHRA
-│           ├── [prompt_definition] "Write unit tests for payment module using"
+│           ├── [prompt_definition] "Write unit tests for payment module using"
 │           └── ...
-└── [subplan_parallel_spawn] "Write tests for all modules except the auth and payment modules"
+└── [subplan_parallel_spawn] "Write tests for all modules except the auth and payment modules"
     └──  ...
-```
+
##### Correcting Decisions (Including Prompts) All corrections use the same unified command: -```bash -agents plan correct --mode= --guidance "" -``` +

+agents plan correct <decision_id> --mode=<mode> --guidance "<corrected decision text>"
+
**Parameters:** * ``: The ULID of the decision to correct @@ -4297,33 +5053,33 @@ agents plan correct --mode= --guidance "

+# Correct a strategy choice
+agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=revert \
+  --guidance "Prioritize the payment module first, not auth, due to upcoming deadline"
 
-# Correct the root prompt to be more specific
-agents plan tree 
-# Shows: [prompt_definition] id=01ARZ3NDEKTSV4RRFFQ69G5FAV "Increase test coverage to 85%"
+# Correct the root prompt to be more specific
+agents plan tree <plan_id>
+# Shows: [prompt_definition] id=01ARZ3NDEKTSV4RRFFQ69G5FAV "Increase test coverage to 85%"
 
-agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=revert \
-  --guidance "Increase test coverage to 85%, prioritizing auth and payment modules. Use mocks for database tests, not integration tests."
+agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=revert \
+  --guidance "Increase test coverage to 85%, prioritizing auth and payment modules. Use mocks for database tests, not integration tests."
 
-# Correct a subplan's prompt (originally created by parent plan)
-agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW --mode=revert \
-  --guidance "Write unit tests for auth module, focusing on edge cases for token expiration"
+# Correct a subplan's prompt (originally created by parent plan)
+agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW --mode=revert \
+  --guidance "Write unit tests for auth module, focusing on edge cases for token expiration"
 
-# Append a fix rather than rewriting history
-agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=append \
-  --guidance "The previous approach missed error handling tests - add comprehensive error path coverage"
+# Append a fix rather than rewriting history
+agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=append \
+  --guidance "The previous approach missed error handling tests - add comprehensive error path coverage"
 
-# Remove an invariant that shouldn't apply
-agents plan correct 01CRZ5QEHMVUX6TTHR81I7HCX --mode=revert \
-  --guidance "Remove this invariant - TCP mocking is not needed for this module since it has no network calls"
+# Remove an invariant that shouldn't apply
+agents plan correct 01CRZ5QEHMVUX6TTHR81I7HCX --mode=revert \
+  --guidance "Remove this invariant - TCP mocking is not needed for this module since it has no network calls"
 
-# Add a missing invariant to the plan
-agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
-```
+# Add a missing invariant to the plan
+agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
+
**Note:** CLI commands should not require interactive input. The `--guidance` parameter provides the correction inline. @@ -4344,16 +5100,16 @@ Because the prompt is part of the decision tree, the system automatically knows ##### Decision Record Structure -```yaml -Decision: - # Identity - decision_id: ULID # Unique identifier - plan_id: ULID # Parent plan this decision belongs to - parent_decision_id: ULID | null # Parent decision (for tree structure) - sequence_number: int # Order within the plan's decisions +

+Decision:
+  # Identity
+  decision_id: ULID # Unique identifier
+  plan_id: ULID # Parent plan this decision belongs to
+  parent_decision_id: ULID | null # Parent decision (for tree structure)
+  sequence_number: int # Order within the plan's decisions
   
-  # Classification
-  decision_type: enum
+  # Classification
+  decision_type: enum
     - prompt_definition         # The prompt/description for this plan (root decision)
     - invariant_enforced        # An invariant (from global, project, action, or plan scope) applicable to this plan, added as a constraint
     - strategy_choice           # High-level approach decision during Strategize
@@ -4366,45 +5122,45 @@ Decision:
     - validation_response       # Response to validation failure
     - user_intervention         # User provided guidance/correction
   
-  # The Decision Itself
-  question: str                        # What question was being answered
-  chosen_option: str                   # What was decided
-  alternatives_considered: list[str]   # Other options that were evaluated
-  confidence_score: float | null       # 0.0-1.0 if the actor provided confidence
+  # The Decision Itself
+  question: str # What question was being answered
+  chosen_option: str # What was decided
+  alternatives_considered: list[str] # Other options that were evaluated
+  confidence_score: float | null # 0.0-1.0 if the actor provided confidence
   
-  # Context Snapshot (for replay)
-  context_snapshot:
-    hot_context_hash: str              # Cryptographic hash of the exact context
-    hot_context_ref: str               # Pointer to the full stored snapshot
-    relevant_resources: list[ResourceRef]  # Every file/symbol that influenced this decision
-    actor_state_ref: str               # Complete LangGraph checkpoint
+  # Context Snapshot (for replay)
+  context_snapshot:
+    hot_context_hash: str # Cryptographic hash of the exact context
+    hot_context_ref: str # Pointer to the full stored snapshot
+    relevant_resources: list[ResourceRef] # Every file/symbol that influenced this decision
+    actor_state_ref: str # Complete LangGraph checkpoint
     
-  # When the system decides "refactor the authentication module to use async patterns," 
-  # it permanently records:
-  # - Which files were examined to make that decision
-  # - What symbols and dependencies were traced
-  # - The exact code state that was analyzed
-  # - The reasoning chain that led to this choice
-  # - Alternative approaches that were considered but rejected
+  # When the system decides "refactor the authentication module to use async patterns," 
+  # it permanently records:
+  # - Which files were examined to make that decision
+  # - What symbols and dependencies were traced
+  # - The exact code state that was analyzed
+  # - The reasoning chain that led to this choice
+  # - Alternative approaches that were considered but rejected
   
-  # Rationale
-  rationale: str                       # Why this option was chosen
-  actor_reasoning: str | null          # Raw LLM reasoning if available
+  # Rationale
+  rationale: str # Why this option was chosen
+  actor_reasoning: str | null # Raw LLM reasoning if available
   
-  # Downstream Impact (populated during Execute phase)
-  downstream_decision_ids: list[ULID]  # Decisions that depend on this one
-  downstream_plan_ids: list[ULID]      # Child plans spawned because of this decision
-  artifacts_produced: list[ArtifactRef] # Files/outputs created under this decision
+  # Downstream Impact (populated during Execute phase)
+  downstream_decision_ids: list[ULID] # Decisions that depend on this one
+  downstream_plan_ids: list[ULID] # Child plans spawned because of this decision
+  artifacts_produced: list[ArtifactRef] # Files/outputs created under this decision
   
-  # Timestamps
-  created_at: datetime
+  # Timestamps
+  created_at: datetime
   
-  # Correction Metadata
-  is_correction: bool                  # Was this decision a correction of another?
-  corrects_decision_id: ULID | null    # If correction, which decision was replaced
-  correction_reason: str | null        # Why the correction was made
-  superseded_by: ULID | null           # If this decision was later corrected
-```
+  # Correction Metadata
+  is_correction: bool # Was this decision a correction of another?
+  corrects_decision_id: ULID | null # If correction, which decision was replaced
+  correction_reason: str | null # Why the correction was made
+  superseded_by: ULID | null # If this decision was later corrected
+
##### Decision Timing @@ -4416,64 +5172,64 @@ Decision: ##### Decision Tree Storage Schema -```sql --- Core decision table -CREATE TABLE decisions ( - decision_id TEXT PRIMARY KEY, -- ULID - plan_id TEXT NOT NULL, - parent_decision_id TEXT, - sequence_number INTEGER NOT NULL, - decision_type TEXT NOT NULL, -- prompt_definition, invariant_enforced, strategy_choice, - -- implementation_choice, resource_selection, subplan_spawn, - -- subplan_parallel_spawn, tool_invocation, error_recovery, - -- validation_response, user_intervention - question TEXT, - chosen_option TEXT NOT NULL, - alternatives_considered TEXT, -- JSON array - confidence_score REAL, - rationale TEXT, - actor_reasoning TEXT, - context_snapshot TEXT NOT NULL, -- JSON blob - is_correction BOOLEAN DEFAULT FALSE, - corrects_decision_id TEXT, - correction_reason TEXT, - superseded_by TEXT, - created_at TEXT NOT NULL, +

+-- Core decision table
+CREATE TABLE decisions (
+    decision_id TEXT PRIMARY KEY,      -- ULID
+    plan_id TEXT NOT NULL,
+    parent_decision_id TEXT,
+    sequence_number INTEGER NOT NULL,
+    decision_type TEXT NOT NULL,        -- prompt_definition, invariant_enforced, strategy_choice,
+                                       -- implementation_choice, resource_selection, subplan_spawn,
+                                       -- subplan_parallel_spawn, tool_invocation, error_recovery,
+                                       -- validation_response, user_intervention
+    question TEXT,
+    chosen_option TEXT NOT NULL,
+    alternatives_considered TEXT,      -- JSON array
+    confidence_score REAL,
+    rationale TEXT,
+    actor_reasoning TEXT,
+    context_snapshot TEXT NOT NULL,    -- JSON blob
+    is_correction BOOLEAN DEFAULT FALSE,
+    corrects_decision_id TEXT,
+    correction_reason TEXT,
+    superseded_by TEXT,
+    created_at TEXT NOT NULL,
     
-    FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
-    FOREIGN KEY (parent_decision_id) REFERENCES decisions(decision_id),
-    FOREIGN KEY (corrects_decision_id) REFERENCES decisions(decision_id),
-    FOREIGN KEY (superseded_by) REFERENCES decisions(decision_id)
+    FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
+    FOREIGN KEY (parent_decision_id) REFERENCES decisions(decision_id),
+    FOREIGN KEY (corrects_decision_id) REFERENCES decisions(decision_id),
+    FOREIGN KEY (superseded_by) REFERENCES decisions(decision_id)
 );
 
--- Downstream relationships (many-to-many for DAG)
-CREATE TABLE decision_dependencies (
-    upstream_decision_id TEXT NOT NULL,
-    downstream_decision_id TEXT NOT NULL,
-    dependency_type TEXT NOT NULL,     -- 'decision', 'plan', 'artifact'
-    downstream_ref TEXT NOT NULL,      -- The actual ID of decision/plan/artifact
+-- Downstream relationships (many-to-many for DAG)
+CREATE TABLE decision_dependencies (
+    upstream_decision_id TEXT NOT NULL,
+    downstream_decision_id TEXT NOT NULL,
+    dependency_type TEXT NOT NULL,     -- 'decision', 'plan', 'artifact'
+    downstream_ref TEXT NOT NULL,      -- The actual ID of decision/plan/artifact
     
-    PRIMARY KEY (upstream_decision_id, downstream_decision_id, downstream_ref),
-    FOREIGN KEY (upstream_decision_id) REFERENCES decisions(decision_id)
+    PRIMARY KEY (upstream_decision_id, downstream_decision_id, downstream_ref),
+    FOREIGN KEY (upstream_decision_id) REFERENCES decisions(decision_id)
 );
 
--- Correction history
-CREATE TABLE correction_attempts (
-    attempt_id TEXT PRIMARY KEY,       -- ULID
-    plan_id TEXT NOT NULL,
-    original_decision_id TEXT NOT NULL,
-    new_decision_id TEXT,
-    original_subtree_snapshot TEXT,    -- Reference to archived state
-    correction_reason TEXT,
-    status TEXT NOT NULL,              -- 'pending', 'executing', 'completed', 'failed'
-    created_at TEXT NOT NULL,
-    completed_at TEXT,
+-- Correction history
+CREATE TABLE correction_attempts (
+    attempt_id TEXT PRIMARY KEY,       -- ULID
+    plan_id TEXT NOT NULL,
+    original_decision_id TEXT NOT NULL,
+    new_decision_id TEXT,
+    original_subtree_snapshot TEXT,    -- Reference to archived state
+    correction_reason TEXT,
+    status TEXT NOT NULL,              -- 'pending', 'executing', 'completed', 'failed'
+    created_at TEXT NOT NULL,
+    completed_at TEXT,
     
-    FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
-    FOREIGN KEY (original_decision_id) REFERENCES decisions(decision_id),
-    FOREIGN KEY (new_decision_id) REFERENCES decisions(decision_id)
+    FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
+    FOREIGN KEY (original_decision_id) REFERENCES decisions(decision_id),
+    FOREIGN KEY (new_decision_id) REFERENCES decisions(decision_id)
 );
-```
+
### Action @@ -4481,7 +5237,7 @@ CREATE TABLE correction_attempts ( An **action** is a reusable plan template that is not associated with any projects yet. -**Important: Actions are created via CLI commands, NOT YAML configuration files.** YAML configuration files are only used to define actors. +**Actions are created via CLI commands with a required `--config` YAML file** that fully defines the action. Any CLI options supplied alongside the config file act as optional overrides for values in the YAML. Examples: @@ -4496,27 +5252,34 @@ An action is the first stage of a plan — before it is used. Because of this, * #### Action Creation (CLI) -Actions are created using the CLI: +Actions are created using the CLI. There are two modes of creation: -```bash -agents action create \ - --name "local/code-coverage" \ - --description "Increase test coverage to target percentage" \ - --strategy-actor "local/coverage-strategist" \ - --execution-actor "local/coverage-executor" \ - --definition-of-done "Coverage reaches target percentage; All new tests pass" \ - --arg "target_coverage_percent:int:required:Target coverage percentage (0-100)" \ - --arg "test_framework:str:optional:Test framework to use (pytest, unittest, etc.)" \ - --invariant "Test files must not import production secrets" \ - --invariant "Coverage must not decrease for existing modules" \ - --invariant-actor "local/coverage-reconciler" -``` +**1. Config-only (all values from YAML):** + +

+agents action create "local/code-coverage" \
+  --config ./actions/code-coverage.yaml
+
+ +**2. Config with CLI overrides:** + +

+agents action create "local/code-coverage" \
+  --config ./actions/code-coverage.yaml \
+  --execution-actor "local/fast-executor" \
+  --available
+
+ +In both modes, the YAML file provides the full action definition. Any CLI options provided alongside `--config` override the corresponding values from the file. **Required parameters:** -* `--name`: Namespaced name (e.g., `local/code-coverage`, `myorg/deploy-action`) -* `--strategy-actor`: Name of the actor to use for Strategize phase -* `--execution-actor`: Name of the actor to use for Execute phase -* `--definition-of-done`: Free-form text describing completion criteria +* `--config`: YAML configuration file that fully defines the action (strategy-actor, execution-actor, definition-of-done, etc.) + +**Optional parameters (overrides):** +* `[]`: Namespaced name (positional, e.g., `local/code-coverage`, `myorg/deploy-action`). When provided, overrides the name in the config file. +* `--strategy-actor`: Override the Strategize actor from config +* `--execution-actor`: Override the Execution actor from config +* `--definition-of-done`: Override the completion criteria from config **Optional parameters:** * `--description`: Human-readable description @@ -4608,16 +5371,9 @@ Example: * `target_coverage_percent`: integer 0–100 -##### 9) `safety_profile` (recommended addition) +##### 9) `automation_profile` -A policy bundle that can be applied to enforce safe execution: - -* allowed skill categories, -* require checkpoints, -* require sandbox, -* require human approval at Apply. - -This relates to the "checkpointable tools + sandbox" approach for safe writing. +The resolved automation profile name for this plan (e.g., `trusted`, `autonomous`, `local/careful-auto`). Determined at `plan use` time using the profile precedence rules (plan > action > project > global). Once set, it is locked to the plan. ### Strategy (Strategize Phase) @@ -4625,44 +5381,44 @@ This relates to the "checkpointable tools + sandbox" approach for safe writing. The `use` command transitions an Action into the Strategize phase by applying it to one or more projects: -```bash -# Basic usage -agents plan use local/code-coverage --project my-api-service +

+# Basic usage
+agents plan use local/code-coverage my-api-service
 
-# Multiple projects
-agents plan use local/schema-update \
-  --project api-service \
-  --project web-frontend \
-  --project mobile-app
+# Multiple projects
+agents plan use local/schema-update \
+  api-service \
+  web-frontend \
+  mobile-app
 
-# With action arguments
-agents plan use local/code-coverage \
-  --project my-api-service \
-  --arg target_coverage_percent=85 \
-  --arg test_framework=pytest
+# With action arguments
+agents plan use local/code-coverage \
+  my-api-service \
+  --arg target_coverage_percent=85 \
+  --arg test_framework=pytest
 
-# With explicit automation level
-agents plan use local/deploy-action \
-  --project staging-env \
-  --automation-level manual
+# With explicit automation profile
+agents plan use local/deploy-action \
+  staging-env \
+  --automation-profile manual
 
-# With invariants attached at use time
-agents plan use local/code-coverage \
-  --project my-api-service \
-  --arg target_coverage_percent=85 \
-  --invariant "All API calls over TCP must be mocked" \
-  --invariant "Do not modify the payments module"
-```
+# With invariants attached at use time
+agents plan use local/code-coverage \
+  my-api-service \
+  --arg target_coverage_percent=85 \
+  --invariant "All API calls over TCP must be mocked" \
+  --invariant "Do not modify the payments module"
+
**Parameters:** -* `--project`: Project to apply the action to (can be repeated for multi-project plans) +* ``: Project to apply the action to (positional, can be repeated for multi-project plans) * `--arg`: Action argument values (format: `name=value`) -* `--automation-level`: Override automation level for this plan +* `--automation-profile`: Override automation profile for this plan * `--invariant`: Invariant to attach to the created plan (can be repeated). These are added as plan-level invariants in addition to any inherited from the action, project, or global scope. When the action is used: 1. A new plan is created with a unique ULID -2. The plan's automation level is determined (plan > session > global) +2. The plan's automation profile is resolved (plan > action > project > global precedence) 3. Any invariants from the action are carried forward as plan-level invariants, combined with any `--invariant` flags provided 4. The plan enters the **Strategize** phase 5. The **Invariant Reconciliation Actor** computes the effective invariant view (resolving conflicts using plan > project > global precedence) @@ -4685,27 +5441,27 @@ This "architect vs coder" separation is explicitly described as a core motivatio **Resource-aware dependency analysis**: During the Strategize phase, the strategy actor employs specialized mechanisms to compute precise dependency closures: -```python -# Pseudocode of what happens inside a strategy actor -def compute_closure_for_refactoring(target_module): +

+# Pseudocode of what happens inside a strategy actor
+def compute_closure_for_refactoring(target_module):
     closure = ResourceClosure()
     
-    # Direct file dependencies
+    # Direct file dependencies
     closure.add_files(find_imports(target_module))
     closure.add_files(find_includes(target_module))
     
-    # Symbol dependencies
-    for symbol in extract_exported_symbols(target_module):
-        closure.add_files(find_symbol_usage(symbol, scope='project'))
+    # Symbol dependencies
+    for symbol in extract_exported_symbols(target_module):
+        closure.add_files(find_symbol_usage(symbol, scope='project'))
     
-    # Test dependencies
+    # Test dependencies
     closure.add_files(find_tests_for_module(target_module))
     
-    # Build system dependencies
+    # Build system dependencies
     closure.add_files(find_build_references(target_module))
     
-    return closure
-```
+    return closure
+
The system leverages several key insights: - **Modular boundaries exist**: Even in legacy codebases, there are natural boundaries @@ -4782,15 +5538,12 @@ And produces estimates for: **Implementation**: Similar to how there's a `strategy_actor` and `execution_actor` for each action, there can be an optional `estimation_actor` whose entire job is cost/risk estimation. This actor runs after Strategize completes (before Execute) and its output is informational only. -```bash -# Example: Action with estimation actor -agents action create \ - --name "local/expensive-refactor" \ - --strategy-actor "local/refactor-planner" \ - --execution-actor "local/refactor-executor" \ - --estimation-actor "local/cost-estimator" \ - --definition-of-done "All code refactored according to plan" -``` +

+# Example: Action with estimation actor (estimation-actor overrides config)
+agents action create --config ./actions/expensive-refactor.yaml \
+  --estimation-actor "local/cost-estimator" \
+  "local/expensive-refactor"
+
This becomes critical in server/multi-user usage and cost controls. @@ -4899,37 +5652,37 @@ When a plan accesses multiple resources: **Complete isolation during execution prevents compound errors**: Each plan executes in its own sandbox, which means: -``` +

 Plan A (refactoring auth module):
 - Sandbox A1: Contains only auth/*.cpp, auth_tests/*.cpp
-- Cannot see Plan B's intermediate states
-- Cannot accidentally depend on Plan B's half-done work
+- Cannot see Plan B's intermediate states
+- Cannot accidentally depend on Plan B's half-done work
 
 Plan B (updating API endpoints):
 - Sandbox B1: Contains only api/*.cpp, api_tests/*.cpp  
 - Makes changes assuming current auth interface
-- Protected from Plan A's intermediate refactoring
-```
+- Protected from Plan A's intermediate refactoring
+
**Hierarchical merge resolution**: When child plans complete, the parent plan performs intelligent merging: -```python -def merge_subplan_results(subplan_results): - # Group by resource type +

+def merge_subplan_results(subplan_results):
+    # Group by resource type
     by_resource = group_by_resource_type(subplan_results)
     
-    # Apply resource-specific merge strategies
-    for resource_type, changes in by_resource:
-        if resource_type == 'git-checkout':
-            merge_git_changes(changes)  # Three-way merge
-        elif resource_type == 'fs-mount':
-            merge_fs_changes(changes)   # Copy-on-write reconciliation
-        elif resource_type.startswith('database'):
-            merge_db_changes(changes)   # Sequential application
+    # Apply resource-specific merge strategies
+    for resource_type, changes in by_resource:
+        if resource_type == 'git-checkout':
+            merge_git_changes(changes)  # Three-way merge
+        elif resource_type == 'fs-mount':
+            merge_fs_changes(changes)   # Copy-on-write reconciliation
+        elif resource_type.startswith('database'):
+            merge_db_changes(changes)   # Sequential application
     
-    # Validate merged state
+    # Validate merged state
     run_integration_tests()
-```
+
#### Execution Data Model @@ -5106,54 +5859,54 @@ CleverAgents provides multiple layers of proactive error prevention that catch s #### Layer 1: Decision-time Validation During Strategize Every decision includes semantic validation: -```yaml -Decision: Refactor payment module to async -alternatives_considered: - - "Convert to async/await patterns" (chosen) - - "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem) - - "Keep synchronous with timeout" (rejected: doesn't solve core latency issue) -confidence_score: 0.85 -validation_performed: +

+Decision: Refactor payment module to async
+alternatives_considered:
+  - "Convert to async/await patterns" (chosen)
+  - "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem)
+  - "Keep synchronous with timeout" (rejected: doesn't solve core latency issue)
+confidence_score: 0.85
+validation_performed:
   - Checked all payment API consumers can handle async
   - Verified database driver supports async operations
   - Confirmed no regulatory requirement for sync processing
-```
+
#### Layer 2: Execution-time Semantic Guards The execution actor uses a tool node that references the independently registered `local/validate-api-compat` tool: -```yaml -# Actor graph uses a named tool node for semantic validation -actors: - code_executor: - type: graph - skills: +

+# Actor graph uses a named tool node for semantic validation
+actors:
+  code_executor:
+    type: graph
+    skills:
       - local/semantic-validators    # Skill containing validation tools for LLM tool-calling
-    nodes:
-      - name: semantic_validator
-        type: tool
-        tool: local/validate-api-compat   # Named tool from Tool Registry
-```
+    nodes:
+      - name: semantic_validator
+        type: tool
+        tool: local/validate-api-compat # Named tool from Tool Registry
+
The `local/validate-api-compat` tool is independently registered via its own YAML: -```yaml -# File: tools/validate-api-compat.yaml -cleveragents: - version: "3.0" +

+# File: tools/validate-api-compat.yaml
+cleveragents:
+  version: "3.0"
 
-tool:
-  name: local/validate-api-compat
-  description: "Check for breaking API changes and attempt auto-migration"
-  source: custom
+tool:
+  name: local/validate-api-compat
+  description: "Check for breaking API changes and attempt auto-migration"
+  source: custom
 
-  capability:
-    writes: true
-    checkpointable: true
+  capability:
+    writes: true
+    checkpointable: true
 
-  code: |
-    # Not just syntax checking - semantic validation
+  code: |
+    # Not just syntax checking - semantic validation
     old_api = extract_api_signature(previous_version)
     new_api = extract_api_signature(current_version)
     
@@ -5164,24 +5917,24 @@ tool:
         
         if can_auto_migrate(affected_consumers, migration_plan):
             apply_migration(migration_plan)
-        else:
+        else:
             raise SemanticError(
-                "Breaking API changes require manual review",
+                "Breaking API changes require manual review",
                 changes=breaking_changes,
                 affected=affected_consumers
             )
-```
+
The `local/semantic-validators` skill references this tool by name: -```yaml -# File: skills/semantic-validators.yaml -skill: - name: local/semantic-validators - description: "Semantic validation tools for API compatibility and code invariants" - tools: +

+# File: skills/semantic-validators.yaml
+skill:
+  name: local/semantic-validators
+  description: "Semantic validation tools for API compatibility and code invariants"
+  tools:
     - local/validate-api-compat
-```
+
#### Layer 3: Invariant Enforcement @@ -5200,7 +5953,7 @@ Invariants are named constraints that guide and constrain plan execution. They c Conflict resolution is performed by the **Invariant Reconciliation Actor** — a dedicated actor responsible for comparing invariants across scopes, identifying conflicts, and producing the final **effective invariant view** for a plan. The Invariant Reconciliation Actor is set at three levels via `--invariant-actor`: 1. **Global config**: Set via `agents config set invariant-actor `. Defines the default Invariant Reconciliation Actor used when neither the project nor the plan specifies one. -2. **Project-level**: Set via `--invariant-actor` on `agents project create` (or later via `agents config set --project`). If a project defines an Invariant Reconciliation Actor, it is used to reconcile that project's invariants against global invariants. +2. **Project-level**: Set via `--invariant-actor` on `agents project create`. If a project defines an Invariant Reconciliation Actor, it is used to reconcile that project's invariants against global invariants. 3. **Plan-level**: Set via `--invariant-actor` on `agents action create` (carried forward when the action is used) or `agents plan use` (which overrides whatever was set on the action). If a plan has an Invariant Reconciliation Actor, it reconciles invariants from all scopes (plan, project, and global) and produces the final effective view for that plan. The lookup order is: plan → project → global config. The first Invariant Reconciliation Actor found is used. @@ -5220,86 +5973,86 @@ Each effective invariant is then recorded as an `invariant_enforced` decision in * **Remove**: Remove an existing invariant from the plan's decision tree (the invariant remains defined at its scope but is no longer enforced for this plan). * **Add**: Add a new invariant to the plan. When adding, the user can select from invariants already accessible to the plan (those defined at the plan, action, project, or global scope), or provide free-form text to create a new ad-hoc invariant. -```bash -# Add invariants at different scopes -agents invariant add --global "All public APIs must maintain backward compatibility" -agents invariant add --global "Payment processing must be idempotent" -agents invariant add --project local/api-service \ - "Database transactions must complete within 5 seconds" -agents invariant add --project local/api-service \ - "Authentication must always use OAuth2" -agents invariant add --plan "All API calls over TCP must be mocked" -agents invariant add --action local/code-coverage "Test files must not import production secrets" +

+# Add invariants at different scopes
+agents invariant add --global "All public APIs must maintain backward compatibility"
+agents invariant add --global "Payment processing must be idempotent"
+agents invariant add --project local/api-service \
+  "Database transactions must complete within 5 seconds"
+agents invariant add --project local/api-service \
+  "Authentication must always use OAuth2"
+agents invariant add --plan <PLAN_ID> "All API calls over TCP must be mocked"
+agents invariant add --action local/code-coverage "Test files must not import production secrets"
 
-# List invariants
-agents invariant list --global
-agents invariant list --project local/api-service
-agents invariant list --plan  --effective   # Shows reconciled view
+# List invariants
+agents invariant list --global
+agents invariant list --project local/api-service
+agents invariant list --plan <PLAN_ID> --effective   # Shows reconciled view
 
-# Remove an invariant
-agents invariant remove 
+# Remove an invariant
+agents invariant remove <INVARIANT_ID>
 
-# Attach invariants at creation time (convenience)
-agents project create --name local/api-service --invariant "All endpoints must validate auth tokens"
-agents action create local/code-coverage --invariant "Test files must not import production secrets" ...
-agents plan use local/code-coverage --project local/api-service --invariant "Mock all network calls"
+# Attach invariants at creation time (convenience)
+agents project create --invariant "All endpoints must validate auth tokens" local/api-service
+agents action create --config ./actions/code-coverage.yaml --invariant "Test files must not import production secrets" local/code-coverage
+agents plan use local/code-coverage local/api-service --invariant "Mock all network calls"
 
-# Correct an invariant decision (remove or replace via standard correction)
-agents plan correct  --mode=revert \
-  --guidance "Remove this invariant - it does not apply to this module"
-```
+# Correct an invariant decision (remove or replace via standard correction)
+agents plan correct <DECISION_ID> --mode=revert \
+  --guidance "Remove this invariant - it does not apply to this module"
+
The system collects, reconciles, and checks invariants: -```python -class InvariantEnforcer: - def compute_effective_invariants(self, plan): - """Compute the effective invariant view for a plan using the Invariant Reconciliation Actor.""" - # 1. Collect raw invariants from all scopes +

+class InvariantEnforcer:
+    def compute_effective_invariants(self, plan):
+        """Compute the effective invariant view for a plan using the Invariant Reconciliation Actor."""
+        # 1. Collect raw invariants from all scopes
         raw = self.collect_all_invariants(plan)
         
-        # 2. Find the Invariant Reconciliation Actor (plan -> project -> global config)
+        # 2. Find the Invariant Reconciliation Actor (plan -> project -> global config)
         reconciler = (
             self.get_plan_invariant_actor(plan)
-            or self.get_project_invariant_actor(plan)
-            or self.get_global_invariant_actor()
+            or self.get_project_invariant_actor(plan)
+            or self.get_global_invariant_actor()
         )
         
-        # 3. Reconcile: apply precedence (plan > project > global), resolve conflicts
-        effective = reconciler.reconcile(raw, precedence=['plan', 'project', 'global'])
-        return effective
+        # 3. Reconcile: apply precedence (plan > project > global), resolve conflicts
+        effective = reconciler.reconcile(raw, precedence=['plan', 'project', 'global'])
+        return effective
     
-    def collect_all_invariants(self, plan):
-        """Collect invariants from all scopes accessible to this plan."""
+    def collect_all_invariants(self, plan):
+        """Collect invariants from all scopes accessible to this plan."""
         invariants = []
         invariants.extend(self.get_global_invariants())
-        for project in plan.projects:
+        for project in plan.projects:
             invariants.extend(self.get_project_invariants(project))
         invariants.extend(self.get_action_invariants(plan.action))
         invariants.extend(self.get_plan_invariants(plan))
-        return invariants
+        return invariants
     
-    def check_invariant_preservation(self, changes, enforced_invariants):
-        """Check that changes respect all enforced invariants."""
-        for invariant in enforced_invariants:
-            if not self.verify_invariant(invariant, changes):
-                return InvariantViolation(invariant, changes)
-        return Success()
-```
+    def check_invariant_preservation(self, changes, enforced_invariants):
+        """Check that changes respect all enforced invariants."""
+        for invariant in enforced_invariants:
+            if not self.verify_invariant(invariant, changes):
+                return InvariantViolation(invariant, changes)
+        return Success()
+
#### Layer 4: Predictive Error Prevention The system learns from past failures: -```yaml +

 Error Pattern Database:
-  - pattern: "Async conversion in payment module"
-    historical_failures:
-      - "Race condition in payment confirmation"
-      - "Timeout handling breaks idempotency"
-    preventive_checks:
-      - "Add explicit transaction boundaries"
-      - "Verify idempotency keys are preserved"
-      - "Check distributed lock acquisition"
-```
+  - pattern: "Async conversion in payment module"
+    historical_failures:
+      - "Race condition in payment confirmation"
+      - "Timeout handling breaks idempotency"
+    preventive_checks:
+      - "Add explicit transaction boundaries"
+      - "Verify idempotency keys are preserved"
+      - "Check distributed lock acquisition"
+
### Applied (Apply Phase) @@ -5324,7 +6077,7 @@ Apply should perform (configurable) validations before committing: * **Diff review gate** - * If automation level requires review, show: + * If `auto_apply` is `false` in the automation profile, show: * changed files summary, * full diff, @@ -5344,38 +6097,46 @@ Apply should perform (configurable) validations before committing: Validation is **defined by the actor configuration and project settings**, not hardcoded. **Actor-defined validation**: The execution actor's workflow should include validation nodes that: -1. Read project-defined test/validation commands from context -2. Execute appropriate tests based on resource type -3. Handle failures by iterating (attempting fixes) or escalating to user +1. Read project-defined validations from context +2. Execute each validation command and collect results +3. For **required** validations that fail: attempt to fix the issue within the bounds of the strategy, retrying up to the configured limit. If the actor determines it cannot solve the problem within the restrictions given by the strategy phase, it may suggest a change to the decision tree and cause the strategy to be recalculated (whether this happens automatically depends on the automation profile). +4. For **informational** validations that fail: record the result in the plan summary without blocking execution. -**Project-defined validation**: Each project should define how its resources are validated: +**Project-defined validation**: Each project defines its validations via `agents project validation add`: -```bash -# Example: Add validation configuration to a project -agents project set-validation \ - --project my-api-service \ - --resource api-repo \ - --test-command "pytest" \ - --lint-command "ruff check ." \ - --type-check-command "pyright" -``` +

+# Add required validations
+agents project validation add --description "Run unit tests with coverage" \
+  --required --resource repo local/api-service "pytest --cov=src --cov-fail-under=80"
+agents project validation add --description "Lint check" \
+  --required local/api-service "ruff check ."
+agents project validation add --description "Type checking" \
+  --required local/api-service "pyright"
 
-This information is passed into the actor's context, allowing generic actors (not specific to any project) to execute appropriate validation.
+# Add informational (non-blocking) validations
+agents project validation add --description "Check bundle size (advisory)" \
+  --informational local/api-service "node scripts/check-bundle-size.js"
+
+ +This information is passed into the actor's context, allowing generic actors (not specific to any project) to execute appropriate validation. Each validation is run independently, and results are collected into the plan's validation summary. #### Validation Failure Handling -When validation fails: +When a **required** validation fails during Execute: -1. **Iteration**: Actor attempts to fix the issue (e.g., fix failing tests) -2. **Retry limit**: After several failed attempts, iteration stops -3. **User intervention**: User can provide additional instructions -4. **Resume**: Plan continues with new guidance +1. **Self-fix**: The execution actor attempts to fix the issue within the bounds of the strategy (e.g., fix failing tests, correct lint errors). The actor iterates, re-running the validation after each fix attempt. +2. **Retry limit**: After the configured number of failed attempts, self-fix stops. +3. **Strategy recalculation**: If the actor determines it cannot solve the problem within the restrictions given by the strategy phase, it may request a change to the decision tree. This causes the Strategize phase to be re-run for the affected subtree. Whether this happens automatically or requires user approval depends on the automation profile (the `auto_strategy_revision` flag). +4. **User intervention**: If the automation profile requires approval, or if strategy recalculation also fails, the system pauses and requests user guidance. +5. **Resume**: Plan continues with new guidance after user input. + +When an **informational** validation fails, the result is recorded in the plan's validation summary but execution continues normally. The user can prompt the plan with additional instructions when stuck: -```bash -agents plan prompt "Try using mock objects for the database tests" -``` +

+agents plan prompt <plan_id> "Try using mock objects for the database tests"
+
#### Apply Data Model @@ -5383,7 +6144,7 @@ A plan in Apply includes: * `apply_summary` * `applied_artifacts` (final commit hash, merged PR link, file list) -* `final_validation_results` (test outputs, lint outputs) +* `final_validation_results` (per-validation command outputs and pass/fail status) * `approval_record` (if human approvals are required) * `deployment_record` (optional, if apply triggers deploy) @@ -5427,30 +6188,24 @@ This distinction matters for server mode: the server can only execute plans on * #### Project Creation (CLI) -```bash -# Step 1: Register resources independently -agents resource add git-checkout local/api-repo \ - --path /repos/api-service \ - --branch main +

+# Step 1: Register resources independently
+agents resource add git-checkout local/api-repo \
+  --path /repos/api-service \
+  --branch main
 
-agents resource add local/database local/staging-db \
-  --connection-string "postgresql://staging.example.com/mydb" \
-  --read-only
+agents resource add local/database local/staging-db \
+  --connection-string "postgresql://staging.example.com/mydb" \
+  --read-only
 
-# Step 2: Create the project
-agents project create \
-  --name "my-api-service"
+# Step 2: Create the project
+agents project create "my-api-service"
 
-# Step 3: Link resources to the project
-agents project link-resource \
-  --project "my-api-service" \
-  --resource local/api-repo
+# Step 3: Link resources to the project
+agents project link-resource "my-api-service" local/api-repo
 
-agents project link-resource \
-  --project "my-api-service" \
-  --resource local/staging-db \
-  --read-only
-```
+agents project link-resource "my-api-service" local/staging-db --read-only
+
Resources are registered once and can be linked to multiple projects. The resource's type, sandbox strategy, and capabilities are defined by its resource type in the Resource Registry — not by the project. @@ -5597,69 +6352,69 @@ Actors are defined via **YAML configuration files**. Tools and skills are also d Example actor configuration (see `examples/` directory for full examples): -```yaml -cleveragents: - version: "3.0" - default_actor: workflow_controller +

+cleveragents:
+  version: "3.0"
+  default_actor: workflow_controller
 
-actors:
-  # Simple LLM actor with skills referenced by name
-  my_assistant:
-    type: llm
-    config:
-      actor: openai/gpt-4           # Reference to built-in actor
-      temperature: 0.7
-      system_prompt: |
+actors:
+  # Simple LLM actor with skills referenced by name
+  my_assistant:
+    type: llm
+    config:
+      actor: openai/gpt-4 # Reference to built-in actor
+      temperature: 0.7
+      system_prompt: |
         You are a helpful assistant.
         Current task: {{ context.task_description }}
-    skills:
+    skills:
       - local/file-ops               # Grants access to all tools in this skill
       - local/git-ops
 
-  # LLM actor with a composite skill (includes many sub-skills)
-  data_processor:
-    type: llm
-    config:
-      actor: anthropic/claude-3-opus
-      system_prompt: |
+  # LLM actor with a composite skill (includes many sub-skills)
+  data_processor:
+    type: llm
+    config:
+      actor: anthropic/claude-3-opus
+      system_prompt: |
         You are a data processing assistant.
-    skills:
+    skills:
       - local/data-toolkit           # A skill containing analysis + transformation tools
 
-  # Actor referencing another actor
-  reviewer:
-    type: llm
-    config:
-      actor: local/code-reviewer    # Reference to another custom actor
-      memory_enabled: true
-      max_history: 20
-    skills:
+  # Actor referencing another actor
+  reviewer:
+    type: llm
+    config:
+      actor: local/code-reviewer # Reference to another custom actor
+      memory_enabled: true
+      max_history: 20
+    skills:
       - local/file-ops
       - local/git-ops
 
-routes:
-  main_workflow:
-    type: graph
-    entry_point: start
-    nodes:
-      - name: analyze
-        type: agent
-        agent: my_assistant
-      - name: process
-        type: agent
-        agent: data_processor
-    edges:
-      - source: start
-        target: analyze
-      - source: analyze
-        target: process
-      - source: process
-        target: end
+routes:
+  main_workflow:
+    type: graph
+    entry_point: start
+    nodes:
+      - name: analyze
+        type: agent
+        agent: my_assistant
+      - name: process
+        type: agent
+        agent: data_processor
+    edges:
+      - source: start
+        target: analyze
+      - source: analyze
+        target: process
+      - source: process
+        target: end
 
-context:
-  global:
-    task_description: "Default task"
-```
+context:
+  global:
+    task_description: "Default task"
+
#### Actor Arguments @@ -5679,13 +6434,13 @@ For built-in actors (like `openai/gpt-4`), common arguments include: Actors can reference other actors **by name**: -```yaml -actors: - complex_workflow: - type: llm - config: - actor: local/base-analyzer # References another actor -``` +

+actors:
+  complex_workflow:
+    type: llm
+    config:
+      actor: local/base-analyzer # References another actor
+
**Load order matters**: Referenced actors must be loaded/defined before actors that depend on them. @@ -5745,40 +6500,40 @@ This is a powerful simplification: actors provide intelligence, tools provide ca **Tool node with named tool reference:** -```yaml -nodes: - - name: run_db_migrate - type: tool - tool: local/run-migrations # Named tool from Tool Registry - override: # Optional metadata override - capability: - human_approval_required: true +

+nodes:
+  - name: run_db_migrate
+    type: tool
+    tool: local/run-migrations # Named tool from Tool Registry
+    override:                           # Optional metadata override
+      capability:
+        human_approval_required: true
 
-  - name: spawn_tests
-    type: tool
-    tool: local/create-subplan          # Another named tool
-```
+  - name: spawn_tests
+    type: tool
+    tool: local/create-subplan # Another named tool
+
**Tool node with anonymous inline tool:** -```yaml -nodes: - - name: custom_validation - type: tool - anonymous: true - description: "Validate output format before proceeding" - input_schema: - type: object - properties: - data: { type: object } - capability: - read_only: true - code: | - # Inline Python — same format as a named tool YAML body - if not params["data"].get("status"): - raise ValueError("Missing status field") - return {"valid": True} -``` +

+nodes:
+  - name: custom_validation
+    type: tool
+    anonymous: true
+    description: "Validate output format before proceeding"
+    input_schema:
+      type: object
+      properties:
+        data: { type: object }
+    capability:
+      read_only: true
+    code: |
+      # Inline Python — same format as a named tool YAML body
+      if not params["data"].get("status"):
+          raise ValueError("Missing status field")
+      return {"valid": True}
+
### Agent @@ -5858,123 +6613,123 @@ block-beta Tools are defined in their own YAML configuration files, separate from skills and actors. A tool YAML file declares the tool's identity, schema, capability metadata, and implementation: -```yaml -# File: tools/run-migrations.yaml -cleveragents: - version: "3.0" +

+# File: tools/run-migrations.yaml
+cleveragents:
+  version: "3.0"
 
-tool:
-  name: local/run-migrations
-  description: "Run database migrations for the API service"
+tool:
+  name: local/run-migrations
+  description: "Run database migrations for the API service"
 
-  source: custom     # mcp | agent_skill | builtin | custom
+  source: custom # mcp | agent_skill | builtin | custom
 
-  # Resource bindings — what resources this tool needs access to
-  resources:
-    db:
-      type: local/database
-      access: read_write
-      required: true
-      description: "Target database for migrations"
+  # Resource bindings — what resources this tool needs access to
+  resources:
+    db:
+      type: local/database
+      access: read_write
+      required: true
+      description: "Target database for migrations"
 
-  input_schema:
-    type: object
-    properties:
-      direction:
-        type: string
-        enum: [up, down]
-      count:
-        type: integer
-        default: 1
-    required: [direction]
+  input_schema:
+    type: object
+    properties:
+      direction:
+        type: string
+        enum: [up, down]
+      count:
+        type: integer
+        default: 1
+    required: [direction]
 
-  capability:
-    writes: true
-    write_scope:
-      resource_slots: [db]           # References the "db" resource slot
-    checkpointable: true
-    checkpoint_scope: transaction
-    side_effects: [schema_mutation]
+  capability:
+    writes: true
+    write_scope:
+      resource_slots: [db] # References the "db" resource slot
+    checkpointable: true
+    checkpoint_scope: transaction
+    side_effects: [schema_mutation]
 
-  code: |
+  code: |
     import subprocess
-    direction = params["direction"]
-    count = params.get("count", 1)
-    db = ctx.resources["db"]          # Access the bound database resource
+    direction = params["direction"]
+    count = params.get("count", 1)
+    db = ctx.resources["db"]          # Access the bound database resource
     result = subprocess.run(
-        ["alembic", direction, str(count)],
+        ["alembic", direction, str(count)],
         capture_output=True, text=True, cwd=db.sandbox.root
     )
-    return {"stdout": result.stdout, "returncode": result.returncode}
-```
+    return {"stdout": result.stdout, "returncode": result.returncode}
+
Another example — a tool that wraps an MCP server endpoint: -```yaml -# File: tools/create-github-issue.yaml -cleveragents: - version: "3.0" +

+# File: tools/create-github-issue.yaml
+cleveragents:
+  version: "3.0"
 
-tool:
-  name: local/create-github-issue
-  description: "Create a GitHub issue via MCP"
+tool:
+  name: local/create-github-issue
+  description: "Create a GitHub issue via MCP"
 
-  source: mcp
-  mcp_server:
-    command: "npx @anthropic/mcp-github"
-    env:
-      GITHUB_TOKEN: "${GITHUB_TOKEN}"
-    tool_name: create_issue   # The tool name as exposed by the MCP server
+  source: mcp
+  mcp_server:
+    command: "npx @anthropic/mcp-github"
+    env:
+      GITHUB_TOKEN: "${GITHUB_TOKEN}"
+    tool_name: create_issue # The tool name as exposed by the MCP server
 
-  capability:
-    writes: true
-    write_scope: [github:issues]
-    checkpointable: false
-```
+  capability:
+    writes: true
+    write_scope: [github:issues]
+    checkpointable: false
+
And an Agent Skill tool: -```yaml -# File: tools/deploy-staging.yaml -cleveragents: - version: "3.0" +

+# File: tools/deploy-staging.yaml
+cleveragents:
+  version: "3.0"
 
-tool:
-  name: local/deploy-staging
-  description: "Deploy the current branch to the staging environment"
+tool:
+  name: local/deploy-staging
+  description: "Deploy the current branch to the staging environment"
 
-  source: agent_skill
-  agent_skill:
-    path: ./skills/deploy-to-staging
-    sandbox_policy: container
-    allowed_tools: ["Bash(docker:*)", "Bash(kubectl:*)", "Read"]
+  source: agent_skill
+  agent_skill:
+    path: ./skills/deploy-to-staging
+    sandbox_policy: container
+    allowed_tools: ["Bash(docker:*)", "Bash(kubectl:*)", "Read"]
 
-  capability:
-    writes: true
-    checkpointable: false
-    side_effects: [deploy, infrastructure]
-```
+  capability:
+    writes: true
+    checkpointable: false
+    side_effects: [deploy, infrastructure]
+
#### Tool Registration and Management Tools are managed through the `agents tool` CLI commands: -```bash -# Register a new tool from its YAML configuration -agents tool add local/run-migrations --config ./tools/run-migrations.yaml +

+# Register a new tool from its YAML configuration
+agents tool add --config ./tools/run-migrations.yaml local/run-migrations
 
-# Upgrade an existing tool (re-reads the config file, overwrites registration)
-agents tool add local/run-migrations --config ./tools/run-migrations.yaml --upgrade
+# Update an existing tool (re-reads the config file, overwrites registration)
+agents tool add --config ./tools/run-migrations.yaml --update local/run-migrations
 
-# List all registered tools
+# List all registered tools
 agents tool list
 
-# Show details for a tool (schema, capability, references)
+# Show details for a tool (schema, capability, references)
 agents tool show local/run-migrations
 
-# Remove a tool
+# Remove a tool
 agents tool remove local/run-migrations
-```
+
Once registered, a tool is available to be referenced by skills (in their `tools` list) and by actor graphs (as `type: tool` nodes). Tools persist in the database (local or server) and follow the same namespace rules as actors and skills. @@ -5988,45 +6743,45 @@ An **anonymous tool** is an inline tool definition that appears directly in a sk Anonymous tools in a skill YAML: -```yaml -skill: - name: local/my-skill - tools: +

+skill:
+  name: local/my-skill
+  tools:
     - local/run-migrations          # Named tool reference
     - local/validate-api-compat     # Named tool reference
 
-  anonymous_tools:                  # Inline definitions, same format as tool YAML
-    - description: "One-off data cleanup for this project"
-      input_schema:
-        type: object
-        properties:
-          table: { type: string }
-      capability:
-        writes: true
-        checkpointable: true
-      code: |
-        # ... Python code ...
-        return {"cleaned": count}
-```
+  anonymous_tools:                  # Inline definitions, same format as tool YAML
+    - description: "One-off data cleanup for this project"
+      input_schema:
+        type: object
+        properties:
+          table: { type: string }
+      capability:
+        writes: true
+        checkpointable: true
+      code: |
+        # ... Python code ...
+        return {"cleaned": count}
+
Anonymous tools in an actor graph node: -```yaml -nodes: - - name: custom_step - type: tool - anonymous: true - description: "Inline validation specific to this workflow" - input_schema: - type: object - properties: - data: { type: object } - capability: - read_only: true - code: | - # ... Python code ... - return {"valid": True} -``` +

+nodes:
+  - name: custom_step
+    type: tool
+    anonymous: true
+    description: "Inline validation specific to this workflow"
+    input_schema:
+      type: object
+      properties:
+        data: { type: object }
+    capability:
+      read_only: true
+    code: |
+      # ... Python code ...
+      return {"valid": True}
+
The anonymous tool format is intentionally identical to the body of a named tool YAML — this means promoting an anonymous tool to a named, registered tool is a simple copy-paste into its own YAML file and `agents tool add`. @@ -6036,52 +6791,52 @@ When referencing a named tool in a skill or actor graph, its registered metadata **Overriding tool metadata in a skill:** -```yaml -skill: - name: local/strict-devops - tools: - - name: local/run-migrations - override: - capability: - human_approval_required: true # Override: require approval in this skill - write_scope: [database:staging] # Override: restrict scope for this context +

+skill:
+  name: local/strict-devops
+  tools:
+    - name: local/run-migrations
+      override:
+        capability:
+          human_approval_required: true # Override: require approval in this skill
+          write_scope: [database:staging] # Override: restrict scope for this context
 
     - local/validate-api-compat            # No overrides, use as registered
-```
+
**Overriding tool metadata in an actor graph node:** -```yaml -nodes: - - name: safe_migrate - type: tool - tool: local/run-migrations - override: - capability: - human_approval_required: true -``` +

+nodes:
+  - name: safe_migrate
+    type: tool
+    tool: local/run-migrations
+    override:
+      capability:
+        human_approval_required: true
+
**Overriding tool metadata when including a sub-skill:** When a skill includes another skill (importing all its tools), individual tools from the included skill can have their metadata overridden: -```yaml -skill: - name: local/production-ops - includes: - - name: local/devops-toolkit - tool_overrides: - - tool: local/run-migrations - override: - capability: - human_approval_required: true # In this context, require human approval - write_scope: [database:production] +

+skill:
+  name: local/production-ops
+  includes:
+    - name: local/devops-toolkit
+      tool_overrides:
+        - tool: local/run-migrations
+          override:
+            capability:
+              human_approval_required: true # In this context, require human approval
+              write_scope: [database:production]
 
-        - tool: local/create-github-issue
-          override:
-            capability:
-              required_permissions: [org:write]  # Stricter permissions in this context
-```
+        - tool: local/create-github-issue
+          override:
+            capability:
+              required_permissions: [org:write] # Stricter permissions in this context
+
Override rules: 1. Overrides are **shallow-merged** — only the specified fields are replaced; unspecified fields retain their registered values. @@ -6105,59 +6860,59 @@ A tool declares one or more **resource slots** in its YAML configuration. Each s Example tool YAML with resource slots: -```yaml -tool: - name: local/run-migrations - description: "Run database migrations" - source: custom +

+tool:
+  name: local/run-migrations
+  description: "Run database migrations"
+  source: custom
 
-  resources:
-    db:
-      type: local/database
-      access: read_write
-      required: true
-      description: "Target database for migrations"
+  resources:
+    db:
+      type: local/database
+      access: read_write
+      required: true
+      description: "Target database for migrations"
 
-  capability:
-    writes: true
-    write_scope: [db:migrations]     # References the "db" slot
-    checkpointable: true
+  capability:
+    writes: true
+    write_scope: [db:migrations] # References the "db" slot
+    checkpointable: true
 
-  code: |
-    direction = params["direction"]
-    db_resource = ctx.resources["db"]   # Access the bound resource
+  code: |
+    direction = params["direction"]
+    db_resource = ctx.resources["db"]   # Access the bound resource
     result = db_resource.handler.execute_migration(direction, db_resource.sandbox)
-    return {"status": "ok"}
-```
+    return {"status": "ok"}
+
A tool that works with multiple resources: -```yaml -tool: - name: local/cross-repo-diff - description: "Compare files across two git repositories" - source: custom +

+tool:
+  name: local/cross-repo-diff
+  description: "Compare files across two git repositories"
+  source: custom
 
-  resources:
-    source_repo:
-      type: git-checkout
-      access: read_only
-      required: true
-      description: "Source repository to compare from"
-    target_repo:
-      type: git-checkout
-      access: read_only
-      required: true
-      description: "Target repository to compare against"
+  resources:
+    source_repo:
+      type: git-checkout
+      access: read_only
+      required: true
+      description: "Source repository to compare from"
+    target_repo:
+      type: git-checkout
+      access: read_only
+      required: true
+      description: "Target repository to compare against"
 
-  capability:
-    read_only: true
+  capability:
+    read_only: true
 
-  code: |
-    source = ctx.resources["source_repo"]
-    target = ctx.resources["target_repo"]
-    # ... compare files across repos ...
-```
+  code: |
+    source = ctx.resources["source_repo"]
+    target = ctx.resources["target_repo"]
+    # ... compare files across repos ...
+
##### Three Binding Modes @@ -6167,13 +6922,13 @@ Resource slots are resolved to actual resources through one of three binding mod The slot declares a resource type requirement, and the system resolves it from the plan's project context at activation time. This is the most common mode — the tool says "I need a git-checkout resource" and the system finds one among the project's linked resources. -```yaml -resources: - repo: - type: git-checkout - access: read_write - # No `bind` field → contextual binding -``` +

+resources:
+  repo:
+    type: git-checkout
+    access: read_write
+    # No `bind` field → contextual binding
+
Resolution rules for contextual binding: * The system searches the plan's project for linked resources matching the slot's type. @@ -6185,14 +6940,14 @@ Resolution rules for contextual binding: The slot is hardcoded to a specific registered resource by name. This is useful for tools that always operate on the same resource, regardless of project context. -```yaml -resources: - docs: - type: fs-mount - access: read_only - bind: local/company-docs # Static: always this resource - description: "Company documentation corpus" -``` +

+resources:
+  docs:
+    type: fs-mount
+    access: read_only
+    bind: local/company-docs # Static: always this resource
+    description: "Company documentation corpus"
+
Static bindings are resolved at registration time and validated — the named resource must exist and be of the correct type. @@ -6200,22 +6955,22 @@ Static bindings are resolved at registration time and validated — the named re The resource reference is passed as a tool argument at invocation time. This is useful for tools that operate on user-specified resources. -```yaml -resources: - target: - type: git-checkout - access: read_only - from_param: repository # Bound from the "repository" input parameter - description: "Repository to analyze" +

+resources:
+  target:
+    type: git-checkout
+    access: read_only
+    from_param: repository # Bound from the "repository" input parameter
+    description: "Repository to analyze"
 
-input_schema:
-  type: object
-  properties:
-    repository:
-      type: string
-      description: "Name of the registered resource to analyze"
-  required: [repository]
-```
+input_schema:
+  type: object
+  properties:
+    repository:
+      type: string
+      description: "Name of the registered resource to analyze"
+  required: [repository]
+
The `from_param` field links a resource slot to an input parameter. At invocation time, the system resolves the parameter value as a resource name from the Resource Registry and validates type compatibility. @@ -6310,7 +7065,7 @@ class ToolRegistry { - toolIndex : Map -- + add(config_path) : ToolRecord - + upgrade(name, config_path) : ToolRecord + + update(name, config_path) : ToolRecord + remove(name) : void + lookup(name) : ToolRecord + list(filters) : ToolRecord[] @@ -6518,15 +7273,15 @@ Bridges Agent Skills Standard (`SKILL.md` folders) into the tool model. Agent Sk 1. **discover()**: Scans the configured skill directory for a `SKILL.md` file. Parses only the YAML frontmatter (`name`, `description`, optional `compatibility`, `metadata`, `allowed-tools`) to produce a lightweight `ToolDescriptor`. This metadata is injected into the agent's system prompt in a structured format so the LLM can decide when the skill is relevant: - ```xml - - - deploy-to-staging - Deploy the current branch to the staging environment. - local/deploy-staging - - - ``` + 

+   <style="color: cyan; font-weight: 600;">available_agent_skills>
+     <style="color: cyan; font-weight: 600;">agent_skill>
+       <style="color: cyan; font-weight: 600;">name>deploy-to-staging</style="color: cyan; font-weight: 600;">name>
+       <style="color: cyan; font-weight: 600;">description>Deploy the current branch to the staging environment.</style="color: cyan; font-weight: 600;">description>
+       <style="color: cyan; font-weight: 600;">tool>local/deploy-staging</style="color: cyan; font-weight: 600;">tool>
+     </style="color: cyan; font-weight: 600;">agent_skill>
+   </style="color: cyan; font-weight: 600;">available_agent_skills>
+
Discovery is **low-cost** — only ~50–100 tokens per Agent Skill for metadata. The full instructions are not loaded until activation. @@ -6561,36 +7316,36 @@ Wraps CleverAgents' native resource operations as tools: **Built-in tool groups:** **File Operations (`file_operations`):** -```python -read_file(path: str) -> str -write_file(path: str, content: str) -> None -edit_file(path: str, edits: list[Edit]) -> None -delete_file(path: str) -> None -move_file(source: str, destination: str) -> None -copy_file(source: str, destination: str) -> None -``` +

+read_file(path: str) -> str
+write_file(path: str, content: str) -> None
+edit_file(path: str, edits: list[Edit]) -> None
+delete_file(path: str) -> None
+move_file(source: str, destination: str) -> None
+copy_file(source: str, destination: str) -> None
+
**Directory Operations (`directory_operations`):** -```python -create_directory(path: str) -> None -list_directory(path: str, pattern: str = "*") -> list[str] -delete_directory(path: str, recursive: bool = False) -> None -``` +

+create_directory(path: str) -> None
+list_directory(path: str, pattern: str = "*") -> list[str]
+delete_directory(path: str, recursive: bool = False) -> None
+
**Search Operations (`search_operations`):** -```python -search_files(pattern: str, content_pattern: str = None) -> list[Match] -find_definition(symbol: str) -> list[Location] -find_references(symbol: str) -> list[Location] -``` +

+search_files(pattern: str, content_pattern: str = None) -> list[Match]
+find_definition(symbol: str) -> list[Location]
+find_references(symbol: str) -> list[Location]
+
**Git Operations (`git_operations`, when resource is a git repository):** -```python -git_status() -> GitStatus -git_diff(path: str = None) -> str -git_log(count: int = 10) -> list[Commit] -git_blame(path: str) -> list[BlameLine] -``` +

+git_status() -> GitStatus
+git_diff(path: str = None) -> str
+git_log(count: int = 10) -> list[Commit]
+git_blame(path: str) -> list[BlameLine]
+
Each built-in tool: * Has fully defined capability metadata @@ -6602,29 +7357,29 @@ Each built-in tool: MCP's metadata is not sufficient (read-only/idempotent is not enough; write scope is unclear). CleverAgents extends every tool — regardless of source — with a uniform capability metadata schema: -```yaml -capability: - read_only: bool # Whether tool only performs read operations - writes: bool # Whether tool can modify resources - write_scope: # What the tool is allowed to mutate - - file_paths: ["src/**", "tests/**"] # Path patterns within bound resources - - resource_slots: ["repo", "db"] # Resource slot names (from resource bindings) - - environment: container | host - idempotent: bool # Whether repeated calls produce same result - checkpointable: bool # Whether tool supports checkpoint/rollback - checkpoint_scope: str # What can be rolled back (file, transaction, commit, snapshot) - side_effects: # Non-reversible effects +

+capability:
+  read_only: bool # Whether tool only performs read operations
+  writes: bool # Whether tool can modify resources
+  write_scope:             # What the tool is allowed to mutate
+    - file_paths: ["src/**", "tests/**"]     # Path patterns within bound resources
+    - resource_slots: ["repo", "db"]         # Resource slot names (from resource bindings)
+    - environment: container | host
+  idempotent: bool # Whether repeated calls produce same result
+  checkpointable: bool # Whether tool supports checkpoint/rollback
+  checkpoint_scope: str # What can be rolled back (file, transaction, commit, snapshot)
+  side_effects:            # Non-reversible effects
     - install_packages
     - mutate_infra
     - send_email
-  required_permissions:    # Permissions needed to invoke
-    - resource:write
-    - sandbox:shell
-  cost_profile:            # Usage constraints
-    rate_limit: "10/min"
-    estimated_cost: "$0.01/call"
-  human_approval_required: bool  # Whether a human must approve invocation
-```
+  required_permissions:    # Permissions needed to invoke
+    - resource:write
+    - sandbox:shell
+  cost_profile:            # Usage constraints
+    rate_limit: "10/min"
+    estimated_cost: "$0.01/call"
+  human_approval_required: bool # Whether a human must approve invocation
+
**Where metadata comes from per source:** @@ -6643,25 +7398,25 @@ When an action is marked `read_only: true`, it can **only use tools that have `r When an LLM agent decides to use a tool (regardless of source), the following flow occurs through the unified execution pipeline: -``` +

 1. LLM generates tool call
-   e.g., edit_file(path="src/main.py", changes=[...])
-   or:   local/github.create_issue(title="Bug fix", body="...")
-   or:   (activates Agent Skill "deploy-to-staging" via instructions)
+   e.g., edit_file(path="src/main.py", changes=[...])
+   or:   local/github.create_issue(title="Bug fix", body="...")
+   or:   (activates Agent Skill "deploy-to-staging" via instructions)
                                 ↓
 2. Tool Router receives call
-   - Resolves tool by name from the Tool Registry or actor's skill tool sets
+   - Resolves tool by name from the Tool Registry or actor's skill tool sets
    - Validates parameters against inputSchema
-   - Checks capability metadata against plan's permission policy:
+   - Checks capability metadata against plan's permission policy:
      • Is this tool in allowed skill categories?
      • Does the plan allow writes?
      • Is human approval required?
    - If denied → return PermissionDeniedError to LLM
                                 ↓
-3. Resource Binding Resolution & Sandbox Context
+3. Resource Binding Resolution & Sandbox Context
    - Resolve resource bindings for this tool:
      • Static bindings: already resolved at registration
-     • Contextual bindings: resolve from plan's project resources
+     • Contextual bindings: resolve from plan's project resources
      • Parameter bindings: resolve from invocation arguments
    - Validate resource type compatibility for each slot
    - Validate access mode (e.g., read_write tool on read_only resource → error)
@@ -6679,44 +7434,44 @@ When an LLM agent decides to use a tool (regardless of source), the following fl
                                 ↓
 5. Change Recording
    - If tool modified resources → create Change record(s)
-   - Append Change(s) to plan's ChangeSet
+   - Append Change(s) to plan's ChangeSet
    - Update sandbox state
    - If checkpointable → record checkpoint for rollback
                                 ↓
 6. Result Return
    - Normalize result to uniform Result type
    - Return to LLM agent for continued reasoning
-```
+
#### Change Tracking from Tool Invocations **Critical Architecture Point:** The ChangeSet is NOT built by parsing LLM output. It is built by recording the effects of tool invocations: -```python -class ToolExecutionContext: - """Context provided to every tool execution, regardless of source.""" +

+class ToolExecutionContext:
+    """Context provided to every tool execution, regardless of source."""
     
-    def __init__(self, plan: Plan, sandbox: Sandbox,
-                 resources: dict[str, BoundResource]):
+    def __init__(self, plan: Plan, sandbox: Sandbox,
+                 resources: dict[str, BoundResource]):
         self.plan = plan
         self.sandbox = sandbox
-        self.resources = resources    # slot_name → BoundResource
-        self.changes: list[Change] = []
+        self.resources = resources    # slot_name → BoundResource
+        self.changes: list[Change] = []
     
-    def record_change(self, change: Change) -> None:
-        """Record a change made by a tool."""
+    def record_change(self, change: Change) -> None:
+        """Record a change made by a tool."""
         self.changes.append(change)
         self.plan.changeset.add_change(change)
 
 
-class WriteFileTool:
-    """Example: built-in tool for writing files."""
+class WriteFileTool:
+    """Example: built-in tool for writing files."""
     
-    def execute(self, path: str, content: str, ctx: ToolExecutionContext) -> None:
+    def execute(self, path: str, content: str, ctx: ToolExecutionContext) -> None:
         handler = ctx.sandbox.get_handler(path)
         change = handler.write(path, content, ctx.sandbox)
         ctx.record_change(change)
-```
+
This approach means: * Every resource modification is explicit and tracked @@ -6777,13 +7532,13 @@ sequenceDiagram MCP servers operate on real filesystem paths, but CleverAgents executes plans in sandboxes. The MCPToolAdapter transparently rewrites paths: -```python -# Before sending to MCP server: -# Logical path: "src/main.py" -# Sandbox path: "/tmp/sandbox-01HXM/worktree/src/main.py" -# The adapter rewrites the tool arguments so the MCP server -# operates on sandboxed state without knowing about the sandbox. -``` +

+# Before sending to MCP server:
+# Logical path: "src/main.py"
+# Sandbox path: "/tmp/sandbox-01HXM/worktree/src/main.py"
+# The adapter rewrites the tool arguments so the MCP server
+# operates on sandboxed state without knowing about the sandbox.
+
This ensures MCP tools respect sandbox boundaries even though they have no awareness of the CleverAgents sandbox model. @@ -6814,15 +7569,15 @@ This means an actor can have dozens of Agent Skill tools available but only pay Both can coexist in the same skill. A common pattern is an Agent Skill tool that teaches the agent a workflow which involves calling multiple MCP tools: -``` -Agent Skill Tool: "local/deploy-staging" +

+Agent Skill Tool: "local/deploy-staging"
   SKILL.md instructions:
     1. Run tests using the built-in shell tool
     2. Create a PR using the GitHub MCP tool (create_pull_request)
     3. Wait for CI using the GitHub MCP tool (get_check_runs)
     4. Deploy using the AWS MCP tool (ecs_update_service)
     5. Verify deployment using the HTTP MCP tool (fetch_url)
-```
+
#### Tool-Level Checkpointability @@ -6916,150 +7671,149 @@ When an actor references a skill, it gains access to the **flattened set of all Skills are defined in their own YAML configuration files, separate from tool and actor configurations. A skill YAML file declares which registered tools it includes (by name), which other skills it includes, and optionally defines anonymous inline tools: -```yaml -# File: skills/devops-toolkit.yaml -cleveragents: - version: "3.0" +

+# File: skills/devops-toolkit.yaml
+cleveragents:
+  version: "3.0"
 
-skill:
-  name: local/devops-toolkit
-  description: "Full-stack development tools for file ops, git, GitHub, and deployment"
+skill:
+  name: local/devops-toolkit
+  description: "Full-stack development tools for file ops, git, GitHub, and deployment"
 
-  # ── Named Tool References ───────────────────────────────
-  # Reference independently registered tools by name.
-  # These tools must already be registered via `agents tool add`.
-  # Optional metadata overrides can be applied per tool.
-  tools:
+  # ── Named Tool References ───────────────────────────────
+  # Reference independently registered tools by name.
+  # These tools must already be registered via `agents tool add`.
+  # Optional metadata overrides can be applied per tool.
+  tools:
     - local/run-migrations                  # Simple reference, use as registered
-    - name: local/deploy-staging            # Reference with metadata override
-      override:
-        capability:
-          human_approval_required: true     # Require approval in this skill context
+    - name: local/deploy-staging            # Reference with metadata override
+      override:
+        capability:
+          human_approval_required: true # Require approval in this skill context
 
-  # ── Include other skills ─────────────────────────────────
-  # All tools from included skills become part of this skill.
-  # Included skills must already be registered in the system.
-  # Individual tools from included skills can have metadata overridden.
-  includes:
+  # ── Include other skills ─────────────────────────────────
+  # All tools from included skills become part of this skill.
+  # Included skills must already be registered in the system.
+  # Individual tools from included skills can have metadata overridden.
+  includes:
     - local/file-ops           # built-in file + directory + search tools
     - local/git-ops            # built-in git tools
-    - name: local/github       # MCP-based GitHub tools, with per-tool overrides
-      tool_overrides:
-        - tool: local/create-github-issue
-          override:
-            capability:
-              write_scope: [github:issues:org-only]
+    - name: local/github       # MCP-based GitHub tools, with per-tool overrides
+      tool_overrides:
+        - tool: local/create-github-issue
+          override:
+            capability:
+              write_scope: [github:issues:org-only]
 
-  # ── MCP Server Tools ─────────────────────────────────────
-  # Connect to MCP servers and expose their tools.
-  # Tools discovered from MCP servers are auto-registered in the
-  # Tool Registry if not already present.
-  mcp_servers:
-    - name: linear
-      command: "npx @anthropic/mcp-linear"
-      env:
-        LINEAR_API_KEY: "${LINEAR_API_KEY}"
-      # Optional: override inferred capability metadata per tool
-      overrides:
-        - tool: create_issue
-          writes: true
-          write_scope: [linear:issues]
-        - tool: list_issues
-          read_only: true
+  # ── MCP Server Tools ─────────────────────────────────────
+  # Connect to MCP servers and expose their tools.
+  # Tools discovered from MCP servers are auto-registered in the
+  # Tool Registry if not already present.
+  mcp_servers:
+    - name: linear
+      command: "npx @anthropic/mcp-linear"
+      env:
+        LINEAR_API_KEY: "${LINEAR_API_KEY}"
+      # Optional: override inferred capability metadata per tool
+      overrides:
+        - tool: create_issue
+          writes: true
+          write_scope: [linear:issues]
+        - tool: list_issues
+          read_only: true
 
-  # ── Agent Skills (SKILL.md folders) ──────────────────────
-  # Each Agent Skill folder is loaded as a composite tool.
-  # The agent discovers it via metadata, activates it by
-  # loading SKILL.md instructions, and follows them.
-  agent_skills:
-    - path: ./skills/code-review-checklist
-      sandbox_policy: none
+  # ── Agent Skills (SKILL.md folders) ──────────────────────
+  # Each Agent Skill folder is loaded as a composite tool.
+  # The agent discovers it via metadata, activates it by
+  # loading SKILL.md instructions, and follows them.
+  agent_skills:
+    - path: ./skills/code-review-checklist
+      sandbox_policy: none
 
-  # ── Built-in Tool Groups ─────────────────────────────────
-  # Opt-in to built-in tool groups provided by CleverAgents.
-  builtins:
-    - group: shell_operations
+  # ── Built-in Tool Groups ─────────────────────────────────
+  # Opt-in to built-in tool groups provided by CleverAgents.
+  builtins:
+    - group: shell_operations
 
-  # ── Anonymous Tools ──────────────────────────────────────
-  # Inline tool definitions for one-off, skill-specific operations.
-  # Same format as a named tool YAML body but without a name.
-  # These are NOT registered in the Tool Registry and are NOT reusable.
-  anonymous_tools:
-    - description: "One-off cleanup for legacy migration artifacts"
-      input_schema:
-        type: object
-        properties:
-          directory: { type: string }
-      capability:
-        writes: true
-        checkpointable: true
-        checkpoint_scope: file
-      code: |
+  # ── Anonymous Tools ──────────────────────────────────────
+  # Inline tool definitions for one-off, skill-specific operations.
+  # Same format as a named tool YAML body but without a name.
+  # These are NOT registered in the Tool Registry and are NOT reusable.
+  anonymous_tools:
+    - description: "One-off cleanup for legacy migration artifacts"
+      input_schema:
+        type: object
+        properties:
+          directory: { type: string }
+      capability:
+        writes: true
+        checkpointable: true
+        checkpoint_scope: file
+      code: |
         import os, glob
-        directory = params["directory"]
+        directory = params["directory"]
         removed = []
-        for f in glob.glob(os.path.join(ctx.sandbox.root, directory, "*.legacy")):
+        for f in glob.glob(os.path.join(ctx.sandbox.root, directory, "*.legacy")):
             os.remove(f)
             removed.append(f)
-        return {"removed": removed, "count": len(removed)}
-```
+        return {"removed": removed, "count": len(removed)}
+
Here is an example of a simpler skill that wraps only built-in tools, suitable for common reuse: -```yaml -# File: skills/file-ops.yaml -cleveragents: - version: "3.0" +

+# File: skills/file-ops.yaml
+cleveragents:
+  version: "3.0"
 
-skill:
-  name: local/file-ops
-  description: "File, directory, and search operations"
+skill:
+  name: local/file-ops
+  description: "File and directory operations"
 
-  builtins:
-    - group: file_operations      # read, write, edit, delete, move, copy
-    - group: directory_operations  # create, list, delete dirs
-    - group: search_operations     # search files, find definitions/references
-```
+  builtins:
+    - group: file_operations      # read, write, edit, delete, move, copy
+    - group: directory_operations  # create, list, delete dirs
+
And an example of a skill that is purely MCP-based: -```yaml -# File: skills/github.yaml -cleveragents: - version: "3.0" +

+# File: skills/github.yaml
+cleveragents:
+  version: "3.0"
 
-skill:
-  name: local/github
-  description: "GitHub operations via MCP"
+skill:
+  name: local/github
+  description: "GitHub operations via MCP"
 
-  mcp_servers:
-    - name: github
-      command: "npx @anthropic/mcp-github"
-      env:
-        GITHUB_TOKEN: "${GITHUB_TOKEN}"
-      overrides:
-        - tool: create_issue
-          writes: true
-          write_scope: [github:issues]
-          checkpointable: false
-        - tool: create_pull_request
-          writes: true
-          write_scope: [github:pulls]
-          checkpointable: false
-        - tool: list_repos
-          read_only: true
-        - tool: get_file_contents
-          read_only: true
-```
+  mcp_servers:
+    - name: github
+      command: "npx @anthropic/mcp-github"
+      env:
+        GITHUB_TOKEN: "${GITHUB_TOKEN}"
+      overrides:
+        - tool: create_issue
+          writes: true
+          write_scope: [github:issues]
+          checkpointable: false
+        - tool: create_pull_request
+          writes: true
+          write_scope: [github:pulls]
+          checkpointable: false
+        - tool: list_repos
+          read_only: true
+        - tool: get_file_contents
+          read_only: true
+
#### Skill Hierarchy and Composition Skills can include other skills via the `includes` field. When a skill includes another, all tools from the child skill (and transitively, all tools from any skills *it* includes) become part of the parent skill's flattened tool set. -``` +

 local/full-stack-dev
   ├── includes: local/file-ops
-  │     └── builtins: file_operations, directory_operations, search_operations
+  │     └── builtins: file_operations, directory_operations
   ├── includes: local/git-ops
   │     └── builtins: git_operations
   ├── includes: local/github
@@ -7070,12 +7824,11 @@ local/full-stack-dev
   Flattened tool set available to actors referencing local/full-stack-dev:
     read_file, write_file, edit_file, delete_file, move_file, copy_file,
     create_directory, list_directory, delete_directory,
-    search_files, find_definition, find_references,
     git_status, git_diff, git_log, git_blame,
     create_issue, create_pr, list_repos, get_file_contents,
     code-review-checklist (agent skill),
     local/run-migrations, local/deploy-staging (named tools)
-```
+
**Rules for skill composition:** @@ -7088,29 +7841,29 @@ local/full-stack-dev Skills are managed through the `agents skill` CLI commands. Named tools referenced by skills must first be registered via `agents tool add` (see the **Tools** section): -```bash -# First, register any named tools the skill will reference -agents tool add local/run-migrations --config ./tools/run-migrations.yaml -agents tool add local/deploy-staging --config ./tools/deploy-staging.yaml +

+# First, register any named tools the skill will reference
+agents tool add --config ./tools/run-migrations.yaml local/run-migrations
+agents tool add --config ./tools/deploy-staging.yaml local/deploy-staging
 
-# Then register the skill (which references those tools by name)
-agents skill add local/devops-toolkit --config ./skills/devops-toolkit.yaml
+# Then register the skill (which references those tools by name)
+agents skill add --config ./skills/devops-toolkit.yaml local/devops-toolkit
 
-# Upgrade an existing skill (re-reads the config file, overwrites registration)
-agents skill add local/devops-toolkit --config ./skills/devops-toolkit.yaml --upgrade
+# Update an existing skill (re-reads the config file, overwrites registration)
+agents skill add --config ./skills/devops-toolkit.yaml --update local/devops-toolkit
 
-# List all registered skills
+# List all registered skills
 agents skill list
 
-# Show details for a skill (tools, includes, metadata)
+# Show details for a skill (tools, includes, metadata)
 agents skill show local/devops-toolkit
 
-# List all tools provided by a skill (flattened, including from child skills)
+# List all tools provided by a skill (flattened, including from child skills)
 agents skill tools local/devops-toolkit
 
-# Remove a skill
+# Remove a skill
 agents skill remove local/devops-toolkit
-```
+
Once registered, a skill is available to be referenced by any actor configuration. Skills persist in the database (local or server) and follow the same namespace rules as actors, tools, and actions. @@ -7120,49 +7873,49 @@ Actors reference skills **by name** to make collections of tools available for L The actor's configuration lists which skills it should have access to: -```yaml -# File: actors/code-assistant.yaml -cleveragents: - version: "3.0" - default_actor: code_assistant +

+# File: actors/code-assistant.yaml
+cleveragents:
+  version: "3.0"
+  default_actor: code_assistant
 
-actors:
-  code_assistant:
-    type: llm
-    config:
-      actor: anthropic/claude-3-opus
-      temperature: 0.3
-      system_prompt: |
+actors:
+  code_assistant:
+    type: llm
+    config:
+      actor: anthropic/claude-3-opus
+      temperature: 0.3
+      system_prompt: |
         You are a code assistant with access to file, git, and GitHub tools.
         Current task: {{ context.task_description }}
 
-    # Reference skills by fully-qualified name.
-    # All tools from these skills become available to this actor.
-    skills:
+    # Reference skills by fully-qualified name.
+    # All tools from these skills become available to this actor.
+    skills:
       - local/file-ops
       - local/git-ops
       - local/github
 
-  # Or reference a single composite skill that includes all of the above
-  full_stack_assistant:
-    type: llm
-    config:
-      actor: anthropic/claude-3-opus
-      system_prompt: |
+  # Or reference a single composite skill that includes all of the above
+  full_stack_assistant:
+    type: llm
+    config:
+      actor: anthropic/claude-3-opus
+      system_prompt: |
         You are a full-stack development assistant.
 
-    skills:
+    skills:
       - local/full-stack-dev    # includes file-ops, git-ops, github, etc.
-```
+
**Server-qualified skill references**: When connected to multiple servers, skills can be disambiguated with a server prefix, same as actors: -```yaml -skills: - - dev:freemo/custom-analysis # from dev server, personal namespace - - prod:cleverthis/deploy-tools # from prod server, org namespace +

+skills:
+  - dev:freemo/custom-analysis     # from dev server, personal namespace
+  - prod:cleverthis/deploy-tools   # from prod server, org namespace
   - local/file-ops                 # local skill
-```
+
#### Skill Registry @@ -7182,7 +7935,7 @@ class SkillRegistry { - skillIndex : Map -- + add(config_path) : SkillRecord - + upgrade(name, config_path) : SkillRecord + + update(name, config_path) : SkillRecord + remove(name) : void + lookup(name) : SkillRecord + list(filters) : SkillRecord[] @@ -7653,19 +8406,19 @@ Consider a web application called "Acme Dashboard" with three registered resourc **Registration:** -```bash -# 1) Checked-out git repo (has local files on disk) -agents resource add git-checkout local/acme-app \ - --path /home/alice/projects/acme-dashboard --branch main +

+# 1) Checked-out git repo (has local files on disk)
+agents resource add git-checkout local/acme-app \
+  --path /home/alice/projects/acme-dashboard --branch main
 
-# 2) Git repo via remote URL (no local checkout — metadata only)
-agents resource add git local/acme-upstream \
-  --url git@github.com:acmecorp/dashboard.git
+# 2) Git repo via remote URL (no local checkout — metadata only)
+agents resource add git local/acme-upstream \
+  --url git@github.com:acmecorp/dashboard.git
 
-# 3) Standalone directory (not a git repo — just files on disk)
-agents resource add fs-directory local/acme-deploy \
-  --path /opt/deploy/acme-dashboard
-```
+# 3) Standalone directory (not a git repo — just files on disk)
+agents resource add fs-directory local/acme-deploy \
+  --path /opt/deploy/acme-dashboard
+
**What gets auto-discovered for each:** @@ -7947,67 +8700,67 @@ Additional resource types (databases, APIs, cloud infrastructure, etc.) can be a Custom resource types are defined in YAML configuration files and registered via `agents resource type add`. Once registered, a custom type automatically becomes available as a new subcommand under `agents resource add`. -```yaml -# File: resource-types/database.yaml -cleveragents: - version: "3.0" +

+# File: resource-types/database.yaml
+cleveragents:
+  version: "3.0"
 
-resource_type:
-  name: local/database
-  description: "A SQL database (PostgreSQL, MySQL, SQLite, etc.)"
-  physical_or_virtual: physical
-  user_addable: true
+resource_type:
+  name: local/database
+  description: "A SQL database (PostgreSQL, MySQL, SQLite, etc.)"
+  physical_or_virtual: physical
+  user_addable: true
 
-  # CLI arguments for `agents resource add local/database`
-  cli_arguments:
-    - name: connection-string
-      type: string
-      required: true
-      description: "Database connection string (e.g., postgresql://host/dbname)"
-      validation:
-        pattern: "^(postgresql|mysql|sqlite)://"
-    - name: schema
-      type: string
-      required: false
-      description: "Default schema to use"
-    - name: read-only
-      type: boolean
-      required: false
-      default: false
-      description: "Whether the database should be treated as read-only"
+  # CLI arguments for `agents resource add local/database`
+  cli_arguments:
+    - name: connection-string
+      type: string
+      required: true
+      description: "Database connection string (e.g., postgresql://host/dbname)"
+      validation:
+        pattern: "^(postgresql|mysql|sqlite)://"
+    - name: schema
+      type: string
+      required: false
+      description: "Default schema to use"
+    - name: read-only
+      type: boolean
+      required: false
+      default: false
+      description: "Whether the database should be treated as read-only"
 
-  # Sandbox and handler
-  sandbox_strategy: transaction_rollback
-  handler: DatabaseHandler
-  checkpointable: true
+  # Sandbox and handler
+  sandbox_strategy: transaction_rollback
+  handler: DatabaseHandler
+  checkpointable: true
 
-  # Allowed parent types (empty means can be top-level)
-  allowed_parent_types: []
+  # Allowed parent types (empty means can be top-level)
+  allowed_parent_types: []
 
-  # Child types
-  child_types:
-    - type: local/db-schema
-      auto_discover: true
-      manual_link: false
-      description: "Discovered database schemas"
-    - type: local/db-table
-      auto_discover: true
-      manual_link: false
-      description: "Discovered tables within schemas"
+  # Child types
+  child_types:
+    - type: local/db-schema
+      auto_discover: true
+      manual_link: false
+      description: "Discovered database schemas"
+    - type: local/db-table
+      auto_discover: true
+      manual_link: false
+      description: "Discovered tables within schemas"
 
-  # Capabilities
-  capabilities:
-    readable: true
-    writable: true
-    sandboxable: true
-    checkpointable: true
-```
+  # Capabilities
+  capabilities:
+    readable: true
+    writable: true
+    sandboxable: true
+    checkpointable: true
+
When this type is registered: -```bash -agents resource type add local/database --config ./resource-types/database.yaml -# Now available: agents resource add local/database --connection-string CONN [--schema SCHEMA] [--read-only] -``` +

+agents resource type add --config ./resource-types/database.yaml local/database
+# Now available: agents resource add local/database <NAME> --connection-string CONN [--schema SCHEMA] [--read-only]
+
The `user_addable` field determines whether the type appears as a subcommand. Types with `user_addable: false` are only auto-generated as children — for example, `git-remote`, `git-branch`, `git-commit`, and `git-tree-entry` are never created directly by users but are discovered when a `git` (or `git-checkout`) resource is registered. @@ -8266,29 +9019,29 @@ This enables powerful queries like: Resources are created via `agents resource add ` with type-specific arguments. Auto-discovered children are created automatically: -```bash -# Register a checked-out git repository (most common) -agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main -# Auto-discovers: git child (repo metadata, remotes, branches, commits, tree entries) -# + fs-directory child (worktree root directory, subdirectories, files) +

+# Register a checked-out git repository (most common)
+agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
+# Auto-discovers: git child (repo metadata, remotes, branches, commits, tree entries)
+#                 + fs-directory child (worktree root directory, subdirectories, files)
 
-# Register a git repo via remote URL (no local checkout — exists on remote server)
-agents resource add git local/upstream --url git@github.com:org/upstream.git
-# Auto-discovers: remotes, branches, tags, commits, trees, tree entries, stashes, submodules
-#                 (no fs-directory — not checked out locally)
+# Register a git repo via remote URL (no local checkout — exists on remote server)
+agents resource add git local/upstream --url git@github.com:org/upstream.git
+# Auto-discovers: remotes, branches, tags, commits, trees, tree entries, stashes, submodules
+#                 (no fs-directory — not checked out locally)
 
-# Register a standalone directory (not a git repo — just files on disk)
-agents resource add fs-directory local/docs --path /opt/docs/api-reference
-# Auto-discovers: subdirectories, files, symlinks, hardlinks
+# Register a standalone directory (not a git repo — just files on disk)
+agents resource add fs-directory local/docs --path /opt/docs/api-reference
+# Auto-discovers: subdirectories, files, symlinks, hardlinks
 
-# Register a standalone filesystem mount (entire volume)
-agents resource add fs-mount local/data-volume --mount-path /mnt/data
-# Auto-discovers: root fs-directory, subdirectories, files, symlinks, hardlinks
+# Register a standalone filesystem mount (entire volume)
+agents resource add fs-mount local/data-volume --mount-path /mnt/data
+# Auto-discovers: root fs-directory, subdirectories, files, symlinks, hardlinks
 
-# Link resources to projects (resources must be registered first)
-agents project link-resource --project local/api-service --resource local/api-repo
-agents project link-resource --project local/api-service --resource local/docs --read-only
-```
+# Link resources to projects (resources must be registered first)
+agents project link-resource local/api-service local/api-repo
+agents project link-resource local/api-service local/docs --read-only
+
#### Auto-Discovery @@ -8334,7 +9087,7 @@ class ResourceRegistry { - typeIndex : Map -- + add(type, name, properties) : ResourceRecord - + upgrade(name, properties) : ResourceRecord + + update(name, properties) : ResourceRecord + remove(name) : void + lookup(name) : ResourceRecord + list(filters) : ResourceRecord[] @@ -8462,54 +9215,54 @@ CleverAgents provides a unified abstraction that allows tools to work with any r Every resource type provides a handler that implements this interface: -```python -class ResourceHandler(Protocol): - """Handler for a specific resource type.""" +

+class ResourceHandler(Protocol):
+    """Handler for a specific resource type."""
     
-    def read(self, path: str, sandbox: Sandbox) -> Content:
-        """Read content from the sandboxed resource."""
+    def read(self, path: str, sandbox: Sandbox) -> Content:
+        """Read content from the sandboxed resource."""
         ...
     
-    def write(self, path: str, content: Content, sandbox: Sandbox) -> Change:
-        """Write content and return the Change record."""
+    def write(self, path: str, content: Content, sandbox: Sandbox) -> Change:
+        """Write content and return the Change record."""
         ...
     
-    def delete(self, path: str, sandbox: Sandbox) -> Change:
-        """Delete resource and return the Change record."""
+    def delete(self, path: str, sandbox: Sandbox) -> Change:
+        """Delete resource and return the Change record."""
         ...
     
-    def list(self, pattern: str, sandbox: Sandbox) -> list[str]:
-        """List paths matching pattern."""
+    def list(self, pattern: str, sandbox: Sandbox) -> list[str]:
+        """List paths matching pattern."""
         ...
     
-    def diff(self, path: str, sandbox: Sandbox) -> str:
-        """Generate diff between sandbox and original state."""
+    def diff(self, path: str, sandbox: Sandbox) -> str:
+        """Generate diff between sandbox and original state."""
         ...
     
-    def supports_operation(self, operation: OperationType) -> bool:
-        """Check if this resource supports the given operation."""
+    def supports_operation(self, operation: OperationType) -> bool:
+        """Check if this resource supports the given operation."""
         ...
     
-    def discover_children(self, resource: ResourceRecord) -> list[ResourceRecord]:
-        """Auto-discover child resources (called at registration and refresh)."""
+    def discover_children(self, resource: ResourceRecord) -> list[ResourceRecord]:
+        """Auto-discover child resources (called at registration and refresh)."""
         ...
     
-    def content_hash(self, path: str, sandbox: Sandbox) -> str:
-        """Compute content hash for identity tracking."""
+    def content_hash(self, path: str, sandbox: Sandbox) -> str:
+        """Compute content hash for identity tracking."""
         ...
     
-    def create_sandbox(self, resource: ResourceRecord) -> Sandbox:
-        """Create a sandbox for this resource using its type's strategy."""
+    def create_sandbox(self, resource: ResourceRecord) -> Sandbox:
+        """Create a sandbox for this resource using its type's strategy."""
         ...
     
-    def create_checkpoint(self, sandbox: Sandbox) -> Checkpoint:
-        """Create a checkpoint within the sandbox."""
+    def create_checkpoint(self, sandbox: Sandbox) -> Checkpoint:
+        """Create a checkpoint within the sandbox."""
         ...
     
-    def rollback_to(self, sandbox: Sandbox, checkpoint: Checkpoint) -> None:
-        """Roll back sandbox state to a checkpoint."""
+    def rollback_to(self, sandbox: Sandbox, checkpoint: Checkpoint) -> None:
+        """Roll back sandbox state to a checkpoint."""
         ...
-```
+
##### Built-in Resource Handlers @@ -8549,14 +9302,14 @@ sequenceDiagram When a tool has multiple resource slots bound, the path scheme or slot name disambiguates: -``` +

 # Explicit slot reference
-path://repo/src/main.py      → routes to the "repo" slot's bound resource
-path://docs/api/readme.md    → routes to the "docs" slot's bound resource
+path://repo/src/main.py      → routes to the "repo" slot's bound resource
+path://docs/api/readme.md    → routes to the "docs" slot's bound resource
 
-# Default: unqualified paths route to the tool's primary resource slot
+# Default: unqualified paths route to the tool's primary resource slot
 src/main.py                  → routes to the first (or only) resource slot
-```
+
### Code Intelligence & Context Discovery @@ -8580,46 +9333,46 @@ CleverAgents employs a sophisticated multi-layered indexing and discovery system The indexing engine operates across three complementary modalities: -```yaml -IndexingEngine: - modalities: - # Traditional text-based indexing - text_index: - type: "full_text_search" - backend: "tantivy" | "elasticsearch" | "sqlite_fts" - features: +

+IndexingEngine:
+  modalities:
+    # Traditional text-based indexing
+    text_index:
+      type: "full_text_search"
+      backend: "tantivy" | "elasticsearch" | "sqlite_fts"
+      features:
         - Token-based search
         - Regex patterns
         - Language-aware tokenization
         - File path indexing
     
-    # Semantic understanding via embeddings
-    vector_index:
-      type: "embedding_search"
-      backend: "faiss" | "qdrant" | "weaviate" | "pgvector"
-      models:
-        - code: "codegen-6B-multi"
-        - docs: "instructor-xl"
-        - cross-modal: "clip-code"
-      features:
+    # Semantic understanding via embeddings
+    vector_index:
+      type: "embedding_search"
+      backend: "faiss" | "qdrant" | "weaviate" | "pgvector"
+      models:
+        - code: "codegen-6B-multi"
+        - docs: "instructor-xl"
+        - cross-modal: "clip-code"
+      features:
         - Function-level embeddings
         - Class-level embeddings
         - Module-level embeddings
         - Documentation embeddings
         - Cross-language similarity
     
-    # Structural understanding via graph
-    graph_index:
-      type: "rdf_knowledge_graph"
-      backend: "blazegraph" | "stardog" | "apache_jena" | "neo4j"
-      ontology: "CodeOntology"
-      features:
+    # Structural understanding via graph
+    graph_index:
+      type: "rdf_knowledge_graph"
+      backend: "blazegraph" | "stardog" | "apache_jena" | "neo4j"
+      ontology: "CodeOntology"
+      features:
         - AST-based relationships
         - Dependency graphs
         - Call graphs
         - Inheritance hierarchies
         - Data flow analysis
-```
+
##### 2. RDF-Based Code Knowledge Graph @@ -8627,179 +9380,179 @@ The graph store represents code as a rich semantic network using RDF (Resource D **Core Ontology Design:** -```turtle -# CodeOntology - Core vocabulary for code representation -@prefix code: . -@prefix rdfs: . -@prefix xsd: . +

+# CodeOntology - Core vocabulary for code representation
+@prefix code: <https://cleveragents.ai/ontology/code#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 
-# Core Classes
-code:Module a rdfs:Class ;
-    rdfs:comment "A code module (file, package, namespace)" .
+# Core Classes
+code:Module a rdfs:Class ;
+    rdfs:comment "A code module (file, package, namespace)" .
 
-code:Class a rdfs:Class ;
-    rdfs:comment "A class or similar construct" .
+code:Class a rdfs:Class ;
+    rdfs:comment "A class or similar construct" .
 
-code:Function a rdfs:Class ;
-    rdfs:comment "A function, method, or procedure" .
+code:Function a rdfs:Class ;
+    rdfs:comment "A function, method, or procedure" .
 
-code:Variable a rdfs:Class ;
-    rdfs:comment "A variable, constant, or field" .
+code:Variable a rdfs:Class ;
+    rdfs:comment "A variable, constant, or field" .
 
-code:Type a rdfs:Class ;
-    rdfs:comment "A type definition" .
+code:Type a rdfs:Class ;
+    rdfs:comment "A type definition" .
 
-# Core Properties
-code:contains a rdf:Property ;
-    rdfs:domain code:Module ;
-    rdfs:range code:Entity ;
-    rdfs:comment "Module contains entity" .
+# Core Properties
+code:contains a rdf:Property ;
+    rdfs:domain code:Module ;
+    rdfs:range code:Entity ;
+    rdfs:comment "Module contains entity" .
 
-code:imports a rdf:Property ;
-    rdfs:domain code:Module ;
-    rdfs:range code:Module ;
-    rdfs:comment "Module imports another module" .
+code:imports a rdf:Property ;
+    rdfs:domain code:Module ;
+    rdfs:range code:Module ;
+    rdfs:comment "Module imports another module" .
 
-code:extends a rdf:Property ;
-    rdfs:domain code:Class ;
-    rdfs:range code:Class ;
-    rdfs:comment "Class inheritance relationship" .
+code:extends a rdf:Property ;
+    rdfs:domain code:Class ;
+    rdfs:range code:Class ;
+    rdfs:comment "Class inheritance relationship" .
 
-code:calls a rdf:Property ;
-    rdfs:domain code:Function ;
-    rdfs:range code:Function ;
-    rdfs:comment "Function calls another function" .
+code:calls a rdf:Property ;
+    rdfs:domain code:Function ;
+    rdfs:range code:Function ;
+    rdfs:comment "Function calls another function" .
 
-code:references a rdf:Property ;
-    rdfs:domain code:Entity ;
-    rdfs:range code:Entity ;
-    rdfs:comment "Entity references another entity" .
+code:references a rdf:Property ;
+    rdfs:domain code:Entity ;
+    rdfs:range code:Entity ;
+    rdfs:comment "Entity references another entity" .
 
-code:hasParameter a rdf:Property ;
-    rdfs:domain code:Function ;
-    rdfs:range code:Parameter ;
-    rdfs:comment "Function has parameter" .
+code:hasParameter a rdf:Property ;
+    rdfs:domain code:Function ;
+    rdfs:range code:Parameter ;
+    rdfs:comment "Function has parameter" .
 
-code:returns a rdf:Property ;
-    rdfs:domain code:Function ;
-    rdfs:range code:Type ;
-    rdfs:comment "Function return type" .
+code:returns a rdf:Property ;
+    rdfs:domain code:Function ;
+    rdfs:range code:Type ;
+    rdfs:comment "Function return type" .
 
-# Annotations
-code:hasDocstring a rdf:Property ;
-    rdfs:domain code:Entity ;
-    rdfs:range xsd:string .
+# Annotations
+code:hasDocstring a rdf:Property ;
+    rdfs:domain code:Entity ;
+    rdfs:range xsd:string .
 
-code:hasComplexity a rdf:Property ;
-    rdfs:domain code:Function ;
-    rdfs:range xsd:integer ;
-    rdfs:comment "Cyclomatic complexity" .
+code:hasComplexity a rdf:Property ;
+    rdfs:domain code:Function ;
+    rdfs:range xsd:integer ;
+    rdfs:comment "Cyclomatic complexity" .
 
-code:hasTestCoverage a rdf:Property ;
-    rdfs:domain code:Entity ;
-    rdfs:range xsd:decimal ;
-    rdfs:comment "Test coverage percentage" .
-```
+code:hasTestCoverage a rdf:Property ;
+    rdfs:domain code:Entity ;
+    rdfs:range xsd:decimal ;
+    rdfs:comment "Test coverage percentage" .
+
**Example Knowledge Graph Fragment:** -```turtle -# Concrete example: Authentication module - a code:Module ; - code:imports ; - code:imports ; - code:contains . +

+# Concrete example: Authentication module
+<file:///src/auth/auth_manager.py> a code:Module ;
+    code:imports <file:///src/core/user.py> ;
+    code:imports <file:///src/utils/crypto.py> ;
+    code:contains <class://AuthManager> .
 
- a code:Class ;
-    code:hasMethod  ;
-    code:hasMethod  ;
-    code:extends  ;
-    code:hasDocstring "Manages user authentication and session tokens" .
+<class://AuthManager> a code:Class ;
+    code:hasMethod <method://AuthManager.authenticate> ;
+    code:hasMethod <method://AuthManager.validate_token> ;
+    code:extends <class://BaseManager> ;
+    code:hasDocstring "Manages user authentication and session tokens" .
 
- a code:Function ;
-    code:hasParameter  ;
-    code:hasParameter  ;
-    code:returns  ;
-    code:calls  ;
-    code:calls  ;
-    code:hasComplexity 8 ;
-    code:hasTestCoverage 0.95 .
-```
+<method://AuthManager.authenticate> a code:Function ;
+    code:hasParameter <param://username> ;
+    code:hasParameter <param://password> ;
+    code:returns <type://AuthToken> ;
+    code:calls <method://CryptoUtils.hash_password> ;
+    code:calls <method://UserDB.find_user> ;
+    code:hasComplexity 8 ;
+    code:hasTestCoverage 0.95 .
+
**Advanced Graph Queries:** -```sparql -# Find all functions that manipulate user authentication -PREFIX code: -SELECT ?function ?module -WHERE { - ?function a code:Function ; - code:calls*/code:references ?entity . - ?entity rdfs:label ?label . - FILTER(CONTAINS(LCASE(?label), "auth") || CONTAINS(LCASE(?label), "user")) - ?module code:contains ?function . +

+# Find all functions that manipulate user authentication
+PREFIX code: <https://cleveragents.ai/ontology/code#>
+SELECT ?function ?module
+WHERE {
+    ?function a code:Function ;
+              code:calls*/code:references ?entity .
+    ?entity rdfs:label ?label .
+    FILTER(CONTAINS(LCASE(?label), "auth") || CONTAINS(LCASE(?label), "user"))
+    ?module code:contains ?function .
 }
 
-# Find circular dependencies
-SELECT ?module1 ?module2
-WHERE {
-    ?module1 code:imports+ ?module2 .
-    ?module2 code:imports+ ?module1 .
-    FILTER(?module1 != ?module2)
+# Find circular dependencies
+SELECT ?module1 ?module2
+WHERE {
+    ?module1 code:imports+ ?module2 .
+    ?module2 code:imports+ ?module1 .
+    FILTER(?module1 != ?module2)
 }
 
-# Find most complex untested functions
-SELECT ?function ?complexity
-WHERE {
-    ?function a code:Function ;
-              code:hasComplexity ?complexity ;
-              code:hasTestCoverage ?coverage .
-    FILTER(?complexity > 10 && ?coverage < 0.5)
+# Find most complex untested functions
+SELECT ?function ?complexity
+WHERE {
+    ?function a code:Function ;
+              code:hasComplexity ?complexity ;
+              code:hasTestCoverage ?coverage .
+    FILTER(?complexity > 10 && ?coverage < 0.5)
 }
-ORDER BY DESC(?complexity)
-LIMIT 10
-```
+ORDER BY DESC(?complexity)
+LIMIT 10
+
##### 3. Intelligent Context Assembly Pipeline The context assembly pipeline leverages all three indices to build optimal context for each agent: -```python -class ContextAssemblyPipeline: - def assemble_context(self, - query: str, - actor_type: str, - resource_scope: List[Resource], - max_tokens: int) -> Context: +

+class ContextAssemblyPipeline:
+    def assemble_context(self, 
+                        query: str, 
+                        actor_type: str,
+                        resource_scope: List[Resource],
+                        max_tokens: int) -> Context:
         
-        # Stage 1: Query Understanding
+        # Stage 1: Query Understanding
         intent = self.analyze_query_intent(query)
-        entities = self.extract_entities(query)  # Classes, functions, concepts
+        entities = self.extract_entities(query)  # Classes, functions, concepts
         
-        # Stage 2: Multi-Modal Search
+        # Stage 2: Multi-Modal Search
         results = SearchResults()
         
-        # Text search for exact matches
-        if intent.needs_exact_match:
+        # Text search for exact matches
+        if intent.needs_exact_match:
             text_results = self.text_index.search(
                 query=query,
-                filters={"resources": resource_scope},
+                filters={"resources": resource_scope},
                 limit=100
             )
             results.add(text_results)
         
-        # Vector search for semantic similarity
-        if intent.needs_semantic_match:
+        # Vector search for semantic similarity
+        if intent.needs_semantic_match:
             query_embedding = self.embed_query(query, actor_type)
             vector_results = self.vector_index.search(
                 embedding=query_embedding,
-                filters={"resources": resource_scope},
+                filters={"resources": resource_scope},
                 limit=50
             )
             results.add(vector_results)
         
-        # Graph traversal for structural relationships
-        if entities:
+        # Graph traversal for structural relationships
+        if entities:
             graph_results = self.graph_index.traverse(
                 start_nodes=entities,
                 patterns=self.get_patterns_for_actor(actor_type),
@@ -8808,168 +9561,168 @@ class ContextAssemblyPipeline:
             )
             results.add(graph_results)
         
-        # Stage 3: Relevance Ranking
+        # Stage 3: Relevance Ranking
         ranked_results = self.rank_by_relevance(
             results=results,
             actor_type=actor_type,
             query_intent=intent
         )
         
-        # Stage 4: Context Optimization
+        # Stage 4: Context Optimization
         context = self.optimize_context(
             ranked_results=ranked_results,
             max_tokens=max_tokens,
             strategy=self.get_strategy_for_actor(actor_type)
         )
         
-        return context
+        return context
     
-    def get_patterns_for_actor(self, actor_type: str) -> List[GraphPattern]:
-        """Different actors need different traversal patterns"""
+    def get_patterns_for_actor(self, actor_type: str) -> List[GraphPattern]:
+        """Different actors need different traversal patterns"""
         patterns = {
-            "strategist": [
-                "module_dependencies",      # Understand architecture
-                "interface_boundaries",     # Find API surfaces
-                "test_coverage_gaps"        # Identify risks
+            "strategist": [
+                "module_dependencies",      # Understand architecture
+                "interface_boundaries",     # Find API surfaces
+                "test_coverage_gaps"        # Identify risks
             ],
-            "executor": [
-                "implementation_details",   # Get full function bodies
-                "local_dependencies",       # Find what to change
-                "usage_patterns"           # Understand call sites
+            "executor": [
+                "implementation_details",   # Get full function bodies
+                "local_dependencies",       # Find what to change
+                "usage_patterns"           # Understand call sites
             ],
-            "reviewer": [
-                "change_impact_analysis",   # What could break
-                "similar_patterns",        # Consistency checks
-                "test_relationships"       # Verification paths
+            "reviewer": [
+                "change_impact_analysis",   # What could break
+                "similar_patterns",        # Consistency checks
+                "test_relationships"       # Verification paths
             ]
         }
-        return patterns.get(actor_type, ["general_traversal"])
-```
+        return patterns.get(actor_type, ["general_traversal"])
+
##### 4. Plugin Architecture for Extensibility The system is designed for extensibility at every level: -```yaml -PluginSystem: - # Language-specific analyzers - analyzers: - python: - class: "PythonAnalyzer" - features: +

+PluginSystem:
+  # Language-specific analyzers
+  analyzers:
+    python:
+      class: "PythonAnalyzer"
+      features:
         - AST parsing via ast module
         - Type inference via mypy
         - Import resolution
         - Docstring extraction
     
-    typescript:
-      class: "TypeScriptAnalyzer"
-      features:
+    typescript:
+      class: "TypeScriptAnalyzer"
+      features:
         - TSC-based parsing
         - Type extraction
         - Module resolution
         - JSDoc parsing
     
-    rust:
-      class: "RustAnalyzer"
-      features:
+    rust:
+      class: "RustAnalyzer"
+      features:
         - rust-analyzer integration
         - Lifetime analysis
         - Trait resolution
         - Macro expansion
     
-    # Custom analyzer example
-    custom_dsl:
-      class: "CustomDSLAnalyzer"
-      config:
-        grammar: "path/to/grammar.peg"
-        semantic_rules: "path/to/rules.yaml"
+    # Custom analyzer example
+    custom_dsl:
+      class: "CustomDSLAnalyzer"
+      config:
+        grammar: "path/to/grammar.peg"
+        semantic_rules: "path/to/rules.yaml"
   
-  # Index backend providers
-  backends:
-    graph:
-      - name: "blazegraph"
-        class: "BlazegraphBackend"
-        scalability: "billions of triples"
-        features: ["SPARQL", "reasoning", "geospatial"]
+  # Index backend providers
+  backends:
+    graph:
+      - name: "blazegraph"
+        class: "BlazegraphBackend"
+        scalability: "billions of triples"
+        features: ["SPARQL", "reasoning", "geospatial"]
       
-      - name: "neo4j"
-        class: "Neo4jBackend"
-        scalability: "enterprise"
-        features: ["Cypher", "APOC", "GDS"]
+      - name: "neo4j"
+        class: "Neo4jBackend"
+        scalability: "enterprise"
+        features: ["Cypher", "APOC", "GDS"]
       
-      - name: "custom_graph"
-        class: "MyCustomGraphDB"
-        config:
-          connection: "custom://localhost:7687"
+      - name: "custom_graph"
+        class: "MyCustomGraphDB"
+        config:
+          connection: "custom://localhost:7687"
     
-    vector:
-      - name: "faiss"
-        class: "FaissBackend"
-        scalability: "100M vectors"
-        features: ["GPU acceleration", "HNSW"]
+    vector:
+      - name: "faiss"
+        class: "FaissBackend"
+        scalability: "100M vectors"
+        features: ["GPU acceleration", "HNSW"]
       
-      - name: "qdrant"
-        class: "QdrantBackend"
-        scalability: "distributed"
-        features: ["filtering", "payloads", "snapshots"]
+      - name: "qdrant"
+        class: "QdrantBackend"
+        scalability: "distributed"
+        features: ["filtering", "payloads", "snapshots"]
   
-  # Embedding model providers
-  embedders:
-    - name: "openai"
-      class: "OpenAIEmbedder"
-      models: ["text-embedding-3-large", "text-embedding-3-small"]
+  # Embedding model providers
+  embedders:
+    - name: "openai"
+      class: "OpenAIEmbedder"
+      models: ["text-embedding-3-large", "text-embedding-3-small"]
     
-    - name: "local"
-      class: "LocalEmbedder"
-      models: ["all-MiniLM-L6-v2", "instructor-xl"]
+    - name: "local"
+      class: "LocalEmbedder"
+      models: ["all-MiniLM-L6-v2", "instructor-xl"]
     
-    - name: "custom"
-      class: "MyFineTunedEmbedder"
-      model_path: "path/to/model"
-```
+    - name: "custom"
+      class: "MyFineTunedEmbedder"
+      model_path: "path/to/model"
+
##### 5. Agent Skills for Code Intelligence Agents interact with the code intelligence system through a specialized skill (`local/code-intelligence`) that contains tools for semantic search, dependency analysis, and refactoring: -```yaml -# Actor references the code intelligence skill -actors: - code_explorer: - type: llm - config: - actor: anthropic/claude-3-opus - skills: +

+# Actor references the code intelligence skill
+actors:
+  code_explorer:
+    type: llm
+    config:
+      actor: anthropic/claude-3-opus
+    skills:
       - local/code-intelligence   # Provides search_code_semantically,
-                                  # analyze_dependencies, suggest_refactoring_targets
-```
+                                  # analyze_dependencies, suggest_refactoring_targets
+
The `local/code-intelligence` skill uses anonymous inline tools to wrap the code intelligence subsystem. These tools are defined inline because they are tightly coupled to the skill's specific implementation and not reused elsewhere (if any were needed in multiple contexts, they would be registered independently via `agents tool add` and referenced by name): -```yaml -# File: skills/code-intelligence.yaml -skill: - name: local/code-intelligence - description: "Semantic code search, dependency analysis, and refactoring recommendations" +

+# File: skills/code-intelligence.yaml
+skill:
+  name: local/code-intelligence
+  description: "Semantic code search, dependency analysis, and refactoring recommendations"
 
-  anonymous_tools:
-    - name: search_code_semantically
-      description: "Find code similar to a concept using vector search, enriched with dependency context"
-      input_schema:
-        type: object
-        properties:
-          query: { type: string }
-          scope: { type: string, default: "all" }
-          limit: { type: integer, default: 10 }
-        required: [query]
-      capability:
-        read_only: true
-      code: |
+  anonymous_tools:
+    - name: search_code_semantically
+      description: "Find code similar to a concept using vector search, enriched with dependency context"
+      input_schema:
+        type: object
+        properties:
+          query: { type: string }
+          scope: { type: string, default: "all" }
+          limit: { type: integer, default: 10 }
+        required: [query]
+      capability:
+        read_only: true
+      code: |
         results = ctx.code_intelligence.vector_search(
-            query=params["query"],
-            scope=params.get("scope", "all"),
-            limit=params.get("limit", 10)
+            query=params["query"],
+            scope=params.get("scope", "all"),
+            limit=params.get("limit", 10)
         )
         for result in results:
             result.context = ctx.code_intelligence.get_dependencies(
@@ -8977,366 +9730,366 @@ skill:
             )
         return results
 
-    - name: analyze_dependencies
-      description: "Analyze module dependencies using graph store"
-      input_schema:
-        type: object
-        properties:
-          module_path: { type: string }
-        required: [module_path]
-      capability:
-        read_only: true
-      code: |
-        module = params["module_path"]
-        deps = ctx.code_intelligence.graph_query(f'''
-            PREFIX code: 
+    - name: analyze_dependencies
+      description: "Analyze module dependencies using graph store"
+      input_schema:
+        type: object
+        properties:
+          module_path: { type: string }
+        required: [module_path]
+      capability:
+        read_only: true
+      code: |
+        module = params["module_path"]
+        deps = ctx.code_intelligence.graph_query(f'''
+            PREFIX code: <https://cleveragents.ai/ontology/code#>
             SELECT ?dep ?type WHERE {{
-                <{module}> code:imports* ?dep . ?dep a ?type .
+                <{module}> code:imports* ?dep . ?dep a ?type .
             }}
-        ''')
+        ''')
         return {
-            "direct_deps": len([d for d in deps if d.distance == 1]),
-            "transitive_deps": len(deps),
-            "circular_deps": ctx.code_intelligence.find_circular_deps(module),
-            "dependency_graph": deps
+            "direct_deps": len([d for d in deps if d.distance == 1]),
+            "transitive_deps": len(deps),
+            "circular_deps": ctx.code_intelligence.find_circular_deps(module),
+            "dependency_graph": deps
         }
 
-    - name: suggest_refactoring_targets
-      description: "Combine text, graph, and vector search to find refactoring targets"
-      input_schema:
-        type: object
-        properties:
-          scope: { type: string }
-        required: [scope]
-      capability:
-        read_only: true
-      code: |
+    - name: suggest_refactoring_targets
+      description: "Combine text, graph, and vector search to find refactoring targets"
+      input_schema:
+        type: object
+        properties:
+          scope: { type: string }
+        required: [scope]
+      capability:
+        read_only: true
+      code: |
         todos = ctx.code_intelligence.text_search(
-            pattern="(TODO|FIXME|HACK):", scope=params["scope"]
+            pattern="(TODO|FIXME|HACK):", scope=params["scope"]
         )
-        complex_functions = ctx.code_intelligence.graph_query('''
+        complex_functions = ctx.code_intelligence.graph_query('''
             SELECT ?func ?complexity ?coverage WHERE {
                 ?func a code:Function ;
-                      code:hasComplexity ?complexity ;
-                      code:hasTestCoverage ?coverage .
-                FILTER(?complexity > 15 || ?coverage < 0.3)
+                      code:hasComplexity ?complexity ;
+                      code:hasTestCoverage ?coverage .
+                FILTER(?complexity > 15 || ?coverage < 0.3)
             } ORDER BY DESC(?complexity)
-        ''')
+        ''')
         smells = []
-        for pattern in ["duplicate code", "long method", "large class"]:
+        for pattern in ["duplicate code", "long method", "large class"]:
             smells.extend(ctx.code_intelligence.find_similar_code(
                 pattern=pattern, threshold=0.8
             ))
         return {
-            "high_priority": complex_functions[:5],
-            "technical_debt": todos,
-            "code_smells": smells,
-            "suggested_order": ctx.code_intelligence.rank_by_impact(
+            "high_priority": complex_functions[:5],
+            "technical_debt": todos,
+            "code_smells": smells,
+            "suggested_order": ctx.code_intelligence.rank_by_impact(
                 complex_functions + todos + smells
             )
         }
-```
+
##### 6. Real-time Index Synchronization The system maintains index freshness through immediate, proactive updates: -```python -class IndexSynchronizer: - def __init__(self): +

+class IndexSynchronizer:
+    def __init__(self):
         self.file_watcher = FileSystemWatcher()
         self.git_monitor = GitChangeMonitor()
         self.incremental_indexer = IncrementalIndexer()
     
-    def on_resource_added(self, resource: Resource, project: Project):
-        """When a resource is added to a project, index it immediately"""
-        # Full initial indexing - happens once when resource is added
-        with self.progress_reporter(f"Indexing {resource.name}") as progress:
+    def on_resource_added(self, resource: Resource, project: Project):
+        """When a resource is added to a project, index it immediately"""
+        # Full initial indexing - happens once when resource is added
+        with self.progress_reporter(f"Indexing {resource.name}") as progress:
             files = self.scan_resource(resource)
             total = len(files)
             
-            # Parallel indexing for performance
-            with ThreadPoolExecutor(max_workers=cpu_count()) as executor:
+            # Parallel indexing for performance
+            with ThreadPoolExecutor(max_workers=cpu_count()) as executor:
                 futures = []
                 
-                for i, file in enumerate(files):
+                for i, file in enumerate(files):
                     future = executor.submit(self.index_file_complete, file)
                     futures.append(future)
                     progress.update(i / total)
                 
-                # Wait for all indexing to complete
-                for future in futures:
+                # Wait for all indexing to complete
+                for future in futures:
                     future.result()
         
-        # Now set up watchers for incremental updates
+        # Now set up watchers for incremental updates
         self.setup_watchers(resource)
         
-        # Mark resource as indexed and ready
-        resource.indexing_status = "ready"
+        # Mark resource as indexed and ready
+        resource.indexing_status = "ready"
         self.notify_agents_index_ready(resource)
         
-        # CRITICAL: Agents can now immediately search this resource
-        # No "warming up" period - indices are complete and ready
+        # CRITICAL: Agents can now immediately search this resource
+        # No "warming up" period - indices are complete and ready
     
-    def index_file_complete(self, file_path: str):
-        """Comprehensive initial indexing of a file"""
-        # Parse file once
+    def index_file_complete(self, file_path: str):
+        """Comprehensive initial indexing of a file"""
+        # Parse file once
         ast = self.parse_file(file_path)
         
-        # Update all indices immediately
+        # Update all indices immediately
         self.update_text_index(file_path, ast)
         self.update_vector_embeddings(file_path, ast)
         self.update_graph_triples(file_path, ast)
         
-        # Extract and index all metadata
+        # Extract and index all metadata
         self.index_symbols(file_path, ast)
         self.index_dependencies(file_path, ast)
         self.index_complexity_metrics(file_path, ast)
     
-    def setup_watchers(self, project: Project):
-        # File system watching for immediate updates
+    def setup_watchers(self, project: Project):
+        # File system watching for immediate updates
         self.file_watcher.watch(
             path=project.root_path,
-            events=["create", "modify", "delete"],
+            events=["create", "modify", "delete"],
             callback=self.on_file_change
         )
         
-        # Git monitoring for batch updates (using linked git resource)
-        git_resource = project.get_linked_resource(type="git-checkout")
+        # Git monitoring for batch updates (using linked git resource)
+        git_resource = project.get_linked_resource(type="git-checkout")
         self.git_monitor.watch(
             repo=git_resource,
-            events=["commit", "merge", "rebase"],
+            events=["commit", "merge", "rebase"],
             callback=self.on_git_change
         )
     
-    def on_file_change(self, event: FileEvent):
-        # Quick incremental update
-        if event.type in ["create", "modify"]:
-            # Parse changed file
+    def on_file_change(self, event: FileEvent):
+        # Quick incremental update
+        if event.type in ["create", "modify"]:
+            # Parse changed file
             ast = self.parse_file(event.path)
             
-            # Update indices
+            # Update indices
             self.update_text_index(event.path, ast)
             self.update_vector_embeddings(event.path, ast)
             self.update_graph_triples(event.path, ast)
         
-        elif event.type == "delete":
+        elif event.type == "delete":
             self.remove_from_indices(event.path)
     
-    def on_git_change(self, event: GitEvent):
-        # Batch update for git operations
+    def on_git_change(self, event: GitEvent):
+        # Batch update for git operations
         changed_files = event.get_changed_files()
         
-        # Optimize batch processing
-        with self.batch_updater() as updater:
-            for file in changed_files:
+        # Optimize batch processing
+        with self.batch_updater() as updater:
+            for file in changed_files:
                 updater.queue_update(file)
             
-            # Process in parallel
-            updater.execute(parallel=True)
+            # Process in parallel
+            updater.execute(parallel=True)
     
-    def update_graph_triples(self, file_path: str, ast: AST):
-        # Generate RDF triples from AST
+    def update_graph_triples(self, file_path: str, ast: AST):
+        # Generate RDF triples from AST
         triples = []
         
-        # Module-level triples
+        # Module-level triples
         module_uri = self.uri_for_file(file_path)
-        for import_stmt in ast.imports:
+        for import_stmt in ast.imports:
             imported_uri = self.resolve_import(import_stmt)
-            triples.append((module_uri, "code:imports", imported_uri))
+            triples.append((module_uri, "code:imports", imported_uri))
         
-        # Function-level triples
-        for func in ast.functions:
+        # Function-level triples
+        for func in ast.functions:
             func_uri = self.uri_for_function(func)
-            triples.append((module_uri, "code:contains", func_uri))
-            triples.append((func_uri, "a", "code:Function"))
-            triples.append((func_uri, "code:hasComplexity", func.complexity))
+            triples.append((module_uri, "code:contains", func_uri))
+            triples.append((func_uri, "a", "code:Function"))
+            triples.append((func_uri, "code:hasComplexity", func.complexity))
             
-            # Call relationships
-            for call in func.calls:
+            # Call relationships
+            for call in func.calls:
                 called_uri = self.resolve_call(call)
-                triples.append((func_uri, "code:calls", called_uri))
+                triples.append((func_uri, "code:calls", called_uri))
         
-        # Update graph store
+        # Update graph store
         self.graph_store.update_triples(triples)
-```
+
##### 7. Fallback to Traditional Search When advanced features are unavailable, the system gracefully degrades: -```python -class FallbackSearchProvider: - def search(self, query: str, resources: List[Resource]) -> SearchResults: - # Try advanced search first - try: - if self.vector_index.is_available(): - return self.vector_search(query, resources) - except ServiceUnavailable: - pass +

+class FallbackSearchProvider:
+    def search(self, query: str, resources: List[Resource]) -> SearchResults:
+        # Try advanced search first
+        try:
+            if self.vector_index.is_available():
+                return self.vector_search(query, resources)
+        except ServiceUnavailable:
+            pass
         
-        # Fallback to graph search
-        try:
-            if self.graph_index.is_available():
-                return self.graph_search(query, resources)
-        except ServiceUnavailable:
-            pass
+        # Fallback to graph search
+        try:
+            if self.graph_index.is_available():
+                return self.graph_search(query, resources)
+        except ServiceUnavailable:
+            pass
         
-        # Ultimate fallback: grep-like text search
-        return self.basic_text_search(query, resources)
+        # Ultimate fallback: grep-like text search
+        return self.basic_text_search(query, resources)
     
-    def basic_text_search(self, query: str, resources: List[Resource]):
-        # Use ripgrep or similar for fast text search
+    def basic_text_search(self, query: str, resources: List[Resource]):
+        # Use ripgrep or similar for fast text search
         results = []
         
-        for resource in resources:
+        for resource in resources:
             matches = ripgrep.search(
                 pattern=query,
                 path=resource.path,
                 context_lines=3
             )
             
-            for match in matches:
+            for match in matches:
                 results.append(SearchResult(
                     file=match.file,
                     line=match.line,
                     content=match.content,
-                    score=1.0  # Basic scoring
+                    score=1.0  # Basic scoring
                 ))
         
-        return results
-```
+        return results
+
#### Index Lifecycle The system follows a clear lifecycle for index management: -```yaml +

 Index Lifecycle:
-  1_resource_added:
-    trigger: "agents resource add / agents project link-resource"
-    action: "Immediate full indexing"
-    duration: "Depends on size (10K files ~1 minute)"
-    result: "All indices ready for instant search"
+  1_resource_added:
+    trigger: "agents resource add / agents project link-resource"
+    action: "Immediate full indexing"
+    duration: "Depends on size (10K files ~1 minute)"
+    result: "All indices ready for instant search"
     
-  2_code_changed:
-    trigger: "File modification detected"
-    action: "Immediate incremental update"
-    duration: "Milliseconds per file"
-    result: "Indices stay synchronized"
+  2_code_changed:
+    trigger: "File modification detected"
+    action: "Immediate incremental update"
+    duration: "Milliseconds per file"
+    result: "Indices stay synchronized"
     
-  3_resource_removed:
-    trigger: "agents project unlink-resource / agents resource remove"
-    action: "Immediate index cleanup"
-    duration: "Seconds"
-    result: "No stale data in indices"
+  3_resource_removed:
+    trigger: "agents project unlink-resource / agents resource remove"
+    action: "Immediate index cleanup"
+    duration: "Seconds"
+    result: "No stale data in indices"
     
-  4_maintenance:
-    trigger: "Scheduled or manual"
-    action: "Reindex for consistency"
-    duration: "Background process"
-    result: "Indices optimized and verified"
+  4_maintenance:
+    trigger: "Scheduled or manual"
+    action: "Reindex for consistency"
+    duration: "Background process"
+    result: "Indices optimized and verified"
 
 Key Guarantees:
-  - "No search happens on stale data"
-  - "No 'index building' delays during agent execution"
-  - "Changes visible in search immediately"
-  - "Initial indexing is a one-time cost per resource"
-```
+  - "No search happens on stale data"
+  - "No 'index building' delays during agent execution"
+  - "Changes visible in search immediately"
+  - "Initial indexing is a one-time cost per resource"
+
#### Integration with Context Tiers The Code Intelligence system directly feeds into the three-tier context architecture: -```yaml +

 Context Tier Integration:
-  hot_tier:
-    source: "Real-time results from code intelligence"
-    content:
+  hot_tier:
+    source: "Real-time results from code intelligence"
+    content:
       - Currently edited files
       - Direct dependencies
       - Immediately relevant functions
     
-  warm_tier:
-    source: "Indexed embeddings and graph queries"
-    content:
+  warm_tier:
+    source: "Indexed embeddings and graph queries"
+    content:
       - Recent search results
       - Cached graph traversals
       - Vector similarity matches
       - Active decision contexts
     
-  cold_tier:
-    source: "Historical indices and compressed data"
-    content:
+  cold_tier:
+    source: "Historical indices and compressed data"
+    content:
       - Previous plan analyses
       - Archived dependency graphs
       - Historical refactoring patterns
       - Learned codebase conventions
-```
+
#### Performance Characteristics The system maintains pre-computed indices for instant search performance: -```yaml +

 Performance Metrics:
-  initial_indexing_speed:
-    text_index: "10,000 files/minute"
-    vector_index: "1,000 files/minute (with GPU)"
-    graph_index: "5,000 files/minute"
+  initial_indexing_speed:
+    text_index: "10,000 files/minute"
+    vector_index: "1,000 files/minute (with GPU)"
+    graph_index: "5,000 files/minute"
   
-  query_performance:
-    text_search: "< 100ms for 1M files"
-    vector_search: "< 200ms for 10M embeddings"
-    graph_traversal: "< 500ms for 3-hop queries"
+  query_performance:
+    text_search: "< 100ms for 1M files"
+    vector_search: "< 200ms for 10M embeddings"
+    graph_traversal: "< 500ms for 3-hop queries"
     
-  storage_requirements:
-    text_index: "~10% of source size"
-    vector_index: "~1GB per 100K functions"
-    graph_store: "~100MB per 10K files"
+  storage_requirements:
+    text_index: "~10% of source size"
+    vector_index: "~1GB per 100K functions"
+    graph_store: "~100MB per 10K files"
     
-  scalability:
-    max_files: "No hard limit (tested to 10M files)"
-    max_graph_size: "1B+ triples"
-    max_vectors: "100M+ embeddings"
-```
+  scalability:
+    max_files: "No hard limit (tested to 10M files)"
+    max_graph_size: "1B+ triples"
+    max_vectors: "100M+ embeddings"
+
#### Progressive Enhancement Path Organizations can adopt Code Intelligence features progressively. At each stage, existing resources are reindexed to take advantage of new capabilities: -```yaml -adoption_stages: - stage_1_basic: - features: ["text search", "file watching"] - requirements: ["ripgrep", "sqlite"] - initial_setup: "Index all text content on resource add" - benefit: "Instant exact-match search" +

+adoption_stages:
+  stage_1_basic:
+    features: ["text search", "file watching"]
+    requirements: ["ripgrep", "sqlite"]
+    initial_setup: "Index all text content on resource add"
+    benefit: "Instant exact-match search"
     
-  stage_2_semantic:
-    features: ["vector embeddings", "similarity search"]
-    requirements: ["embedding model", "vector DB"]
-    initial_setup: "Generate embeddings for all code (one-time cost)"
-    benefit: "Instant semantic similarity search"
+  stage_2_semantic:
+    features: ["vector embeddings", "similarity search"]
+    requirements: ["embedding model", "vector DB"]
+    initial_setup: "Generate embeddings for all code (one-time cost)"
+    benefit: "Instant semantic similarity search"
     
-  stage_3_structural:
-    features: ["RDF graph", "relationship queries"]
-    requirements: ["graph database", "language analyzers"]
-    initial_setup: "Parse and build complete knowledge graph"
-    benefit: "Instant relationship queries"
+  stage_3_structural:
+    features: ["RDF graph", "relationship queries"]
+    requirements: ["graph database", "language analyzers"]
+    initial_setup: "Parse and build complete knowledge graph"
+    benefit: "Instant relationship queries"
     
-  stage_4_intelligent:
-    features: ["ML-driven ranking", "automated analysis"]
-    requirements: ["GPU", "training data"]
-    initial_setup: "Pre-compute ML features and rankings"
-    benefit: "Instant intelligent suggestions"
+  stage_4_intelligent:
+    features: ["ML-driven ranking", "automated analysis"]
+    requirements: ["GPU", "training data"]
+    initial_setup: "Pre-compute ML features and rankings"
+    benefit: "Instant intelligent suggestions"
     
-  stage_5_custom:
-    features: ["Domain-specific ontologies", "Custom analyzers"]
-    requirements: ["Domain expertise", "Custom development"]
-    initial_setup: "Build domain-specific indices"
-    benefit: "Instant domain-aware intelligence"
-```
+  stage_5_custom:
+    features: ["Domain-specific ontologies", "Custom analyzers"]
+    requirements: ["Domain expertise", "Custom development"]
+    initial_setup: "Build domain-specific indices"
+    benefit: "Instant domain-aware intelligence"
+
This Code Intelligence & Context Discovery system ensures that CleverAgents can efficiently work with codebases of any size, providing agents with the contextual understanding they need to make intelligent decisions about code changes, refactoring, and feature development. @@ -9419,103 +10172,2733 @@ This strongly suggests CleverAgents should define: * an "initial context recipe" per project type (codebase vs documents vs infra), * iterative context refinement loops during strategize/execute. +### Output Rendering Framework + +#### Overview + +CleverAgents uses a unified **Output Rendering Framework** to decouple command output data from its visual presentation. Every CLI command produces structured output through a common abstraction layer, and the active **format** determines how that output is rendered to the terminal (or piped to external consumers). The format is set via the global `--format` flag, the `format` config key, or defaults to `rich`. + +The framework is **reactive-first**: commands do not build a static data structure and hand it to a renderer. Instead, commands open an **output session**, create **element handles** for each piece of output (a panel, a table, a progress indicator), and write data to those handles — potentially from multiple concurrent producers. The session coordinates with a **materialization strategy** selected by the active format, which decides *when* and *how* each element's content reaches the terminal. A `rich` session renders updates in-place as they arrive; a `plain` session buffers each element and flushes sequentially; a `json` session accumulates everything and serializes once at the end. **Producer code is format-agnostic** — it writes to handles without knowing which format is active. + +This architecture is designed for modularity, extensibility, and future-proofing — the same session-based output can be consumed by the CLI, a future TUI, a web frontend, or programmatic integrations. The design uses a pipeline of composable stages: **session lifecycle management**, **typed element handles**, **event-driven materialization**, and **format-specific element rendering**. + +#### Architecture + +##### Rendering Pipeline + +All CLI output flows through a five-stage reactive pipeline: + +

+Command Logic ──► OutputSession ──► ElementHandles ──► MaterializationStrategy ──► Terminal/Pipe
+                  (lifecycle)       (typed producers)   (format-driven policy)      (stdout/stderr)
+
+ +1. **Command Logic** opens an `OutputSession` and creates typed **element handles** — `PanelHandle`, `TableHandle`, `ProgressHandle`, etc. — for each piece of output the command will produce. Handles are created in **declaration order**, which determines the canonical order in which elements appear in sequential formats. + +2. **OutputSession** is the central coordinator. It owns the set of active handles, tracks their lifecycle (open → writing → closed), emits `ElementEvent` objects to the active materialization strategy, and provides a `snapshot()` method that returns a static `StructuredOutput` representing the accumulated state at any point in time. + +3. **ElementHandles** are the producer-facing API. Each handle is typed for a specific element kind (panel, table, tree, etc.) and exposes write methods appropriate to that kind (`add_row()`, `set_entry()`, `set_step_status()`, etc.). Handles are **thread-safe** — multiple concurrent coroutines or threads can write to different handles simultaneously. Handles are **format-agnostic** — the producer never knows or cares which format is active. + +4. **MaterializationStrategy** is a polymorphic observer selected by the active format. It receives `ElementEvent` notifications from the session and decides *when* and *how* to render content. Each strategy delegates the actual visual rendering of an element's accumulated state to a paired **ElementRenderer**. + +5. **Terminal/Pipe** receives the final byte stream. The framework auto-detects whether stdout is a TTY and degrades gracefully (e.g., `rich` falls back to `table` when piped to a non-TTY unless `--format rich` was explicitly set). + +##### OutputSession + +The `OutputSession` is the core abstraction that replaces direct construction of static output objects. Commands receive a session (typically injected by the CLI framework) and interact with it throughout their execution: + +

+class OutputSession:
+    """A live output document that coordinates element production and materialization.
+    
+    The session manages the lifecycle of all output elements for a single command
+    invocation. It is the bridge between format-agnostic producer code and the
+    format-specific materialization strategy.
+    
+    Thread Safety:
+        The session is thread-safe. Multiple producers may create and write to
+        handles concurrently. The session serializes event delivery to the
+        materialization strategy using an internal event queue.
+    
+    Lifecycle:
+        session = OutputSession.open(command, strategy)
+        handle_a = session.panel("Title")       # create handles
+        handle_b = session.table("Results", ...) 
+        handle_a.set_entry(...)                  # write to handles (concurrent OK)
+        handle_b.add_row(...)
+        handle_a.close()                         # close handles when done
+        handle_b.close()
+        session.close()                          # finalize the session
+    """
+    
+    # --- Session lifecycle ---
+    
+    command: str                                  # The command that owns this session
+    session_id: str                               # Unique session identifier (ULID)
+    created_at: datetime                          # Session creation timestamp
+    
+    _strategy: MaterializationStrategy            # The active materialization strategy
+    _handles: OrderedDict[str, ElementHandle]     # handle_id → handle, in declaration order
+    _event_queue: asyncio.Queue[ElementEvent]     # Internal event queue for serialization
+    _state: SessionState                          # "open" | "closing" | "closed"
+    _lock: threading.Lock                         # Protects handle creation/removal
+    
+    @classmethod
+    def open(cls, command: str, strategy: MaterializationStrategy,
+             metadata: dict | None = None) -> "OutputSession":
+        """Open a new output session.
+        
+        Called by the CLI framework before command execution. The strategy is
+        selected based on the resolved format (see Format Resolution).
+        
+        Args:
+            command: The command string (e.g., "project show").
+            strategy: The materialization strategy for the active format.
+            metadata: Optional command metadata (user, timestamp, etc.).
+        
+        Returns:
+            A new OutputSession ready for element creation.
+        """
+        ...
+    
+    # --- Element handle factories ---
+    # Each factory creates a typed handle, registers it with the session in
+    # declaration order, and emits an ElementCreated event to the strategy.
+    
+    def panel(self, title: str, *,
+              border_style: str = "rounded",
+              priority: str = "normal",
+              collapse_hint: str = "auto",
+              metadata: dict | None = None) -> "PanelHandle":
+        """Create a panel element handle for key-value pair output."""
+        ...
+    
+    def table(self, title: str | None, *,
+              columns: list["ColumnDef"],
+              summary: dict | None = None,
+              max_rows_hint: int | None = None,
+              sort_key: str | None = None,
+              priority: str = "normal",
+              collapse_hint: str = "auto",
+              metadata: dict | None = None) -> "TableHandle":
+        """Create a table element handle for tabular data."""
+        ...
+    
+    def tree(self, root_label: str, *,
+             root_style: str | None = None,
+             max_depth_hint: int | None = None,
+             show_guides: bool = True,
+             priority: str = "normal",
+             collapse_hint: str = "auto",
+             metadata: dict | None = None) -> "TreeHandle":
+        """Create a tree element handle for hierarchical data."""
+        ...
+    
+    def progress(self, label: str, *,
+                 total: int | None = None,
+                 indeterminate: bool = False,
+                 steps: list[str] | None = None,
+                 priority: str = "normal",
+                 metadata: dict | None = None) -> "ProgressHandle":
+        """Create a progress indicator handle.
+        
+        Args:
+            label: Display label for the progress indicator.
+            total: Total units of work (None for indeterminate).
+            indeterminate: If True, show a spinner instead of a progress bar.
+            steps: Named steps to track (creates ProgressStep objects with
+                   initial status "pending").
+        """
+        ...
+    
+    def status(self, message: str, *,
+               level: str = "info",
+               detail: str | None = None,
+               priority: str = "normal",
+               metadata: dict | None = None) -> "StatusHandle":
+        """Create a status message handle."""
+        ...
+    
+    def text(self, content: str = "", *,
+             wrap: bool = True,
+             indent: int = 0,
+             priority: str = "normal",
+             metadata: dict | None = None) -> "TextHandle":
+        """Create a text block handle."""
+        ...
+    
+    def code(self, content: str = "", *,
+             language: str | None = None,
+             line_numbers: bool = False,
+             highlight_lines: list[int] | None = None,
+             priority: str = "normal",
+             metadata: dict | None = None) -> "CodeHandle":
+        """Create a code block handle."""
+        ...
+    
+    def diff(self, *,
+             file_a: str | None = None,
+             file_b: str | None = None,
+             priority: str = "normal",
+             metadata: dict | None = None) -> "DiffHandle":
+        """Create a diff block handle."""
+        ...
+    
+    def separator(self, style: str = "line") -> "SeparatorHandle":
+        """Create a visual separator. Separators are auto-closed on creation."""
+        ...
+    
+    def action_hint(self, commands: list[str],
+                    description: str | None = None) -> "ActionHintHandle":
+        """Create an action hint. Action hints are auto-closed on creation."""
+        ...
+    
+    # --- Session operations ---
+    
+    def snapshot(self) -> "StructuredOutput":
+        """Return a static snapshot of all elements accumulated so far.
+        
+        The snapshot captures the current state of every handle (open or closed)
+        as a StructuredOutput object. This is used by accumulate-mode strategies
+        (json/yaml) at session end, and is available at any time for logging,
+        debugging, or programmatic inspection.
+        """
+        ...
+    
+    def close(self, *, exit_code: int = 0) -> "StructuredOutput":
+        """Close the session and finalize all output.
+        
+        Any handles still open are force-closed (with a warning logged).
+        Emits a SessionEnd event to the strategy. Returns the final
+        StructuredOutput snapshot.
+        
+        Args:
+            exit_code: The command's exit code (included in the snapshot).
+        
+        Returns:
+            The final StructuredOutput snapshot.
+        """
+        ...
+    
+    # --- Context manager support ---
+    
+    def __enter__(self) -> "OutputSession":
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Auto-close session on context exit.
+        
+        If exiting due to an exception, sets exit_code to 1 and emits an
+        error status element before closing.
+        """
+        ...
+
+ +##### Element Handles + +Element handles are the producer-facing API. Each handle type wraps a specific element kind and provides methods appropriate to that kind. All handles share a common base: + +

+class ElementHandle(Generic[E]):
+    """Base class for all element handles.
+    
+    An element handle is a write-only view of an output element. Producers use
+    handles to incrementally build element content without knowledge of the
+    active format or materialization strategy.
+    
+    Type Parameter:
+        E: The OutputElement subclass this handle wraps (e.g., Panel, Table).
+    
+    Thread Safety:
+        Individual handle methods are thread-safe. Multiple threads may call
+        methods on *different* handles concurrently. Concurrent writes to the
+        *same* handle are serialized via an internal lock.
+    
+    Lifecycle:
+        handle = session.table(...)    # Created by session factory
+        handle.add_row(...)            # Write operations (zero or more)
+        handle.close()                 # Finalize (required unless auto-closed)
+    
+    Closed Handle Behavior:
+        Calling any write method on a closed handle raises ElementClosedError.
+    """
+    
+    handle_id: str                       # Unique handle identifier (ULID)
+    element_type: str                    # Semantic type ("panel", "table", etc.)
+    declaration_index: int               # Position in session's declaration order
+    
+    _session: OutputSession              # Owning session (for event emission)
+    _element: E                          # The accumulated element state
+    _state: HandleState                  # "open" | "closed"
+    _lock: threading.Lock                # Serializes writes to this handle
+    
+    def close(self) -> None:
+        """Close this handle, signaling that no more data will be written.
+        
+        Emits an ElementClosed event to the materialization strategy.
+        For buffered strategies, this triggers rendering of the element.
+        """
+        ...
+    
+    @property
+    def is_open(self) -> bool:
+        """Whether this handle is still accepting writes."""
+        ...
+    
+    @property
+    def element(self) -> E:
+        """The accumulated element state (read-only snapshot)."""
+        ...
+    
+    def __enter__(self) -> Self:
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Auto-close handle on context exit."""
+        if self.is_open:
+            self.close()
+
+
+class PanelHandle(ElementHandle[Panel]):
+    """Handle for building a Panel element incrementally.
+    
+    Panels are titled groups of key-value pairs. Entries can be added,
+    updated, or removed after creation.
+    """
+    
+    def set_entry(self, key: str, value: str, *,
+                  style_hint: str | None = None,
+                  icon: str | None = None) -> None:
+        """Set or update a key-value entry in the panel.
+        
+        If an entry with the given key already exists, it is updated.
+        Otherwise, a new entry is appended.
+        
+        Emits an ElementUpdated event.
+        """
+        ...
+    
+    def set_entries(self, entries: dict[str, str], *,
+                    style_hints: dict[str, str] | None = None) -> None:
+        """Set multiple entries at once (batch update). Emits a single event."""
+        ...
+    
+    def remove_entry(self, key: str) -> None:
+        """Remove an entry by key. Emits an ElementUpdated event."""
+        ...
+
+
+class TableHandle(ElementHandle[Table]):
+    """Handle for building a Table element incrementally.
+    
+    Tables are the primary element for streamed data. Rows can be added
+    one at a time or in batches as data becomes available from queries,
+    API calls, or concurrent operations.
+    """
+    
+    def add_row(self, row: dict) -> None:
+        """Append a single row to the table.
+        
+        The row dict maps column names to cell values. Missing columns
+        are filled with None. Extra columns not in the schema are ignored.
+        
+        Emits an ElementUpdated event (type=row_added).
+        """
+        ...
+    
+    def add_rows(self, rows: list[dict]) -> None:
+        """Append multiple rows in a batch. Emits a single ElementUpdated event."""
+        ...
+    
+    def set_summary(self, summary: dict) -> None:
+        """Set or update the summary/aggregation row. Emits an ElementUpdated event."""
+        ...
+    
+    def set_sort_key(self, column: str, *, descending: bool = False) -> None:
+        """Change the sort key. Emits an ElementUpdated event."""
+        ...
+
+
+class TreeHandle(ElementHandle[Tree]):
+    """Handle for building a Tree element incrementally.
+    
+    Trees are built by adding child nodes to existing nodes. The root node
+    is created with the handle. Subtrees can be constructed incrementally
+    as hierarchical data is discovered.
+    """
+    
+    def add_child(self, parent_path: str | None, label: str, *,
+                  style_hint: str | None = None,
+                  collapsed: bool = False,
+                  metadata: dict | None = None) -> str:
+        """Add a child node to the tree.
+        
+        Args:
+            parent_path: Slash-separated path to the parent node (None = root).
+            label: Display label for the new node.
+            style_hint: Optional color/style hint.
+            collapsed: Whether this node starts collapsed in interactive renderers.
+            metadata: Arbitrary data attached to the node.
+        
+        Returns:
+            The full path to the newly created node (for use as parent_path
+            in subsequent add_child calls).
+        
+        Emits an ElementUpdated event.
+        """
+        ...
+    
+    def set_node_style(self, path: str, style_hint: str) -> None:
+        """Update the style of an existing node. Emits an ElementUpdated event."""
+        ...
+
+
+class ProgressHandle(ElementHandle[ProgressIndicator]):
+    """Handle for updating a ProgressIndicator element.
+    
+    Progress handles are unique in that they are expected to receive many
+    rapid updates. The materialization strategy may throttle update events
+    to avoid overwhelming the terminal (e.g., limiting redraws to 10/sec).
+    """
+    
+    def set_progress(self, current: int, total: int | None = None) -> None:
+        """Update the progress counter.
+        
+        Args:
+            current: Current progress value.
+            total: Total value (can change, e.g., when total is discovered late).
+        
+        Emits an ElementUpdated event (may be throttled by the strategy).
+        """
+        ...
+    
+    def set_step_status(self, step_label: str, status: str) -> None:
+        """Update the status of a named step.
+        
+        Args:
+            step_label: The label of the step to update.
+            status: New status — "pending" | "active" | "done" | "error" | "skipped".
+        
+        Emits an ElementUpdated event.
+        """
+        ...
+    
+    def set_label(self, label: str) -> None:
+        """Update the progress label text. Emits an ElementUpdated event."""
+        ...
+    
+    def increment(self, delta: int = 1) -> None:
+        """Increment progress by delta. Convenience wrapper around set_progress."""
+        ...
+
+
+class StatusHandle(ElementHandle[StatusMessage]):
+    """Handle for a status message.
+    
+    Status handles are typically created and immediately closed (fire-and-forget
+    messages). However, they can be kept open for messages that may be revised
+    (e.g., a "Working..." status that becomes "Done" or "Failed").
+    """
+    
+    def set_message(self, message: str) -> None:
+        """Update the status message text. Emits an ElementUpdated event."""
+        ...
+    
+    def set_level(self, level: str) -> None:
+        """Change the status level. Emits an ElementUpdated event."""
+        ...
+    
+    def set_detail(self, detail: str | None) -> None:
+        """Set or clear the detail text. Emits an ElementUpdated event."""
+        ...
+
+
+class TextHandle(ElementHandle[TextBlock]):
+    """Handle for a text block. Supports appending text incrementally."""
+    
+    def append(self, text: str) -> None:
+        """Append text to the block. Emits an ElementUpdated event."""
+        ...
+    
+    def set_content(self, content: str) -> None:
+        """Replace the entire content. Emits an ElementUpdated event."""
+        ...
+
+
+class CodeHandle(ElementHandle[CodeBlock]):
+    """Handle for a code block."""
+    
+    def set_content(self, content: str) -> None:
+        """Set the code content. Emits an ElementUpdated event."""
+        ...
+    
+    def set_language(self, language: str) -> None:
+        """Set the language for syntax highlighting. Emits an ElementUpdated event."""
+        ...
+    
+    def set_highlight_lines(self, lines: list[int]) -> None:
+        """Set lines to highlight. Emits an ElementUpdated event."""
+        ...
+
+
+class DiffHandle(ElementHandle[DiffBlock]):
+    """Handle for a diff block. Hunks can be added incrementally."""
+    
+    def add_hunk(self, header: str, lines: list["DiffLine"]) -> None:
+        """Add a diff hunk. Emits an ElementUpdated event."""
+        ...
+    
+    def set_stats(self, insertions: int, deletions: int, **extra: int) -> None:
+        """Set diff statistics. Emits an ElementUpdated event."""
+        ...
+
+ +##### Element Events + +Element handles communicate with the materialization strategy through a typed event system. Events are the sole interface between production (handles) and consumption (strategy) — this indirection is what enables format-agnostic producer code: + +

+class ElementEvent:
+    """Base class for all events emitted by element handles."""
+    event_type: str                      # "created" | "updated" | "closed"
+    handle_id: str                       # The handle that emitted this event
+    element_type: str                    # The element kind ("panel", "table", etc.)
+    timestamp: datetime                  # When the event occurred
+    session_id: str                      # The owning session
+
+
+class ElementCreated(ElementEvent):
+    """Emitted when a new element handle is created via a session factory."""
+    event_type = "created"
+    declaration_index: int               # Position in session declaration order
+    initial_state: OutputElement         # The element's initial state
+
+
+class ElementUpdated(ElementEvent):
+    """Emitted when data is written to an element handle."""
+    event_type = "updated"
+    update_type: str                     # Kind-specific: "entry_set", "row_added",
+                                         #   "progress_changed", "step_status_changed", etc.
+    delta: dict                          # The change payload (what was added/modified)
+    element_snapshot: OutputElement      # The full element state after this update
+
+
+class ElementClosed(ElementEvent):
+    """Emitted when an element handle is closed (no more data will arrive)."""
+    event_type = "closed"
+    final_state: OutputElement           # The element's final accumulated state
+
+
+class SessionEnd(ElementEvent):
+    """Emitted when the session itself is closed."""
+    event_type = "session_end"
+    exit_code: int
+    snapshot: "StructuredOutput"         # The complete accumulated output
+
+ +##### Element Data Model (Snapshot Types) + +Each element handle accumulates state into a typed **snapshot object**. These are the data classes that represent a fully-built element — they are what the `ElementRenderer` receives when it is time to paint. They are also the building blocks of the `StructuredOutput` returned by `session.snapshot()`: + +

+class OutputElement:
+    """Base class for all output element snapshot types."""
+    element_type: str                    # Semantic type identifier
+    metadata: dict                       # Arbitrary metadata (timestamps, IDs, etc.)
+    priority: str = "normal"             # "critical" | "normal" | "supplementary"
+    collapse_hint: str = "auto"          # "always" | "auto" | "never" — guidance for renderers
+                                         #   on whether this element can be collapsed/hidden
+
+class Panel(OutputElement):
+    """A titled group of key-value pairs."""
+    element_type = "panel"
+    title: str
+    entries: list[PanelEntry]            # Each entry: key, value, style_hint (color, icon, etc.)
+    border_style: str = "rounded"        # "rounded" | "square" | "heavy" | "none"
+
+class PanelEntry:
+    """A single key-value pair within a Panel."""
+    key: str
+    value: str
+    style_hint: str | None = None        # Color/style for the value (e.g., "success", "warning")
+    icon: str | None = None              # Optional icon/prefix character
+
+class Table(OutputElement):
+    """A tabular data set with typed columns."""
+    element_type = "table"
+    title: str | None
+    columns: list[ColumnDef]             # name, type, alignment, width_hint, sortable
+    rows: list[dict]                     # Column name → cell value
+    summary: dict | None                 # Optional aggregation row (totals, counts)
+    max_rows_hint: int | None            # Suggest truncation for large datasets
+    sort_key: str | None                 # Default sort column
+
+class ColumnDef:
+    """Schema for a single table column."""
+    name: str                            # Column display name
+    type: str = "string"                 # "string" | "number" | "boolean" | "datetime" | "id"
+    alignment: str = "left"              # "left" | "right" | "center"
+    width_hint: int | None = None        # Suggested character width (None = auto)
+    sortable: bool = False               # Whether this column can be sorted
+    style_hint: str | None = None        # Default style for cells in this column
+
+class Tree(OutputElement):
+    """A hierarchical tree structure."""
+    element_type = "tree"
+    root: TreeNode                       # Recursive node structure
+    max_depth_hint: int | None           # Suggest depth truncation
+    show_guides: bool = True             # Whether to show tree guide lines
+
+class TreeNode:
+    """A node in a tree structure."""
+    label: str
+    style_hint: str | None               # Color/style for this node
+    children: list["TreeNode"]
+    collapsed: bool = False              # Hint: start collapsed in interactive renderers
+    metadata: dict                       # Arbitrary data attached to the node
+
+class StatusMessage(OutputElement):
+    """A status line (success, warning, error, info)."""
+    element_type = "status"
+    level: str                           # "ok" | "warn" | "error" | "info"
+    message: str
+    detail: str | None                   # Optional detail text
+
+class ProgressIndicator(OutputElement):
+    """A progress bar or spinner for long-running operations."""
+    element_type = "progress"
+    label: str
+    current: int | None
+    total: int | None
+    indeterminate: bool = False          # Spinner mode vs. progress bar mode
+    steps: list[ProgressStep] | None     # Named steps with status (pending/active/done)
+
+class ProgressStep:
+    """A named step within a progress indicator."""
+    label: str
+    status: str                          # "pending" | "active" | "done" | "error" | "skipped"
+
+class CodeBlock(OutputElement):
+    """A block of source code with optional syntax highlighting."""
+    element_type = "code"
+    content: str
+    language: str | None                 # For syntax highlighting
+    line_numbers: bool = False
+    highlight_lines: list[int] | None    # Lines to emphasize
+
+class DiffBlock(OutputElement):
+    """A unified diff display."""
+    element_type = "diff"
+    hunks: list[DiffHunk]
+    file_a: str | None
+    file_b: str | None
+    stats: dict | None                   # insertions, deletions, etc.
+
+class DiffHunk:
+    """A single hunk within a diff."""
+    header: str                          # @@ line range @@
+    lines: list[DiffLine]
+
+class DiffLine:
+    """A single line in a diff hunk."""
+    type: str                            # "context" | "add" | "remove"
+    content: str
+    line_number_old: int | None
+    line_number_new: int | None
+
+class TextBlock(OutputElement):
+    """A free-form text block (descriptions, rationale, etc.)."""
+    element_type = "text"
+    content: str
+    wrap: bool = True
+    indent: int = 0
+
+class Separator(OutputElement):
+    """A visual separator between logical groups."""
+    element_type = "separator"
+    style: str = "line"                  # "line" | "blank" | "double"
+
+class ActionHint(OutputElement):
+    """A suggested next-step action for the user."""
+    element_type = "action_hint"
+    commands: list[str]                  # Suggested CLI commands
+    description: str | None
+
+class StructuredOutput:
+    """Static snapshot of a complete command output.
+    
+    This is the accumulated state of all elements at a point in time.
+    It is produced by OutputSession.snapshot() and OutputSession.close().
+    
+    Uses:
+    - Final serialization for json/yaml formats
+    - Logging and audit trails
+    - Programmatic inspection and testing
+    - TUI widget data binding (initial state)
+    """
+    command: str                         # The command that produced this output
+    session_id: str                      # The session that produced this output
+    elements: list[OutputElement]        # Ordered list of element snapshots
+    exit_code: int = 0
+    timing: dict | None                  # start_time, end_time, duration
+    metadata: dict                       # command-specific metadata
+
+ +##### Materialization Strategies + +The materialization strategy is the format-side counterpart to the output session. It receives element events and decides *when* and *how* to render content. Each strategy is paired with an `ElementRenderer` that handles the actual visual formatting of individual elements. + +The strategy pattern creates a clean separation between **timing/ordering policy** (when to render) and **visual formatting** (how to render). This means the same `PlainElementRenderer` can be used whether elements arrive all-at-once or are streamed concurrently — the strategy handles the coordination. + +

+class MaterializationStrategy(Protocol):
+    """Interface for format-driven output materialization.
+    
+    A materialization strategy receives element lifecycle events from the
+    OutputSession and decides when to render element content to the output
+    stream. Strategies do not render elements themselves — they delegate
+    to a paired ElementRenderer at the appropriate time.
+    
+    The strategy is the mechanism by which format-agnostic producer code
+    produces correct output regardless of format. The producer writes to
+    handles; the strategy decides what reaches the terminal and when.
+    """
+    
+    strategy_name: str                   # "live" | "sequential_buffer" | "accumulate"
+    
+    def bind(self, renderer: "ElementRenderer",
+             terminal_caps: "TerminalCapabilities") -> None:
+        """Bind this strategy to a renderer and terminal capabilities.
+        
+        Called once during format resolution, before the session opens.
+        The strategy retains a reference to the renderer for use during
+        event handling. The output stream is provided separately via
+        on_session_begin, since the session owns the stream.
+        """
+        ...
+    
+    def on_session_begin(self, session: OutputSession, stream: IO) -> None:
+        """Called when the session opens. The strategy receives the output
+        stream and may write preamble (e.g., opening JSON bracket)."""
+        ...
+    
+    def on_element_created(self, event: ElementCreated) -> None:
+        """Called when a new element handle is created."""
+        ...
+    
+    def on_element_updated(self, event: ElementUpdated) -> None:
+        """Called when data is written to an element handle."""
+        ...
+    
+    def on_element_closed(self, event: ElementClosed) -> None:
+        """Called when an element handle is closed."""
+        ...
+    
+    def on_session_end(self, event: SessionEnd) -> None:
+        """Called when the session closes. The strategy may write epilogue."""
+        ...
+
+
+class LiveMaterializer(MaterializationStrategy):
+    """Materialization strategy for the `rich` format.
+    
+    Renders element updates in real-time using terminal cursor movement.
+    Multiple elements can be visually active and updating simultaneously.
+    The terminal display is a live document that is rewritten in place.
+    
+    Behavior:
+    - on_element_created: Allocates screen region for the element, renders
+      initial (possibly empty) visual state.
+    - on_element_updated: Re-renders the element in place using cursor
+      movement. For progress indicators, updates may be throttled to a
+      maximum refresh rate (default: 15 fps) to avoid terminal flooding.
+    - on_element_closed: Renders the final state and freezes the screen
+      region (no further updates). May apply a visual transition (e.g.,
+      spinner resolves to a checkmark).
+    - on_session_end: Finalizes the display, moves cursor to end, and
+      restores normal terminal scrolling.
+    
+    Screen Layout:
+    Elements are arranged vertically in declaration order. Each element
+    occupies a contiguous block of terminal lines. The materializer tracks
+    the line offset and height of each element's region. When an element's
+    height changes (e.g., a table gains rows), subsequent elements are
+    shifted down.
+    
+    Concurrent Updates:
+    Updates from multiple handles are coalesced into a single frame refresh
+    at the target frame rate. The materializer maintains a dirty-element set
+    and redraws all dirty elements in a single pass per frame.
+    """
+    strategy_name = "live"
+    
+    _frame_rate: float = 15.0            # Maximum redraws per second
+    _element_regions: OrderedDict[str, ScreenRegion]  # handle_id → screen region
+    _dirty_set: set[str]                 # handle_ids that need redraw
+    _frame_timer: asyncio.TimerHandle    # Coalescing timer for frame redraws
+
+
+class SequentialBufferMaterializer(MaterializationStrategy):
+    """Materialization strategy for `plain`, `color`, and `table` formats.
+    
+    Buffers element content and renders elements sequentially in declaration
+    order. An element's content is rendered to the output stream only when
+    its handle is closed. If handles are closed out of declaration order,
+    the out-of-order element's rendered content is held in a buffer until
+    all preceding elements have been rendered.
+    
+    This strategy ensures that static, scrolling output formats produce
+    coherent sequential output even when producers write to handles
+    concurrently and close them in arbitrary order.
+    
+    Behavior:
+    - on_element_created: Records the element's declaration index. No output.
+    - on_element_updated: Buffers the update internally. No output.
+    - on_element_closed: If this element is the next in declaration order,
+      renders it immediately (and any buffered subsequent elements that are
+      also closed). Otherwise, buffers the rendered content.
+    - on_session_end: Force-renders any remaining buffered elements (handles
+      that were never closed, in declaration order).
+    
+    Example (two tables populated concurrently):
+    1. Handle A (index 0) created — table "Resources"
+    2. Handle B (index 1) created — table "Validations"
+    3. Handle B receives rows, Handle A receives rows (interleaved)
+    4. Handle B closes (index 1) — rendered content buffered (waiting for A)
+    5. Handle A closes (index 0) — A is rendered to stream, then buffered B
+       is rendered to stream
+    
+    Result: Output shows table A followed by table B, regardless of the
+    order in which data arrived or handles closed.
+    """
+    strategy_name = "sequential_buffer"
+    
+    _next_render_index: int = 0          # The declaration index to render next
+    _rendered_buffers: dict[int, str]     # index → pre-rendered content (waiting)
+    _closed_set: set[int]                # Declaration indices of closed elements
+
+
+class AccumulateMaterializer(MaterializationStrategy):
+    """Materialization strategy for `json` and `yaml` formats.
+    
+    Accumulates all element data silently until the session ends, then
+    serializes the complete StructuredOutput as a single JSON or YAML
+    document.
+    
+    Behavior:
+    - on_element_created: No output.
+    - on_element_updated: No output.
+    - on_element_closed: No output.
+    - on_session_end: Calls session.snapshot() to get the final
+      StructuredOutput, then delegates to the ElementRenderer's
+      serialize() method for complete document serialization.
+    
+    This strategy is the simplest — it ignores all intermediate events and
+    only acts on session_end. It exists as a distinct strategy (rather than
+    a special case) to maintain the uniform strategy interface.
+    """
+    strategy_name = "accumulate"
+
+ +##### ElementRenderer Protocol + +While the `MaterializationStrategy` controls *when* elements are rendered, the `ElementRenderer` controls *how* each element type is visually formatted. Each format has a paired `ElementRenderer` implementation: + +

+class ElementRenderer(Protocol):
+    """Interface for format-specific element rendering.
+    
+    An ElementRenderer knows how to paint each element type for a specific
+    output format. It is called by the MaterializationStrategy when it is
+    time to render an element.
+    
+    Implementations:
+    - PlainElementRenderer: ASCII text, no escapes
+    - ColorElementRenderer: ANSI-colored text, same layout as plain
+    - TableElementRenderer: Unicode box-drawing with color
+    - RichElementRenderer: Advanced terminal features (cursor, animation)
+    - JsonElementRenderer: JSON serialization
+    - YamlElementRenderer: YAML serialization
+    """
+    
+    format_name: str                     # "plain", "color", "table", "rich", "json", "yaml"
+    
+    def render_panel(self, panel: Panel, stream: IO) -> None:
+        """Render a panel element to the stream."""
+        ...
+    
+    def render_table(self, table: Table, stream: IO) -> None:
+        """Render a table element to the stream."""
+        ...
+    
+    def render_tree(self, tree: Tree, stream: IO) -> None:
+        """Render a tree element to the stream."""
+        ...
+    
+    def render_status(self, status: StatusMessage, stream: IO) -> None:
+        """Render a status message to the stream."""
+        ...
+    
+    def render_progress(self, progress: ProgressIndicator, stream: IO) -> None:
+        """Render a progress indicator to the stream."""
+        ...
+    
+    def render_code(self, code: CodeBlock, stream: IO) -> None:
+        """Render a code block to the stream."""
+        ...
+    
+    def render_diff(self, diff: DiffBlock, stream: IO) -> None:
+        """Render a diff block to the stream."""
+        ...
+    
+    def render_text(self, text: TextBlock, stream: IO) -> None:
+        """Render a text block to the stream."""
+        ...
+    
+    def render_separator(self, separator: Separator, stream: IO) -> None:
+        """Render a visual separator to the stream."""
+        ...
+    
+    def render_action_hint(self, hint: ActionHint, stream: IO) -> None:
+        """Render an action hint to the stream."""
+        ...
+    
+    def render_element(self, element: OutputElement, stream: IO) -> None:
+        """Dispatch to the appropriate render method based on element type.
+        
+        This is the primary entry point used by materialization strategies.
+        It uses a dispatch table to route to the correct typed method.
+        """
+        dispatch = {
+            "panel": self.render_panel,
+            "table": self.render_table,
+            "tree": self.render_tree,
+            "status": self.render_status,
+            "progress": self.render_progress,
+            "code": self.render_code,
+            "diff": self.render_diff,
+            "text": self.render_text,
+            "separator": self.render_separator,
+            "action_hint": self.render_action_hint,
+        }
+        handler = dispatch.get(element.element_type)
+        if handler:
+            handler(element, stream)
+    
+    def serialize(self, output: StructuredOutput, stream: IO) -> None:
+        """Serialize a complete StructuredOutput to the stream.
+        
+        Used by AccumulateMaterializer for json/yaml formats. For visual
+        formats (plain/color/table/rich), this method iterates over
+        output.elements and calls render_element for each.
+        """
+        ...
+    
+    def can_render(self, terminal_caps: "TerminalCapabilities") -> bool:
+        """Whether this renderer can operate in the given terminal environment."""
+        ...
+
+ +##### Format Resolution + +The active format is resolved using a precedence chain: + +1. **CLI flag**: `--format ` on the command line (highest priority). +2. **Environment variable**: `CLEVERAGENTS_FORMAT=`. +3. **Config file**: The `format` key in the global config (`agents config set format `). +4. **TTY detection**: If stdout is not a TTY and no explicit format was set, fall back to `plain` (not `rich`), since non-TTY consumers cannot interpret ANSI codes or cursor movement. +5. **Default**: `rich`. + +Once the format is resolved, the CLI framework selects the corresponding `(MaterializationStrategy, ElementRenderer)` pair from the `RendererRegistry`, opens an `OutputSession` bound to that strategy, and passes the session to the command implementation. + +#### Format Specifications + +##### `plain` — Plain Text + +**Philosophy**: Maximum portability. Output is pure ASCII text with no escape codes, no box-drawing characters, and no color. Suitable for piping to files, logs, grep, awk, or any non-terminal consumer. + +**Rendering rules**: + +- **Panels**: Rendered as indented key-value pairs with a header line. +- **Tables**: Rendered as aligned columns separated by whitespace (no box drawing). Column headers are separated from data by a dashed line. +- **Trees**: Rendered with ASCII indentation using `+--` and `|` characters. +- **Status messages**: Prefixed with `[OK]`, `[WARN]`, `[ERROR]`, `[INFO]`. +- **Progress**: Rendered as static status lines (no animation). Steps shown as `[x]` (done), `[ ]` (pending), `[>]` (active). +- **Diffs**: Standard unified diff format. +- **Code blocks**: Raw text with optional line numbers. +- **No ANSI escape codes** of any kind. +- **No Unicode characters** beyond basic ASCII (no box drawing, no checkmarks, no arrows). + +**Example** (`agents --format plain project show local/api-service`): + +

+$ agents --format plain project show local/api-service
+
+Project Details
+  Name: local/api-service
+  ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1
+  Description: Backend API
+  Resources: 2
+  Remote: no
+  Created: 2026-02-08 12:46
+
+Linked Resources
+  Resource          Type            Sandbox              Read-Only
+  ----------------  --------------  --------------------  ---------
+  local/api-repo    git-checkout    git_worktree          no
+  local/staging-db  local/database  transaction_rollback  yes
+
+Validations (3)
+  val_01HXM5A  pytest --cov=src --cov-fail-under=80  required
+  val_01HXM5B  ruff check .                          required
+  val_01HXM5C  node scripts/check-bundle-size.js     info
+
+Context
+  Include: repo
+  Exclude: **/node_modules/**
+  Max File Size: 1 MB
+
+Indexing Status
+  Text Index: ready
+  Vector Index: ready
+  Graph Store: disabled
+  Indexed Files: 347
+  Last Indexed: 12:48
+
+Active Plans
+  Plan ID   Action               Phase
+  --------  -------------------  -------
+  01HXM7A9  local/code-coverage  execute
+
+[OK] Project loaded
+
+ +**Example** (`agents --format plain plan list`): + +

+$ agents --format plain plan list --phase execute
+
+Plans
+  ID        Phase    State       Action               Project            Elapsed
+  --------  -------  ----------  -------------------  -----------------  ---------
+  01HXM7A9  execute  processing  local/code-coverage  local/api-service  00:01:12
+
+Filters
+  Phase: execute
+  State: (any)
+  Project: (any)
+  Action: (any)
+
+Summary
+  Total: 1
+  Processing: 1
+  Completed: 0
+  Errored: 0
+
+[OK] 1 plan listed
+
+ +##### `color` — Colored Plain Text + +**Philosophy**: Same structural layout as `plain`, but with ANSI color codes applied to improve readability. No box-drawing characters, no cursor movement, no animation. + +**Rendering rules**: + +- **Identical layout to `plain`**, but with color applied: + - **Headers/titles**: Bold cyan. + - **Keys**: Bold blue. + - **Values**: Default color, with semantic coloring: + - Success/positive: Green. + - Warnings/attention: Yellow. + - Errors/failures: Red. + - Identifiers/names: Cyan. + - Counts/numbers: Default (white). + - **Table headers**: Bold cyan with underlines rendered as dim dashes. + - **Status prefixes**: `[OK]` in green, `[WARN]` in yellow, `[ERROR]` in red, `[INFO]` in blue. + - **Diff lines**: `+` lines green, `-` lines red, `@@` headers cyan. +- **No box-drawing characters** — uses the same whitespace/dash layout as `plain`. +- **No cursor movement or animation** — pure scrolling output. +- **Respects `NO_COLOR` environment variable**: If `NO_COLOR` is set, `color` format falls back to `plain`. + +**Example** (`agents --format color project show local/api-service`): + +

+$ agents --format color project show local/api-service
+
+Project Details
+  Name: local/api-service
+  ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1
+  Description: Backend API
+  Resources: 2
+  Remote: no
+  Created: 2026-02-08 12:46
+
+Linked Resources
+  Resource          Type            Sandbox              Read-Only
+  ----------------  --------------  --------------------  ---------
+  local/api-repo    git-checkout    git_worktree          no
+  local/staging-db  local/database  transaction_rollback  yes
+
+Validations (3)
+  val_01HXM5A  pytest --cov=src --cov-fail-under=80  required
+  val_01HXM5B  ruff check .                          required
+  val_01HXM5C  node scripts/check-bundle-size.js     info
+
+Context
+  Include: repo
+  Exclude: **/node_modules/**
+  Max File Size: 1 MB
+
+Indexing Status
+  Text Index: ready
+  Vector Index: ready
+  Graph Store: disabled
+  Indexed Files: 347
+  Last Indexed: 12:48
+
+Active Plans
+  Plan ID   Action               Phase
+  --------  -------------------  -------
+  01HXM7A9  local/code-coverage  execute
+
+[OK] Project loaded
+
+ +##### `table` — ASCII Box-Drawing Tables + +**Philosophy**: Structured, visually distinct panels and tables using Unicode box-drawing characters (╭╮╰╯│─). Uses color. This is the style shown in the existing CLI examples throughout this document. + +**Rendering rules**: + +- **Panels**: Rendered as bordered boxes with title in the top border. Uses `╭─╮│╰─╯` characters for rounded corners. +- **Tables**: Rendered inside bordered boxes with column-aligned headers and separator lines using `─` and `│`. +- **Trees**: Rendered inside a bordered box using `├──`, `└──`, `│` tree guide characters. +- **Status messages**: Use Unicode indicators: `✓` (green) for OK, `⚠` (yellow) for WARN, `✗` (red) for ERROR, `ℹ` (blue) for INFO. +- **Progress**: Rendered as a step list inside a panel with `✓`, `⏳`, `•` markers. +- **Color scheme**: Same semantic coloring as `color` format, applied within box structures. +- **No animation or cursor movement** — the boxes are static, scrolling output. + +**Distinction from `rich`**: The `table` format uses the same box-drawing panels and color as `rich` for static content, but it does **not** use any dynamic or interactive terminal features. There are no animated spinners, no live-updating progress bars, no cursor movement, and no in-place redraws. All output is static and scrolls sequentially. Where `rich` would show a spinning `⠋` and a live progress bar, `table` renders a static snapshot using fixed markers (`✓`, `⏳`, `•`). This makes `table` suitable for terminals without advanced capabilities, and for output that will be reviewed after the fact (e.g., scrollback buffers). + +**Example** (`agents --format table project show local/api-service`): + +

+$ agents --format table project show local/api-service
+
+╭─ Project Details ──────────────╮
+│ Name: local/api-service        │
+│ ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1 │
+│ Description: Backend API       │
+│ Resources: 2                   │
+│ Remote: no                     │
+│ Created: 2026-02-08 12:46      │
+╰────────────────────────────────╯
+
+╭─ Linked Resources ──────────────────────────────────────────────────────╮
+│ Resource          Type            Sandbox              Read-Only        │
+│ ────────────────  ──────────────  ────────────────────  ─────────       │
+│ local/api-repo   git-checkout    git_worktree         no                │
+│ local/staging-db local/database  transaction_rollback yes               │
+╰─────────────────────────────────────────────────────────────────────────╯
+
+╭─ Validations (3) ───────────────────────────────────────────╮
+│ val_01HXM5A  pytest --cov=src --cov-fail-under=80  required │
+│ val_01HXM5B  ruff check .                          required │
+│ val_01HXM5C  node scripts/check-bundle-size.js     info     │
+╰─────────────────────────────────────────────────────────────╯
+
+╭─ Context ───────────────────╮
+│ Include: repo               │
+│ Exclude: **/node_modules/** │
+│ Max File Size: 1 MB         │
+╰─────────────────────────────╯
+
+╭─ Indexing Status ──────────╮
+│ Text Index: ready          │
+│ Vector Index: ready        │
+│ Graph Store: disabled      │
+│ Indexed Files: 347         │
+│ Last Indexed: 12:48        │
+╰────────────────────────────╯
+
+╭─ Active Plans ──────────────────────────╮
+│ Plan ID   Action               Phase    │
+│ ────────  ───────────────────  ───────  │
+│ 01HXM7A9  local/code-coverage  execute  │
+╰─────────────────────────────────────────╯
+
+✓ OK Project loaded
+
+ +**Example** (`agents --format table plan execute 01HXM8C2ZK`): + +Unlike `rich` mode which would show animated spinners and a live progress bar, the `table` format renders a static snapshot of execution state: + +

+$ agents --format table plan execute 01HXM8C2ZK
+
+╭─ Execution ──────────────────────╮
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+│ Phase: execute                   │
+│ Sandbox: git_worktree            │
+│ Worker: local/executor           │
+│ Started: 12:58:10                │
+│ Attempt: 1                       │
+╰──────────────────────────────────╯
+
+╭─ Strategy Summary ─────────────────────╮
+│ Decisions: 8                           │
+│ Invariants: 2                          │
+│ Planned Child Plans: 2+                │
+│ Estimated Files: ~12                   │
+│ Risk: low                              │
+╰────────────────────────────────────────╯
+
+╭─ Progress ────────╮
+│ ✓ Collect context │
+│ ✓ Run tools       │
+│ ⏳ Build changeset │
+│ • Validate        │
+╰───────────────────╯
+
+✓ OK Execution started
+
+ +##### `rich` — Modern Rich CLI Elements + +**Philosophy**: The premium interactive terminal experience. Uses advanced terminal capabilities: cursor movement, inline updates, animated spinners, live-updating progress bars, collapsible sections, syntax highlighting, and dynamic layout. This is the default format. + +**Rendering rules**: + +- **Panels**: Rich bordered panels with rounded corners, title bars, and optional collapse/expand behavior. Panels may animate into view. +- **Tables**: Full-featured tables with automatic column sizing, truncation with ellipsis, sortable column indicators, alternating row shading, and horizontal scrolling for wide tables. +- **Trees**: Interactive collapsible trees. Nodes expand/collapse with visual animation. Color-coded by node type. Depth guides use dotted lines. +- **Status messages**: Use animated checkmarks/spinners that resolve to final state. Success messages may briefly flash or highlight. +- **Progress**: Live-updating progress bars with: + - Animated spinners (Braille, dots, or bars depending on terminal capability). + - Elapsed time and ETA. + - Per-step status with animated transitions (pending → active → done). + - Multi-line progress for parallel operations. +- **Diffs**: Syntax-highlighted side-by-side or unified diffs with line numbers, change highlighting at the character level (not just line level), and navigable hunks. +- **Code blocks**: Full syntax highlighting using terminal colors (256-color or truecolor when available). Line numbers in dim color. Highlighted lines with background color. +- **Dynamic layout**: Adapts to terminal width. Narrow terminals get a stacked layout; wide terminals get side-by-side panels. +- **Live updates**: Long-running commands (plan execute, plan status) use live-updating displays that redraw in place rather than scrolling. +- **Graceful degradation**: If the terminal does not support required capabilities (e.g., no truecolor, no cursor movement), the renderer automatically falls back to `table` rendering for those elements. + +**Example** (`agents --format rich plan execute 01HXM8C2ZK`): + +The `rich` format produces output that cannot be fully represented in static documentation — animated spinners cycle in place, progress bars fill smoothly, and elements update without scrolling. The rendering below is a static snapshot of what the terminal would display at a given moment: + +

+$ agents --format rich plan execute 01HXM8C2ZK
+
+╭─ Execution ──────────────────────╮
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+│ Phase: execute                   │
+│ Sandbox: git_worktree            │
+│ Worker: local/executor           │
+│ Started: 12:58:10                │
+╰──────────────────────────────────╯
+
+⠋ Collecting context...                      (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ animates in place)
+  ├── repo: local/api-repo ✓
+  └── db: local/staging-db ✓
+
+╭─ Strategy Summary ──────────────────────────────────────────────────────╮
+│ 8 decisions │ 2 invariants │ 2+ child plans │ ~12 files │ risk: low     │
+╰─────────────────────────────────────────────────────────────────────────╯
+
+Progress ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  42%  elapsed 0:01:12  ETA 0:01:40
+  ✓ Collect context .................. 0.8s
+  ✓ Run tools (8 calls) ............. 12.4s
+  ⠙ Build changeset ................. (running)     (animates in place)
+  ○ Validate ........................ (pending)
+
+╭─ Live Tool Calls ───────────────────────────────────────╮
+│ #6 read_file   src/auth/__init__.py   ✓  0.1s           │
+│ #7 write_file  tests/test_auth.py     ✓  0.2s           │
+│ #8 edit_file   src/auth/session.py    ⠙  ...            │
+╰─────────────────────────────────────────────────────────╯
+
+ +In `rich` mode: +- The Braille spinner characters (`⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`) animate in real-time, cycling in place without scrolling. +- The progress bar (`━━━`) fills smoothly as work completes. +- Completed steps appear with a green `✓` via in-place line update (the line rewrites, it does not scroll). +- The "Live Tool Calls" panel scrolls its content internally, showing only the most recent N calls. +- The terminal is not flooded with scrolling text — elements update in place using cursor movement. + +**Example** (`agents --format rich version`): + +

+$ agents --format rich version
+
+╭─────────────────────────────────────╮
+│  CleverAgents CLI  v1.0.0           │
+│  channel: stable                    │
+╰─────────────────────────────────────╯
+
+╭─ Build ─────────────────────────────╮
+│ Build Date: 2026-02-08              │
+│ Commit: a17c3f9                     │
+│ Schema: v3                          │
+│ Platform: linux-x86_64              │
+│ Python: 3.13.1                      │
+╰─────────────────────────────────────╯
+
+╭─ Dependencies ─────────────────────────────────────────────────────────╮
+│ LangGraph 0.2.60 │ LangChain 0.3.18 │ MCP SDK 1.4.0 │ Pydantic 2.10.4  │
+╰────────────────────────────────────────────────────────────────────────╯
+
+✓ OK Version reported
+
+ +In `rich` mode, the version card may use background colors, bold gradients, or subtle box shadows (depending on terminal truecolor support). Elements may animate into view with a brief slide or fade transition. + +##### `json` — JSON Data Structure + +**Philosophy**: Machine-readable output for programmatic consumption. Every command produces a well-defined JSON object. No ANSI color codes in the structural data. Color codes may appear only **within** text values that represent verbatim content (such as code blocks or diff output where the original text contained ANSI sequences), but all structural keys, labels, and metadata are plain strings. + +**Rendering rules**: + +- **Top-level structure**: Always a JSON object with a standard envelope: + 

+  {
+    "command": "project show",
+    "status": "ok",
+    "exit_code": 0,
+    "data": { ... },
+    "timing": { "duration_ms": 42 },
+    "metadata": { ... }
+  }
+
+- **Panels**: Rendered as nested objects within `data`. +- **Tables**: Rendered as arrays of objects within `data`. +- **Trees**: Rendered as nested objects with `children` arrays. +- **Status messages**: Included in a `messages` array within the envelope. +- **Progress**: Not rendered (JSON output is non-interactive; progress is omitted). +- **Diffs**: Rendered as structured objects with `hunks` arrays. +- **No ANSI codes** in any structural element. Raw ANSI codes are preserved only in string values that represent verbatim terminal output. +- **Pretty-printed** by default (indented). Compact mode available via `--json-compact` (future option). +- **Consistent schema per command**: Each command's JSON schema is stable and documented, enabling reliable programmatic parsing. + +**Example** (`agents --format json project show local/api-service`): + +

+{
+  "command": "project show",
+  "status": "ok",
+  "exit_code": 0,
+  "data": {
+    "project": {
+      "name": "local/api-service",
+      "id": "01HXM4T08Y0N5R9VZ4QX4BPTZ1",
+      "description": "Backend API",
+      "type": "local",
+      "remote": false,
+      "created_at": "2026-02-08T12:46:00Z"
+    },
+    "linked_resources": [
+      {
+        "name": "local/api-repo",
+        "type": "git-checkout",
+        "sandbox_strategy": "git_worktree",
+        "read_only": false
+      },
+      {
+        "name": "local/staging-db",
+        "type": "local/database",
+        "sandbox_strategy": "transaction_rollback",
+        "read_only": true
+      }
+    ],
+    "validations": [
+      {
+        "id": "val_01HXM5A",
+        "command": "pytest --cov=src --cov-fail-under=80",
+        "mode": "required",
+        "timeout": 600,
+        "resource": "repo"
+      },
+      {
+        "id": "val_01HXM5B",
+        "command": "ruff check .",
+        "mode": "required",
+        "timeout": 300,
+        "resource": null
+      },
+      {
+        "id": "val_01HXM5C",
+        "command": "node scripts/check-bundle-size.js",
+        "mode": "informational",
+        "timeout": 300,
+        "resource": null
+      }
+    ],
+    "context": {
+      "include_resources": ["repo"],
+      "exclude_paths": ["**/node_modules/**"],
+      "max_file_size_bytes": 1048576
+    },
+    "indexing": {
+      "text_index": "ready",
+      "vector_index": "ready",
+      "graph_store": "disabled",
+      "indexed_files": 347,
+      "last_indexed_at": "2026-02-08T12:48:00Z"
+    },
+    "active_plans": [
+      {
+        "plan_id": "01HXM7A9",
+        "action": "local/code-coverage",
+        "phase": "execute"
+      }
+    ]
+  },
+  "timing": {
+    "duration_ms": 42
+  },
+  "messages": [
+    { "level": "ok", "text": "Project loaded" }
+  ]
+}
+
+ +**Example** (`agents --format json plan list --phase execute`): + +

+{
+  "command": "plan list",
+  "status": "ok",
+  "exit_code": 0,
+  "data": {
+    "plans": [
+      {
+        "id": "01HXM7A9",
+        "phase": "execute",
+        "state": "processing",
+        "action": "local/code-coverage",
+        "project": "local/api-service",
+        "elapsed": "00:01:12"
+      }
+    ],
+    "filters": {
+      "phase": "execute",
+      "state": null,
+      "project": null,
+      "action": null
+    },
+    "summary": {
+      "total": 1,
+      "processing": 1,
+      "completed": 0,
+      "errored": 0
+    }
+  },
+  "timing": {
+    "duration_ms": 18
+  },
+  "messages": [
+    { "level": "ok", "text": "1 plan listed" }
+  ]
+}
+
+ +##### `yaml` — YAML Data Structure + +**Philosophy**: Same data as `json` but in YAML format. Preferred by users who find YAML more readable for configuration and scripting workflows. Follows the same structural conventions as `json`. + +**Rendering rules**: + +- **Same data envelope** as JSON (`command`, `status`, `exit_code`, `data`, `timing`, `messages`). +- **YAML 1.2 compliant** output. +- **Multi-line strings** use YAML block scalars (`|` for literal, `>` for folded) when appropriate. +- **No ANSI codes** in structural elements (same rule as JSON). +- **Sorted keys** for deterministic output. + +**Example** (`agents --format yaml project show local/api-service`): + +

+command: project show
+status: ok
+exit_code: 0
+data:
+  project:
+    name: local/api-service
+    id: 01HXM4T08Y0N5R9VZ4QX4BPTZ1
+    description: Backend API
+    type: local
+    remote: false
+    created_at: "2026-02-08T12:46:00Z"
+  linked_resources:
+    - name: local/api-repo
+      type: git-checkout
+      sandbox_strategy: git_worktree
+      read_only: false
+    - name: local/staging-db
+      type: local/database
+      sandbox_strategy: transaction_rollback
+      read_only: true
+  validations:
+    - id: val_01HXM5A
+      command: "pytest --cov=src --cov-fail-under=80"
+      mode: required
+      timeout: 600
+      resource: repo
+    - id: val_01HXM5B
+      command: "ruff check ."
+      mode: required
+      timeout: 300
+      resource: null
+    - id: val_01HXM5C
+      command: "node scripts/check-bundle-size.js"
+      mode: informational
+      timeout: 300
+      resource: null
+  context:
+    include_resources:
+      - repo
+    exclude_paths:
+      - "**/node_modules/**"
+    max_file_size_bytes: 1048576
+  indexing:
+    text_index: ready
+    vector_index: ready
+    graph_store: disabled
+    indexed_files: 347
+    last_indexed_at: "2026-02-08T12:48:00Z"
+  active_plans:
+    - plan_id: 01HXM7A9
+      action: local/code-coverage
+      phase: execute
+timing:
+  duration_ms: 42
+messages:
+  - level: ok
+    text: Project loaded
+
+ +#### Format Comparison Matrix + +| Capability | `plain` | `color` | `table` | `rich` | `json` | `yaml` | +|---|---|---|---|---|---|---| +| Color codes | No | Yes | Yes | Yes | No | No | +| Box drawing | No | No | Yes | Yes | No | No | +| Animation/spinners | No | No | No | Yes | No | No | +| Live updates | No | No | No | Yes | No | No | +| Cursor movement | No | No | No | Yes | No | No | +| Syntax highlighting | No | No | No | Yes | No | No | +| Collapsible sections | No | No | No | Yes | No | No | +| Machine-parseable | Partially | Partially | No | No | Yes | Yes | +| Pipe-safe | Yes | No* | No | No | Yes | Yes | +| Unicode required | No | No | Yes | Yes | No | No | +| TTY required | No | No | No | Yes** | No | No | + +\* `color` output can be piped if the consumer understands ANSI codes (e.g., `less -R`). +\** `rich` gracefully degrades to `table` when stdout is not a TTY. + +#### Renderer Registration and Extension + +The framework uses a **registry pattern** for format renderers, enabling third-party or plugin renderers. Each format is registered as a `(MaterializationStrategy, ElementRenderer)` pair — the strategy controls timing/ordering, and the renderer controls visual formatting: + +

+@dataclass
+class FormatRegistration:
+    """A registered format: its strategy factory, renderer factory, and fallback."""
+    strategy_factory: Callable[[TerminalCapabilities], MaterializationStrategy]
+    renderer_factory: Callable[[TerminalCapabilities], ElementRenderer]
+    fallback: str | None                 # Format name to fall back to, or None
+
+
+class RendererRegistry:
+    """Central registry for format (strategy, renderer) pairs.
+    
+    Formats are registered by name and resolved at runtime based on the
+    active format and terminal capabilities. The registry supports dynamic
+    registration, enabling plugins to add custom formats (e.g., 'html',
+    'csv', 'markdown').
+    
+    Built-in registrations:
+        "rich"  → (LiveMaterializer, RichElementRenderer), fallback="table"
+        "table" → (SequentialBufferMaterializer, TableElementRenderer), fallback="color"
+        "color" → (SequentialBufferMaterializer, ColorElementRenderer), fallback="plain"
+        "plain" → (SequentialBufferMaterializer, PlainElementRenderer), fallback=None
+        "json"  → (AccumulateMaterializer, JsonElementRenderer), fallback=None
+        "yaml"  → (AccumulateMaterializer, YamlElementRenderer), fallback=None
+    """
+    
+    _formats: dict[str, FormatRegistration] = {}
+    
+    @classmethod
+    def register(cls, format_name: str,
+                 strategy_factory: Callable[[TerminalCapabilities], MaterializationStrategy],
+                 renderer_factory: Callable[[TerminalCapabilities], ElementRenderer],
+                 fallback: str | None = None) -> None:
+        """Register a format.
+        
+        Args:
+            format_name: The format identifier (e.g., 'rich', 'json').
+            strategy_factory: Callable that creates a MaterializationStrategy,
+                given terminal capabilities.
+            renderer_factory: Callable that creates an ElementRenderer,
+                given terminal capabilities.
+            fallback: Optional fallback format name if this format cannot
+                operate in the current terminal environment.
+        """
+        cls._formats[format_name] = FormatRegistration(
+            strategy_factory=strategy_factory,
+            renderer_factory=renderer_factory,
+            fallback=fallback,
+        )
+    
+    @classmethod
+    def resolve(cls, format_name: str,
+                terminal_caps: TerminalCapabilities
+                ) -> tuple[MaterializationStrategy, ElementRenderer]:
+        """Resolve the best (strategy, renderer) pair for the given format.
+        
+        Walks the fallback chain if the requested format's renderer cannot
+        operate in the current terminal environment. Returns the first pair
+        where the renderer reports can_render(terminal_caps) == True.
+        
+        Raises:
+            ValueError: If no usable format is found (should never happen
+                since 'plain' has no fallback and always works).
+        """
+        current = format_name
+        visited: set[str] = set()
+        
+        while current and current not in visited:
+            visited.add(current)
+            registration = cls._formats.get(current)
+            if registration is None:
+                break
+            
+            renderer = registration.renderer_factory(terminal_caps)
+            if renderer.can_render(terminal_caps):
+                strategy = registration.strategy_factory(terminal_caps)
+                strategy.bind(renderer, terminal_caps=terminal_caps)
+                return strategy, renderer
+            
+            current = registration.fallback
+        
+        # Ultimate fallback is always plain
+        plain = cls._formats["plain"]
+        renderer = plain.renderer_factory(terminal_caps)
+        strategy = plain.strategy_factory(terminal_caps)
+        strategy.bind(renderer, terminal_caps=terminal_caps)
+        return strategy, renderer
+    
+    @classmethod
+    def available_formats(cls) -> list[str]:
+        """Return all registered format names."""
+        return sorted(cls._formats.keys())
+    
+    @classmethod
+    def is_registered(cls, format_name: str) -> bool:
+        """Check if a format is registered."""
+        return format_name in cls._formats
+
+ +##### Terminal Capability Detection + +The framework detects terminal capabilities to guide format resolution, strategy selection, and renderer fallback: + +

+@dataclass
+class TerminalCapabilities:
+    """Detected capabilities of the output terminal.
+    
+    This dataclass is populated once at CLI startup and passed to the
+    RendererRegistry for format resolution. It is also available to
+    individual strategies and renderers for fine-grained adaptation
+    (e.g., adjusting column widths to terminal width, choosing between
+    256-color and truecolor palettes).
+    """
+    is_tty: bool                         # Is stdout a TTY?
+    width: int                           # Terminal width in columns
+    height: int                          # Terminal height in rows
+    supports_ansi: bool                  # Supports basic ANSI escape codes?
+    supports_256_color: bool             # Supports 256-color palette?
+    supports_truecolor: bool             # Supports 24-bit truecolor?
+    supports_unicode: bool               # Supports Unicode (box-drawing, etc.)?
+    supports_cursor_movement: bool       # Supports cursor repositioning?
+    supports_alternate_screen: bool      # Supports alternate screen buffer?
+    no_color: bool                       # Is NO_COLOR environment variable set?
+    term_program: str | None             # TERM_PROGRAM value (e.g., "iTerm2", "vscode")
+    
+    @classmethod
+    def detect(cls) -> "TerminalCapabilities":
+        """Auto-detect terminal capabilities from the environment.
+        
+        Detection logic:
+        - is_tty: os.isatty(sys.stdout.fileno())
+        - width/height: os.get_terminal_size() with fallback to (80, 24)
+        - supports_ansi: True if is_tty and not Windows legacy console
+        - supports_256_color: True if TERM contains "256color" or COLORTERM is set
+        - supports_truecolor: True if COLORTERM is "truecolor" or "24bit"
+        - supports_unicode: True if locale encoding is UTF-8
+        - supports_cursor_movement: True if is_tty and TERM is not "dumb"
+        - supports_alternate_screen: True if supports_cursor_movement
+        - no_color: True if NO_COLOR environment variable is set (any value)
+        - term_program: Value of TERM_PROGRAM environment variable
+        """
+        ...
+
+ +##### Plugin Format Registration + +Third-party plugins can register custom formats using the registry: + +

+# Example: Registering a custom 'csv' format plugin
+from cleveragents.output import RendererRegistry, SequentialBufferMaterializer
+
+class CsvElementRenderer(ElementRenderer):
+    """Renders tables as CSV, other elements as plain text."""
+    format_name = "csv"
+    
+    def render_table(self, table: Table, stream: IO) -> None:
+        writer = csv.writer(stream)
+        writer.writerow([col.name for col in table.columns])
+        for row in table.rows:
+            writer.writerow([row.get(col.name, "") for col in table.columns])
+    
+    def can_render(self, terminal_caps: TerminalCapabilities) -> bool:
+        return True  # CSV works everywhere
+
+# Register at plugin load time
+RendererRegistry.register(
+    format_name="csv",
+    strategy_factory=lambda caps: SequentialBufferMaterializer(),
+    renderer_factory=lambda caps: CsvElementRenderer(),
+    fallback="plain",
+)
+
+ +#### Edge Cases and Special Behaviors + +##### Error Output + +Errors are rendered through the same framework. When a command raises an exception or signals an error, the session's context manager (`__exit__`) catches the exception, creates a `StatusMessage` with `level="error"` and an optional `TextBlock` with details, and closes the session with `exit_code=1`. In `json`/`yaml` formats, errors produce: + +

+{
+  "command": "project show",
+  "status": "error",
+  "exit_code": 1,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Project 'local/nonexistent' not found",
+    "detail": "No project with name 'local/nonexistent' exists. Run 'agents project list' to see available projects.",
+    "suggestions": [
+      "agents project list",
+      "agents project create local/nonexistent"
+    ]
+  },
+  "timing": { "duration_ms": 5 }
+}
+
+ +##### Empty Results + +When a list command returns no results, all formats handle it gracefully: + +- **plain/color**: Prints a message like `No projects found.` +- **table**: Renders an empty table with headers and a `(empty)` message. +- **rich**: Renders a dimmed panel with an empty-state message and suggested actions. +- **json/yaml**: Returns an empty array in the appropriate data field. + +##### Large Data Sets + +For commands that may return large result sets (e.g., `resource list` with thousands of resources): + +- **plain/color/table** (SequentialBufferMaterializer): The table handle accumulates rows as the producer adds them. Since the buffer is in-memory, very large result sets benefit from the `max_rows_hint` — the renderer truncates display at N rows with a `(... and N more rows)` indicator. The full data is still available in the snapshot for json/yaml. +- **rich** (LiveMaterializer): Uses a virtual-scrolling table that renders only visible rows. Shows a count indicator (e.g., "Showing 1-50 of 2,847"). New rows animate into view as they are added. +- **json/yaml** (AccumulateMaterializer): Accumulates and emits a complete array at session end. Streaming JSON lines (one JSON object per row) for very large sets is a future consideration. + +##### Nested/Recursive Structures + +Tree-like data (resource trees, decision trees, plan hierarchies) may be arbitrarily deep. Renderers respect `max_depth_hint`: + +- **plain/color**: Truncate at depth N with a `... (N more levels)` indicator. +- **table**: Same truncation, rendered inside a box. +- **rich**: Collapsible tree nodes — deep levels start collapsed. User can expand interactively if the terminal supports it. +- **json/yaml**: Full depth — no truncation (programmatic consumers need complete data). + +##### Mixed Content + +Some commands produce mixed output (e.g., `plan status` has panels, tables, progress bars, and status messages). Each element is created via its own handle on the session, and the materialization strategy renders them in declaration order. The `ElementRenderer` is responsible for visual spacing and grouping between heterogeneous elements (e.g., inserting blank lines between a panel and a table in `plain` format, or adding visual margins in `rich` format). + +##### Producer Error Mid-Stream + +When a producer encounters an error while writing to a handle (e.g., an API call fails while populating a table), the framework handles it as follows: + +1. **The handle is closed with partial data** — the producer catches its exception, optionally calls `handle.close()` (or lets the context manager close it), and then creates a `StatusMessage` handle with `level="error"` to report the failure. + +2. **The materialization strategy renders whatever was accumulated** — a table with 3 of an expected 10 rows is rendered with those 3 rows, followed by the error message. This is better than rendering nothing. + +3. **The session's exit code is set to 1** — indicating partial failure. + +4. **For `json`/`yaml` formats**, the accumulated snapshot includes both the partial data and the error message in the `messages` array, giving programmatic consumers full visibility. + +Example of producer error handling: + +

+async def list_resources(session: OutputSession, client: ApiClient) -> None:
+    table = session.table("Resources", columns=[
+        ColumnDef(name="Name"), ColumnDef(name="Type"), ColumnDef(name="Status"),
+    ])
+    
+    try:
+        async for resource in client.list_resources():
+            table.add_row({
+                "Name": resource.name,
+                "Type": resource.type,
+                "Status": resource.status,
+            })
+    except ApiError as e:
+        table.close()  # Close with partial data
+        session.status(f"Error fetching resources: {e}", level="error")
+        return
+    
+    table.close()
+    session.status(f"{table.element.row_count} resources listed", level="ok")
+
+ +##### Abandoned Handles + +If a handle is never explicitly closed and the session ends (either normally via `session.close()` or via the context manager's `__exit__`), the session force-closes all remaining open handles: + +1. A warning is logged (not rendered to the user): `"Handle {handle_id} ({element_type}) was not explicitly closed; force-closing at session end."` +2. The handle is closed with its current accumulated state. +3. The materialization strategy processes the `ElementClosed` event normally. + +This ensures that no data is silently lost, even if producer code forgets to close a handle due to an unhandled code path. + +##### Back-Pressure and Throttling + +The `LiveMaterializer` (used by `rich` format) limits terminal redraws to its configured frame rate (default 15 fps). When handles emit updates faster than the frame rate: + +1. Updates are coalesced — the materializer tracks a **dirty set** of handle IDs that have been updated since the last frame. +2. On each frame tick, all dirty elements are redrawn in a single pass, and the dirty set is cleared. +3. The event queue between session and strategy uses bounded capacity. If the queue fills (producer is vastly faster than rendering), the session's `_emit_event` method drops `ElementUpdated` events for handles that are already in the dirty set (since the next frame will redraw them anyway). `ElementCreated` and `ElementClosed` events are never dropped. + +For `SequentialBufferMaterializer` and `AccumulateMaterializer`, there is no back-pressure concern — updates are buffered in memory and never rendered incrementally. + +##### Cancellation Semantics + +When a command is cancelled (e.g., user presses Ctrl+C): + +1. The session receives a cancellation signal and enters the `"closing"` state. +2. All open handles are force-closed with their current state. +3. A `StatusMessage` with `level="warn"` and message `"Operation cancelled"` is emitted. +4. The session closes with `exit_code=130` (standard SIGINT exit code). +5. **For `rich` format**: The `LiveMaterializer` freezes the display, resolves any active spinners to a cancellation indicator (e.g., yellow `⚠`), and moves the cursor to the end of the output. +6. **For buffered formats**: Any elements that have been rendered stay on screen. Pending buffered elements are flushed in order, followed by the cancellation message. +7. **For `json`/`yaml`**: The accumulated snapshot is serialized with `"status": "cancelled"` and the appropriate exit code. + +##### Interleaved Status Messages During Concurrent Production + +When multiple producers are running concurrently (e.g., populating two tables), status messages may be created at any time by any producer. The materialization strategy handles these based on format: + +- **`rich`** (LiveMaterializer): Status messages are rendered immediately in a dedicated status region at the bottom of the display (below all element regions). Multiple concurrent status messages stack vertically. +- **`plain`/`color`/`table`** (SequentialBufferMaterializer): Status messages created during concurrent production are treated as elements in declaration order, just like tables and panels. A status message created between two table creations will be rendered between those tables. Status messages created *after* all tables will render after all tables are flushed. +- **`json`/`yaml`** (AccumulateMaterializer): All status messages are collected in the `messages` array of the final snapshot, ordered by timestamp. + +#### Integration with Future TUI + +The reactive `OutputSession` architecture is intentionally designed to serve as the data layer for a future TUI (text user interface). The session's event-driven model maps directly to TUI widget patterns: + +1. **Element handles become observable data sources.** A TUI `MaterializationStrategy` (e.g., `TuiMaterializer`) would subscribe to element events and route them to TUI widgets. The producer code (command logic) is completely unaware of whether it is driving a CLI, TUI, or web frontend — it writes to handles identically in all cases. + +2. **Element types map to TUI widgets:** + - `PanelHandle` → info pane or detail card widget + - `TableHandle` → sortable, filterable data grid widget (rows arrive incrementally via `add_row` events) + - `TreeHandle` → collapsible tree view widget (nodes arrive incrementally via `add_child` events) + - `ProgressHandle` → animated progress bar or step-list widget + - `StatusHandle` → toast notification or status bar message + - `CodeHandle` → syntax-highlighted code viewer widget + - `DiffHandle` → side-by-side diff viewer widget + +3. **Interactive features are additive.** The TUI can offer features that the CLI cannot — sorting table columns, filtering rows, collapsing/expanding tree nodes, searching within code blocks — without any changes to producer code. These features are implemented in the TUI's `ElementRenderer` and widget layer. + +4. **Concurrent updates are native.** Because the session already supports multiple concurrent producers writing to different handles, the TUI naturally displays multiple simultaneously-updating widgets (e.g., two tables being populated in parallel by concurrent operations). The `TuiMaterializer` routes events to widgets, and each widget redraws independently using the TUI framework's event loop. + +5. **The `StructuredOutput` snapshot** provides the initial state when navigating to a completed session in the TUI (e.g., reviewing a past command's output), while live sessions use the event stream. + +The separation between production (element handles), timing (materialization strategy), and presentation (element renderer) ensures that the same command logic supports CLI, TUI, and web frontends without modification — only the `(MaterializationStrategy, ElementRenderer)` pair changes. + +#### Programmatic Usage Examples + +This section demonstrates how command implementations use the Output Rendering Framework through the `OutputSession` API, and how the same producer code produces correct output across all formats. + +##### Example 1: Simple Static Command Output + +The simplest usage — a command that creates elements, populates them synchronously, and closes them. No concurrency, no streaming. + +**Producer code** (`agents project show`): + +

+async def cmd_project_show(session: OutputSession, project_name: str) -> None:
+    """Implementation of 'agents project show <project>'."""
+    project = await api.get_project(project_name)
+    resources = await api.list_project_resources(project.id)
+    validations = await api.list_project_validations(project.id)
+    
+    # --- Build output elements ---
+    
+    # Panel: Project details
+    with session.panel("Project Details") as panel:
+        panel.set_entries({
+            "Name": project.name,
+            "ID": project.id,
+            "Description": project.description,
+            "Resources": str(len(resources)),
+            "Remote": "yes" if project.remote else "no",
+            "Created": project.created_at.strftime("%Y-%m-%d %H:%M"),
+        }, style_hints={
+            "Name": "identifier",
+            "Resources": "number",
+            "Remote": "success" if not project.remote else "info",
+            "Created": "success",
+        })
+    
+    # Table: Linked resources
+    with session.table("Linked Resources", columns=[
+        ColumnDef(name="Resource", type="string", style_hint="identifier"),
+        ColumnDef(name="Type"),
+        ColumnDef(name="Sandbox"),
+        ColumnDef(name="Read-Only"),
+    ]) as table:
+        for r in resources:
+            table.add_row({
+                "Resource": r.name,
+                "Type": r.type,
+                "Sandbox": r.sandbox_strategy,
+                "Read-Only": "yes" if r.read_only else "no",
+            })
+    
+    # Table: Validations
+    with session.table(f"Validations ({len(validations)})", columns=[
+        ColumnDef(name="ID", type="id", style_hint="identifier"),
+        ColumnDef(name="Command"),
+        ColumnDef(name="Mode"),
+    ]) as table:
+        for v in validations:
+            table.add_row({
+                "ID": v.id,
+                "Command": v.command,
+                "Mode": v.mode,
+            })
+    
+    # Status: Final message
+    session.status("Project loaded", level="ok")
+
+ +**What this produces in `plain` format:** + +

+Project Details
+  Name: local/api-service
+  ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1
+  Description: Backend API
+  Resources: 2
+  Remote: no
+  Created: 2026-02-08 12:46
+
+Linked Resources
+  Resource          Type            Sandbox              Read-Only
+  ----------------  --------------  --------------------  ---------
+  local/api-repo    git-checkout    git_worktree          no
+  local/staging-db  local/database  transaction_rollback  yes
+
+Validations (3)
+  ID           Command                                Mode
+  -----------  -------------------------------------  -----------
+  val_01HXM5A  pytest --cov=src --cov-fail-under=80   required
+  val_01HXM5B  ruff check .                           required
+  val_01HXM5C  node scripts/check-bundle-size.js      informational
+
+[OK] Project loaded
+
+ +**What this produces in `rich` format:** + +

+╭─ Project Details ──────────────╮
+│ Name: local/api-service        │
+│ ID: 01HXM4T08Y0N5R9VZ4QX4BPTZ1 │
+│ Description: Backend API       │
+│ Resources: 2                   │
+│ Remote: no                     │
+│ Created: 2026-02-08 12:46      │
+╰────────────────────────────────╯
+
+╭─ Linked Resources ──────────────────────────────────────────────────────╮
+│ Resource          Type            Sandbox              Read-Only        │
+│ ────────────────  ──────────────  ────────────────────  ─────────       │
+│ local/api-repo   git-checkout    git_worktree         no                │
+│ local/staging-db local/database  transaction_rollback yes               │
+╰─────────────────────────────────────────────────────────────────────────╯
+
+╭─ Validations (3) ───────────────────────────────────────────────────╮
+│ ID           Command                                Mode            │
+│ ───────────  ─────────────────────────────────────  ───────────     │
+│ val_01HXM5A  pytest --cov=src --cov-fail-under=80   required        │
+│ val_01HXM5B  ruff check .                           required        │
+│ val_01HXM5C  node scripts/check-bundle-size.js      informational   │
+╰─────────────────────────────────────────────────────────────────────╯
+
+✓ OK Project loaded
+
+ +**What this produces in `json` format:** + +

+{
+  "command": "project show",
+  "status": "ok",
+  "exit_code": 0,
+  "data": {
+    "project_details": {
+      "Name": "local/api-service",
+      "ID": "01HXM4T08Y0N5R9VZ4QX4BPTZ1",
+      "Description": "Backend API",
+      "Resources": "2",
+      "Remote": "no",
+      "Created": "2026-02-08 12:46"
+    },
+    "linked_resources": [
+      {
+        "Resource": "local/api-repo",
+        "Type": "git-checkout",
+        "Sandbox": "git_worktree",
+        "Read-Only": "no"
+      },
+      {
+        "Resource": "local/staging-db",
+        "Type": "local/database",
+        "Sandbox": "transaction_rollback",
+        "Read-Only": "yes"
+      }
+    ],
+    "validations": [
+      {
+        "ID": "val_01HXM5A",
+        "Command": "pytest --cov=src --cov-fail-under=80",
+        "Mode": "required"
+      },
+      {
+        "ID": "val_01HXM5B",
+        "Command": "ruff check .",
+        "Mode": "required"
+      },
+      {
+        "ID": "val_01HXM5C",
+        "Command": "node scripts/check-bundle-size.js",
+        "Mode": "informational"
+      }
+    ]
+  },
+  "timing": { "duration_ms": 42 },
+  "messages": [
+    { "level": "ok", "text": "Project loaded" }
+  ]
+}
+
+ +In all three formats, the producer code is **identical**. The `OutputSession` and its materialization strategy handle the differences transparently. + +##### Example 2: Streaming Rows into a Table + +A command that streams rows into a table as results arrive from a paginated API. The table handle stays open while the producer fetches pages. + +**Producer code** (`agents resource list`): + +

+async def cmd_resource_list(session: OutputSession, project: str | None) -> None:
+    """Implementation of 'agents resource list'."""
+    
+    # Create the table handle — it will accumulate rows as we stream them
+    table = session.table("Resources", columns=[
+        ColumnDef(name="Name", type="string", style_hint="identifier"),
+        ColumnDef(name="Type"),
+        ColumnDef(name="Project"),
+        ColumnDef(name="Sandbox"),
+        ColumnDef(name="Status"),
+    ], sort_key="Name")
+    
+    # Create a progress indicator for the fetch operation
+    progress = session.progress("Fetching resources...", indeterminate=True)
+    
+    # Stream pages from the API
+    count = 0
+    async for page in api.list_resources_paginated(project=project):
+        for resource in page.items:
+            table.add_row({
+                "Name": resource.name,
+                "Type": resource.type,
+                "Project": resource.project,
+                "Sandbox": resource.sandbox_strategy,
+                "Status": resource.status,
+            })
+            count += 1
+        
+        # Update progress label with count so far
+        progress.set_label(f"Fetching resources... ({count} found)")
+    
+    # Close the progress indicator (it has served its purpose)
+    progress.close()
+    
+    # Set summary and close the table
+    table.set_summary({"total": count})
+    table.close()
+    
+    # Final status
+    session.status(f"{count} resources listed", level="ok")
+
+ +**What this looks like in `plain` format** (SequentialBufferMaterializer): + +The progress indicator is rendered as a static line. The table is buffered until `table.close()` is called, then rendered in full. The user sees nothing until the fetch is complete — then the entire result appears at once: + +

+Fetching resources... (47 found) [done]
+
+Resources
+  Name                  Type            Project            Sandbox              Status
+  --------------------  --------------  -----------------  --------------------  --------
+  local/api-repo        git-checkout    local/api-service  git_worktree          active
+  local/staging-db      local/database  local/api-service  transaction_rollback  active
+  local/docs-repo       git-checkout    local/docs-site    git_worktree          active
+  ... (44 more rows)
+
+  Total: 47
+
+[OK] 47 resources listed
+
+ +**What this looks like in `rich` format** (LiveMaterializer): + +The progress spinner animates in real-time. The table updates in-place as rows arrive — each new row appears at the bottom of the table, the row count updates, and the terminal display is rewritten without scrolling. This is a static snapshot of the live display mid-fetch: + +

+⠙ Fetching resources... (23 found)
+
+╭─ Resources ────────────────────────────────────────────────────────────────────────────╮
+│ Name                  Type            Project            Sandbox              Status   │
+│ ────────────────────  ──────────────  ─────────────────  ────────────────────  ──────  │
+│ local/api-repo        git-checkout    local/api-service  git_worktree          active  │
+│ local/staging-db      local/database  local/api-service  transaction_rollback  active  │
+│ local/docs-repo       git-checkout    local/docs-site    git_worktree          active  │
+│   ...                                                                                  │
+│ local/test-fixtures   git-checkout    local/api-service  git_worktree          active  │
+│                                                                                        │
+│ Showing 1-23 of 23 (fetching...)                                                       │
+╰────────────────────────────────────────────────────────────────────────────────────────╯
+
+ +In `rich` mode, the spinner animates, the table grows as rows arrive, and the row count updates — all in-place without scrolling. When the fetch completes, the spinner resolves to `✓`, and the table shows its final state. + +##### Example 3: Concurrent Parallel Operations (Two Tables Simultaneously) + +This is the key motivating example for the reactive architecture. Two tables are populated simultaneously by parallel workers, and the producer code is completely format-agnostic. + +**Producer code** (`agents plan status` — showing resources and active tool calls concurrently): + +

+async def cmd_plan_status(session: OutputSession, plan_id: str) -> None:
+    """Implementation of 'agents plan status <plan_id>'.
+    
+    This command fetches plan metadata, then concurrently streams two data
+    sources: resource statuses and active tool call logs. Both data sources
+    are long-running — they produce results over several seconds as the
+    backend resolves each item.
+    """
+    plan = await api.get_plan(plan_id)
+    
+    # Panel: Plan metadata (created and closed synchronously)
+    with session.panel("Plan") as panel:
+        panel.set_entries({
+            "Plan ID": plan.id,
+            "Phase": plan.phase,
+            "State": plan.state,
+            "Action": plan.action,
+            "Project": plan.project,
+            "Started": plan.started_at.strftime("%H:%M:%S"),
+        }, style_hints={
+            "Plan ID": "identifier",
+            "Phase": "info",
+            "State": "warning" if plan.state == "processing" else "success",
+        })
+    
+    # Create both table handles BEFORE starting concurrent producers.
+    # Declaration order determines rendering order in sequential formats.
+    resource_table = session.table("Resource Status", columns=[
+        ColumnDef(name="Resource", style_hint="identifier"),
+        ColumnDef(name="Type"),
+        ColumnDef(name="Status"),
+        ColumnDef(name="Latency", type="string", alignment="right"),
+    ])
+    
+    tool_table = session.table("Tool Call Log", columns=[
+        ColumnDef(name="#", type="number", alignment="right"),
+        ColumnDef(name="Tool"),
+        ColumnDef(name="Target"),
+        ColumnDef(name="Result"),
+        ColumnDef(name="Duration", type="string", alignment="right"),
+    ])
+    
+    # --- Run two producers concurrently ---
+    # Each producer writes to its own handle. Neither producer knows
+    # which format is active. The materialization strategy handles
+    # the coordination.
+    
+    async def stream_resources():
+        """Producer A: streams resource status checks."""
+        async for status in api.stream_resource_statuses(plan.id):
+            resource_table.add_row({
+                "Resource": status.resource_name,
+                "Type": status.resource_type,
+                "Status": status.status,
+                "Latency": f"{status.latency_ms}ms",
+            })
+        resource_table.close()
+    
+    async def stream_tool_calls():
+        """Producer B: streams tool call results."""
+        async for call in api.stream_tool_calls(plan.id):
+            tool_table.add_row({
+                "#": call.sequence_number,
+                "Tool": call.tool_name,
+                "Target": call.target,
+                "Result": call.result_summary,
+                "Duration": f"{call.duration_ms}ms",
+            })
+        tool_table.close()
+    
+    # Launch both producers concurrently
+    await asyncio.gather(stream_resources(), stream_tool_calls())
+    
+    # Final status
+    session.status(f"Plan {plan_id} status retrieved", level="ok")
+
+ +**What this produces in `plain` format** (SequentialBufferMaterializer): + +Both tables are populated concurrently, but the materializer buffers each one and renders them in **declaration order** when their handles close. The user sees nothing until the first-declared table (Resource Status) closes, then it prints. Then when the second table (Tool Call Log) closes, it prints. Data may have arrived interleaved across both tables, but the output is perfectly sequential: + +

+Plan
+  Plan ID: 01HXM7A9
+  Phase: execute
+  State: processing
+  Action: local/code-coverage
+  Project: local/api-service
+  Started: 12:58:10
+
+Resource Status
+  Resource          Type            Status   Latency
+  ----------------  --------------  -------  -------
+  local/api-repo    git-checkout    ready    42ms
+  local/staging-db  local/database  ready    128ms
+
+Tool Call Log
+  #   Tool        Target                  Result         Duration
+  --  ----------  ----------------------  -------------  --------
+   1  read_file   src/auth/__init__.py    200 lines      0.1s
+   2  read_file   src/auth/session.py     340 lines      0.1s
+   3  write_file  tests/test_auth.py      created        0.2s
+   4  edit_file   src/auth/session.py     12 lines +/-   0.3s
+   5  run_tests   pytest tests/test_auth  3 passed       2.1s
+
+[OK] Plan 01HXM7A9 status retrieved
+
+ +**What this produces in `rich` format** (LiveMaterializer): + +Both tables are visible simultaneously and update in-place as data arrives. This snapshot shows the display mid-stream — the resource table has two rows and the tool call table has three so far: + +

+╭─ Plan ──────────────────────────────╮
+│ Plan ID: 01HXM7A9                   │
+│ Phase: execute                      │
+│ State: processing                   │
+│ Action: local/code-coverage         │
+│ Project: local/api-service          │
+│ Started: 12:58:10                   │
+╰─────────────────────────────────────╯
+
+╭─ Resource Status ⠙ ───────────────────────────────────────────╮
+│ Resource          Type            Status   Latency            │
+│ ────────────────  ──────────────  ───────  ───────            │
+│ local/api-repo    git-checkout    ready    42ms               │
+│ local/staging-db  local/database  ready    128ms              │
+│                                                               │
+│ 2 resources (streaming...)                                    │
+╰───────────────────────────────────────────────────────────────╯
+
+╭─ Tool Call Log ⠙ ────────────────────────────────────────────────────╮
+│ #   Tool        Target                  Result         Duration      │
+│ ──  ──────────  ──────────────────────  ─────────────  ────────      │
+│  1  read_file   src/auth/__init__.py    200 lines      0.1s          │
+│  2  read_file   src/auth/session.py     340 lines      0.1s          │
+│  3  write_file  tests/test_auth.py      created        0.2s          │
+│                                                                      │
+│ 3 calls (streaming...)                                               │
+╰──────────────────────────────────────────────────────────────────────╯
+
+ +In `rich` mode, both tables have animated spinners in their titles indicating active streaming. As new rows arrive from either producer, the corresponding table's display is updated in-place. When a producer finishes and closes its handle, the spinner resolves to a `✓` and the "(streaming...)" indicator is removed. The other table continues updating independently. + +**What this produces in `json` format** (AccumulateMaterializer): + +Nothing is printed until the session closes. Then the complete accumulated state is serialized: + +

+{
+  "command": "plan status",
+  "status": "ok",
+  "exit_code": 0,
+  "data": {
+    "plan": {
+      "Plan ID": "01HXM7A9",
+      "Phase": "execute",
+      "State": "processing",
+      "Action": "local/code-coverage",
+      "Project": "local/api-service",
+      "Started": "12:58:10"
+    },
+    "resource_status": [
+      { "Resource": "local/api-repo", "Type": "git-checkout", "Status": "ready", "Latency": "42ms" },
+      { "Resource": "local/staging-db", "Type": "local/database", "Status": "ready", "Latency": "128ms" }
+    ],
+    "tool_call_log": [
+      { "#": 1, "Tool": "read_file", "Target": "src/auth/__init__.py", "Result": "200 lines", "Duration": "0.1s" },
+      { "#": 2, "Tool": "read_file", "Target": "src/auth/session.py", "Result": "340 lines", "Duration": "0.1s" },
+      { "#": 3, "Tool": "write_file", "Target": "tests/test_auth.py", "Result": "created", "Duration": "0.2s" },
+      { "#": 4, "Tool": "edit_file", "Target": "src/auth/session.py", "Result": "12 lines +/-", "Duration": "0.3s" },
+      { "#": 5, "Tool": "run_tests", "Target": "pytest tests/test_auth", "Result": "3 passed", "Duration": "2.1s" }
+    ]
+  },
+  "timing": { "duration_ms": 3200 },
+  "messages": [
+    { "level": "ok", "text": "Plan 01HXM7A9 status retrieved" }
+  ]
+}
+
+ +The critical point: **the producer code in all three formats is exactly the same**. The `asyncio.gather` call runs both producers concurrently regardless of format. The materialization strategy — `LiveMaterializer`, `SequentialBufferMaterializer`, or `AccumulateMaterializer` — transparently decides how that concurrent data reaches the user. + +##### Example 4: Progress with Concurrent Sub-Operations + +A command that executes a multi-step process with a progress indicator, where some steps involve parallel sub-operations. + +**Producer code** (`agents plan execute`): + +

+async def cmd_plan_execute(session: OutputSession, plan_id: str) -> None:
+    """Implementation of 'agents plan execute <plan_id>'."""
+    plan = await api.get_plan(plan_id)
+    
+    # Panel: Execution metadata
+    with session.panel("Execution") as panel:
+        panel.set_entries({
+            "Plan": plan.id,
+            "Phase": "execute",
+            "Sandbox": plan.sandbox_strategy,
+            "Worker": plan.worker,
+            "Started": datetime.now().strftime("%H:%M:%S"),
+        })
+    
+    # Progress indicator with named steps
+    progress = session.progress("Executing plan", total=4, steps=[
+        "Collect context",
+        "Run tools",
+        "Build changeset",
+        "Validate",
+    ])
+    
+    # Step 1: Collect context
+    progress.set_step_status("Collect context", "active")
+    context = await api.collect_context(plan.id)
+    progress.set_step_status("Collect context", "done")
+    progress.set_progress(1, 4)
+    
+    # Step 2: Run tools (parallel sub-operations)
+    progress.set_step_status("Run tools", "active")
+    tool_results = await api.run_tools(plan.id, context)
+    progress.set_step_status("Run tools", "done")
+    progress.set_progress(2, 4)
+    
+    # Step 3: Build changeset
+    progress.set_step_status("Build changeset", "active")
+    changeset = await api.build_changeset(plan.id, tool_results)
+    progress.set_step_status("Build changeset", "done")
+    progress.set_progress(3, 4)
+    
+    # Step 4: Validate
+    progress.set_step_status("Validate", "active")
+    validation = await api.validate_changeset(plan.id, changeset)
+    progress.set_step_status("Validate", "done")
+    progress.set_progress(4, 4)
+    
+    progress.close()
+    
+    # Summary panel
+    with session.panel("Strategy Summary") as panel:
+        panel.set_entries({
+            "Decisions": str(changeset.decision_count),
+            "Invariants": str(changeset.invariant_count),
+            "Planned Child Plans": f"{changeset.child_plan_count}+",
+            "Estimated Files": f"~{changeset.file_count}",
+            "Risk": changeset.risk_level,
+        })
+    
+    # Final status
+    if validation.passed:
+        session.status("Execution complete — all validations passed", level="ok")
+    else:
+        session.status(
+            f"Execution complete — {validation.failure_count} validation(s) failed",
+            level="warn",
+            detail=validation.summary,
+        )
+
+ +**What this looks like in `plain` format:** + +The progress indicator renders as a static step list. Since `SequentialBufferMaterializer` buffers each element until its handle closes, the progress indicator is not visible during execution — it appears as a completed snapshot after the fact: + +

+Execution
+  Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+  Phase: execute
+  Sandbox: git_worktree
+  Worker: local/executor
+  Started: 12:58:10
+
+Executing plan  [4/4]
+  [x] Collect context
+  [x] Run tools
+  [x] Build changeset
+  [x] Validate
+
+Strategy Summary
+  Decisions: 8
+  Invariants: 2
+  Planned Child Plans: 2+
+  Estimated Files: ~12
+  Risk: low
+
+[OK] Execution complete — all validations passed
+
+ +**What this looks like in `rich` format:** + +The progress indicator is live — the spinner animates, the progress bar fills, and steps transition from pending to active to done in real-time. This snapshot shows the display mid-execution (step 3 active): + +

+╭─ Execution ──────────────────────╮
+│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+│ Phase: execute                   │
+│ Sandbox: git_worktree            │
+│ Worker: local/executor           │
+│ Started: 12:58:10                │
+╰──────────────────────────────────╯
+
+Executing plan ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  50%  elapsed 0:00:13
+  ✓ Collect context .................. 0.8s
+  ✓ Run tools ...................... 12.4s
+  ⠙ Build changeset ................. (running)
+  ○ Validate ........................ (pending)
+
+ +When execution completes, the progress indicator resolves to its final state (all steps `✓`), the Strategy Summary panel appears below it, and the final status message is displayed. + +##### Example 5: Error Mid-Stream with Partial Output + +A command where one of multiple concurrent producers fails, demonstrating graceful partial output. + +**Producer code** (hypothetical `agents resource verify`): + +

+async def cmd_resource_verify(session: OutputSession, project: str) -> None:
+    """Verify all resources in a project. Some verifications may fail."""
+    resources = await api.list_project_resources(project)
+    
+    # Create a table that will be populated concurrently
+    results_table = session.table("Verification Results", columns=[
+        ColumnDef(name="Resource", style_hint="identifier"),
+        ColumnDef(name="Type"),
+        ColumnDef(name="Check"),
+        ColumnDef(name="Status"),
+        ColumnDef(name="Detail"),
+    ])
+    
+    # Progress indicator
+    progress = session.progress(
+        "Verifying resources",
+        total=len(resources),
+        steps=[r.name for r in resources],
+    )
+    
+    # Verify each resource concurrently
+    async def verify_one(resource):
+        progress.set_step_status(resource.name, "active")
+        try:
+            result = await api.verify_resource(resource.id)
+            results_table.add_row({
+                "Resource": resource.name,
+                "Type": resource.type,
+                "Check": result.check_name,
+                "Status": "pass" if result.passed else "fail",
+                "Detail": result.detail,
+            })
+            progress.set_step_status(
+                resource.name,
+                "done" if result.passed else "error",
+            )
+        except ApiError as e:
+            results_table.add_row({
+                "Resource": resource.name,
+                "Type": resource.type,
+                "Check": "connection",
+                "Status": "error",
+                "Detail": str(e),
+            })
+            progress.set_step_status(resource.name, "error")
+        progress.increment()
+    
+    # Launch all verifications concurrently
+    await asyncio.gather(
+        *[verify_one(r) for r in resources],
+        return_exceptions=True,  # Don't fail fast — collect all results
+    )
+    
+    progress.close()
+    results_table.close()
+    
+    # Summarize
+    snapshot = results_table.element
+    pass_count = sum(1 for r in snapshot.rows if r["Status"] == "pass")
+    fail_count = sum(1 for r in snapshot.rows if r["Status"] in ("fail", "error"))
+    
+    if fail_count == 0:
+        session.status(f"All {pass_count} resources verified", level="ok")
+    else:
+        session.status(
+            f"{fail_count} of {pass_count + fail_count} resources failed verification",
+            level="error",
+        )
+
+ +**What this produces in `plain` format** (after all concurrent verifications complete): + +

+Verifying resources  [3/3]
+  [x] local/api-repo
+  [!] local/staging-db
+  [x] local/docs-repo
+
+Verification Results
+  Resource          Type            Check       Status  Detail
+  ----------------  --------------  ----------  ------  ----------------------------------
+  local/api-repo    git-checkout    integrity   pass    All refs valid
+  local/staging-db  local/database  connection  error   Connection refused (port 5432)
+  local/docs-repo   git-checkout    integrity   pass    All refs valid
+
+[ERROR] 1 of 3 resources failed verification
+
+ +**What this produces in `color` format:** + +

+Verifying resources  [3/3]
+  [x] local/api-repo
+  [!] local/staging-db
+  [x] local/docs-repo
+
+Verification Results
+  Resource          Type            Check       Status  Detail
+  ----------------  --------------  ----------  ------  ----------------------------------
+  local/api-repo    git-checkout    integrity   pass    All refs valid
+  local/staging-db  local/database  connection  error   Connection refused (port 5432)
+  local/docs-repo   git-checkout    integrity   pass    All refs valid
+
+[ERROR] 1 of 3 resources failed verification
+
+ +**What this produces in `yaml` format:** + +

+command: resource verify
+status: error
+exit_code: 1
+data:
+  verification_results:
+    - Resource: local/api-repo
+      Type: git-checkout
+      Check: integrity
+      Status: pass
+      Detail: All refs valid
+    - Resource: local/staging-db
+      Type: local/database
+      Check: connection
+      Status: error
+      Detail: "Connection refused (port 5432)"
+    - Resource: local/docs-repo
+      Type: git-checkout
+      Check: integrity
+      Status: pass
+      Detail: All refs valid
+timing:
+  duration_ms: 2840
+messages:
+  - level: error
+    text: "1 of 3 resources failed verification"
+
+ +In all formats, the concurrent verification produces a complete result set with partial failures clearly visible. The producer code uses `return_exceptions=True` on `asyncio.gather` to ensure all verifications complete even if some fail, and the error handling within each `verify_one` coroutine ensures that failures are recorded as table rows rather than causing the entire command to abort. + ## Behavior -### Automation Levels +### Automation Profiles -Automation levels determine which phase transitions happen automatically. +Automation profiles determine which phase transitions happen automatically and which require human approval. -#### Automation Level Modes +#### Overview -| Mode | Behavior | -|------|----------| -| **Manual** | User explicitly triggers: create → use → execute → apply. Every phase transition requires a command. Every decision point pauses for human input. User sees context, alternatives, and recommendation. User provides explicit choice or custom guidance. | -| **Review-before-apply** | Strategize + Execute happen automatically. AI makes all decisions autonomously. System pauses before Apply to show diff and ask for approval. User can approve, reject, or correct specific decisions. | -| **Full automation** | System runs all phases automatically end-to-end. AI makes all decisions. Execution proceeds through apply. Human notified of completion. Rollback available if issues detected. | +An **automation profile** is a named collection of boolean flags that controls which tasks are automated vs. require human approval. Profiles follow the same `/` naming convention as actors, tools, skills, and other entities. Profiles are managed via the `agents automation-profile` CLI commands. -#### Progressive Trust Building +##### Automatable Tasks -New users typically follow this progression: -1. Start with manual mode to understand system behavior -2. Move to review-before-apply as confidence builds -3. Enable full automation for specific task types -4. Gradually expand full automation scope +Each automation profile specifies a true/false value for each of the following automatable tasks: -#### Semantic Escalation +| Flag | Description | When `true` | When `false` | +|------|-------------|-------------|--------------| +| `auto_strategize` | Automatically enter Strategize after `plan use` | Strategize begins immediately | System pauses; user must run `agents plan execute` to start Strategize | +| `auto_execute` | Automatically proceed from Strategize to Execute | Execute begins when Strategize completes | System pauses after Strategize; user reviews strategy and runs `agents plan execute` | +| `auto_apply` | Automatically proceed from Execute to Apply | Apply begins when Execute completes | System pauses after Execute; user reviews diffs and runs `agents plan apply` | +| `auto_decisions_strategize` | Automatically make decisions during Strategize | Strategy actor makes all decisions autonomously | System pauses at each decision point for user input | +| `auto_decisions_execute` | Automatically make decisions during Execute | Execution actor makes all decisions autonomously | System pauses at each decision point for user input | +| `auto_validation_fix` | Automatically attempt to fix validation failures | Execution actor self-fixes failing required validations within strategy bounds | System pauses on validation failure; user must provide guidance | +| `auto_strategy_revision` | Automatically revise strategy when Execute cannot solve within constraints | System re-runs Strategize for affected subtree | System pauses and asks user whether to revise the strategy | +| `auto_child_plans` | Automatically spawn and execute child plans | Child plans are created and executed without pausing | System pauses before spawning each child plan for approval | +| `auto_retry_transient` | Automatically retry on transient failures (network, timeout, rate-limit) | System retries automatically with backoff | System pauses and asks user to retry or abort | +| `auto_checkpoint_restore` | Automatically restore from checkpoint on failure | System rolls back to last checkpoint and retries | System pauses; user decides whether to restore or intervene | +| `require_sandbox` | Require sandbox isolation for Execute phase | Execute must run in a sandbox (worktree, container, etc.) | Sandbox is optional; Execute may modify resources directly | +| `require_checkpoints` | Require checkpointing during Execute | Tools must create checkpoints before writes | Checkpointing is optional | +| `allow_unsafe_tools` | Allow execution of tools marked as unsafe | Unsafe tools can be invoked | Unsafe tools are blocked; only safe tools are allowed | -Even in full automation mode, the system understands when it needs help: +##### Built-in Automation Profiles -```python -class AutonomyController: - def assess_decision_confidence(self, decision, context): +CleverAgents ships with six built-in automation profiles. Built-in profiles use no namespace prefix. + +| Flag | `locked-down` | `manual` | `supervised` | `trusted` | `autonomous` | `full-auto` | +|------|:---:|:---:|:---:|:---:|:---:|:---:| +| `auto_strategize` | - | - | ✓ | ✓ | ✓ | ✓ | +| `auto_execute` | - | - | - | ✓ | ✓ | ✓ | +| `auto_apply` | - | - | - | - | - | ✓ | +| `auto_decisions_strategize` | - | - | ✓ | ✓ | ✓ | ✓ | +| `auto_decisions_execute` | - | - | - | ✓ | ✓ | ✓ | +| `auto_validation_fix` | - | - | - | ✓ | ✓ | ✓ | +| `auto_strategy_revision` | - | - | - | - | ✓ | ✓ | +| `auto_child_plans` | - | - | - | ✓ | ✓ | ✓ | +| `auto_retry_transient` | - | - | ✓ | ✓ | ✓ | ✓ | +| `auto_checkpoint_restore` | - | - | - | - | ✓ | ✓ | +| `require_sandbox` | ✓ | ✓ | ✓ | ✓ | ✓ | - | +| `require_checkpoints` | ✓ | ✓ | ✓ | ✓ | ✓ | - | +| `allow_unsafe_tools` | - | - | - | - | - | ✓ | + +**`locked-down`**: Maximum human control. Every phase transition, every decision, every child plan requires explicit human approval. Sandbox and checkpoints are mandatory. Unsafe tools are blocked. Use for: critical production systems, first-time exploration of an unfamiliar codebase, high-risk infrastructure changes. + +**`manual`**: Human drives all phase transitions but decisions within Strategize and Execute are still manual. Similar to `locked-down` but serves as the default starting point. Use for: new users learning the system, sensitive projects, regulatory environments. + +**`supervised`**: Strategize runs automatically with autonomous decisions, but the system pauses before Execute for human review of the strategy. Transient failures are retried automatically. Use for: projects where you trust the planning but want to review before execution begins. + +**`trusted`**: Strategize and Execute run automatically with autonomous decisions. Validation failures are self-fixed. Child plans are spawned automatically. The system pauses only before Apply for human review of the final diffs. Use for: day-to-day feature development, routine refactoring, test generation. + +**`autonomous`**: Everything runs automatically except Apply. The system can even revise its own strategy if execution hits a wall, and restore from checkpoints on failure. Use for: well-understood projects, batch operations, tasks with strong invariant coverage. + +**`full-auto`**: Complete end-to-end automation including Apply. No sandbox or checkpoint requirements. Unsafe tools are allowed. Use for: low-risk routine tasks (dependency updates, documentation generation, formatting), CI/CD pipeline integration, trusted batch operations with rollback capabilities. + +##### Profile Precedence + +Automation profiles are determined using this precedence (highest to lowest): + +1. **Plan-level**: Explicitly set via `--automation-profile` on `agents plan use` +2. **Action-level**: Set on the action via `--automation-profile` on `agents action create` +3. **Project-level**: Set via `agents config set automation-profile --project ` +4. **Global-level**: Set via `agents config set automation-profile ` + +The **effective profile** for a plan is resolved at the moment of `agents plan use`. Once resolved, the profile is **locked to that plan** — subsequent changes to project or global profiles do not affect running plans. + +##### Child Plan Profile Inheritance + +Child plans inherit the parent plan's effective automation profile. If the parent's profile is changed explicitly after creation, new child plans use the new profile while already-running child plans retain their original profile. + +##### Custom Automation Profiles + +Custom profiles are created via YAML configuration files and registered with `agents automation-profile add`: + +

+# File: profiles/careful-auto.yaml
+name: local/careful-auto
+description: "Autonomous execution with mandatory sandbox and manual apply"
+flags:
+  auto_strategize: true
+  auto_execute: true
+  auto_apply: false
+  auto_decisions_strategize: true
+  auto_decisions_execute: true
+  auto_validation_fix: true
+  auto_strategy_revision: false
+  auto_child_plans: true
+  auto_retry_transient: true
+  auto_checkpoint_restore: true
+  require_sandbox: true
+  require_checkpoints: true
+  allow_unsafe_tools: false
+
+ +

+agents automation-profile add --config ./profiles/careful-auto.yaml
+
+ +##### Semantic Escalation + +Even when a profile sets a task to automatic, the system may still escalate to the user when confidence is low. Semantic escalation is orthogonal to automation profiles — it provides a safety net that works within any profile: + +

+class AutonomyController:
+    def assess_decision_confidence(self, decision, context):
         factors = {
-            'past_success_rate': self.get_historical_success(decision.type),
-            'codebase_familiarity': self.get_familiarity_score(context.project),
-            'risk_assessment': self.evaluate_risk(decision),
-            'invariant_complexity': self.analyze_invariants(decision)
+            'past_success_rate': self.get_historical_success(decision.type),
+            'codebase_familiarity': self.get_familiarity_score(context.project),
+            'risk_assessment': self.evaluate_risk(decision),
+            'invariant_complexity': self.analyze_invariants(decision)
         }
         
         confidence = self.compute_confidence(factors)
         
-        if confidence < self.threshold:
-            if self.automation_level == 'full':
-                # Even in full automation, critical decisions escalate
-                return RequestHumanGuidance(decision, factors)
+        if confidence < self.threshold:
+            # Even in autonomous profiles, critical decisions escalate
+            return RequestHumanGuidance(decision, factors)
         
-        return ProceedAutonomously(decision)
-```
+        return ProceedAutonomously(decision)
+
-#### Automation Level Hierarchy +##### Progressive Trust Building -Automation levels are determined using this precedence (highest to lowest): +New users typically follow this progression: -1. **Plan-level**: Explicitly set when using an action on projects -2. **Session-level**: Set for the current session -3. **Global-level**: Persisted application configuration - -```bash -# Set global automation level (persists across sessions) -agents config set automation-level review-before-apply - -# Set session automation level (overrides global for this session) -agents session set automation-level full-automation - -# Use action with explicit automation level (overrides session and global) -agents plan use local/my-action --project my-proj --automation-level manual -``` - -#### Automation Level Persistence Rules - -1. **Global level**: Persisted in application configuration. Default is `manual` on fresh install. - -2. **Session level**: Lives for the duration of the session. Not persisted. - -3. **Plan level**: Once a plan's automation level is determined (at the moment of `use`), it is **locked to that plan**. Even if the session or global level changes later, the plan retains its original automation level. - -4. **Explicit change**: A plan's automation level can be changed **explicitly** after creation: - -```bash -agents plan set-automation-level full-automation -``` - -#### Child Plan Automation Levels - -**Child plans inherit the parent plan's automation level.** - -However, if the parent plan's automation level is changed explicitly mid-execution, new child plans will use the new level while already-completed child plans retain their original level. - -#### Granular Automation Flags - -For fine-grained control, additional flags can modify behavior: - -* `auto_strategize` - Automatically proceed from Action to Strategize -* `auto_execute` - Automatically proceed from Strategize to Execute -* `auto_apply` - Automatically proceed from Execute to Apply -* `auto_retry_on_failure` - Automatically retry failed phases - -This allows combinations like: -* Auto strategize, manual execute, manual apply (for risky infra tasks) -* Auto strategize + execute, manual apply (the review-before-apply pattern) +1. Start with `manual` to understand system behavior +1. Move to `supervised` as confidence in the planning phase builds +1. Adopt `trusted` for routine development tasks +1. Enable `autonomous` for well-understood projects with strong invariant coverage +1. Use `full-auto` for low-risk batch operations or CI/CD integration ### Validation and Guardrails @@ -9592,9 +12975,9 @@ This makes plan runs auditable and correctable. When user requests correction at Decision B: 1. **Mark for Correction** - ``` + 

    Decision B.superseded_by = new_decision_id
-   ```
+
2. **Identify Downstream Impact** - Recursively collect all decisions that depend on Decision B (including `invariant_enforced`, `subplan_spawn`, and `subplan_parallel_spawn` decisions) @@ -9632,26 +13015,26 @@ Once a plan is applied: #### CLI Commands for Correction -```bash -# View decision tree -agents plan tree -agents plan tree --format=json # For visualization tools +

+# View decision tree
+agents plan tree <plan_id>
+agents --format=json plan tree <plan_id>  # For visualization tools
 
-# Inspect a specific decision
-agents plan explain 
-# Shows: question, chosen option, alternatives, rationale, downstream impact
+# Inspect a specific decision
+agents plan explain <decision_id>
+# Shows: question, chosen option, alternatives, rationale, downstream impact
 
-# Correct via revert-and-replay
-agents plan correct  --mode=revert --guidance ""
-# Re-executes from that point with the new guidance
+# Correct via revert-and-replay
+agents plan correct <decision_id> --mode=revert --guidance "<what the decision should be>"
+# Re-executes from that point with the new guidance
 
-# Correct via append (add fix at end)  
-agents plan correct  --mode=append --guidance ""
-# Creates a new child plan to fix the outcome without rewriting history
+# Correct via append (add fix at end)  
+agents plan correct <decision_id> --mode=append --guidance "<description of the fix>"
+# Creates a new child plan to fix the outcome without rewriting history
 
-# Compare old vs new after correction
-agents plan diff 
-```
+# Compare old vs new after correction
+agents plan diff --correction <correction_attempt_id>
+
#### Correction Safety @@ -9742,7 +13125,7 @@ To debug large plans: ## Summary of Key Intended Behaviors (If You Only Read One Section) -* Plans follow **Action → Strategize → Execute → Apply** with automation levels controlling transitions. +* Plans follow **Action → Strategize → Execute → Apply** with **automation profiles** controlling transitions and decision automation. * **Strategize is read-only** and produces a strategy + blueprint. * **Execute happens in a sandbox**, can spawn child plans, and should support checkpoints/rollback when enabled. * **Apply commits changes** from sandbox to real project after review/validation. @@ -9809,25 +13192,25 @@ The current system generates code as a single text blob that gets written to one #### Implementation Steps 1. **Create Resource Abstraction Layer** - ```python - # New modules needed: + 

+   # New modules needed:
    src/cleveragents/domain/models/resources.py
    src/cleveragents/domain/resources/handlers.py
    src/cleveragents/domain/resources/sandbox.py
-   ```
+
2. **Implement Built-in Tools (via built-in skills)** - ```python - # Core file operations (provided by built-in skill groups) - read_file(path: str) -> str - write_file(path: str, content: str) -> None - edit_file(path: str, changes: list[Edit]) -> None - delete_file(path: str) -> None - move_file(src: str, dst: str) -> None - create_directory(path: str) -> None - list_files(pattern: str) -> list[str] - search_files(pattern: str, content_pattern: str) -> list[Match] - ``` + 

+   # Core file operations (provided by built-in skill groups)
+   read_file(path: str) -> str
+   write_file(path: str, content: str) -> None
+   edit_file(path: str, changes: list[Edit]) -> None
+   delete_file(path: str) -> None
+   move_file(src: str, dst: str) -> None
+   create_directory(path: str) -> None
+   list_files(pattern: str) -> list[str]
+   search_files(pattern: str, content_pattern: str) -> list[Match]
+
3. **Connect Tools to ChangeSet** - Each tool invocation that modifies resources creates a `Change` record @@ -9844,15 +13227,15 @@ Execute phase currently writes directly to the project. The specification requir #### Implementation Steps 1. **Define Sandbox Interface** - ```python - class Sandbox(Protocol): - def create() -> SandboxRef - def read(path: str) -> Content - def write(path: str, content: Content) -> Change - def diff() -> DiffView - def commit() -> None - def rollback() -> None - ``` + 

+   class Sandbox(Protocol):
+       def create() -> SandboxRef
+       def read(path: str) -> Content
+       def write(path: str, content: Content) -> Change
+       def diff() -> DiffView
+       def commit() -> None
+       def rollback() -> None
+
2. **Implement Sandbox Strategies** - `GitWorktreeSandbox` - For git repositories (preferred) @@ -9874,20 +13257,20 @@ No decision tracking exists. The specification's key innovation is recording eve #### Implementation Steps 1. **Create Decision Models** - ```sql - -- New tables needed - CREATE TABLE decisions ( - decision_id TEXT PRIMARY KEY, -- ULID - plan_id TEXT NOT NULL, - parent_decision_id TEXT, - decision_type TEXT NOT NULL, - question TEXT NOT NULL, - chosen_option TEXT NOT NULL, - alternatives_considered TEXT, -- JSON array - context_snapshot TEXT NOT NULL, -- JSON - created_at TEXT NOT NULL + 

+   -- New tables needed
+   CREATE TABLE decisions (
+       decision_id TEXT PRIMARY KEY,  -- ULID
+       plan_id TEXT NOT NULL,
+       parent_decision_id TEXT,
+       decision_type TEXT NOT NULL,
+       question TEXT NOT NULL,
+       chosen_option TEXT NOT NULL,
+       alternatives_considered TEXT,  -- JSON array
+       context_snapshot TEXT NOT NULL,  -- JSON
+       created_at TEXT NOT NULL
    );
-   ```
+
2. **Implement Decision Recording** - Every choice during Strategize creates a Decision record @@ -9895,9 +13278,9 @@ No decision tracking exists. The specification's key innovation is recording eve - Track downstream dependencies 3. **Build Correction Mechanism** - ```bash - agents plan correct --mode=revert --guidance "" - ``` + 

+   agents plan correct <decision_id> --mode=revert --guidance "<new decision>"
+
- Mark decision as superseded - Recompute only affected subtree - Preserve unaffected work @@ -9912,13 +13295,13 @@ Current context is limited to a few hundred characters from a few files. Large c #### Implementation Steps 1. **Eager Indexing on Resource Add** - ```python - def on_resource_added(resource: Resource): - # Index immediately when resource added to project - index_text_content(resource) # Full-text search - generate_embeddings(resource) # Vector embeddings - build_knowledge_graph(resource) # RDF triples - ``` + 

+   def on_resource_added(resource: Resource):
+       # Index immediately when resource added to project
+       index_text_content(resource)      # Full-text search
+       generate_embeddings(resource)     # Vector embeddings
+       build_knowledge_graph(resource)   # RDF triples
+
2. **Three-Index Architecture** - **Text Index**: Tantivy/SQLite FTS for exact matches @@ -9940,27 +13323,27 @@ Actors exist but don't define behavior beyond model selection. The specification #### Implementation Steps 1. **Extend Actor Configuration** - ```yaml - actors: - my_strategist: - type: graph - config: - provider: anthropic - model: claude-3-opus - memory_policy: per_plan - context_view: architect # High-level view - skills: + 

+   actors:
+     my_strategist:
+       type: graph
+       config:
+         provider: anthropic
+         model: claude-3-opus
+         memory_policy: per_plan
+         context_view: architect # High-level view
+       skills:
          - local/file-ops             # provides read_file
          - local/code-intelligence    # provides search_code, analyze_dependencies
-       routes:
-         strategize:
-           entry_point: analyze
-           nodes:
-             - name: analyze
-               type: llm
-             - name: plan
-               type: llm
-   ```
+       routes:
+         strategize:
+           entry_point: analyze
+           nodes:
+             - name: analyze
+               type: llm
+             - name: plan
+               type: llm
+
2. **Implement Tool Access Policies** - Strategy actors: read-only tools @@ -9984,7 +13367,7 @@ Resources are currently defined inline within projects. The specification requir 1. **Resource Type Registry and CLI** - Implement 24 built-in resource types: 15 physical (`git-checkout`, `git`, `git-remote`, `git-branch`, `git-tag`, `git-commit`, `git-tree`, `git-tree-entry`, `git-stash`, `git-submodule`, `fs-mount`, `fs-directory`, `fs-file`, `fs-symlink`, `fs-hardlink`) and 9 virtual (`file`, `directory`, `symlink`, `commit`, `branch`, `tag`, `remote`, `submodule`, `tree`) - Implement resource type YAML parsing and validation for custom types - - Implement `agents resource type add [--upgrade]/remove/list/show` commands + - Implement `agents resource type add [--update]/remove/list/show` commands - Implement dynamic CLI subcommand registration (custom types create new `agents resource add` subcommands) 2. **Resource Registry and CLI** @@ -10028,13 +13411,13 @@ No tool or skill abstraction exists. The specification defines tools as independ 1. **Tool Registry and CLI** - Implement tool YAML parsing and validation (including `resources` section for resource slots) - - Implement `agents tool add [--upgrade]/remove/list/show` commands + - Implement `agents tool add [--update]/remove/list/show` commands - Implement Tool Registry persistence in database - Implement anonymous tool support (inline definitions without registration) 2. **Skill Registry and CLI** - Implement skill YAML parsing and validation - - Implement `agents skill add [--upgrade]/remove/list/show/tools` commands + - Implement `agents skill add [--update]/remove/list/show/tools` commands - Implement hierarchical skill composition (includes) with per-tool metadata overrides - Implement Skill Registry persistence in database - Implement named tool references (resolving from Tool Registry) and anonymous inline tools @@ -10048,33 +13431,33 @@ No tool or skill abstraction exists. The specification defines tools as independ - Inject bound resources into `ToolExecutionContext.resources` 4. **MCP Tool Adapter** - ```python - class MCPToolAdapter: - def wrap_mcp_tool(self, tool) -> Tool: - # Add sandbox interception - # Add change tracking - # Add capability metadata - # Add resource binding support - ``` + 

+   class MCPToolAdapter:
+       def wrap_mcp_tool(self, tool) -> Tool:
+           # Add sandbox interception
+           # Add change tracking
+           # Add capability metadata
+           # Add resource binding support
+
5. **Tool Capability Metadata** - ```python - class ToolCapability: - read_only: bool - write_scope: list[str] # References resource slot names - checkpointable: bool - idempotent: bool - side_effects: list[str] - ``` + 

+   class ToolCapability:
+       read_only: bool
+       write_scope: list[str]       # References resource slot names
+       checkpointable: bool
+       idempotent: bool
+       side_effects: list[str]
+
6. **External MCP Server Support** - ```yaml - # In tool or skill YAML configuration - mcp_servers: - - name: github - command: "npx @anthropic/mcp-github" - env: {GITHUB_TOKEN: "${GITHUB_TOKEN}"} - ``` + 

+   # In tool or skill YAML configuration
+   mcp_servers:
+     - name: github
+       command: "npx @anthropic/mcp-github"
+       env: {GITHUB_TOKEN: "${GITHUB_TOKEN}"}
+
7. **Agent Skills Adapter** - Implement SKILL.md frontmatter parsing for discovery @@ -10101,20 +13484,18 @@ Current validation is a stub. The specification requires multi-layer semantic va - Record validation in decision metadata 2. **Execution-Time Guards** - ```yaml - # Actor references a skill containing validation tools - skills: + 

+   # Actor references a skill containing validation tools
+   skills:
      - local/semantic-validators   # validate_api_compatibility,
-                                   # check_invariants, verify_test_coverage
-   ```
+                                   # check_invariants, verify_test_coverage
+
3. **Project-Specific Validation** - ```bash - agents project set-validation \ - --project my-api \ - --test-command "pytest" \ - --lint-command "ruff check ." - ``` + 

+   agents project validation add --description "Run tests" --required my-api "pytest"
+   agents project validation add --description "Lint check" --required my-api "ruff check ."
+
#### Estimated Effort: 2 weeks @@ -10126,12 +13507,12 @@ The reactive/LangGraph infrastructure exists but isn't connected to the main pla #### Implementation Steps 1. **Create Unified Plan Graph** - ```python - class PlanLifecycleGraph: - def strategize_subgraph(self) -> StateGraph - def execute_subgraph(self) -> StateGraph - def apply_subgraph(self) -> StateGraph - ``` + 

+   class PlanLifecycleGraph:
+       def strategize_subgraph(self) -> StateGraph
+       def execute_subgraph(self) -> StateGraph
+       def apply_subgraph(self) -> StateGraph
+
2. **Wire Phase Transitions** - `use` command triggers strategize graph @@ -10198,13 +13579,13 @@ This allows the system to remain functional during development while progressive When a strategy actor analyzes a codebase during the Strategize phase, it doesn't just make decisions in isolation. Each decision creates a comprehensive Decision record that includes: -```yaml -context_snapshot: - hot_context_hash: str # Cryptographic hash of the exact context - hot_context_ref: str # Pointer to the full stored snapshot - relevant_resources: list[ResourceRef] # Every file/symbol that influenced this decision - actor_state_ref: str # Complete LangGraph checkpoint -``` +

+context_snapshot:
+  hot_context_hash: str # Cryptographic hash of the exact context
+  hot_context_ref: str # Pointer to the full stored snapshot
+  relevant_resources: list[ResourceRef] # Every file/symbol that influenced this decision
+  actor_state_ref: str # Complete LangGraph checkpoint
+
This means when the system decides "refactor the authentication module to use async patterns," it permanently records: - Which files were examined to make that decision @@ -10237,25 +13618,25 @@ At each level, only the relevant context is loaded. The persistent decision grap **Concrete example of persistence in action**: -``` +

 Plan: Convert Firefox Renderer to Rust
-├── [invariant_enforced] "Maintain API compatibility with existing C++ callers"
-├── [invariant_enforced] "All converted modules must pass existing C++ test suites"
-├── [strategy_choice] Architecture approach: Start with leaf modules, work inward
+├── [invariant_enforced] "Maintain API compatibility with existing C++ callers"
+├── [invariant_enforced] "All converted modules must pass existing C++ test suites"
+├── [strategy_choice] Architecture approach: Start with leaf modules, work inward
 │   Context: Analyzed module dependency graph, 2,847 modules total
 │   Resources: module_graph.json, architecture_docs.md
 │   
-├── [subplan_parallel_spawn] Phase 1: Convert utility libraries (no external deps)
-│   └── [subplan_spawn] Convert string_utils module
+├── [subplan_parallel_spawn] Phase 1: Convert utility libraries (no external deps)
+│   └── [subplan_spawn] Convert string_utils module
 │       └── Plan: 01KH29R8WPKPBHRY7Q0NA9XW86
-│           ├── [prompt_definition] "Convert string_utils module to Rust"
-│           ├── [invariant_enforced] "Maintain API compatibility with existing C++ callers"
-│           ├── [implementation_choice] Use Rust's String type, not custom implementation
+│           ├── [prompt_definition] "Convert string_utils module to Rust"
+│           ├── [invariant_enforced] "Maintain API compatibility with existing C++ callers"
+│           ├── [implementation_choice] Use Rust's String type, not custom implementation
 │           │   Context: Analyzed 47 string_utils.cpp functions
 │           │   Resources: string_utils.cpp, string_utils.h, 12 dependent files
-│           │   Rationale: Rust's String provides same guarantees with better ergonomics
+│           │   Rationale: Rust's String provides same guarantees with better ergonomics
 │           └── ...
-```
+
Even months later, we can query: "Why did we use Rust's String type?" and get the exact context and reasoning, without reprocessing the entire codebase. @@ -10268,27 +13649,27 @@ Even months later, we can query: "Why did we use Rust's String type?" and get th During the Strategize phase, the strategy actor employs several mechanisms to compute precise dependency closures: 1. **Resource-aware analysis**: The actor uses specialized skills to trace dependencies: - ```python - # Pseudocode of what happens inside a strategy actor - def compute_closure_for_refactoring(target_module): + 

+   # Pseudocode of what happens inside a strategy actor
+   def compute_closure_for_refactoring(target_module):
        closure = ResourceClosure()
        
-       # Direct file dependencies
+       # Direct file dependencies
        closure.add_files(find_imports(target_module))
        closure.add_files(find_includes(target_module))
        
-       # Symbol dependencies
-       for symbol in extract_exported_symbols(target_module):
-           closure.add_files(find_symbol_usage(symbol, scope='project'))
+       # Symbol dependencies
+       for symbol in extract_exported_symbols(target_module):
+           closure.add_files(find_symbol_usage(symbol, scope='project'))
        
-       # Test dependencies
+       # Test dependencies
        closure.add_files(find_tests_for_module(target_module))
        
-       # Build system dependencies
+       # Build system dependencies
        closure.add_files(find_build_references(target_module))
        
-       return closure
-   ```
+       return closure
+
2. **Hierarchical scoping**: When spawning child plans (via `subplan_spawn` or `subplan_parallel_spawn`), each child plan receives: - An explicit `relevant_resources` list @@ -10297,26 +13678,26 @@ During the Strategize phase, the strategy actor employs several mechanisms to co - The parent plan's effective invariant view (already reconciled from action, project, and global scopes) 3. **Decision-based tracking**: Each `subplan_spawn` decision records the child plan it creates, and `subplan_parallel_spawn` decisions group parallel child plans: - ```yaml - # Individual child plan spawn - decision_type: subplan_spawn - chosen_option: "Refactor authentication module" - downstream_plan_ids: ["plan-auth-refactor-123"] - artifacts_produced: - - auth_module_files: ["auth.rs", "auth_test.rs", "auth_types.rs"] - - api_updates: ["api/v2/login.rs", "api/v2/logout.rs"] + 

+   # Individual child plan spawn
+   decision_type: subplan_spawn
+   chosen_option: "Refactor authentication module"
+   downstream_plan_ids: ["plan-auth-refactor-123"]
+   artifacts_produced: 
+     - auth_module_files: ["auth.rs", "auth_test.rs", "auth_types.rs"]
+     - api_updates: ["api/v2/login.rs", "api/v2/logout.rs"]
    
-   # Parallel group of child plans
-   decision_type: subplan_parallel_spawn
-   chosen_option: "Convert utility libraries in parallel"
-   # Contains subplan_spawn children, each with their own downstream_plan_ids
-   ```
+   # Parallel group of child plans
+   decision_type: subplan_parallel_spawn
+   chosen_option: "Convert utility libraries in parallel"
+   # Contains subplan_spawn children, each with their own downstream_plan_ids
+
**Concrete example - Converting a subsystem to Rust**: Let's trace how the system handles "Convert Firefox's Network Stack to Rust": -``` +

 STRATEGIZE PHASE:
 1. Analyze network stack structure
    - Identifies 847 C++ files in netwerk/ directory
@@ -10331,11 +13712,11 @@ STRATEGIZE PHASE:
    - Total closure: 25 files (not 847!)
    
 3. Generate execution blueprint with child plans:
-   - [subplan_parallel_spawn] DNS module conversions:
+   - [subplan_parallel_spawn] DNS module conversions:
      - convert-dns-types: Closure of 5 files (type definitions)
      - convert-dns-cache: Closure of 8 files (cache + tests)  
      - convert-dns-resolver: Closure of 12 files (resolver + integration)
-```
+
**Why this is tractable even for massive codebases**: @@ -10363,64 +13744,64 @@ The Firefox example would decompose into ~1,000 bounded child plans (grouped via 1. **Complete isolation during execution**: Each plan executes in its own sandbox, which means: - ``` + 

    Plan A (refactoring auth module):
    - Sandbox A1: Contains only auth/*.cpp, auth_tests/*.cpp
-   - Cannot see Plan B's intermediate states
-   - Cannot accidentally depend on Plan B's half-done work
+   - Cannot see Plan B's intermediate states
+   - Cannot accidentally depend on Plan B's half-done work
    
    Plan B (updating API endpoints):
    - Sandbox B1: Contains only api/*.cpp, api_tests/*.cpp  
    - Makes changes assuming current auth interface
-   - Protected from Plan A's intermediate refactoring
-   ```
+   - Protected from Plan A's intermediate refactoring
+
2. **Resource-specific sandbox strategies provide natural coordination**: - ```yaml + 

    Git repositories:
-     - Strategy: git worktrees
-     - Coordination: Git's three-way merge algorithm
+     - Strategy: git worktrees
+     - Coordination: Git's three-way merge algorithm
      - Conflict detection: Built into Git
-     - Rollback: git reset/checkout
+     - Rollback: git reset/checkout
    
-   Databases:
-     - Strategy: Transaction isolation  
-     - Coordination: MVCC (multi-version concurrency control)
+   Databases:
+     - Strategy: Transaction isolation  
+     - Coordination: MVCC (multi-version concurrency control)
      - Conflict detection: Serialization failures
-     - Rollback: Transaction abort
+     - Rollback: Transaction abort
    
    Cloud Infrastructure:
-     - Strategy: Terraform workspaces
-     - Coordination: State locking
+     - Strategy: Terraform workspaces
+     - Coordination: State locking
      - Conflict detection: Resource conflicts in plan
-     - Rollback: Previous state restoration
-   ```
+     - Rollback: Previous state restoration
+
3. **Hierarchical merge resolution**: When child plans complete, the parent plan performs intelligent merging: - ```python - def merge_subplan_results(subplan_results): - # Group by resource type + 

+   def merge_subplan_results(subplan_results):
+       # Group by resource type
        by_resource = group_by_resource_type(subplan_results)
        
-       # Apply resource-specific merge strategies
-        for resource_type, changes in by_resource:
-            if resource_type == 'git-checkout':
-                merge_git_changes(changes)  # Three-way merge
-            elif resource_type == 'fs-mount':
-                merge_fs_changes(changes)   # Copy-on-write reconciliation
-            elif resource_type.startswith('database'):
-                merge_db_changes(changes)   # Sequential application
+       # Apply resource-specific merge strategies
+        for resource_type, changes in by_resource:
+            if resource_type == 'git-checkout':
+                merge_git_changes(changes)  # Three-way merge
+            elif resource_type == 'fs-mount':
+                merge_fs_changes(changes)   # Copy-on-write reconciliation
+            elif resource_type.startswith('database'):
+                merge_db_changes(changes)   # Sequential application
        
-       # Validate merged state
+       # Validate merged state
        run_integration_tests()
-   ```
+
**Concrete example - Preventing cascading failures**: Consider refactoring a shared authentication library used by 15 services: -``` +

 PARALLEL EXECUTION WITHOUT COORDINATION (what we prevent):
 - Service A refactors to async auth → breaks Service B
 - Service B compensates with workaround → breaks Service C  
@@ -10429,29 +13810,29 @@ PARALLEL EXECUTION WITHOUT COORDINATION (what we prevent):
 
 CLEVERAGENTS COORDINATED EXECUTION:
 Parent Plan: Refactor auth library
-├── [invariant_enforced] "Auth library public API must remain backward compatible during transition"
-├── [subplan_spawn] Plan 1: Update auth library interface
+├── [invariant_enforced] "Auth library public API must remain backward compatible during transition"
+├── [subplan_spawn] Plan 1: Update auth library interface
 │   Sandbox: Only auth library files
 │   Output: New interface definition
 │   
 ├── Barrier: Wait for Plan 1 completion
 │   
-├── [subplan_parallel_spawn] Plans 2-16: Update each service (in parallel)
-│   Each sandbox: Only that service's files
+├── [subplan_parallel_spawn] Plans 2-16: Update each service (in parallel)
+│   Each sandbox: Only that service's files
 │   Each uses: New interface from Plan 1
 │   No inter-service dependencies during execution
 │   
 └── Merge Phase:
     - Collect all service updates
-    - Apply to main branch in order
+    - Apply to main branch in order
     - Run integration tests
     - If conflicts: Parent plan resolves using semantic understanding
-```
+
**Advanced coordination patterns**: 1. **Optimistic concurrency with semantic conflict resolution**: - ```yaml + 

    Two child plans both modify api/user.rs:
    - Plan A: Adds async fn get_user_profile()
    - Plan B: Adds fn validate_user_permissions()
@@ -10460,26 +13841,26 @@ Parent Plan: Refactor auth library
    - Git merge succeeds (different functions)
    - Semantic validation ensures both functions work together
    - Parent plan adds integration glue if needed
-   ```
+
2. **Checkpoint-based coordination**: - ``` + 

    Execution timeline:
    T1: Plan A creates checkpoint before major refactor
    T2: Plan B creates checkpoint before API changes
    T3: Plan A encounters error, rolls back to T1
    T4: Plan B completes successfully
-   T5: Plan A retries with knowledge of B's success
-   ```
+   T5: Plan A retries with knowledge of B's success
+
3. **Resource locking for critical sections**: - ```yaml + 

    When modifying shared schema files:
    - Acquire exclusive lock on schema resources
    - Make changes atomically
    - Release lock with new version
    - Other plans rebase on new schema
-   ```
+
### Q: How does the system proactively prevent semantic errors before they propagate? @@ -10488,34 +13869,34 @@ Parent Plan: Refactor auth library **Layer 1: Decision-time validation during Strategize**: Every decision includes semantic validation: -```yaml -Decision: Refactor payment module to async -alternatives_considered: - - "Convert to async/await patterns" (chosen) - - "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem) - - "Keep synchronous with timeout" (rejected: doesn't solve core latency issue) -confidence_score: 0.85 -validation_performed: +

+Decision: Refactor payment module to async
+alternatives_considered:
+  - "Convert to async/await patterns" (chosen)
+  - "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem)
+  - "Keep synchronous with timeout" (rejected: doesn't solve core latency issue)
+confidence_score: 0.85
+validation_performed:
   - Checked all payment API consumers can handle async
   - Verified database driver supports async operations
   - Confirmed no regulatory requirement for sync processing
-```
+
**Layer 2: Execution-time semantic guards**: The execution actor uses a tool node that references the independently registered `local/validate-api-compat` tool: -```yaml -actors: - code_executor: - type: graph - skills: +

+actors:
+  code_executor:
+    type: graph
+    skills:
       - local/semantic-validators    # Contains validation tools for LLM tool-calling
-    nodes:
-      - name: semantic_validator
-        type: tool
-        tool: local/validate-api-compat   # Named tool from Tool Registry
-```
+    nodes:
+      - name: semantic_validator
+        type: tool
+        tool: local/validate-api-compat # Named tool from Tool Registry
+
The `local/validate-api-compat` tool (independently registered via `agents tool add`) performs semantic validation — not just syntax checking. It extracts API signatures, finds breaking changes, checks affected consumers, and either auto-migrates or raises a `SemanticError` for manual review. @@ -10523,70 +13904,70 @@ The `local/validate-api-compat` tool (independently registered via `agents tool Invariants are attached at four scopes (global, project, action, plan) and managed via the unified `agents invariant` command or `--invariant` flags on creation commands. When a plan enters Strategize, the **Invariant Reconciliation Actor** (set via `--invariant-actor` on actions/plans/projects, or globally via `agents config set invariant-actor`) computes the effective invariant view by applying precedence rules (plan > project > global) to resolve conflicts. Each effective invariant is recorded as an `invariant_enforced` decision, making them visible, correctable, and auditable: -```python -# The system collects, reconciles, and enforces semantic invariants -class InvariantEnforcer: - def compute_effective_invariants(self, plan): - """Compute the effective invariant view using the Invariant Reconciliation Actor.""" +

+# The system collects, reconciles, and enforces semantic invariants
+class InvariantEnforcer:
+    def compute_effective_invariants(self, plan):
+        """Compute the effective invariant view using the Invariant Reconciliation Actor."""
         raw = self.collect_all_invariants(plan)
         reconciler = (
             self.get_plan_invariant_actor(plan)
-            or self.get_project_invariant_actor(plan)
-            or self.get_global_invariant_actor()
+            or self.get_project_invariant_actor(plan)
+            or self.get_global_invariant_actor()
         )
-        # Apply precedence: plan > project > global
-        return reconciler.reconcile(raw, precedence=['plan', 'project', 'global'])
+        # Apply precedence: plan > project > global
+        return reconciler.reconcile(raw, precedence=['plan', 'project', 'global'])
     
-    def collect_all_invariants(self, plan):
-        """Collect invariants from all scopes accessible to this plan."""
+    def collect_all_invariants(self, plan):
+        """Collect invariants from all scopes accessible to this plan."""
         invariants = []
         invariants.extend(self.get_global_invariants())
-        for project in plan.projects:
+        for project in plan.projects:
             invariants.extend(self.get_project_invariants(project))
         invariants.extend(self.get_action_invariants(plan.action))
         invariants.extend(self.get_plan_invariants(plan))
-        return invariants
+        return invariants
     
-    # Example invariants at different scopes:
-    # Global:  "Payment processing must be idempotent"
-    # Project: "Database transactions must complete within 5 seconds"
-    # Action:  "Test files must not import production secrets"
-    # Plan:    "All API calls over TCP must be mocked"
+    # Example invariants at different scopes:
+    # Global:  "Payment processing must be idempotent"
+    # Project: "Database transactions must complete within 5 seconds"
+    # Action:  "Test files must not import production secrets"
+    # Plan:    "All API calls over TCP must be mocked"
     
-    def check_invariant_preservation(self, changes, enforced_invariants):
-        for invariant in enforced_invariants:
-            if not self.verify_invariant(invariant, changes):
-                return InvariantViolation(invariant, changes)
-        return Success()
-```
+    def check_invariant_preservation(self, changes, enforced_invariants):
+        for invariant in enforced_invariants:
+            if not self.verify_invariant(invariant, changes):
+                return InvariantViolation(invariant, changes)
+        return Success()
+
**Layer 4: Predictive error prevention through pattern matching**: The system learns from past failures: -```yaml +

 Error Pattern Database:
-  - pattern: "Async conversion in payment module"
-    historical_failures:
-      - "Race condition in payment confirmation"
-      - "Timeout handling breaks idempotency"
-    preventive_checks:
-      - "Add explicit transaction boundaries"
-      - "Verify idempotency keys are preserved"
-      - "Check distributed lock acquisition"
-```
+  - pattern: "Async conversion in payment module"
+    historical_failures:
+      - "Race condition in payment confirmation"
+      - "Timeout handling breaks idempotency"
+    preventive_checks:
+      - "Add explicit transaction boundaries"
+      - "Verify idempotency keys are preserved"
+      - "Check distributed lock acquisition"
+
**Concrete example - Preventing a subtle distributed systems bug**: Scenario: Refactoring a service to use event sourcing: -``` +

 PROACTIVE CONTAINMENT IN ACTION:
 
 1. Strategy Phase Semantic Analysis:
-   - Decision: "Convert order service to event sourcing"
-   - Semantic check: "Event sourcing requires eventual consistency"
+   - Decision: "Convert order service to event sourcing"
+   - Semantic check: "Event sourcing requires eventual consistency"
    - Identifies: 3 services assume immediate consistency
-   - Adds decision: "Update dependent services for eventual consistency"
+   - Adds decision: "Update dependent services for eventual consistency"
 
 2. Execution Phase Invariant Checking:
    - Detects: PaymentService.chargeCard() called after OrderCreated event
@@ -10598,11 +13979,11 @@ PROACTIVE CONTAINMENT IN ACTION:
    - Impact: Async events break compliance reporting
    - Resolution: Add audit event buffer with guaranteed ordering
    
-4. Pre-Apply Semantic Verification:
+4. Pre-Apply Semantic Verification:
    - Simulates production event flow
    - Detects: Under high load, events can arrive out of order
    - Adds: Event ordering guarantees via vector clocks
-```
+
**Why this prevents issues that traditional testing misses**: @@ -10615,107 +13996,120 @@ Traditional tests check "does the code work?" Our semantic containment asks: **Integration with Definition of Done (DoD)**: Each plan's DoD includes semantic requirements: -```yaml -definition_of_done: - must: - - "All API changes maintain backward compatibility" - - "No increase in p99 latency" - - "Audit trail remains complete" - should: - - "Improve code coverage by 10%" - - "Reduce cyclomatic complexity" - may: - - "Optimize for memory usage" -``` +

+definition_of_done:
+  must:
+    - "All API changes maintain backward compatibility"
+    - "No increase in p99 latency"
+    - "Audit trail remains complete"
+  should:
+    - "Improve code coverage by 10%"
+    - "Reduce cyclomatic complexity"
+  may:
+    - "Optimize for memory usage"
+
The validation nodes enforce these semantics, not just test passage. ### Q: How does the system balance human supervision with autonomous operation? -**What exists today architecturally**: The specification defines a sophisticated gradation of automation levels that precisely controls when human intervention is needed. This isn't a binary human/AI split - it's a spectrum that can be adjusted per task, per project, or per organization. +**What exists today architecturally**: The specification defines a comprehensive automation profile system with 13 individual boolean flags controlling every aspect of human-vs-automated operation. This isn't a binary human/AI split — it's a fine-grained matrix that can be adjusted per task, per project, or per organization. -**How the automation levels work in practice**: +**How the automation profiles work in practice**: -```yaml -Manual Mode: +

+locked-down Profile:
+  - Every phase transition pauses for human action
   - Every decision point pauses for human input
   - User sees: Context, alternatives, recommendation
   - User provides: Explicit choice or custom guidance
-  - Use case: Critical production changes, learning new codebases
+  - Use case: Critical production changes, first-time codebase exploration
 
-Review-before-apply Mode:
-  - AI makes all decisions autonomously
-  - Execution completes in sandbox
-  - Human reviews complete diff before apply
-  - User can: Approve, reject, or correct specific decisions
+supervised Profile:
+  - Strategize runs automatically with autonomous decisions
+  - System pauses before Execute for human review of strategy
+  - Transient failures retried automatically
+  - Use case: Projects where you trust planning but want to review before execution
+
+trusted Profile:
+  - Strategize and Execute run automatically with autonomous decisions
+  - Validation failures self-fixed within strategy bounds
+  - Child plans spawned automatically
+  - System pauses before Apply for human diff review
   - Use case: Normal feature development, refactoring
 
-Full Automation Mode:
-  - AI makes all decisions
-  - Execution proceeds through apply
-  - Human notified of completion
-  - Rollback available if issues detected
-  - Use case: Routine updates, test generation, documentation
-```
+autonomous Profile:
+  - Everything automatic except Apply
+  - Can revise its own strategy if execution hits a wall
+  - Restores from checkpoints on failure
+  - Use case: Well-understood projects, batch operations
+
+full-auto Profile:
+  - Complete end-to-end automation including Apply
+  - No sandbox or checkpoint requirements
+  - Unsafe tools allowed
+  - Use case: Routine updates, CI/CD integration
+
**The decision correction mechanism enables progressive automation**: The `agents plan correct` command is crucial for building trust: -```bash -# User observes AI made suboptimal choice -agents plan tree -# Sees: [Decision] "Use REST API for service communication" +

+# User observes AI made suboptimal choice
+agents plan tree <plan_id>
+# Sees: [Decision] "Use REST API for service communication"
 
-# User knows gRPC would be better for this use case
-agents plan correct  --mode=revert \
-  --guidance "Use gRPC instead of REST. This service requires streaming 
+# User knows gRPC would be better for this use case
+agents plan correct <decision_id> --mode=revert \
+  --guidance "Use gRPC instead of REST. This service requires streaming 
              updates and binary protocol efficiency. Set up protocol 
-             buffer definitions and generate client/server stubs."
+             buffer definitions and generate client/server stubs."
 
-# System:
-# 1. Marks original decision as superseded
-# 2. Creates new decision with user guidance
-# 3. Recomputes ONLY affected downstream decisions
-# 4. Preserves all unrelated work
-```
+# System:
+# 1. Marks original decision as superseded
+# 2. Creates new decision with user guidance
+# 3. Recomputes ONLY affected downstream decisions
+# 4. Preserves all unrelated work
+
-**Progressive trust building through automation levels**: +**Progressive trust building through automation profiles**: New users typically follow this progression: -1. Start with manual mode to understand system behavior -2. Move to review-before-apply as confidence builds -3. Enable full automation for specific task types -4. Gradually expand full automation scope +1. Start with `manual` to understand system behavior +2. Move to `supervised` as confidence in planning builds +3. Adopt `trusted` for routine development tasks +4. Enable `autonomous` for well-understood projects +5. Use `full-auto` for low-risk batch operations **Real autonomy through semantic understanding**: True autonomy isn't about removing humans - it's about the system understanding when it needs help: -```python -class AutonomyController: - def assess_decision_confidence(self, decision, context): +

+class AutonomyController:
+    def assess_decision_confidence(self, decision, context):
         factors = {
-            'past_success_rate': self.get_historical_success(decision.type),
-            'codebase_familiarity': self.get_familiarity_score(context.project),
-            'risk_assessment': self.evaluate_risk(decision),
-            'invariant_complexity': self.analyze_invariants(decision)
+            'past_success_rate': self.get_historical_success(decision.type),
+            'codebase_familiarity': self.get_familiarity_score(context.project),
+            'risk_assessment': self.evaluate_risk(decision),
+            'invariant_complexity': self.analyze_invariants(decision)
         }
         
         confidence = self.compute_confidence(factors)
         
-        if confidence < self.threshold:
-            if self.automation_level == 'full':
-                # Even in full automation, critical decisions escalate
-                return RequestHumanGuidance(decision, factors)
+        if confidence < self.threshold:
+             if self.profile.auto_decisions_strategize:
+                # Even in full automation, critical decisions escalate
+                return RequestHumanGuidance(decision, factors)
         
-        return ProceedAutonomously(decision)
-```
+        return ProceedAutonomously(decision)
+
**Concrete example - Autonomous handling of a complex refactoring**: -``` -Scenario: "Modernize legacy e-commerce system" +

+Scenario: "Modernize legacy e-commerce system"
 
 INITIAL PLAN (Full Automation Mode):
 1. System analyzes 50,000 line codebase
@@ -10724,29 +14118,29 @@ INITIAL PLAN (Full Automation Mode):
 
 AUTONOMOUS EXECUTION WITH SMART ESCALATION:
 
-[subplan_parallel_spawn] Plans 1-15: Update utility functions (executes autonomously)
+[subplan_parallel_spawn] Plans 1-15: Update utility functions (executes autonomously)
 - Confidence: 0.95 (straightforward transformations)
 - Result: Success
 
-[subplan_spawn] Plan 16: Refactor payment processing
+[subplan_spawn] Plan 16: Refactor payment processing
 - Confidence: 0.4 (critical business logic)
-- [invariant_enforced] "Preserve exact penny rounding behavior"
-- Action: ESCALATES to human
-- Human provides: "Preserve exact penny rounding behavior"
+- [invariant_enforced] "Preserve exact penny rounding behavior"
+- Action: ESCALATES to human
+- Human provides: "Preserve exact penny rounding behavior"
 - Continues autonomously with constraint
 
-[subplan_parallel_spawn] Plans 17-30: UI component updates (executes autonomously)
+[subplan_parallel_spawn] Plans 17-30: UI component updates (executes autonomously)
 - Confidence: 0.9 (isolated changes)
 - Result: Success
 
-[subplan_spawn] Plan 31: Database schema migration
+[subplan_spawn] Plan 31: Database schema migration
 - Detects: Would require 6-hour downtime
-- Action: ESCALATES to human
-- Human provides: "Use online migration with feature flags"
+- Action: ESCALATES to human
+- Human provides: "Use online migration with feature flags"
 - Re-plans with zero-downtime approach
 
-[subplan_parallel_spawn] Plans 32-47: Complete autonomously
-```
+[subplan_parallel_spawn] Plans 32-47: Complete autonomously
+
**The path to greater autonomy**: @@ -10858,7 +14252,7 @@ The architecture doesn't require magical AI breakthroughs. It requires: - **Bounded context operations**: ✓ Dependency closure computation defined - **Parallel execution with isolation**: ✓ Sandbox model complete - **Semantic validation**: ✓ Multi-layer approach specified -- **Progressive automation**: ✓ Automation levels and correction defined +- **Progressive automation**: ✓ Automation profiles and correction defined The difference between handling a 1,000 file project and a 100,000 file project is: - More child plans (hierarchical decomposition handles this)