diff --git a/docs/adr/ADR-026-agent-client-protocol.md b/docs/adr/ADR-026-agent-client-protocol.md index b5cbf8524..e63ac8808 100644 --- a/docs/adr/ADR-026-agent-client-protocol.md +++ b/docs/adr/ADR-026-agent-client-protocol.md @@ -1,10 +1,10 @@ # ADR-026: Agent Client Protocol (ACP) -**Status:** Proposed +**Status:** Accepted **Date:** 2026-02-17 **Supersedes:** None -**Author(s):** CleverAgents Team -**Approver(s):** +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -128,8 +128,9 @@ Each ACP operation group maps to an Application-layer service: | Voter | Comment | |-------|---------| +| Jeffrey Phillips Freeman | ACP provides the standardized agent-to-agent communication layer needed for multi-actor orchestration | -**Total: 0** +**Total: 1** ### Votes Against diff --git a/docs/adr/ADR-027-language-server-protocol.md b/docs/adr/ADR-027-language-server-protocol.md index d5eefac36..353cb2d4a 100644 --- a/docs/adr/ADR-027-language-server-protocol.md +++ b/docs/adr/ADR-027-language-server-protocol.md @@ -1,10 +1,10 @@ # ADR-027: Language Server Protocol (LSP) Integration -**Status:** Proposed +**Status:** Accepted **Date:** 2026-02-17 **Supersedes:** None -**Author(s):** CleverAgents Team -**Approver(s):** +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -107,8 +107,9 @@ The LSP server is a long-lived process launched by the editor. It: | Voter | Comment | |-------|---------| +| Jeffrey Phillips Freeman | LSP integration gives IDE users real-time access to CleverAgents without leaving their editor | -**Total: 0** +**Total: 1** ### Votes Against diff --git a/docs/adr/ADR-028-agent-skills-standard.md b/docs/adr/ADR-028-agent-skills-standard.md index a721a8282..ac55ac416 100644 --- a/docs/adr/ADR-028-agent-skills-standard.md +++ b/docs/adr/ADR-028-agent-skills-standard.md @@ -1,10 +1,10 @@ # ADR-028: Agent Skills Standard (AgentSkills.io) -**Status:** Proposed +**Status:** Accepted **Date:** 2026-02-17 **Supersedes:** None -**Author(s):** CleverAgents Team -**Approver(s):** +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -121,8 +121,9 @@ This composition is a key design principle: Agent Skills extend the agent's *kno | Voter | Comment | |-------|---------| +| Jeffrey Phillips Freeman | AgentSkills.io adoption enables a portable skill ecosystem that works across agent frameworks | -**Total: 0** +**Total: 1** ### Votes Against diff --git a/docs/adr/ADR-029-model-context-protocol.md b/docs/adr/ADR-029-model-context-protocol.md index 6ddac2e2d..ce4ffcb84 100644 --- a/docs/adr/ADR-029-model-context-protocol.md +++ b/docs/adr/ADR-029-model-context-protocol.md @@ -1,10 +1,10 @@ # ADR-029: Model Context Protocol (MCP) Adoption -**Status:** Proposed +**Status:** Accepted **Date:** 2026-02-17 **Supersedes:** None -**Author(s):** CleverAgents Team -**Approver(s):** +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -141,8 +141,9 @@ Phase 4 — Deactivation: | Voter | Comment | |-------|---------| +| Jeffrey Phillips Freeman | MCP provides a proven standard for tool integration that aligns with the broader AI tooling ecosystem | -**Total: 0** +**Total: 1** ### Votes Against diff --git a/docs/adr/ADR-030-skill-abstraction-definition.md b/docs/adr/ADR-030-skill-abstraction-definition.md index 504dde008..d8fb65920 100644 --- a/docs/adr/ADR-030-skill-abstraction-definition.md +++ b/docs/adr/ADR-030-skill-abstraction-definition.md @@ -1,10 +1,10 @@ # ADR-030: Skill Abstraction Definition -**Status:** Proposed +**Status:** Accepted **Date:** 2026-02-17 **Supersedes:** None -**Author(s):** CleverAgents Team -**Approver(s):** +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -155,8 +155,9 @@ This binding is the only path through which actors acquire tool capabilities. Th | Voter | Comment | |-------|---------| +| Jeffrey Phillips Freeman | Formalizing skills as YAML-configured tool bundles with context injection gives actors composable capabilities | -**Total: 0** +**Total: 1** ### Votes Against diff --git a/docs/adr/ADR-031-actor-abstraction-definition.md b/docs/adr/ADR-031-actor-abstraction-definition.md index d2be47d07..664ee51b0 100644 --- a/docs/adr/ADR-031-actor-abstraction-definition.md +++ b/docs/adr/ADR-031-actor-abstraction-definition.md @@ -1,10 +1,10 @@ # ADR-031: Actor Abstraction Definition -**Status:** Proposed +**Status:** Accepted **Date:** 2026-02-17 **Supersedes:** None -**Author(s):** CleverAgents Team -**Approver(s):** +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -186,8 +186,9 @@ There is no mechanism for an actor to gain tool capabilities outside the skill s | Voter | Comment | |-------|---------| +| Jeffrey Phillips Freeman | Unifying agents, workflows, and pipelines under the actor-as-graph abstraction eliminates conceptual fragmentation | -**Total: 0** +**Total: 1** ### Votes Against diff --git a/docs/specification.md b/docs/specification.md index fb35f0fca..b6838ef93 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -2,77 +2,187 @@ ## Overview -CleverAgents is your **command center for AI agents**—a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow. The core value proposition is enabling **long-running, complex, large-scale tasks to execute autonomously with minimal human intervention**, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off. +CleverAgents is your **command center for AI agents** — a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow. -In **server mode**, CleverAgents becomes a collaborative hub where teams can share resources—prompts, actors, actions, and projects—while executing plans in the cloud. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine. +The core value proposition is enabling long-running, complex, large-scale tasks to execute autonomously with minimal human intervention, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off. -While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top: +!!! info "Server Mode" + + In **server mode**, CleverAgents becomes a collaborative hub where teams can share resources — prompts, actors, actions, and projects — while executing plans in the cloud. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine. + +!!! note "Runtime Foundation" + + While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top of these foundations. + +!!! success "Core Capabilities" + + - [x] A **first-class plan lifecycle** (Action templates driving Strategize / Execute / Apply phases) for breaking down and tracking complex work + - [x] A **project + resource model** for grounding tasks in real codebases, databases, documents, and infrastructure + - [x] A consistent **actor abstraction** for defining and composing intelligent agents + - [x] An independently registered **resource abstraction** for representing anything that can be read, written, or queried + - [x] An independently registered **tool abstraction** for reusable, callable operations with resource bindings + - [x] A **validation abstraction** that extends the tool concept with pass/fail semantics and resource-centric attachment with optional project/plan scoping + - [x] A consistent **skill abstraction** for organizing tools into composable capability collections + - [x] A **sandbox + checkpoint** safety model for safe, reversible execution + - [x] A **CLI/TUI/Web UX** for controlling and monitoring large multi-step autonomous work + +!!! example "Advanced Subsystems" + + - A scalable **Advanced Context Management System (ACMS)** with a Universal Knowledge Ontology (UKO), a demand-driven Context Request Protocol (CRP), pluggable context strategies, a fusion coordinator, and hot/warm/cold tiers with per-actor views. + - **Invariants** as first-class constraints (global, project, action, and plan scoped) that flow into the decision tree, with precedence-based conflict resolution via the Invariant Reconciliation Actor. + - A future-facing ==correction model== where the user can "edit the decision tree" and only recompute affected subtrees. ### Standards Alignment -CleverAgents deliberately adopts open, versioned protocols wherever possible so that clients, tools, and skills can interoperate without bespoke integrations. Two guiding principles govern protocol adoption: +CleverAgents deliberately adopts open, versioned protocols wherever possible so that clients, tools, and skills can interoperate without bespoke integrations. -* **Prefer open protocols** — align with community standards to keep integrations portable and reduce vendor lock-in. -* **Keep adapters at the edge** — standards map into stable internal domain models so core logic remains protocol-agnostic. +!!! tip "Guiding Principles" + + 1. **Prefer open protocols** — align with community standards to keep integrations portable and reduce vendor lock-in. + 2. **Keep adapters at the edge** — standards map into stable internal domain models so core logic remains protocol-agnostic. The following standards are integrated into the architecture: -* **Agent Client Protocol (ACP)** — defines the versioned client-server contract for sessions, plan lifecycle, registry access, and event streaming across all Presentation-layer clients (CLI, TUI, Web, IDE). This makes clients interchangeable and enables reliable remote execution in server mode. -* **Model Context Protocol (MCP)** — the standard for discovering and invoking external tools over a server boundary. MCP servers are bridged into the Tool Registry via adapters, giving CleverAgents plug-and-play access to a growing ecosystem of tool providers. -* **Language Server Protocol (LSP)** — the standard for IDE integration. The CleverAgents IDE plugin is an LSP server that surfaces plan-aware code actions, diagnostics, and context lookups, communicating with the backend exclusively through ACP. This provides editor-agnostic IDE support without bespoke plugins. -* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))** — the standard for packaging instruction-driven, multi-step workflows as `SKILL.md` with progressive disclosure. Agent Skills complement MCP tools by teaching agents *how* to accomplish complex tasks rather than simply exposing callable functions. +| Standard | Role | Key Benefit | +| :------- | :--- | :---------- | +| **ACP** (Agent Client Protocol) | Versioned client-server contract for sessions, plan lifecycle, registry access, and event streaming | Clients are interchangeable; enables reliable remote execution in server mode | +| **MCP** (Model Context Protocol) | Discovering and invoking external tools over a server boundary | Plug-and-play access to a growing ecosystem of tool providers | +| **LSP** (Language Server Protocol) | IDE integration via an LSP server surfacing plan-aware code actions and diagnostics | Editor-agnostic IDE support without bespoke plugins | +| **Agent Skills** ([AgentSkills.io](https://AgentSkills.io)) | Packaging instruction-driven, multi-step workflows as `SKILL.md` with progressive disclosure | Teaches agents *how* to accomplish complex tasks, complementing MCP tools | -**CleverAgents** provides: +??? info "Agent Client Protocol (ACP) -- Details" - * A **first-class plan lifecycle** (Action templates driving Strategize/Execute/Apply phases) for breaking down and tracking complex work, - * A **project + resource model** for grounding tasks in real codebases, databases, documents, and infrastructure, - * A consistent **actor abstraction** for defining and composing intelligent agents, - * An independently registered **resource abstraction** for representing anything that can be read, written, or queried, - * An independently registered **tool abstraction** for reusable, callable operations with resource bindings, - * A **validation abstraction** that extends the tool concept with pass/fail semantics and resource-centric attachment with optional project/plan scoping, - * A consistent **skill abstraction** for organizing tools into composable capability collections, - * A **sandbox + checkpoint** safety model for safe, reversible execution, - * A **CLI/TUI/Web UX** for controlling and monitoring large multi-step autonomous work. - * A scalable **Advanced Context Management System (ACMS)** with a Universal Knowledge Ontology (UKO), a demand-driven Context Request Protocol (CRP), pluggable context strategies, a fusion coordinator, and hot/warm/cold tiers with per-actor views. - * **Invariants** as first-class constraints (global, project, action, and plan scoped) that flow into the decision tree, with precedence-based conflict resolution via the Invariant Reconciliation Actor. - * A future-facing correction model where the user can "edit the decision tree" and only recompute affected subtrees. + Defines the versioned client-server contract for sessions, plan lifecycle, registry access, and event streaming across all Presentation-layer clients (CLI, TUI, Web, IDE). This makes clients interchangeable and enables reliable remote execution in server mode. + +??? info "Model Context Protocol (MCP) -- Details" + + The standard for discovering and invoking external tools over a server boundary. MCP servers are bridged into the Tool Registry via adapters, giving CleverAgents plug-and-play access to a growing ecosystem of tool providers. + +??? info "Language Server Protocol (LSP) -- Details" + + The standard for IDE integration. The CleverAgents IDE plugin is an LSP server that surfaces plan-aware code actions, diagnostics, and context lookups, communicating with the backend exclusively through ACP. This provides editor-agnostic IDE support without bespoke plugins. + +??? info "Agent Skills (AgentSkills.io) -- Details" + + The standard for packaging instruction-driven, multi-step workflows as `SKILL.md` with progressive disclosure. Agent Skills complement MCP tools by teaching agents *how* to accomplish complex tasks rather than simply exposing callable functions. ## Glossary -* **Plan**: A ULID-identified, hierarchical unit of work instantiated from an Action template. Progresses through four phases — Action, Strategize, Execute, Apply — persisting a decision tree at each step. May spawn child plans. Scoped to one or more projects. Top-level plans (explicitly created by users) carry a namespaced name (`[[server:]namespace/]name`); child plans (subplans spawned by a parent plan) are identified solely by their plan ID (ULID) and do not have a name. All plans are referenced by plan ID when precision is needed, especially in hierarchies containing subplans. -* **Action**: A YAML-defined, reusable plan template specifying a description, definition of done, strategy/execution actors, typed arguments, and optional invariants. Project-agnostic until bound to one or more projects via `agents plan use`, which instantiates a Plan. Namespaced as `[[server:]namespace/]name`. -* **Strategize**: Second phase of the plan lifecycle (following the Action phase). The first phase where active processing occurs. Read-only: the strategy actor produces the initial decision tree — strategy choices, invariant enforcement records, resource selections, child plan blueprints — without modifying any resources. -* **Execute**: Third phase of the plan lifecycle. The execution actor carries out decisions from Strategize — invoking tools, spawning child plans, producing artifacts, creating checkpoints — with all mutations confined to a sandbox. May also create additional decisions constrained by Strategize-phase decisions, based on runtime discoveries. If Strategize constraints prove too restrictive, Execute reverts to Strategize for adjustment. -* **Apply**: Fourth and final phase of the plan lifecycle. Merges the sandbox changeset into real project resources. Terminal states within Apply: `applied` (success — changes committed), `constrained` (cannot complete within current strategy constraints — may revert to Strategize), `errored` (failed), `cancelled` (user/system cancelled). If the plan enters the `constrained` state, it may automatically or manually revert to Strategize for strategy adjustment. -* **Project**: A named scope linking resources (from the Resource Registry), context policies, invariants, and validation attachments. Does not own resources; a single resource may be linked to multiple projects. Identified solely by its namespaced name (`[[server:]namespace/]name`) — no ULID is generated. May be local or remote. -* **Resource**: A ULID-identified entity registered in the Resource Registry representing anything readable, writable, or queryable (git repos, filesystems, databases, etc.). Classified as physical or virtual, typed by a Resource Type, and organized in a DAG via parent/child links. User-added resources also carry a namespaced name (`[[server:]namespace/]name`); auto-discovered children have ULID only. -* **Resource Type**: A schema-level definition constraining a category of resources. Specifies accepted CLI arguments, physical/virtual classification, permitted parent/child type relationships, auto-discovery rules, sandbox strategy, and handler implementation. Built-in types (e.g., `git-checkout`, `fs-mount`) are unnamespaced; custom types are YAML-defined and namespaced as `[[server:]namespace/]name`. -* **Physical Resource**: A resource bound to a concrete, located artifact — a specific file at a specific path, a specific repo at a specific URL. Directly readable and writable by tools. Two physical resources with identical content remain distinct instances. -* **Virtual Resource**: A resource representing an abstract equivalence identity that links physical resources sharing the same content, hash, or name. Has no location; cannot be directly read or written. Equivalence relationships update when underlying physical resources diverge. -* **Resource Binding**: The association between a tool and the resources it operates on, declared via typed resource slots. Slots resolve through contextual binding (from the plan's project), static binding (hardcoded at registration), or parameter binding (passed at invocation). -* **Resource Registry**: The persistent catalog of all registered resources and their DAG relationships (parent/child links). One of the core registries, alongside the Tool Registry, Skill Registry, Actor Registry, and Provider Registry. -* **Skill**: A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing Model Context Protocol (MCP) server tools and Agent Skills ([https://AgentSkills.io](https://AgentSkills.io)) tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`. -* **MCP (Model Context Protocol)**: A standard for exposing tools and resources over a server boundary via JSON-RPC. CleverAgents discovers MCP tools through the MCPToolAdapter and registers them in the Tool Registry with extended capability metadata. MCP tools can be composed into skills and used as tool nodes in actor graphs. -* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))**: A standard for packaging instruction-driven, multi-step workflows as `SKILL.md` files with optional `scripts/`, `references/`, and `assets/` directories, using progressive disclosure. In CleverAgents, Agent Skills are surfaced as tools inside skills and loaded on demand by the actor runtime. Within actor graphs they appear as tool nodes and may orchestrate multiple MCP tools during execution. -* **Tool**: The atomic unit of execution: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover`/`activate`/`execute`/`deactivate`). Sources: Model Context Protocol (MCP) servers, Agent Skills ([https://AgentSkills.io](https://AgentSkills.io)) folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`. -* **Validation**: A Tool subtype adding: a `mode` (`required` | `informational`) controlling whether failure blocks execution; a structured JSON return with mandatory `passed` boolean, optional `data`, and optional `message`. Always read-only (`writes = false`, `checkpointable = false`). May wrap an existing Tool via `wraps` + `transform` to reuse its implementation. Shares the Tool naming namespace — no name collisions allowed. Usable anywhere a Tool is expected, but not vice versa. Managed via `agents validation add/attach/detach`; listed, inspected, and removed through standard `agents tool` commands. Always attached to a resource, optionally scoped to a project or plan. -* **Anonymous Tool**: An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context. -* **Actor**: A YAML-configured conversational unit — either a single LLM/agent or a composed LangGraph of actors and tool nodes. Specialized roles: strategy actor, execution actor, estimation actor, invariant reconciliation actor. Namespaced as `[[server:]namespace/]name`. -* **Session**: A persistent conversation thread tied to an orchestrator actor. Maintains message history across plans and serves as the user's natural-language interface. -* **Server**: An optional shared backend providing multi-user storage, namespace resolution, and remote plan execution. -* **ACP (Agent Client Protocol)**: A versioned client-server protocol that defines authentication, session lifecycle, plan operations, registry access, and event streaming for all Presentation-layer clients (CLI, TUI, Web, IDE plugin). In local mode ACP maps to in-process service facade calls; in server mode it is implemented by the REST API over HTTPS. Ensures clients are interchangeable and supports third-party clients. -* **LSP (Language Server Protocol)**: A standard for IDE integration. The CleverAgents IDE plugin runs as an LSP server that translates code actions and diagnostics into plan operations and validation results, communicating with the backend through ACP. This enables editor-agnostic IDE support without bespoke plugins per editor. -* **Namespace**: The scoping segment in the name format `[[server:]namespace/]name`. Defaults to `local/` when omitted. `local/` is reserved for local-only items (no server applies). Non-`local/` namespaces with server omitted assume the default configured server. `/` and `/` are server-stored. Built-in LLM actors use provider prefixes (e.g., `openai/`, `anthropic/`). Built-in resource types are unnamespaced. -* **Decision**: A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, `subplan_parallel_spawn`, among others. Execute-phase decisions are constrained by Strategize-phase decisions and arise from runtime discoveries. Supports targeted correction with selective subtree recomputation. -* **Invariant**: A natural-language constraint on plan execution scoped to global, project, action, or plan level. Precedence: plan > action > project > global. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans. -* **Automation Profile**: A named set of confidence thresholds (each 0.0–1.0) gating which plan operations proceed automatically versus requiring human approval. Covers phase transitions, decision autonomy, self-repair, child plan spawning, and safety requirements. 0.0 = always automatic; 1.0 = always manual. Eight built-in profiles (`manual` through `full-auto`). Custom profiles namespaced as `[[server:]namespace/]name`. -* **ULID**: Universally Unique Lexicographically Sortable Identifier. Assigned to plans, decisions, resources, correction attempts, and validation attachments. Projects, actions, skills, and tools use their namespaced name as sole identifier instead. -* **ACMS (Advanced Context Management System)**: The pluggable, strategy-driven framework for assembling actor context. Comprises the UKO, CRP, pluggable context strategies, the Context Assembly Pipeline, and hot/warm/cold tiered storage with per-actor scoped views. -* **UKO (Universal Knowledge Ontology)**: An RDF-based, inheritance-driven ontology representing resources at multiple abstraction levels with provenance and temporal versioning. Four layers: universal foundation, domain specializations (software, documents, data schemas, infrastructure), paradigm/format specializations (procedural programming, markdown), and technology-specific (Python, PostgreSQL). Semantically aware — implicit relationships are inferred from content analysis. -* **CRP (Context Request Protocol)**: A structured vocabulary through which actors declare needed information, desired detail depth, and scope. -* **Context Strategy**: A pluggable retrieval component that searches for and assembles ContextFragments using a specific approach (keyword search, semantic embedding, graph navigation, temporal archaeology, etc.). Registered with the Context Assembly Pipeline; executed in parallel by the StrategyExecutor. -* **Context Assembly Pipeline**: The central ACMS orchestrator. Ten pluggable Protocol-defined components in three phases: Strategy Orchestration, Fragment Fusion, and Context Finalization. Each component ships with a default implementation and is overridable at global, project, or plan scope. -* **Skeleton (context)**: A compressed representation of a plan's accumulated context produced by the SkeletonCompressor. Propagated from parent plans to child plans as inherited context. Size governed by the `skeleton_ratio` budget parameter. +???+ abstract "Plan Lifecycle" + + Plan + : A ==ULID-identified==, hierarchical unit of work instantiated from an Action template. Progresses through four phases — **Action**, **Strategize**, **Execute**, **Apply** — persisting a decision tree at each step. May spawn child plans. Scoped to one or more projects. Top-level plans carry a namespaced name (`[[server:]namespace/]name`); child plans are identified solely by their plan ID (ULID). All plans are referenced by plan ID when precision is needed, especially in hierarchies containing subplans. + + Action + : A YAML-defined, reusable plan template specifying a description, definition of done, strategy/execution actors, typed arguments, and optional invariants. Project-agnostic until bound to one or more projects via `agents plan use`, which instantiates a Plan. Namespaced as `[[server:]namespace/]name`. + + Strategize + : Second phase of the plan lifecycle (following the Action phase). The first phase where active processing occurs. ==Read-only==: the strategy actor produces the initial decision tree — strategy choices, invariant enforcement records, resource selections, child plan blueprints — without modifying any resources. + + Execute + : Third phase of the plan lifecycle. The execution actor carries out decisions from Strategize — invoking tools, spawning child plans, producing artifacts, creating checkpoints — with all mutations confined to a sandbox. May also create additional decisions constrained by Strategize-phase decisions, based on runtime discoveries. + + Apply + : Fourth and final phase of the plan lifecycle. Merges the sandbox changeset into real project resources. Terminal states: `applied` (success), `constrained` (cannot complete — may revert to Strategize), `errored` (failed), `cancelled` (user/system cancelled). + + Decision + : A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, `subplan_parallel_spawn`, among others. Supports targeted correction with selective subtree recomputation. + + Invariant + : A natural-language constraint on plan execution scoped to global, project, action, or plan level. Precedence: ==plan > action > project > global==. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans. + + Automation Profile + : A named set of confidence thresholds (each `0.0`–`1.0`) gating which plan operations proceed automatically versus requiring human approval. `0.0` = always automatic; `1.0` = always manual. Eight built-in profiles (`manual` through `full-auto`). Custom profiles namespaced as `[[server:]namespace/]name`. + +???+ abstract "Projects & Resources" + + Project + : A named scope linking resources (from the Resource Registry), context policies, invariants, and validation attachments. Does not own resources; a single resource may be linked to multiple projects. Identified solely by its namespaced name (`[[server:]namespace/]name`) — no ULID is generated. May be local or remote. + + Resource + : A ULID-identified entity registered in the Resource Registry representing anything readable, writable, or queryable (git repos, filesystems, databases, etc.). Classified as physical or virtual, typed by a Resource Type, and organized in a DAG via parent/child links. + + Resource Type + : A schema-level definition constraining a category of resources. Specifies accepted CLI arguments, physical/virtual classification, permitted parent/child type relationships, auto-discovery rules, sandbox strategy, and handler implementation. Built-in types (e.g., `git-checkout`, `fs-mount`) are unnamespaced; custom types are namespaced as `[[server:]namespace/]name`. + + Physical Resource + : A resource bound to a concrete, located artifact — a specific file at a specific path, a specific repo at a specific URL. Directly readable and writable by tools. Two physical resources with identical content remain distinct instances. + + Virtual Resource + : A resource representing an abstract equivalence identity that links physical resources sharing the same content, hash, or name. ==Has no location; cannot be directly read or written.== Equivalence relationships update when underlying physical resources diverge. + + Resource Binding + : The association between a tool and the resources it operates on, declared via typed resource slots. Slots resolve through **contextual binding** (from the plan's project), **static binding** (hardcoded at registration), or **parameter binding** (passed at invocation). + + Resource Registry + : The persistent catalog of all registered resources and their DAG relationships (parent/child links). One of the core registries, alongside the Tool Registry, Skill Registry, Actor Registry, and Provider Registry. + +???+ abstract "Tools & Skills" + + Tool + : The ==atomic unit of execution==: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`). Sources: MCP servers, Agent Skills folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`. + + Validation + : A Tool subtype adding: a `mode` (`required` | `informational`) controlling whether failure blocks execution; a structured JSON return with mandatory `passed` boolean, optional `data`, and optional `message`. ==Always read-only== (`writes = false`, `checkpointable = false`). May wrap an existing Tool via `wraps` + `transform`. Managed via `agents validation add/attach/detach`; always attached to a resource, optionally scoped to a project or plan. + + Anonymous Tool + : An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context. + + Skill + : A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing MCP server tools and Agent Skills ([AgentSkills.io](https://AgentSkills.io)) tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`. + + MCP (Model Context Protocol) + : A standard for exposing tools and resources over a server boundary via JSON-RPC. CleverAgents discovers MCP tools through the `MCPToolAdapter` and registers them in the Tool Registry with extended capability metadata. MCP tools can be composed into skills and used as tool nodes in actor graphs. + + Agent Skills ([AgentSkills.io](https://AgentSkills.io)) + : A standard for packaging instruction-driven, multi-step workflows as `SKILL.md` files with optional `scripts/`, `references/`, and `assets/` directories, using progressive disclosure. Surfaced as tools inside skills and loaded on demand by the actor runtime. + +???+ abstract "Actors & Sessions" + + Actor + : A YAML-configured conversational unit — either a single LLM/agent or a composed LangGraph of actors and tool nodes. Specialized roles: strategy actor, execution actor, estimation actor, invariant reconciliation actor. Namespaced as `[[server:]namespace/]name`. + + Session + : A persistent conversation thread tied to an orchestrator actor. Maintains message history across plans and serves as the user's natural-language interface. + + Server + : An optional shared backend providing multi-user storage, namespace resolution, and remote plan execution. + +???+ abstract "Protocols & Standards" + + ACP (Agent Client Protocol) + : A versioned client-server protocol that defines authentication, session lifecycle, plan operations, registry access, and event streaming for all Presentation-layer clients (CLI, TUI, Web, IDE plugin). In local mode ACP maps to in-process service facade calls; in server mode it is implemented by the REST API over HTTPS. + + LSP (Language Server Protocol) + : A standard for IDE integration. The CleverAgents IDE plugin runs as an LSP server that translates code actions and diagnostics into plan operations and validation results, communicating with the backend through ACP. Enables editor-agnostic IDE support without bespoke plugins per editor. + +???+ abstract "Naming & Identity" + + Namespace + : The scoping segment in the name format `[[server:]namespace/]name`. Defaults to `local/` when omitted. `local/` is reserved for local-only items. Non-`local/` namespaces with server omitted assume the default configured server. Built-in LLM actors use provider prefixes (e.g., `openai/`, `anthropic/`). Built-in resource types are unnamespaced. + + ULID + : ==Universally Unique Lexicographically Sortable Identifier.== Assigned to plans, decisions, resources, correction attempts, and validation attachments. Projects, actions, skills, and tools use their namespaced name as sole identifier instead. + +???+ abstract "Context Management (ACMS)" + + ACMS (Advanced Context Management System) + : The pluggable, strategy-driven framework for assembling actor context. Comprises the UKO, CRP, pluggable context strategies, the Context Assembly Pipeline, and hot/warm/cold tiered storage with per-actor scoped views. + + UKO (Universal Knowledge Ontology) + : An RDF-based, inheritance-driven ontology representing resources at multiple abstraction levels with provenance and temporal versioning. Four layers: universal foundation, domain specializations (software, documents, data schemas, infrastructure), paradigm/format specializations (procedural programming, markdown), and technology-specific (Python, PostgreSQL). ==Semantically aware — implicit relationships are inferred from content analysis.== + + CRP (Context Request Protocol) + : A structured vocabulary through which actors declare needed information, desired detail depth, and scope. + + Context Strategy + : A pluggable retrieval component that searches for and assembles ContextFragments using a specific approach (keyword search, semantic embedding, graph navigation, temporal archaeology, etc.). Registered with the Context Assembly Pipeline; executed in parallel by the StrategyExecutor. + + Context Assembly Pipeline + : The central ACMS orchestrator. Ten pluggable Protocol-defined components in three phases: **Strategy Orchestration**, **Fragment Fusion**, and **Context Finalization**. Each component ships with a default implementation and is overridable at global, project, or plan scope. + + Skeleton (context) + : A compressed representation of a plan's accumulated context produced by the SkeletonCompressor. Propagated from parent plans to child plans as inherited context. Size governed by the `skeleton_ratio` budget parameter. ## CLI Commands @@ -233,22 +343,31 @@ The following standards are integrated into the architecture: ### Command Reference +!!! info "Output Format Tabs" + Each command example below is shown in multiple output formats using content tabs. Select a tab to see how the same command renders in that format. The `table` format is visually identical to `rich` in static documentation (the difference is live animation). The `color` format has the same layout as `plain` but with ANSI color codes applied to headers, keys, and values. See **Output Rendering Framework** for full format specifications. + #### Global Options -**Purpose** -Configure global state locations and shell integration for every command. +!!! note "Purpose" + + Configure global state locations and shell integration for every command. **Arguments** - `--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 `core.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. +- `--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 `core.format`. If not set in config either, defaults to `rich`. See **Output Rendering Framework** for full details on each format. + + ??? tip "Available Output Formats" + + | Format | Description | Best For | + | :----- | :---------- | :------- | + | `rich` | Modern rich CLI elements with dynamic effects, animated spinners, progress bars, and generous color | Interactive terminal use **(default)** | + | `color` | Plain scrolling text with ANSI color codes | Terminals that support color but not advanced rendering | + | `table` | ASCII box-drawing characters to create structured tables and panels with color | Structured visual output similar to examples in this document | + | `plain` | Plain text with no color codes or non-ASCII characters | Piping into files, logs, or non-terminal consumers | + | `json` | Structured JSON output for programmatic consumption | Scripts, CI/CD pipelines, programmatic consumption | + | `yaml` | Structured YAML output for programmatic consumption | Configuration, programmatic consumption | - `--help`, `-h`: Print help for the current command. - `--version`: Print the version and exit. - `--install-completion [SHELL]`: Install shell completion for the given shell. @@ -257,41 +376,159 @@ Configure global state locations and shell integration for every command. **Examples** -

-$ agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info
+=== "Rich"
 
-╭─ System Snapshot ─────────────────╮
-│ CleverAgents 1.0.0                │
-│ Mode: local                       │
-│ Automation: review                │
-│ Status: ready                     │
-╰───────────────────────────────────╯
+    

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

+    ╭─ Projects & Sessions ─╮
+    │ Projects: 2           │
+    │ Sessions: 1 active    │
+    │ Active Plans: 0       │
+    │ Actors: 3             │
+    ╰───────────────────────╯
+
+    ✓ OK Environment loaded
+
+ +=== "Plain" + + ``` + $ agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info + + System Snapshot + CleverAgents 1.0.0 + Mode: local + Automation: review + 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 + + Runtime + PID: 4127 + 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 + + [OK] Environment loaded + ``` + +=== "JSON" + + ```json + { + "command": "info", + "status": "ok", + "exit_code": 0, + "data": { + "system_snapshot": { + "name": "CleverAgents", + "version": "1.0.0", + "mode": "local", + "automation": "review", + "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" + }, + "runtime": { + "pid": 4127, + "uptime": "00:14:32", + "python": "3.13.1", + "host": "devbox.local", + "platform": "linux" + }, + "projects_and_sessions": { + "projects": 2, + "sessions": "1 active", + "active_plans": 0, + "actors": 3 + } + }, + "timing": { + "duration_ms": 12 + }, + "messages": [ + { "level": "ok", "text": "Environment loaded" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: info + status: ok + exit_code: 0 + data: + system_snapshot: + name: CleverAgents + version: "1.0.0" + mode: local + automation: review + 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 + runtime: + pid: 4127 + uptime: "00:14:32" + python: "3.13.1" + host: devbox.local + platform: linux + projects_and_sessions: + projects: 2 + sessions: 1 active + active_plans: 0 + actors: 3 + timing: + duration_ms: 12 + messages: + - level: ok + text: Environment loaded + ``` #### agents version @@ -306,32 +543,125 @@ None. **Examples** -

-$ agents version
+=== "Rich"
 
-╭─ CLI Version ────╮
-│ CleverAgents CLI │
-│ Version: 1.0.0   │
-│ Channel: stable  │
-│ Python: 3.13     │
-╰──────────────────╯
+    

+    $ agents version
 
-╭─ Build ────────────────╮
-│ Build Date: 2026-02-08 │
-│ Commit: a17c3f9        │
-│ Schema: v3             │
-│ Platform: linux-x86_64 │
-╰────────────────────────╯
+    ╭─ CLI Version ────╮
+    │ CleverAgents CLI │
+    │ Version: 1.0.0   │
+    │ Channel: stable  │
+    │ Python: 3.13     │
+    ╰──────────────────╯
 
-╭─ Dependencies ─────────────────╮
-│ LangGraph: 0.2.60              │
-│ LangChain: 0.3.18              │
-│ MCP SDK: 1.4.0                 │
-│ Pydantic: 2.10.4               │
-╰────────────────────────────────╯
+    ╭─ Build ────────────────╮
+    │ Build Date: 2026-02-08 │
+    │ Commit: a17c3f9        │
+    │ Schema: v3             │
+    │ Platform: linux-x86_64 │
+    ╰────────────────────────╯
 
-✓ OK Version reported
-

+    ╭─ Dependencies ─────────────────╮
+    │ LangGraph: 0.2.60              │
+    │ LangChain: 0.3.18              │
+    │ MCP SDK: 1.4.0                 │
+    │ Pydantic: 2.10.4               │
+    ╰────────────────────────────────╯
+
+    ✓ OK Version reported
+
+ +=== "Plain" + + ``` + $ agents version + + CLI Version + CleverAgents CLI + Version: 1.0.0 + Channel: stable + Python: 3.13 + + Build + Build Date: 2026-02-08 + Commit: a17c3f9 + Schema: v3 + Platform: linux-x86_64 + + Dependencies + LangGraph: 0.2.60 + LangChain: 0.3.18 + MCP SDK: 1.4.0 + Pydantic: 2.10.4 + + [OK] Version reported + ``` + +=== "JSON" + + ```json + { + "command": "version", + "status": "ok", + "exit_code": 0, + "data": { + "cli": { + "name": "CleverAgents CLI", + "version": "1.0.0", + "channel": "stable", + "python": "3.13" + }, + "build": { + "build_date": "2026-02-08", + "commit": "a17c3f9", + "schema": "v3", + "platform": "linux-x86_64" + }, + "dependencies": { + "langgraph": "0.2.60", + "langchain": "0.3.18", + "mcp_sdk": "1.4.0", + "pydantic": "2.10.4" + } + }, + "timing": { + "duration_ms": 8 + }, + "messages": [ + { "level": "ok", "text": "Version reported" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: version + status: ok + exit_code: 0 + data: + cli: + name: CleverAgents CLI + version: "1.0.0" + channel: stable + python: "3.13" + build: + build_date: "2026-02-08" + commit: a17c3f9 + schema: v3 + platform: linux-x86_64 + dependencies: + langgraph: "0.2.60" + langchain: "0.3.18" + mcp_sdk: "1.4.0" + pydantic: "2.10.4" + timing: + duration_ms: 8 + messages: + - level: ok + text: Version reported + ``` #### agents info @@ -346,40 +676,153 @@ None. **Examples** -

-$ agents info
+=== "Rich"
 
-╭─ Environment ───────────────────────────────────────────────╮
-│ 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)                              │
-╰─────────────────────────────────────────────────────────────╯
+    

+    $ agents info
 
-╭─ Runtime ─────────────────────────╮
-│ Automation: review                │
-│ Providers: 3 configured           │
-│ Sessions: 2 active                │
-│ Active Plans: 1                   │
-╰───────────────────────────────────╯
+    ╭─ Environment ───────────────────────────────────────────────╮
+    │ 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)                              │
+    ╰─────────────────────────────────────────────────────────────╯
 
-╭─ Storage ─────╮
-│ Cache: 118 MB │
-│ Logs: 42 MB   │
-│ Backups: 3    │
-│ DB Size: 8 MB │
-╰───────────────╯
+    ╭─ Runtime ─────────────────────────╮
+    │ Automation: review                │
+    │ Providers: 3 configured           │
+    │ Sessions: 2 active                │
+    │ Active Plans: 1                   │
+    ╰───────────────────────────────────╯
 
-╭─ Indexing ─────────────╮
-│ Text Index: ready      │
-│ Vector Index: ready    │
-│ Graph Store: disabled  │
-│ Indexed Files: 1,247   │
-╰────────────────────────╯
+    ╭─ Storage ─────╮
+    │ Cache: 118 MB │
+    │ Logs: 42 MB   │
+    │ Backups: 3    │
+    │ DB Size: 8 MB │
+    ╰───────────────╯
 
-✓ OK Environment details ready
-

+    ╭─ Indexing ─────────────╮
+    │ Text Index: ready      │
+    │ Vector Index: ready    │
+    │ Graph Store: disabled  │
+    │ Indexed Files: 1,247   │
+    ╰────────────────────────╯
+
+    ✓ OK Environment details ready
+
+ +=== "Plain" + + ``` + $ agents info + + Environment + 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) + + Runtime + Automation: review + Providers: 3 configured + Sessions: 2 active + Active Plans: 1 + + Storage + Cache: 118 MB + Logs: 42 MB + Backups: 3 + DB Size: 8 MB + + Indexing + Text Index: ready + Vector Index: ready + Graph Store: disabled + Indexed Files: 1,247 + + [OK] Environment details ready + ``` + +=== "JSON" + + ```json + { + "command": "info", + "status": "ok", + "exit_code": 0, + "data": { + "environment": { + "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)" + }, + "runtime": { + "automation": "review", + "providers": 3, + "sessions": "2 active", + "active_plans": 1 + }, + "storage": { + "cache_mb": 118, + "logs_mb": 42, + "backups": 3, + "db_size_mb": 8 + }, + "indexing": { + "text_index": "ready", + "vector_index": "ready", + "graph_store": "disabled", + "indexed_files": 1247 + } + }, + "timing": { + "duration_ms": 18 + }, + "messages": [ + { "level": "ok", "text": "Environment details ready" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: info + status: ok + exit_code: 0 + data: + environment: + 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) + runtime: + automation: review + providers: 3 + sessions: 2 active + active_plans: 1 + storage: + cache_mb: 118 + logs_mb: 42 + backups: 3 + db_size_mb: 8 + indexing: + text_index: ready + vector_index: ready + graph_store: disabled + indexed_files: 1247 + timing: + duration_ms: 18 + messages: + - level: ok + text: Environment details ready + ``` #### agents diagnostics @@ -394,83 +837,368 @@ None. **Examples** -

-$ agents diagnostics
+=== "Rich"
 
-╭─ Checks ────────────────────────────────╮
-│ Check            Status  Details        │
-│ ───────────────  ──────  ────────────── │
-│ 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)    │
-│ Graph store      WARN    not configured │
-│ File permissions OK      data dir r/w   │
-│ Git              OK      git 2.43.0     │
-╰─────────────────────────────────────────╯
+    

+    $ agents diagnostics
 
-╭─ Summary ─────────╮
-│ Checks: 10 total  │
-│ Warnings: 2       │
-│ Errors: 0         │
-│ Duration: 0.6s    │
-╰───────────────────╯
+    ╭─ Checks ────────────────────────────────╮
+    │ Check            Status  Details        │
+    │ ───────────────  ──────  ────────────── │
+    │ 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)    │
+    │ Graph store      WARN    not configured │
+    │ File permissions OK      data dir r/w   │
+    │ Git              OK      git 2.43.0     │
+    ╰─────────────────────────────────────────╯
 
-╭─ Recommendations ─────────────────────────────────────────────╮
-│ - Set OPENAI_API_KEY to enable OpenAI models                  │
-│ - Configure a graph store backend for structural code queries │
-│ - Verify provider credentials via config                      │
-╰───────────────────────────────────────────────────────────────╯
+    ╭─ Summary ─────────╮
+    │ Checks: 10 total  │
+    │ Warnings: 2       │
+    │ Errors: 0         │
+    │ Duration: 0.6s    │
+    ╰───────────────────╯
 
-⚠ WARN 2 warnings require attention
-

+    ╭─ Recommendations ─────────────────────────────────────────────╮
+    │ - Set OPENAI_API_KEY to enable OpenAI models                  │
+    │ - Configure a graph store backend for structural code queries │
+    │ - Verify provider credentials via config                      │
+    ╰───────────────────────────────────────────────────────────────╯
+
+    ⚠ WARN 2 warnings require attention
+
+ +=== "Plain" + + ``` + $ agents diagnostics + + Checks + Check Status Details + --------------- ------ -------------- + 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) + Graph store WARN not configured + File permissions OK data dir r/w + Git OK git 2.43.0 + + 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 + - Verify provider credentials via config + + [WARN] 2 warnings require attention + ``` + +=== "JSON" + + ```json + { + "command": "diagnostics", + "status": "ok", + "exit_code": 0, + "data": { + "checks": [ + { "check": "Config file", "status": "ok", "details": "readable" }, + { "check": "Database", "status": "ok", "details": "writable" }, + { "check": "OPENAI_API_KEY", "status": "warn", "details": "missing" }, + { "check": "Anthropic key", "status": "ok", "details": "configured" }, + { "check": "Disk space", "status": "ok", "details": "2.1 GB free" }, + { "check": "Text index", "status": "ok", "details": "tantivy 0.22" }, + { "check": "Vector index", "status": "ok", "details": "faiss (CPU)" }, + { "check": "Graph store", "status": "warn", "details": "not configured" }, + { "check": "File permissions", "status": "ok", "details": "data dir r/w" }, + { "check": "Git", "status": "ok", "details": "git 2.43.0" } + ], + "summary": { + "total": 10, + "warnings": 2, + "errors": 0, + "duration_s": 0.6 + }, + "recommendations": [ + "Set OPENAI_API_KEY to enable OpenAI models", + "Configure a graph store backend for structural code queries", + "Verify provider credentials via config" + ] + }, + "timing": { + "duration_ms": 600 + }, + "messages": [ + { "level": "warn", "text": "2 warnings require attention" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: diagnostics + status: ok + exit_code: 0 + data: + checks: + - check: Config file + status: ok + details: readable + - check: Database + status: ok + details: writable + - check: OPENAI_API_KEY + status: warn + details: missing + - check: Anthropic key + status: ok + details: configured + - check: Disk space + status: ok + details: 2.1 GB free + - check: Text index + status: ok + details: tantivy 0.22 + - check: Vector index + status: ok + details: faiss (CPU) + - check: Graph store + status: warn + details: not configured + - check: File permissions + status: ok + details: data dir r/w + - check: Git + status: ok + details: git 2.43.0 + summary: + total: 10 + warnings: 2 + errors: 0 + duration_s: 0.6 + recommendations: + - Set OPENAI_API_KEY to enable OpenAI models + - Configure a graph store backend for structural code queries + - Verify provider credentials via config + timing: + duration_ms: 600 + messages: + - level: warn + text: 2 warnings require attention + ``` When critical checks fail, diagnostics reports errors: -

-$ agents diagnostics
+=== "Rich"
 
-╭─ 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                │
-╰─────────────────────────────────────────────────────╯
+    

+    $ agents diagnostics
 
-╭─ Summary ─────────╮
-│ Checks: 10 total  │
-│ Warnings: 1       │
-│ Errors: 3         │
-│ Duration: 1.2s    │
-╰───────────────────╯
+    ╭─ 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                │
+    ╰─────────────────────────────────────────────────────╯
 
-╭─ 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 provider.anthropic.api-key                │
-│ 3. FAISS library not installed — vector search will not work        │
-│    Run: pip install faiss-cpu                                       │
-╰─────────────────────────────────────────────────────────────────────╯
+    ╭─ Summary ─────────╮
+    │ Checks: 10 total  │
+    │ Warnings: 1       │
+    │ Errors: 3         │
+    │ Duration: 1.2s    │
+    ╰───────────────────╯
 
-✗ ERROR 3 errors must be resolved before CleverAgents can operate
-

+    ╭─ 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 provider.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
+
+ +=== "Plain" + + ``` + $ 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 provider.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 + ``` + +=== "JSON" + + ```json + { + "command": "diagnostics", + "status": "error", + "exit_code": 1, + "data": { + "checks": [ + { "check": "Config file", "status": "ok", "details": "readable" }, + { "check": "Database", "status": "error", "details": "locked by another process" }, + { "check": "OPENAI_API_KEY", "status": "ok", "details": "configured" }, + { "check": "Anthropic key", "status": "error", "details": "invalid key format" }, + { "check": "Disk space", "status": "warn", "details": "312 MB free (low)" }, + { "check": "Text index", "status": "ok", "details": "tantivy 0.22" }, + { "check": "Vector index", "status": "error", "details": "FAISS library not found" }, + { "check": "Graph store", "status": "ok", "details": "neo4j 5.15" }, + { "check": "File permissions", "status": "ok", "details": "data dir r/w" }, + { "check": "Git", "status": "ok", "details": "git 2.43.0" } + ], + "summary": { + "total": 10, + "warnings": 1, + "errors": 3, + "duration_s": 1.2 + }, + "errors": [ + { + "index": 1, + "message": "Database is locked by PID 12847 -- stop the other process or delete the lock file at ~/.cleveragents/agents.db-lock" + }, + { + "index": 2, + "message": "Anthropic key starts with \"pk-\" -- expected \"sk-ant-\" prefix", + "fix": "agents config set provider.anthropic.api-key " + }, + { + "index": 3, + "message": "FAISS library not installed -- vector search will not work", + "fix": "pip install faiss-cpu" + } + ] + }, + "timing": { + "duration_ms": 1200 + }, + "messages": [ + { "level": "error", "text": "3 errors must be resolved before CleverAgents can operate" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: diagnostics + status: error + exit_code: 1 + data: + checks: + - check: Config file + status: ok + details: readable + - check: Database + status: error + details: locked by another process + - check: OPENAI_API_KEY + status: ok + details: configured + - check: Anthropic key + status: error + details: invalid key format + - check: Disk space + status: warn + details: 312 MB free (low) + - check: Text index + status: ok + details: tantivy 0.22 + - check: Vector index + status: error + details: FAISS library not found + - check: Graph store + status: ok + details: neo4j 5.15 + - check: File permissions + status: ok + details: data dir r/w + - check: Git + status: ok + details: git 2.43.0 + summary: + total: 10 + warnings: 1 + errors: 3 + duration_s: 1.2 + errors: + - index: 1 + message: >- + Database is locked by PID 12847 -- stop the other process or + delete the lock file at ~/.cleveragents/agents.db-lock + - index: 2 + message: Anthropic key starts with "pk-" -- expected "sk-ant-" prefix + fix: agents config set provider.anthropic.api-key + - index: 3 + message: FAISS library not installed -- vector search will not work + fix: pip install faiss-cpu + timing: + duration_ms: 1200 + messages: + - level: error + text: 3 errors must be resolved before CleverAgents can operate + ``` #### agents init 
agents init [--yes|-y]
+!!! danger "Destructive Operation" + + This command ==wipes all existing data== and re-creates the global config and database. A backup is created automatically, but all sessions, plans, and registry entries will be removed. + **Purpose** Initialize or reset the global CleverAgents environment. This wipes any existing data and re-creates the global config and database. @@ -480,55 +1208,225 @@ Initialize or reset the global CleverAgents environment. This wipes any existing **Examples** -

-$ agents init
+=== "Rich"
 
-Warning: This will remove all data in /home/alex/.cleveragents
-Continue? [y/N]: y
+    

+    $ agents init
 
-╭─ Environment Reset ────────────────────────────────╮
-│ Config: /home/alex/.cleveragents/config.toml       │
-│ Database: /home/alex/.cleveragents/cleveragents.db │
-│ Backup: /home/alex/.cleveragents.backup-2026-02-08 │
-│ Status: ready                                      │
-╰────────────────────────────────────────────────────╯
+    Warning: This will remove all data in /home/alex/.cleveragents
+    Continue? [y/N]: y
 
-╭─ Defaults ──────────────────────────────────╮
-│ Automation Profile: supervised              │
-│ Built-in Profiles: 8 loaded                 │
-╰─────────────────────────────────────────────╯
+    ╭─ Environment Reset ────────────────────────────────╮
+    │ Config: /home/alex/.cleveragents/config.toml       │
+    │ Database: /home/alex/.cleveragents/cleveragents.db │
+    │ Backup: /home/alex/.cleveragents.backup-2026-02-08 │
+    │ Status: ready                                      │
+    ╰────────────────────────────────────────────────────╯
 
-╭─ Created ─────────────────╮
-│ Config: config.toml       │
-│ Database: cleveragents.db │
-│ Logs: logs/               │
-│ Cache: cache/             │
-│ Backups: backups/         │
-╰───────────────────────────╯
+    ╭─ Defaults ──────────────────────────────────╮
+    │ Automation Profile: supervised              │
+    │ Built-in Profiles: 8 loaded                 │
+    ╰─────────────────────────────────────────────╯
 
-╭─ Schema ───────────────────────╮
-│ Version: v3                    │
-│ Tables: 12 created             │
-│ Migrations: up to date         │
-╰────────────────────────────────╯
+    ╭─ Created ─────────────────╮
+    │ Config: config.toml       │
+    │ Database: cleveragents.db │
+    │ Logs: logs/               │
+    │ Cache: cache/             │
+    │ Backups: backups/         │
+    ╰───────────────────────────╯
 
-✓ OK Environment initialized
-

+    ╭─ Schema ───────────────────────╮
+    │ Version: v3                    │
+    │ Tables: 12 created             │
+    │ Migrations: up to date         │
+    ╰────────────────────────────────╯
+
+    ✓ OK Environment initialized
+
+ +=== "Plain" + + ``` + $ 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 + Backup: /home/alex/.cleveragents.backup-2026-02-08 + Status: ready + + Defaults + Automation Profile: supervised + Built-in Profiles: 8 loaded + + Created + Config: config.toml + Database: cleveragents.db + Logs: logs/ + Cache: cache/ + Backups: backups/ + + Schema + Version: v3 + Tables: 12 created + Migrations: up to date + + [OK] Environment initialized + ``` + +=== "JSON" + + ```json + { + "command": "init", + "status": "ok", + "exit_code": 0, + "data": { + "environment_reset": { + "config": "/home/alex/.cleveragents/config.toml", + "database": "/home/alex/.cleveragents/cleveragents.db", + "backup": "/home/alex/.cleveragents.backup-2026-02-08", + "status": "ready" + }, + "defaults": { + "automation_profile": "supervised", + "builtin_profiles": 8 + }, + "created": { + "config": "config.toml", + "database": "cleveragents.db", + "logs": "logs/", + "cache": "cache/", + "backups": "backups/" + }, + "schema": { + "version": "v3", + "tables": 12, + "migrations": "up to date" + } + }, + "timing": { + "duration_ms": 340 + }, + "messages": [ + { "level": "ok", "text": "Environment initialized" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: init + status: ok + exit_code: 0 + data: + environment_reset: + config: /home/alex/.cleveragents/config.toml + database: /home/alex/.cleveragents/cleveragents.db + backup: /home/alex/.cleveragents.backup-2026-02-08 + status: ready + defaults: + automation_profile: supervised + builtin_profiles: 8 + created: + config: config.toml + database: cleveragents.db + logs: logs/ + cache: cache/ + backups: backups/ + schema: + version: v3 + tables: 12 + migrations: up to date + timing: + duration_ms: 340 + messages: + - level: ok + text: Environment initialized + ``` Non-interactive initialization using `--yes` (useful in scripts and CI): -

-$ agents init --yes
+=== "Rich"
 
-╭─ Initialized ──────────────────────────────────────────╮
-│ Data Dir: /home/alex/.cleveragents (created)           │
-│ Config: /home/alex/.cleveragents/config.toml           │
-│ Database: initialized (schema v3)                      │
-│ Directories: logs, cache, sessions, contexts           │
-╰────────────────────────────────────────────────────────╯
+    

+    $ agents init --yes
 
-✓ OK Initialized (non-interactive)
-

+    ╭─ 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)
+
+ +=== "Plain" + + ``` + $ 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) + ``` + +=== "JSON" + + ```json + { + "command": "init --yes", + "status": "ok", + "exit_code": 0, + "data": { + "initialized": { + "data_dir": "/home/alex/.cleveragents", + "config": "/home/alex/.cleveragents/config.toml", + "database": "initialized (schema v3)", + "directories": ["logs", "cache", "sessions", "contexts"] + } + }, + "timing": { + "duration_ms": 280 + }, + "messages": [ + { "level": "ok", "text": "Initialized (non-interactive)" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: init --yes + status: ok + exit_code: 0 + data: + initialized: + data_dir: /home/alex/.cleveragents + config: /home/alex/.cleveragents/config.toml + database: initialized (schema v3) + directories: + - logs + - cache + - sessions + - contexts + timing: + duration_ms: 280 + messages: + - level: ok + text: Initialized (non-interactive) + ``` #### agents session @@ -548,33 +1446,125 @@ Create a new session for interactive work. **Examples** -

-$ agents session create --actor local/orchestrator
+=== "Rich"
 
-╭─ Session ───────────────────────╮
-│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z  │
-│ Actor: local/orchestrator       │
-│ Created: 2026-02-08 12:44       │
-│ Namespace: local                │
-╰─────────────────────────────────╯
+    

+    $ agents session create --actor local/orchestrator
 
-╭─ Settings ─────────────╮
-│ Automation: review     │
-│ Streaming: off         │
-│ Context: default       │
-│ Memory: enabled        │
-│ Max History: 50 turns  │
-╰────────────────────────╯
+    ╭─ Session ───────────────────────╮
+    │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z  │
+    │ Actor: local/orchestrator       │
+    │ Created: 2026-02-08 12:44       │
+    │ Namespace: local                │
+    ╰─────────────────────────────────╯
 
-╭─ Actor Details ───────────────────╮
-│ Provider: anthropic               │
-│ Model: claude-3.5                 │
-│ Temperature: 0.7                  │
-│ Context Window: 200K tokens       │
-╰───────────────────────────────────╯
+    ╭─ Settings ─────────────╮
+    │ Automation: review     │
+    │ Streaming: off         │
+    │ Context: default       │
+    │ Memory: enabled        │
+    │ Max History: 50 turns  │
+    ╰────────────────────────╯
 
-✓ OK Session created
-

+    ╭─ Actor Details ───────────────────╮
+    │ Provider: anthropic               │
+    │ Model: claude-3.5                 │
+    │ Temperature: 0.7                  │
+    │ Context Window: 200K tokens       │
+    ╰───────────────────────────────────╯
+
+    ✓ OK Session created
+
+ +=== "Plain" + + ``` + $ agents session create --actor local/orchestrator + + 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 + + Actor Details + Provider: anthropic + Model: claude-3.5 + Temperature: 0.7 + Context Window: 200K tokens + + [OK] Session created + ``` + +=== "JSON" + + ```json + { + "command": "agents session create --actor local/orchestrator", + "status": "ok", + "exit_code": 0, + "data": { + "session": { + "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "actor": "local/orchestrator", + "created": "2026-02-08T12:44:00Z", + "namespace": "local" + }, + "settings": { + "automation": "review", + "streaming": "off", + "context": "default", + "memory": "enabled", + "max_history": 50 + }, + "actor_details": { + "provider": "anthropic", + "model": "claude-3.5", + "temperature": 0.7, + "context_window": "200K tokens" + } + }, + "timing": { "duration_ms": 120 }, + "messages": [{ "level": "ok", "text": "Session created" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents session create --actor local/orchestrator + status: ok + exit_code: 0 + data: + session: + id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + actor: local/orchestrator + created: "2026-02-08T12:44:00Z" + namespace: local + settings: + automation: review + streaming: "off" + context: default + memory: enabled + max_history: 50 + actor_details: + provider: anthropic + model: claude-3.5 + temperature: 0.7 + context_window: 200K tokens + timing: + duration_ms: 120 + messages: + - level: ok + text: Session created + ``` ##### agents session list @@ -589,26 +1579,117 @@ None. **Examples** -

-$ agents --format table session list
+=== "Rich"
 
-╭─ 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    │
-╰──────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents --format table session list
 
-╭─ Summary ────────────────────╮
-│ Total: 2                     │
-│ Most Recent: weekly-planning │
-│ Oldest: refactor-sprint      │
-│ Total Messages: 20           │
-│ Storage: 42 KB               │
-╰──────────────────────────────╯
+    ╭─ 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    │
+    ╰──────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 2 sessions listed
-

+    ╭─ Summary ────────────────────╮
+    │ Total: 2                     │
+    │ Most Recent: weekly-planning │
+    │ Oldest: refactor-sprint      │
+    │ Total Messages: 20           │
+    │ Storage: 42 KB               │
+    ╰──────────────────────────────╯
+
+    ✓ OK 2 sessions listed
+
+ +=== "Plain" + + ``` + $ 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 + + Summary + Total: 2 + Most Recent: weekly-planning + Oldest: refactor-sprint + Total Messages: 20 + Storage: 42 KB + + [OK] 2 sessions listed + ``` + +=== "JSON" + + ```json + { + "command": "agents --format table session list", + "status": "ok", + "exit_code": 0, + "data": { + "sessions": [ + { + "id": "01HXM2A6", + "name": "weekly-planning", + "actor": "local/orchestrator", + "messages": 6, + "updated": "2026-02-08T12:44:00Z" + }, + { + "id": "01HXM1F2", + "name": "refactor-sprint", + "actor": "local/orchestrator", + "messages": 14, + "updated": "2026-02-07T18:11:00Z" + } + ], + "summary": { + "total": 2, + "most_recent": "weekly-planning", + "oldest": "refactor-sprint", + "total_messages": 20, + "storage": "42 KB" + } + }, + "timing": { "duration_ms": 85 }, + "messages": [{ "level": "ok", "text": "2 sessions listed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents --format table session list + status: ok + exit_code: 0 + data: + sessions: + - id: 01HXM2A6 + name: weekly-planning + actor: local/orchestrator + messages: 6 + updated: "2026-02-08T12:44:00Z" + - id: 01HXM1F2 + name: refactor-sprint + actor: local/orchestrator + messages: 14 + updated: "2026-02-07T18:11:00Z" + summary: + total: 2 + most_recent: weekly-planning + oldest: refactor-sprint + total_messages: 20 + storage: 42 KB + timing: + duration_ms: 85 + messages: + - level: ok + text: 2 sessions listed + ``` ##### agents session show @@ -623,45 +1704,153 @@ Show details and recent messages for a session. **Examples** -

-$ agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
+=== "Rich"
 
-╭─ Session Summary ───────────────╮
-│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z  │
-│ Actor: local/orchestrator       │
-│ Messages: 6                     │
-│ Created: 2026-02-08 12:30       │
-│ Updated: 2026-02-08 12:44       │
-│ Automation: review              │
-╰─────────────────────────────────╯
+    

+    $ agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
-╭─ Recent Messages ──────────────────────────────────╮
-│ user  Create an action to refresh dependency locks │
-│ assistant  Plan created, running commands...       │
-│ assistant  Completed 2 commands                    │
-╰────────────────────────────────────────────────────╯
+    ╭─ Session Summary ───────────────╮
+    │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z  │
+    │ Actor: local/orchestrator       │
+    │ Messages: 6                     │
+    │ Created: 2026-02-08 12:30       │
+    │ Updated: 2026-02-08 12:44       │
+    │ Automation: review              │
+    ╰─────────────────────────────────╯
 
-╭─ Linked Plans ────────────────────────────────╮
-│ Plan ID                     Phase   State     │
-│ ──────────────────────────  ──────  ────────  │
-│ 01HXM8C2ZK4Q7C2B3F2R4VYV6J  execute  complete │
-╰───────────────────────────────────────────────╯
+    ╭─ Recent Messages ──────────────────────────────────╮
+    │ user  Create an action to refresh dependency locks │
+    │ assistant  Plan created, running commands...       │
+    │ assistant  Completed 2 commands                    │
+    ╰────────────────────────────────────────────────────╯
 
-╭─ Token Usage ──────────────╮
-│ Input Tokens: 3,420        │
-│ Output Tokens: 1,185       │
-│ Estimated Cost: $0.0184    │
-╰────────────────────────────╯
+    ╭─ Linked Plans ────────────────────────────────╮
+    │ Plan ID                     Phase   State     │
+    │ ──────────────────────────  ──────  ────────  │
+    │ 01HXM8C2ZK4Q7C2B3F2R4VYV6J  execute  complete │
+    ╰───────────────────────────────────────────────╯
 
-✓ OK Session details loaded
-

+    ╭─ Token Usage ──────────────╮
+    │ Input Tokens: 3,420        │
+    │ Output Tokens: 1,185       │
+    │ Estimated Cost: $0.0184    │
+    ╰────────────────────────────╯
+
+    ✓ OK Session details loaded
+
+ +=== "Plain" + + ``` + $ agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + + 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 + assistant Plan created, running commands... + assistant Completed 2 commands + + Linked Plans + Plan ID Phase State + -------------------------- ------- -------- + 01HXM8C2ZK4Q7C2B3F2R4VYV6J execute complete + + Token Usage + Input Tokens: 3,420 + Output Tokens: 1,185 + Estimated Cost: $0.0184 + + [OK] Session details loaded + ``` + +=== "JSON" + + ```json + { + "command": "agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "status": "ok", + "exit_code": 0, + "data": { + "session_summary": { + "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "actor": "local/orchestrator", + "messages": 6, + "created": "2026-02-08T12:30:00Z", + "updated": "2026-02-08T12:44:00Z", + "automation": "review" + }, + "recent_messages": [ + { "role": "user", "text": "Create an action to refresh dependency locks" }, + { "role": "assistant", "text": "Plan created, running commands..." }, + { "role": "assistant", "text": "Completed 2 commands" } + ], + "linked_plans": [ + { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "phase": "execute", + "state": "complete" + } + ], + "token_usage": { + "input_tokens": 3420, + "output_tokens": 1185, + "estimated_cost": "$0.0184" + } + }, + "timing": { "duration_ms": 95 }, + "messages": [{ "level": "ok", "text": "Session details loaded" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + status: ok + exit_code: 0 + data: + session_summary: + id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + actor: local/orchestrator + messages: 6 + created: "2026-02-08T12:30:00Z" + updated: "2026-02-08T12:44:00Z" + automation: review + recent_messages: + - role: user + text: Create an action to refresh dependency locks + - role: assistant + text: Plan created, running commands... + - role: assistant + text: Completed 2 commands + linked_plans: + - plan_id: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + phase: execute + state: complete + token_usage: + input_tokens: 3420 + output_tokens: 1185 + estimated_cost: "$0.0184" + timing: + duration_ms: 95 + messages: + - level: ok + text: Session details loaded + ``` ##### agents session delete 
agents session delete [--yes|-y] <SESSION_ID>
-**Purpose** -Delete a session and its stored conversation history. +!!! danger "Irreversible Deletion" + This command ==permanently deletes== a session and its stored conversation history. Messages and context cannot be recovered after deletion. Use `--yes` to skip the confirmation prompt. **Arguments** @@ -670,28 +1859,105 @@ Delete a session and its stored conversation history. **Examples** -

-$ agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
+=== "Rich"
 
-Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
+    

+    $ agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
-╭─ Deletion Summary ──────────────────╮
-│ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
-│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z      │
-│ Messages: 6 removed                 │
-│ Storage: 18 KB freed                │
-│ Plans Orphaned: 0                   │
-╰─────────────────────────────────────╯
+    Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
 
-╭─ Cleanup ───────────╮
-│ Backups: none       │
-│ Logs: preserved     │
-│ Context: cleared    │
-│ Checkpoints: none   │
-╰─────────────────────╯
+    ╭─ Deletion Summary ──────────────────╮
+    │ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
+    │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z      │
+    │ Messages: 6 removed                 │
+    │ Storage: 18 KB freed                │
+    │ Plans Orphaned: 0                   │
+    ╰─────────────────────────────────────╯
 
-✓ OK Session deleted
-

+    ╭─ Cleanup ───────────╮
+    │ Backups: none       │
+    │ Logs: preserved     │
+    │ Context: cleared    │
+    │ Checkpoints: none   │
+    ╰─────────────────────╯
+
+    ✓ OK Session deleted
+
+ +=== "Plain" + + ``` + $ agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + + Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y + + 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 + + [OK] Session deleted + ``` + +=== "JSON" + + ```json + { + "command": "agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "status": "ok", + "exit_code": 0, + "data": { + "deletion_summary": { + "session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "messages_removed": 6, + "storage_freed": "18 KB", + "plans_orphaned": 0 + }, + "cleanup": { + "backups": "none", + "logs": "preserved", + "context": "cleared", + "checkpoints": "none" + } + }, + "timing": { "duration_ms": 62 }, + "messages": [{ "level": "ok", "text": "Session deleted" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + status: ok + exit_code: 0 + data: + deletion_summary: + session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + messages_removed: 6 + storage_freed: 18 KB + plans_orphaned: 0 + cleanup: + backups: none + logs: preserved + context: cleared + checkpoints: none + timing: + duration_ms: 62 + messages: + - level: ok + text: Session deleted + ``` ##### agents session export @@ -707,32 +1973,121 @@ Export a session as a portable JSON file. **Examples** -

-$ agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
+=== "Rich"
 
-╭─ Session Export ────────────────────╮
-│ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
-│ Output: /tmp/weekly-planning.json   │
-│ Messages: 6                         │
-│ Size: 24 KB                         │
-│ Format: JSON                        │
-╰─────────────────────────────────────╯
+    

+    $ agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
-╭─ Contents ─────────────────╮
-│ Messages: 6                │
-│ Plan References: 1         │
-│ Metadata Keys: 2           │
-│ Actor Config: included     │
-│ Schema Version: v3         │
-╰────────────────────────────╯
+    ╭─ Session Export ────────────────────╮
+    │ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
+    │ Output: /tmp/weekly-planning.json   │
+    │ Messages: 6                         │
+    │ Size: 24 KB                         │
+    │ Format: JSON                        │
+    ╰─────────────────────────────────────╯
 
-╭─ Integrity ──────────────────╮
-│ Checksum: sha256:7a9b...42c1 │
-│ Encrypted: no                │
-╰──────────────────────────────╯
+    ╭─ Contents ─────────────────╮
+    │ Messages: 6                │
+    │ Plan References: 1         │
+    │ Metadata Keys: 2           │
+    │ Actor Config: included     │
+    │ Schema Version: v3         │
+    ╰────────────────────────────╯
 
-✓ OK Export completed
-

+    ╭─ Integrity ──────────────────╮
+    │ Checksum: sha256:7a9b...42c1 │
+    │ Encrypted: no                │
+    ╰──────────────────────────────╯
+
+    ✓ OK Export completed
+
+ +=== "Plain" + + ``` + $ agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + + 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 + + Integrity + Checksum: sha256:7a9b...42c1 + Encrypted: no + + [OK] Export completed + ``` + +=== "JSON" + + ```json + { + "command": "agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "status": "ok", + "exit_code": 0, + "data": { + "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" + }, + "integrity": { + "checksum": "sha256:7a9b...42c1", + "encrypted": false + } + }, + "timing": { "duration_ms": 140 }, + "messages": [{ "level": "ok", "text": "Export completed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + status: ok + exit_code: 0 + data: + 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 + integrity: + checksum: "sha256:7a9b...42c1" + encrypted: false + timing: + duration_ms: 140 + messages: + - level: ok + text: Export completed + ``` ##### agents session import @@ -747,34 +2102,118 @@ Import a session JSON file. **Examples** -

-$ agents session import --input /tmp/weekly-planning.json
+=== "Rich"
 
-╭─ Session Import ────────────────────────╮
-│ Input: /tmp/weekly-planning.json        │
-│ Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1  │
-│ Messages: 6                             │
-│ Schema: v3                              │
-╰─────────────────────────────────────────╯
+    

+    $ agents session import --input /tmp/weekly-planning.json
 
-╭─ Validation ────────────╮
-│ Checksum: verified      │
-│ Schema: compatible      │
-│ Actor Ref: resolved     │
-╰─────────────────────────╯
+    ╭─ Session Import ────────────────────────╮
+    │ Input: /tmp/weekly-planning.json        │
+    │ Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1  │
+    │ Messages: 6                             │
+    │ Schema: v3                              │
+    ╰─────────────────────────────────────────╯
 
-╭─ Merge ──────────────╮
-│ Existing: none       │
-│ Strategy: create new │
-╰──────────────────────╯
+    ╭─ Validation ────────────╮
+    │ Checksum: verified      │
+    │ Schema: compatible      │
+    │ Actor Ref: resolved     │
+    ╰─────────────────────────╯
 
-✓ OK Import completed
-

+    ╭─ Merge ──────────────╮
+    │ Existing: none       │
+    │ Strategy: create new │
+    ╰──────────────────────╯
+
+    ✓ OK Import completed
+
+ +=== "Plain" + + ``` + $ agents session import --input /tmp/weekly-planning.json + + Session Import + Input: /tmp/weekly-planning.json + Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1 + Messages: 6 + Schema: v3 + + Validation + Checksum: verified + Schema: compatible + Actor Ref: resolved + + Merge + Existing: none + Strategy: create new + + [OK] Import completed + ``` + +=== "JSON" + + ```json + { + "command": "agents session import --input /tmp/weekly-planning.json", + "status": "ok", + "exit_code": 0, + "data": { + "session_import": { + "input": "/tmp/weekly-planning.json", + "session_id": "01HXM3D3B2W4CQYQ3P4ZB8A5T1", + "messages": 6, + "schema": "v3" + }, + "validation": { + "checksum": "verified", + "schema": "compatible", + "actor_ref": "resolved" + }, + "merge": { + "existing": "none", + "strategy": "create new" + } + }, + "timing": { "duration_ms": 210 }, + "messages": [{ "level": "ok", "text": "Import completed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents session import --input /tmp/weekly-planning.json + status: ok + exit_code: 0 + data: + session_import: + input: /tmp/weekly-planning.json + session_id: 01HXM3D3B2W4CQYQ3P4ZB8A5T1 + messages: 6 + schema: v3 + validation: + checksum: verified + schema: compatible + actor_ref: resolved + merge: + existing: none + strategy: create new + timing: + duration_ms: 210 + messages: + - level: ok + text: Import completed + ``` ##### agents session tell 
agents session tell --session <SESSION_ID> [--actor <ACTOR>] [--stream] <PROMPT>
+!!! tip "Primary User Interface" + + This is the main natural-language interface for interacting with CleverAgents. The orchestrator interprets your request and issues the necessary CleverAgents commands under the hood — creating actions, plans, or project changes as needed. Use `--stream` to see responses in real time. + **Purpose** Send a natural-language request to the orchestrator. The orchestrator can create actions, plans, or project changes by issuing the necessary CleverAgents commands under the hood. @@ -787,70 +2226,276 @@ Send a natural-language request to the orchestrator. The orchestrator can create **Examples** -

-$ agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
-  --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
+=== "Rich"
 
-╭─ Plan Request ──────────────────────────────────────────╮
-│ Actor: local/orchestrator                               │
-│ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z                     │
-│ Automation: review                                      │
-│ Prompt: Create an action to refresh dependency locks... │
-╰─────────────────────────────────────────────────────────╯
+    

+    $ agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
+      --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
 
-╭─ Commands Executed ─────────────────────────────────────────────────────────────────────────────────────────╮
-│ - agents action create --config ./actions/refresh-locks.yaml                                              │
-│ - agents resource add git-checkout local/platform-repo --path /repos/platform                               │
-│ - agents project link-resource local/platform local/platform-repo                                           │
-╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+    ╭─ Plan Request ──────────────────────────────────────────╮
+    │ Actor: local/orchestrator                               │
+    │ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z                     │
+    │ Automation: review                                      │
+    │ Prompt: Create an action to refresh dependency locks... │
+    ╰─────────────────────────────────────────────────────────╯
 
-╭─ Result ──────────────────────────╮
-│ Action: local/refresh-locks       │
-│ Project: local/platform           │
-│ Resource: local/platform-repo     │
-╰───────────────────────────────────╯
+    ╭─ Commands Executed ─────────────────────────────────────────────────────────────────────────────────────────╮
+    │ - agents action create --config ./actions/refresh-locks.yaml                                              │
+    │ - agents resource add git-checkout local/platform-repo --path /repos/platform                               │
+    │ - agents project link-resource local/platform local/platform-repo                                           │
+    ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-╭─ Usage ─────────────────────╮
-│ Input Tokens: 1,842         │
-│ Output Tokens: 624          │
-│ Cost: $0.0094               │
-│ Duration: 3.2s              │
-│ Tool Calls: 3               │
-╰─────────────────────────────╯
+    ╭─ Result ──────────────────────────╮
+    │ Action: local/refresh-locks       │
+    │ Project: local/platform           │
+    │ Resource: local/platform-repo     │
+    ╰───────────────────────────────────╯
 
-✓ OK Orchestrator completed 3 commands
-

+    ╭─ Usage ─────────────────────╮
+    │ Input Tokens: 1,842         │
+    │ Output Tokens: 624          │
+    │ Cost: $0.0094               │
+    │ Duration: 3.2s              │
+    │ Tool Calls: 3               │
+    ╰─────────────────────────────╯
+
+    ✓ OK Orchestrator completed 3 commands
+
+ +=== "Plain" + + ``` + $ 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: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + Automation: review + Prompt: Create an action to refresh dependency locks... + + Commands Executed + - agents action create --config ./actions/refresh-locks.yaml + - agents resource add git-checkout local/platform-repo --path /repos/platform + - agents project link-resource local/platform local/platform-repo + + Result + Action: local/refresh-locks + Project: local/platform + Resource: local/platform-repo + + Usage + Input Tokens: 1,842 + Output Tokens: 624 + Cost: $0.0094 + Duration: 3.2s + Tool Calls: 3 + + [OK] Orchestrator completed 3 commands + ``` + +=== "JSON" + + ```json + { + "command": "agents session tell \"Create an action to refresh dependency locks and add it to the platform project\" --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "status": "ok", + "exit_code": 0, + "data": { + "plan_request": { + "actor": "local/orchestrator", + "session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "automation": "review", + "prompt": "Create an action to refresh dependency locks..." + }, + "commands_executed": [ + "agents action create --config ./actions/refresh-locks.yaml", + "agents resource add git-checkout local/platform-repo --path /repos/platform", + "agents project link-resource local/platform local/platform-repo" + ], + "result": { + "action": "local/refresh-locks", + "project": "local/platform", + "resource": "local/platform-repo" + }, + "usage": { + "input_tokens": 1842, + "output_tokens": 624, + "cost": "$0.0094", + "duration_s": 3.2, + "tool_calls": 3 + } + }, + "timing": { "duration_ms": 3200 }, + "messages": [{ "level": "ok", "text": "Orchestrator completed 3 commands" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents session tell "Create an action to refresh dependency locks and add it to the platform project" --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + status: ok + exit_code: 0 + data: + plan_request: + actor: local/orchestrator + session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + automation: review + prompt: Create an action to refresh dependency locks... + commands_executed: + - agents action create --config ./actions/refresh-locks.yaml + - agents resource add git-checkout local/platform-repo --path /repos/platform + - agents project link-resource local/platform local/platform-repo + result: + action: local/refresh-locks + project: local/platform + resource: local/platform-repo + usage: + input_tokens: 1842 + output_tokens: 624 + cost: "$0.0094" + duration_s: 3.2 + tool_calls: 3 + timing: + duration_ms: 3200 + messages: + - level: ok + text: 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?"
+=== "Rich"
 
-╭─ Session ──────────────────────────╮
-│ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z     │
-│ Actor: local/orchestrator          │
-│ Mode: streaming                    │
-╰────────────────────────────────────╯
+    

+    $ agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?"
 
-▍ The last plan (01HXM8C2ZK) modified 6 files in the auth module:
+    ╭─ Session ──────────────────────────╮
+    │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z     │
+    │ Actor: local/orchestrator          │
+    │ Mode: streaming                    │
+    ╰────────────────────────────────────╯
 
-  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
+    ▍ The last plan (01HXM8C2ZK) modified 6 files in the auth module:
 
-All changes passed validation (24/24 tests, lint clean).
+      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
 
-╭─ Usage ──────────────────╮
-│ Tokens: 1,240 (stream)   │
-│ Duration: 3.1s           │
-│ Tool Calls: 2            │
-╰──────────────────────────╯
+    All changes passed validation (24/24 tests, lint clean).
 
-✓ OK Stream complete
-

+    ╭─ Usage ──────────────────╮
+    │ Tokens: 1,240 (stream)   │
+    │ Duration: 3.1s           │
+    │ Tool Calls: 2            │
+    ╰──────────────────────────╯
+
+    ✓ OK Stream complete
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "agents session tell --session 01HXM2A6K1 --stream \"What files were changed in the last plan?\"", + "status": "ok", + "exit_code": 0, + "data": { + "session": { + "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", + "actor": "local/orchestrator", + "mode": "streaming" + }, + "response": "The last plan (01HXM8C2ZK) modified 6 files in the auth module:\n\n1. src/auth/session.py \u2014 refactored session validation\n2. src/auth/tokens.py \u2014 updated token expiry to 7200s\n3. src/auth/__init__.py \u2014 updated exports\n4. tests/test_auth.py \u2014 added 12 new test cases\n5. tests/test_session.py \u2014 updated session fixtures\n6. docs/auth.md \u2014 updated API documentation\n\nAll changes passed validation (24/24 tests, lint clean).", + "files_changed": [ + "src/auth/session.py", + "src/auth/tokens.py", + "src/auth/__init__.py", + "tests/test_auth.py", + "tests/test_session.py", + "docs/auth.md" + ], + "usage": { + "tokens": 1240, + "duration_s": 3.1, + "tool_calls": 2 + } + }, + "timing": { "duration_ms": 3100 }, + "messages": [{ "level": "ok", "text": "Stream complete" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?" + status: ok + exit_code: 0 + data: + session: + id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z + actor: local/orchestrator + mode: streaming + response: > + 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). + files_changed: + - src/auth/session.py + - src/auth/tokens.py + - src/auth/__init__.py + - tests/test_auth.py + - tests/test_session.py + - docs/auth.md + usage: + tokens: 1240 + duration_s: 3.1 + tool_calls: 2 + timing: + duration_ms: 3100 + messages: + - level: ok + text: Stream complete + ``` #### agents project @@ -875,68 +2520,256 @@ Create a new project record. **Examples** -

-$ agents project create --description "Backend API" local/api-service
+=== "Rich"
 
-╭─ Project ──────────────────────╮
-│ Name: local/api-service        │
-│ Description: Backend API       │
-│ Type: local                    │
-│ Created: 2026-02-08 12:46      │
-╰────────────────────────────────╯
+    

+    $ agents project create --description "Backend API" local/api-service
 
-╭─ Paths ────────────────────────────────────╮
-│ Root: /repos/api-service                   │
-│ Data Dir: /repos/api-service/.cleveragents │
-╰────────────────────────────────────────────╯
+    ╭─ Project ──────────────────────╮
+    │ Name: local/api-service        │
+    │ Description: Backend API       │
+    │ Type: local                    │
+    │ Created: 2026-02-08 12:46      │
+    ╰────────────────────────────────╯
 
-╭─ Defaults ──────────────────────────────╮
-│ Sandbox: git_worktree                   │
-│ Validations: 0                          │
-│ Context Filters: none                   │
-│ Automation Profile: (inherits global)   │
-╰─────────────────────────────────────────╯
+    ╭─ Paths ────────────────────────────────────╮
+    │ Root: /repos/api-service                   │
+    │ Data Dir: /repos/api-service/.cleveragents │
+    ╰────────────────────────────────────────────╯
 
-╭─ Resources ──────╮
-│ Total: 0         │
-│ Indexed: 0       │
-│ Sandboxable: 0   │
-╰──────────────────╯
+    ╭─ Defaults ──────────────────────────────╮
+    │ Sandbox: git_worktree                   │
+    │ Validations: 0                          │
+    │ Context Filters: none                   │
+    │ Automation Profile: (inherits global)   │
+    ╰─────────────────────────────────────────╯
 
-✓ OK Project created
-

+    ╭─ Resources ──────╮
+    │ Total: 0         │
+    │ Indexed: 0       │
+    │ Sandboxable: 0   │
+    ╰──────────────────╯
+
+    ✓ OK Project created
+
+ +=== "Plain" + + ``` + $ agents project create --description "Backend API" local/api-service + + Project + Name: local/api-service + Description: Backend API + Type: local + Created: 2026-02-08 12:46 + + Paths + Root: /repos/api-service + Data Dir: /repos/api-service/.cleveragents + + Defaults + Sandbox: git_worktree + Validations: 0 + Context Filters: none + Automation Profile: (inherits global) + + Resources + Total: 0 + Indexed: 0 + Sandboxable: 0 + + [OK] Project created + ``` + +=== "JSON" + + ```json + { + "command": "agents project create --description \"Backend API\" local/api-service", + "status": "ok", + "exit_code": 0, + "data": { + "project": { + "name": "local/api-service", + "description": "Backend API", + "type": "local", + "created": "2026-02-08T12:46:00Z" + }, + "paths": { + "root": "/repos/api-service", + "data_dir": "/repos/api-service/.cleveragents" + }, + "defaults": { + "sandbox": "git_worktree", + "validations": 0, + "context_filters": null, + "automation_profile": null + }, + "resources": { + "total": 0, + "indexed": 0, + "sandboxable": 0 + } + }, + "timing": { "duration_ms": 85 }, + "messages": [{ "level": "ok", "text": "Project created" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project create --description "Backend API" local/api-service + status: ok + exit_code: 0 + data: + project: + name: local/api-service + description: Backend API + type: local + created: "2026-02-08T12:46:00Z" + paths: + root: /repos/api-service + data_dir: /repos/api-service/.cleveragents + defaults: + sandbox: git_worktree + validations: 0 + context_filters: null + automation_profile: null + resources: + total: 0 + indexed: 0 + sandboxable: 0 + timing: + duration_ms: 85 + messages: + - level: ok + text: 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/web-db \
-  --invariant "All components must have unit tests" \
-  --invariant "CSS must pass stylelint checks" \
-  --invariant-actor local/invariant-resolver \
-  local/web-app
+=== "Rich"
 
-╭─ Project Created ─────────────────────╮
-│ Name: local/web-app                   │
-│ Description: Frontend web app         │
-│ Remote: no                            │
-╰───────────────────────────────────────╯
+    

+    $ agents project create -d "Frontend web application" \
+      --resource local/web-repo --resource local/web-db \
+      --invariant "All components must have unit tests" \
+      --invariant "CSS must pass stylelint checks" \
+      --invariant-actor local/invariant-resolver \
+      local/web-app
 
-╭─ Linked Resources ───────────────────────────────────────╮
-│ Name               Type          Read-Only               │
-│ ─────────────────  ──────────────  ─────────             │
-│ local/web-repo     git-checkout    no                   │
-│ local/web-db       local/database  no                   │
-╰──────────────────────────────────────────────────────────╯
+    ╭─ Project Created ─────────────────────╮
+    │ Name: local/web-app                   │
+    │ Description: Frontend web app         │
+    │ Remote: no                            │
+    ╰───────────────────────────────────────╯
 
-╭─ Invariants ────────────────────────────────────╮
-│ 1. All components must have unit tests          │
-│ 2. CSS must pass stylelint checks               │
-│ Reconciliation Actor: local/invariant-resolver  │
-╰─────────────────────────────────────────────────╯
+    ╭─ Linked Resources ───────────────────────────────────────╮
+    │ Name               Type          Read-Only               │
+    │ ─────────────────  ──────────────  ─────────             │
+    │ local/web-repo     git-checkout    no                   │
+    │ local/web-db       local/database  no                   │
+    ╰──────────────────────────────────────────────────────────╯
 
-✓ OK Project created
-

+    ╭─ Invariants ────────────────────────────────────╮
+    │ 1. All components must have unit tests          │
+    │ 2. CSS must pass stylelint checks               │
+    │ Reconciliation Actor: local/invariant-resolver  │
+    ╰─────────────────────────────────────────────────╯
+
+    ✓ OK Project created
+
+ +=== "Plain" + + ``` + $ agents project create -d "Frontend web application" \ + --resource local/web-repo --resource local/web-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 + Description: Frontend web app + Remote: no + + Linked Resources + Name Type Read-Only + ----------------- -------------- --------- + local/web-repo git-checkout no + local/web-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 + ``` + +=== "JSON" + + ```json + { + "command": "agents project create -d \"Frontend web application\" --resource local/web-repo --resource local/web-db --invariant \"All components must have unit tests\" --invariant \"CSS must pass stylelint checks\" --invariant-actor local/invariant-resolver local/web-app", + "status": "ok", + "exit_code": 0, + "data": { + "project": { + "name": "local/web-app", + "description": "Frontend web app", + "remote": false + }, + "linked_resources": [ + { "name": "local/web-repo", "type": "git-checkout", "read_only": false }, + { "name": "local/web-db", "type": "local/database", "read_only": false } + ], + "invariants": { + "items": [ + "All components must have unit tests", + "CSS must pass stylelint checks" + ], + "reconciliation_actor": "local/invariant-resolver" + } + }, + "timing": { "duration_ms": 120 }, + "messages": [{ "level": "ok", "text": "Project created" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project create -d "Frontend web application" --resource local/web-repo --resource local/web-db --invariant "All components must have unit tests" --invariant "CSS must pass stylelint checks" --invariant-actor local/invariant-resolver local/web-app + status: ok + exit_code: 0 + data: + project: + name: local/web-app + description: Frontend web app + remote: false + linked_resources: + - name: local/web-repo + type: git-checkout + read_only: false + - name: local/web-db + type: local/database + read_only: false + invariants: + items: + - All components must have unit tests + - CSS must pass stylelint checks + reconciliation_actor: local/invariant-resolver + timing: + duration_ms: 120 + messages: + - level: ok + text: Project created + ``` ##### agents project link-resource @@ -953,32 +2786,119 @@ Link a registered resource to a project. The resource must already be registered **Examples** -

-$ agents resource add git-checkout local/api-repo --path /repos/api --branch main
-$ agents project link-resource local/api-service local/api-repo
+=== "Rich"
 
-╭─ Resource Linked ───────────────────────╮
-│ Project: local/api-service              │
-│ Resource: local/api-repo                │
-│ Type: git-checkout                      │
-│ Read-Only: no                           │
-╰─────────────────────────────────────────╯
+    

+    $ agents resource add git-checkout local/api-repo --path /repos/api --branch main
+    $ agents project link-resource local/api-service local/api-repo
 
-╭─ Access ─────────────────╮
-│ Read: allowed            │
-│ Write: allowed           │
-│ Apply: requires approval │
-╰──────────────────────────╯
+    ╭─ Resource Linked ───────────────────────╮
+    │ Project: local/api-service              │
+    │ Resource: local/api-repo                │
+    │ Type: git-checkout                      │
+    │ Read-Only: no                           │
+    ╰─────────────────────────────────────────╯
 
-╭─ Indexing ─────────────────────╮
-│ Status: indexing...            │
-│ Files Found: 347               │
-│ Language: Python (primary)     │
-│ Estimated Time: ~20 seconds    │
-╰────────────────────────────────╯
+    ╭─ Access ─────────────────╮
+    │ Read: allowed            │
+    │ Write: allowed           │
+    │ Apply: requires approval │
+    ╰──────────────────────────╯
 
-✓ OK Resource linked to project
-

+    ╭─ Indexing ─────────────────────╮
+    │ Status: indexing...            │
+    │ Files Found: 347               │
+    │ Language: Python (primary)     │
+    │ Estimated Time: ~20 seconds    │
+    ╰────────────────────────────────╯
+
+    ✓ OK Resource linked to project
+
+ +=== "Plain" + + ``` + $ 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 + + Access + Read: allowed + Write: allowed + Apply: requires approval + + Indexing + Status: indexing... + Files Found: 347 + Language: Python (primary) + Estimated Time: ~20 seconds + + [OK] Resource linked to project + ``` + +=== "JSON" + + ```json + { + "command": "agents project link-resource local/api-service local/api-repo", + "status": "ok", + "exit_code": 0, + "data": { + "resource_linked": { + "project": "local/api-service", + "resource": "local/api-repo", + "type": "git-checkout", + "read_only": false + }, + "access": { + "read": "allowed", + "write": "allowed", + "apply": "requires approval" + }, + "indexing": { + "status": "indexing", + "files_found": 347, + "language": "Python (primary)", + "estimated_time_seconds": 20 + } + }, + "timing": { "duration_ms": 92 }, + "messages": [{ "level": "ok", "text": "Resource linked to project" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project link-resource local/api-service local/api-repo + status: ok + exit_code: 0 + data: + resource_linked: + project: local/api-service + resource: local/api-repo + type: git-checkout + read_only: false + access: + read: allowed + write: allowed + apply: requires approval + indexing: + status: indexing + files_found: 347 + language: Python (primary) + estimated_time_seconds: 20 + timing: + duration_ms: 92 + messages: + - level: ok + text: Resource linked to project + ``` ##### agents project unlink-resource @@ -995,32 +2915,117 @@ Unlink a resource from a project. The resource itself remains registered in the **Examples** -

-$ agents project unlink-resource local/api-service local/api-repo
+=== "Rich"
 
-Unlink local/api-repo from local/api-service? [y/N]: y
+    

+    $ agents project unlink-resource local/api-service local/api-repo
 
-╭─ Resource Unlinked ─────────────────────────────────╮
-│ Project: local/api-service                          │
-│ Resource: local/api-repo                            │
-│ Type: git-checkout                                  │
-╰─────────────────────────────────────────────────────╯
+    Unlink local/api-repo from local/api-service? [y/N]: y
 
-╭─ Index Cleanup ──────────╮
-│ Text Index: 347 removed  │
-│ Vectors: 892 removed     │
-│ Graph Triples: cleared   │
-│ Duration: 0.3s           │
-╰──────────────────────────╯
+    ╭─ Resource Unlinked ─────────────────────────────────╮
+    │ Project: local/api-service                          │
+    │ Resource: local/api-repo                            │
+    │ Type: git-checkout                                  │
+    ╰─────────────────────────────────────────────────────╯
 
-╭─ Project Summary ──────────────╮
-│ Linked Resources: 1 remaining  │
-│ Last Updated: 2026-02-09 10:30 │
-│ Active Plans: 0                │
-╰────────────────────────────────╯
+    ╭─ Index Cleanup ──────────╮
+    │ Text Index: 347 removed  │
+    │ Vectors: 892 removed     │
+    │ Graph Triples: cleared   │
+    │ Duration: 0.3s           │
+    ╰──────────────────────────╯
 
-✓ OK Resource unlinked from project
-

+    ╭─ Project Summary ──────────────╮
+    │ Linked Resources: 1 remaining  │
+    │ Last Updated: 2026-02-09 10:30 │
+    │ Active Plans: 0                │
+    ╰────────────────────────────────╯
+
+    ✓ OK Resource unlinked from project
+
+ +=== "Plain" + + ``` + $ 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 + + Index Cleanup + 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 + + [OK] Resource unlinked from project + ``` + +=== "JSON" + + ```json + { + "command": "agents project unlink-resource local/api-service local/api-repo", + "status": "ok", + "exit_code": 0, + "data": { + "resource_unlinked": { + "project": "local/api-service", + "resource": "local/api-repo", + "type": "git-checkout" + }, + "index_cleanup": { + "text_index": "347 removed", + "vectors": "892 removed", + "graph_triples": "cleared", + "duration_seconds": 0.3 + }, + "project_summary": { + "linked_resources": 1, + "last_updated": "2026-02-09T10:30:00Z", + "active_plans": 0 + } + }, + "timing": { "duration_ms": 340 }, + "messages": [{ "level": "ok", "text": "Resource unlinked from project" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project unlink-resource local/api-service local/api-repo + status: ok + exit_code: 0 + data: + resource_unlinked: + project: local/api-service + resource: local/api-repo + type: git-checkout + index_cleanup: + text_index: 347 removed + vectors: 892 removed + graph_triples: cleared + duration_seconds: 0.3 + project_summary: + linked_resources: 1 + last_updated: "2026-02-09T10:30:00Z" + active_plans: 0 + timing: + duration_ms: 340 + messages: + - level: ok + text: Resource unlinked from project + ``` ##### agents project list @@ -1035,27 +3040,107 @@ List projects with optional filters. **Examples** -

-$ agents --format table project list
+=== "Rich"
 
-╭─ Projects ────────────────────────────────────────────────────╮
-│ Name               Resources  Remote  Active Plans            │
-│ ─────────────────  ─────────  ──────  ────────────            │
-│ local/api-service  2          No      1                       │
-│ local/docs         1          No      0                       │
-╰───────────────────────────────────────────────────────────────╯
+    

+    $ agents --format table project list
 
-╭─ Summary ──────────────────╮
-│ Total: 2                   │
-│ With Resources: 2          │
-│ Remote: 0                  │
-│ Total Resources: 3         │
-│ Indexed Files: 1,247       │
-│ Active Plans: 1            │
-╰────────────────────────────╯
+    ╭─ Projects ────────────────────────────────────────────────────╮
+    │ Name               Resources  Remote  Active Plans            │
+    │ ─────────────────  ─────────  ──────  ────────────            │
+    │ local/api-service  2          No      1                       │
+    │ local/docs         1          No      0                       │
+    ╰───────────────────────────────────────────────────────────────╯
 
-✓ OK 2 projects listed
-

+    ╭─ Summary ──────────────────╮
+    │ Total: 2                   │
+    │ With Resources: 2          │
+    │ Remote: 0                  │
+    │ Total Resources: 3         │
+    │ Indexed Files: 1,247       │
+    │ Active Plans: 1            │
+    ╰────────────────────────────╯
+
+    ✓ OK 2 projects listed
+
+ +=== "Plain" + + ``` + $ agents --format table project list + + Projects + Name Resources Remote Active Plans + ----------------- --------- ------ ------------ + local/api-service 2 No 1 + local/docs 1 No 0 + + Summary + Total: 2 + With Resources: 2 + Remote: 0 + Total Resources: 3 + Indexed Files: 1,247 + Active Plans: 1 + + [OK] 2 projects listed + ``` + +=== "JSON" + + ```json + { + "command": "agents --format table project list", + "status": "ok", + "exit_code": 0, + "data": { + "projects": [ + { "name": "local/api-service", "resources": 2, "remote": false, "active_plans": 1 }, + { "name": "local/docs", "resources": 1, "remote": false, "active_plans": 0 } + ], + "summary": { + "total": 2, + "with_resources": 2, + "remote": 0, + "total_resources": 3, + "indexed_files": 1247, + "active_plans": 1 + } + }, + "timing": { "duration_ms": 45 }, + "messages": [{ "level": "ok", "text": "2 projects listed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents --format table project list + status: ok + exit_code: 0 + data: + projects: + - name: local/api-service + resources: 2 + remote: false + active_plans: 1 + - name: local/docs + resources: 1 + remote: false + active_plans: 0 + summary: + total: 2 + with_resources: 2 + remote: 0 + total_resources: 3 + indexed_files: 1247 + active_plans: 1 + timing: + duration_ms: 45 + messages: + - level: ok + text: 2 projects listed + ``` ##### agents project show @@ -1070,55 +3155,233 @@ Show full project details. **Examples** -

-$ agents project show local/api-service
+=== "Rich"
 
-╭─ Project Details ──────────────╮
-│ Name: local/api-service        │
-│ Description: Backend API       │
-│ Resources: 2                   │
-│ Remote: no                     │
-│ Created: 2026-02-08 12:46      │
-╰────────────────────────────────╯
+    

+    $ agents project show local/api-service
 
-╭─ Linked Resources ──────────────────────────────────────────────────────╮
-│ Resource          Type            Sandbox              Read-Only        │
-│ ────────────────  ──────────────  ────────────────────  ─────────       │
-│ local/api-repo   git-checkout    git_worktree         no                │
-│ local/staging-db local/database  transaction_rollback yes               │
-╰─────────────────────────────────────────────────────────────────────────╯
+    ╭─ Project Details ──────────────╮
+    │ Name: local/api-service        │
+    │ Description: Backend API       │
+    │ Resources: 2                   │
+    │ Remote: no                     │
+    │ Created: 2026-02-08 12:46      │
+    ╰────────────────────────────────╯
 
-╭─ Validations (3) ──────────────────────────────────────────────────────────────────╮
-│ local/run-tests          Run unit tests with coverage    required                │
-│   resource: local/api-repo  scope: project  (attachment: 01HXM5A1B2C3D4E5F6G7…)│
-│ local/lint-check         Lint check                     required                │
-│   resource: local/api-repo  scope: direct (always active)  (attachment: 01HXM5…)│
-│ local/check-bundle-size  Check bundle size (advisory)   info                    │
-│   resource: local/api-repo  scope: project  (attachment: 01HXM5D4E5F6G7H8J9…)│
-╰───────────────────────────────────────────────────────────────────────────────────╯
+    ╭─ Linked Resources ──────────────────────────────────────────────────────╮
+    │ Resource          Type            Sandbox              Read-Only        │
+    │ ────────────────  ──────────────  ────────────────────  ─────────       │
+    │ local/api-repo   git-checkout    git_worktree         no                │
+    │ local/staging-db local/database  transaction_rollback yes               │
+    ╰─────────────────────────────────────────────────────────────────────────╯
 
-╭─ Context ───────────────────╮
-│ Include: repo               │
-│ Exclude: **/node_modules/** │
-│ Max File Size: 1 MB         │
-╰─────────────────────────────╯
+    ╭─ Validations (3) ──────────────────────────────────────────────────────────────────╮
+    │ local/run-tests          Run unit tests with coverage    required                │
+    │   resource: local/api-repo  scope: project  (attachment: 01HXM5A1B2C3D4E5F6G7…)│
+    │ local/lint-check         Lint check                     required                │
+    │   resource: local/api-repo  scope: direct (always active)  (attachment: 01HXM5…)│
+    │ local/check-bundle-size  Check bundle size (advisory)   info                    │
+    │   resource: local/api-repo  scope: project  (attachment: 01HXM5D4E5F6G7H8J9…)│
+    ╰───────────────────────────────────────────────────────────────────────────────────╯
 
-╭─ Indexing Status ──────────╮
-│ Text Index: ready          │
-│ Vector Index: ready        │
-│ Graph Store: disabled      │
-│ Indexed Files: 347         │
-│ Last Indexed: 12:48        │
-╰────────────────────────────╯
+    ╭─ Context ───────────────────╮
+    │ Include: repo               │
+    │ Exclude: **/node_modules/** │
+    │ Max File Size: 1 MB         │
+    ╰─────────────────────────────╯
 
-╭─ Active Plans ──────────────────────────╮
-│ Plan ID   Action               Phase    │
-│ ────────  ───────────────────  ───────  │
-│ 01HXM7A9  local/code-coverage  execute  │
-╰─────────────────────────────────────────╯
+    ╭─ Indexing Status ──────────╮
+    │ Text Index: ready          │
+    │ Vector Index: ready        │
+    │ Graph Store: disabled      │
+    │ Indexed Files: 347         │
+    │ Last Indexed: 12:48        │
+    ╰────────────────────────────╯
 
-✓ OK Project loaded
-

+    ╭─ Active Plans ──────────────────────────╮
+    │ Plan ID   Action               Phase    │
+    │ ────────  ───────────────────  ───────  │
+    │ 01HXM7A9  local/code-coverage  execute  │
+    ╰─────────────────────────────────────────╯
+
+    ✓ OK Project loaded
+
+ +=== "Plain" + + ``` + $ agents project show local/api-service + + Project Details + Name: local/api-service + 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) + local/run-tests Run unit tests with coverage required + resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7...) + local/lint-check Lint check required + resource: local/api-repo scope: direct (always active) (attachment: 01HXM5...) + local/check-bundle-size Check bundle size (advisory) info + resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9...) + + 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 + ``` + +=== "JSON" + + ```json + { + "command": "agents project show local/api-service", + "status": "ok", + "exit_code": 0, + "data": { + "project": { + "name": "local/api-service", + "description": "Backend API", + "resources": 2, + "remote": false, + "created": "2026-02-08T12:46:00Z" + }, + "linked_resources": [ + { "name": "local/api-repo", "type": "git-checkout", "sandbox": "git_worktree", "read_only": false }, + { "name": "local/staging-db", "type": "local/database", "sandbox": "transaction_rollback", "read_only": true } + ], + "validations": [ + { + "name": "local/run-tests", + "description": "Run unit tests with coverage", + "mode": "required", + "resource": "local/api-repo", + "scope": "project", + "attachment_id": "01HXM5A1B2C3D4E5F6G7" + }, + { + "name": "local/lint-check", + "description": "Lint check", + "mode": "required", + "resource": "local/api-repo", + "scope": "direct", + "attachment_id": "01HXM5" + }, + { + "name": "local/check-bundle-size", + "description": "Check bundle size (advisory)", + "mode": "informational", + "resource": "local/api-repo", + "scope": "project", + "attachment_id": "01HXM5D4E5F6G7H8J9" + } + ], + "context": { + "include": ["repo"], + "exclude": ["**/node_modules/**"], + "max_file_size_bytes": 1048576 + }, + "indexing_status": { + "text_index": "ready", + "vector_index": "ready", + "graph_store": "disabled", + "indexed_files": 347, + "last_indexed": "12:48" + }, + "active_plans": [ + { "plan_id": "01HXM7A9", "action": "local/code-coverage", "phase": "execute" } + ] + }, + "timing": { "duration_ms": 62 }, + "messages": [{ "level": "ok", "text": "Project loaded" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project show local/api-service + status: ok + exit_code: 0 + data: + project: + name: local/api-service + description: Backend API + resources: 2 + remote: false + created: "2026-02-08T12:46:00Z" + linked_resources: + - name: local/api-repo + type: git-checkout + sandbox: git_worktree + read_only: false + - name: local/staging-db + type: local/database + sandbox: transaction_rollback + read_only: true + validations: + - name: local/run-tests + description: Run unit tests with coverage + mode: required + resource: local/api-repo + scope: project + attachment_id: 01HXM5A1B2C3D4E5F6G7 + - name: local/lint-check + description: Lint check + mode: required + resource: local/api-repo + scope: direct + attachment_id: 01HXM5 + - name: local/check-bundle-size + description: Check bundle size (advisory) + mode: informational + resource: local/api-repo + scope: project + attachment_id: 01HXM5D4E5F6G7H8J9 + context: + include: + - repo + exclude: + - "**/node_modules/**" + max_file_size_bytes: 1048576 + indexing_status: + text_index: ready + vector_index: ready + graph_store: disabled + indexed_files: 347 + last_indexed: "12:48" + active_plans: + - plan_id: 01HXM7A9 + action: local/code-coverage + phase: execute + timing: + duration_ms: 62 + messages: + - level: ok + text: Project loaded + ``` ##### agents project validations @@ -1130,6 +3393,10 @@ See: [agents validation](#agents-validation) for full details on creating, manag 
agents project delete [--force|-f] [--yes|-y] <NAME>
+!!! warning "Irreversible Action" + + Deleting a project ==cannot be undone==. All resource links, validation attachments, and context policies will be removed. The resources themselves remain in the Resource Registry. Use `--force` to also cancel active plans targeting this project. + **Purpose** Delete a project and unlink all associated resources. The resources themselves remain in the Resource Registry. @@ -1141,75 +3408,305 @@ Delete a project and unlink all associated resources. The resources themselves r **Examples** -

-$ agents project delete local/docs
+=== "Rich"
 
-Delete project local/docs? This cannot be undone. [y/N]: y
+    

+    $ agents project delete local/docs
 
-╭─ Deletion Summary ──────────────────╮
-│ Project: local/docs                 │
-│ Resources: 1 unlinked               │
-│ Data Dir: /repos/docs/.cleveragents │
-╰─────────────────────────────────────╯
+    Delete project local/docs? This cannot be undone. [y/N]: y
 
-╭─ Index Cleanup ────────╮
-│ Text Index: cleared    │
-│ Vectors: 240 removed   │
-│ Graph Triples: none    │
-│ Storage Freed: 12 MB   │
-╰────────────────────────╯
+    ╭─ Deletion Summary ──────────────────╮
+    │ Project: local/docs                 │
+    │ Resources: 1 unlinked               │
+    │ Data Dir: /repos/docs/.cleveragents │
+    ╰─────────────────────────────────────╯
 
-╭─ Backups ────────────────────────────────────╮
-│ Snapshot: /backups/local-docs-2026-02-08.tgz │
-│ Retention: 7 days                            │
-╰──────────────────────────────────────────────╯
+    ╭─ Index Cleanup ────────╮
+    │ Text Index: cleared    │
+    │ Vectors: 240 removed   │
+    │ Graph Triples: none    │
+    │ Storage Freed: 12 MB   │
+    ╰────────────────────────╯
 
-✓ OK Project deleted
-

+    ╭─ Backups ────────────────────────────────────╮
+    │ Snapshot: /backups/local-docs-2026-02-08.tgz │
+    │ Retention: 7 days                            │
+    ╰──────────────────────────────────────────────╯
+
+    ✓ OK Project deleted
+
+ +=== "Plain" + + ``` + $ agents project delete local/docs + + Delete project local/docs? This cannot be undone. [y/N]: y + + Deletion Summary + Project: local/docs + Resources: 1 unlinked + Data Dir: /repos/docs/.cleveragents + + Index Cleanup + Text Index: cleared + Vectors: 240 removed + Graph Triples: none + Storage Freed: 12 MB + + Backups + Snapshot: /backups/local-docs-2026-02-08.tgz + Retention: 7 days + + [OK] Project deleted + ``` + +=== "JSON" + + ```json + { + "command": "agents project delete local/docs", + "status": "ok", + "exit_code": 0, + "data": { + "deletion_summary": { + "project": "local/docs", + "resources_unlinked": 1, + "data_dir": "/repos/docs/.cleveragents" + }, + "index_cleanup": { + "text_index": "cleared", + "vectors": "240 removed", + "graph_triples": "none", + "storage_freed_mb": 12 + }, + "backups": { + "snapshot": "/backups/local-docs-2026-02-08.tgz", + "retention_days": 7 + } + }, + "timing": { "duration_ms": 530 }, + "messages": [{ "level": "ok", "text": "Project deleted" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project delete local/docs + status: ok + exit_code: 0 + data: + deletion_summary: + project: local/docs + resources_unlinked: 1 + data_dir: /repos/docs/.cleveragents + index_cleanup: + text_index: cleared + vectors: 240 removed + graph_triples: none + storage_freed_mb: 12 + backups: + snapshot: /backups/local-docs-2026-02-08.tgz + retention_days: 7 + timing: + duration_ms: 530 + messages: + - level: ok + text: Project deleted + ``` Attempting to delete a project that has active plans (without `--force`): -

-$ agents project delete local/api-service
+=== "Rich"
 
-Delete project local/api-service? [y/N]: y
+    

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

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "agents project delete local/api-service", + "status": "error", + "exit_code": 1, + "data": { + "delete_blocked": { + "reason": "project has active plans", + "active_plans": [ + { "plan_id": "01HXM7A9", "phase": "execute/processing", "action": "local/code-coverage" }, + { "plan_id": "01HXM4J1", "phase": "strategize/processing", "action": "local/refactor-api" } + ] + }, + "resolution": [ + "Cancel or complete active plans first", + "Use --force to cancel all active plans and delete the project" + ] + }, + "timing": { "duration_ms": 38 }, + "messages": [{ "level": "error", "text": "Delete blocked — 2 active plans" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project delete local/api-service + status: error + exit_code: 1 + data: + delete_blocked: + reason: project has active plans + active_plans: + - plan_id: 01HXM7A9 + phase: execute/processing + action: local/code-coverage + - plan_id: 01HXM4J1 + phase: strategize/processing + action: local/refactor-api + resolution: + - Cancel or complete active plans first + - Use --force to cancel all active plans and delete the project + timing: + duration_ms: 38 + messages: + - level: error + text: "Delete blocked \u2014 2 active plans" + ``` Force-deleting a project with active plans: -

-$ agents project delete --force --yes local/api-service
+=== "Rich"
 
-╭─ Force Delete ─────────────────────────────────────────╮
-│ Cancelling: 2 active plans                             │
-│   01HXM7A9 — cancelled (was execute/processing)        │
-│   01HXM4J1 — cancelled (was strategize/processing)     │
-╰────────────────────────────────────────────────────────╯
+    

+    $ agents project delete --force --yes local/api-service
 
-╭─ Deleted ────────────────────╮
-│ Project: local/api-service   │
-│ Resources Unlinked: 2        │
-│ Validations Detached: 3      │
-│ Plans Cancelled: 2           │
-│ Context Policies: cleared    │
-╰──────────────────────────────╯
+    ╭─ Force Delete ─────────────────────────────────────────╮
+    │ Cancelling: 2 active plans                             │
+    │   01HXM7A9 — cancelled (was execute/processing)        │
+    │   01HXM4J1 — cancelled (was strategize/processing)     │
+    ╰────────────────────────────────────────────────────────╯
 
-✓ OK Project force-deleted
-

+    ╭─ Deleted ────────────────────╮
+    │ Project: local/api-service   │
+    │ Resources Unlinked: 2        │
+    │ Validations Detached: 3      │
+    │ Plans Cancelled: 2           │
+    │ Context Policies: cleared    │
+    ╰──────────────────────────────╯
+
+    ✓ OK Project force-deleted
+
+ +=== "Plain" + + ``` + $ 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 Detached: 3 + Plans Cancelled: 2 + Context Policies: cleared + + [OK] Project force-deleted + ``` + +=== "JSON" + + ```json + { + "command": "agents project delete --force --yes local/api-service", + "status": "ok", + "exit_code": 0, + "data": { + "force_delete": { + "cancelled_plans": [ + { "plan_id": "01HXM7A9", "previous_state": "execute/processing" }, + { "plan_id": "01HXM4J1", "previous_state": "strategize/processing" } + ] + }, + "deleted": { + "project": "local/api-service", + "resources_unlinked": 2, + "validations_detached": 3, + "plans_cancelled": 2, + "context_policies": "cleared" + } + }, + "timing": { "duration_ms": 245 }, + "messages": [{ "level": "ok", "text": "Project force-deleted" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents project delete --force --yes local/api-service + status: ok + exit_code: 0 + data: + force_delete: + cancelled_plans: + - plan_id: 01HXM7A9 + previous_state: execute/processing + - plan_id: 01HXM4J1 + previous_state: strategize/processing + deleted: + project: local/api-service + resources_unlinked: 2 + validations_detached: 3 + plans_cancelled: 2 + context_policies: cleared + timing: + duration_ms: 245 + messages: + - level: ok + text: Project force-deleted + ``` ##### agents project context @@ -1270,41 +3767,150 @@ Set the context policy for a project and (optionally) a specific view. **Examples** -

-$ 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
+=== "Rich"
 
-╭─ Context Policy ────────────╮
-│ Project: local/api-service  │
-│ View: strategize            │
-│ Include: repo               │
-│ Exclude: **/node_modules/** │
-╰─────────────────────────────╯
+    

+    $ 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
 
-╭─ Limits ─────────────────────╮
-│ Hot Tokens: 12000 (soft cap) │
-│ Warm Decisions: 50           │
-│ Cold Decisions: 200          │
-│ Query Limit: 20              │
-│ Max File Size: 1 MB          │
-│ Max Total Size: 50 MB        │
-╰──────────────────────────────╯
+    ╭─ Context Policy ────────────╮
+    │ Project: local/api-service  │
+    │ View: strategize            │
+    │ Include: repo               │
+    │ Exclude: **/node_modules/** │
+    ╰─────────────────────────────╯
 
-╭─ Summarization ─╮
-│ Enabled: yes    │
-│ Max Tokens: 800 │
-╰─────────────────╯
+    ╭─ Limits ─────────────────────╮
+    │ Hot Tokens: 12000 (soft cap) │
+    │ Warm Decisions: 50           │
+    │ Cold Decisions: 200          │
+    │ Query Limit: 20              │
+    │ Max File Size: 1 MB          │
+    │ Max Total Size: 50 MB        │
+    ╰──────────────────────────────╯
 
-╭─ Other Views ────────╮
-│ execute: (default)   │
-│ apply: (default)     │
-│ default: (unset)     │
-╰──────────────────────╯
+    ╭─ Summarization ─╮
+    │ Enabled: yes    │
+    │ Max Tokens: 800 │
+    ╰─────────────────╯
 
-✓ OK Context policy updated
-

+    ╭─ Other Views ────────╮
+    │ execute: (default)   │
+    │ apply: (default)     │
+    │ default: (unset)     │
+    ╰──────────────────────╯
+
+    ✓ OK Context policy updated
+
+ +=== "Plain" + + ``` + $ 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 + Exclude: **/node_modules/** + + Limits + Hot Tokens: 12000 (soft cap) + Warm Decisions: 50 + Cold Decisions: 200 + Query Limit: 20 + Max File Size: 1 MB + Max Total Size: 50 MB + + Summarization + Enabled: yes + Max Tokens: 800 + + Other Views + execute: (default) + apply: (default) + default: (unset) + + [OK] Context policy updated + ``` + +=== "JSON" + + ```json + { + "command": "project context set", + "status": "ok", + "exit_code": 0, + "data": { + "context_policy": { + "project": "local/api-service", + "view": "strategize", + "include_resources": ["repo"], + "exclude_paths": ["**/node_modules/**"] + }, + "limits": { + "hot_max_tokens": 12000, + "warm_max_decisions": 50, + "cold_max_decisions": 200, + "query_limit": 20, + "max_file_size": "1 MB", + "max_total_size": "50 MB" + }, + "summarization": { + "enabled": true, + "max_tokens": 800 + }, + "other_views": { + "execute": "(default)", + "apply": "(default)", + "default": "(unset)" + } + }, + "timing": { + "duration_ms": 42 + }, + "messages": ["Context policy updated"] + } + ``` + +=== "YAML" + + ```yaml + command: project context set + status: ok + exit_code: 0 + data: + context_policy: + project: local/api-service + view: strategize + include_resources: + - repo + exclude_paths: + - "**/node_modules/**" + limits: + hot_max_tokens: 12000 + warm_max_decisions: 50 + cold_max_decisions: 200 + query_limit: 20 + max_file_size: 1 MB + max_total_size: 50 MB + summarization: + enabled: true + max_tokens: 800 + other_views: + execute: (default) + apply: (default) + default: (unset) + timing: + duration_ms: 42 + messages: + - Context policy updated + ``` ###### agents project context show @@ -1321,39 +3927,154 @@ Show the active context policy for a project. **Examples** -

-$ agents project context show --view strategize local/api-service
+=== "Rich"
 
-╭─ Context Policy ────────────╮
-│ Project: local/api-service  │
-│ View: strategize            │
-│ Include: repo               │
-│ Exclude: **/node_modules/** │
-╰─────────────────────────────╯
+    

+    $ agents project context show --view strategize local/api-service
 
-╭─ Limits ─────────────────────╮
-│ Hot Tokens: 12000 (soft cap) │
-│ Warm Decisions: 50           │
-│ Cold Decisions: 200          │
-│ Query Limit: 20              │
-│ Max File Size: 1 MB          │
-│ Max Total Size: 50 MB        │
-╰──────────────────────────────╯
+    ╭─ Context Policy ────────────╮
+    │ Project: local/api-service  │
+    │ View: strategize            │
+    │ Include: repo               │
+    │ Exclude: **/node_modules/** │
+    ╰─────────────────────────────╯
 
-╭─ Summarization ─╮
-│ Enabled: yes    │
-│ Max Tokens: 800 │
-╰─────────────────╯
+    ╭─ Limits ─────────────────────╮
+    │ Hot Tokens: 12000 (soft cap) │
+    │ Warm Decisions: 50           │
+    │ Cold Decisions: 200          │
+    │ Query Limit: 20              │
+    │ Max File Size: 1 MB          │
+    │ Max Total Size: 50 MB        │
+    ╰──────────────────────────────╯
 
-╭─ Current Usage ──────────────╮
-│ Hot Context: 8,420 / 12,000  │
-│ Warm Entries: 12 / 50        │
-│ Cold Entries: 47 / 200       │
-│ Indexed Resources: 1         │
-╰──────────────────────────────╯
+    ╭─ Summarization ─╮
+    │ Enabled: yes    │
+    │ Max Tokens: 800 │
+    ╰─────────────────╯
 
-✓ OK Context policy loaded
-

+    ╭─ Current Usage ──────────────╮
+    │ Hot Context: 8,420 / 12,000  │
+    │ Warm Entries: 12 / 50        │
+    │ Cold Entries: 47 / 200       │
+    │ Indexed Resources: 1         │
+    ╰──────────────────────────────╯
+
+    ✓ OK Context policy loaded
+
+ +=== "Plain" + + ``` + $ agents project context show --view strategize local/api-service + + Context Policy + Project: local/api-service + View: strategize + Include: repo + Exclude: **/node_modules/** + + Limits + Hot Tokens: 12000 (soft cap) + Warm Decisions: 50 + Cold Decisions: 200 + Query Limit: 20 + Max File Size: 1 MB + Max Total Size: 50 MB + + Summarization + Enabled: yes + Max Tokens: 800 + + Current Usage + Hot Context: 8,420 / 12,000 + Warm Entries: 12 / 50 + Cold Entries: 47 / 200 + Indexed Resources: 1 + + [OK] Context policy loaded + ``` + +=== "JSON" + + ```json + { + "command": "project context show", + "status": "ok", + "exit_code": 0, + "data": { + "context_policy": { + "project": "local/api-service", + "view": "strategize", + "include_resources": ["repo"], + "exclude_paths": ["**/node_modules/**"] + }, + "limits": { + "hot_max_tokens": 12000, + "warm_max_decisions": 50, + "cold_max_decisions": 200, + "query_limit": 20, + "max_file_size": "1 MB", + "max_total_size": "50 MB" + }, + "summarization": { + "enabled": true, + "max_tokens": 800 + }, + "current_usage": { + "hot_context_tokens": 8420, + "hot_context_limit": 12000, + "warm_entries": 12, + "warm_limit": 50, + "cold_entries": 47, + "cold_limit": 200, + "indexed_resources": 1 + } + }, + "timing": { + "duration_ms": 38 + }, + "messages": ["Context policy loaded"] + } + ``` + +=== "YAML" + + ```yaml + command: project context show + status: ok + exit_code: 0 + data: + context_policy: + project: local/api-service + view: strategize + include_resources: + - repo + exclude_paths: + - "**/node_modules/**" + limits: + hot_max_tokens: 12000 + warm_max_decisions: 50 + cold_max_decisions: 200 + query_limit: 20 + max_file_size: 1 MB + max_total_size: 50 MB + summarization: + enabled: true + max_tokens: 800 + current_usage: + hot_context_tokens: 8420 + hot_context_limit: 12000 + warm_entries: 12 + warm_limit: 50 + cold_entries: 47 + cold_limit: 200 + indexed_resources: 1 + timing: + duration_ms: 38 + messages: + - Context policy loaded + ``` ###### agents project context inspect @@ -1377,42 +4098,199 @@ Inspect the current state of the ACMS context assembly for a project. Shows the **Examples** -

-$ agents project context inspect --view execute --focus uko-py:module/src.auth --breadth 2 local/api-service
+=== "Rich"
 
-╭─ ACMS Context Inspection ────────────────────────────────────────╮
-│ Project: local/api-service                                      │
-│ View: execute                                                   │
-│ Focus: uko-py:module/src.auth                                   │
-│ Breadth: 2 hops  │  Depth: 3 (MEMBER_SUMMARY)                  │
-╰──────────────────────────────────────────────────────────────────╯
+    

+    $ agents project context inspect --view execute --focus uko-py:module/src.auth --breadth 2 local/api-service
 
-╭─ UKO Graph (2-hop neighborhood) ─────────────────────────────────╮
-│ uko-py:module/src.auth (depth 9/FULL_SOURCE, 1,240 tokens)      │
-│   ├─ contains → uko-py:class/AuthHandler (depth 3, 320 tokens)  │
-│   ├─ contains → uko-py:class/TokenValidator (depth 3, 280 tok)  │
-│   ├─ imports  → uko-py:module/src.db (depth 0, 90 tokens)       │
-│   └─ imports  → uko-py:module/src.config (depth 0, 60 tok)      │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ ACMS Context Inspection ────────────────────────────────────────╮
+    │ Project: local/api-service                                      │
+    │ View: execute                                                   │
+    │ Focus: uko-py:module/src.auth                                   │
+    │ Breadth: 2 hops  │  Depth: 3 (MEMBER_SUMMARY)                  │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-╭─ Active Strategies ──────────────────────────────────────────────╮
-│ breadth-depth-navigator  quality=0.85  budget=45%  4 fragments  │
-│ semantic-embedding       quality=0.60  budget=35%  6 fragments  │
-│ simple-keyword           quality=0.30  budget=20%  3 fragments  │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ UKO Graph (2-hop neighborhood) ─────────────────────────────────╮
+    │ uko-py:module/src.auth (depth 9/FULL_SOURCE, 1,240 tokens)      │
+    │   ├─ contains → uko-py:class/AuthHandler (depth 3, 320 tokens)  │
+    │   ├─ contains → uko-py:class/TokenValidator (depth 3, 280 tok)  │
+    │   ├─ imports  → uko-py:module/src.db (depth 0, 90 tokens)       │
+    │   └─ imports  → uko-py:module/src.config (depth 0, 60 tok)      │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-╭─ Budget ─────────────────────────────╮
-│ Model Window: 128,000 tokens         │
-│ Response Reserve: 4,096 tokens       │
-│ Tool Definitions: 2,400 tokens       │
-│ System Prompt: 1,200 tokens           │
-│ Skeleton Reserve: 18,046 (15%)       │
-│ Available Budget: 102,258 tokens     │
-│ Used: 1,990 / 102,258 (1.9%)         │
-╰──────────────────────────────────────╯
+    ╭─ Active Strategies ──────────────────────────────────────────────╮
+    │ breadth-depth-navigator  quality=0.85  budget=45%  4 fragments  │
+    │ semantic-embedding       quality=0.60  budget=35%  6 fragments  │
+    │ simple-keyword           quality=0.30  budget=20%  3 fragments  │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-✓ OK Context inspection complete
-

+    ╭─ Budget ─────────────────────────────╮
+    │ Model Window: 128,000 tokens         │
+    │ Response Reserve: 4,096 tokens       │
+    │ Tool Definitions: 2,400 tokens       │
+    │ System Prompt: 1,200 tokens           │
+    │ Skeleton Reserve: 18,046 (15%)       │
+    │ Available Budget: 102,258 tokens     │
+    │ Used: 1,990 / 102,258 (1.9%)         │
+    ╰──────────────────────────────────────╯
+
+    ✓ OK Context inspection complete
+
+ +=== "Plain" + + ``` + $ agents project context inspect --view execute --focus uko-py:module/src.auth --breadth 2 local/api-service + + ACMS Context Inspection + Project: local/api-service + View: execute + Focus: uko-py:module/src.auth + Breadth: 2 hops Depth: 3 (MEMBER_SUMMARY) + + UKO Graph (2-hop neighborhood) + uko-py:module/src.auth (depth 9/FULL_SOURCE, 1,240 tokens) + contains -> uko-py:class/AuthHandler (depth 3, 320 tokens) + contains -> uko-py:class/TokenValidator (depth 3, 280 tok) + imports -> uko-py:module/src.db (depth 0, 90 tokens) + imports -> uko-py:module/src.config (depth 0, 60 tok) + + Active Strategies + Strategy Quality Budget Fragments + ------------------------- ------- ------ --------- + breadth-depth-navigator 0.85 45% 4 + semantic-embedding 0.60 35% 6 + simple-keyword 0.30 20% 3 + + Budget + Model Window: 128,000 tokens + Response Reserve: 4,096 tokens + Tool Definitions: 2,400 tokens + System Prompt: 1,200 tokens + Skeleton Reserve: 18,046 (15%) + Available Budget: 102,258 tokens + Used: 1,990 / 102,258 (1.9%) + + [OK] Context inspection complete + ``` + +=== "JSON" + + ```json + { + "command": "project context inspect", + "status": "ok", + "exit_code": 0, + "data": { + "inspection": { + "project": "local/api-service", + "view": "execute", + "focus": ["uko-py:module/src.auth"], + "breadth": 2, + "depth": 3, + "depth_name": "MEMBER_SUMMARY" + }, + "uko_graph": { + "root": "uko-py:module/src.auth", + "root_depth": 9, + "root_depth_name": "FULL_SOURCE", + "root_tokens": 1240, + "edges": [ + { "relation": "contains", "target": "uko-py:class/AuthHandler", "depth": 3, "tokens": 320 }, + { "relation": "contains", "target": "uko-py:class/TokenValidator", "depth": 3, "tokens": 280 }, + { "relation": "imports", "target": "uko-py:module/src.db", "depth": 0, "tokens": 90 }, + { "relation": "imports", "target": "uko-py:module/src.config", "depth": 0, "tokens": 60 } + ] + }, + "active_strategies": [ + { "name": "breadth-depth-navigator", "quality": 0.85, "budget_pct": 0.45, "fragments": 4 }, + { "name": "semantic-embedding", "quality": 0.60, "budget_pct": 0.35, "fragments": 6 }, + { "name": "simple-keyword", "quality": 0.30, "budget_pct": 0.20, "fragments": 3 } + ], + "budget": { + "model_window": 128000, + "response_reserve": 4096, + "tool_definitions": 2400, + "system_prompt": 1200, + "skeleton_reserve": 18046, + "skeleton_ratio": 0.15, + "available_budget": 102258, + "used": 1990, + "utilization": 0.019 + } + }, + "timing": { + "duration_ms": 185 + }, + "messages": ["Context inspection complete"] + } + ``` + +=== "YAML" + + ```yaml + command: project context inspect + status: ok + exit_code: 0 + data: + inspection: + project: local/api-service + view: execute + focus: + - uko-py:module/src.auth + breadth: 2 + depth: 3 + depth_name: MEMBER_SUMMARY + uko_graph: + root: uko-py:module/src.auth + root_depth: 9 + root_depth_name: FULL_SOURCE + root_tokens: 1240 + edges: + - relation: contains + target: uko-py:class/AuthHandler + depth: 3 + tokens: 320 + - relation: contains + target: uko-py:class/TokenValidator + depth: 3 + tokens: 280 + - relation: imports + target: uko-py:module/src.db + depth: 0 + tokens: 90 + - relation: imports + target: uko-py:module/src.config + depth: 0 + tokens: 60 + active_strategies: + - name: breadth-depth-navigator + quality: 0.85 + budget_pct: 0.45 + fragments: 4 + - name: semantic-embedding + quality: 0.60 + budget_pct: 0.35 + fragments: 6 + - name: simple-keyword + quality: 0.30 + budget_pct: 0.20 + fragments: 3 + budget: + model_window: 128000 + response_reserve: 4096 + tool_definitions: 2400 + system_prompt: 1200 + skeleton_reserve: 18046 + skeleton_ratio: 0.15 + available_budget: 102258 + used: 1990 + utilization: 0.019 + timing: + duration_ms: 185 + messages: + - Context inspection complete + ``` ###### agents project context simulate @@ -1435,44 +4313,216 @@ Simulate a context assembly run without invoking an actor. Produces a dry-run re **Examples** -

-$ agents project context simulate --view strategize --budget 16000 \
-    --focus uko-py:module/src.auth --focus uko-py:module/src.db \
-    local/api-service
+=== "Rich"
 
-╭─ ACMS Simulation ────────────────────────────────────────────────╮
-│ Project: local/api-service                                      │
-│ View: strategize                                                │
-│ Budget: 16,000 tokens (override)                               │
-│ Focus: uko-py:module/src.auth, uko-py:module/src.db             │
-╰──────────────────────────────────────────────────────────────────╯
+    

+    $ agents project context simulate --view strategize --budget 16000 \
+        --focus uko-py:module/src.auth --focus uko-py:module/src.db \
+        local/api-service
 
-╭─ Strategy Results ───────────────────────────────────────────────╮
-│ breadth-depth-navigator                                        │
-│   Confidence: 0.85  │  Budget: 7,200 tokens  │  12 fragments    │
-│   Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95)       │
-│        src/db/models.py (depth 3, 480t, score=0.88)             │
-│                                                                  │
-│ semantic-embedding                                             │
-│   Confidence: 0.60  │  Budget: 5,600 tokens  │  8 fragments     │
-│   Top: src/auth/jwt.py (depth 3, 380t, score=0.82)              │
-│        src/middleware/auth_check.py (depth 3, 290t, score=0.79)  │
-│                                                                  │
-│ simple-keyword                                                 │
-│   Confidence: 0.30  │  Budget: 3,200 tokens  │  5 fragments     │
-│   Top: src/auth/utils.py (depth 6, 210t, score=0.71)            │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ ACMS Simulation ────────────────────────────────────────────────╮
+    │ Project: local/api-service                                      │
+    │ View: strategize                                                │
+    │ Budget: 16,000 tokens (override)                               │
+    │ Focus: uko-py:module/src.auth, uko-py:module/src.db             │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-╭─ Fusion Result ──────────────────────────────────────────────────╮
-│ Included: 18 fragments (14,820 tokens, 92.6% of budget)         │
-│ Excluded: 7 fragments (3,200 tokens, below budget cutoff)       │
-│ Deduplicated: 4 fragments merged                               │
-│ Skeleton: 2,400 tokens (15% reserve)                           │
-│ Preamble: 180 tokens                                           │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ Strategy Results ───────────────────────────────────────────────╮
+    │ breadth-depth-navigator                                        │
+    │   Confidence: 0.85  │  Budget: 7,200 tokens  │  12 fragments    │
+    │   Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95)       │
+    │        src/db/models.py (depth 3, 480t, score=0.88)             │
+    │                                                                  │
+    │ semantic-embedding                                             │
+    │   Confidence: 0.60  │  Budget: 5,600 tokens  │  8 fragments     │
+    │   Top: src/auth/jwt.py (depth 3, 380t, score=0.82)              │
+    │        src/middleware/auth_check.py (depth 3, 290t, score=0.79)  │
+    │                                                                  │
+    │ simple-keyword                                                 │
+    │   Confidence: 0.30  │  Budget: 3,200 tokens  │  5 fragments     │
+    │   Top: src/auth/utils.py (depth 6, 210t, score=0.71)            │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-✓ OK Simulation complete (dry run — no context was assembled)
-

+    ╭─ Fusion Result ──────────────────────────────────────────────────╮
+    │ Included: 18 fragments (14,820 tokens, 92.6% of budget)         │
+    │ Excluded: 7 fragments (3,200 tokens, below budget cutoff)       │
+    │ Deduplicated: 4 fragments merged                               │
+    │ Skeleton: 2,400 tokens (15% reserve)                           │
+    │ Preamble: 180 tokens                                           │
+    ╰──────────────────────────────────────────────────────────────────╯
+
+    ✓ OK Simulation complete (dry run — no context was assembled)
+
+ +=== "Plain" + + ``` + $ agents project context simulate --view strategize --budget 16000 \ + --focus uko-py:module/src.auth --focus uko-py:module/src.db \ + local/api-service + + ACMS Simulation + Project: local/api-service + View: strategize + Budget: 16,000 tokens (override) + Focus: uko-py:module/src.auth, uko-py:module/src.db + + Strategy Results + breadth-depth-navigator + Confidence: 0.85 Budget: 7,200 tokens 12 fragments + Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95) + src/db/models.py (depth 3, 480t, score=0.88) + + semantic-embedding + Confidence: 0.60 Budget: 5,600 tokens 8 fragments + Top: src/auth/jwt.py (depth 3, 380t, score=0.82) + src/middleware/auth_check.py (depth 3, 290t, score=0.79) + + simple-keyword + Confidence: 0.30 Budget: 3,200 tokens 5 fragments + Top: src/auth/utils.py (depth 6, 210t, score=0.71) + + Fusion Result + Included: 18 fragments (14,820 tokens, 92.6% of budget) + Excluded: 7 fragments (3,200 tokens, below budget cutoff) + Deduplicated: 4 fragments merged + Skeleton: 2,400 tokens (15% reserve) + Preamble: 180 tokens + + [OK] Simulation complete (dry run -- no context was assembled) + ``` + +=== "JSON" + + ```json + { + "command": "project context simulate", + "status": "ok", + "exit_code": 0, + "data": { + "simulation": { + "project": "local/api-service", + "view": "strategize", + "budget": 16000, + "budget_source": "override", + "focus": ["uko-py:module/src.auth", "uko-py:module/src.db"] + }, + "strategy_results": [ + { + "name": "breadth-depth-navigator", + "confidence": 0.85, + "budget_tokens": 7200, + "fragments": 12, + "top": [ + { "path": "src/auth/__init__.py", "depth": 9, "tokens": 1240, "score": 0.95 }, + { "path": "src/db/models.py", "depth": 3, "tokens": 480, "score": 0.88 } + ] + }, + { + "name": "semantic-embedding", + "confidence": 0.60, + "budget_tokens": 5600, + "fragments": 8, + "top": [ + { "path": "src/auth/jwt.py", "depth": 3, "tokens": 380, "score": 0.82 }, + { "path": "src/middleware/auth_check.py", "depth": 3, "tokens": 290, "score": 0.79 } + ] + }, + { + "name": "simple-keyword", + "confidence": 0.30, + "budget_tokens": 3200, + "fragments": 5, + "top": [ + { "path": "src/auth/utils.py", "depth": 6, "tokens": 210, "score": 0.71 } + ] + } + ], + "fusion_result": { + "included_fragments": 18, + "included_tokens": 14820, + "budget_utilization": 0.926, + "excluded_fragments": 7, + "excluded_tokens": 3200, + "deduplicated_fragments": 4, + "skeleton_tokens": 2400, + "skeleton_ratio": 0.15, + "preamble_tokens": 180 + } + }, + "timing": { + "duration_ms": 310 + }, + "messages": ["Simulation complete (dry run -- no context was assembled)"] + } + ``` + +=== "YAML" + + ```yaml + command: project context simulate + status: ok + exit_code: 0 + data: + simulation: + project: local/api-service + view: strategize + budget: 16000 + budget_source: override + focus: + - uko-py:module/src.auth + - uko-py:module/src.db + strategy_results: + - name: breadth-depth-navigator + confidence: 0.85 + budget_tokens: 7200 + fragments: 12 + top: + - path: src/auth/__init__.py + depth: 9 + tokens: 1240 + score: 0.95 + - path: src/db/models.py + depth: 3 + tokens: 480 + score: 0.88 + - name: semantic-embedding + confidence: 0.60 + budget_tokens: 5600 + fragments: 8 + top: + - path: src/auth/jwt.py + depth: 3 + tokens: 380 + score: 0.82 + - path: src/middleware/auth_check.py + depth: 3 + tokens: 290 + score: 0.79 + - name: simple-keyword + confidence: 0.30 + budget_tokens: 3200 + fragments: 5 + top: + - path: src/auth/utils.py + depth: 6 + tokens: 210 + score: 0.71 + fusion_result: + included_fragments: 18 + included_tokens: 14820 + budget_utilization: 0.926 + excluded_fragments: 7 + excluded_tokens: 3200 + deduplicated_fragments: 4 + skeleton_tokens: 2400 + skeleton_ratio: 0.15 + preamble_tokens: 180 + timing: + duration_ms: 310 + messages: + - "Simulation complete (dry run -- no context was assembled)" + ``` #### agents actor @@ -1506,86 +4556,354 @@ Run a named actor in isolation with simple, manual context. **Examples** -

-$ agents actor run --context docs local/code_reader "Summarize the README"
+=== "Rich"
 
-╭─ Run Summary ─────────────────╮
-│ Actor: local/code_reader      │
-│ Context: docs                 │
-│ Temperature: 0.2              │
-│ Provider: anthropic           │
-│ Model: claude-3.5             │
-╰───────────────────────────────╯
+    

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

+    ╭─ Result Metrics ───────╮
+    │ Output: stdout         │
+    │ Input Tokens: 1,524    │
+    │ Output Tokens: 842     │
+    │ Duration: 1.8s         │
+    │ Cost: $0.0021          │
+    │ Tool Calls: 0          │
+    ╰────────────────────────╯
+
+    ✓ OK Summary generated
+
+ +=== "Plain" + + ``` + $ agents actor run --context docs local/code_reader "Summarize the README" + + 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 + + Result Metrics + Output: stdout + Input Tokens: 1,524 + Output Tokens: 842 + Duration: 1.8s + Cost: $0.0021 + Tool Calls: 0 + + [OK] Summary generated + ``` + +=== "JSON" + + ```json + { + "command": "agents actor run --context docs local/code_reader \"Summarize the README\"", + "status": "ok", + "exit_code": 0, + "data": { + "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" + }, + "result_metrics": { + "output": "stdout", + "input_tokens": 1524, + "output_tokens": 842, + "duration_s": 1.8, + "cost": "$0.0021", + "tool_calls": 0 + } + }, + "timing": { + "duration_ms": 1800 + }, + "messages": [ + { "level": "ok", "text": "Summary generated" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor run --context docs local/code_reader "Summarize the README" + status: ok + exit_code: 0 + data: + 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 + result_metrics: + output: stdout + input_tokens: 1524 + output_tokens: 842 + duration_s: 1.8 + cost: "$0.0021" + tool_calls: 0 + timing: + duration_ms: 1800 + messages: + - level: ok + text: 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"
+=== "Rich"
 
-╭─ Actor Run ─────────────────────────╮
-│ Actor: local/reviewer               │
-│ Type: agent                         │
-│ Temperature: 0.2                    │
-│ Skill: local/code-analysis          │
-╰─────────────────────────────────────╯
+    

+    $ agents actor run --temperature 0.2 --skill local/code-analysis \
+      local/reviewer "Review the auth module for security issues"
 
-╭─ 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.                   │
-╰───────────────────────────────────────────────────────────────────╯
+    ╭─ Actor Run ─────────────────────────╮
+    │ Actor: local/reviewer               │
+    │ Type: agent                         │
+    │ Temperature: 0.2                    │
+    │ Skill: local/code-analysis          │
+    ╰─────────────────────────────────────╯
 
-╭─ Usage ──────────────╮
-│ Tokens: 2,840        │
-│ Duration: 4.2s       │
-│ Cost: $0.009         │
-│ Tool Calls: 6        │
-╰──────────────────────╯
+    ╭─ 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.                   │
+    ╰───────────────────────────────────────────────────────────────────╯
 
-✓ OK Actor run completed
-

+    ╭─ Usage ──────────────╮
+    │ Tokens: 2,840        │
+    │ Duration: 4.2s       │
+    │ Cost: $0.009         │
+    │ Tool Calls: 6        │
+    ╰──────────────────────╯
+
+    ✓ OK Actor run completed
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "agents actor run --temperature 0.2 --skill local/code-analysis local/reviewer \"Review the auth module for security issues\"", + "status": "ok", + "exit_code": 0, + "data": { + "actor_run": { + "actor": "local/reviewer", + "type": "agent", + "temperature": 0.2, + "skill": "local/code-analysis" + }, + "response": { + "text": "I identified 3 potential security concerns in the auth module:\n\n1. 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.\n\n2. Missing rate limiting on the /auth/refresh endpoint. An attacker could brute-force refresh tokens.\n\n3. Low severity: Password hashing uses bcrypt with cost=10. Consider cost=12 for production deployments.", + "issues_found": 3 + }, + "usage": { + "tokens": 2840, + "duration_s": 4.2, + "cost": "$0.009", + "tool_calls": 6 + } + }, + "timing": { + "duration_ms": 4200 + }, + "messages": [ + { "level": "ok", "text": "Actor run completed" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: >- + agents actor run --temperature 0.2 --skill local/code-analysis + local/reviewer "Review the auth module for security issues" + status: ok + exit_code: 0 + data: + actor_run: + actor: local/reviewer + type: agent + temperature: 0.2 + skill: local/code-analysis + response: + text: >- + 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. + issues_found: 3 + usage: + tokens: 2840 + duration_s: 4.2 + cost: "$0.009" + tool_calls: 6 + timing: + duration_ms: 4200 + messages: + - level: ok + text: Actor run completed + ``` Saving actor output to a file: -

-$ agents actor run --output review.md local/reviewer "Write a code review report"
+=== "Rich"
 
-╭─ Actor Run ───────────────╮
-│ Actor: local/reviewer     │
-│ Output: review.md         │
-│ Tokens: 4,120             │
-│ Duration: 6.8s            │
-╰───────────────────────────╯
+    

+    $ agents actor run --output review.md local/reviewer "Write a code review report"
 
-✓ OK Output written to review.md (2.4 KB)
-

+    ╭─ Actor Run ───────────────╮
+    │ Actor: local/reviewer     │
+    │ Output: review.md         │
+    │ Tokens: 4,120             │
+    │ Duration: 6.8s            │
+    ╰───────────────────────────╯
+
+    ✓ OK Output written to review.md (2.4 KB)
+
+ +=== "Plain" + + ``` + $ 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) + ``` + +=== "JSON" + + ```json + { + "command": "agents actor run --output review.md local/reviewer \"Write a code review report\"", + "status": "ok", + "exit_code": 0, + "data": { + "actor_run": { + "actor": "local/reviewer", + "output": "review.md", + "tokens": 4120, + "duration_s": 6.8 + } + }, + "timing": { + "duration_ms": 6800 + }, + "messages": [ + { "level": "ok", "text": "Output written to review.md (2.4 KB)" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor run --output review.md local/reviewer "Write a code review report" + status: ok + exit_code: 0 + data: + actor_run: + actor: local/reviewer + output: review.md + tokens: 4120 + duration_s: 6.8 + timing: + duration_ms: 6800 + messages: + - level: ok + text: Output written to review.md (2.4 KB) + ``` ##### agents actor add @@ -1601,83 +4919,330 @@ Add a new actor configuration, or replace an existing one with `--update`. The a **Examples** -

-$ agents actor add --config ./actors/reviewer.yaml
+=== "Rich"
 
-╭─ Actor Added ────────╮
-│ Name: local/reviewer │
-│ Provider: openai     │
-│ Model: gpt-4         │
-│ Default: yes         │
-│ Unsafe: no           │
-│ Type: graph          │
-╰──────────────────────╯
+    

+    $ agents actor add --config ./actors/reviewer.yaml
 
-╭─ Config ─────────────────────╮
-│ Path: ./actors/reviewer.yaml │
-│ Hash: 8b3f3d2                │
-│ Options: 4                   │
-│ Nodes: 3                     │
-│ Edges: 4                     │
-╰──────────────────────────────╯
+    ╭─ Actor Added ────────╮
+    │ Name: local/reviewer │
+    │ Provider: openai     │
+    │ Model: gpt-4         │
+    │ Default: yes         │
+    │ Unsafe: no           │
+    │ Type: graph          │
+    ╰──────────────────────╯
 
-╭─ Capabilities ───────╮
-│ - code review        │
-│ - diff summarization │
-│ - lint guidance      │
-╰──────────────────────╯
+    ╭─ Config ─────────────────────╮
+    │ Path: ./actors/reviewer.yaml │
+    │ Hash: 8b3f3d2                │
+    │ Options: 4                   │
+    │ Nodes: 3                     │
+    │ Edges: 4                     │
+    ╰──────────────────────────────╯
 
-╭─ Tools ────────────────────────╮
-│ Tool          Read-Only  Safe  │
-│ ────────────  ─────────  ────  │
-│ read_file     yes        yes   │
-│ search_files  yes        yes   │
-│ git_diff      yes        yes   │
-╰────────────────────────────────╯
+    ╭─ Capabilities ───────╮
+    │ - code review        │
+    │ - diff summarization │
+    │ - lint guidance      │
+    ╰──────────────────────╯
 
-✓ OK Actor added
-

+    ╭─ Tools ────────────────────────╮
+    │ Tool          Read-Only  Safe  │
+    │ ────────────  ─────────  ────  │
+    │ read_file     yes        yes   │
+    │ search_files  yes        yes   │
+    │ git_diff      yes        yes   │
+    ╰────────────────────────────────╯
+
+    ✓ OK Actor added
+
+ +=== "Plain" + + ``` + $ agents actor add --config ./actors/reviewer.yaml + + Actor Added + Name: local/reviewer + Provider: openai + Model: gpt-4 + Default: yes + Unsafe: no + Type: graph + + Config + Path: ./actors/reviewer.yaml + Hash: 8b3f3d2 + Options: 4 + Nodes: 3 + Edges: 4 + + Capabilities + - code review + - diff summarization + - lint guidance + + Tools + Tool Read-Only Safe + ------------ --------- ---- + read_file yes yes + search_files yes yes + git_diff yes yes + + [OK] Actor added + ``` + +=== "JSON" + + ```json + { + "command": "agents actor add --config ./actors/reviewer.yaml", + "status": "ok", + "exit_code": 0, + "data": { + "actor_added": { + "name": "local/reviewer", + "provider": "openai", + "model": "gpt-4", + "default": true, + "unsafe": false, + "type": "graph" + }, + "config": { + "path": "./actors/reviewer.yaml", + "hash": "8b3f3d2", + "options": 4, + "nodes": 3, + "edges": 4 + }, + "capabilities": [ + "code review", + "diff summarization", + "lint guidance" + ], + "tools": [ + { "tool": "read_file", "read_only": true, "safe": true }, + { "tool": "search_files", "read_only": true, "safe": true }, + { "tool": "git_diff", "read_only": true, "safe": true } + ] + }, + "timing": { + "duration_ms": 95 + }, + "messages": [ + { "level": "ok", "text": "Actor added" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor add --config ./actors/reviewer.yaml + status: ok + exit_code: 0 + data: + actor_added: + name: local/reviewer + provider: openai + model: gpt-4 + default: true + unsafe: false + type: graph + config: + path: ./actors/reviewer.yaml + hash: 8b3f3d2 + options: 4 + nodes: 3 + edges: 4 + capabilities: + - code review + - diff summarization + - lint guidance + tools: + - tool: read_file + read_only: true + safe: true + - tool: search_files + read_only: true + safe: true + - tool: git_diff + read_only: true + safe: true + timing: + duration_ms: 95 + messages: + - level: ok + text: Actor added + ``` Attempting to register an actor that already exists (without `--update`): -

-$ agents actor add --config ./actors/reviewer.yaml
+=== "Rich"
 
-╭─ Error ─────────────────────────────────────────────────╮
-│ Actor already exists: local/reviewer                    │
-│ Registered: 2026-02-07 14:22                            │
-│ Use --update to replace the existing actor definition.  │
-╰─────────────────────────────────────────────────────────╯
+    

+    $ agents actor add --config ./actors/reviewer.yaml
 
-✗ ERROR Actor already registered — use --update to replace
-

+    ╭─ Error ─────────────────────────────────────────────────╮
+    │ Actor already exists: local/reviewer                    │
+    │ Registered: 2026-02-07 14:22                            │
+    │ Use --update to replace the existing actor definition.  │
+    ╰─────────────────────────────────────────────────────────╯
+
+    ✗ ERROR Actor already registered — use --update to replace
+
+ +=== "Plain" + + ``` + $ agents actor add --config ./actors/reviewer.yaml + + Error + Actor already exists: local/reviewer + Registered: 2026-02-07 14:22 + Use --update to replace the existing actor definition. + + [ERROR] Actor already registered -- use --update to replace + ``` + +=== "JSON" + + ```json + { + "command": "agents actor add --config ./actors/reviewer.yaml", + "status": "error", + "exit_code": 1, + "data": { + "error": { + "message": "Actor already exists: local/reviewer", + "registered": "2026-02-07T14:22:00Z", + "hint": "Use --update to replace the existing actor definition." + } + }, + "timing": { + "duration_ms": 42 + }, + "messages": [ + { "level": "error", "text": "Actor already registered -- use --update to replace" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor add --config ./actors/reviewer.yaml + status: error + exit_code: 1 + data: + error: + message: "Actor already exists: local/reviewer" + registered: "2026-02-07T14:22:00Z" + hint: Use --update to replace the existing actor definition. + timing: + duration_ms: 42 + messages: + - level: error + text: Actor already registered -- use --update to replace + ``` Updating an existing actor with `--update`: -

-$ agents actor add --config ./actors/reviewer.yaml --update
+=== "Rich"
 
-╭─ Actor Updated ─────────────────────╮
-│ Name: local/reviewer                │
-│ Type: agent                         │
-│ Status: updated                     │
-╰─────────────────────────────────────╯
+    

+    $ agents actor add --config ./actors/reviewer.yaml --update
 
-╭─ Changes ────────────────────────────╮
-│ Skills: +1 (local/code-analysis)     │
-│ Model: unchanged                     │
-│ Graph: updated                       │
-╰──────────────────────────────────────╯
+    ╭─ Actor Updated ─────────────────────╮
+    │ Name: local/reviewer                │
+    │ Type: agent                         │
+    │ Status: updated                     │
+    ╰─────────────────────────────────────╯
 
-✓ OK Actor updated
-

+    ╭─ Changes ────────────────────────────╮
+    │ Skills: +1 (local/code-analysis)     │
+    │ Model: unchanged                     │
+    │ Graph: updated                       │
+    ╰──────────────────────────────────────╯
+
+    ✓ OK Actor updated
+
+ +=== "Plain" + + ``` + $ agents actor add --config ./actors/reviewer.yaml --update + + Actor Updated + Name: local/reviewer + Type: agent + Status: updated + + Changes + Skills: +1 (local/code-analysis) + Model: unchanged + Graph: updated + + [OK] Actor updated + ``` + +=== "JSON" + + ```json + { + "command": "agents actor add --config ./actors/reviewer.yaml --update", + "status": "ok", + "exit_code": 0, + "data": { + "actor_updated": { + "name": "local/reviewer", + "type": "agent", + "status": "updated" + }, + "changes": { + "skills": "+1 (local/code-analysis)", + "model": "unchanged", + "graph": "updated" + } + }, + "timing": { + "duration_ms": 88 + }, + "messages": [ + { "level": "ok", "text": "Actor updated" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor add --config ./actors/reviewer.yaml --update + status: ok + exit_code: 0 + data: + actor_updated: + name: local/reviewer + type: agent + status: updated + changes: + skills: "+1 (local/code-analysis)" + model: unchanged + graph: updated + timing: + duration_ms: 88 + messages: + - level: ok + text: Actor updated + ``` ##### agents actor remove 
agents actor remove <NAME>
-**Purpose** -Remove a custom actor. +!!! warning "Destructive Operation" + Removes a custom actor registration. Active plans and actions referencing this actor will lose their actor binding. Check the **Impact** section in the output to verify no active plans or sessions are affected. **Arguments** @@ -1685,28 +5250,109 @@ Remove a custom actor. **Examples** -

-$ agents actor remove local/reviewer
+=== "Rich"
 
-╭─ Actor Removed ──────╮
-│ Name: local/reviewer │
-│ Provider: openai     │
-│ Model: gpt-4         │
-╰──────────────────────╯
+    

+    $ agents actor remove local/reviewer
 
-╭─ Impact ───────────────────────────────────╮
-│ Sessions: 0 affected                       │
-│ Active Plans: 0 affected                   │
-│ Actions Referencing: 0                     │
-╰────────────────────────────────────────────╯
+    ╭─ Actor Removed ──────╮
+    │ Name: local/reviewer │
+    │ Provider: openai     │
+    │ Model: gpt-4         │
+    ╰──────────────────────╯
 
-╭─ Cleanup ──────────────╮
-│ Config: kept on disk   │
-│ Contexts: 1 orphaned   │
-╰────────────────────────╯
+    ╭─ Impact ───────────────────────────────────╮
+    │ Sessions: 0 affected                       │
+    │ Active Plans: 0 affected                   │
+    │ Actions Referencing: 0                     │
+    ╰────────────────────────────────────────────╯
 
-✓ OK Actor removed
-

+    ╭─ Cleanup ──────────────╮
+    │ Config: kept on disk   │
+    │ Contexts: 1 orphaned   │
+    ╰────────────────────────╯
+
+    ✓ OK Actor removed
+
+ +=== "Plain" + + ``` + $ agents actor remove local/reviewer + + Actor Removed + Name: local/reviewer + Provider: openai + Model: gpt-4 + + Impact + Sessions: 0 affected + Active Plans: 0 affected + Actions Referencing: 0 + + Cleanup + Config: kept on disk + Contexts: 1 orphaned + + [OK] Actor removed + ``` + +=== "JSON" + + ```json + { + "command": "agents actor remove local/reviewer", + "status": "ok", + "exit_code": 0, + "data": { + "actor_removed": { + "name": "local/reviewer", + "provider": "openai", + "model": "gpt-4" + }, + "impact": { + "sessions": 0, + "active_plans": 0, + "actions_referencing": 0 + }, + "cleanup": { + "config": "kept on disk", + "contexts": "1 orphaned" + } + }, + "timing": { + "duration_ms": 65 + }, + "messages": [ + { "level": "ok", "text": "Actor removed" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor remove local/reviewer + status: ok + exit_code: 0 + data: + actor_removed: + name: local/reviewer + provider: openai + model: gpt-4 + impact: + sessions: 0 + active_plans: 0 + actions_referencing: 0 + cleanup: + config: kept on disk + contexts: 1 orphaned + timing: + duration_ms: 65 + messages: + - level: ok + text: Actor removed + ``` ##### agents actor list @@ -1721,27 +5367,141 @@ None. **Examples** -

-$ agents actor list
+=== "Rich"
 
-╭─ 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          │
-╰───────────────────────────────────────────────────────────────────────╯
+    

+    $ agents actor list
 
-╭─ Summary ──────────────╮
-│ Total: 3               │
-│ Built-in: 2            │
-│ Custom: 1              │
-│ Unsafe: 0              │
-│ Providers Used: 2      │
-╰────────────────────────╯
+    ╭─ 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          │
+    ╰───────────────────────────────────────────────────────────────────────╯
 
-✓ OK 3 actors listed
-

+    ╭─ Summary ──────────────╮
+    │ Total: 3               │
+    │ Built-in: 2            │
+    │ Custom: 1              │
+    │ Unsafe: 0              │
+    │ Providers Used: 2      │
+    ╰────────────────────────╯
+
+    ✓ OK 3 actors listed
+
+ +=== "Plain" + + ``` + $ agents actor list + + Actors + Name Provider Model Default Built-in Unsafe + -------------- --------- ---------- ------- -------- ------ + local/reviewer openai gpt-4 yes no + openai/gpt-4 openai gpt-4 yes no + anthropic/3.5 anthropic claude-3.5 yes no + + Summary + Total: 3 + Built-in: 2 + Custom: 1 + Unsafe: 0 + Providers Used: 2 + + [OK] 3 actors listed + ``` + +=== "JSON" + + ```json + { + "command": "agents actor list", + "status": "ok", + "exit_code": 0, + "data": { + "actors": [ + { + "name": "local/reviewer", + "provider": "openai", + "model": "gpt-4", + "default": true, + "builtin": false, + "unsafe": false + }, + { + "name": "openai/gpt-4", + "provider": "openai", + "model": "gpt-4", + "default": false, + "builtin": true, + "unsafe": false + }, + { + "name": "anthropic/3.5", + "provider": "anthropic", + "model": "claude-3.5", + "default": false, + "builtin": true, + "unsafe": false + } + ], + "summary": { + "total": 3, + "builtin": 2, + "custom": 1, + "unsafe": 0, + "providers_used": 2 + } + }, + "timing": { + "duration_ms": 55 + }, + "messages": [ + { "level": "ok", "text": "3 actors listed" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor list + status: ok + exit_code: 0 + data: + actors: + - name: local/reviewer + provider: openai + model: gpt-4 + default: true + builtin: false + unsafe: false + - name: openai/gpt-4 + provider: openai + model: gpt-4 + default: false + builtin: true + unsafe: false + - name: anthropic/3.5 + provider: anthropic + model: claude-3.5 + default: false + builtin: true + unsafe: false + summary: + total: 3 + builtin: 2 + custom: 1 + unsafe: 0 + providers_used: 2 + timing: + duration_ms: 55 + messages: + - level: ok + text: 3 actors listed + ``` ##### agents actor show @@ -1756,59 +5516,223 @@ Show details for a single actor. **Examples** -

-$ agents actor show local/reviewer
+=== "Rich"
 
-╭─ Actor Details ────────────────────╮
-│ Name: local/reviewer               │
-│ 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               │
-╰────────────────────────────────────╯
+    

+    $ agents actor show local/reviewer
 
-╭─ Options ──────────╮
-│ - temperature: 0.2 │
-│ - max_tokens: 2048 │
-│ - top_p: 1.0       │
-╰────────────────────╯
+    ╭─ Actor Details ────────────────────╮
+    │ Name: local/reviewer               │
+    │ 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               │
+    ╰────────────────────────────────────╯
 
-╭─ Graph Structure ─╮
-│ Nodes: 3          │
-│ Edges: 4          │
-│ Entry: analyze    │
-│ Exit: report      │
-╰───────────────────╯
+    ╭─ Options ──────────╮
+    │ - temperature: 0.2 │
+    │ - max_tokens: 2048 │
+    │ - top_p: 1.0       │
+    ╰────────────────────╯
 
-╭─ Tools ────────────────────────╮
-│ Tool          Read-Only  Safe  │
-│ ────────────  ─────────  ────  │
-│ read_file     yes        yes   │
-│ search_files  yes        yes   │
-│ git_diff      yes        yes   │
-╰────────────────────────────────╯
+    ╭─ Graph Structure ─╮
+    │ Nodes: 3          │
+    │ Edges: 4          │
+    │ Entry: analyze    │
+    │ Exit: report      │
+    ╰───────────────────╯
 
-╭─ Access ────────────╮
-│ Unsafe: no          │
-│ Filesystem: allowed │
-│ Network: restricted │
-╰─────────────────────╯
+    ╭─ Tools ────────────────────────╮
+    │ Tool          Read-Only  Safe  │
+    │ ────────────  ─────────  ────  │
+    │ read_file     yes        yes   │
+    │ search_files  yes        yes   │
+    │ git_diff      yes        yes   │
+    ╰────────────────────────────────╯
 
-╭─ Usage ─────────────────────────────────────────╮
-│ Referenced by Actions: 1 (local/code-coverage)  │
-│ Active in Sessions: 0                           │
-│ Total Runs: 14                                  │
-│ Avg Cost/Run: $0.0032                           │
-╰─────────────────────────────────────────────────╯
+    ╭─ Access ────────────╮
+    │ Unsafe: no          │
+    │ Filesystem: allowed │
+    │ Network: restricted │
+    ╰─────────────────────╯
 
-✓ OK Actor loaded
-

+    ╭─ Usage ─────────────────────────────────────────╮
+    │ Referenced by Actions: 1 (local/code-coverage)  │
+    │ Active in Sessions: 0                           │
+    │ Total Runs: 14                                  │
+    │ Avg Cost/Run: $0.0032                           │
+    ╰─────────────────────────────────────────────────╯
+
+    ✓ OK Actor loaded
+
+ +=== "Plain" + + ``` + $ agents actor show local/reviewer + + Actor Details + Name: local/reviewer + 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 + + Options + - temperature: 0.2 + - max_tokens: 2048 + - top_p: 1.0 + + Graph Structure + 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 + + Access + 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 + + [OK] Actor loaded + ``` + +=== "JSON" + + ```json + { + "command": "agents actor show local/reviewer", + "status": "ok", + "exit_code": 0, + "data": { + "actor_details": { + "name": "local/reviewer", + "provider": "openai", + "model": "gpt-4", + "default": true, + "builtin": false, + "unsafe": false, + "type": "graph", + "created": "2026-02-08T12:35:00Z", + "updated": "2026-02-08T12:40:00Z", + "config": "./actors/reviewer.yaml", + "config_hash": "9c4e2a1" + }, + "options": { + "temperature": 0.2, + "max_tokens": 2048, + "top_p": 1.0 + }, + "graph_structure": { + "nodes": 3, + "edges": 4, + "entry": "analyze", + "exit": "report" + }, + "tools": [ + { "tool": "read_file", "read_only": true, "safe": true }, + { "tool": "search_files", "read_only": true, "safe": true }, + { "tool": "git_diff", "read_only": true, "safe": true } + ], + "access": { + "unsafe": false, + "filesystem": "allowed", + "network": "restricted" + }, + "usage": { + "referenced_by_actions": "1 (local/code-coverage)", + "active_in_sessions": 0, + "total_runs": 14, + "avg_cost_per_run": "$0.0032" + } + }, + "timing": { + "duration_ms": 78 + }, + "messages": [ + { "level": "ok", "text": "Actor loaded" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor show local/reviewer + status: ok + exit_code: 0 + data: + actor_details: + name: local/reviewer + provider: openai + model: gpt-4 + default: true + builtin: false + unsafe: false + type: graph + created: "2026-02-08T12:35:00Z" + updated: "2026-02-08T12:40:00Z" + config: ./actors/reviewer.yaml + config_hash: 9c4e2a1 + options: + temperature: 0.2 + max_tokens: 2048 + top_p: 1.0 + graph_structure: + nodes: 3 + edges: 4 + entry: analyze + exit: report + tools: + - tool: read_file + read_only: true + safe: true + - tool: search_files + read_only: true + safe: true + - tool: git_diff + read_only: true + safe: true + access: + unsafe: false + filesystem: allowed + network: restricted + usage: + referenced_by_actions: 1 (local/code-coverage) + active_in_sessions: 0 + total_runs: 14 + avg_cost_per_run: "$0.0032" + timing: + duration_ms: 78 + messages: + - level: ok + text: Actor loaded + ``` ##### agents actor context @@ -1819,8 +5743,8 @@ Manage manual context for actor runs. These commands mirror the legacy context b 
agents actor context remove [--yes|-y] (--all|-a|<NAME>)
-**Purpose** -Remove files or directories from an actor context. +!!! warning "Context Data Loss" + Remove files or directories from an actor context. Use `--all` to clear all contexts at once. Context data is not recoverable after removal. **Arguments** @@ -1830,21 +5754,81 @@ Remove files or directories from an actor context. **Examples** -

-$ agents actor context remove docs
+=== "Rich"
 
-╭─ Context Removed ───────────╮
-│ Context: docs               │
-│ Status: removed             │
-╰─────────────────────────────╯
+    

+    $ agents actor context remove docs
 
-╭─ Stats ───────────────────╮
-│ Remaining Size: 48 KB     │
-│ Updated: 2026-02-08 13:06 │
-╰───────────────────────────╯
+    ╭─ Context Removed ───────────╮
+    │ Context: docs               │
+    │ Status: removed             │
+    ╰─────────────────────────────╯
 
-✓ OK Context updated
-

+    ╭─ Stats ───────────────────╮
+    │ Remaining Size: 48 KB     │
+    │ Updated: 2026-02-08 13:06 │
+    ╰───────────────────────────╯
+
+    ✓ OK Context updated
+
+ +=== "Plain" + + ``` + $ agents actor context remove docs + + Context Removed + Context: docs + Status: removed + + Stats + Remaining Size: 48 KB + Updated: 2026-02-08 13:06 + + [OK] Context updated + ``` + +=== "JSON" + + ```json + { + "command": "agents actor context remove docs", + "status": "ok", + "exit_code": 0, + "data": { + "context_removed": { + "context": "docs", + "status": "removed" + }, + "stats": { + "remaining_size_kb": 48, + "updated": "2026-02-08T13:06:00Z" + } + }, + "timing": { "duration_ms": 65 }, + "messages": [{ "level": "ok", "text": "Context updated" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor context remove docs + status: ok + exit_code: 0 + data: + context_removed: + context: docs + status: removed + stats: + remaining_size_kb: 48 + updated: "2026-02-08T13:06:00Z" + timing: + duration_ms: 65 + messages: + - level: ok + text: Context updated + ``` ###### agents actor context list @@ -1859,26 +5843,107 @@ List files stored in an actor context. **Examples** -

-$ agents actor context list docs
+=== "Rich"
 
-╭─ Context Files ──────────────────────────────╮
-│ 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 │
-╰──────────────────────────────────────────────╯
+    

+    $ agents actor context list docs
 
-╭─ Stats ───────────────────────╮
-│ Total Files: 3                │
-│ Total Size: 26.5 KB           │
-│ Estimated Tokens: ~6,600      │
-│ Languages: Markdown           │
-╰───────────────────────────────╯
+    ╭─ Context Files ──────────────────────────────╮
+    │ 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 │
+    ╰──────────────────────────────────────────────╯
 
-✓ OK 3 files listed
-

+    ╭─ Stats ───────────────────────╮
+    │ Total Files: 3                │
+    │ Total Size: 26.5 KB           │
+    │ Estimated Tokens: ~6,600      │
+    │ Languages: Markdown           │
+    ╰───────────────────────────────╯
+
+    ✓ OK 3 files listed
+
+ +=== "Plain" + + ``` + $ agents actor context list docs + + Context Files + 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 + + [OK] 3 files listed + ``` + +=== "JSON" + + ```json + { + "command": "agents actor context list docs", + "status": "ok", + "exit_code": 0, + "data": { + "context_files": [ + { "name": "README.md", "type": "file", "size_kb": 4.2, "added": "2026-02-08T12:10:00Z" }, + { "name": "docs/overview.md", "type": "file", "size_kb": 12.8, "added": "2026-02-08T12:10:00Z" }, + { "name": "docs/cli.md", "type": "file", "size_kb": 9.5, "added": "2026-02-08T12:10:00Z" } + ], + "stats": { + "total_files": 3, + "total_size_kb": 26.5, + "estimated_tokens": 6600, + "languages": ["Markdown"] + } + }, + "timing": { "duration_ms": 35 }, + "messages": [{ "level": "ok", "text": "3 files listed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor context list docs + status: ok + exit_code: 0 + data: + context_files: + - name: README.md + type: file + size_kb: 4.2 + added: "2026-02-08T12:10:00Z" + - name: docs/overview.md + type: file + size_kb: 12.8 + added: "2026-02-08T12:10:00Z" + - name: docs/cli.md + type: file + size_kb: 9.5 + added: "2026-02-08T12:10:00Z" + stats: + total_files: 3 + total_size_kb: 26.5 + estimated_tokens: 6600 + languages: + - Markdown + timing: + duration_ms: 35 + messages: + - level: ok + text: 3 files listed + ``` ###### agents actor context show @@ -1893,19 +5958,77 @@ Show content of a file in an actor context. **Examples** -

-$ agents actor context show docs
+=== "Rich"
 
-╭─ Context Summary ───────────╮
-│ Context: docs               │
-│ Files: 3                    │
-│ Total Size: 26.5 KB         │
-│ Estimated Tokens: ~6,600    │
-│ Created: 2026-02-08 12:10   │
-╰─────────────────────────────╯
+    

+    $ agents actor context show docs
 
-✓ OK Context displayed
-

+    ╭─ Context Summary ───────────╮
+    │ Context: docs               │
+    │ Files: 3                    │
+    │ Total Size: 26.5 KB         │
+    │ Estimated Tokens: ~6,600    │
+    │ Created: 2026-02-08 12:10   │
+    ╰─────────────────────────────╯
+
+    ✓ OK Context displayed
+
+ +=== "Plain" + + ``` + $ agents actor context show docs + + Context Summary + Context: docs + Files: 3 + Total Size: 26.5 KB + Estimated Tokens: ~6,600 + Created: 2026-02-08 12:10 + + [OK] Context displayed + ``` + +=== "JSON" + + ```json + { + "command": "agents actor context show docs", + "status": "ok", + "exit_code": 0, + "data": { + "context_summary": { + "context": "docs", + "files": 3, + "total_size_kb": 26.5, + "estimated_tokens": 6600, + "created": "2026-02-08T12:10:00Z" + } + }, + "timing": { "duration_ms": 45 }, + "messages": [{ "level": "ok", "text": "Context displayed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor context show docs + status: ok + exit_code: 0 + data: + context_summary: + context: docs + files: 3 + total_size_kb: 26.5 + estimated_tokens: 6600 + created: "2026-02-08T12:10:00Z" + timing: + duration_ms: 45 + messages: + - level: ok + text: Context displayed + ``` ###### agents actor context export @@ -1921,23 +6044,89 @@ Export a context as JSON. **Examples** -

-$ agents actor context export --output /tmp/docs-context.json docs
+=== "Rich"
 
-╭─ Context Export ───────────────╮
-│ Context: docs                  │
-│ Output: /tmp/docs-context.json │
-│ Items: 12                      │
-│ Size: 48 KB                    │
-╰────────────────────────────────╯
+    

+    $ agents actor context export --output /tmp/docs-context.json docs
 
-╭─ Integrity ──────────────────╮
-│ Checksum: sha256:19b2...a7d0 │
-│ Compressed: no               │
-╰──────────────────────────────╯
+    ╭─ Context Export ───────────────╮
+    │ Context: docs                  │
+    │ Output: /tmp/docs-context.json │
+    │ Items: 12                      │
+    │ Size: 48 KB                    │
+    ╰────────────────────────────────╯
 
-✓ OK Export completed
-

+    ╭─ Integrity ──────────────────╮
+    │ Checksum: sha256:19b2...a7d0 │
+    │ Compressed: no               │
+    ╰──────────────────────────────╯
+
+    ✓ OK Export completed
+
+ +=== "Plain" + + ``` + $ agents actor context export --output /tmp/docs-context.json docs + + Context Export + Context: docs + Output: /tmp/docs-context.json + Items: 12 + Size: 48 KB + + Integrity + Checksum: sha256:19b2...a7d0 + Compressed: no + + [OK] Export completed + ``` + +=== "JSON" + + ```json + { + "command": "agents actor context export --output /tmp/docs-context.json docs", + "status": "ok", + "exit_code": 0, + "data": { + "context_export": { + "context": "docs", + "output": "/tmp/docs-context.json", + "items": 12, + "size_kb": 48 + }, + "integrity": { + "checksum": "sha256:19b2...a7d0", + "compressed": false + } + }, + "timing": { "duration_ms": 180 }, + "messages": [{ "level": "ok", "text": "Export completed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor context export --output /tmp/docs-context.json docs + status: ok + exit_code: 0 + data: + context_export: + context: docs + output: /tmp/docs-context.json + items: 12 + size_kb: 48 + integrity: + checksum: "sha256:19b2...a7d0" + compressed: false + timing: + duration_ms: 180 + messages: + - level: ok + text: Export completed + ``` ###### agents actor context import @@ -1954,22 +6143,85 @@ Import a context from JSON. **Examples** -

-$ agents actor context import --input /tmp/docs-context.json docs
+=== "Rich"
 
-╭─ Context Import ──────────────╮
-│ Context: docs                 │
-│ Input: /tmp/docs-context.json │
-│ Items: 12                     │
-╰───────────────────────────────╯
+    

+    $ agents actor context import --input /tmp/docs-context.json docs
 
-╭─ Merge ───────────╮
-│ Strategy: replace │
-│ Conflicts: 0      │
-╰───────────────────╯
+    ╭─ Context Import ──────────────╮
+    │ Context: docs                 │
+    │ Input: /tmp/docs-context.json │
+    │ Items: 12                     │
+    ╰───────────────────────────────╯
 
-✓ OK Import completed
-

+    ╭─ Merge ───────────╮
+    │ Strategy: replace │
+    │ Conflicts: 0      │
+    ╰───────────────────╯
+
+    ✓ OK Import completed
+
+ +=== "Plain" + + ``` + $ agents actor context import --input /tmp/docs-context.json docs + + Context Import + Context: docs + Input: /tmp/docs-context.json + Items: 12 + + Merge + Strategy: replace + Conflicts: 0 + + [OK] Import completed + ``` + +=== "JSON" + + ```json + { + "command": "agents actor context import --input /tmp/docs-context.json docs", + "status": "ok", + "exit_code": 0, + "data": { + "context_import": { + "context": "docs", + "input": "/tmp/docs-context.json", + "items": 12 + }, + "merge": { + "strategy": "replace", + "conflicts": 0 + } + }, + "timing": { "duration_ms": 210 }, + "messages": [{ "level": "ok", "text": "Import completed" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor context import --input /tmp/docs-context.json docs + status: ok + exit_code: 0 + data: + context_import: + context: docs + input: /tmp/docs-context.json + items: 12 + merge: + strategy: replace + conflicts: 0 + timing: + duration_ms: 210 + messages: + - level: ok + text: Import completed + ``` ###### agents actor context clear @@ -1986,29 +6238,95 @@ Clear all files from a context but keep the context itself. **Examples** -

-$ agents actor context clear docs
+=== "Rich"
 
-Clear context docs? [y/N]: y
+    

+    $ agents actor context clear docs
 
-╭─ Context Cleared ────╮
-│ Context: docs        │
-│ Items: 12 removed    │
-│ Storage: 48 KB freed │
-╰──────────────────────╯
+    Clear context docs? [y/N]: y
 
-╭─ Retention ────────╮
-│ Context: preserved │
-│ Files: removed     │
-╰────────────────────╯
+    ╭─ Context Cleared ────╮
+    │ Context: docs        │
+    │ Items: 12 removed    │
+    │ Storage: 48 KB freed │
+    ╰──────────────────────╯
 
-✓ OK Context cleared
-

+    ╭─ Retention ────────╮
+    │ Context: preserved │
+    │ Files: removed     │
+    ╰────────────────────╯
+
+    ✓ OK Context cleared
+
+ +=== "Plain" + + ``` + $ agents actor context clear docs + + Clear context docs? [y/N]: y + + Context Cleared + Context: docs + Items: 12 removed + Storage: 48 KB freed + + Retention + Context: preserved + Files: removed + + [OK] Context cleared + ``` + +=== "JSON" + + ```json + { + "command": "agents actor context clear docs", + "status": "ok", + "exit_code": 0, + "data": { + "context_cleared": { + "context": "docs", + "items": "12 removed", + "storage": "48 KB freed" + }, + "retention": { + "context": "preserved", + "files": "removed" + } + }, + "timing": { "duration_ms": 85 }, + "messages": [{ "level": "ok", "text": "Context cleared" }] + } + ``` + +=== "YAML" + + ```yaml + command: agents actor context clear docs + status: ok + exit_code: 0 + data: + context_cleared: + context: docs + items: 12 removed + storage: 48 KB freed + retention: + context: preserved + files: removed + timing: + duration_ms: 85 + messages: + - level: ok + text: Context cleared + ``` #### agents skill -**Purpose** -Manage skills — reusable, namespaced collections of tools. Skills are defined in their own YAML configuration files and registered in the system through these commands. Once registered, skills can be referenced by actors. +!!! info "Purpose" + + Manage skills — reusable, namespaced collections of tools. Skills are defined in their own YAML configuration files and registered in the system through these commands. Once registered, skills can be referenced by actors. ##### agents skill add @@ -2026,87 +6344,356 @@ Register a new skill. The skill is fully defined by the YAML configuration file Registering a new skill: -

-$ agents skill add --config ./skills/devops-toolkit.yaml
+=== "Rich"
 
-╭─ Skill Registered ────────────────────────╮
-│ Name: local/devops-toolkit                │
-│ Description: Full-stack development tools │
-│ Config: ./skills/devops-toolkit.yaml      │
-│ Created: 2026-02-08 13:10                 │
-╰───────────────────────────────────────────╯
+    

+    $ agents skill add --config ./skills/devops-toolkit.yaml
 
-╭─ Includes ────────────────────╮
-│ local/file-ops (registered)   │
-│ local/git-ops (registered)    │
-│ local/github (registered)     │
-╰───────────────────────────────╯
+    ╭─ Skill Registered ────────────────────────╮
+    │ Name: local/devops-toolkit                │
+    │ Description: Full-stack development tools │
+    │ Config: ./skills/devops-toolkit.yaml      │
+    │ Created: 2026-02-08 13:10                 │
+    ╰───────────────────────────────────────────╯
 
-╭─ 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                             │
-╰───────────────────────────────────────────────╯
+    ╭─ Includes ────────────────────╮
+    │ local/file-ops (registered)   │
+    │ local/git-ops (registered)    │
+    │ local/github (registered)     │
+    ╰───────────────────────────────╯
 
-╭─ MCP Servers ────────────────────╮
-│ linear: validated (2 tools)      │
-╰──────────────────────────────────╯
+    ╭─ 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                             │
+    ╰───────────────────────────────────────────────╯
 
-✓ OK Skill registered with 23 tools
-

+    ╭─ MCP Servers ────────────────────╮
+    │ linear: validated (2 tools)      │
+    ╰──────────────────────────────────╯
+
+    ✓ OK Skill registered with 23 tools
+
+ +=== "Plain" + + ``` + $ agents skill add --config ./skills/devops-toolkit.yaml + + Skill Registered + Name: local/devops-toolkit + 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) + + 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 (2 tools) + + [OK] Skill registered with 23 tools + ``` + +=== "JSON" + + ```json + { + "command": "skill add --config ./skills/devops-toolkit.yaml", + "status": "ok", + "exit_code": 0, + "data": { + "skill": { + "name": "local/devops-toolkit", + "description": "Full-stack development tools", + "config": "./skills/devops-toolkit.yaml", + "created": "2026-02-08T13:10:00Z" + }, + "includes": [ + { "name": "local/file-ops", "status": "registered" }, + { "name": "local/git-ops", "status": "registered" }, + { "name": "local/github", "status": "registered" } + ], + "tool_sources": [ + { "source": "builtin", "count": 14, "details": "file, dir, git, shell" }, + { "source": "mcp", "count": 6, "details": "github (4), linear (2)" }, + { "source": "agent_skill", "count": 2, "details": "deploy, code-review" }, + { "source": "custom", "count": 1, "details": "run_migrations" } + ], + "total_tools": 23, + "mcp_servers": [ + { "name": "linear", "status": "validated", "tools": 2 } + ] + }, + "timing": { + "duration_ms": 150 + }, + "messages": [ + { "level": "ok", "text": "Skill registered with 23 tools" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: skill add --config ./skills/devops-toolkit.yaml + status: ok + exit_code: 0 + data: + skill: + name: local/devops-toolkit + description: Full-stack development tools + config: ./skills/devops-toolkit.yaml + created: "2026-02-08T13:10:00Z" + includes: + - name: local/file-ops + status: registered + - name: local/git-ops + status: registered + - name: local/github + status: registered + tool_sources: + - source: builtin + count: 14 + details: file, dir, git, shell + - source: mcp + count: 6 + details: github (4), linear (2) + - source: agent_skill + count: 2 + details: deploy, code-review + - source: custom + count: 1 + details: run_migrations + total_tools: 23 + mcp_servers: + - name: linear + status: validated + tools: 2 + timing: + duration_ms: 150 + messages: + - level: ok + text: Skill registered with 23 tools + ``` Attempting to add a skill that already exists (without `--update`): -

-$ agents skill add --config ./skills/devops-toolkit-v2.yaml
+=== "Rich"
 
-✗ Error: Skill 'local/devops-toolkit' is already registered.
+    

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

+    To overwrite the existing configuration, re-run with --update:
+
+      agents skill add --config ./skills/devops-toolkit-v2.yaml --update
+
+ +=== "Plain" + + ``` + $ agents skill add --config ./skills/devops-toolkit-v2.yaml + + Error: Skill 'local/devops-toolkit' is already registered. + + To overwrite the existing configuration, re-run with --update: + + agents skill add --config ./skills/devops-toolkit-v2.yaml --update + ``` + +=== "JSON" + + ```json + { + "command": "skill add --config ./skills/devops-toolkit-v2.yaml", + "status": "error", + "exit_code": 1, + "data": { + "skill_name": "local/devops-toolkit", + "reason": "already registered" + }, + "timing": { + "duration_ms": 30 + }, + "messages": [ + { "level": "error", "text": "Skill 'local/devops-toolkit' is already registered." }, + { "level": "info", "text": "To overwrite the existing configuration, re-run with --update" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: skill add --config ./skills/devops-toolkit-v2.yaml + status: error + exit_code: 1 + data: + skill_name: local/devops-toolkit + reason: already registered + timing: + duration_ms: 30 + messages: + - level: error + text: "Skill 'local/devops-toolkit' is already registered." + - level: info + text: To overwrite the existing configuration, re-run with --update + ``` Updating an existing skill with `--update`: -

-$ agents skill add --config ./skills/devops-toolkit-v2.yaml --update
+=== "Rich"
 
-╭─ Skill Updated ───────────────────────────╮
-│ Name: local/devops-toolkit                │
-│ Description: Full-stack development tools │
-│ Updated: 2026-02-08 14:22                 │
-╰───────────────────────────────────────────╯
+    

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

+    ╭─ 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 updated (23 → 25 tools)
+
+ +=== "Plain" + + ``` + $ agents skill add --config ./skills/devops-toolkit-v2.yaml --update + + 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 + + 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 updated (23 -> 25 tools) + ``` + +=== "JSON" + + ```json + { + "command": "skill add --config ./skills/devops-toolkit-v2.yaml --update", + "status": "ok", + "exit_code": 0, + "data": { + "skill": { + "name": "local/devops-toolkit", + "description": "Full-stack development tools", + "updated": "2026-02-08T14:22:00Z" + }, + "changes": { + "tools_added": 2, + "tools_removed": 0, + "tools_modified": 1, + "includes_changed": false, + "mcp_servers_changed": false + }, + "affected_actors": [ + "local/code-assistant", + "local/full-stack-assistant" + ], + "tool_count": { + "before": 23, + "after": 25 + } + }, + "timing": { + "duration_ms": 180 + }, + "messages": [ + { "level": "ok", "text": "Skill updated (23 -> 25 tools)" }, + { "level": "warn", "text": "2 actors reference this skill and will pick up changes on next use" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: skill add --config ./skills/devops-toolkit-v2.yaml --update + status: ok + exit_code: 0 + data: + skill: + name: local/devops-toolkit + description: Full-stack development tools + updated: "2026-02-08T14:22:00Z" + changes: + tools_added: 2 + tools_removed: 0 + tools_modified: 1 + includes_changed: false + mcp_servers_changed: false + affected_actors: + - local/code-assistant + - local/full-stack-assistant + tool_count: + before: 23 + after: 25 + timing: + duration_ms: 180 + messages: + - level: ok + text: "Skill updated (23 -> 25 tools)" + - level: warn + text: 2 actors reference this skill and will pick up changes on next use + ``` ##### agents skill remove 
agents skill remove [--yes|-y] <NAME>
-**Purpose** -Remove a registered skill. +!!! warning "Cascading Impact" + Removing a skill ==unregisters all tools== provided by that skill and closes any associated MCP server connections. Other skills that include this skill, and actors that reference it, will lose access to those tools. **Arguments** @@ -2115,27 +6702,114 @@ Remove a registered skill. **Examples** -

-$ agents skill remove local/devops-toolkit
+=== "Rich"
 
-Remove skill local/devops-toolkit? [y/N]: y
+    

+    $ agents skill remove local/devops-toolkit
 
-╭─ Skill Removed ──────────────────────╮
-│ Name: local/devops-toolkit           │
-│ Tools: 23 removed from registry      │
-│ MCP Servers: 1 connection closed     │
-╰──────────────────────────────────────╯
+    Remove skill local/devops-toolkit? [y/N]: y
 
-╭─ 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                       │
-╰────────────────────────────────────────────────────╯
+    ╭─ Skill Removed ──────────────────────╮
+    │ Name: local/devops-toolkit           │
+    │ Tools: 23 removed from registry      │
+    │ MCP Servers: 1 connection closed     │
+    ╰──────────────────────────────────────╯
 
-✓ OK Skill removed
-

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ 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 + + 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 + ``` + +=== "JSON" + + ```json + { + "command": "skill remove local/devops-toolkit", + "status": "ok", + "exit_code": 0, + "data": { + "skill": { + "name": "local/devops-toolkit", + "tools_removed": 23, + "mcp_servers_closed": 1 + }, + "dependency_check": { + "including_skills": [ + { "name": "local/full-stack-dev", "impact": "will lose devops tools" } + ], + "referencing_actors": [ + "local/code-assistant", + "local/full-stack-assistant" + ] + } + }, + "timing": { + "duration_ms": 95 + }, + "messages": [ + { "level": "ok", "text": "Skill removed" }, + { "level": "warn", "text": "1 skill includes this skill" }, + { "level": "warn", "text": "2 actors reference this skill" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: skill remove local/devops-toolkit + status: ok + exit_code: 0 + data: + skill: + name: local/devops-toolkit + tools_removed: 23 + mcp_servers_closed: 1 + dependency_check: + including_skills: + - name: local/full-stack-dev + impact: will lose devops tools + referencing_actors: + - local/code-assistant + - local/full-stack-assistant + timing: + duration_ms: 95 + messages: + - level: ok + text: Skill removed + - level: warn + text: 1 skill includes this skill + - level: warn + text: 2 actors reference this skill + ``` ##### agents skill list @@ -2151,28 +6825,133 @@ List registered skills with optional filters. **Examples** -

-$ agents skill list
+=== "Rich"
 
-╭─ 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    25     4         builtin, mcp, custom       │
-╰─────────────────────────────────────────────────────────────────────╯
+    

+    $ agents skill list
 
-╭─ Summary ─────────╮
-│ Total: 5          │
-│ Local: 5          │
-│ Server: 0         │
-│ Total Tools: 28   │
-╰───────────────────╯
+    ╭─ 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    25     4         builtin, mcp, custom       │
+    ╰─────────────────────────────────────────────────────────────────────╯
 
-✓ OK 5 skills listed
-

+    ╭─ Summary ─────────╮
+    │ Total: 5          │
+    │ Local: 5          │
+    │ Server: 0         │
+    │ Total Tools: 28   │
+    ╰───────────────────╯
+
+    ✓ OK 5 skills listed
+
+ +=== "Plain" + + ``` + $ 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 25 4 builtin, mcp, custom + + Summary + Total: 5 + Local: 5 + Server: 0 + Total Tools: 28 + + [OK] 5 skills listed + ``` + +=== "JSON" + + ```json + { + "command": "skill list", + "status": "ok", + "exit_code": 0, + "data": { + "skills": [ + { "name": "local/file-ops", "tools": 9, "includes": 0, "sources": ["builtin"] }, + { "name": "local/git-ops", "tools": 4, "includes": 0, "sources": ["builtin"] }, + { "name": "local/github", "tools": 4, "includes": 0, "sources": ["mcp"] }, + { "name": "local/devops-toolkit", "tools": 23, "includes": 3, "sources": ["builtin", "mcp", "custom"] }, + { "name": "local/full-stack-dev", "tools": 25, "includes": 4, "sources": ["builtin", "mcp", "custom"] } + ], + "summary": { + "total": 5, + "local": 5, + "server": 0, + "total_tools": 28 + } + }, + "timing": { + "duration_ms": 45 + }, + "messages": [ + { "level": "ok", "text": "5 skills listed" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: skill list + status: ok + exit_code: 0 + data: + skills: + - name: local/file-ops + tools: 9 + includes: 0 + sources: + - builtin + - name: local/git-ops + tools: 4 + includes: 0 + sources: + - builtin + - name: local/github + tools: 4 + includes: 0 + sources: + - mcp + - name: local/devops-toolkit + tools: 23 + includes: 3 + sources: + - builtin + - mcp + - custom + - name: local/full-stack-dev + tools: 25 + includes: 4 + sources: + - builtin + - mcp + - custom + summary: + total: 5 + local: 5 + server: 0 + total_tools: 28 + timing: + duration_ms: 45 + messages: + - level: ok + text: 5 skills listed + ``` ##### agents skill show @@ -2187,54 +6966,226 @@ Show full details for a registered skill, including its includes, tool sources, **Examples** -

-$ agents skill show local/devops-toolkit
+=== "Rich"
 
-╭─ Skill Details ──────────────────────────────╮
-│ Name: local/devops-toolkit                   │
-│ Description: Full-stack development tools    │
-│ Config: ./skills/devops-toolkit.yaml         │
-│ Created: 2026-02-08 13:10                    │
-│ Updated: 2026-02-08 14:22                    │
-╰──────────────────────────────────────────────╯
+    

+    $ agents skill show local/devops-toolkit
 
-╭─ Includes (3) ────────────────────────────╮
-│ local/file-ops  → 9 tools (builtin)       │
-│ local/git-ops   → 4 tools (builtin)       │
-│ local/github    → 4 tools (mcp)           │
-╰───────────────────────────────────────────╯
+    ╭─ Skill Details ──────────────────────────────╮
+    │ Name: local/devops-toolkit                   │
+    │ Description: Full-stack development tools    │
+    │ Config: ./skills/devops-toolkit.yaml         │
+    │ Created: 2026-02-08 13:10                    │
+    │ Updated: 2026-02-08 14:22                    │
+    ╰──────────────────────────────────────────────╯
 
-╭─ 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           │
-╰───────────────────────────────────────────────────────────╯
+    ╭─ Includes (3) ────────────────────────────╮
+    │ local/file-ops  → 9 tools (builtin)       │
+    │ local/git-ops   → 4 tools (builtin)       │
+    │ local/github    → 4 tools (mcp)           │
+    ╰───────────────────────────────────────────╯
 
-╭─ MCP Servers (1) ───────────────────╮
-│ linear: stdio, 2 tools, connected   │
-╰─────────────────────────────────────╯
+    ╭─ 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           │
+    ╰───────────────────────────────────────────────────────────╯
 
-╭─ Capability Summary ──────────╮
-│ Total Tools: 23               │
-│ Read-Only: 10                 │
-│ Writes: 13                    │
-│ Checkpointable: 10            │
-│ Has Side Effects: 3           │
-│ Requires Approval: 1          │
-╰───────────────────────────────╯
+    ╭─ MCP Servers (1) ───────────────────╮
+    │ linear: stdio, 2 tools, connected   │
+    ╰─────────────────────────────────────╯
 
-╭─ Referenced By ───────────────────╮
-│ Actors: local/code-assistant      │
-│ Skills: local/full-stack-dev      │
-╰───────────────────────────────────╯
+    ╭─ Capability Summary ──────────╮
+    │ Total Tools: 23               │
+    │ Read-Only: 10                 │
+    │ Writes: 13                    │
+    │ Checkpointable: 10            │
+    │ Has Side Effects: 3           │
+    │ Requires Approval: 1          │
+    ╰───────────────────────────────╯
 
-✓ OK Skill loaded
-

+    ╭─ Referenced By ───────────────────╮
+    │ Actors: local/code-assistant      │
+    │ Skills: local/full-stack-dev      │
+    ╰───────────────────────────────────╯
+
+    ✓ OK Skill loaded
+
+ +=== "Plain" + + ``` + $ agents skill show local/devops-toolkit + + Skill Details + Name: local/devops-toolkit + 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) + + 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 + + MCP Servers (1) + linear: stdio, 2 tools, connected + + Capability Summary + 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 + + [OK] Skill loaded + ``` + +=== "JSON" + + ```json + { + "command": "skill show local/devops-toolkit", + "status": "ok", + "exit_code": 0, + "data": { + "skill": { + "name": "local/devops-toolkit", + "description": "Full-stack development tools", + "config": "./skills/devops-toolkit.yaml", + "created": "2026-02-08T13:10:00Z", + "updated": "2026-02-08T14:22:00Z" + }, + "includes": [ + { "name": "local/file-ops", "tools": 9, "source": "builtin" }, + { "name": "local/git-ops", "tools": 4, "source": "builtin" }, + { "name": "local/github", "tools": 4, "source": "mcp" } + ], + "direct_tools": [ + { "name": "create_issue", "source": "mcp:linear", "writes": true, "checkpoint": "no" }, + { "name": "list_issues", "source": "mcp:linear", "writes": false, "checkpoint": null }, + { "name": "deploy-to-staging", "source": "agent_skill", "writes": true, "checkpoint": "composite" }, + { "name": "code-review", "source": "agent_skill", "writes": false, "checkpoint": null }, + { "name": "run_migrations", "source": "custom", "writes": true, "checkpoint": "transaction" }, + { "name": "shell_execute", "source": "builtin", "writes": true, "checkpoint": "snapshot" } + ], + "mcp_servers": [ + { "name": "linear", "transport": "stdio", "tools": 2, "status": "connected" } + ], + "capability_summary": { + "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"] + } + }, + "timing": { + "duration_ms": 110 + }, + "messages": [ + { "level": "ok", "text": "Skill loaded" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: skill show local/devops-toolkit + status: ok + exit_code: 0 + data: + skill: + name: local/devops-toolkit + description: Full-stack development tools + config: ./skills/devops-toolkit.yaml + created: "2026-02-08T13:10:00Z" + updated: "2026-02-08T14:22:00Z" + includes: + - name: local/file-ops + tools: 9 + source: builtin + - name: local/git-ops + tools: 4 + source: builtin + - name: local/github + tools: 4 + source: mcp + direct_tools: + - name: create_issue + source: "mcp:linear" + writes: true + checkpoint: "no" + - name: list_issues + source: "mcp:linear" + writes: false + checkpoint: null + - name: deploy-to-staging + source: agent_skill + writes: true + checkpoint: composite + - name: code-review + source: agent_skill + writes: false + checkpoint: null + - name: run_migrations + source: custom + writes: true + checkpoint: transaction + - name: shell_execute + source: builtin + writes: true + checkpoint: snapshot + mcp_servers: + - name: linear + transport: stdio + tools: 2 + status: connected + capability_summary: + 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 + timing: + duration_ms: 110 + messages: + - level: ok + text: Skill loaded + ``` ##### agents skill tools @@ -2249,53 +7200,318 @@ List all tools provided by a skill, including those inherited from included skil **Examples** -

-$ agents skill tools local/devops-toolkit
+=== "Rich"
 
-╭─ 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                  │
-│ 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              │
-╰──────────────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents skill tools local/devops-toolkit
 
-╭─ Summary ──────────────────╮
-│ Total: 23                  │
-│ From Includes: 17          │
-│ Direct: 6                  │
-│ Read-Only: 10              │
-│ Writes: 13                 │
-│ Checkpointable: 10         │
-╰────────────────────────────╯
+    ╭─ 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                  │
+    │ 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              │
+    ╰──────────────────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 23 tools listed
-

+    ╭─ Summary ──────────────────╮
+    │ Total: 23                  │
+    │ From Includes: 17          │
+    │ Direct: 6                  │
+    │ Read-Only: 10              │
+    │ Writes: 13                 │
+    │ Checkpointable: 10         │
+    ╰────────────────────────────╯
+
+    ✓ OK 23 tools listed
+
+ +=== "Plain" + + ``` + $ 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 yes - - + write_file builtin local/file-ops - yes file + edit_file builtin local/file-ops - yes file + delete_file builtin local/file-ops - yes file + move_file builtin local/file-ops - yes file + copy_file builtin local/file-ops - yes file + create_directory builtin local/file-ops - yes file + list_directory builtin local/file-ops yes - - + delete_directory builtin local/file-ops - yes file + git_status builtin local/git-ops yes - - + git_diff builtin local/git-ops yes - - + git_log builtin local/git-ops yes - - + git_blame builtin local/git-ops yes - - + create_issue mcp:github local/github - yes no + create_pr mcp:github local/github - yes no + list_repos mcp:github local/github yes - - + get_file_contents mcp:github local/github yes - - + create_issue mcp:linear (direct) - yes no + list_issues mcp:linear (direct) yes - - + run_migrations custom (direct) - yes transaction + deploy-to-staging agent_skill (direct) - yes composite + code-review agent_skill (direct) yes - - + shell_execute builtin (direct) - yes snapshot + + Summary + Total: 23 + From Includes: 17 + Direct: 6 + Read-Only: 10 + Writes: 13 + Checkpointable: 10 + + [OK] 23 tools listed + ``` + +=== "JSON" + + ```json + { + "command": "skill tools local/devops-toolkit", + "status": "ok", + "exit_code": 0, + "data": { + "tools": [ + { "name": "read_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "write_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" }, + { "name": "edit_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" }, + { "name": "delete_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" }, + { "name": "move_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" }, + { "name": "copy_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" }, + { "name": "create_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" }, + { "name": "list_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "delete_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" }, + { "name": "git_status", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "git_diff", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "git_log", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "git_blame", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "create_issue", "source": "mcp:github", "from_skill": "local/github", "read_only": false, "writes": true, "checkpoint": "no" }, + { "name": "create_pr", "source": "mcp:github", "from_skill": "local/github", "read_only": false, "writes": true, "checkpoint": "no" }, + { "name": "list_repos", "source": "mcp:github", "from_skill": "local/github", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "get_file_contents", "source": "mcp:github", "from_skill": "local/github", "read_only": true, "writes": false, "checkpoint": null }, + { "name": "create_issue", "source": "mcp:linear", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "no" }, + { "name": "list_issues", "source": "mcp:linear", "from_skill": null, "read_only": true, "writes": false, "checkpoint": null }, + { "name": "run_migrations", "source": "custom", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "transaction" }, + { "name": "deploy-to-staging", "source": "agent_skill", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "composite" }, + { "name": "code-review", "source": "agent_skill", "from_skill": null, "read_only": true, "writes": false, "checkpoint": null }, + { "name": "shell_execute", "source": "builtin", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "snapshot" } + ], + "summary": { + "total": 23, + "from_includes": 17, + "direct": 6, + "read_only": 10, + "writes": 13, + "checkpointable": 10 + } + }, + "timing": { + "duration_ms": 85 + }, + "messages": [ + { "level": "ok", "text": "23 tools listed" } + ] + } + ``` + +=== "YAML" + + ```yaml + command: skill tools local/devops-toolkit + status: ok + exit_code: 0 + data: + tools: + - name: read_file + source: builtin + from_skill: local/file-ops + read_only: true + writes: false + checkpoint: null + - name: write_file + source: builtin + from_skill: local/file-ops + read_only: false + writes: true + checkpoint: file + - name: edit_file + source: builtin + from_skill: local/file-ops + read_only: false + writes: true + checkpoint: file + - name: delete_file + source: builtin + from_skill: local/file-ops + read_only: false + writes: true + checkpoint: file + - name: move_file + source: builtin + from_skill: local/file-ops + read_only: false + writes: true + checkpoint: file + - name: copy_file + source: builtin + from_skill: local/file-ops + read_only: false + writes: true + checkpoint: file + - name: create_directory + source: builtin + from_skill: local/file-ops + read_only: false + writes: true + checkpoint: file + - name: list_directory + source: builtin + from_skill: local/file-ops + read_only: true + writes: false + checkpoint: null + - name: delete_directory + source: builtin + from_skill: local/file-ops + read_only: false + writes: true + checkpoint: file + - name: git_status + source: builtin + from_skill: local/git-ops + read_only: true + writes: false + checkpoint: null + - name: git_diff + source: builtin + from_skill: local/git-ops + read_only: true + writes: false + checkpoint: null + - name: git_log + source: builtin + from_skill: local/git-ops + read_only: true + writes: false + checkpoint: null + - name: git_blame + source: builtin + from_skill: local/git-ops + read_only: true + writes: false + checkpoint: null + - name: create_issue + source: "mcp:github" + from_skill: local/github + read_only: false + writes: true + checkpoint: "no" + - name: create_pr + source: "mcp:github" + from_skill: local/github + read_only: false + writes: true + checkpoint: "no" + - name: list_repos + source: "mcp:github" + from_skill: local/github + read_only: true + writes: false + checkpoint: null + - name: get_file_contents + source: "mcp:github" + from_skill: local/github + read_only: true + writes: false + checkpoint: null + - name: create_issue + source: "mcp:linear" + from_skill: null + read_only: false + writes: true + checkpoint: "no" + - name: list_issues + source: "mcp:linear" + from_skill: null + read_only: true + writes: false + checkpoint: null + - name: run_migrations + source: custom + from_skill: null + read_only: false + writes: true + checkpoint: transaction + - name: deploy-to-staging + source: agent_skill + from_skill: null + read_only: false + writes: true + checkpoint: composite + - name: code-review + source: agent_skill + from_skill: null + read_only: true + writes: false + checkpoint: null + - name: shell_execute + source: builtin + from_skill: null + read_only: false + writes: true + checkpoint: snapshot + summary: + total: 23 + from_includes: 17 + direct: 6 + read_only: 10 + writes: 13 + checkpointable: 10 + timing: + duration_ms: 85 + messages: + - level: ok + text: 23 tools listed + ``` #### agents tool -**Purpose** -Manage tools — namespaced, independently registered, callable operations. Tools are defined in their own YAML configuration files and registered in the system through these commands. Once registered, tools can be referenced by name in skills (as part of a tool collection) and in actor graphs (as tool nodes). +!!! info "Purpose" + Manage ==tools== — namespaced, independently registered, callable operations. Tools are defined in their own YAML configuration files and registered in the system through these commands. Once registered, tools can be referenced by name in skills (as part of a tool collection) and in actor graphs (as tool nodes). + +??? tip "Tool Lifecycle Overview" + | Stage | Command | Description | + | :---- | :------ | :---------- | + | **Register** | `agents tool add` | Register from YAML config | + | **Inspect** | `agents tool show` | View tool details and capabilities | + | **List** | `agents tool list` | Browse registered tools | + | **Update** | `agents tool add --update` | Re-register with updated config | + | **Remove** | `agents tool remove` | Unregister a tool | ##### agents tool add @@ -2313,73 +7529,284 @@ Register a new tool. The tool is fully defined by the YAML configuration file sp Registering a new tool: -

-$ agents tool add --config ./tools/run-migrations.yaml
+=== "Rich"
 
-╭─ Tool Registered ────────────────────────────╮
-│ Name: local/run-migrations                   │
-│ Description: Run database migrations         │
-│ Source: custom                               │
-│ Config: ./tools/run-migrations.yaml          │
-│ Created: 2026-02-09 10:15                    │
-╰──────────────────────────────────────────────╯
+    

+    $ agents tool add --config ./tools/run-migrations.yaml
 
-╭─ Capability ─────────────────────╮
-│ Writes: true                     │
-│ Write Scope: database:migrations │
-│ Checkpointable: true             │
-│ Checkpoint Scope: transaction    │
-│ Side Effects: schema_mutation    │
-╰──────────────────────────────────╯
+    ╭─ Tool Registered ────────────────────────────╮
+    │ Name: local/run-migrations                   │
+    │ Description: Run database migrations         │
+    │ Source: custom                               │
+    │ Config: ./tools/run-migrations.yaml          │
+    │ Created: 2026-02-09 10:15                    │
+    ╰──────────────────────────────────────────────╯
 
-✓ OK Tool registered
-

+    ╭─ Capability ─────────────────────╮
+    │ Writes: true                     │
+    │ Write Scope: database:migrations │
+    │ Checkpointable: true             │
+    │ Checkpoint Scope: transaction    │
+    │ Side Effects: schema_mutation    │
+    ╰──────────────────────────────────╯
+
+    ✓ OK Tool registered
+
+ +=== "Plain" + + ``` + $ agents tool add --config ./tools/run-migrations.yaml + + Tool Registered + Name: local/run-migrations + 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 + + [OK] Tool registered + ``` + +=== "JSON" + + ```json + { + "command": "tool add", + "status": "ok", + "exit_code": 0, + "data": { + "tool_registered": { + "name": "local/run-migrations", + "description": "Run database migrations", + "source": "custom", + "config": "./tools/run-migrations.yaml", + "created": "2026-02-09T10:15:00Z" + }, + "capability": { + "writes": true, + "write_scope": "database:migrations", + "checkpointable": true, + "checkpoint_scope": "transaction", + "side_effects": ["schema_mutation"] + } + }, + "timing": { "duration_ms": 58 }, + "messages": ["Tool registered"] + } + ``` + +=== "YAML" + + ```yaml + command: tool add + status: ok + exit_code: 0 + data: + tool_registered: + name: local/run-migrations + description: Run database migrations + source: custom + config: ./tools/run-migrations.yaml + created: "2026-02-09T10:15:00Z" + capability: + writes: true + write_scope: "database:migrations" + checkpointable: true + checkpoint_scope: transaction + side_effects: + - schema_mutation + timing: + duration_ms: 58 + messages: + - Tool registered + ``` Attempting to add a tool that already exists (without `--update`): -

-$ agents tool add --config ./tools/run-migrations-v2.yaml
+=== "Rich"
 
-✗ Error: Tool 'local/run-migrations' is already registered.
+    

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

+    To overwrite the existing configuration, re-run with --update:
+
+      agents tool add --config ./tools/run-migrations-v2.yaml --update
+
+ +=== "Plain" + + ``` + $ agents tool add --config ./tools/run-migrations-v2.yaml + + [ERROR] Tool 'local/run-migrations' is already registered. + + To overwrite the existing configuration, re-run with --update: + + agents tool add --config ./tools/run-migrations-v2.yaml --update + ``` + +=== "JSON" + + ```json + { + "command": "tool add", + "status": "error", + "exit_code": 1, + "data": { + "error": "Tool 'local/run-migrations' is already registered.", + "hint": "To overwrite the existing configuration, re-run with --update", + "suggested_command": "agents tool add --config ./tools/run-migrations-v2.yaml --update" + }, + "timing": { "duration_ms": 12 }, + "messages": ["Tool 'local/run-migrations' is already registered."] + } + ``` + +=== "YAML" + + ```yaml + command: tool add + status: error + exit_code: 1 + data: + error: "Tool 'local/run-migrations' is already registered." + hint: "To overwrite the existing configuration, re-run with --update" + suggested_command: "agents tool add --config ./tools/run-migrations-v2.yaml --update" + timing: + duration_ms: 12 + messages: + - "Tool 'local/run-migrations' is already registered." + ``` Updating an existing tool with `--update`: -

-$ agents tool add --config ./tools/db-migrate.yaml --update
+=== "Rich"
 
-╭─ Tool Updated ─────────────────────────────╮
-│ Name: local/db-migrate                     │
-│ Source: custom (Python)                    │
-│ Status: updated (was version 1 → now 2)    │
-╰────────────────────────────────────────────╯
+    

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

+    ╭─ References ──────────────────╮
+    │ Skills: 1 (local/db-tools)    │
+    │ Actors: 0                     │
+    │ Referencing skills will use   │
+    │ the updated definition.       │
+    ╰───────────────────────────────╯
+
+    ✓ OK Tool updated
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "tool add", + "status": "ok", + "exit_code": 0, + "data": { + "tool_updated": { + "name": "local/db-migrate", + "source": "custom", + "source_language": "Python", + "status": "updated", + "previous_version": 1, + "current_version": 2 + }, + "changes": { + "input_schema": "modified (added batch_size)", + "capabilities": "unchanged (writes, checkpoint)", + "description": "updated" + }, + "references": { + "skills": ["local/db-tools"], + "actors": [] + } + }, + "timing": { "duration_ms": 45 }, + "messages": ["Tool updated"] + } + ``` + +=== "YAML" + + ```yaml + command: tool add + status: ok + exit_code: 0 + data: + tool_updated: + name: local/db-migrate + source: custom + source_language: Python + status: updated + previous_version: 1 + current_version: 2 + changes: + input_schema: "modified (added batch_size)" + capabilities: "unchanged (writes, checkpoint)" + description: updated + references: + skills: + - local/db-tools + actors: [] + timing: + duration_ms: 45 + messages: + - Tool updated + ``` ##### agents tool remove 
agents tool remove [--yes|-y] <NAME>
-**Purpose** -Remove a registered tool. Because Validations are a subtype of Tool and share the same registry, this command also removes validations. When removing a Validation, all attachments are automatically detached before the entry is removed from the registry. +!!! danger "Destructive Operation" + Remove a registered tool. Because Validations are a subtype of Tool and share the same registry, this command ==also removes validations==. When removing a Validation, all attachments are automatically detached before the entry is removed from the registry. + + References from skills and actor graphs will **break** until resolved. **Arguments** @@ -2388,47 +7815,186 @@ Remove a registered tool. Because Validations are a subtype of Tool and share th **Examples** -

-$ agents tool remove local/run-migrations
+=== "Rich"
 
-Remove tool local/run-migrations? [y/N]: y
+    

+    $ agents tool remove local/run-migrations
 
-╭─ Tool Removed ────────────────────╮
-│ Name: local/run-migrations        │
-│ Source: custom                    │
-╰───────────────────────────────────╯
+    Remove tool local/run-migrations? [y/N]: y
 
-╭─ References ──────────────────────────────────────╮
-│ Warning: This tool is referenced by:              │
-│ - Skill: local/devops-toolkit                     │
-│ - Actor graph node: code_executor.run_db_migrate  │
-│ These references will break until resolved.       │
-╰───────────────────────────────────────────────────╯
+    ╭─ Tool Removed ────────────────────╮
+    │ Name: local/run-migrations        │
+    │ Source: custom                    │
+    ╰───────────────────────────────────╯
 
-✓ OK Tool removed
-

+    ╭─ References ──────────────────────────────────────╮
+    │ Warning: This tool is referenced by:              │
+    │ - Skill: local/devops-toolkit                     │
+    │ - Actor graph node: code_executor.run_db_migrate  │
+    │ These references will break until resolved.       │
+    ╰───────────────────────────────────────────────────╯
+
+    ✓ OK Tool removed
+
+ +=== "Plain" + + ``` + $ agents tool remove local/run-migrations + + Remove tool local/run-migrations? [y/N]: y + + Tool Removed + Name: local/run-migrations + Source: custom + + References + Warning: This tool is referenced by: + - Skill: local/devops-toolkit + - Actor graph node: code_executor.run_db_migrate + These references will break until resolved. + + [OK] Tool removed + ``` + +=== "JSON" + + ```json + { + "command": "tool remove", + "status": "ok", + "exit_code": 0, + "data": { + "tool_removed": { + "name": "local/run-migrations", + "source": "custom" + }, + "broken_references": [ + { "type": "skill", "name": "local/devops-toolkit" }, + { "type": "actor_graph_node", "name": "code_executor.run_db_migrate" } + ] + }, + "timing": { "duration_ms": 34 }, + "messages": [ + "Tool removed", + "Warning: This tool is referenced by 1 skill and 1 actor graph node. These references will break until resolved." + ] + } + ``` + +=== "YAML" + + ```yaml + command: tool remove + status: ok + exit_code: 0 + data: + tool_removed: + name: local/run-migrations + source: custom + broken_references: + - type: skill + name: local/devops-toolkit + - type: actor_graph_node + name: code_executor.run_db_migrate + timing: + duration_ms: 34 + messages: + - Tool removed + - "Warning: This tool is referenced by 1 skill and 1 actor graph node. These references will break until resolved." + ``` When removing a validation, attachments are cleaned up automatically: -

-$ agents tool remove local/check-bundle-size
+=== "Rich"
 
-Remove validation local/check-bundle-size? [y/N]: y
+    

+    $ agents tool remove local/check-bundle-size
 
-╭─ Validation Removed ─────────────────────────────╮
-│ Name: local/check-bundle-size                    │
-│ Description: Check bundle size (advisory)       │
-╰──────────────────────────────────────────────────╯
+    Remove validation local/check-bundle-size? [y/N]: y
 
-╭─ Detached From ────────────────────────────────────────────╮
-│ Warning: This validation had 2 attachments:               │
-│ - local/api-repo (scope: project local/api-service)       │
-│ - local/api-repo (direct)                                 │
-│ These attachments have been removed.                      │
-╰───────────────────────────────────────────────────────────╯
+    ╭─ Validation Removed ─────────────────────────────╮
+    │ Name: local/check-bundle-size                    │
+    │ Description: Check bundle size (advisory)       │
+    ╰──────────────────────────────────────────────────╯
 
-✓ OK Validation removed
-

+    ╭─ Detached From ────────────────────────────────────────────╮
+    │ Warning: This validation had 2 attachments:               │
+    │ - local/api-repo (scope: project local/api-service)       │
+    │ - local/api-repo (direct)                                 │
+    │ These attachments have been removed.                      │
+    ╰───────────────────────────────────────────────────────────╯
+
+    ✓ OK Validation removed
+
+ +=== "Plain" + + ``` + $ agents tool remove local/check-bundle-size + + Remove validation local/check-bundle-size? [y/N]: y + + Validation Removed + Name: local/check-bundle-size + Description: Check bundle size (advisory) + + Detached From + Warning: This validation had 2 attachments: + - local/api-repo (scope: project local/api-service) + - local/api-repo (direct) + These attachments have been removed. + + [OK] Validation removed + ``` + +=== "JSON" + + ```json + { + "command": "tool remove", + "status": "ok", + "exit_code": 0, + "data": { + "validation_removed": { + "name": "local/check-bundle-size", + "description": "Check bundle size (advisory)" + }, + "detached_attachments": [ + { "resource": "local/api-repo", "scope": "project", "project": "local/api-service" }, + { "resource": "local/api-repo", "scope": "direct" } + ] + }, + "timing": { "duration_ms": 41 }, + "messages": [ + "Validation removed", + "Warning: This validation had 2 attachments which have been removed." + ] + } + ``` + +=== "YAML" + + ```yaml + command: tool remove + status: ok + exit_code: 0 + data: + validation_removed: + name: local/check-bundle-size + description: "Check bundle size (advisory)" + detached_attachments: + - resource: local/api-repo + scope: project + project: local/api-service + - resource: local/api-repo + scope: direct + timing: + duration_ms: 41 + messages: + - Validation removed + - "Warning: This validation had 2 attachments which have been removed." + ``` ##### agents tool list @@ -2445,53 +8011,264 @@ List registered tools with optional filters. Because Validations are a subtype o **Examples** -

-$ agents tool list --namespace local
+=== "Rich"
 
-╭─ Tools ─────────────────────────────────────────────────────────────────╮
-│ Name                       Type        Source   Read-Only  Writes    │
-│ ─────────────────────────  ──────────  ───────  ─────────  ──────    │
-│ local/run-migrations       tool        custom   —          ✓         │
-│ local/validate-api-compat  tool        custom   —          ✓         │
-│ local/create-subplan       tool        custom   —          ✓         │
-│ local/deploy-staging       tool        agent    —          ✓         │
-│ local/run-tests            validation  custom   ✓          —         │
-│ local/lint-check           validation  custom   ✓          —         │
-│ local/check-bundle-size    validation  custom   ✓          —         │
-│ local/type-check           validation  custom   ✓          —         │
-╰─────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents tool list --namespace local
 
-╭─ Summary ────────────────╮
-│ Total: 8                 │
-│ Tools: 4                 │
-│ Validations: 4           │
-│ Read-Only: 4             │
-│ Writes: 4                │
-╰──────────────────────────╯
+    ╭─ Tools ─────────────────────────────────────────────────────────────────╮
+    │ Name                       Type        Source   Read-Only  Writes    │
+    │ ─────────────────────────  ──────────  ───────  ─────────  ──────    │
+    │ local/run-migrations       tool        custom   —          ✓         │
+    │ local/validate-api-compat  tool        custom   —          ✓         │
+    │ local/create-subplan       tool        custom   —          ✓         │
+    │ local/deploy-staging       tool        agent    —          ✓         │
+    │ local/run-tests            validation  custom   ✓          —         │
+    │ local/lint-check           validation  custom   ✓          —         │
+    │ local/check-bundle-size    validation  custom   ✓          —         │
+    │ local/type-check           validation  custom   ✓          —         │
+    ╰─────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 8 tools listed
-

+    ╭─ Summary ────────────────╮
+    │ Total: 8                 │
+    │ Tools: 4                 │
+    │ Validations: 4           │
+    │ Read-Only: 4             │
+    │ Writes: 4                │
+    ╰──────────────────────────╯
 
-

-$ agents tool list --type validation --namespace local
+    ✓ OK 8 tools listed
+    

 
-╭─ Validations ────────────────────────────────────────────────────────────────────╮
-│ Name                       Source   Mode          Attachments                │
-│ ─────────────────────────  ───────  ────────────  ────────────────────────   │
-│ local/run-tests            custom   required      2 (1 direct, 1 project)    │
-│ local/lint-check           custom   required      1 (1 direct)               │
-│ local/check-bundle-size    custom   informational 1 (1 project)              │
-│ local/type-check           custom   required      2 (2 project)              │
-╰──────────────────────────────────────────────────────────────────────────────────╯
+=== "Plain"
 
-╭─ Summary ──────────────╮
-│ Total: 4               │
-│ Required: 3            │
-│ Informational: 1       │
-╰────────────────────────╯
+    ```
+    $ agents tool list --namespace local
 
-✓ OK 4 validations listed
-
+ Tools + Name Type Source Read-Only Writes + ------------------------- ---------- ------- --------- ------ + local/run-migrations tool custom - yes + local/validate-api-compat tool custom - yes + local/create-subplan tool custom - yes + local/deploy-staging tool agent - yes + local/run-tests validation custom yes - + local/lint-check validation custom yes - + local/check-bundle-size validation custom yes - + local/type-check validation custom yes - + + Summary + Total: 8 + Tools: 4 + Validations: 4 + Read-Only: 4 + Writes: 4 + + [OK] 8 tools listed + ``` + +=== "JSON" + + ```json + { + "command": "tool list", + "status": "ok", + "exit_code": 0, + "data": { + "tools": [ + { "name": "local/run-migrations", "type": "tool", "source": "custom", "read_only": false, "writes": true }, + { "name": "local/validate-api-compat", "type": "tool", "source": "custom", "read_only": false, "writes": true }, + { "name": "local/create-subplan", "type": "tool", "source": "custom", "read_only": false, "writes": true }, + { "name": "local/deploy-staging", "type": "tool", "source": "agent", "read_only": false, "writes": true }, + { "name": "local/run-tests", "type": "validation", "source": "custom", "read_only": true, "writes": false }, + { "name": "local/lint-check", "type": "validation", "source": "custom", "read_only": true, "writes": false }, + { "name": "local/check-bundle-size", "type": "validation", "source": "custom", "read_only": true, "writes": false }, + { "name": "local/type-check", "type": "validation", "source": "custom", "read_only": true, "writes": false } + ], + "summary": { + "total": 8, + "tools": 4, + "validations": 4, + "read_only": 4, + "writes": 4 + } + }, + "timing": { "duration_ms": 22 }, + "messages": ["8 tools listed"] + } + ``` + +=== "YAML" + + ```yaml + command: tool list + status: ok + exit_code: 0 + data: + tools: + - name: local/run-migrations + type: tool + source: custom + read_only: false + writes: true + - name: local/validate-api-compat + type: tool + source: custom + read_only: false + writes: true + - name: local/create-subplan + type: tool + source: custom + read_only: false + writes: true + - name: local/deploy-staging + type: tool + source: agent + read_only: false + writes: true + - name: local/run-tests + type: validation + source: custom + read_only: true + writes: false + - name: local/lint-check + type: validation + source: custom + read_only: true + writes: false + - name: local/check-bundle-size + type: validation + source: custom + read_only: true + writes: false + - name: local/type-check + type: validation + source: custom + read_only: true + writes: false + summary: + total: 8 + tools: 4 + validations: 4 + read_only: 4 + writes: 4 + timing: + duration_ms: 22 + messages: + - 8 tools listed + ``` + +=== "Rich" + + 

+    $ agents tool list --type validation --namespace local
+
+    ╭─ Validations ────────────────────────────────────────────────────────────────────╮
+    │ Name                       Source   Mode          Attachments                │
+    │ ─────────────────────────  ───────  ────────────  ────────────────────────   │
+    │ local/run-tests            custom   required      2 (1 direct, 1 project)    │
+    │ local/lint-check           custom   required      1 (1 direct)               │
+    │ local/check-bundle-size    custom   informational 1 (1 project)              │
+    │ local/type-check           custom   required      2 (2 project)              │
+    ╰──────────────────────────────────────────────────────────────────────────────────╯
+
+    ╭─ Summary ──────────────╮
+    │ Total: 4               │
+    │ Required: 3            │
+    │ Informational: 1       │
+    ╰────────────────────────╯
+
+    ✓ OK 4 validations listed
+
+ +=== "Plain" + + ``` + $ agents tool list --type validation --namespace local + + Validations + Name Source Mode Attachments + ------------------------- ------- ------------ ------------------------ + local/run-tests custom required 2 (1 direct, 1 project) + local/lint-check custom required 1 (1 direct) + local/check-bundle-size custom informational 1 (1 project) + local/type-check custom required 2 (2 project) + + Summary + Total: 4 + Required: 3 + Informational: 1 + + [OK] 4 validations listed + ``` + +=== "JSON" + + ```json + { + "command": "tool list", + "status": "ok", + "exit_code": 0, + "data": { + "validations": [ + { "name": "local/run-tests", "source": "custom", "mode": "required", "attachments": { "total": 2, "direct": 1, "project": 1 } }, + { "name": "local/lint-check", "source": "custom", "mode": "required", "attachments": { "total": 1, "direct": 1 } }, + { "name": "local/check-bundle-size", "source": "custom", "mode": "informational", "attachments": { "total": 1, "project": 1 } }, + { "name": "local/type-check", "source": "custom", "mode": "required", "attachments": { "total": 2, "project": 2 } } + ], + "summary": { + "total": 4, + "required": 3, + "informational": 1 + } + }, + "timing": { "duration_ms": 18 }, + "messages": ["4 validations listed"] + } + ``` + +=== "YAML" + + ```yaml + command: tool list + status: ok + exit_code: 0 + data: + validations: + - name: local/run-tests + source: custom + mode: required + attachments: + total: 2 + direct: 1 + project: 1 + - name: local/lint-check + source: custom + mode: required + attachments: + total: 1 + direct: 1 + - name: local/check-bundle-size + source: custom + mode: informational + attachments: + total: 1 + project: 1 + - name: local/type-check + source: custom + mode: required + attachments: + total: 2 + project: 2 + summary: + total: 4 + required: 3 + informational: 1 + timing: + duration_ms: 18 + messages: + - 4 validations listed + ``` ##### agents tool show @@ -2506,87 +8283,334 @@ Show full details for a registered tool, including its schema, capability metada **Examples** -

-$ agents tool show local/run-migrations
+=== "Rich"
 
-╭─ Tool Details ───────────────────────────────╮
-│ Name: local/run-migrations                   │
-│ Description: Run database migrations         │
-│ Source: custom                               │
-│ Config: ./tools/run-migrations.yaml          │
-│ Registered: 2026-02-09 10:15                 │
-╰──────────────────────────────────────────────╯
+    

+    $ agents tool show local/run-migrations
 
-╭─ Input Schema ─────────────────────────────────╮
-│ direction: string (required) enum: [up, down]  │
-│ count: integer (default: 1)                    │
-╰────────────────────────────────────────────────╯
+    ╭─ Tool Details ───────────────────────────────╮
+    │ Name: local/run-migrations                   │
+    │ Description: Run database migrations         │
+    │ Source: custom                               │
+    │ Config: ./tools/run-migrations.yaml          │
+    │ Registered: 2026-02-09 10:15                 │
+    ╰──────────────────────────────────────────────╯
 
-╭─ Capability ──────────────────────╮
-│ Read-Only: false                  │
-│ Writes: true                      │
-│ Write Scope: database:migrations  │
-│ Checkpointable: true              │
-│ Checkpoint Scope: transaction     │
-│ Side Effects: schema_mutation     │
-│ Idempotent: false                 │
-╰───────────────────────────────────╯
+    ╭─ Input Schema ─────────────────────────────────╮
+    │ direction: string (required) enum: [up, down]  │
+    │ count: integer (default: 1)                    │
+    ╰────────────────────────────────────────────────╯
 
-╭─ Referenced By ───────────────────────╮
-│ Skills:                               │
-│   - local/devops-toolkit              │
-│ Actor Graph Nodes:                    │
-│   - code_executor.run_db_migrate      │
-╰───────────────────────────────────────╯
+    ╭─ Capability ──────────────────────╮
+    │ Read-Only: false                  │
+    │ Writes: true                      │
+    │ Write Scope: database:migrations  │
+    │ Checkpointable: true              │
+    │ Checkpoint Scope: transaction     │
+    │ Side Effects: schema_mutation     │
+    │ Idempotent: false                 │
+    ╰───────────────────────────────────╯
 
-✓ OK Tool details loaded
-

+    ╭─ Referenced By ───────────────────────╮
+    │ Skills:                               │
+    │   - local/devops-toolkit              │
+    │ Actor Graph Nodes:                    │
+    │   - code_executor.run_db_migrate      │
+    ╰───────────────────────────────────────╯
+
+    ✓ OK Tool details loaded
+
+ +=== "Plain" + + ``` + $ 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 + + 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 + Side Effects: schema_mutation + Idempotent: false + + Referenced By + Skills: + - local/devops-toolkit + Actor Graph Nodes: + - code_executor.run_db_migrate + + [OK] Tool details loaded + ``` + +=== "JSON" + + ```json + { + "command": "tool show", + "status": "ok", + "exit_code": 0, + "data": { + "tool_details": { + "name": "local/run-migrations", + "description": "Run database migrations", + "source": "custom", + "config": "./tools/run-migrations.yaml", + "registered": "2026-02-09T10:15:00Z" + }, + "input_schema": { + "direction": { "type": "string", "required": true, "enum": ["up", "down"] }, + "count": { "type": "integer", "default": 1 } + }, + "capability": { + "read_only": false, + "writes": true, + "write_scope": "database:migrations", + "checkpointable": true, + "checkpoint_scope": "transaction", + "side_effects": ["schema_mutation"], + "idempotent": false + }, + "referenced_by": { + "skills": ["local/devops-toolkit"], + "actor_graph_nodes": ["code_executor.run_db_migrate"] + } + }, + "timing": { "duration_ms": 15 }, + "messages": ["Tool details loaded"] + } + ``` + +=== "YAML" + + ```yaml + command: tool show + status: ok + exit_code: 0 + data: + tool_details: + name: local/run-migrations + description: Run database migrations + source: custom + config: ./tools/run-migrations.yaml + registered: "2026-02-09T10:15:00Z" + input_schema: + direction: + type: string + required: true + enum: + - up + - down + count: + type: integer + default: 1 + capability: + read_only: false + writes: true + write_scope: "database:migrations" + checkpointable: true + checkpoint_scope: transaction + side_effects: + - schema_mutation + idempotent: false + referenced_by: + skills: + - local/devops-toolkit + actor_graph_nodes: + - code_executor.run_db_migrate + timing: + duration_ms: 15 + messages: + - Tool details loaded + ``` When showing a Validation, the output includes validation-specific sections: -

-$ agents tool show local/run-tests
+=== "Rich"
 
-╭─ Validation Details ──────────────────────────────╮
-│ Name: local/run-tests                             │
-│ Type: validation                                  │
-│ Description: Run unit tests with coverage          │
-│ Source: custom                                    │
-│ Mode: required                                    │
-│ Config: ./validations/run-tests.yaml              │
-│ Registered: 2026-02-09 10:15                      │
-╰───────────────────────────────────────────────────╯
+    

+    $ agents tool show local/run-tests
 
-╭─ Input Schema ─────────────────────────────────────╮
-│ coverage_threshold: integer (default: 80)          │
-╰────────────────────────────────────────────────────╯
+    ╭─ Validation Details ──────────────────────────────╮
+    │ Name: local/run-tests                             │
+    │ Type: validation                                  │
+    │ Description: Run unit tests with coverage          │
+    │ Source: custom                                    │
+    │ Mode: required                                    │
+    │ Config: ./validations/run-tests.yaml              │
+    │ Registered: 2026-02-09 10:15                      │
+    ╰───────────────────────────────────────────────────╯
 
-╭─ Output Schema (Validation Return Format) ─────────╮
-│ passed: boolean (required)                         │
-│ message: string (optional)                         │
-│ data: object (optional, arbitrary structure)        │
-╰────────────────────────────────────────────────────╯
+    ╭─ Input Schema ─────────────────────────────────────╮
+    │ coverage_threshold: integer (default: 80)          │
+    ╰────────────────────────────────────────────────────╯
 
-╭─ Capability ──────────────────────╮
-│ Read-Only: true (enforced)         │
-│ Checkpointable: false (enforced)   │
-│ Timeout: 600s                      │
-╰───────────────────────────────────╯
+    ╭─ Output Schema (Validation Return Format) ─────────╮
+    │ passed: boolean (required)                         │
+    │ message: string (optional)                         │
+    │ data: object (optional, arbitrary structure)        │
+    ╰────────────────────────────────────────────────────╯
 
-╭─ Attached To ─────────────────────────────────────────────────────╮
-│ local/api-repo (direct, always active)                           │
-│   (attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1)                      │
-│ local/api-repo (scope: project local/api-service)                │
-│   (attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0)                      │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ Capability ──────────────────────╮
+    │ Read-Only: true (enforced)         │
+    │ Checkpointable: false (enforced)   │
+    │ Timeout: 600s                      │
+    ╰───────────────────────────────────╯
 
-✓ OK Validation details loaded
-

+    ╭─ Attached To ─────────────────────────────────────────────────────╮
+    │ local/api-repo (direct, always active)                           │
+    │   (attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1)                      │
+    │ local/api-repo (scope: project local/api-service)                │
+    │   (attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0)                      │
+    ╰──────────────────────────────────────────────────────────────────╯
+
+    ✓ OK Validation details loaded
+
+ +=== "Plain" + + ``` + $ agents tool show local/run-tests + + Validation Details + Name: local/run-tests + Type: validation + Description: Run unit tests with coverage + Source: custom + Mode: required + Config: ./validations/run-tests.yaml + Registered: 2026-02-09 10:15 + + Input Schema + coverage_threshold: integer (default: 80) + + Output Schema (Validation Return Format) + passed: boolean (required) + message: string (optional) + data: object (optional, arbitrary structure) + + Capability + Read-Only: true (enforced) + Checkpointable: false (enforced) + Timeout: 600s + + Attached To + local/api-repo (direct, always active) + (attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1) + local/api-repo (scope: project local/api-service) + (attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0) + + [OK] Validation details loaded + ``` + +=== "JSON" + + ```json + { + "command": "tool show", + "status": "ok", + "exit_code": 0, + "data": { + "validation_details": { + "name": "local/run-tests", + "type": "validation", + "description": "Run unit tests with coverage", + "source": "custom", + "mode": "required", + "config": "./validations/run-tests.yaml", + "registered": "2026-02-09T10:15:00Z" + }, + "input_schema": { + "coverage_threshold": { "type": "integer", "default": 80 } + }, + "output_schema": { + "passed": { "type": "boolean", "required": true }, + "message": { "type": "string", "required": false }, + "data": { "type": "object", "required": false, "description": "arbitrary structure" } + }, + "capability": { + "read_only": true, + "read_only_enforced": true, + "checkpointable": false, + "checkpointable_enforced": true, + "timeout_seconds": 600 + }, + "attached_to": [ + { "resource": "local/api-repo", "scope": "direct", "attachment_id": "01HXM5B2C3D4E5F6G7H8J9K0L1" }, + { "resource": "local/api-repo", "scope": "project", "project": "local/api-service", "attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0" } + ] + }, + "timing": { "duration_ms": 19 }, + "messages": ["Validation details loaded"] + } + ``` + +=== "YAML" + + ```yaml + command: tool show + status: ok + exit_code: 0 + data: + validation_details: + name: local/run-tests + type: validation + description: Run unit tests with coverage + source: custom + mode: required + config: ./validations/run-tests.yaml + registered: "2026-02-09T10:15:00Z" + input_schema: + coverage_threshold: + type: integer + default: 80 + output_schema: + passed: + type: boolean + required: true + message: + type: string + required: false + data: + type: object + required: false + description: arbitrary structure + capability: + read_only: true + read_only_enforced: true + checkpointable: false + checkpointable_enforced: true + timeout_seconds: 600 + attached_to: + - resource: local/api-repo + scope: direct + attachment_id: 01HXM5B2C3D4E5F6G7H8J9K0L1 + - resource: local/api-repo + scope: project + project: local/api-service + attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0 + timing: + duration_ms: 19 + messages: + - Validation details loaded + ``` #### agents validation -**Purpose** -Register and attach validations — a specialized subtype of Tool that extends the Tool class with pass/fail semantics and attachment scoping. A Validation inherits all base Tool properties (name, source, input_schema, capability, resource bindings, lifecycle hooks, etc.) and adds: a `mode` field (`required` or `informational`), and a structured JSON return format with a mandatory `passed` boolean, an optional `message` string, and an optional `data` object for arbitrary informational output. Since Validation extends Tool, it shares the same backing sources (custom, MCP, agent_skill, builtin) plus the additional `wrapped` source type for Validations that wrap an existing Tool via the `wraps` field. It uses the same YAML configuration format (with an additional `validation` block and optional `wraps`/`transform` fields), and the same registries and resolution mechanisms. Validations are always read-only (`writes` is always `false`, `checkpointable` is always `false`). +!!! info "Purpose" + Register and attach ==validations== — a specialized subtype of Tool that extends the Tool class with pass/fail semantics and attachment scoping. A Validation inherits all base Tool properties (name, source, input_schema, capability, resource bindings, lifecycle hooks, etc.) and adds: a `mode` field (`required` or `informational`), and a structured JSON return format with a mandatory `passed` boolean, an optional `message` string, and an optional `data` object for arbitrary informational output. Since Validation extends Tool, it shares the same backing sources (custom, MCP, agent_skill, builtin) plus the additional `wrapped` source type for Validations that wrap an existing Tool via the `wraps` field. It uses the same YAML configuration format (with an additional `validation` block and optional `wraps`/`transform` fields), and the same registries and resolution mechanisms. Validations are always read-only (`writes` is always `false`, `checkpointable` is always `false`). Because Validations are a subtype of Tool and share the same Tool Registry and naming namespace, only validation-specific operations have dedicated subcommands here: `add` (registration with validation-specific fields like `mode`), `attach`, and `detach`. General tool operations — listing, inspection, and removal — are handled through the `agents tool` commands: @@ -2619,54 +8643,245 @@ Register a new validation. The validation is fully defined by the YAML configura **Examples** -

-$ agents validation add --config ./validations/run-tests.yaml
+=== "Rich"
 
-╭─ Validation Registered ────────────────────────────────╮
-│ Name: local/run-tests                                  │
-│ Description: Run unit tests with coverage               │
-│ Source: custom                                         │
-│ Mode: required                                         │
-│ Config: ./validations/run-tests.yaml                   │
-│ Created: 2026-02-09 10:15                              │
-╰────────────────────────────────────────────────────────╯
+    

+    $ agents validation add --config ./validations/run-tests.yaml
 
-╭─ Capability ────────────────────────╮
-│ Read-Only: true (enforced)         │
-│ Checkpointable: false (enforced)   │
-│ Timeout: 600s                      │
-╰─────────────────────────────────────╯
+    ╭─ Validation Registered ────────────────────────────────╮
+    │ Name: local/run-tests                                  │
+    │ Description: Run unit tests with coverage               │
+    │ Source: custom                                         │
+    │ Mode: required                                         │
+    │ Config: ./validations/run-tests.yaml                   │
+    │ Created: 2026-02-09 10:15                              │
+    ╰────────────────────────────────────────────────────────╯
 
-✓ OK Validation registered
-

+    ╭─ Capability ────────────────────────╮
+    │ Read-Only: true (enforced)         │
+    │ Checkpointable: false (enforced)   │
+    │ Timeout: 600s                      │
+    ╰─────────────────────────────────────╯
 
-

-$ agents validation add --config ./validations/lint-check.yaml
+    ✓ OK Validation registered
+    

 
-╭─ Validation Registered ──────────────╮
-│ Name: local/lint-check               │
-│ Description: Lint check              │
-│ Source: custom                       │
-│ Mode: required                       │
-│ Timeout: 300s                        │
-╰───────────────────────────────────────╯
+=== "Plain"
 
-✓ OK Validation registered
-
+ ``` + $ agents validation add --config ./validations/run-tests.yaml -

-$ agents validation add --config ./validations/check-bundle-size.yaml
+    Validation Registered
+      Name: local/run-tests
+      Description: Run unit tests with coverage
+      Source: custom
+      Mode: required
+      Config: ./validations/run-tests.yaml
+      Created: 2026-02-09 10:15
 
-╭─ Validation Registered ───────────────────────────╮
-│ Name: local/check-bundle-size                     │
-│ Description: Check bundle size (advisory)        │
-│ Source: custom                                    │
-│ Mode: informational                              │
-│ Timeout: 300s                                    │
-╰───────────────────────────────────────────────────╯
+    Capability
+      Read-Only: true (enforced)
+      Checkpointable: false (enforced)
+      Timeout: 600s
 
-✓ OK Validation registered
-
+ [OK] Validation registered + ``` + +=== "JSON" + + ```json + { + "command": "validation add", + "status": "ok", + "exit_code": 0, + "data": { + "validation_registered": { + "name": "local/run-tests", + "description": "Run unit tests with coverage", + "source": "custom", + "mode": "required", + "config": "./validations/run-tests.yaml", + "created": "2026-02-09 10:15" + }, + "capability": { + "read_only": "true (enforced)", + "checkpointable": "false (enforced)", + "timeout": "600s" + } + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 120 }, + "messages": ["Validation registered"] + } + ``` + +=== "YAML" + + ```yaml + command: validation add + status: ok + exit_code: 0 + data: + validation_registered: + name: local/run-tests + description: Run unit tests with coverage + source: custom + mode: required + config: ./validations/run-tests.yaml + created: "2026-02-09 10:15" + capability: + read_only: "true (enforced)" + checkpointable: "false (enforced)" + timeout: 600s + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 120 + messages: + - "Validation registered" + ``` + +=== "Rich" + + 

+    $ agents validation add --config ./validations/lint-check.yaml
+
+    ╭─ Validation Registered ──────────────╮
+    │ Name: local/lint-check               │
+    │ Description: Lint check              │
+    │ Source: custom                       │
+    │ Mode: required                       │
+    │ Timeout: 300s                        │
+    ╰───────────────────────────────────────╯
+
+    ✓ OK Validation registered
+
+ +=== "Plain" + + ``` + $ agents validation add --config ./validations/lint-check.yaml + + Validation Registered + Name: local/lint-check + Description: Lint check + Source: custom + Mode: required + Timeout: 300s + + [OK] Validation registered + ``` + +=== "JSON" + + ```json + { + "command": "validation add", + "status": "ok", + "exit_code": 0, + "data": { + "validation_registered": { + "name": "local/lint-check", + "description": "Lint check", + "source": "custom", + "mode": "required", + "timeout": "300s" + } + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 95 }, + "messages": ["Validation registered"] + } + ``` + +=== "YAML" + + ```yaml + command: validation add + status: ok + exit_code: 0 + data: + validation_registered: + name: local/lint-check + description: Lint check + source: custom + mode: required + timeout: 300s + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 95 + messages: + - "Validation registered" + ``` + +=== "Rich" + + 

+    $ agents validation add --config ./validations/check-bundle-size.yaml
+
+    ╭─ Validation Registered ───────────────────────────╮
+    │ Name: local/check-bundle-size                     │
+    │ Description: Check bundle size (advisory)        │
+    │ Source: custom                                    │
+    │ Mode: informational                              │
+    │ Timeout: 300s                                    │
+    ╰───────────────────────────────────────────────────╯
+
+    ✓ OK Validation registered
+
+ +=== "Plain" + + ``` + $ agents validation add --config ./validations/check-bundle-size.yaml + + Validation Registered + Name: local/check-bundle-size + Description: Check bundle size (advisory) + Source: custom + Mode: informational + Timeout: 300s + + [OK] Validation registered + ``` + +=== "JSON" + + ```json + { + "command": "validation add", + "status": "ok", + "exit_code": 0, + "data": { + "validation_registered": { + "name": "local/check-bundle-size", + "description": "Check bundle size (advisory)", + "source": "custom", + "mode": "informational", + "timeout": "300s" + } + }, + "timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 88 }, + "messages": ["Validation registered"] + } + ``` + +=== "YAML" + + ```yaml + command: validation add + status: ok + exit_code: 0 + data: + validation_registered: + name: local/check-bundle-size + description: "Check bundle size (advisory)" + source: custom + mode: informational + timeout: 300s + timing: + started: "2026-02-09T10:16:00Z" + duration_ms: 88 + messages: + - "Validation registered" + ``` ##### agents validation attach @@ -2688,52 +8903,236 @@ The command returns a system-assigned **attachment ULID** that uniquely identifi **Examples** -

-$ agents validation attach --project local/api-service local/api-repo local/run-tests
+=== "Rich"
 
-╭─ Validation Attached ──────────────────────────────────────╮
-│ Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0       │
-│ Validation: local/run-tests                              │
-│ Mode: required                                          │
-│ Resource: local/api-repo                                │
-│ Scope: project local/api-service                        │
-╰────────────────────────────────────────────────────────────╯
+    

+    $ agents validation attach --project local/api-service local/api-repo local/run-tests
 
-✓ OK Validation attached
-

+    ╭─ Validation Attached ──────────────────────────────────────╮
+    │ Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0       │
+    │ Validation: local/run-tests                              │
+    │ Mode: required                                          │
+    │ Resource: local/api-repo                                │
+    │ Scope: project local/api-service                        │
+    ╰────────────────────────────────────────────────────────────╯
 
-

-$ agents validation attach local/api-repo local/lint-check
+    ✓ OK Validation attached
+    

 
-╭─ Validation Attached ──────────────────────────────────────╮
-│ Attachment ID: 01HXM5B2C3D4E5F6G7H8J9K0L1       │
-│ Validation: local/lint-check                             │
-│ Mode: required                                          │
-│ Resource: local/api-repo                                │
-│ Scope: direct (always active)                           │
-│ This validation will run for ALL plans/projects           │
-│ that access this resource.                               │
-╰────────────────────────────────────────────────────────────╯
+=== "Plain"
 
-✓ OK Validation attached
-
+ ``` + $ agents validation attach --project local/api-service local/api-repo local/run-tests + + Validation Attached + Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0 + Validation: local/run-tests + Mode: required + Resource: local/api-repo + Scope: project local/api-service + + [OK] Validation attached + ``` + +=== "JSON" + + ```json + { + "command": "validation attach", + "status": "ok", + "exit_code": 0, + "data": { + "validation_attached": { + "attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0", + "validation": "local/run-tests", + "mode": "required", + "resource": "local/api-repo", + "scope": "project local/api-service" + } + }, + "timing": { "started": "2026-02-09T10:20:00Z", "duration_ms": 45 }, + "messages": ["Validation attached"] + } + ``` + +=== "YAML" + + ```yaml + command: validation attach + status: ok + exit_code: 0 + data: + validation_attached: + attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0 + validation: local/run-tests + mode: required + resource: local/api-repo + scope: project local/api-service + timing: + started: "2026-02-09T10:20:00Z" + duration_ms: 45 + messages: + - "Validation attached" + ``` + +=== "Rich" + + 

+    $ agents validation attach local/api-repo local/lint-check
+
+    ╭─ Validation Attached ──────────────────────────────────────╮
+    │ Attachment ID: 01HXM5B2C3D4E5F6G7H8J9K0L1       │
+    │ Validation: local/lint-check                             │
+    │ Mode: required                                          │
+    │ Resource: local/api-repo                                │
+    │ Scope: direct (always active)                           │
+    │ This validation will run for ALL plans/projects           │
+    │ that access this resource.                               │
+    ╰────────────────────────────────────────────────────────────╯
+
+    ✓ OK Validation attached
+
+ +=== "Plain" + + ``` + $ agents validation attach local/api-repo local/lint-check + + Validation Attached + Attachment ID: 01HXM5B2C3D4E5F6G7H8J9K0L1 + Validation: local/lint-check + Mode: required + Resource: local/api-repo + Scope: direct (always active) + This validation will run for ALL plans/projects + that access this resource. + + [OK] Validation attached + ``` + +=== "JSON" + + ```json + { + "command": "validation attach", + "status": "ok", + "exit_code": 0, + "data": { + "validation_attached": { + "attachment_id": "01HXM5B2C3D4E5F6G7H8J9K0L1", + "validation": "local/lint-check", + "mode": "required", + "resource": "local/api-repo", + "scope": "direct (always active)", + "note": "This validation will run for ALL plans/projects that access this resource." + } + }, + "timing": { "started": "2026-02-09T10:21:00Z", "duration_ms": 42 }, + "messages": ["Validation attached"] + } + ``` + +=== "YAML" + + ```yaml + command: validation attach + status: ok + exit_code: 0 + data: + validation_attached: + attachment_id: 01HXM5B2C3D4E5F6G7H8J9K0L1 + validation: local/lint-check + mode: required + resource: local/api-repo + scope: "direct (always active)" + note: "This validation will run for ALL plans/projects that access this resource." + timing: + started: "2026-02-09T10:21:00Z" + duration_ms: 42 + messages: + - "Validation attached" + ``` Attaching with validation-specific arguments: -

-$ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90
+=== "Rich"
 
-╭─ Validation Attached ──────────────────────────────────────╮
-│ Attachment ID: 01HXM5C3D4E5F6G7H8J9K0L1M2       │
-│ Validation: local/run-tests                              │
-│ Mode: required                                          │
-│ Resource: local/api-repo                                │
-│ Scope: project local/api-service                        │
-│ Args: coverage_threshold=90                              │
-╰────────────────────────────────────────────────────────────╯
+    

+    $ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90
 
-✓ OK Validation attached
-

+    ╭─ Validation Attached ──────────────────────────────────────╮
+    │ Attachment ID: 01HXM5C3D4E5F6G7H8J9K0L1M2       │
+    │ Validation: local/run-tests                              │
+    │ Mode: required                                          │
+    │ Resource: local/api-repo                                │
+    │ Scope: project local/api-service                        │
+    │ Args: coverage_threshold=90                              │
+    ╰────────────────────────────────────────────────────────────╯
+
+    ✓ OK Validation attached
+
+ +=== "Plain" + + ``` + $ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90 + + Validation Attached + Attachment ID: 01HXM5C3D4E5F6G7H8J9K0L1M2 + Validation: local/run-tests + Mode: required + Resource: local/api-repo + Scope: project local/api-service + Args: coverage_threshold=90 + + [OK] Validation attached + ``` + +=== "JSON" + + ```json + { + "command": "validation attach", + "status": "ok", + "exit_code": 0, + "data": { + "validation_attached": { + "attachment_id": "01HXM5C3D4E5F6G7H8J9K0L1M2", + "validation": "local/run-tests", + "mode": "required", + "resource": "local/api-repo", + "scope": "project local/api-service", + "args": { + "coverage_threshold": 90 + } + } + }, + "timing": { "started": "2026-02-09T10:22:00Z", "duration_ms": 48 }, + "messages": ["Validation attached"] + } + ``` + +=== "YAML" + + ```yaml + command: validation attach + status: ok + exit_code: 0 + data: + validation_attached: + attachment_id: 01HXM5C3D4E5F6G7H8J9K0L1M2 + validation: local/run-tests + mode: required + resource: local/api-repo + scope: project local/api-service + args: + coverage_threshold: 90 + timing: + started: "2026-02-09T10:22:00Z" + duration_ms: 48 + messages: + - "Validation attached" + ``` ##### agents validation detach @@ -2749,20 +9148,79 @@ Detach a validation by its attachment ULID. The attachment ULID is returned by ` **Examples** -

-$ agents validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0
+=== "Rich"
 
-Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y
+    

+    $ agents validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0
 
-╭─ Validation Detached ───────────────────────────────────────╮
-│ Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0        │
-│ Validation: local/run-tests                               │
-│ Resource: local/api-repo                                  │
-│ Scope: project local/api-service                          │
-╰─────────────────────────────────────────────────────────────╯
+    Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y
 
-✓ OK Validation detached
-

+    ╭─ Validation Detached ───────────────────────────────────────╮
+    │ Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0        │
+    │ Validation: local/run-tests                               │
+    │ Resource: local/api-repo                                  │
+    │ Scope: project local/api-service                          │
+    ╰─────────────────────────────────────────────────────────────╯
+
+    ✓ OK Validation detached
+
+ +=== "Plain" + + ``` + $ agents validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0 + + Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y + + Validation Detached + Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0 + Validation: local/run-tests + Resource: local/api-repo + Scope: project local/api-service + + [OK] Validation detached + ``` + +=== "JSON" + + ```json + { + "command": "validation detach", + "status": "ok", + "exit_code": 0, + "data": { + "validation_detached": { + "attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0", + "validation": "local/run-tests", + "resource": "local/api-repo", + "scope": "project local/api-service" + }, + "confirmation": "Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y" + }, + "timing": { "started": "2026-02-09T10:25:00Z", "duration_ms": 1200 }, + "messages": ["Validation detached"] + } + ``` + +=== "YAML" + + ```yaml + command: validation detach + status: ok + exit_code: 0 + data: + validation_detached: + attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0 + validation: local/run-tests + resource: local/api-repo + scope: project local/api-service + confirmation: "Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y" + timing: + started: "2026-02-09T10:25:00Z" + duration_ms: 1200 + messages: + - "Validation detached" + ``` #### agents resource type @@ -2783,43 +9241,139 @@ Register a new custom resource type. The resource type is fully defined by the Y **Examples** -

-$ agents resource type add --config ./resource-types/svn.yaml
+=== "Rich"
 
-╭─ Resource Type ────────────────────╮
-│ Name: local/svn                    │
-│ Physical/Virtual: physical         │
-│ User Addable: yes                  │
-│ Registered: 2026-02-09 10:15       │
-╰────────────────────────────────────╯
+    

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

+    ╭─ Sandbox ──────────────────────╮
+    │ Strategy: copy_on_write        │
+    │ Handler: SVNHandler (custom)   │
+    ╰────────────────────────────────╯
+
+    ✓ OK Resource type registered
+    ℹ New subcommand available: agents resource add local/svn
+
+ +=== "Plain" + + ``` + $ agents resource type add --config ./resource-types/svn.yaml + + Resource Type + Name: local/svn + 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 + + Sandbox + Strategy: copy_on_write + Handler: SVNHandler (custom) + + [OK] Resource type registered + Info: New subcommand available: agents resource add local/svn + ``` + +=== "JSON" + + ```json + { + "command": "resource type add", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/svn", + "physical_virtual": "physical", + "user_addable": true, + "registered": "2026-02-09T10:15:00Z", + "cli_arguments": [ + { "argument": "--url", "required": true, "description": "Repository URL" }, + { "argument": "--checkout", "required": false, "description": "Local checkout" } + ], + "child_types": { + "auto_discover": ["svn-revision", "svn-file"], + "manual_link": ["fs-mount"] + }, + "sandbox": { + "strategy": "copy_on_write", + "handler": "SVNHandler (custom)" + } + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 85 }, + "messages": ["Resource type registered", "New subcommand available: agents resource add local/svn"] + } + ``` + +=== "YAML" + + ```yaml + command: resource type add + status: ok + exit_code: 0 + data: + name: local/svn + physical_virtual: physical + user_addable: true + registered: "2026-02-09T10:15:00Z" + cli_arguments: + - argument: "--url" + required: true + description: Repository URL + - argument: "--checkout" + required: false + description: Local checkout + child_types: + auto_discover: + - svn-revision + - svn-file + manual_link: + - fs-mount + sandbox: + strategy: copy_on_write + handler: "SVNHandler (custom)" + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 85 + messages: + - "Resource type registered" + - "New subcommand available: agents resource add local/svn" + ``` ##### agents resource type remove 
agents resource type remove [--yes|-y] <NAME>
-**Purpose** -Remove a custom resource type. Built-in types cannot be removed. Fails if any registered resources use this type. +!!! warning "Destructive Operation" + Remove a custom resource type. ==Built-in types cannot be removed.== Fails if any registered resources currently use this type — remove those resources first. **Arguments** @@ -2828,19 +9382,70 @@ Remove a custom resource type. Built-in types cannot be removed. Fails if any re **Examples** -

-$ agents resource type remove local/svn
+=== "Rich"
 
-Remove resource type local/svn? [y/N]: y
+    

+    $ agents resource type remove local/svn
 
-╭─ Resource Type Removed ───────╮
-│ Name: local/svn               │
-│ Resources Using: 0            │
-│ Subcommand Removed: yes       │
-╰───────────────────────────────╯
+    Remove resource type local/svn? [y/N]: y
 
-✓ OK Resource type removed
-

+    ╭─ Resource Type Removed ───────╮
+    │ Name: local/svn               │
+    │ Resources Using: 0            │
+    │ Subcommand Removed: yes       │
+    ╰───────────────────────────────╯
+
+    ✓ OK Resource type removed
+
+ +=== "Plain" + + ``` + $ 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 + + [OK] Resource type removed + ``` + +=== "JSON" + + ```json + { + "command": "resource type remove", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/svn", + "resources_using": 0, + "subcommand_removed": true + }, + "timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 60 }, + "messages": ["Resource type removed"] + } + ``` + +=== "YAML" + + ```yaml + command: resource type remove + status: ok + exit_code: 0 + data: + name: local/svn + resources_using: 0 + subcommand_removed: true + timing: + started: "2026-02-09T10:16:00Z" + duration_ms: 60 + messages: + - "Resource type removed" + ``` ##### agents resource type list @@ -2855,49 +9460,284 @@ None (use the global `--format` option to control output format). **Examples** -

-$ agents resource type list
+=== "Rich"
 
-╭─ 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                          │
-╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents resource type list
 
-╭─ Summary ─────────────────╮
-│ Built-in: 24              │
-│ Custom: 1                 │
-│ User Addable: 4           │
-╰───────────────────────────╯
+    ╭─ 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                          │
+    ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 25 resource types listed
-

+    ╭─ Summary ─────────────────╮
+    │ Built-in: 24              │
+    │ Custom: 1                 │
+    │ User Addable: 4           │
+    ╰───────────────────────────╯
+
+    ✓ OK 25 resource types listed
+
+ +=== "Plain" + + ``` + $ 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 + + Summary + Built-in: 24 + Custom: 1 + User Addable: 4 + + [OK] 25 resource types listed + ``` + +=== "JSON" + + ```json + { + "command": "resource type list", + "status": "ok", + "exit_code": 0, + "data": { + "resource_types": [ + { "name": "git-checkout", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["git", "fs-directory"] }, + { "name": "git", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["git-remote", "git-branch", "git-tag", "git-commit", "git-stash", "git-submodule"] }, + { "name": "git-remote", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "git-branch", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-commit"] }, + { "name": "git-tag", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "git-commit", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-tree"] }, + { "name": "git-tree", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-tree-entry"] }, + { "name": "git-tree-entry", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "git-stash", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "git-submodule", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "fs-mount", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["fs-directory"] }, + { "name": "fs-directory", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["fs-file", "fs-directory", "fs-symlink", "fs-hardlink"] }, + { "name": "fs-file", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "fs-symlink", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "fs-hardlink", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] }, + { "name": "file", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "directory", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "symlink", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "commit", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "branch", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "tag", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "remote", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "submodule", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "tree", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] }, + { "name": "local/svn", "source": "custom", "physical_virtual": "physical", "addable": true, "auto_children": ["svn-revision", "svn-file"] } + ], + "summary": { + "built_in": 24, + "custom": 1, + "user_addable": 4 + } + }, + "timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 45 }, + "messages": ["25 resource types listed"] + } + ``` + +=== "YAML" + + ```yaml + command: resource type list + status: ok + exit_code: 0 + data: + resource_types: + - name: git-checkout + source: built-in + physical_virtual: physical + addable: true + auto_children: [git, fs-directory] + - name: git + source: built-in + physical_virtual: physical + addable: true + auto_children: [git-remote, git-branch, git-tag, git-commit, git-stash, git-submodule] + - name: git-remote + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: git-branch + source: built-in + physical_virtual: physical + addable: false + auto_children: [git-commit] + - name: git-tag + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: git-commit + source: built-in + physical_virtual: physical + addable: false + auto_children: [git-tree] + - name: git-tree + source: built-in + physical_virtual: physical + addable: false + auto_children: [git-tree-entry] + - name: git-tree-entry + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: git-stash + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: git-submodule + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: fs-mount + source: built-in + physical_virtual: physical + addable: true + auto_children: [fs-directory] + - name: fs-directory + source: built-in + physical_virtual: physical + addable: true + auto_children: [fs-file, fs-directory, fs-symlink, fs-hardlink] + - name: fs-file + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: fs-symlink + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: fs-hardlink + source: built-in + physical_virtual: physical + addable: false + auto_children: [] + - name: file + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: directory + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: symlink + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: commit + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: branch + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: tag + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: remote + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: submodule + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: tree + source: built-in + physical_virtual: virtual + addable: false + auto_children: [] + - name: local/svn + source: custom + physical_virtual: physical + addable: true + auto_children: [svn-revision, svn-file] + summary: + built_in: 24 + custom: 1 + user_addable: 4 + timing: + started: "2026-02-09T10:16:00Z" + duration_ms: 45 + messages: + - "25 resource types listed" + ``` ##### agents resource type show @@ -2912,48 +9752,175 @@ Show detailed information about a resource type, including its full schema. **Examples** -

-$ agents resource type show git-checkout
+=== "Rich"
 
-╭─ Resource Type ──────────────────────────────────────────────────────╮
-│ Name: git-checkout                                                   │
-│ Source: built-in                                                     │
-│ Description: A locally checked-out git repository with worktree      │
-│ Physical/Virtual: physical                                           │
-│ User Addable: yes                                                    │
-╰──────────────────────────────────────────────────────────────────────╯
+    

+    $ agents resource type show git-checkout
 
-╭─ CLI Arguments (agents resource add git-checkout) ─────────────────╮
-│ Argument    Required  Type    Description                          │
-│ ──────────  ────────  ──────  ──────────────────────────────       │
-│ --path      yes       path    Local checkout directory             │
-│ --branch    no        string  Default branch (default: main)       │
-╰────────────────────────────────────────────────────────────────────╯
+    ╭─ Resource Type ──────────────────────────────────────────────────────╮
+    │ Name: git-checkout                                                   │
+    │ Source: built-in                                                     │
+    │ Description: A locally checked-out git repository with worktree      │
+    │ Physical/Virtual: physical                                           │
+    │ User Addable: yes                                                    │
+    ╰──────────────────────────────────────────────────────────────────────╯
 
-╭─ Parent Types ───────────────╮
-│ Allowed: (any, top-level OK) │
-╰──────────────────────────────╯
+    ╭─ CLI Arguments (agents resource add git-checkout) ─────────────────╮
+    │ Argument    Required  Type    Description                          │
+    │ ──────────  ────────  ──────  ──────────────────────────────       │
+    │ --path      yes       path    Local checkout directory             │
+    │ --branch    no        string  Default branch (default: main)       │
+    ╰────────────────────────────────────────────────────────────────────╯
 
-╭─ Child Types ────────────────────────────────────────────────────╮
-│ Type           Auto  Manual Link  Description                    │
-│ ─────────────  ────  ───────────  ──────────────────────────     │
-│ git            yes   no           Repo object DB and history     │
-│ fs-directory   yes   no           Worktree root directory        │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ Parent Types ───────────────╮
+    │ Allowed: (any, top-level OK) │
+    ╰──────────────────────────────╯
 
-╭─ Sandbox ──────────────────────╮
-│ Strategy: git_worktree         │
-│ Checkpointable: yes            │
-│ Handler: GitCheckoutHandler    │
-╰────────────────────────────────╯
+    ╭─ Child Types ────────────────────────────────────────────────────╮
+    │ Type           Auto  Manual Link  Description                    │
+    │ ─────────────  ────  ───────────  ──────────────────────────     │
+    │ git            yes   no           Repo object DB and history     │
+    │ fs-directory   yes   no           Worktree root directory        │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-✓ OK Resource type details loaded
-

+    ╭─ Sandbox ──────────────────────╮
+    │ Strategy: git_worktree         │
+    │ Checkpointable: yes            │
+    │ Handler: GitCheckoutHandler    │
+    ╰────────────────────────────────╯
+
+    ✓ OK Resource type details loaded
+
+ +=== "Plain" + + ``` + $ 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 + + CLI Arguments (agents resource add git-checkout) + Argument Required Type Description + ---------- -------- ------ ------------------------------ + --path yes path Local checkout directory + --branch no string Default branch (default: main) + + Parent Types + Allowed: (any, top-level OK) + + Child Types + 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 + + [OK] Resource type details loaded + ``` + +=== "JSON" + + ```json + { + "command": "resource type show", + "status": "ok", + "exit_code": 0, + "data": { + "name": "git-checkout", + "source": "built-in", + "description": "A locally checked-out git repository with worktree", + "physical_virtual": "physical", + "user_addable": true, + "cli_arguments": [ + { "argument": "--path", "required": true, "type": "path", "description": "Local checkout directory" }, + { "argument": "--branch", "required": false, "type": "string", "description": "Default branch (default: main)" } + ], + "parent_types": { + "allowed": "any", + "top_level": true + }, + "child_types": [ + { "type": "git", "auto": true, "manual_link": false, "description": "Repo object DB and history" }, + { "type": "fs-directory", "auto": true, "manual_link": false, "description": "Worktree root directory" } + ], + "sandbox": { + "strategy": "git_worktree", + "checkpointable": true, + "handler": "GitCheckoutHandler" + } + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 42 }, + "messages": ["Resource type details loaded"] + } + ``` + +=== "YAML" + + ```yaml + command: resource type show + status: ok + exit_code: 0 + data: + name: git-checkout + source: built-in + description: "A locally checked-out git repository with worktree" + physical_virtual: physical + user_addable: true + cli_arguments: + - argument: "--path" + required: true + type: path + description: "Local checkout directory" + - argument: "--branch" + required: false + type: string + description: "Default branch (default: main)" + parent_types: + allowed: any + top_level: true + child_types: + - type: git + auto: true + manual_link: false + description: "Repo object DB and history" + - type: fs-directory + auto: true + manual_link: false + description: "Worktree root directory" + sandbox: + strategy: git_worktree + checkpointable: true + handler: GitCheckoutHandler + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 42 + messages: + - "Resource type details loaded" + ``` #### agents resource -**Purpose** -Manage independently registered resources. Resources represent anything that can be read, written, or queried — git repositories, filesystems, databases, APIs, and more. Resources are registered independently of projects and linked to one or more projects via `agents project link-resource`. Resources form a directed acyclic graph (DAG) with parent/child relationships, and child resources are often auto-discovered when a parent resource is registered. +!!! info "Purpose" + Manage independently registered ==resources==. Resources represent anything that can be read, written, or queried — git repositories, filesystems, databases, APIs, and more. Resources are registered independently of projects and linked to one or more projects via `agents project link-resource`. Resources form a ==directed acyclic graph (DAG)== with parent/child relationships, and child resources are often auto-discovered when a parent resource is registered. + +??? example "Supported Resource Types" + | Type | Physical | Description | + | :--- | :------: | :---------- | + | `git-checkout` | Yes | Local git working directory | + | `git` | Yes | Bare git repository | + | `fs-mount` | Yes | Filesystem mount point | + | `fs-directory` | Virtual | Directory within a mount | + | `fs-file` | Virtual | Individual file reference | + | Custom types | Varies | Registered via `agents resource type add` | ##### agents resource add @@ -2974,78 +9941,231 @@ The command returns the name and ULID of the newly created resource. Auto-discov **Examples** -

-$ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
+=== "Rich"
 
-╭─ Resource ──────────────────────────────────────╮
-│ Name: local/api-repo                            │
-│ ID: 01HXR1A1B2C3D4E5F6G7H8J9K0                  │
-│ Type: git-checkout                              │
-│ Physical/Virtual: physical                      │
-│ Path: /home/user/projects/api-service           │
-│ Branch: main                                    │
-│ Created: 2026-02-09 10:20                       │
-╰─────────────────────────────────────────────────╯
+    

+    $ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
 
-╭─ Auto-discovered Children ─────────────────────────────────────────╮
-│ ID               Type            Status                            │
-│ ───────────────  ──────────────  ─────────────────                 │
-│ 01HXR1A1B2C3…   git             created                            │
-│ 01HXR1A1B2C4…   git-remote      created                            │
-│ 01HXR1A1B2C5…   git-branch      created                            │
-│ 01HXR1A1B2C6…   git-branch      created                            │
-│ 01HXR1A1B2C7…   fs-directory    created                            │
-│   + 47 git-commit resources                                        │
-│   + 312 git-tree-entry resources                                   │
-│   + 3 fs-directory + 28 fs-file                                    │
-╰────────────────────────────────────────────────────────────────────╯
+    ╭─ Resource ──────────────────────────────────────╮
+    │ Name: local/api-repo                            │
+    │ ID: 01HXR1A1B2C3D4E5F6G7H8J9K0                  │
+    │ 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 │
-╰────────────────────────────────╯
+    ╭─ Auto-discovered Children ─────────────────────────────────────────╮
+    │ ID               Type            Status                            │
+    │ ───────────────  ──────────────  ─────────────────                 │
+    │ 01HXR1A1B2C3…   git             created                            │
+    │ 01HXR1A1B2C4…   git-remote      created                            │
+    │ 01HXR1A1B2C5…   git-branch      created                            │
+    │ 01HXR1A1B2C6…   git-branch      created                            │
+    │ 01HXR1A1B2C7…   fs-directory    created                            │
+    │   + 47 git-commit resources                                        │
+    │   + 312 git-tree-entry resources                                   │
+    │   + 3 fs-directory + 28 fs-file                                    │
+    ╰────────────────────────────────────────────────────────────────────╯
 
-✓ OK Resource registered (395 child resources discovered)
-

+    ╭─ Capabilities ─────────────────╮
+    │ Readable: yes                  │
+    │ Writable: yes                  │
+    │ Sandboxable: yes               │
+    │ Checkpointable: yes            │
+    │ Sandbox Strategy: git_worktree │
+    ╰────────────────────────────────╯
 
-

-$ agents resource add fs-mount local/docs --mount-path /docs/api-reference
+    ✓ OK Resource registered (395 child resources discovered)
+    

 
-╭─ Resource ──────────────────────────────────────╮
-│ Name: local/docs                                │
-│ ID: 01HXR2B3C4D5E6F7G8H9J0K1L2                  │
-│ Type: fs-mount                                  │
-│ Physical/Virtual: physical                      │
-│ Mount Path: /docs/api-reference                 │
-│ Created: 2026-02-09 10:22                       │
-╰─────────────────────────────────────────────────╯
+    

+    $ agents resource add fs-mount local/docs --mount-path /docs/api-reference
 
-╭─ Auto-discovered Children ────────────────────╮
-│   + 1 fs-directory (root)                     │
-│   + 3 fs-directory resources                  │
-│   + 28 fs-file resources                      │
-╰───────────────────────────────────────────────╯
+    ╭─ Resource ──────────────────────────────────────╮
+    │ Name: local/docs                                │
+    │ ID: 01HXR2B3C4D5E6F7G8H9J0K1L2                  │
+    │ Type: fs-mount                                  │
+    │ Physical/Virtual: physical                      │
+    │ Mount Path: /docs/api-reference                 │
+    │ Created: 2026-02-09 10:22                       │
+    ╰─────────────────────────────────────────────────╯
 
-╭─ Capabilities ──────────────────────╮
-│ Readable: yes                       │
-│ Writable: yes                       │
-│ Sandboxable: yes                    │
-│ Checkpointable: yes                 │
-│ Sandbox Strategy: copy_on_write     │
-╰─────────────────────────────────────╯
+    ╭─ Auto-discovered Children ────────────────────╮
+    │   + 1 fs-directory (root)                     │
+    │   + 3 fs-directory resources                  │
+    │   + 28 fs-file resources                      │
+    ╰───────────────────────────────────────────────╯
 
-✓ OK Resource registered (31 child resources discovered)
-

+    ╭─ Capabilities ──────────────────────╮
+    │ Readable: yes                       │
+    │ Writable: yes                       │
+    │ Sandboxable: yes                    │
+    │ Checkpointable: yes                 │
+    │ Sandbox Strategy: copy_on_write     │
+    ╰─────────────────────────────────────╯
+
+    ✓ OK Resource registered (31 child resources discovered)
+
+ +=== "Plain" + + ``` + $ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main + + Resource + Name: local/api-repo + ID: 01HXR1A1B2C3D4E5F6G7H8J9K0 + Type: git-checkout + Physical/Virtual: physical + Path: /home/user/projects/api-service + Branch: main + Created: 2026-02-09 10:20 + + Auto-discovered Children + ID Type Status + --------------- -------------- ----------------- + 01HXR1A1B2C3.. git created + 01HXR1A1B2C4.. git-remote created + 01HXR1A1B2C5.. git-branch created + 01HXR1A1B2C6.. git-branch created + 01HXR1A1B2C7.. 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 + + [OK] Resource registered (395 child resources discovered) + + $ agents resource add fs-mount local/docs --mount-path /docs/api-reference + + Resource + Name: local/docs + ID: 01HXR2B3C4D5E6F7G8H9J0K1L2 + Type: fs-mount + Physical/Virtual: physical + Mount Path: /docs/api-reference + Created: 2026-02-09 10:22 + + Auto-discovered Children + + 1 fs-directory (root) + + 3 fs-directory resources + + 28 fs-file resources + + Capabilities + Readable: yes + Writable: yes + Sandboxable: yes + Checkpointable: yes + Sandbox Strategy: copy_on_write + + [OK] Resource registered (31 child resources discovered) + ``` + +=== "JSON" + + ```json + { + "command": "resource add", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/api-repo", + "id": "01HXR1A1B2C3D4E5F6G7H8J9K0", + "type": "git-checkout", + "physical_virtual": "physical", + "path": "/home/user/projects/api-service", + "branch": "main", + "created": "2026-02-09T10:20:00Z", + "auto_discovered_children": [ + { "id": "01HXR1A1B2C3…", "type": "git", "status": "created" }, + { "id": "01HXR1A1B2C4…", "type": "git-remote", "status": "created" }, + { "id": "01HXR1A1B2C5…", "type": "git-branch", "status": "created" }, + { "id": "01HXR1A1B2C6…", "type": "git-branch", "status": "created" }, + { "id": "01HXR1A1B2C7…", "type": "fs-directory", "status": "created" } + ], + "children_summary": { + "git_commit": 47, + "git_tree_entry": 312, + "fs_directory": 3, + "fs_file": 28 + }, + "total_children": 395, + "capabilities": { + "readable": true, + "writable": true, + "sandboxable": true, + "checkpointable": true, + "sandbox_strategy": "git_worktree" + } + }, + "timing": { "started": "2026-02-09T10:20:00Z", "duration_ms": 250 }, + "messages": ["Resource registered (395 child resources discovered)"] + } + ``` + +=== "YAML" + + ```yaml + command: resource add + status: ok + exit_code: 0 + data: + name: local/api-repo + id: 01HXR1A1B2C3D4E5F6G7H8J9K0 + type: git-checkout + physical_virtual: physical + path: /home/user/projects/api-service + branch: main + created: "2026-02-09T10:20:00Z" + auto_discovered_children: + - id: "01HXR1A1B2C3\u2026" + type: git + status: created + - id: "01HXR1A1B2C4\u2026" + type: git-remote + status: created + - id: "01HXR1A1B2C5\u2026" + type: git-branch + status: created + - id: "01HXR1A1B2C6\u2026" + type: git-branch + status: created + - id: "01HXR1A1B2C7\u2026" + type: fs-directory + status: created + children_summary: + git_commit: 47 + git_tree_entry: 312 + fs_directory: 3 + fs_file: 28 + total_children: 395 + capabilities: + readable: true + writable: true + sandboxable: true + checkpointable: true + sandbox_strategy: git_worktree + timing: + started: "2026-02-09T10:20:00Z" + duration_ms: 250 + messages: + - "Resource registered (395 child resources discovered)" + ``` ##### agents resource remove 
agents resource remove [--yes|-y] <NAME>
-**Purpose** -Remove a registered resource and all its auto-discovered child resources. Only user-added (named) resources can be removed. Fails if the resource is linked to any project (unlink first). +!!! danger "Cascading Deletion" + Removes a registered resource ==and all its auto-discovered child resources==. A `git-checkout` resource can have hundreds of child resources (files, directories). This operation fails if the resource is linked to any project — use `agents project unlink-resource` first. **Arguments** @@ -3054,20 +10174,74 @@ Remove a registered resource and all its auto-discovered child resources. Only u **Examples** -

-$ agents resource remove local/api-repo
+=== "Rich"
 
-Remove resource local/api-repo and 395 child resources? [y/N]: y
+    

+    $ agents resource remove local/api-repo
 
-╭─ Resource Removed ──────────────────────────────────╮
-│ Name: local/api-repo                                │
-│ Type: git-checkout                                  │
-│ Children Removed: 395                               │
-│ Projects Unlinked: 0                                │
-╰─────────────────────────────────────────────────────╯
+    Remove resource local/api-repo and 395 child resources? [y/N]: y
 
-✓ OK Resource removed
-

+    ╭─ Resource Removed ──────────────────────────────────╮
+    │ Name: local/api-repo                                │
+    │ Type: git-checkout                                  │
+    │ Children Removed: 395                               │
+    │ Projects Unlinked: 0                                │
+    ╰─────────────────────────────────────────────────────╯
+
+    ✓ OK Resource removed
+
+ +=== "Plain" + + ``` + $ agents resource remove local/api-repo + + 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 + + [OK] Resource removed + ``` + +=== "JSON" + + ```json + { + "command": "resource remove", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/api-repo", + "type": "git-checkout", + "children_removed": 395, + "projects_unlinked": 0 + }, + "timing": { "started": "2026-02-09T10:24:00Z", "duration_ms": 120 }, + "messages": ["Resource removed"] + } + ``` + +=== "YAML" + + ```yaml + command: resource remove + status: ok + exit_code: 0 + data: + name: local/api-repo + type: git-checkout + children_removed: 395 + projects_unlinked: 0 + timing: + started: "2026-02-09T10:24:00Z" + duration_ms: 120 + messages: + - "Resource removed" + ``` ##### agents resource list @@ -3083,27 +10257,139 @@ List registered resources with optional filters. By default, lists only user-add **Examples** -

-$ agents resource list
+=== "Rich"
 
-╭─ Resources ──────────────────────────────────────────────────────────────────────────────────────────────╮
-│ Name               ID                            Type         Phys/Virt  Children  Projects                 │
-│ ─────────────────  ────────────────────────────  ───────────  ─────────  ────────  ────────────────         │
-│ local/api-repo     01HXR1A1B2C3D4E5F6G7H8J9K0  git-checkout physical   395       local/api-service          │
-│ local/docs         01HXR2B2C3D4E5F6G7H8J9K0L1  fs-mount     physical   32        local/api-service          │
-│ local/staging-db   01HXR3C3D4E5F6G7H8J9K0L1M2  database     physical   12        local/api-service,         │
-│                                                                                   local/staging            │
-╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents resource list
 
-╭─ Summary ───────────╮
-│ Total: 3            │
-│ Physical: 3         │
-│ Virtual: 0          │
-│ Total Children: 405 │
-╰─────────────────────╯
+    ╭─ Resources ──────────────────────────────────────────────────────────────────────────────────────────────╮
+    │ Name               ID                            Type         Phys/Virt  Children  Projects                 │
+    │ ─────────────────  ────────────────────────────  ───────────  ─────────  ────────  ────────────────         │
+    │ local/api-repo     01HXR1A1B2C3D4E5F6G7H8J9K0  git-checkout physical   395       local/api-service          │
+    │ local/docs         01HXR2B2C3D4E5F6G7H8J9K0L1  fs-mount     physical   32        local/api-service          │
+    │ local/staging-db   01HXR3C3D4E5F6G7H8J9K0L1M2  database     physical   12        local/api-service,         │
+    │                                                                                   local/staging            │
+    ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 3 resources listed
-

+    ╭─ Summary ───────────╮
+    │ Total: 3            │
+    │ Physical: 3         │
+    │ Virtual: 0          │
+    │ Total Children: 405 │
+    ╰─────────────────────╯
+
+    ✓ OK 3 resources listed
+
+ +=== "Plain" + + ``` + $ agents resource list + + Resources + --------- + Name ID Type Phys/Virt Children Projects + ----------------- ---------------------------- ----------- --------- -------- ---------------- + local/api-repo 01HXR1A1B2C3D4E5F6G7H8J9K0 git-checkout physical 395 local/api-service + local/docs 01HXR2B2C3D4E5F6G7H8J9K0L1 fs-mount physical 32 local/api-service + local/staging-db 01HXR3C3D4E5F6G7H8J9K0L1M2 database physical 12 local/api-service, local/staging + + Summary + Total: 3 + Physical: 3 + Virtual: 0 + Total Children: 405 + + [OK] 3 resources listed + ``` + +=== "JSON" + + ```json + { + "command": "resource list", + "status": "ok", + "exit_code": 0, + "data": { + "resources": [ + { + "name": "local/api-repo", + "id": "01HXR1A1B2C3D4E5F6G7H8J9K0", + "type": "git-checkout", + "physical_virtual": "physical", + "children": 395, + "projects": ["local/api-service"] + }, + { + "name": "local/docs", + "id": "01HXR2B2C3D4E5F6G7H8J9K0L1", + "type": "fs-mount", + "physical_virtual": "physical", + "children": 32, + "projects": ["local/api-service"] + }, + { + "name": "local/staging-db", + "id": "01HXR3C3D4E5F6G7H8J9K0L1M2", + "type": "database", + "physical_virtual": "physical", + "children": 12, + "projects": ["local/api-service", "local/staging"] + } + ], + "summary": { + "total": 3, + "physical": 3, + "virtual": 0, + "total_children": 405 + } + }, + "timing": { "started": "2026-02-09T10:25:00Z", "duration_ms": 90 }, + "messages": ["3 resources listed"] + } + ``` + +=== "YAML" + + ```yaml + command: resource list + status: ok + exit_code: 0 + data: + resources: + - name: local/api-repo + id: 01HXR1A1B2C3D4E5F6G7H8J9K0 + type: git-checkout + physical_virtual: physical + children: 395 + projects: + - local/api-service + - name: local/docs + id: 01HXR2B2C3D4E5F6G7H8J9K0L1 + type: fs-mount + physical_virtual: physical + children: 32 + projects: + - local/api-service + - name: local/staging-db + id: 01HXR3C3D4E5F6G7H8J9K0L1M2 + type: database + physical_virtual: physical + children: 12 + projects: + - local/api-service + - local/staging + summary: + total: 3 + physical: 3 + virtual: 0 + total_children: 405 + timing: + started: "2026-02-09T10:25:00Z" + duration_ms: 90 + messages: + - "3 resources listed" + ``` ##### agents resource show @@ -3118,53 +10404,195 @@ Show detailed information about a registered resource including its type, capabi **Examples** -

-$ agents resource show local/api-repo
+=== "Rich"
 
-╭─ Resource ─────────────────────────────────────────╮
-│ Name: local/api-repo                               │
-│ ID: 01HXR1A1B2C3D4E5F6G7H8J9K0                     │
-│ Type: git-checkout                                 │
-│ Physical/Virtual: physical                         │
-│ Path: /home/user/projects/api-service              │
-│ Branch: main                                       │
-│ Created: 2026-02-09 10:20                          │
-╰────────────────────────────────────────────────────╯
+    

+    $ agents resource show local/api-repo
 
-╭─ Capabilities ────────────────────╮
-│ Readable: yes                     │
-│ Writable: yes                     │
-│ Sandboxable: yes                  │
-│ Checkpointable: yes               │
-│ Sandbox Strategy: git_worktree    │
-╰───────────────────────────────────╯
+    ╭─ Resource ─────────────────────────────────────────╮
+    │ Name: local/api-repo                               │
+    │ ID: 01HXR1A1B2C3D4E5F6G7H8J9K0                     │
+    │ Type: git-checkout                                 │
+    │ Physical/Virtual: physical                         │
+    │ Path: /home/user/projects/api-service              │
+    │ Branch: main                                       │
+    │ Created: 2026-02-09 10:20                          │
+    ╰────────────────────────────────────────────────────╯
 
-╭─ Parents ────╮
-│ (top-level)  │
-╰──────────────╯
+    ╭─ Capabilities ────────────────────╮
+    │ Readable: yes                     │
+    │ Writable: yes                     │
+    │ Sandboxable: yes                  │
+    │ Checkpointable: yes               │
+    │ Sandbox Strategy: git_worktree    │
+    ╰───────────────────────────────────╯
 
-╭─ Direct Children ──────────────────────────────────────────────────────╮
-│ ID                            Type          Auto  Children             │
-│ ────────────────────────────  ────────────  ────  ────────             │
-│ 01HXR4D4E5F6G7H8J9K0L1M2N3  git           yes   363                    │
-│ 01HXR5E5F6G7H8J9K0L1M2N3P4  fs-directory  yes   32                     │
-╰────────────────────────────────────────────────────────────────────────╯
+    ╭─ Parents ────╮
+    │ (top-level)  │
+    ╰──────────────╯
 
-╭─ Linked Projects ─────────────╮
-│ - local/api-service (r/w)     │
-╰───────────────────────────────╯
+    ╭─ Direct Children ──────────────────────────────────────────────────────╮
+    │ ID                            Type          Auto  Children             │
+    │ ────────────────────────────  ────────────  ────  ────────             │
+    │ 01HXR4D4E5F6G7H8J9K0L1M2N3  git           yes   363                    │
+    │ 01HXR5E5F6G7H8J9K0L1M2N3P4  fs-directory  yes   32                     │
+    ╰────────────────────────────────────────────────────────────────────────╯
 
-╭─ 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)    │
-╰────────────────────────────────────────────────╯
+    ╭─ Linked Projects ─────────────╮
+    │ - local/api-service (r/w)     │
+    ╰───────────────────────────────╯
 
-✓ OK Resource details loaded
-

+    ╭─ 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)    │
+    ╰────────────────────────────────────────────────╯
+
+    ✓ OK Resource details loaded
+
+ +=== "Plain" + + ``` + $ agents resource show local/api-repo + + Resource + Name: local/api-repo + ID: 01HXR1A1B2C3D4E5F6G7H8J9K0 + 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 + + Parents + (top-level) + + Direct Children + ID Type Auto Children + ---------------------------- ------------ ---- -------- + 01HXR4D4E5F6G7H8J9K0L1M2N3 git yes 363 + 01HXR5E5F6G7H8J9K0L1M2N3P4 fs-directory yes 32 + + Linked Projects + - local/api-service (r/w) + + 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) + + [OK] Resource details loaded + ``` + +=== "JSON" + + ```json + { + "command": "resource show", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/api-repo", + "id": "01HXR1A1B2C3D4E5F6G7H8J9K0", + "type": "git-checkout", + "physical_virtual": "physical", + "path": "/home/user/projects/api-service", + "branch": "main", + "created": "2026-02-09T10:20:00Z", + "capabilities": { + "readable": true, + "writable": true, + "sandboxable": true, + "checkpointable": true, + "sandbox_strategy": "git_worktree" + }, + "parents": ["(top-level)"], + "direct_children": [ + { "id": "01HXR4D4E5F6G7H8J9K0L1M2N3", "type": "git", "auto": true, "children": 363 }, + { "id": "01HXR5E5F6G7H8J9K0L1M2N3P4", "type": "fs-directory", "auto": true, "children": 32 } + ], + "linked_projects": [ + { "name": "local/api-service", "access": "r/w" } + ], + "tool_bindings": [ + { "tool": "(builtin) git_status", "slot": "repo", "access": "read_only" }, + { "tool": "(builtin) git_diff", "slot": "repo", "access": "read_only" }, + { "tool": "(builtin) git_log", "slot": "repo", "access": "read_only" }, + { "tool": "local/run-migrations", "slot": "db", "access": "(not bound)" } + ] + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 65 }, + "messages": ["Resource details loaded"] + } + ``` + +=== "YAML" + + ```yaml + command: resource show + status: ok + exit_code: 0 + data: + name: local/api-repo + id: 01HXR1A1B2C3D4E5F6G7H8J9K0 + type: git-checkout + physical_virtual: physical + path: /home/user/projects/api-service + branch: main + created: "2026-02-09T10:20:00Z" + capabilities: + readable: true + writable: true + sandboxable: true + checkpointable: true + sandbox_strategy: git_worktree + parents: + - (top-level) + direct_children: + - id: 01HXR4D4E5F6G7H8J9K0L1M2N3 + type: git + auto: true + children: 363 + - id: 01HXR5E5F6G7H8J9K0L1M2N3P4 + type: fs-directory + auto: true + children: 32 + linked_projects: + - name: local/api-service + access: r/w + tool_bindings: + - tool: (builtin) git_status + slot: repo + access: read_only + - tool: (builtin) git_diff + slot: repo + access: read_only + - tool: (builtin) git_log + slot: repo + access: read_only + - tool: local/run-migrations + slot: db + access: (not bound) + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 65 + messages: + - Resource details loaded + ``` ##### agents resource inspect @@ -3181,61 +10609,283 @@ Inspect a resource's contents. For file-based resources (git checkouts, filesyst **Examples** -

-$ agents resource inspect local/api-repo --tree
+=== "Rich"
 
-╭─ Resource Tree: local/api-repo ──────────────────────────────────────╮
-│                                                                     │
-│ /home/user/projects/api-service                                     │
-│ ├── src/                                                           │
-│ │   ├── api/                                                       │
-│ │   │   ├── __init__.py                                             │
-│ │   │   ├── auth/                                                   │
-│ │   │   │   ├── auth_middleware.py                                   │
-│ │   │   │   ├── token_service.py                                     │
-│ │   │   │   └── rbac.py                                              │
-│ │   │   ├── routes/                                                 │
-│ │   │   └── models/                                                 │
-│ │   └── utils/                                                     │
-│ ├── tests/                                                         │
-│ ├── README.md                                                       │
-│ └── pyproject.toml                                                   │
-│                                                                     │
-╰─────────────────────────────────────────────────────────────────────╯
+    

+    $ agents resource inspect local/api-repo --tree
 
-╭─ Summary ──────────────╮
-│ Directories: 8         │
-│ Files: 41               │
-│ Total Size: 284 KB      │
-╰────────────────────────╯
+    ╭─ Resource Tree: local/api-repo ──────────────────────────────────────╮
+    │                                                                     │
+    │ /home/user/projects/api-service                                     │
+    │ ├── src/                                                           │
+    │ │   ├── api/                                                       │
+    │ │   │   ├── __init__.py                                             │
+    │ │   │   ├── auth/                                                   │
+    │ │   │   │   ├── auth_middleware.py                                   │
+    │ │   │   │   ├── token_service.py                                     │
+    │ │   │   │   └── rbac.py                                              │
+    │ │   │   ├── routes/                                                 │
+    │ │   │   └── models/                                                 │
+    │ │   └── utils/                                                     │
+    │ ├── tests/                                                         │
+    │ ├── README.md                                                       │
+    │ └── pyproject.toml                                                   │
+    │                                                                     │
+    ╰─────────────────────────────────────────────────────────────────────╯
 
-✓ OK Resource tree displayed
-

+    ╭─ Summary ──────────────╮
+    │ Directories: 8         │
+    │ Files: 41               │
+    │ Total Size: 284 KB      │
+    ╰────────────────────────╯
 
-

-$ agents resource inspect local/api-repo --file src/api/auth/auth_middleware.py
+    ✓ OK Resource tree displayed
+    

 
-╭─ File: src/api/auth/auth_middleware.py ──────────────────╮
-│ Resource: local/api-repo                                │
-│ Size: 2.4 KB                                            │
-│ Language: Python                                         │
-│ Last Modified: 2026-02-10 14:32                          │
-╰──────────────────────────────────────────────────────────╯
+=== "Plain"
 
-  1 │ from fastapi import Request, HTTPException
-  2 │ from .token_service import validate_token
-  3 │
-  4 │ async def auth_middleware(request: Request):
-  5 │     token = request.headers.get("Authorization")
-  6 │     if not token:
-  7 │         raise HTTPException(status_code=401)
-  8 │     user = await validate_token(token)
-  9 │     request.state.user = user
- 10 │     return user
-    │ ... (24 more lines)
+    ```
+    $ agents resource inspect local/api-repo --tree
 
-✓ OK File displayed
-
+ Resource Tree: local/api-repo + + /home/user/projects/api-service + +-- src/ + | +-- api/ + | | +-- __init__.py + | | +-- auth/ + | | | +-- auth_middleware.py + | | | +-- token_service.py + | | | +-- rbac.py + | | +-- routes/ + | | +-- models/ + | +-- utils/ + +-- tests/ + +-- README.md + +-- pyproject.toml + + Summary + Directories: 8 + Files: 41 + Total Size: 284 KB + + [OK] Resource tree displayed + ``` + +=== "JSON" + + ```json + { + "command": "resource inspect", + "status": "ok", + "exit_code": 0, + "data": { + "resource": "local/api-repo", + "mode": "tree", + "root": "/home/user/projects/api-service", + "tree": [ + { + "name": "src/", + "type": "directory", + "children": [ + { + "name": "api/", + "type": "directory", + "children": [ + { "name": "__init__.py", "type": "file" }, + { + "name": "auth/", + "type": "directory", + "children": [ + { "name": "auth_middleware.py", "type": "file" }, + { "name": "token_service.py", "type": "file" }, + { "name": "rbac.py", "type": "file" } + ] + }, + { "name": "routes/", "type": "directory" }, + { "name": "models/", "type": "directory" } + ] + }, + { "name": "utils/", "type": "directory" } + ] + }, + { "name": "tests/", "type": "directory" }, + { "name": "README.md", "type": "file" }, + { "name": "pyproject.toml", "type": "file" } + ], + "summary": { + "directories": 8, + "files": 41, + "total_size": "284 KB" + } + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 150 }, + "messages": ["Resource tree displayed"] + } + ``` + +=== "YAML" + + ```yaml + command: resource inspect + status: ok + exit_code: 0 + data: + resource: local/api-repo + mode: tree + root: /home/user/projects/api-service + tree: + - name: src/ + type: directory + children: + - name: api/ + type: directory + children: + - name: __init__.py + type: file + - name: auth/ + type: directory + children: + - name: auth_middleware.py + type: file + - name: token_service.py + type: file + - name: rbac.py + type: file + - name: routes/ + type: directory + - name: models/ + type: directory + - name: utils/ + type: directory + - name: tests/ + type: directory + - name: README.md + type: file + - name: pyproject.toml + type: file + summary: + directories: 8 + files: 41 + total_size: 284 KB + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 150 + messages: + - Resource tree displayed + ``` + +=== "Rich" + + 

+    $ agents resource inspect local/api-repo --file src/api/auth/auth_middleware.py
+
+    ╭─ File: src/api/auth/auth_middleware.py ──────────────────╮
+    │ Resource: local/api-repo                                │
+    │ Size: 2.4 KB                                            │
+    │ Language: Python                                         │
+    │ Last Modified: 2026-02-10 14:32                          │
+    ╰──────────────────────────────────────────────────────────╯
+
+      1 │ from fastapi import Request, HTTPException
+      2 │ from .token_service import validate_token
+      3 │
+      4 │ async def auth_middleware(request: Request):
+      5 │     token = request.headers.get("Authorization")
+      6 │     if not token:
+      7 │         raise HTTPException(status_code=401)
+      8 │     user = await validate_token(token)
+      9 │     request.state.user = user
+     10 │     return user
+        │ ... (24 more lines)
+
+    ✓ OK File displayed
+
+ +=== "Plain" + + ``` + $ agents resource inspect local/api-repo --file src/api/auth/auth_middleware.py + + File: src/api/auth/auth_middleware.py + Resource: local/api-repo + Size: 2.4 KB + Language: Python + Last Modified: 2026-02-10 14:32 + + 1 | from fastapi import Request, HTTPException + 2 | from .token_service import validate_token + 3 | + 4 | async def auth_middleware(request: Request): + 5 | token = request.headers.get("Authorization") + 6 | if not token: + 7 | raise HTTPException(status_code=401) + 8 | user = await validate_token(token) + 9 | request.state.user = user + 10 | return user + | ... (24 more lines) + + [OK] File displayed + ``` + +=== "JSON" + + ```json + { + "command": "resource inspect", + "status": "ok", + "exit_code": 0, + "data": { + "resource": "local/api-repo", + "mode": "file", + "file": { + "path": "src/api/auth/auth_middleware.py", + "size": "2.4 KB", + "language": "Python", + "last_modified": "2026-02-10T14:32:00Z", + "lines_shown": 10, + "total_lines": 34, + "content": "from fastapi import Request, HTTPException\nfrom .token_service import validate_token\n\nasync def auth_middleware(request: Request):\n token = request.headers.get(\"Authorization\")\n if not token:\n raise HTTPException(status_code=401)\n user = await validate_token(token)\n request.state.user = user\n return user\n" + } + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 30 }, + "messages": ["File displayed"] + } + ``` + +=== "YAML" + + ```yaml + command: resource inspect + status: ok + exit_code: 0 + data: + resource: local/api-repo + mode: file + file: + path: src/api/auth/auth_middleware.py + size: 2.4 KB + language: Python + last_modified: "2026-02-10T14:32:00Z" + lines_shown: 10 + total_lines: 34 + content: | + from fastapi import Request, HTTPException + from .token_service import validate_token + + async def auth_middleware(request: Request): + token = request.headers.get("Authorization") + if not token: + raise HTTPException(status_code=401) + user = await validate_token(token) + request.state.user = user + return user + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 30 + messages: + - File displayed + ``` ##### agents resource tree @@ -3252,34 +10902,173 @@ Display the resource DAG as a tree starting from a given resource, showing paren **Examples** -

-$ agents resource tree local/api-repo --depth 2
+=== "Rich"
 
-╭─ Resource Tree: local/api-repo ──────────────────────────────────────╮
-│                                                                     │
-│ git-checkout 01HXR1A1..J9K0 (physical)                              │
-│ ├── git 01HXR4D4..M2N3 (physical)                                   │
-│ │   ├── git-remote 01HXR6F6..P4Q5                                   │
-│ │   ├── git-branch 01HXR7G7..Q5R6                                   │
-│ │   │   ├── git-commit 01HXR8H8..R6S7                               │
-│ │   │   └── ... 22 more git-commit resources                        │
-│ │   └── git-branch 01HXR9J9..S7T8                                   │
-│ │       └── ... 26 git-commit resources                             │
-│ └── fs-directory 01HXR5E5..N3P4 (physical)                          │
-│     ├── fs-directory 01HXRAK1..T8U9                                 │
-│     ├── fs-directory 01HXRBL2..U9V0                                 │
-│     └── ... 28 more fs-file resources                               │
-│                                                                     │
-╰─────────────────────────────────────────────────────────────────────╯
+    

+    $ agents resource tree local/api-repo --depth 2
 
-╭─ Summary ──────────────╮
-│ Total shown: 14        │
-│ Total in subtree: 395  │
-│ Max depth: 2           │
-╰────────────────────────╯
+    ╭─ Resource Tree: local/api-repo ──────────────────────────────────────╮
+    │                                                                     │
+    │ git-checkout 01HXR1A1..J9K0 (physical)                              │
+    │ ├── git 01HXR4D4..M2N3 (physical)                                   │
+    │ │   ├── git-remote 01HXR6F6..P4Q5                                   │
+    │ │   ├── git-branch 01HXR7G7..Q5R6                                   │
+    │ │   │   ├── git-commit 01HXR8H8..R6S7                               │
+    │ │   │   └── ... 22 more git-commit resources                        │
+    │ │   └── git-branch 01HXR9J9..S7T8                                   │
+    │ │       └── ... 26 git-commit resources                             │
+    │ └── fs-directory 01HXR5E5..N3P4 (physical)                          │
+    │     ├── fs-directory 01HXRAK1..T8U9                                 │
+    │     ├── fs-directory 01HXRBL2..U9V0                                 │
+    │     └── ... 28 more fs-file resources                               │
+    │                                                                     │
+    ╰─────────────────────────────────────────────────────────────────────╯
 
-✓ OK Resource tree displayed
-

+    ╭─ Summary ──────────────╮
+    │ Total shown: 14        │
+    │ Total in subtree: 395  │
+    │ Max depth: 2           │
+    ╰────────────────────────╯
+
+    ✓ OK Resource tree displayed
+
+ +=== "Plain" + + ``` + $ agents resource tree local/api-repo --depth 2 + + Resource Tree: local/api-repo + + git-checkout 01HXR1A1..J9K0 (physical) + +-- git 01HXR4D4..M2N3 (physical) + | +-- git-remote 01HXR6F6..P4Q5 + | +-- git-branch 01HXR7G7..Q5R6 + | | +-- git-commit 01HXR8H8..R6S7 + | | +-- ... 22 more git-commit resources + | +-- git-branch 01HXR9J9..S7T8 + | +-- ... 26 git-commit resources + +-- fs-directory 01HXR5E5..N3P4 (physical) + +-- fs-directory 01HXRAK1..T8U9 + +-- fs-directory 01HXRBL2..U9V0 + +-- ... 28 more fs-file resources + + Summary + Total shown: 14 + Total in subtree: 395 + Max depth: 2 + + [OK] Resource tree displayed + ``` + +=== "JSON" + + ```json + { + "command": "resource tree", + "status": "ok", + "exit_code": 0, + "data": { + "resource": "local/api-repo", + "max_depth": 2, + "tree": { + "type": "git-checkout", + "id": "01HXR1A1..J9K0", + "physical": true, + "children": [ + { + "type": "git", + "id": "01HXR4D4..M2N3", + "physical": true, + "children": [ + { "type": "git-remote", "id": "01HXR6F6..P4Q5" }, + { + "type": "git-branch", + "id": "01HXR7G7..Q5R6", + "children": [ + { "type": "git-commit", "id": "01HXR8H8..R6S7" }, + "... 22 more git-commit resources" + ] + }, + { + "type": "git-branch", + "id": "01HXR9J9..S7T8", + "children": ["... 26 git-commit resources"] + } + ] + }, + { + "type": "fs-directory", + "id": "01HXR5E5..N3P4", + "physical": true, + "children": [ + { "type": "fs-directory", "id": "01HXRAK1..T8U9" }, + { "type": "fs-directory", "id": "01HXRBL2..U9V0" }, + "... 28 more fs-file resources" + ] + } + ] + }, + "summary": { + "total_shown": 14, + "total_in_subtree": 395, + "max_depth": 2 + } + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 85 }, + "messages": ["Resource tree displayed"] + } + ``` + +=== "YAML" + + ```yaml + command: resource tree + status: ok + exit_code: 0 + data: + resource: local/api-repo + max_depth: 2 + tree: + type: git-checkout + id: 01HXR1A1..J9K0 + physical: true + children: + - type: git + id: 01HXR4D4..M2N3 + physical: true + children: + - type: git-remote + id: 01HXR6F6..P4Q5 + - type: git-branch + id: 01HXR7G7..Q5R6 + children: + - type: git-commit + id: 01HXR8H8..R6S7 + - "... 22 more git-commit resources" + - type: git-branch + id: 01HXR9J9..S7T8 + children: + - "... 26 git-commit resources" + - type: fs-directory + id: 01HXR5E5..N3P4 + physical: true + children: + - type: fs-directory + id: 01HXRAK1..T8U9 + - type: fs-directory + id: 01HXRBL2..U9V0 + - "... 28 more fs-file resources" + summary: + total_shown: 14 + total_in_subtree: 395 + max_depth: 2 + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 85 + messages: + - Resource tree displayed + ``` ##### agents resource link-child @@ -3295,18 +11084,70 @@ Manually link one resource as a child of another. The child resource must alread **Examples** -

-$ agents resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
+=== "Rich"
 
-╭─ Child Linked ──────────────────────────────────────╮
-│ Parent: local/api-repo                              │
-│ Child: 01HXR2B2C3D4E5F6G7H8J9K0L1                   │
-│ Child Type: fs-mount                                │
-│ Status: linked                                      │
-╰─────────────────────────────────────────────────────╯
+    

+    $ agents resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
 
-✓ OK Child resource linked
-

+    ╭─ Child Linked ──────────────────────────────────────╮
+    │ Parent: local/api-repo                              │
+    │ Child: 01HXR2B2C3D4E5F6G7H8J9K0L1                   │
+    │ Child Type: fs-mount                                │
+    │ Status: linked                                      │
+    ╰─────────────────────────────────────────────────────╯
+
+    ✓ OK Child resource linked
+
+ +=== "Plain" + + ``` + $ agents resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1 + + Child Linked + Parent: local/api-repo + Child: 01HXR2B2C3D4E5F6G7H8J9K0L1 + Child Type: fs-mount + Status: linked + + [OK] Child resource linked + ``` + +=== "JSON" + + ```json + { + "command": "resource link-child", + "status": "ok", + "exit_code": 0, + "data": { + "parent": "local/api-repo", + "child": "01HXR2B2C3D4E5F6G7H8J9K0L1", + "child_type": "fs-mount", + "status": "linked" + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 38 }, + "messages": ["Child resource linked"] + } + ``` + +=== "YAML" + + ```yaml + command: resource link-child + status: ok + exit_code: 0 + data: + parent: local/api-repo + child: 01HXR2B2C3D4E5F6G7H8J9K0L1 + child_type: fs-mount + status: linked + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 38 + messages: + - Child resource linked + ``` ##### agents resource unlink-child @@ -3323,24 +11164,92 @@ Remove a manual parent/child link between two resources. Auto-discovered links c **Examples** -

-$ agents resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
+=== "Rich"
 
-Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y
+    

+    $ agents resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
 
-╭─ Child Unlinked ────────────────────────────────────╮
-│ Parent: local/api-repo                              │
-│ Child: 01HXR2B2C3D4E5F6G7H8J9K0L1                   │
-│ Status: unlinked                                    │
-╰─────────────────────────────────────────────────────╯
+    Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y
 
-✓ OK Child resource unlinked
-

+    ╭─ Child Unlinked ────────────────────────────────────╮
+    │ Parent: local/api-repo                              │
+    │ Child: 01HXR2B2C3D4E5F6G7H8J9K0L1                   │
+    │ Status: unlinked                                    │
+    ╰─────────────────────────────────────────────────────╯
+
+    ✓ OK Child resource unlinked
+
+ +=== "Plain" + + ``` + $ agents resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1 + + Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y + + Child Unlinked + Parent: local/api-repo + Child: 01HXR2B2C3D4E5F6G7H8J9K0L1 + Status: unlinked + + [OK] Child resource unlinked + ``` + +=== "JSON" + + ```json + { + "command": "resource unlink-child", + "status": "ok", + "exit_code": 0, + "data": { + "parent": "local/api-repo", + "child": "01HXR2B2C3D4E5F6G7H8J9K0L1", + "status": "unlinked" + }, + "timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 45 }, + "messages": ["Child resource unlinked"] + } + ``` + +=== "YAML" + + ```yaml + command: resource unlink-child + status: ok + exit_code: 0 + data: + parent: local/api-repo + child: 01HXR2B2C3D4E5F6G7H8J9K0L1 + status: unlinked + timing: + started: "2026-02-09T10:15:00Z" + duration_ms: 45 + messages: + - Child resource unlinked + ``` #### agents plan -**Purpose** -Manage plans through the Strategize -> Execute -> Apply lifecycle (instantiated from Action templates). +!!! info "Purpose" + Manage ==plans== through the **Strategize → Execute → Apply** lifecycle (instantiated from Action templates). + +??? abstract "Plan Lifecycle at a Glance" + ``` + Action ──use──▶ Strategize ──execute──▶ Execute ──apply──▶ Apply + ▲ │ │ + └──────────────────────┘ │ + ▲ (reversion) │ + └────────────────────────────────────────┘ + ``` + + - [x] **Action** — Reusable template defining work, actors, and constraints + - [x] **Strategize** — Strategy actor produces a decision tree + - [x] **Execute** — Execution actor implements the strategy in a sandbox + - [x] **Apply** — Changeset is merged into real project resources + + !!! note "Phase Reversion" + Both Execute and Apply can revert to Strategize when constraints are too restrictive. See `auto_strategy_revision` and `auto_reversion_from_apply` automation profile flags. ##### agents plan list @@ -3359,78 +11268,356 @@ List plans with optional filtering. **Examples** -

-$ agents --format table plan list --phase execute
+=== "Rich"
 
-╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
-│ ID        Phase    State       Action               Project            Elapsed       │
-│ ────────  ───────  ──────────  ───────────────────  ─────────────────  ─────────     │
-│ 01HXM7A9  execute  processing  local/code-coverage  local/api-service  00:01:12      │
-╰──────────────────────────────────────────────────────────────────────────────────────╯
+    

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

+    ╭─ Summary ─────────╮
+    │ Total: 1          │
+    │ Processing: 1     │
+    │ Completed: 0      │
+    │ Errored: 0        │
+    ╰───────────────────╯
+
+    ✓ OK 1 plan listed
+
+ +=== "Plain" + + ``` + $ 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 + + Filters + Phase: execute + State: (any) + Project: (any) + Action: (any) + + Summary + Total: 1 + Processing: 1 + Completed: 0 + Errored: 0 + + [OK] 1 plan listed + ``` + +=== "JSON" + + ```json + { + "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": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 }, + "messages": ["1 plan listed"] + } + ``` + +=== "YAML" + + ```yaml + 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: + started: "2026-02-09T14:30:00Z" + duration_ms: 95 + messages: + - "1 plan listed" + ``` Listing all plans without filters shows plans across all phases and states: -

-$ agents plan list
+=== "Rich"
 
-╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────╮
-│ ID        Phase       State       Action               Project            Elapsed            │
-│ ────────  ──────────  ──────────  ───────────────────  ─────────────────  ─────────          │
-│ 01HXM7A9  execute     processing  local/code-coverage  local/api-service  00:01:12           │
-│ 01HXM6R3  apply       applied     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           │
-╰──────────────────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents plan list
 
-╭─ Summary ─────────────╮
-│ Total: 5              │
-│ Processing: 2         │
-│ Completed: 1          │
-│ Errored: 1            │
-│ Cancelled: 1          │
-╰───────────────────────╯
+    ╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────╮
+    │ ID        Phase       State       Action               Project            Elapsed            │
+    │ ────────  ──────────  ──────────  ───────────────────  ─────────────────  ─────────          │
+    │ 01HXM7A9  execute     processing  local/code-coverage  local/api-service  00:01:12           │
+    │ 01HXM6R3  apply       applied     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           │
+    ╰──────────────────────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 5 plans listed
-

+    ╭─ Summary ─────────────╮
+    │ Total: 5              │
+    │ Processing: 2         │
+    │ Completed: 1          │
+    │ Errored: 1            │
+    │ Cancelled: 1          │
+    ╰───────────────────────╯
+
+    ✓ OK 5 plans listed
+
+ +=== "Plain" + + ``` + $ agents plan list + + Plans + ID Phase State Action Project Elapsed + -------- ---------- ---------- ------------------- ----------------- --------- + 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12 + 01HXM6R3 apply applied 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 + ``` + +=== "JSON" + + ```json + { + "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" }, + { "id": "01HXM6R3", "phase": "apply", "state": "applied", "action": "local/add-auth", "project": "local/api-service", "elapsed": "00:07:14" }, + { "id": "01HXM5K2", "phase": "execute", "state": "errored", "action": "local/migrate-db", "project": "local/api-service", "elapsed": "00:04:33" }, + { "id": "01HXM4J1", "phase": "strategize", "state": "processing", "action": "local/refactor-api", "project": "local/web-app", "elapsed": "00:00:45" }, + { "id": "01HXM3H8", "phase": "cancelled", "state": "cancelled", "action": "local/add-logging", "project": "local/api-service", "elapsed": "00:02:10" } + ], + "summary": { + "total": 5, + "processing": 2, + "completed": 1, + "errored": 1, + "cancelled": 1 + } + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 }, + "messages": ["5 plans listed"] + } + ``` + +=== "YAML" + + ```yaml + 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" + - id: "01HXM6R3" + phase: apply + state: applied + action: "local/add-auth" + project: "local/api-service" + elapsed: "00:07:14" + - id: "01HXM5K2" + phase: execute + state: errored + action: "local/migrate-db" + project: "local/api-service" + elapsed: "00:04:33" + - id: "01HXM4J1" + phase: strategize + state: processing + action: "local/refactor-api" + project: "local/web-app" + elapsed: "00:00:45" + - id: "01HXM3H8" + phase: cancelled + state: cancelled + action: "local/add-logging" + project: "local/api-service" + elapsed: "00:02:10" + summary: + total: 5 + processing: 2 + completed: 1 + errored: 1 + cancelled: 1 + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 95 + messages: + - "5 plans listed" + ``` Filtering by project with `--project`: -

-$ agents plan list --project local/web-app
+=== "Rich"
 
-╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
-│ ID        Phase       State       Action               Project        Elapsed        │
-│ ────────  ──────────  ──────────  ───────────────────  ─────────────  ─────────      │
-│ 01HXM4J1  strategize  processing  local/refactor-api   local/web-app  00:00:45       │
-╰──────────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents plan list --project local/web-app
 
-╭─ Filters ─────────────────╮
-│ Phase: (any)              │
-│ State: (any)              │
-│ Project: local/web-app    │
-│ Action: (any)             │
-╰───────────────────────────╯
+    ╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
+    │ ID        Phase       State       Action               Project        Elapsed        │
+    │ ────────  ──────────  ──────────  ───────────────────  ─────────────  ─────────      │
+    │ 01HXM4J1  strategize  processing  local/refactor-api   local/web-app  00:00:45       │
+    ╰──────────────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 1 plan listed
-

+    ╭─ Filters ─────────────────╮
+    │ Phase: (any)              │
+    │ State: (any)              │
+    │ Project: local/web-app    │
+    │ Action: (any)             │
+    ╰───────────────────────────╯
+
+    ✓ OK 1 plan listed
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan list", + "status": "ok", + "exit_code": 0, + "data": { + "plans": [ + { + "id": "01HXM4J1", + "phase": "strategize", + "state": "processing", + "action": "local/refactor-api", + "project": "local/web-app", + "elapsed": "00:00:45" + } + ], + "filters": { + "phase": null, + "state": null, + "project": "local/web-app", + "action": null + }, + "total": 1 + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 85 }, + "messages": ["1 plan listed"] + } + ``` + +=== "YAML" + + ```yaml + command: plan list + status: ok + exit_code: 0 + data: + plans: + - id: "01HXM4J1" + phase: strategize + state: processing + action: "local/refactor-api" + project: "local/web-app" + elapsed: "00:00:45" + filters: + phase: null + state: null + project: "local/web-app" + action: null + total: 1 + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 85 + messages: + - "1 plan listed" + ``` ##### agents plan use @@ -3462,111 +11649,416 @@ All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-acto **Examples** -

-$ agents plan use local/code-coverage local/api-service \
-  --arg target_coverage_percent=85 --automation-profile trusted
+=== "Rich"
 
-╭─ Plan Created ──────────────────────╮
-│ Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: strategize                   │
-│ Action: local/code-coverage         │
-│ Project: local/api-service          │
-│ Automation: trusted                 │
-│ Attempt: 1                          │
-╰─────────────────────────────────────╯
+    

+    $ agents plan use local/code-coverage local/api-service \
+      --arg target_coverage_percent=85 --automation-profile trusted
 
-╭─ Inputs ──────────────────────╮
-│ - target_coverage_percent=85  │
-│ - automation_profile=trusted  │
-╰───────────────────────────────╯
+    ╭─ Plan Created ──────────────────────╮
+    │ Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+    │ Phase: strategize                   │
+    │ Action: local/code-coverage         │
+    │ Project: local/api-service          │
+    │ Automation: trusted                 │
+    │ Attempt: 1                          │
+    ╰─────────────────────────────────────╯
 
-╭─ Actors ────────────────────────╮
-│ Strategy: local/strategist      │
-│ Execution: local/executor       │
-│ Estimation: (none)              │
-╰─────────────────────────────────╯
+    ╭─ Inputs ──────────────────────╮
+    │ - target_coverage_percent=85  │
+    │ - automation_profile=trusted  │
+    ╰───────────────────────────────╯
 
-╭─ Automation ─────────────────────────╮
-│ Profile: trusted                     │
-│ Source: CLI flag                     │
-│ Read-Only: no                        │
-╰──────────────────────────────────────╯
+    ╭─ Actors ────────────────────────╮
+    │ Strategy: local/strategist      │
+    │ Execution: local/executor       │
+    │ Estimation: (none)              │
+    ╰─────────────────────────────────╯
 
-╭─ Context ───────────────────────╮
-│ Resources: 2 (repo, db)         │
-│ Indexed Files: 347              │
-│ View: strategize                │
-│ Hot Token Budget: 12,000        │
-╰─────────────────────────────────╯
+    ╭─ Automation ─────────────────────────╮
+    │ Profile: trusted                     │
+    │ Source: CLI flag                     │
+    │ Read-Only: no                        │
+    ╰──────────────────────────────────────╯
 
-╭─ Next Steps ─────────────────────────────────────╮
-│ - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J  │
-│ - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
-╰──────────────────────────────────────────────────╯
+    ╭─ Context ───────────────────────╮
+    │ Resources: 2 (repo, db)         │
+    │ Indexed Files: 347              │
+    │ View: strategize                │
+    │ Hot Token Budget: 12,000        │
+    ╰─────────────────────────────────╯
 
-✓ OK Plan created
-

+    ╭─ Next Steps ─────────────────────────────────────╮
+    │ - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+    │ - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J  │
+    │ - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
+    ╰──────────────────────────────────────────────────╯
+
+    ✓ OK Plan created
+
+ +=== "Plain" + + ``` + $ 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: trusted + Attempt: 1 + + Inputs + - target_coverage_percent=85 + - automation_profile=trusted + + Actors + Strategy: local/strategist + Execution: local/executor + Estimation: (none) + + Automation + Profile: trusted + Source: CLI flag + Read-Only: no + + Context + Resources: 2 (repo, db) + Indexed Files: 347 + View: strategize + Hot Token Budget: 12,000 + + Next Steps + - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J + - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J + - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + [OK] Plan created + ``` + +=== "JSON" + + ```json + { + "command": "plan use", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "phase": "strategize", + "action": "local/code-coverage", + "project": "local/api-service", + "automation_profile": "trusted", + "attempt": 1, + "inputs": { + "target_coverage_percent": 85, + "automation_profile": "trusted" + }, + "actors": { + "strategy": "local/strategist", + "execution": "local/executor", + "estimation": null + }, + "automation": { + "profile": "trusted", + "source": "CLI flag", + "read_only": false + }, + "context": { + "resources": 2, + "indexed_files": 347, + "view": "strategize", + "hot_token_budget": 12000 + }, + "next_steps": [ + "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J" + ] + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 }, + "messages": ["Plan created"] + } + ``` + +=== "YAML" + + ```yaml + command: plan use + status: ok + exit_code: 0 + data: + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + phase: strategize + action: "local/code-coverage" + project: "local/api-service" + automation_profile: trusted + attempt: 1 + inputs: + target_coverage_percent: 85 + automation_profile: trusted + actors: + strategy: "local/strategist" + execution: "local/executor" + estimation: null + automation: + profile: trusted + source: "CLI flag" + read_only: false + context: + resources: 2 + indexed_files: 347 + view: strategize + hot_token_budget: 12000 + next_steps: + - "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J" + - "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J" + - "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J" + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 95 + messages: + - "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
+=== "Rich"
 
-╭─ Plan Created ──────────────────────────────────────╮
-│ Plan: 01HXM9D2ZK4Q7C2B3F2R4VYV6J                    │
-│ Action: local/security-audit                        │
-│ Phase: strategize (running)                         │
-│ Automation: supervised                              │
-╰─────────────────────────────────────────────────────╯
+    

+    $ 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
 
-╭─ Target Projects ───────────────────╮
-│ 1. local/api-service (3 resources)  │
-│ 2. local/web-app (2 resources)      │
-╰─────────────────────────────────────╯
+    ╭─ Plan Created ──────────────────────────────────────╮
+    │ Plan: 01HXM9D2ZK4Q7C2B3F2R4VYV6J                    │
+    │ Action: local/security-audit                        │
+    │ Phase: strategize (running)                         │
+    │ Automation: supervised                              │
+    ╰─────────────────────────────────────────────────────╯
 
-╭─ 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         │
-╰────────────────────────────────────────────────────────────╯
+    ╭─ Target Projects ───────────────────╮
+    │ 1. local/api-service (3 resources)  │
+    │ 2. local/web-app (2 resources)      │
+    ╰─────────────────────────────────────╯
 
-✓ OK Plan created — strategize in progress
-

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan use", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM9D2ZK4Q7C2B3F2R4VYV6J", + "action": "local/security-audit", + "phase": "strategize", + "phase_state": "running", + "automation_profile": "supervised", + "target_projects": [ + { "name": "local/api-service", "resources": 3 }, + { "name": "local/web-app", "resources": 2 } + ], + "invariants": [ + { "scope": "plan", "source": "CLI", "text": "Never modify production DB schemas" }, + { "scope": "plan", "source": "CLI", "text": "All changes must include test coverage" }, + { "scope": "project", "source": "config", "text": "API responses must be backward-compat" }, + { "scope": "global", "source": "config", "text": "Follow Python PEP 8 style guide" } + ] + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 130 }, + "messages": ["Plan created -- strategize in progress"] + } + ``` + +=== "YAML" + + ```yaml + command: plan use + status: ok + exit_code: 0 + data: + plan_id: "01HXM9D2ZK4Q7C2B3F2R4VYV6J" + action: "local/security-audit" + phase: strategize + phase_state: running + automation_profile: supervised + target_projects: + - name: "local/api-service" + resources: 3 + - name: "local/web-app" + resources: 2 + invariants: + - scope: plan + source: CLI + text: "Never modify production DB schemas" + - scope: plan + source: CLI + text: "All changes must include test coverage" + - scope: project + source: config + text: "API responses must be backward-compat" + - scope: global + source: config + text: "Follow Python PEP 8 style guide" + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 130 + messages: + - "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
+=== "Rich"
 
-╭─ Plan Created ──────────────────────────────────────╮
-│ Plan: 01HXM9E3ZK4Q7C2B3F2R4VYV6J                    │
-│ Action: local/code-coverage                         │
-│ Phase: strategize (running)                         │
-│ Automation: trusted                                 │
-╰─────────────────────────────────────────────────────╯
+    

+    $ agents plan use local/code-coverage local/api-service \
+      --strategy-actor local/senior-planner \
+      --execution-actor local/fast-executor \
+      --arg target_coverage_percent=95
 
-╭─ Actor Overrides ────────────────────╮
-│ Strategy: local/senior-planner       │
-│ Execution: local/fast-executor       │
-│ (Estimation: action default)         │
-╰──────────────────────────────────────╯
+    ╭─ Plan Created ──────────────────────────────────────╮
+    │ Plan: 01HXM9E3ZK4Q7C2B3F2R4VYV6J                    │
+    │ Action: local/code-coverage                         │
+    │ Phase: strategize (running)                         │
+    │ Automation: trusted                                 │
+    ╰─────────────────────────────────────────────────────╯
 
-╭─ Arguments ─────────────────╮
-│ target_coverage_percent: 95 │
-╰─────────────────────────────╯
+    ╭─ Actor Overrides ────────────────────╮
+    │ Strategy: local/senior-planner       │
+    │ Execution: local/fast-executor       │
+    │ (Estimation: action default)         │
+    ╰──────────────────────────────────────╯
 
-✓ OK Plan created — strategize in progress
-

+    ╭─ Arguments ─────────────────╮
+    │ target_coverage_percent: 95 │
+    ╰─────────────────────────────╯
+
+    ✓ OK Plan created — strategize in progress
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan use", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM9E3ZK4Q7C2B3F2R4VYV6J", + "action": "local/code-coverage", + "phase": "strategize", + "phase_state": "running", + "automation_profile": "trusted", + "actor_overrides": { + "strategy": "local/senior-planner", + "execution": "local/fast-executor", + "estimation": null + }, + "arguments": { + "target_coverage_percent": 95 + } + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 110 }, + "messages": ["Plan created -- strategize in progress"] + } + ``` + +=== "YAML" + + ```yaml + command: plan use + status: ok + exit_code: 0 + data: + plan_id: "01HXM9E3ZK4Q7C2B3F2R4VYV6J" + action: "local/code-coverage" + phase: strategize + phase_state: running + automation_profile: trusted + actor_overrides: + strategy: "local/senior-planner" + execution: "local/fast-executor" + estimation: null + arguments: + target_coverage_percent: 95 + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 110 + messages: + - "Plan created -- strategize in progress" + ``` ##### agents plan execute @@ -3581,72 +12073,289 @@ Start or resume execution for a plan. **Examples** -

-$ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Execution ──────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: execute                   │
-│ Sandbox: git_worktree            │
-│ Worker: local/executor           │
-│ Started: 12:58:10                │
-│ Attempt: 1                       │
-╰──────────────────────────────────╯
+    

+    $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
-╭─ Sandbox ──────────────────────────────────╮
-│ Strategy: git_worktree                     │
-│ Path: /repos/api/.worktrees/plan-01HXM8    │
-│ Branch: cleveragents/plan-01HXM8C2         │
-│ Status: active                             │
-╰────────────────────────────────────────────╯
+    ╭─ 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                              │
-╰────────────────────────────────────────╯
+    ╭─ Sandbox ──────────────────────────────────╮
+    │ Strategy: git_worktree                     │
+    │ Path: /repos/api/.worktrees/plan-01HXM8    │
+    │ Branch: cleveragents/plan-01HXM8C2         │
+    │ Status: active                             │
+    ╰────────────────────────────────────────────╯
 
-╭─ Progress ────────╮
-│ ⏳ Collect context │
-│ • Run tools       │
-│ • Build changeset │
-│ • Validate        │
-╰───────────────────╯
+    ╭─ Strategy Summary ─────────────────────╮
+    │ Decisions: 8                           │
+    │ Invariants: 2                          │
+    │ Planned Child Plans: 2+                │
+    │ Estimated Files: ~12                   │
+    │ Risk: low                              │
+    ╰────────────────────────────────────────╯
 
-✓ OK Execution started
-

+    ╭─ Progress ────────╮
+    │ ⏳ Collect context │
+    │ • Run tools       │
+    │ • Build changeset │
+    │ • Validate        │
+    ╰───────────────────╯
+
+    ✓ OK Execution started
+
+ +=== "Plain" + + ``` + $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + Execution + Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + Phase: execute + Sandbox: git_worktree + 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 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan execute", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "phase": "execute", + "sandbox": { + "strategy": "git_worktree", + "path": "/repos/api/.worktrees/plan-01HXM8", + "branch": "cleveragents/plan-01HXM8C2", + "status": "active" + }, + "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": [ + { "label": "Collect context", "status": "running" }, + { "label": "Run tools", "status": "pending" }, + { "label": "Build changeset", "status": "pending" }, + { "label": "Validate", "status": "pending" } + ] + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 150 }, + "messages": ["Execution started"] + } + ``` + +=== "YAML" + + ```yaml + command: plan execute + status: ok + exit_code: 0 + data: + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + phase: execute + sandbox: + strategy: git_worktree + path: "/repos/api/.worktrees/plan-01HXM8" + branch: "cleveragents/plan-01HXM8C2" + status: active + 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: + - label: "Collect context" + status: running + - label: "Run tools" + status: pending + - label: "Build changeset" + status: pending + - label: "Validate" + status: pending + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 150 + messages: + - "Execution started" + ``` Resuming execution of a plan that was previously paused or errored: -

-$ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Execution Resumed ─────────────────╮
-│ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J    │
-│ Phase: execute (resumed)            │
-│ Sandbox: git_worktree               │
-│ Worker: local/executor              │
-│ Checkpoint: cp_01HXM8C2 (loaded)    │
-│ Resumed From: step 4 of 6           │
-╰─────────────────────────────────────╯
+    

+    $ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
 
-╭─ 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)      │
-╰──────────────────────────────────────────╯
+    ╭─ Execution Resumed ─────────────────╮
+    │ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J    │
+    │ Phase: execute (resumed)            │
+    │ Sandbox: git_worktree               │
+    │ Worker: local/executor              │
+    │ Checkpoint: cp_01HXM8C2 (loaded)    │
+    │ Resumed From: step 4 of 6           │
+    ╰─────────────────────────────────────╯
 
-╭─ Guidance Applied ──────────────────────────────────────────────╮
-│ "Use smaller batch sizes for the migration to avoid timeouts"   │
-╰─────────────────────────────────────────────────────────────────╯
+    ╭─ 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)      │
+    ╰──────────────────────────────────────────╯
 
-✓ OK Execution resumed from checkpoint cp_01HXM8C2
-

+    ╭─ Guidance Applied ──────────────────────────────────────────────╮
+    │ "Use smaller batch sizes for the migration to avoid timeouts"   │
+    ╰─────────────────────────────────────────────────────────────────╯
+
+    ✓ OK Execution resumed from checkpoint cp_01HXM8C2
+
+ +=== "Plain" + + ``` + $ 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 + v Step 1: Collect context (0.8s) + v Step 2: Analyze codebase (4.2s) + v Step 3: Generate migrations (6.1s) + x Step 4: Apply migrations (errored) + o Step 5: Update models (pending) + o Step 6: Run validations (pending) + + Guidance Applied + "Use smaller batch sizes for the migration to avoid timeouts" + + [OK] Execution resumed from checkpoint cp_01HXM8C2 + ``` + +=== "JSON" + + ```json + { + "command": "plan execute", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM7K2ZK4Q7C2B3F2R4VYV6J", + "phase": "execute", + "resumed": true, + "sandbox": "git_worktree", + "worker": "local/executor", + "checkpoint": "cp_01HXM8C2", + "resumed_from": "step 4 of 6", + "progress": [ + { "step": 1, "label": "Collect context", "status": "done", "duration_s": 0.8 }, + { "step": 2, "label": "Analyze codebase", "status": "done", "duration_s": 4.2 }, + { "step": 3, "label": "Generate migrations", "status": "done", "duration_s": 6.1 }, + { "step": 4, "label": "Apply migrations", "status": "errored" }, + { "step": 5, "label": "Update models", "status": "pending" }, + { "step": 6, "label": "Run validations", "status": "pending" } + ], + "guidance": "Use smaller batch sizes for the migration to avoid timeouts" + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 180 }, + "messages": ["Execution resumed from checkpoint cp_01HXM8C2"] + } + ``` + +=== "YAML" + + ```yaml + command: plan execute + status: ok + exit_code: 0 + data: + plan_id: "01HXM7K2ZK4Q7C2B3F2R4VYV6J" + phase: execute + resumed: true + sandbox: git_worktree + worker: "local/executor" + checkpoint: "cp_01HXM8C2" + resumed_from: "step 4 of 6" + progress: + - step: 1 + label: "Collect context" + status: done + duration_s: 0.8 + - step: 2 + label: "Analyze codebase" + status: done + duration_s: 4.2 + - step: 3 + label: "Generate migrations" + status: done + duration_s: 6.1 + - step: 4 + label: "Apply migrations" + status: errored + - step: 5 + label: "Update models" + status: pending + - step: 6 + label: "Run validations" + status: pending + guidance: "Use smaller batch sizes for the migration to avoid timeouts" + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 180 + messages: + - "Execution resumed from checkpoint cp_01HXM8C2" + ``` ##### agents plan apply @@ -3662,85 +12371,335 @@ Apply sandboxed changes to real resources. **Examples** -

-$ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
+    

+    $ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
-╭─ Apply Summary ─────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
-│ Artifacts: 6 files updated          │
-│ Changes: 42 insertions, 9 deletions │
-│ Project: local/api-service          │
-│ Applied At: 2026-02-08 13:04        │
-╰─────────────────────────────────────╯
+    Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
 
-╭─ Validation (from Execute) ────╮
-│ Tests: passed (24/24)          │
-│ Lint: passed (0 warnings)      │
-│ Type Check: passed (0 errors)  │
-│ Duration: 12.4s                │
-╰────────────────────────────────╯
+    ╭─ Apply Summary ─────────────────────╮
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
+    │ Artifacts: 6 files updated          │
+    │ Changes: 42 insertions, 9 deletions │
+    │ Project: local/api-service          │
+    │ Applied At: 2026-02-08 13:04        │
+    ╰─────────────────────────────────────╯
 
-╭─ Sandbox Cleanup ─────────╮
-│ Worktree: removed         │
-│ Branch: merged to main    │
-│ Checkpoint: archived      │
-╰───────────────────────────╯
+    ╭─ Validation (from Execute) ────╮
+    │ Tests: passed (24/24)          │
+    │ Lint: passed (0 warnings)      │
+    │ Type Check: passed (0 errors)  │
+    │ Duration: 12.4s                │
+    ╰────────────────────────────────╯
 
-╭─ Plan Lifecycle ────────────────────────╮
-│ Phase: apply                            │
-│ State: applied                          │
-│ Total Duration: 00:06:14                │
-│ Total Cost: $0.0847                     │
-│ Decisions Made: 8                       │
-│ Child Plans: 2 (completed)              │
-╰─────────────────────────────────────────╯
+    ╭─ Sandbox Cleanup ─────────╮
+    │ Worktree: removed         │
+    │ Branch: merged to main    │
+    │ Checkpoint: archived      │
+    ╰───────────────────────────╯
 
-╭─ Next Steps ──────╮
-│ - Review git diff │
-│ - Commit changes  │
-╰───────────────────╯
+    ╭─ Plan Lifecycle ────────────────────────╮
+    │ Phase: apply                            │
+    │ State: applied                          │
+    │ Total Duration: 00:06:14                │
+    │ Total Cost: $0.0847                     │
+    │ Decisions Made: 8                       │
+    │ Child Plans: 2 (completed)              │
+    ╰─────────────────────────────────────────╯
 
-✓ OK Changes applied
-

+    ╭─ Next Steps ──────╮
+    │ - Review git diff │
+    │ - Commit changes  │
+    ╰───────────────────╯
+
+    ✓ OK Changes applied
+
+ +=== "Plain" + + ``` + $ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y + + Apply Summary + Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + Artifacts: 6 files updated + Changes: 42 insertions, 9 deletions + Project: local/api-service + Applied At: 2026-02-08 13:04 + + Validation (from Execute) + 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 + + Plan Lifecycle + Phase: apply + State: applied + Total Duration: 00:06:14 + Total Cost: $0.0847 + Decisions Made: 8 + Child Plans: 2 (completed) + + Next Steps + - Review git diff + - Commit changes + + [OK] Changes applied + ``` + +=== "JSON" + + ```json + { + "command": "plan apply", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "artifacts": 6, + "changes": { + "insertions": 42, + "deletions": 9 + }, + "project": "local/api-service", + "applied_at": "2026-02-08T13:04:00Z", + "validation": { + "tests": { "status": "passed", "passed": 24, "total": 24 }, + "lint": { "status": "passed", "warnings": 0 }, + "type_check": { "status": "passed", "errors": 0 }, + "duration_s": 12.4 + }, + "sandbox_cleanup": { + "worktree": "removed", + "branch": "merged to main", + "checkpoint": "archived" + }, + "lifecycle": { + "phase": "apply", + "state": "applied", + "total_duration": "00:06:14", + "total_cost": "$0.0847", + "decisions_made": 8, + "child_plans": 2 + } + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 1250 }, + "messages": ["Changes applied"] + } + ``` + +=== "YAML" + + ```yaml + command: plan apply + status: ok + exit_code: 0 + data: + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + artifacts: 6 + changes: + insertions: 42 + deletions: 9 + project: "local/api-service" + applied_at: "2026-02-08T13:04:00Z" + validation: + tests: + status: passed + passed: 24 + total: 24 + lint: + status: passed + warnings: 0 + type_check: + status: passed + errors: 0 + duration_s: 12.4 + sandbox_cleanup: + worktree: removed + branch: merged to main + checkpoint: archived + lifecycle: + phase: apply + state: applied + total_duration: "00:06:14" + total_cost: "$0.0847" + decisions_made: 8 + child_plans: 2 + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 1250 + messages: + - "Changes applied" + ``` When Execute-phase validations failed and were not resolved (e.g., the execution actor exhausted its retry limit or failed outright), the plan cannot be applied. Apply checks the validation record and refuses to proceed: -

-$ agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Apply Summary ─────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
-│ Artifacts: 6 files updated          │
-│ Changes: 42 insertions, 9 deletions │
-│ Project: local/api-service          │
-╰─────────────────────────────────────╯
+    

+    $ agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
-╭─ 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                                            │
-╰────────────────────────────────────────────────────────────╯
+    ╭─ Apply Summary ─────────────────────╮
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J    │
+    │ Artifacts: 6 files updated          │
+    │ Changes: 42 insertions, 9 deletions │
+    │ Project: local/api-service          │
+    ╰─────────────────────────────────────╯
 
-╭─ Sandbox Status ─────────────────────────────────────────────╮
-│ Worktree: preserved (changes NOT committed)                  │
-│ Checkpoint: cp_01HXM8C2 (pre-apply state available)          │
-│ The sandbox is preserved for correction or manual review.    │
-╰──────────────────────────────────────────────────────────────╯
+    ╭─ 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                                            │
+    ╰────────────────────────────────────────────────────────────╯
 
-╭─ 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                      │
-╰─────────────────────────────────────────────────────────────────────╯
+    ╭─ Sandbox Status ─────────────────────────────────────────────╮
+    │ Worktree: preserved (changes NOT committed)                  │
+    │ Checkpoint: cp_01HXM8C2 (pre-apply state available)          │
+    │ The sandbox is preserved for correction or manual review.    │
+    ╰──────────────────────────────────────────────────────────────╯
 
-✗ ERROR Apply refused — 2 required Execute-phase validations did not pass
-

+    ╭─ 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 refused — 2 required Execute-phase validations did not pass
+
+ +=== "Plain" + + ``` + $ agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + Apply Summary + Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + Artifacts: 6 files updated + Changes: 42 insertions, 9 deletions + Project: local/api-service + + Validation + x Tests: FAILED (22/24 passed, 2 failed) + FAIL test_auth.py::test_session_refresh -- AssertionError + FAIL test_auth.py::test_token_expiry -- TimeoutError + v Lint: passed (0 warnings) + v 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 refused -- 2 required Execute-phase validations did not pass + ``` + +=== "JSON" + + ```json + { + "command": "plan apply", + "status": "error", + "exit_code": 1, + "data": { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "artifacts": 6, + "changes": { + "insertions": 42, + "deletions": 9 + }, + "project": "local/api-service", + "validation": { + "tests": { + "status": "failed", + "passed": 22, + "total": 24, + "failures": [ + "test_auth.py::test_session_refresh -- AssertionError", + "test_auth.py::test_token_expiry -- TimeoutError" + ] + }, + "lint": { "status": "passed", "warnings": 0 }, + "type_check": { "status": "passed", "errors": 0 }, + "duration_s": 14.8 + }, + "sandbox": { + "worktree": "preserved", + "checkpoint": "cp_01HXM8C2" + }, + "recovery_options": [ + "agents plan prompt", + "agents plan correct", + "agents plan rollback", + "agents plan cancel" + ] + }, + "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 320 }, + "messages": ["Apply refused -- 2 required Execute-phase validations did not pass"] + } + ``` + +=== "YAML" + + ```yaml + command: plan apply + status: error + exit_code: 1 + data: + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + artifacts: 6 + changes: + insertions: 42 + deletions: 9 + project: "local/api-service" + validation: + tests: + status: failed + passed: 22 + total: 24 + failures: + - "test_auth.py::test_session_refresh -- AssertionError" + - "test_auth.py::test_token_expiry -- TimeoutError" + lint: + status: passed + warnings: 0 + type_check: + status: passed + errors: 0 + duration_s: 14.8 + sandbox: + worktree: preserved + checkpoint: "cp_01HXM8C2" + recovery_options: + - "agents plan prompt" + - "agents plan correct" + - "agents plan rollback" + - "agents plan cancel" + timing: + started: "2026-02-09T14:30:00Z" + duration_ms: 320 + messages: + - "Apply refused -- 2 required Execute-phase validations did not pass" + ``` ##### agents plan status @@ -3755,159 +12714,613 @@ Show detailed status for a plan. **Examples** -

-$ agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Plan Status ────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: execute                   │
-│ State: processing                │
-│ Action: local/code-coverage      │
-│ Project: local/api-service       │
-│ Automation: review               │
-│ Attempt: 1                       │
-╰──────────────────────────────────╯
+    

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

+    ╭─ Cost ───────────────╮
+    │ Tokens Used: 12,420  │
+    │ Cost So Far: $0.041  │
+    │ Estimated: $0.085    │
+    ╰──────────────────────╯
+
+    ✓ OK Status refreshed
+
+ +=== "Plain" + + ``` + $ agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + Plan Status + Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + Phase: execute + State: processing + Action: local/code-coverage + Project: local/api-service + Automation: review + Attempt: 1 + + Progress + [OK] Strategize + ... Execute + . Apply (queued) + + Timing + Started: 12:57:01 + Elapsed: 00:01:12 + ETA: 00:03:45 + + Execution Detail + 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 + + [OK] Status refreshed + ``` + +=== "JSON" + + ```json + { + "command": "plan status", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "phase": "execute", + "state": "processing", + "action": "local/code-coverage", + "project": "local/api-service", + "automation": "review", + "attempt": 1, + "progress": [ + { "step": "Strategize", "status": "done" }, + { "step": "Execute", "status": "running" }, + { "step": "Apply", "status": "queued" } + ], + "timing": { + "started": "12:57:01", + "elapsed": "00:01:12", + "eta": "00:03:45" + }, + "execution": { + "sandbox": "git_worktree", + "tool_calls": 8, + "files_modified": 3, + "child_plans": "1/2 complete", + "checkpoints": 2 + }, + "cost": { + "tokens_used": 12420, + "cost_so_far": 0.041, + "estimated": 0.085 + } + }, + "timing": { + "started": "2026-02-08T12:57:01Z", + "duration_ms": 120 + }, + "messages": ["Status refreshed"] + } + ``` + +=== "YAML" + + ```yaml + command: plan status + status: ok + exit_code: 0 + data: + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + phase: execute + state: processing + action: local/code-coverage + project: local/api-service + automation: review + attempt: 1 + progress: + - step: Strategize + status: done + - step: Execute + status: running + - step: Apply + status: queued + timing: + started: "12:57:01" + elapsed: "00:01:12" + eta: "00:03:45" + execution: + sandbox: git_worktree + tool_calls: 8 + files_modified: 3 + child_plans: "1/2 complete" + checkpoints: 2 + cost: + tokens_used: 12420 + cost_so_far: 0.041 + estimated: 0.085 + timing: + started: "2026-02-08T12:57:01Z" + duration_ms: 120 + messages: + - "Status refreshed" + ``` Status of a plan that has completed successfully: -

-$ agents plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Plan Status ─────────────────────╮
-│ Plan: 01HXM6R3ZK4Q7C2B3F2R4VYV6J  │
-│ Phase: apply                      │
-│ State: applied                    │
-│ Action: local/add-auth            │
-│ Project: local/api-service        │
-│ Automation: trusted               │
-│ Attempt: 1                        │
-╰───────────────────────────────────╯
+    

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

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ agents plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J + + Plan Status + Plan: 01HXM6R3ZK4Q7C2B3F2R4VYV6J + Phase: apply + State: applied + Action: local/add-auth + Project: local/api-service + Automation: trusted + Attempt: 1 + + Progress + [OK] Strategize + [OK] Execute + [OK] 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan status", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM6R3ZK4Q7C2B3F2R4VYV6J", + "phase": "apply", + "state": "applied", + "action": "local/add-auth", + "project": "local/api-service", + "automation": "trusted", + "attempt": 1, + "progress": [ + { "step": "Strategize", "status": "done" }, + { "step": "Execute", "status": "done" }, + { "step": "Apply", "status": "committed" } + ], + "timing": { + "started": "2026-02-08T12:57:01Z", + "finished": "2026-02-08T13:04:15Z", + "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 + } + }, + "timing": { + "started": "2026-02-08T12:57:01Z", + "duration_ms": 434000 + }, + "messages": ["Plan completed successfully"] + } + ``` + +=== "YAML" + + ```yaml + command: plan status + status: ok + exit_code: 0 + data: + plan_id: "01HXM6R3ZK4Q7C2B3F2R4VYV6J" + phase: apply + state: applied + action: local/add-auth + project: local/api-service + automation: trusted + attempt: 1 + progress: + - step: Strategize + status: done + - step: Execute + status: done + - step: Apply + status: committed + timing: + started: "2026-02-08T12:57:01Z" + finished: "2026-02-08T13:04:15Z" + 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 + timing: + started: "2026-02-08T12:57:01Z" + duration_ms: 434000 + messages: + - "Plan completed successfully" + ``` Status of a plan in the strategize phase: -

-$ agents plan status 01HXM9F2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Plan Status ────────────────────╮
-│ Plan: 01HXM9F2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: strategize                │
-│ State: processing                │
-│ Action: local/refactor-auth      │
-│ Project: local/api-service       │
-│ Automation: supervised           │
-╰──────────────────────────────────╯
+    

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

+    ╭─ Strategy Progress ────────╮
+    │ Decisions Made: 4          │
+    │ Invariants Enforced: 2     │
+    │ Child Plans Planned: 3     │
+    │ Elapsed: 00:00:28          │
+    ╰────────────────────────────╯
+
+    ✓ OK Strategize in progress
+
+ +=== "Plain" + + ``` + $ 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) + o Execute (waiting) + o Apply (waiting) + + Strategy Progress + Decisions Made: 4 + Invariants Enforced: 2 + Child Plans Planned: 3 + Elapsed: 00:00:28 + + [OK] Strategize in progress + ``` + +=== "JSON" + + ```json + { + "command": "plan status", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM9F2ZK4Q7C2B3F2R4VYV6J", + "phase": "strategize", + "state": "processing", + "action": "local/refactor-auth", + "project": "local/api-service", + "automation": "supervised", + "progress": [ + { "step": "Strategize", "status": "running" }, + { "step": "Execute", "status": "waiting" }, + { "step": "Apply", "status": "waiting" } + ], + "strategy_progress": { + "decisions_made": 4, + "invariants_enforced": 2, + "child_plans_planned": 3, + "elapsed": "00:00:28" + } + }, + "timing": { + "started": "2026-02-08T12:57:01Z", + "duration_ms": 28000 + }, + "messages": ["Strategize in progress"] + } + ``` + +=== "YAML" + + ```yaml + command: plan status + status: ok + exit_code: 0 + data: + plan_id: "01HXM9F2ZK4Q7C2B3F2R4VYV6J" + phase: strategize + state: processing + action: local/refactor-auth + project: local/api-service + automation: supervised + progress: + - step: Strategize + status: running + - step: Execute + status: waiting + - step: Apply + status: waiting + strategy_progress: + decisions_made: 4 + invariants_enforced: 2 + child_plans_planned: 3 + elapsed: "00:00:28" + timing: + started: "2026-02-08T12:57:01Z" + duration_ms: 28000 + messages: + - "Strategize in progress" + ``` Status of a plan that encountered an error: -

-$ agents plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Plan Status ────────────────────╮
-│ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: execute                   │
-│ State: errored                   │
-│ Action: local/migrate-db         │
-│ Project: local/api-service       │
-│ Automation: supervised           │
-│ Attempt: 1                       │
-╰──────────────────────────────────╯
+    

+    $ agents plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
 
-╭─ Progress ───────────╮
-│ ✓ Strategize         │
-│ ✗ Execute            │
-│ ○ Apply (skipped)    │
-╰──────────────────────╯
+    ╭─ Plan Status ────────────────────╮
+    │ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
+    │ Phase: execute                   │
+    │ State: errored                   │
+    │ Action: local/migrate-db         │
+    │ Project: local/api-service       │
+    │ Automation: supervised           │
+    │ Attempt: 1                       │
+    ╰──────────────────────────────────╯
 
-╭─ 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 │
-╰─────────────────────────────────────────────────────────────────╯
+    ╭─ Progress ───────────╮
+    │ ✓ Strategize         │
+    │ ✗ Execute            │
+    │ ○ Apply (skipped)    │
+    ╰──────────────────────╯
 
-╭─ Cost ───────────────╮
-│ Tokens Used: 8,340   │
-│ Cost So Far: $0.028  │
-╰──────────────────────╯
+    ╭─ 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 │
+    ╰─────────────────────────────────────────────────────────────────╯
 
-✗ ERROR Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort
-

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ 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 + [OK] Strategize + [FAIL] Execute + o 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan status", + "status": "error", + "exit_code": 1, + "data": { + "plan_id": "01HXM7K2ZK4Q7C2B3F2R4VYV6J", + "phase": "execute", + "state": "errored", + "action": "local/migrate-db", + "project": "local/api-service", + "automation": "supervised", + "attempt": 1, + "progress": [ + { "step": "Strategize", "status": "done" }, + { "step": "Execute", "status": "failed" }, + { "step": "Apply", "status": "skipped" } + ], + "error": { + "message": "Tool invocation failed: connection refused", + "tool": "local/db-migrate", + "step": "4 of 6", + "checkpoint": "cp_01HXM8C2", + "recoverable": true + }, + "cost": { + "tokens_used": 8340, + "cost_so_far": 0.028 + } + }, + "timing": { + "started": "2026-02-08T12:57:01Z", + "duration_ms": 72000 + }, + "messages": ["Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort"] + } + ``` + +=== "YAML" + + ```yaml + command: plan status + status: error + exit_code: 1 + data: + plan_id: "01HXM7K2ZK4Q7C2B3F2R4VYV6J" + phase: execute + state: errored + action: local/migrate-db + project: local/api-service + automation: supervised + attempt: 1 + progress: + - step: Strategize + status: done + - step: Execute + status: failed + - step: Apply + status: skipped + error: + message: "Tool invocation failed: connection refused" + tool: local/db-migrate + step: "4 of 6" + checkpoint: cp_01HXM8C2 + recoverable: true + cost: + tokens_used: 8340 + cost_so_far: 0.028 + timing: + started: "2026-02-08T12:57:01Z" + duration_ms: 72000 + messages: + - "Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort" + ``` ##### agents plan cancel 
agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>
-**Purpose** -Cancel a plan that is not terminal. +!!! warning "Irreversible State Transition" + Cancel a plan that is not in a terminal state. Cancellation transitions the plan to the `cancelled` state, which is ==terminal==. The sandbox and any child plan artifacts are preserved for inspection but cannot be resumed. + + !!! tip "Recovery After Cancel" + A cancelled plan cannot be resumed, but you can re-execute the same action with `agents plan use` to create a new plan instance. **Arguments** @@ -3916,36 +13329,133 @@ Cancel a plan that is not terminal. **Examples** -

-$ agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
+=== "Rich"
 
-╭─ Plan Cancelled ─────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: execute                   │
-│ Reason: blocked on credentials   │
-│ State: cancelled                 │
-│ Cancelled At: 13:02:15           │
-╰──────────────────────────────────╯
+    

+    $ agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
 
-╭─ Sandbox ────────────────╮
-│ Status: preserved        │
-│ Files Modified: 3        │
-│ Checkpoints: 2           │
-╰──────────────────────────╯
+    ╭─ Plan Cancelled ─────────────────╮
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+    │ Phase: execute                   │
+    │ Reason: blocked on credentials   │
+    │ State: cancelled                 │
+    │ Cancelled At: 13:02:15           │
+    ╰──────────────────────────────────╯
 
-╭─ Child Plans ─────────────╮
-│ Completed: 1              │
-│ Cancelled: 1              │
-│ Artifacts Preserved: yes  │
-╰───────────────────────────╯
+    ╭─ Sandbox ────────────────╮
+    │ Status: preserved        │
+    │ Files Modified: 3        │
+    │ Checkpoints: 2           │
+    ╰──────────────────────────╯
 
-╭─ Recovery ───────────────────────────────────────────╮
-│ - Resolve credentials                                │
-│ - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-╰──────────────────────────────────────────────────────╯
+    ╭─ Child Plans ─────────────╮
+    │ Completed: 1              │
+    │ Cancelled: 1              │
+    │ Artifacts Preserved: yes  │
+    ╰───────────────────────────╯
 
-✓ OK Plan cancelled
-

+    ╭─ Recovery ───────────────────────────────────────────╮
+    │ - Resolve credentials                                │
+    │ - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+    ╰──────────────────────────────────────────────────────╯
+
+    ✓ OK Plan cancelled
+
+ +=== "Plain" + + ``` + $ 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 + + Sandbox + Status: preserved + Files Modified: 3 + Checkpoints: 2 + + Child Plans + Completed: 1 + Cancelled: 1 + Artifacts Preserved: yes + + Recovery + - Resolve credentials + - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + [OK] Plan cancelled + ``` + +=== "JSON" + + ```json + { + "command": "plan cancel", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "phase": "execute", + "reason": "blocked on credentials", + "state": "cancelled", + "cancelled_at": "13:02:15", + "sandbox": { + "status": "preserved", + "files_modified": 3, + "checkpoints": 2 + }, + "child_plans": { + "completed": 1, + "cancelled": 1, + "artifacts_preserved": true + }, + "recovery": [ + "Resolve credentials", + "Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J" + ] + }, + "timing": { + "started": "2026-02-08T13:02:15Z", + "duration_ms": 340 + }, + "messages": ["Plan cancelled"] + } + ``` + +=== "YAML" + + ```yaml + command: plan cancel + status: ok + exit_code: 0 + data: + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + phase: execute + reason: "blocked on credentials" + state: cancelled + cancelled_at: "13:02:15" + sandbox: + status: preserved + files_modified: 3 + checkpoints: 2 + child_plans: + completed: 1 + cancelled: 1 + artifacts_preserved: true + recovery: + - "Resolve credentials" + - "Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J" + timing: + started: "2026-02-08T13:02:15Z" + duration_ms: 340 + messages: + - "Plan cancelled" + ``` ##### agents plan tree @@ -3961,50 +13471,217 @@ Render the decision tree for a plan. **Examples** -

-$ agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ 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"                          │
-│    └─ ...                                                                                │
-╰──────────────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
-╭─ Tree Summary ─────────────╮
-│ Nodes: 9                   │
-│ Depth: 3                   │
-│ Child Plans: 2+            │
-│ Invariants: 2              │
-│ Superseded: 0 (hidden)     │
-╰────────────────────────────╯
+    ╭─ 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"                          │
+    │    └─ ...                                                                                │
+    ╰──────────────────────────────────────────────────────────────────────────────────────────╯
 
-╭─ Child Plans ──────────────────────────────────────╮
-│ ID          Phase    State                          │
-│ ──────────  ───────  ─────────                    │
-│ 01HXM9F1A   execute  processing                     │
-│ 01HXM9F2B   execute  queued                         │
-╰────────────────────────────────────────────────────╯
+    ╭─ Tree Summary ─────────────╮
+    │ Nodes: 9                   │
+    │ Depth: 3                   │
+    │ Child Plans: 2+            │
+    │ Invariants: 2              │
+    │ Superseded: 0 (hidden)     │
+    ╰────────────────────────────╯
 
-╭─ 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           │
-╰──────────────────────────────────────────────────╯
+    ╭─ Child Plans ──────────────────────────────────────╮
+    │ ID          Phase    State                          │
+    │ ──────────  ───────  ─────────                    │
+    │ 01HXM9F1A   execute  processing                     │
+    │ 01HXM9F2B   execute  queued                         │
+    ╰────────────────────────────────────────────────────╯
 
-✓ OK Decision tree rendered
-

+    ╭─ 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           │
+    ╰──────────────────────────────────────────────────╯
+
+    ✓ OK Decision tree rendered
+
+ +=== "Plain" + + ``` + $ 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" + +-- ... + + Tree Summary + Nodes: 9 + Depth: 3 + Child Plans: 2+ + Invariants: 2 + Superseded: 0 (hidden) + + Child Plans + ID Phase State + ---------- ------- --------- + 01HXM9F1A execute processing + 01HXM9F2B 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 + + [OK] Decision tree rendered + ``` + +=== "JSON" + + ```json + { + "command": "plan tree", + "status": "ok", + "exit_code": 0, + "data": { + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "tree": { + "type": "prompt_definition", + "description": "Increase test coverage to 85%", + "children": [ + { "type": "invariant_enforced", "description": "Prioritize financial transaction and user mgmt code" }, + { "type": "invariant_enforced", "description": "All API calls over TCP must be mocked" }, + { "type": "strategy_choice", "description": "Prioritize auth and payments", "confidence": 0.82 }, + { + "type": "subplan_parallel_spawn", + "description": "Implement auth and payment modules, in parallel", + "children": [ + { "type": "subplan_spawn", "description": "Write auth tests", "plan_id": "01HXM9F1A" }, + { "type": "subplan_spawn", "description": "Write payment tests", "plan_id": "01HXM9F2B" } + ] + }, + { + "type": "subplan_parallel_spawn", + "description": "Write tests for remaining modules", + "children": ["..."] + } + ] + }, + "summary": { + "nodes": 9, + "depth": 3, + "child_plans": "2+", + "invariants": 2, + "superseded": 0 + }, + "child_plans": [ + { "id": "01HXM9F1A", "phase": "execute", "state": "processing" }, + { "id": "01HXM9F2B", "phase": "execute", "state": "queued" } + ], + "decision_ids": { + "root": "01HXM9A0B1Q2W3R5G8Z0P4Q1X8", + "invariant_1": "01HXM9A0C1R3X4S6G9Z1P5Q2Y9", + "invariant_2": "01HXM9A0D2S4Y5T7H0Z2P6Q3Z0", + "strategy": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9", + "parallel_1": "01HXM9A1D3R8X5S7H1Z2P5Q2Y0", + "spawn_auth": "01HXM9A2D3Q8W4R6H9Z1P5Q2X0", + "spawn_payment": "01HXM9A3E4Q9W5R7I0Z2P6Q3X1", + "parallel_2": "01HXM9A4F5Q0W6R8J1Z3P7Q4X2" + } + }, + "timing": { + "started": "2026-02-08T12:58:00Z", + "duration_ms": 85 + }, + "messages": ["Decision tree rendered"] + } + ``` + +=== "YAML" + + ```yaml + command: plan tree + status: ok + exit_code: 0 + data: + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + tree: + type: prompt_definition + description: "Increase test coverage to 85%" + children: + - type: invariant_enforced + description: "Prioritize financial transaction and user mgmt code" + - type: invariant_enforced + description: "All API calls over TCP must be mocked" + - type: strategy_choice + description: "Prioritize auth and payments" + confidence: 0.82 + - type: subplan_parallel_spawn + description: "Implement auth and payment modules, in parallel" + children: + - type: subplan_spawn + description: "Write auth tests" + plan_id: "01HXM9F1A" + - type: subplan_spawn + description: "Write payment tests" + plan_id: "01HXM9F2B" + - type: subplan_parallel_spawn + description: "Write tests for remaining modules" + children: + - "..." + summary: + nodes: 9 + depth: 3 + child_plans: "2+" + invariants: 2 + superseded: 0 + child_plans: + - id: "01HXM9F1A" + phase: execute + state: processing + - id: "01HXM9F2B" + phase: execute + state: queued + decision_ids: + root: "01HXM9A0B1Q2W3R5G8Z0P4Q1X8" + invariant_1: "01HXM9A0C1R3X4S6G9Z1P5Q2Y9" + invariant_2: "01HXM9A0D2S4Y5T7H0Z2P6Q3Z0" + strategy: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" + parallel_1: "01HXM9A1D3R8X5S7H1Z2P5Q2Y0" + spawn_auth: "01HXM9A2D3Q8W4R6H9Z1P5Q2X0" + spawn_payment: "01HXM9A3E4Q9W5R7I0Z2P6Q3X1" + parallel_2: "01HXM9A4F5Q0W6R8J1Z3P7Q4X2" + timing: + started: "2026-02-08T12:58:00Z" + duration_ms: 85 + messages: + - "Decision tree rendered" + ``` ##### agents plan explain @@ -4021,98 +13698,356 @@ Show a detailed explanation for a decision. **Examples** -

-$ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --show-context
+=== "Rich"
 
-╭─ Decision ─────────────────────────────────────╮
-│ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9                 │
-│ Type: strategy_choice                          │
-│ Question: Which modules should be prioritized? │
-│ Chosen: Auth and payments                      │
-│ Confidence: 0.82                               │
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J               │
-│ Sequence: 2 of 5                               │
-│ Created: 2026-02-08 12:58                      │
-╰────────────────────────────────────────────────╯
+    

+    $ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --show-context
 
-╭─ Alternatives Considered ──────────────────────╮
-│ 1. Auth and payments (chosen)                  │
-│ 2. User module first (coverage 71%, med risk)  │
-│ 3. All modules equally (spread thin)           │
-╰────────────────────────────────────────────────╯
+    ╭─ Decision ─────────────────────────────────────╮
+    │ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9                 │
+    │ Type: strategy_choice                          │
+    │ Question: Which modules should be prioritized? │
+    │ Chosen: Auth and payments                      │
+    │ Confidence: 0.82                               │
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J               │
+    │ Sequence: 2 of 5                               │
+    │ Created: 2026-02-08 12:58                      │
+    ╰────────────────────────────────────────────────╯
 
-╭─ Impact ──────────────────────╮
-│ Downstream Decisions: 3       │
-│ Downstream Child Plans: 2     │
-│ Artifacts Produced: 5         │
-│ Correction Impact: medium     │
-╰───────────────────────────────╯
+    ╭─ Alternatives Considered ──────────────────────╮
+    │ 1. Auth and payments (chosen)                  │
+    │ 2. User module first (coverage 71%, med risk)  │
+    │ 3. All modules equally (spread thin)           │
+    ╰────────────────────────────────────────────────╯
 
-╭─ Context Snapshot ───────────────╮
-│ - Coverage < 70% in auth         │
-│ - Payments failures last release │
-│ - Auth: 12 files, 45% coverage   │
-│ - Payments: 8 files, 52% cover.  │
-│ Hot Context Hash: sha256:4b2e... │
-╰──────────────────────────────────╯
+    ╭─ Impact ──────────────────────╮
+    │ Downstream Decisions: 3       │
+    │ Downstream Child Plans: 2     │
+    │ Artifacts Produced: 5         │
+    │ Correction Impact: medium     │
+    ╰───────────────────────────────╯
 
-╭─ Rationale ───────────────────────────────────────╮
-│ Auth and payment modules have the lowest coverage │
-│ and highest business risk. Auth handles security  │
-│ tokens, payments handles money. Both had bugs in  │
-│ the last release traceable to missing tests.      │
-╰───────────────────────────────────────────────────╯
+    ╭─ Context Snapshot ───────────────╮
+    │ - Coverage < 70% in auth         │
+    │ - Payments failures last release │
+    │ - Auth: 12 files, 45% coverage   │
+    │ - Payments: 8 files, 52% cover.  │
+    │ Hot Context Hash: sha256:4b2e... │
+    ╰──────────────────────────────────╯
 
-╭─ Correction ──────────────────────────────────────────────╮
-│ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9            │
-│   --mode revert --guidance "Prioritize payments first..." │
-╰───────────────────────────────────────────────────────────╯
+    ╭─ Rationale ───────────────────────────────────────╮
+    │ Auth and payment modules have the lowest coverage │
+    │ and highest business risk. Auth handles security  │
+    │ tokens, payments handles money. Both had bugs in  │
+    │ the last release traceable to missing tests.      │
+    ╰───────────────────────────────────────────────────╯
 
-✓ OK Decision explained
-

+    ╭─ Correction ──────────────────────────────────────────────╮
+    │ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9            │
+    │   --mode revert --guidance "Prioritize payments first..." │
+    ╰───────────────────────────────────────────────────────────╯
+
+    ✓ OK Decision explained
+
+ +=== "Plain" + + ``` + $ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --show-context + + Decision + ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 + Type: strategy_choice + Question: Which modules should be prioritized? + Chosen: Auth and payments + Confidence: 0.82 + 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) + + Impact + Downstream Decisions: 3 + Downstream Child Plans: 2 + Artifacts Produced: 5 + Correction Impact: medium + + Context Snapshot + - Coverage < 70% in auth + - Payments failures last release + - Auth: 12 files, 45% coverage + - Payments: 8 files, 52% cover. + Hot Context Hash: sha256:4b2e... + + Rationale + Auth and payment modules have the lowest coverage + and highest business risk. Auth handles security + tokens, payments handles money. Both had bugs in + the last release traceable to missing tests. + + Correction + agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 + --mode revert --guidance "Prioritize payments first..." + + [OK] Decision explained + ``` + +=== "JSON" + + ```json + { + "command": "plan explain", + "status": "ok", + "exit_code": 0, + "data": { + "decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9", + "type": "strategy_choice", + "question": "Which modules should be prioritized?", + "chosen": "Auth and payments", + "confidence": 0.82, + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "sequence": "2 of 5", + "created": "2026-02-08T12:58:00Z", + "alternatives": [ + { "index": 1, "description": "Auth and payments", "chosen": true }, + { "index": 2, "description": "User module first (coverage 71%, med risk)", "chosen": false }, + { "index": 3, "description": "All modules equally (spread thin)", "chosen": false } + ], + "impact": { + "downstream_decisions": 3, + "downstream_child_plans": 2, + "artifacts_produced": 5, + "correction_impact": "medium" + }, + "context_snapshot": { + "items": [ + "Coverage < 70% in auth", + "Payments failures last release", + "Auth: 12 files, 45% coverage", + "Payments: 8 files, 52% cover." + ], + "hot_context_hash": "sha256:4b2e..." + }, + "rationale": "Auth and payment modules have the lowest coverage and highest business risk. Auth handles security tokens, payments handles money. Both had bugs in the last release traceable to missing tests.", + "correction_hint": "agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Prioritize payments first..."" + }, + "timing": { + "started": "2026-02-08T12:58:00Z", + "duration_ms": 110 + }, + "messages": ["Decision explained"] + } + ``` + +=== "YAML" + + ```yaml + command: plan explain + status: ok + exit_code: 0 + data: + decision_id: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" + type: strategy_choice + question: "Which modules should be prioritized?" + chosen: "Auth and payments" + confidence: 0.82 + plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + sequence: "2 of 5" + created: "2026-02-08T12:58:00Z" + alternatives: + - index: 1 + description: "Auth and payments" + chosen: true + - index: 2 + description: "User module first (coverage 71%, med risk)" + chosen: false + - index: 3 + description: "All modules equally (spread thin)" + chosen: false + impact: + downstream_decisions: 3 + downstream_child_plans: 2 + artifacts_produced: 5 + correction_impact: medium + context_snapshot: + items: + - "Coverage < 70% in auth" + - "Payments failures last release" + - "Auth: 12 files, 45% coverage" + - "Payments: 8 files, 52% cover." + hot_context_hash: "sha256:4b2e..." + rationale: >- + Auth and payment modules have the lowest coverage + and highest business risk. Auth handles security + tokens, payments handles money. Both had bugs in + the last release traceable to missing tests. + correction_hint: >- + agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 + --mode revert --guidance "Prioritize payments first..." + timing: + started: "2026-02-08T12:58:00Z" + duration_ms: 110 + messages: + - "Decision explained" + ``` Including the raw model reasoning with `--show-reasoning`: -

-$ agents plan explain --show-reasoning 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
+=== "Rich"
 
-╭─ Decision ──────────────────────────────╮
-│ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9          │
-│ Type: strategy_choice                   │
-│ Choice: Convert to async/await          │
-│ Alternatives: 3                         │
-╰─────────────────────────────────────────╯
+    

+    $ agents plan explain --show-reasoning 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
 
-╭─ Alternatives Considered ────────────────────────────────────╮
-│ 1. Convert to async/await patterns (chosen)                  │
-│    2. Keep synchronous with thread pool                      │
-│    3. Use callback-based approach                            │
-╰──────────────────────────────────────────────────────────────╯
+    ╭─ Decision ──────────────────────────────╮
+    │ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9          │
+    │ Type: strategy_choice                   │
+    │ Choice: Convert to async/await          │
+    │ Alternatives: 3                         │
+    ╰─────────────────────────────────────────╯
 
-╭─ 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.    │
-╰──────────────────────────────────────────────────────────────╯
+    ╭─ Alternatives Considered ────────────────────────────────────╮
+    │ 1. Convert to async/await patterns (chosen)                  │
+    │    2. Keep synchronous with thread pool                      │
+    │    3. Use callback-based approach                            │
+    ╰──────────────────────────────────────────────────────────────╯
 
-╭─ 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.              │
-╰───────────────────────────────────────────────────────────────╯
+    ╭─ 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.    │
+    ╰──────────────────────────────────────────────────────────────╯
 
-✓ OK Decision explained
-

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan explain", + "status": "ok", + "exit_code": 0, + "data": { + "decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9", + "type": "strategy_choice", + "choice": "Convert to async/await", + "alternatives_count": 3, + "alternatives": [ + { "index": 1, "description": "Convert to async/await patterns", "chosen": true }, + { "index": 2, "description": "Keep synchronous with thread pool", "chosen": false }, + { "index": 3, "description": "Use callback-based approach", "chosen": false } + ], + "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": "I need to decide on the concurrency pattern for the payment processing module. Let me analyze the current codebase:\n\n1. src/payments/api.py uses synchronous requests.\n2. src/core/scheduler.py already uses asyncio.\n3. The database driver (asyncpg) supports async natively.\n4. Project invariant says \"prefer modern Python patterns\".\n\nGiven 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." + }, + "timing": { + "started": "2026-02-08T12:58:00Z", + "duration_ms": 95 + }, + "messages": ["Decision explained"] + } + ``` + +=== "YAML" + + ```yaml + command: plan explain + status: ok + exit_code: 0 + data: + decision_id: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" + type: strategy_choice + choice: "Convert to async/await" + alternatives_count: 3 + alternatives: + - index: 1 + description: "Convert to async/await patterns" + chosen: true + - index: 2 + description: "Keep synchronous with thread pool" + chosen: false + - index: 3 + description: "Use callback-based approach" + chosen: false + 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: >- + 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. + timing: + started: "2026-02-08T12:58:00Z" + duration_ms: 95 + messages: + - "Decision explained" + ``` ##### agents plan correct @@ -4132,104 +14067,398 @@ 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
+=== "Rich"
 
-╭─ Correction ────────────────────────────────────────╮
-│ Mode: revert                                        │
-│ Impact: 3 decisions, 2 child plans, 5 artifacts     │
-│ New Decision: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8            │
-│ Corrects: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9                │
-│ Attempt: 2                                          │
-╰─────────────────────────────────────────────────────╯
+    

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

+    ╭─ History ───────────────────────────────────────────╮
+    │ - Original decision superseded                      │
+    │ - Prior artifacts archived for comparison           │
+    │ - agents plan diff --correction 01HXM9B7Z3Q1Q8K2..  │
+    ╰─────────────────────────────────────────────────────╯
+
+    ✓ OK Correction applied
+
+ +=== "Plain" + + ``` + $ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Prioritize payments first" --yes + + Correction + Mode: revert + Impact: 3 decisions, 2 child plans, 5 artifacts + New Decision: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 + Corrects: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 + Attempt: 2 + + Affected Subtree + Decisions Invalidated: 3 + Child Plans Rolled Back: 2 + Artifacts Archived: 5 + Unaffected Decisions: 2 + + Sandbox Rollback + Checkpoint: cp_01HXM8C2 + Files Reverted: 5 + Status: restored + + Recompute + Queued: 2 child plans + ETA: 4m + + History + - Original decision superseded + - Prior artifacts archived for comparison + - agents plan diff --correction 01HXM9B7Z3Q1Q8K2.. + + [OK] Correction applied + ``` + +=== "JSON" + + ```json + { + "command": "plan correct", + "status": "ok", + "exit_code": 0, + "data": { + "correction": { + "mode": "revert", + "impact": "3 decisions, 2 child plans, 5 artifacts", + "new_decision": "01HXM9B7Z3Q1Q8K2E9H7K3W2M8", + "corrects": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9", + "attempt": 2 + }, + "affected_subtree": { + "decisions_invalidated": 3, + "child_plans_rolled_back": 2, + "artifacts_archived": 5, + "unaffected_decisions": 2 + }, + "sandbox_rollback": { + "checkpoint": "cp_01HXM8C2", + "files_reverted": 5, + "status": "restored" + }, + "recompute": { + "queued": "2 child plans", + "eta": "4m" + }, + "history": [ + "Original decision superseded", + "Prior artifacts archived for comparison", + "agents plan diff --correction 01HXM9B7Z3Q1Q8K2.." + ] + }, + "timing": { "started": "2025-06-15T10:24:00Z", "duration_ms": 2350 }, + "messages": ["Correction applied"] + } + ``` + +=== "YAML" + + ```yaml + command: plan correct + status: ok + exit_code: 0 + data: + correction: + mode: revert + impact: "3 decisions, 2 child plans, 5 artifacts" + new_decision: "01HXM9B7Z3Q1Q8K2E9H7K3W2M8" + corrects: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" + attempt: 2 + affected_subtree: + decisions_invalidated: 3 + child_plans_rolled_back: 2 + artifacts_archived: 5 + unaffected_decisions: 2 + sandbox_rollback: + checkpoint: cp_01HXM8C2 + files_reverted: 5 + status: restored + recompute: + queued: "2 child plans" + eta: "4m" + history: + - "Original decision superseded" + - "Prior artifacts archived for comparison" + - "agents plan diff --correction 01HXM9B7Z3Q1Q8K2.." + timing: + started: "2025-06-15T10:24:00Z" + duration_ms: 2350 + messages: + - "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"
+=== "Rich"
 
-╭─ Correction ─────────────────────────────────────╮
-│ Mode: append                                     │
-│ Impact: adds to existing subtree, no rollback    │
-│ New Decision: 01HXM9C3Z5T2Q8K2E9H7K3W2M8         │
-│ Appended After: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9       │
-│ Attempt: 2                                       │
-╰──────────────────────────────────────────────────╯
+    

+    $ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode append \
+      --guidance "Also add rate limiting to the auth endpoints"
 
-╭─ 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.         │
-╰─────────────────────────────────────────────────────────────────╯
+    ╭─ Correction ─────────────────────────────────────╮
+    │ Mode: append                                     │
+    │ Impact: adds to existing subtree, no rollback    │
+    │ New Decision: 01HXM9C3Z5T2Q8K2E9H7K3W2M8         │
+    │ Appended After: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9       │
+    │ Attempt: 2                                       │
+    ╰──────────────────────────────────────────────────╯
 
-╭─ Queued ──────────╮
-│ New child: 1      │
-│ ETA: 2m           │
-╰───────────────────╯
+    ╭─ 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.         │
+    ╰─────────────────────────────────────────────────────────────────╯
 
-✓ OK Append correction queued
-

+    ╭─ Queued ──────────╮
+    │ New child: 1      │
+    │ ETA: 2m           │
+    ╰───────────────────╯
+
+    ✓ OK Append correction queued
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan correct", + "status": "ok", + "exit_code": 0, + "data": { + "correction": { + "mode": "append", + "impact": "adds to existing subtree, no rollback", + "new_decision": "01HXM9C3Z5T2Q8K2E9H7K3W2M8", + "appended_after": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9", + "attempt": 2 + }, + "append_detail": { + "original_decision_preserved": true, + "existing_artifacts_kept": true, + "additional_work": "appended as new child plan", + "note": "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" + } + }, + "timing": { "started": "2025-06-15T10:26:00Z", "duration_ms": 890 }, + "messages": ["Append correction queued"] + } + ``` + +=== "YAML" + + ```yaml + command: plan correct + status: ok + exit_code: 0 + data: + correction: + mode: append + impact: "adds to existing subtree, no rollback" + new_decision: "01HXM9C3Z5T2Q8K2E9H7K3W2M8" + appended_after: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" + attempt: 2 + append_detail: + original_decision_preserved: true + existing_artifacts_kept: true + additional_work: "appended as new child plan" + note: "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" + timing: + started: "2025-06-15T10:26:00Z" + duration_ms: 890 + messages: + - "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
+=== "Rich"
 
-╭─ Dry Run — Correction Preview ─────────────────────────────────────╮
-│ ⚠  This is a preview only. No changes will be made.                │
-╰────────────────────────────────────────────────────────────────────╯
+    

+    $ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert \
+      --guidance "Use async/await pattern instead" --dry-run
 
-╭─ 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)               │
-╰──────────────────────────────────────────────────────╯
+    ╭─ Dry Run — Correction Preview ─────────────────────────────────────╮
+    │ ⚠  This is a preview only. No changes will be made.                │
+    ╰────────────────────────────────────────────────────────────────────╯
 
-╭─ Estimated Cost ──────────╮
-│ Re-strategize: ~$0.012    │
-│ Re-execute: ~$0.035       │
-│ Total: ~$0.047            │
-│ ETA: ~4 minutes           │
-╰───────────────────────────╯
+    ╭─ 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)               │
+    ╰──────────────────────────────────────────────────────╯
 
-To execute this correction, remove --dry-run and add --yes
-

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Use async/await pattern instead" --dry-run + + Dry Run -- Correction Preview + WARNING: 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 x4 + 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan correct", + "status": "ok", + "exit_code": 0, + "data": { + "dry_run": true, + "would_revert": { + "decisions_to_invalidate": [ + { "id": "01HXM9A1..", "type": "strategy_choice", "label": "sync pattern" }, + { "id": "01HXM9A2..", "type": "implementation_choice", "label": "requests" }, + { "id": "01HXM9A3..", "type": "tool_invocation", "label": "write_file x4" } + ], + "child_plans_to_roll_back": 2, + "artifacts_to_archive": 5, + "unaffected_decisions": 2 + }, + "estimated_cost": { + "re_strategize": "$0.012", + "re_execute": "$0.035", + "total": "$0.047", + "eta": "~4 minutes" + } + }, + "timing": { "started": "2025-06-15T10:28:00Z", "duration_ms": 320 }, + "messages": ["To execute this correction, remove --dry-run and add --yes"] + } + ``` + +=== "YAML" + + ```yaml + command: plan correct + status: ok + exit_code: 0 + data: + dry_run: true + would_revert: + decisions_to_invalidate: + - id: "01HXM9A1.." + type: strategy_choice + label: "sync pattern" + - id: "01HXM9A2.." + type: implementation_choice + label: "requests" + - id: "01HXM9A3.." + type: tool_invocation + label: "write_file x4" + child_plans_to_roll_back: 2 + artifacts_to_archive: 5 + unaffected_decisions: 2 + estimated_cost: + re_strategize: "$0.012" + re_execute: "$0.035" + total: "$0.047" + eta: "~4 minutes" + timing: + started: "2025-06-15T10:28:00Z" + duration_ms: 320 + messages: + - "To execute this correction, remove --dry-run and add --yes" + ``` ##### agents plan diff @@ -4245,84 +14474,346 @@ Show diffs for a plan or a correction attempt. **Examples** -

-$ agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ Diff Summary ─────────────────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J               │
-│ Project: local/api-service                     │
-│ Files Changed: 2                               │
-│ Insertions: 12                                 │
-│ Deletions: 4                                   │
-│ Net Change: +8 lines                           │
-╰────────────────────────────────────────────────╯
+    

+    $ agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
-╭─ Files ───────────────────────────────╮
-│ Path                 Change  Status   │
-│ ───────────────────  ──────  ──────── │
-│ src/auth/session.py  +8 -2   modified │
-│ src/auth/tokens.py   +4 -2   modified │
-╰───────────────────────────────────────╯
+    ╭─ Diff Summary ─────────────────────────────────╮
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J               │
+    │ Project: local/api-service                     │
+    │ Files Changed: 2                               │
+    │ Insertions: 12                                 │
+    │ Deletions: 4                                   │
+    │ Net Change: +8 lines                           │
+    ╰────────────────────────────────────────────────╯
 
-╭─ 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                    │
-╰──────────────────────────────────────────╯
+    ╭─ Files ───────────────────────────────╮
+    │ Path                 Change  Status   │
+    │ ───────────────────  ──────  ──────── │
+    │ src/auth/session.py  +8 -2   modified │
+    │ src/auth/tokens.py   +4 -2   modified │
+    ╰───────────────────────────────────────╯
 
-╭─ Risk Assessment ────────────────╮
-│ API Compatibility: preserved     │
-│ Test Coverage: maintained        │
-│ Breaking Changes: none detected  │
-╰──────────────────────────────────╯
+    ╭─ 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                    │
+    ╰──────────────────────────────────────────╯
 
-✓ OK Diff generated
-

+    ╭─ Risk Assessment ────────────────╮
+    │ API Compatibility: preserved     │
+    │ Test Coverage: maintained        │
+    │ Breaking Changes: none detected  │
+    ╰──────────────────────────────────╯
+
+    ✓ OK Diff generated
+
+ +=== "Plain" + + ``` + $ agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + Diff Summary + 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 + + 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 + + [OK] Diff generated + ``` + +=== "JSON" + + ```json + { + "command": "plan diff", + "status": "ok", + "exit_code": 0, + "data": { + "diff_summary": { + "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "project": "local/api-service", + "files_changed": 2, + "insertions": 12, + "deletions": 4, + "net_change": "+8 lines" + }, + "files": [ + { "path": "src/auth/session.py", "change": "+8 -2", "status": "modified" }, + { "path": "src/auth/tokens.py", "change": "+4 -2", "status": "modified" } + ], + "patch_preview": [ + { + "file": "src/auth/session.py", + "hunks": [ + { + "range": "@@ -12,4 +12,10 @@", + "deletions": ["import jwt", "def validate_token(...)"], + "insertions": ["import sessionlib", "def validate_session(...)"] + } + ] + }, + { + "file": "src/auth/tokens.py", + "hunks": [ + { + "range": "@@ -5,3 +5,7 @@", + "deletions": ["TOKEN_EXPIRY = 3600"], + "insertions": ["TOKEN_EXPIRY = 7200"] + } + ] + } + ], + "risk_assessment": { + "api_compatibility": "preserved", + "test_coverage": "maintained", + "breaking_changes": "none detected" + } + }, + "timing": { "started": "2025-06-15T10:30:00Z", "duration_ms": 750 }, + "messages": ["Diff generated"] + } + ``` + +=== "YAML" + + ```yaml + command: plan diff + status: ok + exit_code: 0 + data: + diff_summary: + plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + project: local/api-service + files_changed: 2 + insertions: 12 + deletions: 4 + net_change: "+8 lines" + files: + - path: src/auth/session.py + change: "+8 -2" + status: modified + - path: src/auth/tokens.py + change: "+4 -2" + status: modified + patch_preview: + - file: src/auth/session.py + hunks: + - range: "@@ -12,4 +12,10 @@" + deletions: + - "import jwt" + - "def validate_token(...)" + insertions: + - "import sessionlib" + - "def validate_session(...)" + - file: src/auth/tokens.py + hunks: + - range: "@@ -5,3 +5,7 @@" + deletions: + - "TOKEN_EXPIRY = 3600" + insertions: + - "TOKEN_EXPIRY = 7200" + risk_assessment: + api_compatibility: preserved + test_coverage: maintained + breaking_changes: none detected + timing: + started: "2025-06-15T10:30:00Z" + duration_ms: 750 + messages: + - "Diff generated" + ``` Showing the diff for a specific correction attempt, comparing what changed between the original and corrected execution: -

-$ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
+=== "Rich"
 
-╭─ Correction Diff ───────────────────────────────╮
-│ Correction: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8          │
-│ Original Decision: 01HXM9A1C2Q7W3R5..           │
-│ Mode: revert                                    │
-│ Files Changed: 3                                │
-│ New Insertions: 18                              │
-│ New Deletions: 6                                │
-╰─────────────────────────────────────────────────╯
+    

+    $ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
 
-╭─ 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)       │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ Correction Diff ───────────────────────────────╮
+    │ Correction: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8          │
+    │ Original Decision: 01HXM9A1C2Q7W3R5..           │
+    │ Mode: revert                                    │
+    │ Files Changed: 3                                │
+    │ New Insertions: 18                              │
+    │ New Deletions: 6                                │
+    ╰─────────────────────────────────────────────────╯
 
-╭─ 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               │
-│   ...                                             │
-╰───────────────────────────────────────────────────╯
+    ╭─ 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)       │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-✓ OK Correction diff generated
-

+    ╭─ 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
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "plan diff", + "status": "ok", + "exit_code": 0, + "data": { + "correction_diff": { + "correction": "01HXM9B7Z3Q1Q8K2E9H7K3W2M8", + "original_decision": "01HXM9A1C2Q7W3R5..", + "mode": "revert", + "files_changed": 3, + "new_insertions": 18, + "new_deletions": 6 + }, + "comparison": [ + { "file": "src/payments/api.py", "before": "+12 -4", "after": "+18 -6 (expanded)" }, + { "file": "src/auth/tokens.py", "before": "+8 -2", "after": "(unchanged)" }, + { "file": "tests/test_payments.py", "before": "(new file)", "after": "(new file, larger)" } + ], + "patch_preview": [ + { + "file": "src/payments/api.py", + "context": "corrected vs original", + "hunks": [ + { + "range": "@@ -1,12 +1,18 @@", + "deletions": ["# sync payment processing"], + "insertions": ["# async payment processing (corrected)", "import asyncio", "from aiohttp import ClientSession"] + } + ] + } + ] + }, + "timing": { "started": "2025-06-15T10:32:00Z", "duration_ms": 920 }, + "messages": ["Correction diff generated"] + } + ``` + +=== "YAML" + + ```yaml + command: plan diff + status: ok + exit_code: 0 + data: + correction_diff: + correction: "01HXM9B7Z3Q1Q8K2E9H7K3W2M8" + original_decision: "01HXM9A1C2Q7W3R5.." + mode: revert + files_changed: 3 + new_insertions: 18 + new_deletions: 6 + comparison: + - file: src/payments/api.py + before: "+12 -4" + after: "+18 -6 (expanded)" + - file: src/auth/tokens.py + before: "+8 -2" + after: "(unchanged)" + - file: tests/test_payments.py + before: "(new file)" + after: "(new file, larger)" + patch_preview: + - file: src/payments/api.py + context: "corrected vs original" + hunks: + - range: "@@ -1,12 +1,18 @@" + deletions: + - "# sync payment processing" + insertions: + - "# async payment processing (corrected)" + - "import asyncio" + - "from aiohttp import ClientSession" + timing: + started: "2025-06-15T10:32:00Z" + duration_ms: 920 + messages: + - "Correction diff generated" + ``` ##### agents plan artifacts @@ -4337,34 +14828,141 @@ List artifacts produced by a plan. **Examples** -

-$ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
+=== "Rich"
 
-╭─ 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       │
-╰─────────────────────────────────────────────────────────────╯
+    

+    $ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
 
-╭─ Summary ───────────╮
-│ Total: 4            │
-│ Writes: 2 (new)     │
-│ Edits: 2 (modified) │
-│ Deletes: 0          │
-│ Total Size: 11.8 KB │
-╰─────────────────────╯
+    ╭─ 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       │
+    ╰─────────────────────────────────────────────────────────────╯
 
-╭─ By Plan ─────────────────╮
-│ Root Plan: 3 artifacts    │
-│ auth-tests: 1 artifact    │
-│ payment-tests: (pending)  │
-╰───────────────────────────╯
+    ╭─ Summary ───────────╮
+    │ Total: 4            │
+    │ Writes: 2 (new)     │
+    │ Edits: 2 (modified) │
+    │ Deletes: 0          │
+    │ Total Size: 11.8 KB │
+    ╰─────────────────────╯
 
-✓ OK 4 artifacts listed
-

+    ╭─ By Plan ─────────────────╮
+    │ Root Plan: 3 artifacts    │
+    │ auth-tests: 1 artifact    │
+    │ payment-tests: (pending)  │
+    ╰───────────────────────────╯
+
+    ✓ OK 4 artifacts listed
+
+ +=== "Plain" + + ``` + $ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J + + 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 + + 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) + + [OK] 4 artifacts listed + ``` + +=== "JSON" + + ```json + { + "command": "plan artifacts", + "status": "ok", + "exit_code": 0, + "data": { + "artifacts": [ + { "path": "src/auth/session.py", "type": "write", "size": "2.1 KB", "change": "+8 -2", "child_plan": "root" }, + { "path": "tests/test_session.py", "type": "write", "size": "4.7 KB", "change": "+47 -0", "child_plan": "root" }, + { "path": "src/auth/tokens.py", "type": "edit", "size": "1.8 KB", "change": "+4 -2", "child_plan": "root" }, + { "path": "tests/test_tokens.py", "type": "write", "size": "3.2 KB", "change": "+32 -0", "child_plan": "auth" } + ], + "summary": { + "total": 4, + "writes": 2, + "edits": 2, + "deletes": 0, + "total_size": "11.8 KB" + }, + "by_plan": { + "root": 3, + "auth-tests": 1, + "payment-tests": "pending" + } + }, + "timing": { "started": "2025-06-15T10:33:00Z", "duration_ms": 480 }, + "messages": ["4 artifacts listed"] + } + ``` + +=== "YAML" + + ```yaml + command: plan artifacts + status: ok + exit_code: 0 + data: + artifacts: + - path: src/auth/session.py + type: write + size: "2.1 KB" + change: "+8 -2" + child_plan: root + - path: tests/test_session.py + type: write + size: "4.7 KB" + change: "+47 -0" + child_plan: root + - path: src/auth/tokens.py + type: edit + size: "1.8 KB" + change: "+4 -2" + child_plan: root + - path: tests/test_tokens.py + type: write + size: "3.2 KB" + change: "+32 -0" + child_plan: auth + summary: + total: 4 + writes: 2 + edits: 2 + deletes: 0 + total_size: "11.8 KB" + by_plan: + root: 3 + auth-tests: 1 + payment-tests: pending + timing: + started: "2025-06-15T10:33:00Z" + duration_ms: 480 + messages: + - "4 artifacts listed" + ``` ##### agents plan prompt @@ -4380,37 +14978,120 @@ Provide additional guidance to a plan, typically when it is errored or awaiting **Examples** -

-$ agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
+=== "Rich"
 
-╭─ Guidance Added ────────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J        │
-│ Guidance: Use mocks for database tests  │
-│ Scope: next execution step              │
-│ Phase: execute                          │
-│ State: errored → processing             │
-╰─────────────────────────────────────────╯
+    

+    $ agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
 
-╭─ Decision Created ────────────────────────╮
-│ Type: user_intervention                   │
-│ ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3            │
-│ Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9        │
-╰───────────────────────────────────────────╯
+    ╭─ Guidance Added ────────────────────────╮
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J        │
+    │ Guidance: Use mocks for database tests  │
+    │ Scope: next execution step              │
+    │ Phase: execute                          │
+    │ State: errored → processing             │
+    ╰─────────────────────────────────────────╯
 
-╭─ Queue ────╮
-│ Pending: 1 │
-│ Applied: 0 │
-╰────────────╯
+    ╭─ Decision Created ────────────────────────╮
+    │ Type: user_intervention                   │
+    │ ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3            │
+    │ Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9        │
+    ╰───────────────────────────────────────────╯
 
-✓ OK Guidance queued
-

+    ╭─ Queue ────╮
+    │ Pending: 1 │
+    │ Applied: 0 │
+    ╰────────────╯
+
+    ✓ OK Guidance queued
+
+ +=== "Plain" + + ``` + $ 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 + + Decision Created + Type: user_intervention + ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3 + Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 + + Queue + Pending: 1 + Applied: 0 + + [OK] Guidance queued + ``` + +=== "JSON" + + ```json + { + "command": "plan prompt", + "status": "ok", + "exit_code": 0, + "data": { + "guidance_added": { + "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "guidance": "Use mocks for database tests", + "scope": "next execution step", + "phase": "execute", + "state_transition": "errored -> processing" + }, + "decision_created": { + "type": "user_intervention", + "id": "01HXM9C5G7R2X8S3K4Z5Q8R6Y3", + "parent": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" + }, + "queue": { + "pending": 1, + "applied": 0 + } + }, + "timing": { "started": "2025-06-15T10:35:00Z", "duration_ms": 620 }, + "messages": ["Guidance queued"] + } + ``` + +=== "YAML" + + ```yaml + command: plan prompt + status: ok + exit_code: 0 + data: + guidance_added: + plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + guidance: "Use mocks for database tests" + scope: next execution step + phase: execute + state_transition: "errored -> processing" + decision_created: + type: user_intervention + id: "01HXM9C5G7R2X8S3K4Z5Q8R6Y3" + parent: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" + queue: + pending: 1 + applied: 0 + timing: + started: "2025-06-15T10:35:00Z" + duration_ms: 620 + messages: + - "Guidance queued" + ``` ##### agents plan rollback 
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>
-**Purpose** -Rollback a plan sandbox to a checkpoint. +!!! danger "Destructive Operation" + Rollback a plan sandbox to a previous checkpoint. All changes made ==after== the target checkpoint are **reverted**: files are restored or removed, decisions are discarded, and tool calls are undone. Child plans spawned after the checkpoint are invalidated. **Arguments** @@ -4420,49 +15101,171 @@ Rollback a plan sandbox to a checkpoint. **Examples** -

-$ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
+=== "Rich"
 
-Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
+    

+    $ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
 
-╭─ Rollback Summary ───────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Checkpoint: cp_01HXM8C2          │
-│ Label: before auth refactor      │
-│ Files: 6 reverted                │
-╰──────────────────────────────────╯
+    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    │
-╰─────────────────────────────────────╯
+    ╭─ Rollback Summary ───────────────╮
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
+    │ Checkpoint: cp_01HXM8C2          │
+    │ Label: before auth refactor      │
+    │ Files: 6 reverted                │
+    ╰──────────────────────────────────╯
 
-╭─ Impact ──────────────────────────────╮
-│ Child Plans Invalidated: 2            │
-│ Sandbox: restored to cp_01HXM8C2      │
-│ Decisions After CP: 2 discarded       │
-│ Tool Calls After CP: 5 undone         │
-╰───────────────────────────────────────╯
+    ╭─ 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    │
+    ╰─────────────────────────────────────╯
 
-╭─ Post-Rollback State ──────────╮
-│ Phase: execute                 │
-│ State: queued (awaiting input) │
-│ Checkpoints Remaining: 2       │
-╰────────────────────────────────╯
+    ╭─ Impact ──────────────────────────────╮
+    │ Child Plans Invalidated: 2            │
+    │ Sandbox: restored to cp_01HXM8C2      │
+    │ Decisions After CP: 2 discarded       │
+    │ Tool Calls After CP: 5 undone         │
+    ╰───────────────────────────────────────╯
 
-✓ OK Rollback complete
-

+    ╭─ Post-Rollback State ──────────╮
+    │ Phase: execute                 │
+    │ State: queued (awaiting input) │
+    │ Checkpoints Remaining: 2       │
+    ╰────────────────────────────────╯
+
+    ✓ OK Rollback complete
+
+ +=== "Plain" + + ``` + $ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2 + + Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y + + Rollback Summary + Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + Checkpoint: cp_01HXM8C2 + Label: before auth refactor + Files: 6 reverted + + 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 + + Impact + 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 + + [OK] Rollback complete + ``` + +=== "JSON" + + ```json + { + "command": "plan rollback", + "status": "ok", + "exit_code": 0, + "data": { + "rollback_summary": { + "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "checkpoint": "cp_01HXM8C2", + "label": "before auth refactor", + "files_reverted": 6 + }, + "changes_reverted": [ + { "file": "src/auth/session.py", "action": "restored" }, + { "file": "src/auth/tokens.py", "action": "restored" }, + { "file": "tests/test_session.py", "action": "removed" }, + { "file": "tests/test_tokens.py", "action": "removed" }, + { "file": "src/auth/fixtures.py", "action": "restored" }, + { "file": "src/auth/__init__.py", "action": "restored" } + ], + "impact": { + "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 + } + }, + "timing": { "started": "2025-06-15T10:37:00Z", "duration_ms": 1850 }, + "messages": ["Rollback complete"] + } + ``` + +=== "YAML" + + ```yaml + command: plan rollback + status: ok + exit_code: 0 + data: + rollback_summary: + plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J" + checkpoint: cp_01HXM8C2 + label: before auth refactor + files_reverted: 6 + changes_reverted: + - file: src/auth/session.py + action: restored + - file: src/auth/tokens.py + action: restored + - file: tests/test_session.py + action: removed + - file: tests/test_tokens.py + action: removed + - file: src/auth/fixtures.py + action: restored + - file: src/auth/__init__.py + action: restored + impact: + 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 + timing: + started: "2025-06-15T10:37:00Z" + duration_ms: 1850 + messages: + - "Rollback complete" + ``` #### agents action -**Purpose** -Manage reusable actions. +!!! info "Purpose" + Manage ==reusable actions== — named templates that define a complete unit of work including strategy actors, execution actors, definition of done, arguments, and invariants. Actions serve as the entry point to the plan lifecycle. + +??? tip "Action vs Plan" + An **action** is a ==template==; a **plan** is an ==instance==. When you run `agents plan use `, the action template spawns a new plan that progresses through the lifecycle phases. Actions can be reused many times (default) or configured as single-use (`reusable: false`). ##### agents action create @@ -4477,38 +15280,137 @@ Create a new action template from a YAML configuration file. The `--config` file **Examples** -

-$ agents action create --config ./actions/code-coverage.yaml
+=== "Rich"
 
-╭─ Action Created ────────────────────────╮
-│ Name: local/code-coverage               │
-│ State: available                        │
-│ Strategy Actor: local/strategist        │
-│ Execution Actor: local/executor         │
-│ Reusable: yes                           │
-│ Read Only: no                           │
-│ Config: ./actions/code-coverage.yaml    │
-│ Created: 2026-02-08 12:20               │
-╰─────────────────────────────────────────╯
+    

+    $ agents action create --config ./actions/code-coverage.yaml
 
-╭─ Definition of Done ─╮
-│ Coverage reaches 85% │
-╰──────────────────────╯
+    ╭─ Action Created ────────────────────────╮
+    │ Name: local/code-coverage               │
+    │ State: available                        │
+    │ Strategy Actor: local/strategist        │
+    │ Execution Actor: local/executor         │
+    │ Reusable: yes                           │
+    │ Read Only: no                           │
+    │ Config: ./actions/code-coverage.yaml    │
+    │ Created: 2026-02-08 12:20               │
+    ╰─────────────────────────────────────────╯
 
-╭─ Arguments ──────────────────────────────────────────────────────╮
-│ Name                     Type    Required  Description           │
-│ ───────────────────────  ──────  ────────  ───────────────────── │
-│ target_coverage_percent  int     yes       Target coverage %     │
-│ test_command             string  no        Test framework to use │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ Definition of Done ─╮
+    │ Coverage reaches 85% │
+    ╰──────────────────────╯
 
-╭─ Automation ──────────────────────────╮
-│ Profile: supervised                   │
-│ Source: default                       │
-╰───────────────────────────────────────╯
+    ╭─ Arguments ──────────────────────────────────────────────────────╮
+    │ Name                     Type    Required  Description           │
+    │ ───────────────────────  ──────  ────────  ───────────────────── │
+    │ target_coverage_percent  int     yes       Target coverage %     │
+    │ test_command             string  no        Test framework to use │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-✓ OK Action created
-

+    ╭─ Automation ──────────────────────────╮
+    │ Profile: supervised                   │
+    │ Source: default                       │
+    ╰───────────────────────────────────────╯
+
+    ✓ OK Action created
+
+ +=== "Plain" + + ``` + $ agents action create --config ./actions/code-coverage.yaml + + Action Created + Name: local/code-coverage + State: available + 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 + ``` + +=== "JSON" + + ```json + { + "command": "action create", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/code-coverage", + "state": "available", + "strategy_actor": "local/strategist", + "execution_actor": "local/executor", + "reusable": true, + "read_only": false, + "config": "./actions/code-coverage.yaml", + "created": "2026-02-08T12:20:00Z", + "definition_of_done": "Coverage reaches 85%", + "arguments": [ + { "name": "target_coverage_percent", "type": "int", "required": true, "description": "Target coverage %" }, + { "name": "test_command", "type": "string", "required": false, "description": "Test framework to use" } + ], + "automation": { + "profile": "supervised", + "source": "default" + } + }, + "timing": { "started": "2026-02-08T12:20:00Z", "duration_ms": 110 }, + "messages": ["Action created"] + } + ``` + +=== "YAML" + + ```yaml + command: action create + status: ok + exit_code: 0 + data: + name: local/code-coverage + state: available + strategy_actor: local/strategist + execution_actor: local/executor + reusable: true + read_only: false + config: "./actions/code-coverage.yaml" + created: "2026-02-08T12:20:00Z" + definition_of_done: "Coverage reaches 85%" + arguments: + - name: target_coverage_percent + type: int + required: true + description: "Target coverage %" + - name: test_command + type: string + required: false + description: "Test framework to use" + automation: + profile: supervised + source: default + timing: + started: "2026-02-08T12:20:00Z" + duration_ms: 110 + messages: + - "Action created" + ``` ##### agents action list @@ -4524,29 +15426,109 @@ List actions with optional filters. **Examples** -

-$ agents action list
+=== "Rich"
 
-╭─ Actions ──────────────────────────────────────────────────────────────────────────────────╮
-│ Name                 State      Strategy Actor    Execution Actor  Reusable  Plans         │
-│ ───────────────────  ─────────  ────────────────  ───────────────  ────────  ─────         │
-│ local/code-coverage  available  local/strategist  local/executor   ✓         3             │
-╰────────────────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents action list
 
-╭─ Filters ────────╮
-│ State: available │
-│ Namespace: (any) │
-╰──────────────────╯
+    ╭─ Actions ──────────────────────────────────────────────────────────────────────────────────╮
+    │ Name                 State      Strategy Actor    Execution Actor  Reusable  Plans         │
+    │ ───────────────────  ─────────  ────────────────  ───────────────  ────────  ─────         │
+    │ local/code-coverage  available  local/strategist  local/executor   ✓         3             │
+    ╰────────────────────────────────────────────────────────────────────────────────────────────╯
 
-╭─ Summary ──────────────╮
-│ Total: 1               │
-│ Available: 1           │
-│ Archived: 0            │
-│ Total Plans Created: 3 │
-╰────────────────────────╯
+    ╭─ Filters ────────╮
+    │ State: available │
+    │ Namespace: (any) │
+    ╰──────────────────╯
 
-✓ OK 1 action listed
-

+    ╭─ Summary ──────────────╮
+    │ Total: 1               │
+    │ Available: 1           │
+    │ Archived: 0            │
+    │ Total Plans Created: 3 │
+    ╰────────────────────────╯
+
+    ✓ OK 1 action listed
+
+ +=== "Plain" + + ``` + $ agents action list + + Actions + Name State Strategy Actor Execution Actor Reusable Plans + ------------------- --------- ---------------- --------------- -------- ----- + local/code-coverage available local/strategist local/executor yes 3 + + Filters + State: available + Namespace: (any) + + Summary + Total: 1 + Available: 1 + Archived: 0 + Total Plans Created: 3 + + [OK] 1 action listed + ``` + +=== "JSON" + + ```json + { + "command": "action list", + "status": "ok", + "exit_code": 0, + "data": { + "actions": [ + { + "name": "local/code-coverage", + "state": "available", + "strategy_actor": "local/strategist", + "execution_actor": "local/executor", + "reusable": true, + "plans": 3 + } + ], + "filters": { "state": "available", "namespace": null }, + "summary": { "total": 1, "available": 1, "archived": 0, "total_plans_created": 3 } + }, + "timing": { "started": "2026-02-08T12:21:00Z", "duration_ms": 45 }, + "messages": ["1 action listed"] + } + ``` + +=== "YAML" + + ```yaml + command: action list + status: ok + exit_code: 0 + data: + actions: + - name: local/code-coverage + state: available + strategy_actor: local/strategist + execution_actor: local/executor + reusable: true + plans: 3 + filters: + state: available + namespace: null + summary: + total: 1 + available: 1 + archived: 0 + total_plans_created: 3 + timing: + started: "2026-02-08T12:21:00Z" + duration_ms: 45 + messages: + - "1 action listed" + ``` ##### agents action show @@ -4561,50 +15543,167 @@ Show details for an action. **Examples** -

-$ agents action show local/code-coverage
+=== "Rich"
 
-╭─ Action Details ──────────────────────╮
-│ Name: local/code-coverage             │
-│ State: available                      │
-│ Strategy Actor: local/strategist      │
-│ Execution Actor: local/executor       │
-│ Reusable: yes                         │
-│ Read Only: no                         │
-│ Created: 2026-02-08 12:20             │
-╰───────────────────────────────────────╯
+    

+    $ agents action show local/code-coverage
 
-╭─ Definition of Done ─╮
-│ Coverage reaches 85% │
-╰──────────────────────╯
+    ╭─ Action Details ──────────────────────╮
+    │ Name: local/code-coverage             │
+    │ State: available                      │
+    │ Strategy Actor: local/strategist      │
+    │ Execution Actor: local/executor       │
+    │ Reusable: yes                         │
+    │ Read Only: no                         │
+    │ Created: 2026-02-08 12:20             │
+    ╰───────────────────────────────────────╯
 
-╭─ Arguments ──────────────────────────────────────────────────────╮
-│ Name                     Type    Required  Description           │
-│ ───────────────────────  ──────  ────────  ───────────────────── │
-│ target_coverage_percent  int     yes       Target coverage %     │
-│ test_command             string  no        Test framework to use │
-╰──────────────────────────────────────────────────────────────────╯
+    ╭─ Definition of Done ─╮
+    │ Coverage reaches 85% │
+    ╰──────────────────────╯
 
-╭─ Automation ──────────────────────────╮
-│ Profile: supervised                   │
-│ Source: default                       │
-╰───────────────────────────────────────╯
+    ╭─ Arguments ──────────────────────────────────────────────────────╮
+    │ Name                     Type    Required  Description           │
+    │ ───────────────────────  ──────  ────────  ───────────────────── │
+    │ target_coverage_percent  int     yes       Target coverage %     │
+    │ test_command             string  no        Test framework to use │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-╭─ History ────────────────────╮
-│ Plans Created: 3             │
-│ Plans Completed: 2           │
-│ Plans Failed: 0              │
-│ Avg Duration: 00:04:30       │
-│ Avg Cost: $0.072             │
-╰──────────────────────────────╯
+    ╭─ Automation ──────────────────────────╮
+    │ Profile: supervised                   │
+    │ Source: default                       │
+    ╰───────────────────────────────────────╯
 
-╭─ Usage ───────────────────────────────────────────────────────────╮
-│ - agents plan use local/code-coverage local/api-service           │
-│     --arg target_coverage_percent=85                              │
-╰───────────────────────────────────────────────────────────────────╯
+    ╭─ History ────────────────────╮
+    │ Plans Created: 3             │
+    │ Plans Completed: 2           │
+    │ Plans Failed: 0              │
+    │ Avg Duration: 00:04:30       │
+    │ Avg Cost: $0.072             │
+    ╰──────────────────────────────╯
 
-✓ OK Action loaded
-

+    ╭─ Usage ───────────────────────────────────────────────────────────╮
+    │ - agents plan use local/code-coverage local/api-service           │
+    │     --arg target_coverage_percent=85                              │
+    ╰───────────────────────────────────────────────────────────────────╯
+
+    ✓ OK Action loaded
+
+ +=== "Plain" + + ``` + $ agents action show local/code-coverage + + Action Details + Name: local/code-coverage + State: available + Strategy Actor: local/strategist + Execution Actor: local/executor + Reusable: yes + Read Only: no + 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 + + History + 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 local/api-service + --arg target_coverage_percent=85 + + [OK] Action loaded + ``` + +=== "JSON" + + ```json + { + "command": "action show", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/code-coverage", + "state": "available", + "strategy_actor": "local/strategist", + "execution_actor": "local/executor", + "reusable": true, + "read_only": false, + "created": "2026-02-08T12:20:00Z", + "definition_of_done": "Coverage reaches 85%", + "arguments": [ + { "name": "target_coverage_percent", "type": "int", "required": true, "description": "Target coverage %" }, + { "name": "test_command", "type": "string", "required": false, "description": "Test framework to use" } + ], + "automation": { "profile": "supervised", "source": "default" }, + "history": { + "plans_created": 3, + "plans_completed": 2, + "plans_failed": 0, + "avg_duration": "00:04:30", + "avg_cost": "$0.072" + } + }, + "timing": { "started": "2026-02-08T12:21:00Z", "duration_ms": 60 }, + "messages": ["Action loaded"] + } + ``` + +=== "YAML" + + ```yaml + command: action show + status: ok + exit_code: 0 + data: + name: local/code-coverage + state: available + strategy_actor: local/strategist + execution_actor: local/executor + reusable: true + read_only: false + created: "2026-02-08T12:20:00Z" + definition_of_done: "Coverage reaches 85%" + arguments: + - name: target_coverage_percent + type: int + required: true + description: "Target coverage %" + - name: test_command + type: string + required: false + description: "Test framework to use" + automation: + profile: supervised + source: default + history: + plans_created: 3 + plans_completed: 2 + plans_failed: 0 + avg_duration: "00:04:30" + avg_cost: "$0.072" + timing: + started: "2026-02-08T12:21:00Z" + duration_ms: 60 + messages: + - "Action loaded" + ``` ##### agents action archive @@ -4619,35 +15718,138 @@ Archive an action. **Examples** -

-$ agents action archive local/old-action
+=== "Rich"
 
-╭─ Action Archived ───────────╮
-│ Name: local/old-action      │
-│ State: available → archived │
-│ Archived: 2026-02-08 12:22  │
-╰─────────────────────────────╯
+    

+    $ agents action archive local/old-action
 
-╭─ Impact ───────────────────────╮
-│ Availability: hidden from list │
-│ Existing Plans: unchanged      │
-│ Active Plans: 0 affected       │
-╰────────────────────────────────╯
+    ╭─ Action Archived ───────────╮
+    │ Name: local/old-action      │
+    │ State: available → archived │
+    │ Archived: 2026-02-08 12:22  │
+    ╰─────────────────────────────╯
 
-╭─ History ─────────────────╮
-│ Total Plans: 5            │
-│ Completed: 4              │
-│ Failed: 1                 │
-│ Last Used: 2026-02-06     │
-╰───────────────────────────╯
+    ╭─ Impact ───────────────────────╮
+    │ Availability: hidden from list │
+    │ Existing Plans: unchanged      │
+    │ Active Plans: 0 affected       │
+    ╰────────────────────────────────╯
 
-✓ OK Action archived
-

+    ╭─ History ─────────────────╮
+    │ Total Plans: 5            │
+    │ Completed: 4              │
+    │ Failed: 1                 │
+    │ Last Used: 2026-02-06     │
+    ╰───────────────────────────╯
+
+    ✓ OK Action archived
+
+ +=== "Plain" + + ``` + $ agents action archive local/old-action + + Action Archived + Name: local/old-action + State: available -> archived + Archived: 2026-02-08 12:22 + + Impact + Availability: hidden from list + Existing Plans: unchanged + Active Plans: 0 affected + + History + Total Plans: 5 + Completed: 4 + Failed: 1 + Last Used: 2026-02-06 + + [OK] Action archived + ``` + +=== "JSON" + + ```json + { + "command": "action archive", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/old-action", + "state_transition": "available -> archived", + "archived": "2026-02-08T12:22:00Z", + "impact": { + "availability": "hidden from list", + "existing_plans": "unchanged", + "active_plans_affected": 0 + }, + "history": { + "total_plans": 5, + "completed": 4, + "failed": 1, + "last_used": "2026-02-06" + } + }, + "timing": { "started": "2026-02-08T12:22:00Z", "duration_ms": 55 }, + "messages": ["Action archived"] + } + ``` + +=== "YAML" + + ```yaml + command: action archive + status: ok + exit_code: 0 + data: + name: local/old-action + state_transition: "available -> archived" + archived: "2026-02-08T12:22:00Z" + impact: + availability: hidden from list + existing_plans: unchanged + active_plans_affected: 0 + history: + total_plans: 5 + completed: 4 + failed: 1 + last_used: "2026-02-06" + timing: + started: "2026-02-08T12:22:00Z" + duration_ms: 55 + messages: + - "Action archived" + ``` #### agents automation-profile -**Purpose** -Manage automation profiles — named collections of confidence thresholds (floating-point values from 0.0 to 1.0) that control which tasks are automated vs. require human approval. Each threshold specifies the minimum confidence level at which the system proceeds automatically; below the threshold, the system drops to manual mode. A threshold of 0.0 means "always automatic" and 1.0 means "always manual." Built-in profiles (`manual`, `review`, `supervised`, `cautious`, `trusted`, `auto`, `ci`, `full-auto`) are always available. Custom profiles follow the same `/` naming convention as other entities. +!!! info "Purpose" + Manage ==automation profiles== — named collections of confidence thresholds (floating-point values from `0.0` to `1.0`) that control which tasks are automated vs. require human approval. Each threshold specifies the minimum confidence level at which the system proceeds automatically; below the threshold, the system drops to manual mode. + +!!! tip "Threshold Scale" + | Value | Meaning | + | :---: | :------ | + | `0.0` | ==Always automatic== — no human approval needed | + | `0.5` | Automatic when confidence ≥ 50% | + | `1.0` | ==Always manual== — always requires human approval | + +??? example "Built-in Profiles" + The following profiles are always available and cannot be removed: + + | Profile | Description | + | :------ | :---------- | + | `manual` | All thresholds at `1.0` — everything requires approval | + | `review` | Automatic strategize, manual execute and apply | + | `supervised` | Automatic strategize and execute, manual apply | + | `cautious` | Most operations automatic, manual for risky decisions | + | `trusted` | Nearly fully automatic, manual only for apply | + | `auto` | Fully automatic except strategy revisions | + | `ci` | Optimized for CI/CD pipelines | + | `full-auto` | All thresholds at `0.0` — fully autonomous | + + Custom profiles follow the same `/` naming convention as other entities. ##### agents automation-profile add @@ -4663,41 +15865,137 @@ Register a new custom automation profile from a YAML configuration file. The pro **Examples** -

-$ agents automation-profile add --config ./profiles/careful-auto.yaml
+=== "Rich"
 
-╭─ Profile Registered ─────────────────────────────────────────────╮
-│ Name: local/careful-auto                                         │
-│ Description: Autonomous execution with mandatory sandbox         │
-│              and manual apply                                    │
-│ Created: 2026-02-08 14:30                                        │
-╰──────────────────────────────────────────────────────────────────╯
+    

+    $ agents automation-profile add --config ./profiles/careful-auto.yaml
 
-╭─ Confidence Thresholds ────────────────╮
-│ auto_strategize: 0.0                   │
-│ auto_execute: 0.0                      │
-│ auto_apply: 1.0                        │
-│ auto_decisions_strategize: 0.0         │
-│ auto_decisions_execute: 0.0            │
-│ auto_validation_fix: 0.0               │
-│ auto_strategy_revision: 1.0            │
-│ auto_child_plans: 0.0                  │
-│ auto_retry_transient: 0.0              │
-│ auto_checkpoint_restore: 0.0           │
-│ require_sandbox: true                  │
-│ require_checkpoints: true              │
-│ allow_unsafe_tools: false              │
-╰────────────────────────────────────────╯
+    ╭─ Profile Registered ─────────────────────────────────────────────╮
+    │ Name: local/careful-auto                                         │
+    │ Description: Autonomous execution with mandatory sandbox         │
+    │              and manual apply                                    │
+    │ Created: 2026-02-08 14:30                                        │
+    ╰──────────────────────────────────────────────────────────────────╯
 
-✓ OK Profile registered
-

+    ╭─ Confidence Thresholds ────────────────╮
+    │ auto_strategize: 0.0                   │
+    │ auto_execute: 0.0                      │
+    │ auto_apply: 1.0                        │
+    │ auto_decisions_strategize: 0.0         │
+    │ auto_decisions_execute: 0.0            │
+    │ auto_validation_fix: 0.0               │
+    │ auto_strategy_revision: 1.0            │
+    │ auto_child_plans: 0.0                  │
+    │ auto_retry_transient: 0.0              │
+    │ auto_checkpoint_restore: 0.0           │
+    │ require_sandbox: true                  │
+    │ require_checkpoints: true              │
+    │ allow_unsafe_tools: false              │
+    ╰────────────────────────────────────────╯
+
+    ✓ OK Profile registered
+
+ +=== "Plain" + + ``` + $ 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 + + Confidence Thresholds + auto_strategize: 0.0 + auto_execute: 0.0 + auto_apply: 1.0 + auto_decisions_strategize: 0.0 + auto_decisions_execute: 0.0 + auto_validation_fix: 0.0 + auto_strategy_revision: 1.0 + auto_child_plans: 0.0 + auto_retry_transient: 0.0 + auto_checkpoint_restore: 0.0 + require_sandbox: true + require_checkpoints: true + allow_unsafe_tools: false + + [OK] Profile registered + ``` + +=== "JSON" + + ```json + { + "command": "automation-profile add", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/careful-auto", + "description": "Autonomous execution with mandatory sandbox and manual apply", + "created": "2026-02-08T14:30:00Z", + "thresholds": { + "auto_strategize": 0.0, + "auto_execute": 0.0, + "auto_apply": 1.0, + "auto_decisions_strategize": 0.0, + "auto_decisions_execute": 0.0, + "auto_validation_fix": 0.0, + "auto_strategy_revision": 1.0, + "auto_child_plans": 0.0, + "auto_retry_transient": 0.0, + "auto_checkpoint_restore": 0.0 + }, + "flags": { + "require_sandbox": true, + "require_checkpoints": true, + "allow_unsafe_tools": false + } + }, + "timing": { "started": "2026-02-08T14:30:00Z", "duration_ms": 70 }, + "messages": ["Profile registered"] + } + ``` + +=== "YAML" + + ```yaml + command: automation-profile add + status: ok + exit_code: 0 + data: + name: local/careful-auto + description: "Autonomous execution with mandatory sandbox and manual apply" + created: "2026-02-08T14:30:00Z" + thresholds: + auto_strategize: 0.0 + auto_execute: 0.0 + auto_apply: 1.0 + auto_decisions_strategize: 0.0 + auto_decisions_execute: 0.0 + auto_validation_fix: 0.0 + auto_strategy_revision: 1.0 + auto_child_plans: 0.0 + auto_retry_transient: 0.0 + auto_checkpoint_restore: 0.0 + flags: + require_sandbox: true + require_checkpoints: true + allow_unsafe_tools: false + timing: + started: "2026-02-08T14:30:00Z" + duration_ms: 70 + messages: + - "Profile registered" + ``` ##### agents automation-profile remove 
agents automation-profile remove [--yes|-y] <NAME>
-**Purpose** -Remove a custom automation profile. Built-in profiles cannot be removed. +!!! warning "Destructive Operation" + Remove a custom automation profile. ==Built-in profiles cannot be removed.== Plans and projects currently referencing this profile will fall back to their inherited or global default profile. **Arguments** @@ -4706,17 +16004,62 @@ Remove a custom automation profile. Built-in profiles cannot be removed. **Examples** -

-$ agents automation-profile remove local/careful-auto
+=== "Rich"
 
-Remove automation profile local/careful-auto? [y/N]: y
+    

+    $ agents automation-profile remove local/careful-auto
 
-╭─ Profile Removed ──────────╮
-│ Name: local/careful-auto   │
-╰────────────────────────────╯
+    Remove automation profile local/careful-auto? [y/N]: y
 
-✓ OK Profile removed
-

+    ╭─ Profile Removed ──────────╮
+    │ Name: local/careful-auto   │
+    ╰────────────────────────────╯
+
+    ✓ OK Profile removed
+
+ +=== "Plain" + + ``` + $ 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 + ``` + +=== "JSON" + + ```json + { + "command": "automation-profile remove", + "status": "ok", + "exit_code": 0, + "data": { + "name": "local/careful-auto" + }, + "timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 40 }, + "messages": ["Profile removed"] + } + ``` + +=== "YAML" + + ```yaml + command: automation-profile remove + status: ok + exit_code: 0 + data: + name: local/careful-auto + timing: + started: "2026-02-08T14:31:00Z" + duration_ms: 40 + messages: + - "Profile removed" + ``` ##### agents automation-profile list @@ -4731,31 +16074,149 @@ List all available automation profiles (built-in and custom). **Examples** -

-$ agents automation-profile list
+=== "Rich"
 
-╭─ Automation Profiles ──────────────────────────────────────────────────────────╮
-│ Name                Source    Auto-Apply  Sandbox  Description                 │
-│ ──────────────────  ────────  ──────────  ───────  ────────────────────────    │
-│ manual             built-in  1.0         yes      Human-driven (default)       │
-│ review             built-in  1.0         yes      Auto-phase, manual decisions │
-│ supervised         built-in  1.0         yes      Auto-plan, manual exec       │
-│ cautious           built-in  1.0         yes      Confidence-gated automation  │
-│ trusted            built-in  1.0         yes      Auto-exec, manual apply      │
-│ auto               built-in  1.0         yes      Full auto except apply       │
-│ ci                 built-in  0.0         yes      Full auto, safe CI/CD        │
-│ full-auto          built-in  0.0         no       Complete automation          │
-│ local/careful-auto custom    0.8         yes      Custom careful profile       │
-╰────────────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents automation-profile list
 
-╭─ Summary ───────────╮
-│ Built-in: 8         │
-│ Custom: 1           │
-│ Total: 9            │
-╰─────────────────────╯
+    ╭─ Automation Profiles ──────────────────────────────────────────────────────────╮
+    │ Name                Source    Auto-Apply  Sandbox  Description                 │
+    │ ──────────────────  ────────  ──────────  ───────  ────────────────────────    │
+    │ manual             built-in  1.0         yes      Human-driven (default)       │
+    │ review             built-in  1.0         yes      Auto-phase, manual decisions │
+    │ supervised         built-in  1.0         yes      Auto-plan, manual exec       │
+    │ cautious           built-in  1.0         yes      Confidence-gated automation  │
+    │ trusted            built-in  1.0         yes      Auto-exec, manual apply      │
+    │ auto               built-in  1.0         yes      Full auto except apply       │
+    │ ci                 built-in  0.0         yes      Full auto, safe CI/CD        │
+    │ full-auto          built-in  0.0         no       Complete automation          │
+    │ local/careful-auto custom    0.8         yes      Custom careful profile       │
+    ╰────────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 9 profiles listed
-

+    ╭─ Summary ───────────╮
+    │ Built-in: 8         │
+    │ Custom: 1           │
+    │ Total: 9            │
+    ╰─────────────────────╯
+
+    ✓ OK 9 profiles listed
+
+ +=== "Plain" + + ``` + $ agents automation-profile list + + Automation Profiles + Name Source Auto-Apply Sandbox Description + ------------------ -------- ---------- ------- ---------------------------- + manual built-in 1.0 yes Human-driven (default) + review built-in 1.0 yes Auto-phase, manual decisions + supervised built-in 1.0 yes Auto-plan, manual exec + cautious built-in 1.0 yes Confidence-gated automation + trusted built-in 1.0 yes Auto-exec, manual apply + auto built-in 1.0 yes Full auto except apply + ci built-in 0.0 yes Full auto, safe CI/CD + full-auto built-in 0.0 no Complete automation + local/careful-auto custom 0.8 yes Custom careful profile + + Summary + Built-in: 8 + Custom: 1 + Total: 9 + + [OK] 9 profiles listed + ``` + +=== "JSON" + + ```json + { + "command": "automation-profile list", + "status": "ok", + "exit_code": 0, + "data": { + "profiles": [ + { "name": "manual", "source": "built-in", "auto_apply": 1.0, "sandbox": true, "description": "Human-driven (default)" }, + { "name": "review", "source": "built-in", "auto_apply": 1.0, "sandbox": true, "description": "Auto-phase, manual decisions" }, + { "name": "supervised", "source": "built-in", "auto_apply": 1.0, "sandbox": true, "description": "Auto-plan, manual exec" }, + { "name": "cautious", "source": "built-in", "auto_apply": 1.0, "sandbox": true, "description": "Confidence-gated automation" }, + { "name": "trusted", "source": "built-in", "auto_apply": 1.0, "sandbox": true, "description": "Auto-exec, manual apply" }, + { "name": "auto", "source": "built-in", "auto_apply": 1.0, "sandbox": true, "description": "Full auto except apply" }, + { "name": "ci", "source": "built-in", "auto_apply": 0.0, "sandbox": true, "description": "Full auto, safe CI/CD" }, + { "name": "full-auto", "source": "built-in", "auto_apply": 0.0, "sandbox": false, "description": "Complete automation" }, + { "name": "local/careful-auto", "source": "custom", "auto_apply": 0.8, "sandbox": true, "description": "Custom careful profile" } + ], + "summary": { "built_in": 8, "custom": 1, "total": 9 } + }, + "timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 50 }, + "messages": ["9 profiles listed"] + } + ``` + +=== "YAML" + + ```yaml + command: automation-profile list + status: ok + exit_code: 0 + data: + profiles: + - name: manual + source: built-in + auto_apply: 1.0 + sandbox: true + description: "Human-driven (default)" + - name: review + source: built-in + auto_apply: 1.0 + sandbox: true + description: "Auto-phase, manual decisions" + - name: supervised + source: built-in + auto_apply: 1.0 + sandbox: true + description: "Auto-plan, manual exec" + - name: cautious + source: built-in + auto_apply: 1.0 + sandbox: true + description: "Confidence-gated automation" + - name: trusted + source: built-in + auto_apply: 1.0 + sandbox: true + description: "Auto-exec, manual apply" + - name: auto + source: built-in + auto_apply: 1.0 + sandbox: true + description: "Full auto except apply" + - name: ci + source: built-in + auto_apply: 0.0 + sandbox: true + description: "Full auto, safe CI/CD" + - name: full-auto + source: built-in + auto_apply: 0.0 + sandbox: false + description: "Complete automation" + - name: local/careful-auto + source: custom + auto_apply: 0.8 + sandbox: true + description: "Custom careful profile" + summary: + built_in: 8 + custom: 1 + total: 9 + timing: + started: "2026-02-08T14:31:00Z" + duration_ms: 50 + messages: + - "9 profiles listed" + ``` ##### agents automation-profile show @@ -4770,47 +16231,162 @@ Show full details for an automation profile, including all flag values. **Examples** -

-$ agents automation-profile show trusted
+=== "Rich"
 
-╭─ Automation Profile ───────────────────────────────────────────╮
-│ Name: trusted                                                  │
-│ Source: built-in                                               │
-│ Description: Auto-exec, manual apply. Day-to-day development   │
-╰────────────────────────────────────────────────────────────────╯
+    

+    $ agents automation-profile show trusted
 
-╭─ Phase Transitions (thresholds) ─────╮
-│ auto_strategize: 0.0                 │
-│ auto_execute: 0.0                    │
-│ auto_apply: 1.0                      │
-╰──────────────────────────────────────╯
+    ╭─ Automation Profile ───────────────────────────────────────────╮
+    │ Name: trusted                                                  │
+    │ Source: built-in                                               │
+    │ Description: Auto-exec, manual apply. Day-to-day development   │
+    ╰────────────────────────────────────────────────────────────────╯
 
-╭─ Decision Automation (thresholds) ───╮
-│ auto_decisions_strategize: 0.0       │
-│ auto_decisions_execute: 0.0          │
-╰──────────────────────────────────────╯
+    ╭─ Phase Transitions (thresholds) ─────╮
+    │ auto_strategize: 0.0                 │
+    │ auto_execute: 0.0                    │
+    │ auto_apply: 1.0                      │
+    ╰──────────────────────────────────────╯
 
-╭─ Self-Repair (thresholds) ───────────╮
-│ auto_validation_fix: 0.0             │
-│ auto_strategy_revision: 1.0          │
-│ auto_retry_transient: 0.0            │
-│ auto_checkpoint_restore: 1.0         │
-╰──────────────────────────────────────╯
+    ╭─ Decision Automation (thresholds) ───╮
+    │ auto_decisions_strategize: 0.0       │
+    │ auto_decisions_execute: 0.0          │
+    ╰──────────────────────────────────────╯
 
-╭─ Execution Controls (thresholds) ────╮
-│ auto_child_plans: 0.0                │
-│ require_sandbox: true                │
-│ require_checkpoints: true            │
-│ allow_unsafe_tools: false            │
-╰──────────────────────────────────────╯
+    ╭─ Self-Repair (thresholds) ───────────╮
+    │ auto_validation_fix: 0.0             │
+    │ auto_strategy_revision: 1.0          │
+    │ auto_retry_transient: 0.0            │
+    │ auto_checkpoint_restore: 1.0         │
+    ╰──────────────────────────────────────╯
 
-✓ OK Profile loaded
-

+    ╭─ Execution Controls (thresholds) ────╮
+    │ auto_child_plans: 0.0                │
+    │ require_sandbox: true                │
+    │ require_checkpoints: true            │
+    │ allow_unsafe_tools: false            │
+    ╰──────────────────────────────────────╯
+
+    ✓ OK Profile loaded
+
+ +=== "Plain" + + ``` + $ agents automation-profile show trusted + + Automation Profile + Name: trusted + Source: built-in + Description: Auto-exec, manual apply. Day-to-day development + + Phase Transitions (thresholds) + auto_strategize: 0.0 + auto_execute: 0.0 + auto_apply: 1.0 + + Decision Automation (thresholds) + auto_decisions_strategize: 0.0 + auto_decisions_execute: 0.0 + + Self-Repair (thresholds) + auto_validation_fix: 0.0 + auto_strategy_revision: 1.0 + auto_retry_transient: 0.0 + auto_checkpoint_restore: 1.0 + + Execution Controls (thresholds) + auto_child_plans: 0.0 + require_sandbox: true + require_checkpoints: true + allow_unsafe_tools: false + + [OK] Profile loaded + ``` + +=== "JSON" + + ```json + { + "command": "automation-profile show", + "status": "ok", + "exit_code": 0, + "data": { + "name": "trusted", + "source": "built-in", + "description": "Auto-exec, manual apply. Day-to-day development", + "phase_transitions": { + "auto_strategize": 0.0, + "auto_execute": 0.0, + "auto_apply": 1.0 + }, + "decision_automation": { + "auto_decisions_strategize": 0.0, + "auto_decisions_execute": 0.0 + }, + "self_repair": { + "auto_validation_fix": 0.0, + "auto_strategy_revision": 1.0, + "auto_retry_transient": 0.0, + "auto_checkpoint_restore": 1.0 + }, + "execution_controls": { + "auto_child_plans": 0.0, + "require_sandbox": true, + "require_checkpoints": true, + "allow_unsafe_tools": false + } + }, + "timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 55 }, + "messages": ["Profile loaded"] + } + ``` + +=== "YAML" + + ```yaml + command: automation-profile show + status: ok + exit_code: 0 + data: + name: trusted + source: built-in + description: "Auto-exec, manual apply. Day-to-day development" + phase_transitions: + auto_strategize: 0.0 + auto_execute: 0.0 + auto_apply: 1.0 + decision_automation: + auto_decisions_strategize: 0.0 + auto_decisions_execute: 0.0 + self_repair: + auto_validation_fix: 0.0 + auto_strategy_revision: 1.0 + auto_retry_transient: 0.0 + auto_checkpoint_restore: 1.0 + execution_controls: + auto_child_plans: 0.0 + require_sandbox: true + require_checkpoints: true + allow_unsafe_tools: false + timing: + started: "2026-02-08T14:31:00Z" + duration_ms: 55 + messages: + - "Profile loaded" + ``` #### agents config -**Purpose** -Manage global configuration values. +!!! info "Purpose" + Manage ==global configuration values== that control system-wide defaults. Configuration keys use hierarchical dot-path notation (e.g., `core.automation-profile`, `core.log.level`). + +??? tip "Key Configuration Categories" + | Category | Example Keys | Description | + | :------- | :----------- | :---------- | + | **Core** | `core.automation-profile`, `core.format`, `core.log.level` | System-wide defaults | + | **Actor** | `actor.default.invariant` | Default actor assignments | + | **Output** | `core.format` | Default rendering format (`rich`, `json`, `yaml`, etc.) | ##### agents config set @@ -4830,60 +16406,241 @@ The `core.format` key sets the default output rendering format used by all comma **Examples** -

-$ agents config set core.automation-profile trusted
+=== "Rich"
 
-╭─ Config Updated ──────────────────────╮
-│ Key: core.automation-profile          │
-│ Value: trusted                        │
-│ Previous: manual                      │
-│ Source: config                        │
-│ Scope: global                         │
-╰───────────────────────────────────────╯
+    

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

+    ╭─ Saved To ──────────────────────────╮
+    │ File: ~/.cleveragents/config.toml   │
+    │ Line: 8                             │
+    ╰─────────────────────────────────────╯
+
+    ✓ OK Config updated
+
+ +=== "Plain" + + ``` + $ agents config set core.automation-profile trusted + + Config Updated + Key: core.automation-profile + Value: trusted + Previous: manual + Source: config + Scope: global + + Effective + Sessions: new sessions + Plans: future plans (unless set) + Existing: unchanged + + Saved To + File: ~/.cleveragents/config.toml + Line: 8 + + [OK] Config updated + ``` + +=== "JSON" + + ```json + { + "command": "config set", + "status": "ok", + "exit_code": 0, + "data": { + "key": "core.automation-profile", + "value": "trusted", + "previous": "manual", + "source": "config", + "scope": "global", + "effective": { + "sessions": "new sessions", + "plans": "future plans (unless set)", + "existing": "unchanged" + }, + "saved_to": { "file": "~/.cleveragents/config.toml", "line": 8 } + }, + "timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 30 }, + "messages": ["Config updated"] + } + ``` + +=== "YAML" + + ```yaml + command: config set + status: ok + exit_code: 0 + data: + key: core.automation-profile + value: trusted + previous: manual + source: config + scope: global + effective: + sessions: new sessions + plans: "future plans (unless set)" + existing: unchanged + saved_to: + file: "~/.cleveragents/config.toml" + line: 8 + timing: + started: "2026-02-08T14:32:00Z" + duration_ms: 30 + messages: + - "Config updated" + ``` Setting the default output format: -

-$ agents config set core.format table
+=== "Rich"
 
-╭─ Config Updated ─────────────────╮
-│ Key: core.format                 │
-│ Previous: rich                   │
-│ New Value: table                 │
-│ Scope: user (~/.cleveragents)    │
-╰──────────────────────────────────╯
+    

+    $ agents config set core.format table
 
-✓ OK Set core.format = table
-

+    ╭─ Config Updated ─────────────────╮
+    │ Key: core.format                 │
+    │ Previous: rich                   │
+    │ New Value: table                 │
+    │ Scope: user (~/.cleveragents)    │
+    ╰──────────────────────────────────╯
+
+    ✓ OK Set core.format = table
+
+ +=== "Plain" + + ``` + $ agents config set core.format table + + Config Updated + Key: core.format + Previous: rich + New Value: table + Scope: user (~/.cleveragents) + + [OK] Set core.format = table + ``` + +=== "JSON" + + ```json + { + "command": "config set", + "status": "ok", + "exit_code": 0, + "data": { + "key": "core.format", + "previous": "rich", + "value": "table", + "scope": "user (~/.cleveragents)" + }, + "timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 25 }, + "messages": ["Set core.format = table"] + } + ``` + +=== "YAML" + + ```yaml + command: config set + status: ok + exit_code: 0 + data: + key: core.format + previous: rich + value: table + scope: "user (~/.cleveragents)" + timing: + started: "2026-02-08T14:32:00Z" + duration_ms: 25 + messages: + - "Set core.format = table" + ``` Setting a global invariant actor: -

-$ agents config set actor.default.invariant local/invariant-resolver
+=== "Rich"
 
-╭─ Config Updated ──────────────────────────────────╮
-│ Key: actor.default.invariant                      │
-│ Previous: (not set)                               │
-│ New Value: local/invariant-resolver               │
-│ Scope: user (~/.cleveragents)                     │
-╰───────────────────────────────────────────────────╯
+    

+    $ agents config set actor.default.invariant local/invariant-resolver
 
-✓ OK Set actor.default.invariant = local/invariant-resolver
-

+    ╭─ Config Updated ──────────────────────────────────╮
+    │ Key: actor.default.invariant                      │
+    │ Previous: (not set)                               │
+    │ New Value: local/invariant-resolver               │
+    │ Scope: user (~/.cleveragents)                     │
+    ╰───────────────────────────────────────────────────╯
+
+    ✓ OK Set actor.default.invariant = local/invariant-resolver
+
+ +=== "Plain" + + ``` + $ agents config set actor.default.invariant local/invariant-resolver + + Config Updated + Key: actor.default.invariant + Previous: (not set) + New Value: local/invariant-resolver + Scope: user (~/.cleveragents) + + [OK] Set actor.default.invariant = local/invariant-resolver + ``` + +=== "JSON" + + ```json + { + "command": "config set", + "status": "ok", + "exit_code": 0, + "data": { + "key": "actor.default.invariant", + "previous": null, + "value": "local/invariant-resolver", + "scope": "user (~/.cleveragents)" + }, + "timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 28 }, + "messages": ["Set actor.default.invariant = local/invariant-resolver"] + } + ``` + +=== "YAML" + + ```yaml + command: config set + status: ok + exit_code: 0 + data: + key: actor.default.invariant + previous: null + value: local/invariant-resolver + scope: "user (~/.cleveragents)" + timing: + started: "2026-02-08T14:32:00Z" + duration_ms: 28 + messages: + - "Set actor.default.invariant = local/invariant-resolver" + ``` ##### agents config get @@ -4898,33 +16655,132 @@ Get a configuration value. **Examples** -

-$ agents config get core.automation-profile
+=== "Rich"
 
-╭─ Config ──────────────────────────╮
-│ Key: core.automation-profile      │
-│ Value: trusted                    │
-│ Source: config                    │
-│ Overridden: no                    │
-│ Type: string                      │
-╰───────────────────────────────────╯
+    

+    $ agents config get core.automation-profile
 
-╭─ Origin ──────────────────────────╮
-│ File: ~/.cleveragents/config.toml │
-│ Line: 8                           │
-│ Default: supervised               │
-╰───────────────────────────────────╯
+    ╭─ Config ──────────────────────────╮
+    │ Key: core.automation-profile      │
+    │ Value: trusted                    │
+    │ Source: config                    │
+    │ Overridden: no                    │
+    │ Type: string                      │
+    ╰───────────────────────────────────╯
 
-╭─ Resolution Chain ──────────────╮
-│ 1. CLI flag: (not set)          │
-│ 2. Env var: (not set)           │
-│ 3. Config file: trusted         │
-│ 4. Default: supervised          │
-│ Winner: config file (level 3)   │
-╰─────────────────────────────────╯
+    ╭─ Origin ──────────────────────────╮
+    │ File: ~/.cleveragents/config.toml │
+    │ Line: 8                           │
+    │ Default: supervised               │
+    ╰───────────────────────────────────╯
 
-✓ OK Config read
-

+    ╭─ Resolution Chain ──────────────╮
+    │ 1. CLI flag: (not set)          │
+    │ 2. Env var: (not set)           │
+    │ 3. Config file: trusted         │
+    │ 4. Default: supervised          │
+    │ Winner: config file (level 3)   │
+    ╰─────────────────────────────────╯
+
+    ✓ OK Config read
+
+ +=== "Plain" + + ``` + $ agents config get core.automation-profile + + Config + Key: core.automation-profile + Value: trusted + Source: config + Overridden: no + Type: string + + Origin + File: ~/.cleveragents/config.toml + Line: 8 + Default: supervised + + Resolution Chain + 1. CLI flag: (not set) + 2. Env var: (not set) + 3. Config file: trusted + 4. Default: supervised + Winner: config file (level 3) + + [OK] Config read + ``` + +=== "JSON" + + ```json + { + "command": "config get", + "status": "ok", + "exit_code": 0, + "data": { + "key": "core.automation-profile", + "value": "trusted", + "source": "config", + "overridden": false, + "type": "string", + "origin": { + "file": "~/.cleveragents/config.toml", + "line": 8, + "default": "supervised" + }, + "resolution_chain": [ + { "level": 1, "source": "CLI flag", "value": null }, + { "level": 2, "source": "Env var", "value": null }, + { "level": 3, "source": "Config file", "value": "trusted" }, + { "level": 4, "source": "Default", "value": "supervised" } + ], + "winner": { "source": "config file", "level": 3 } + }, + "timing": { "started": "2026-02-08T14:33:00Z", "duration_ms": 20 }, + "messages": ["Config read"] + } + ``` + +=== "YAML" + + ```yaml + command: config get + status: ok + exit_code: 0 + data: + key: core.automation-profile + value: trusted + source: config + overridden: false + type: string + origin: + file: "~/.cleveragents/config.toml" + line: 8 + default: supervised + resolution_chain: + - level: 1 + source: "CLI flag" + value: null + - level: 2 + source: "Env var" + value: null + - level: 3 + source: "Config file" + value: trusted + - level: 4 + source: Default + value: supervised + winner: + source: "config file" + level: 3 + timing: + started: "2026-02-08T14:33:00Z" + duration_ms: 20 + messages: + - "Config read" + ``` ##### agents config list @@ -4939,35 +16795,132 @@ None. **Examples** -

-$ agents config list
+=== "Rich"
 
-╭─ Config ───────────────────────────────────────────────────╮
-│ Key               Value               Source   Modified    │
-│ ────────────────  ──────────────────  ───────  ────────    │
-│ core.automation-profile  trusted             config   yes  │
-│ actor.default.invariant local/reconciler    config   yes   │
-│ core.log.level          FATAL               default  no    │
-╰────────────────────────────────────────────────────────────╯
+    

+    $ agents config list
 
-╭─ Overrides ─────╮
-│ Env: none       │
-│ CLI Flags: none │
-╰─────────────────╯
+    ╭─ Config ───────────────────────────────────────────────────╮
+    │ Key               Value               Source   Modified    │
+    │ ────────────────  ──────────────────  ───────  ────────    │
+    │ core.automation-profile  trusted             config   yes  │
+    │ actor.default.invariant local/reconciler    config   yes   │
+    │ core.log.level          FATAL               default  no    │
+    ╰────────────────────────────────────────────────────────────╯
 
-╭─ Config File ───────────────────────╮
-│ Path: ~/.cleveragents/config.toml   │
-│ Size: 284 bytes                     │
-│ Valid: yes                          │
-╰─────────────────────────────────────╯
+    ╭─ Overrides ─────╮
+    │ Env: none       │
+    │ CLI Flags: none │
+    ╰─────────────────╯
 
-✓ OK 6 settings listed
-

+    ╭─ Config File ───────────────────────╮
+    │ Path: ~/.cleveragents/config.toml   │
+    │ Size: 284 bytes                     │
+    │ Valid: yes                          │
+    ╰─────────────────────────────────────╯
+
+    ✓ OK 6 settings listed
+
+ +=== "Plain" + + ``` + $ agents config list + + Config + Key Value Source Modified + ----------------------- ------------------ ------- -------- + core.automation-profile trusted config yes + actor.default.invariant local/reconciler config yes + core.log.level FATAL default no + + Overrides + Env: none + CLI Flags: none + + Config File + Path: ~/.cleveragents/config.toml + Size: 284 bytes + Valid: yes + + [OK] 6 settings listed + ``` + +=== "JSON" + + ```json + { + "command": "config list", + "status": "ok", + "exit_code": 0, + "data": { + "settings": [ + { "key": "core.automation-profile", "value": "trusted", "source": "config", "modified": true }, + { "key": "actor.default.invariant", "value": "local/reconciler", "source": "config", "modified": true }, + { "key": "core.log.level", "value": "FATAL", "source": "default", "modified": false } + ], + "overrides": { "env": null, "cli_flags": null }, + "config_file": { + "path": "~/.cleveragents/config.toml", + "size_bytes": 284, + "valid": true + } + }, + "timing": { "started": "2026-02-08T14:33:00Z", "duration_ms": 25 }, + "messages": ["6 settings listed"] + } + ``` + +=== "YAML" + + ```yaml + command: config list + status: ok + exit_code: 0 + data: + settings: + - key: core.automation-profile + value: trusted + source: config + modified: true + - key: actor.default.invariant + value: local/reconciler + source: config + modified: true + - key: core.log.level + value: FATAL + source: default + modified: false + overrides: + env: null + cli_flags: null + config_file: + path: "~/.cleveragents/config.toml" + size_bytes: 284 + valid: true + timing: + started: "2026-02-08T14:33:00Z" + duration_ms: 25 + messages: + - "6 settings listed" + ``` #### agents invariant -**Purpose** -Manage invariants — named constraints that guide and constrain plan execution. Invariants can be attached to any scope: global (all plans), project (all plans targeting that project), plan (a specific plan and its child plans), or action (carried forward when the action is used). Exactly one scope flag is required for `add` and `list`. +!!! info "Purpose" + Manage ==invariants== — named constraints that guide and constrain plan execution. Invariants can be attached to any scope: global (all plans), project (all plans targeting that project), plan (a specific plan and its child plans), or action (carried forward when the action is used). + +!!! warning "Scope Requirements" + Exactly ==one scope flag== is required for `add` and `list`. The available scopes are: + + | Scope | Flag | Applies To | + | :---- | :--- | :--------- | + | **Global** | `--global` | All plans across all projects | + | **Project** | `--project ` | All plans targeting that project | + | **Plan** | `--plan ` | A specific plan and its child plans | + | **Action** | `--action ` | Carried forward when the action is used | + + When multiple scopes apply to a plan, the ==union== of all applicable invariants is enforced. ##### agents invariant add @@ -4989,50 +16942,161 @@ At least one scope flag (`--global`, `--project`, `--plan`, or `--action`) must **Examples** -

-$ agents invariant add --global "All public APIs must maintain backward compatibility"
+=== "Rich"
 
-╭─ Invariant Added ──────────────────────────────────────────────────────╮
-│ Invariant: All public APIs must maintain backward compatibility        │
-│ Scope: global                                                          │
-│ ID: inv_01HXM9A1B                                                      │
-╰────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents invariant add --global "All public APIs must maintain backward compatibility"
 
-✓ OK Invariant added
+    ╭─ Invariant Added ──────────────────────────────────────────────────────╮
+    │ Invariant: All public APIs must maintain backward compatibility        │
+    │ Scope: global                                                          │
+    │ ID: inv_01HXM9A1B                                                      │
+    ╰────────────────────────────────────────────────────────────────────────╯
 
-$ agents invariant add --project local/api-service "All endpoints must validate auth tokens"
+    ✓ OK Invariant added
 
-╭─ Invariant Added ──────────────────────────────────────────────╮
-│ Project: local/api-service                                     │
-│ Invariant: All endpoints must validate auth tokens             │
-│ Scope: project                                                 │
-│ ID: inv_01HXM9A2C                                              │
-╰────────────────────────────────────────────────────────────────╯
+    $ agents invariant add --project local/api-service "All endpoints must validate auth tokens"
 
-✓ OK Invariant added
+    ╭─ Invariant Added ──────────────────────────────────────────────╮
+    │ Project: local/api-service                                     │
+    │ Invariant: All endpoints must validate auth tokens             │
+    │ Scope: project                                                 │
+    │ ID: inv_01HXM9A2C                                              │
+    ╰────────────────────────────────────────────────────────────────╯
 
-$ agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
+    ✓ OK Invariant added
 
-╭─ Invariant Added ─────────────────────────────────────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J                                      │
-│ Invariant: All database queries must use parameterized statements     │
-│ Scope: plan                                                           │
-│ ID: inv_01HXM9G3A                                                     │
-╰───────────────────────────────────────────────────────────────────────╯
+    $ agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
 
-✓ OK Invariant added
+    ╭─ Invariant Added ─────────────────────────────────────────────────────╮
+    │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J                                      │
+    │ Invariant: All database queries must use parameterized statements     │
+    │ Scope: plan                                                           │
+    │ ID: inv_01HXM9G3A                                                     │
+    ╰───────────────────────────────────────────────────────────────────────╯
 
-$ agents invariant add --action local/code-coverage "Test files must not import production secrets"
+    ✓ OK Invariant added
 
-╭─ Invariant Added ──────────────────────────────────────────────────────╮
-│ Action: local/code-coverage                                            │
-│ Invariant: Test files must not import production secrets               │
-│ Scope: action                                                          │
-│ ID: inv_01HXM9H4B                                                      │
-╰────────────────────────────────────────────────────────────────────────╯
+    $ agents invariant add --action local/code-coverage "Test files must not import production secrets"
 
-✓ OK Invariant added
-

+    ╭─ Invariant Added ──────────────────────────────────────────────────────╮
+    │ Action: local/code-coverage                                            │
+    │ Invariant: Test files must not import production secrets               │
+    │ Scope: action                                                          │
+    │ ID: inv_01HXM9H4B                                                      │
+    ╰────────────────────────────────────────────────────────────────────────╯
+
+    ✓ OK Invariant added
+
+ +=== "Plain" + + ``` + $ 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 + + [OK] Invariant added + + $ 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 + + [OK] Invariant added + + $ 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 + + [OK] Invariant added + + $ 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 + + [OK] Invariant added + ``` + +=== "JSON" + + ```json + { + "command": "invariant add", + "status": "ok", + "exit_code": 0, + "data": [ + { + "invariant": "All public APIs must maintain backward compatibility", + "scope": "global", + "id": "inv_01HXM9A1B" + }, + { + "project": "local/api-service", + "invariant": "All endpoints must validate auth tokens", + "scope": "project", + "id": "inv_01HXM9A2C" + }, + { + "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "invariant": "All database queries must use parameterized statements", + "scope": "plan", + "id": "inv_01HXM9G3A" + }, + { + "action": "local/code-coverage", + "invariant": "Test files must not import production secrets", + "scope": "action", + "id": "inv_01HXM9H4B" + } + ], + "timing": { "started": "2026-02-08T14:35:00Z", "duration_ms": 45 }, + "messages": ["Invariant added"] + } + ``` + +=== "YAML" + + ```yaml + command: invariant add + status: ok + exit_code: 0 + data: + - invariant: "All public APIs must maintain backward compatibility" + scope: global + id: inv_01HXM9A1B + - project: local/api-service + invariant: "All endpoints must validate auth tokens" + scope: project + id: inv_01HXM9A2C + - plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + invariant: "All database queries must use parameterized statements" + scope: plan + id: inv_01HXM9G3A + - action: local/code-coverage + invariant: "Test files must not import production secrets" + scope: action + id: inv_01HXM9H4B + timing: + started: "2026-02-08T14:35:00Z" + duration_ms: 45 + messages: + - "Invariant added" + ``` ##### agents invariant list @@ -5052,41 +17116,134 @@ List invariants at a given scope. Use `--effective` with `--plan` to show the fi **Examples** -

-$ agents invariant list --global
+=== "Rich"
 
-╭─ Global Invariants ──────────────────────────────────────────────────────╮
-│ ID              Text                                                     │
-│ ──────────────  ────────────────────────────────────────────────────     │
-│ inv_01HXM9A1B  All public APIs must maintain backward compatibility      │
-│ inv_01HXM9A1C  Payment processing must be idempotent                     │
-╰──────────────────────────────────────────────────────────────────────────╯
+    

+    $ agents invariant list --global
 
-✓ OK 2 invariants
+    ╭─ Global Invariants ──────────────────────────────────────────────────────╮
+    │ ID              Text                                                     │
+    │ ──────────────  ────────────────────────────────────────────────────     │
+    │ inv_01HXM9A1B  All public APIs must maintain backward compatibility      │
+    │ inv_01HXM9A1C  Payment processing must be idempotent                     │
+    ╰──────────────────────────────────────────────────────────────────────────╯
 
-$ agents invariant list --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J --effective
+    ✓ OK 2 invariants
 
-╭─ 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            │
-╰───────────────────────────────────────────────────────────────────────────────────────────╯
+    $ agents invariant list --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J --effective
 
-│ Conflicts Resolved: 1                                                              │
-│   Global "Use shared DB pool" overridden by 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            │
+    ╰───────────────────────────────────────────────────────────────────────────────────────────╯
 
-✓ OK 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
-

+    │ 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)
+
+ +=== "Plain" + + ``` + $ agents invariant list --global + + Global Invariants + ID Text + -------------- -------------------------------------------------------- + inv_01HXM9A1B All public APIs must maintain backward compatibility + inv_01HXM9A1C Payment processing must be idempotent + + [OK] 2 invariants + + $ 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 + + 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) + ``` + +=== "JSON" + + ```json + { + "command": "invariant list", + "status": "ok", + "exit_code": 0, + "data": { + "scope": "plan", + "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", + "effective": true, + "invariants": [ + { "id": "inv_01HXM9A1B", "source": "global", "text": "All public APIs must maintain backward compatibility" }, + { "id": "inv_01HXM9A2C", "source": "project", "text": "All endpoints must validate auth tokens" }, + { "id": "inv_01HXM9G3A", "source": "plan", "text": "All database queries must use parameterized statements" } + ], + "conflicts_resolved": [ + { + "overridden": { "source": "global", "text": "Use shared DB pool" }, + "by": { "source": "plan", "text": "All database queries must use parameterized statements" } + } + ] + }, + "timing": { "started": "2026-02-08T14:35:00Z", "duration_ms": 35 }, + "messages": ["3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)"] + } + ``` + +=== "YAML" + + ```yaml + command: invariant list + status: ok + exit_code: 0 + data: + scope: plan + plan_id: 01HXM8C2ZK4Q7C2B3F2R4VYV6J + effective: true + invariants: + - id: inv_01HXM9A1B + source: global + text: "All public APIs must maintain backward compatibility" + - id: inv_01HXM9A2C + source: project + text: "All endpoints must validate auth tokens" + - id: inv_01HXM9G3A + source: plan + text: "All database queries must use parameterized statements" + conflicts_resolved: + - overridden: + source: global + text: "Use shared DB pool" + by: + source: plan + text: "All database queries must use parameterized statements" + timing: + started: "2026-02-08T14:35:00Z" + duration_ms: 35 + messages: + - "3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)" + ``` ##### agents invariant remove 
agents invariant remove [--yes|-y] <INVARIANT_ID>
-**Purpose** -Remove an invariant by ID. The invariant is removed from whichever scope it was originally attached to. +!!! warning "Constraint Removal" + Remove an invariant by ID. The invariant is removed from whichever scope it was originally attached to. ==Active plans== that have already incorporated this invariant into their decision trees are not retroactively affected, but future plans will no longer enforce this constraint. **Arguments** @@ -5095,19 +17252,70 @@ Remove an invariant by ID. The invariant is removed from whichever scope it was **Examples** -

-$ agents invariant remove inv_01HXM9A1C
+=== "Rich"
 
-Remove invariant inv_01HXM9A1C ("Payment processing must be idempotent", scope: global)? [y/N]: y
+    

+    $ agents invariant remove inv_01HXM9A1C
 
-╭─ Invariant Removed ──────────────────────────────────────────────╮
-│ Removed: Payment processing must be idempotent                   │
-│ Scope: global                                                    │
-│ ID: inv_01HXM9A1C                                                │
-╰──────────────────────────────────────────────────────────────────╯
+    Remove invariant inv_01HXM9A1C ("Payment processing must be idempotent", scope: global)? [y/N]: y
 
-✓ OK Invariant removed
-

+    ╭─ Invariant Removed ──────────────────────────────────────────────╮
+    │ Removed: Payment processing must be idempotent                   │
+    │ Scope: global                                                    │
+    │ ID: inv_01HXM9A1C                                                │
+    ╰──────────────────────────────────────────────────────────────────╯
+
+    ✓ OK Invariant removed
+
+ +=== "Plain" + + ``` + $ 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 + + [OK] Invariant removed + ``` + +=== "JSON" + + ```json + { + "command": "invariant remove", + "status": "ok", + "exit_code": 0, + "data": { + "removed": "Payment processing must be idempotent", + "scope": "global", + "id": "inv_01HXM9A1C" + }, + "timing": { "started": "2026-02-08T14:36:00Z", "duration_ms": 30 }, + "messages": ["Invariant removed"] + } + ``` + +=== "YAML" + + ```yaml + command: invariant remove + status: ok + exit_code: 0 + data: + removed: "Payment processing must be idempotent" + scope: global + id: inv_01HXM9A1C + timing: + started: "2026-02-08T14:36:00Z" + duration_ms: 30 + messages: + - "Invariant removed" + ``` ## Core Concepts @@ -5144,10 +17352,9 @@ The normal phase progression is forward, but both Execute and Apply may revert t | Strategize | `execute` | Execute | | Execute | `apply` | Apply | -**Important behavioral rules:** - -* 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. -* **There is no `strategize` command.** The phase transition verbs are used in CLI commands — not the phase names. The `use` verb (as in `agents plan use`) is the command that transitions a plan from the Action phase into Strategize. This is by design: "use" describes the user's intent (using an action template on a project), and the system responds by entering the Strategize phase. +!!! note "Important behavioral rules" + * 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. + * **There is no `strategize` command.** The phase transition verbs are used in CLI commands — not the phase names. The `use` verb (as in `agents plan use`) is the command that transitions a plan from the Action phase into Strategize. This is by design: ==`use` describes the user's intent== (using an action template on a project), and the system responds by entering the Strategize phase. #### Phase Reversion (→ Strategize) @@ -5172,42 +17379,50 @@ While the normal phase progression is forward (Action → Strategize → Execute #### Plan States (Per Phase) -A plan's phase indicates "what step of the lifecycle it is in." Separately, the plan has a **processing state** indicating "what is happening right now." +A plan's ==phase== indicates "what step of the lifecycle it is in." Separately, the plan has a ==processing state== indicating "what is happening right now." -Recommended state model: +=== "Action Phase" -* **Action phase states** + | State | Description | + | :---- | :---------- | + | `available` | Action exists and can be used | + | `archived` | Soft-deleted or hidden (optional) | - * `available` (action exists and can be used) - * `archived` (soft-deleted or hidden, optional) +=== "Strategize / Execute Phases" -* **Strategize / Execute phase states** + | State | Terminal? | Description | + | :---- | :-------: | :---------- | + | `queued` | No | Waiting for compute/worker | + | `processing` | No | Currently running | + | `errored` | Yes | Failed; includes error metadata | + | `complete` | Yes | Finished successfully | + | `cancelled` | Yes | User/system cancelled; safe terminal | - * `queued` (waiting for compute/worker) - * `processing` (currently running) - * `errored` (failed; includes error metadata) - * `complete` (finished successfully) - * `cancelled` (user/system cancelled; safe terminal for that phase) +=== "Apply Phase" -* **Apply phase states** - - * `queued` (waiting for compute/worker) - * `processing` (currently running — diff review, conflict resolution, validation) - * `errored` (failed; includes error metadata) - * `applied` (terminal — changes successfully committed to real resources) - * `constrained` (terminal — cannot complete within the current strategy's constraints; may trigger automatic or manual reversion to Strategize, controlled by the `auto_reversion_from_apply` automation profile flag) - * `cancelled` (user/system cancelled; safe terminal) + | State | Terminal? | Description | + | :---- | :-------: | :---------- | + | `queued` | No | Waiting for compute/worker | + | `processing` | No | Currently running — diff review, conflict resolution, validation | + | `errored` | Yes | Failed; includes error metadata | + | `applied` | Yes | ==Changes successfully committed== to real resources | + | `constrained` | Yes | Cannot complete within current strategy's constraints; may trigger reversion to Strategize | + | `cancelled` | Yes | User/system cancelled; safe terminal | #### Plan Identity and Traceability Every plan should have: -* **plan_id**: Unique, immutable ID (UUID or ULID). -* **parent_plan_id**: Nullable; present for child plans. -* **root_plan_id**: The top-most plan in the tree. -* **attempt**: An integer attempt counter that increments when re-running a phase (e.g., re-executing after a fix). -* **created_at / updated_at / completed_at** timestamps. -* **created_by** (user identity / session identity). +| Field | Type | Description | +| :---- | :--- | :---------- | +| `plan_id` | UUID/ULID | ==Unique, immutable== identifier | +| `parent_plan_id` | UUID/ULID? | Nullable; present for child plans | +| `root_plan_id` | UUID/ULID | The top-most plan in the tree | +| `attempt` | Integer | Attempt counter (increments on phase re-run) | +| `created_at` | Timestamp | When the plan was created | +| `updated_at` | Timestamp | Last modification time | +| `completed_at` | Timestamp? | When the plan reached a terminal state | +| `created_by` | Identity | User or session identity | #### Plan Hierarchy and Parallelism @@ -5227,28 +17442,34 @@ This is core to the long-term objective: tackling large tasks while only recompu ##### Hierarchical Decomposition for Scale -When handling massive tasks (e.g., converting Firefox to Rust), the system uses hierarchical decomposition. Each level spawns child plans (which are themselves full Plans with their own decision trees): +??? example "Example: Converting Firefox to Rust" + When handling massive tasks, the system uses hierarchical decomposition. Each level spawns child plans (which are themselves full Plans with their own decision trees): -1. **Root Plan**: High-level architectural decisions and invariants - - "Convert Firefox Renderer to Rust" - - Invariant: "Maintain API compatibility with existing C++ callers" - - Decision: "Start with leaf modules, work inward" - - Context: Module dependency graph (2,847 modules) + **1. Root Plan** — High-level architectural decisions and invariants -2. **Subsystem-Level Plans**: Major component decisions (spawned via `subplan_parallel_spawn` for independent subsystems) - - "Phase 1: Convert utility libraries (no external deps)" - - Each subsystem plan gets its own bounded context and inherits parent invariants - -3. **Module-Level Plans**: Individual module conversions - - "Convert string_utils module" - - Context: Only the 47 functions and 12 dependent files - - Decision: "Use Rust's String type" + : - "Convert Firefox Renderer to Rust" + - Invariant: "Maintain API compatibility with existing C++ callers" + - Decision: "Start with leaf modules, work inward" + - Context: Module dependency graph (2,847 modules) -4. **File-Level Plans**: Specific file changes - - Actual code transformations - - Minimal context needed + **2. Subsystem-Level Plans** — Major component decisions (`subplan_parallel_spawn`) -At each level, only the relevant context is loaded. The persistent decision graph means we can always reconstruct why we're converting a particular module and what constraints (including inherited invariants) apply from higher-level decisions. + : - "Phase 1: Convert utility libraries (no external deps)" + - Each subsystem plan gets its own bounded context and inherits parent invariants + + **3. Module-Level Plans** — Individual module conversions + + : - "Convert string_utils module" + - Context: Only the 47 functions and 12 dependent files + - Decision: "Use Rust's String type" + + **4. File-Level Plans** — Specific file changes + + : - Actual code transformations + - Minimal context needed + + !!! tip + At each level, only the ==relevant context== is loaded. The persistent decision graph means we can always reconstruct why we're converting a particular module and what constraints apply from higher-level decisions. ##### Child Plan Spawning Mechanism @@ -5318,14 +17539,24 @@ The `local/plan-tools` skill references this tool (and others) by name: ##### Child Plan Execution Modes -* **Sequential**: Individual `subplan_spawn` decisions without a `subplan_parallel_spawn` wrapper execute one after another. If one fails, subsequent child plans are not started. -* **Parallel**: Multiple `subplan_spawn` decisions grouped under a `subplan_parallel_spawn` decision execute concurrently. If one fails, others can continue. The `subplan_parallel_spawn` decision acts as a container that signals the system to spawn all enclosed child plans simultaneously. +=== "Sequential" + + Individual `subplan_spawn` decisions without a `subplan_parallel_spawn` wrapper execute one after another. If one fails, subsequent child plans are ==not started==. + +=== "Parallel" + + Multiple `subplan_spawn` decisions grouped under a `subplan_parallel_spawn` decision execute ==concurrently==. If one fails, others can continue. The `subplan_parallel_spawn` decision acts as a container that signals the system to spawn all enclosed child plans simultaneously. ##### Child Plan Failure Handling -* **Parallel execution** (via `subplan_parallel_spawn`): Other parallel child plans continue even if one fails. -* **Sequential execution**: Subsequent child plans are not started if a prior one fails. -* **Note**: An "error" only occurs if an exception is thrown by the application (a bug). Plan failures (e.g., tests don't pass) are handled within the plan's logic, not as application errors. +!!! note "Failure Semantics" + | Execution Mode | On Failure | Behavior | + | :------------- | :--------- | :------- | + | **Parallel** | One child fails | Other child plans ==continue== | + | **Sequential** | One child fails | Subsequent child plans ==not started== | + + !!! tip + An "error" only occurs if an exception is thrown by the application (a bug). Plan failures (e.g., tests don't pass) are handled within the plan's logic, not as application errors. ##### Child Plan Result Merging @@ -5949,22 +18180,14 @@ Key properties: A sandbox isolates plan execution from the real project resources until Apply. -##### Key Sandbox Principles +!!! tip "Key Sandbox Principles" + - [x] **Lazy Sandboxing** — Resources are sandboxed ==only when accessed==, not upfront + - [x] **Per-Plan Sandboxes** — Each plan and child plan has its own isolated sandbox + - [x] **Resource-Defined Strategy** — The sandbox strategy is defined on each **resource**, not globally + - [x] **Cleanup Behavior** — Automatic cleanup on exit, crash recovery on next run, retention-based archival -1. **Lazy Sandboxing**: Resources are sandboxed **only when accessed**, not upfront. - - A project may have many resources (git repo + 10 databases + cloud accounts) - - A plan may only modify one resource - - Only accessed resources are sandboxed - - Efficient for large projects - -2. **Per-Plan Sandboxes**: Each plan and child plan has its own sandbox containing only the resources it edits. - -3. **Resource-Defined Strategy**: The sandbox strategy is defined on each **resource**, not by skills or globally. - -4. **Cleanup Behavior**: - - Sandboxes are cleaned up before application exit when possible - - Abandoned sandboxes (from crashes, etc.) are cleaned up on next application run - - Completed plan sandboxes are cleaned or archived based on retention policy +??? info "Why Lazy Sandboxing?" + A project may have many resources (git repo + 10 databases + cloud accounts), but a plan may only modify one resource. Only accessed resources are sandboxed, making this efficient for large projects with many linked resources. ##### Sandbox Implementation Strategies @@ -6704,20 +18927,24 @@ This enables a pattern where: An **actor** is the abstraction that generalizes "agent" into "anything conversational." -* It can be as small as a single LLM agent. -* It can also be an entire graph that itself calls other actors/tools. -* Actors can be nested/hierarchical, enabling "orchestrator of orchestrators." +!!! abstract "Actor at a Glance" + * It can be as small as a ==single LLM agent==. + * It can also be an ==entire graph== that itself calls other actors/tools. + * Actors can be nested/hierarchical, enabling "orchestrator of orchestrators." -**Every custom actor IS a graph** (a LangGraph defined via YAML configuration). Even a simple actor wrapping a single LLM is technically a graph with one node. + **Every custom actor IS a graph** (a LangGraph defined via YAML configuration). Even a simple actor wrapping a single LLM is technically a graph with one node. #### Actor Naming Actors are **always named using `/` format**: -* `local/my-reviewer` - Local actor -* `freemo/code-analyzer` - Personal server actor -* `cleverthis/deploy-specialist` - Organization actor -* `openai/gpt-4` - Built-in LLM actor +??? example "Naming Examples" + | Name | Namespace | Description | + | :--- | :-------- | :---------- | + | `local/my-reviewer` | `local` | Local actor on this machine | + | `freemo/code-analyzer` | `freemo` | Personal server actor | + | `cleverthis/deploy-specialist` | `cleverthis` | Organization actor | + | `openai/gpt-4` | `openai` | Built-in LLM actor | #### Actor Definition (YAML Configuration) @@ -6960,18 +19187,17 @@ A design goal is user empowerment: "users customize LLM behavior without modifyi #### What a Tool Is -A **tool** is a namespaced, independently registered, callable operation. It is the **atomic unit of execution** in CleverAgents — the smallest piece of functionality that can read, write, or transform resources. Tools are defined in their own YAML configuration files, managed through the `agents tool` CLI commands, and registered in the **Tool Registry**. +A **tool** is a namespaced, independently registered, callable operation. It is the ==atomic unit of execution== in CleverAgents — the smallest piece of functionality that can read, write, or transform resources. Tools are defined in their own YAML configuration files, managed through the `agents tool` CLI commands, and registered in the **Tool Registry**. Tools follow the same `/` naming convention as actors, skills, and other entities (e.g., `local/run-migrations`, `cleverthis/validate-api`, `local/create-subplan`). They support optional server-qualified prefixes for multi-server disambiguation (e.g., `dev:freemo/custom-analysis`). **Validation as a Tool subtype**: A **Validation** is a specialized subtype of Tool that extends the Tool class with validation-specific metadata (`mode`: required/informational) and a structured JSON return format (`{ "passed": bool, "message": string, "data": object }`). Because Validation extends Tool via standard class inheritance, it inherits all base properties and behaviors — registration, resource bindings, lifecycle hooks, capability metadata, source types (custom, MCP, agent_skill, builtin, and the validation-specific `wrapped` source for Validations that delegate to an existing Tool), and the ability to exist as a tool node in an actor graph. A Validation can also **wrap** an existing plain Tool via the `wraps` field, reusing the Tool's implementation and interpreting its output through a `transform` function — see the **Tool Wrapping** subsection under Core Concepts > Validation for details. -Key constraints on Validations: - -- **Always read-only**: Validations observe and report but never modify resources. `writes` is always `false` and `checkpointable` is always `false` (read-only operations need no checkpointing). The `agents validation add` command does not accept `--writes`/`--no-writes` or `--checkpointable`/`--no-checkpointable` flags. -- **Shared namespace**: Validations and plain Tools share the same naming namespace in the Tool Registry. A Validation and a plain Tool cannot have the same name — attempting to register a Validation with a name already taken by a Tool (or vice versa) results in a conflict error. -- **Superset/subset semantics**: A Validation can be used anywhere a Tool is expected (since it IS a Tool), but a plain Tool cannot be used where a Validation is specifically required (e.g., attached to a resource as a validation). -- **Unified management**: Since Validations live in the Tool Registry, they are listed via `agents tool list` (with `--type validation` to filter), inspected via `agents tool show`, and removed via `agents tool remove`. Only registration (`agents validation add`), attachment (`agents validation attach`), and detachment (`agents validation detach`) have validation-specific CLI commands. +!!! note "Key Constraints on Validations" + - **Always read-only**: Validations observe and report but ==never modify resources==. `writes` is always `false` and `checkpointable` is always `false`. + - **Shared namespace**: Validations and plain Tools share the same naming namespace in the Tool Registry. A name conflict results in an error. + - **Superset/subset semantics**: A Validation can be used anywhere a Tool is expected (since it IS a Tool), but not vice versa. + - **Unified management**: Listed via `agents tool list --type validation`, inspected via `agents tool show`, removed via `agents tool remove`. Only `add`, `attach`, and `detach` have validation-specific CLI commands. Validations can be attached to resources directly, or to resources through projects or plans. The same mechanisms used to determine what tools can operate on what resources carry over to determining what validations apply to a particular resource. See the **Validation** section (immediately following this Tools section) for full details on the Validation type system, modes, attachment scoping, failure handling, and data model. @@ -8014,10 +20240,14 @@ When `require_checkpoints` is enabled on a plan, the plan may **only** use tools #### What a Validation Is -A **Validation** is a specialized subtype of Tool designed to verify that work performed during plan execution meets specified quality, correctness, or compliance criteria. A Validation observes the current state of resources, evaluates a condition, and returns a structured pass/fail result. It never modifies resources — it only reads and reports. +!!! abstract "Validation in Brief" + A **Validation** is a specialized subtype of Tool designed to verify that work performed during plan execution meets specified quality, correctness, or compliance criteria. A Validation observes the current state of resources, evaluates a condition, and returns a structured ==pass/fail result==. It never modifies resources — it only reads and reports. Because Validation extends Tool via standard class inheritance, it is not a separate concept bolted onto the system — it *is* a tool, with additional constraints and metadata. This means validation benefits from the entire tool infrastructure: source types, resource bindings, lifecycle hooks, input/output schemas, registry management, skill composition, and actor graph integration. No parallel system is required. +!!! success "Safety Guarantee" + Validations are ==always safe to run==. They cannot cause side effects, corrupt state, or require rollback. This enables aggressive parallelization, speculative validation, and retry without concern. + #### Relationship to Tool A Validation inherits **all** base Tool properties: @@ -8043,17 +20273,20 @@ A Validation inherits **all** base Tool properties: #### Read-Only Enforcement -Validations are **always read-only**. This is a hard constraint, not a convention: +!!! danger "Hard Constraint — Not a Convention" + Validations are **always read-only**: -- `writes` is always `false`. A Validation must never modify, create, or delete resources. It reads the current state and reports findings. -- `checkpointable` is always `false`. Since a Validation produces no state changes, there is nothing to checkpoint or roll back. -- `read_only` is always `true` (implicit). This is the inverse of `writes` and is always set for validations. + | Property | Value | Reason | + | :------- | :---: | :----- | + | `writes` | `false` | Must never modify, create, or delete resources | + | `checkpointable` | `false` | No state changes → nothing to checkpoint | + | `read_only` | `true` | Implicit inverse of `writes` | -This constraint is enforced at multiple levels: +This constraint is enforced at ==multiple levels==: -1. **Registration time**: The `agents validation add` command does not accept `--writes`/`--no-writes` or `--checkpointable`/`--no-checkpointable` flags. Any `writes` or `checkpointable` values in the validation YAML configuration file are silently overridden to `false`. -2. **Runtime enforcement**: The execution runtime treats validation invocations as read-only operations. Resource bindings for validations are resolved with `access: read_only` semantics — the validation receives a read-only view of the resource, not a writable handle. If a validation's implementation attempts to write (e.g., a custom Python validation calling a write API), the sandbox enforces the read-only constraint and the invocation fails. -3. **Sandbox interaction**: When a validation executes within a plan's sandbox, it reads the sandbox state (e.g., the modified files in a git worktree) but cannot modify it. This allows validations to verify the work-in-progress without risk of corrupting it. +1. **Registration time**: The `agents validation add` command does not accept `--writes`/`--no-writes` or `--checkpointable`/`--no-checkpointable` flags. Any such values in the validation YAML are silently overridden to `false`. +2. **Runtime enforcement**: The execution runtime treats validation invocations as read-only operations. Resource bindings are resolved with `access: read_only` semantics. If a validation's implementation attempts to write, the sandbox enforces the constraint and the invocation fails. +3. **Sandbox interaction**: When a validation executes within a plan's sandbox, it reads the sandbox state but cannot modify it — verifying work-in-progress without risk of corruption. The read-only guarantee has an important architectural consequence: validations are **always safe to run**. They cannot cause side effects, corrupt state, or require rollback. This enables aggressive parallelization, speculative validation (running validations before all work is complete to provide early feedback), and retry without concern for accumulated state changes. @@ -8061,18 +20294,25 @@ The read-only guarantee has an important architectural consequence: validations Each Validation has a `mode` that determines how the system responds to failure: -**Required** (`mode: required`): -- The validation **must** pass for execution to proceed to the Apply phase. -- When a required validation fails, the execution actor attempts to fix the underlying issue (e.g., fix failing tests, correct lint errors) within the bounds of the current strategy, then re-runs the validation. -- This fix-then-revalidate loop continues up to the configured retry limit. -- If self-fix is exhausted, the actor may request a strategy revision (re-running the Strategize phase for the affected subtree) or escalate to the user, depending on the automation profile. -- Required validations act as hard gates — they define "definition of done" for a plan. +=== "Required (`mode: required`)" -**Informational** (`mode: informational`): -- The validation's result is **recorded** but does not block execution. -- When an informational validation fails, the result (including `message` and `data`) is included in the plan's validation summary for human review, but the plan continues normally. -- Informational validations are useful for advisory checks: bundle size reports, code complexity metrics, deprecation warnings, performance benchmarks, or any check where failure is noteworthy but not blocking. -- The distinction between required and informational allows teams to introduce new validations gradually — start as informational to measure impact, then promote to required once the codebase is clean. + !!! danger "Hard Gate" + Required validations ==must pass== for execution to proceed to the Apply phase. They define the "definition of done" for a plan. + + - When a required validation fails, the execution actor attempts to **fix the underlying issue** (e.g., fix failing tests, correct lint errors) within the bounds of the current strategy, then re-runs the validation. + - This fix-then-revalidate loop continues up to the configured retry limit. + - If self-fix is exhausted, the actor may request a strategy revision or escalate to the user, depending on the automation profile. + +=== "Informational (`mode: informational`)" + + !!! info "Advisory Check" + Informational validations are ==recorded but do not block== execution. Useful for advisory checks where failure is noteworthy but not blocking. + + - When an informational validation fails, the result (including `message` and `data`) is included in the plan's validation summary for human review, but the plan continues normally. + - Use cases: bundle size reports, code complexity metrics, deprecation warnings, performance benchmarks. + +??? tip "Gradual Promotion Pattern" + The distinction between required and informational allows teams to introduce new validations gradually — start as ==informational== to measure impact, then promote to ==required== once the codebase is clean. The mode is set at registration time (in the validation YAML or via `--required`/`--informational` on `agents validation add`) and applies globally to that validation. The mode cannot be overridden per-attachment — if different scopes need different enforcement levels for the same check, register separate validations with different names and modes. @@ -8202,9 +20442,12 @@ Validation is the **final step** of the Execute phase. The execution actor's wor ##### Validation is Not Run During Apply -Validation runs during Execute, **not** during Apply. By the time a plan reaches Apply, all required validations have already passed. Apply commits the sandbox changes to the real resources. If the user wants post-apply verification (e.g., integration tests against the real system), that should be implemented as a separate plan or an external CI pipeline — not as a validation attachment. +!!! warning "Apply is the Point of No Return" + Validation runs during Execute, **not** during Apply. By the time a plan reaches Apply, all required validations have already passed. Apply commits the sandbox changes to the real resources. -The rationale: Apply is a controlled commit step. Introducing validation during Apply would create a situation where committed changes might need to be rolled back, defeating the purpose of the sandbox model. The Execute phase is where all verification occurs, and Apply is the point of no return. + If post-apply verification is needed (e.g., integration tests against the real system), implement it as a separate plan or external CI pipeline — ==not as a validation attachment==. + + **Rationale**: Introducing validation during Apply would create situations where committed changes might need to be rolled back, defeating the purpose of the sandbox model. #### Validation Failure Handling @@ -8255,10 +20498,11 @@ When an **informational** validation returns `"passed": false`: ##### Validation Error vs. Validation Failure -An important distinction: - -- **Validation failure** (`passed: false`): The validation ran successfully and determined the condition was not met. This is normal and handled by the mode-specific logic above. -- **Validation error**: The validation itself failed to execute — a runtime exception, timeout, malformed return, or infrastructure failure. Validation errors are treated as required validation failures regardless of the validation's mode, because a validation that cannot run provides no assurance. +!!! note "Important Distinction" + | Condition | Meaning | Handling | + | :-------- | :------ | :------- | + | **Validation failure** (`passed: false`) | Validation ran successfully, condition not met | Mode-specific (fix loop for required, record for informational) | + | **Validation error** | Validation itself failed to execute (runtime exception, timeout, malformed return) | ==Always treated as required failure== regardless of mode | When a validation error occurs: - The result is recorded with `passed: false`, a system-generated `message` describing the error, and the raw error details in `data`. @@ -9021,23 +21265,21 @@ Both registries persist in the database (local SQLite or server). MCP server too A **session** is a user's interactive thread with CleverAgents across time. -A session should: - -* maintain conversational continuity, -* store plan references, -* persist memory (if enabled), -* provide a UI anchor (CLI invocation, TUI workspace, web session). +!!! abstract "Session Responsibilities" + - [x] Maintain ==conversational continuity== across interactions + - [x] Store plan references for active and past plans + - [x] Persist memory (if enabled) across CLI invocations + - [x] Provide a UI anchor (CLI invocation, TUI workspace, web session) #### Session and Memory Persistence The notes include a known issue: conversation history can be lost between CLI invocations depending on connection string configuration, implying the system needs a stable memory service backend. -Therefore, CleverAgents should specify: - -* sessions have stable IDs -* sessions can be resumed -* session storage backend is configured explicitly -* if session persistence is disabled, the UX should be explicit about it (no silent history loss) +!!! warning "Persistence Requirements" + - Sessions must have ==stable IDs== + - Sessions must be ==resumable== across CLI invocations + - Session storage backend must be ==configured explicitly== + - If session persistence is disabled, the UX must be explicit about it — ==no silent history loss== ### Server @@ -13731,20 +25973,25 @@ This makes plan runs auditable and correctable. #### Two Correction Modes -1. **Revert-from-history correction (`--mode=revert`)** +=== "Revert (`--mode=revert`)" -* Find the decision point in the tree -* Roll back all changes (code and non-code) to that point -* Re-run from that decision point forward -* Keep old execution artifacts for comparison -* Potentially expensive if high up in the tree + !!! warning "Potentially Expensive" + Find the decision point in the tree, roll back all changes (code and non-code) to that point, and re-run from that decision point forward. Old execution artifacts are kept for comparison. -2. **Add-at-end correction (`--mode=append`)** + - [x] Roll back all changes to the decision point + - [x] Re-run from that decision point forward + - [x] Keep old execution artifacts for comparison + - [ ] ==Potentially expensive== if high up in the tree -* Leave history intact -* Append a new plan at the end that fixes the outcome -* Cheaper and safer sometimes -* Does not rewrite history +=== "Append (`--mode=append`)" + + !!! success "Safer and Cheaper" + Leave history intact and append a new plan at the end that fixes the outcome. Does not rewrite history. + + - [x] Leave history intact + - [x] Append a new corrective plan at the end + - [x] Cheaper and safer in many cases + - [x] Does ==not rewrite history== #### Correction Flow (Revert Mode) @@ -13814,15 +26061,16 @@ agents plan diff --correction <correction_a #### Correction Safety -Corrections always: +!!! success "Safety Guarantees" + Corrections always: -* Create a new attempt revision (increment `plan.attempt`) -* Preserve old artifacts for diff/compare -* Run execute in sandbox again -* Require apply gating again -* Never modify already-applied changes + - [x] Create a new attempt revision (increment `plan.attempt`) + - [x] Preserve old artifacts for diff/compare + - [x] Run execute in sandbox again + - [x] Require apply gating again + - [x] ==Never modify already-applied changes== -This keeps history reproducible and prevents accidental destructive edits. + This keeps history reproducible and prevents accidental destructive edits. ### Human-in-the-Loop Collaboration @@ -13831,12 +26079,13 @@ This keeps history reproducible and prevents accidental destructive edits. Even though the direction is "more autonomous," the transcript explicitly recognizes that real workflows require engineers to collaborate with the system, editing code while it works, and using better UX integration (TUI/web/IDE). -So CleverAgents should aim for: - -* visibility: what is it doing now? -* interruptibility: pause/cancel/retry -* editability: allow user to modify strategy before execute -* reconciliation: detect if user changed sandbox files mid-run and handle it +!!! tip "Design Principles for Human-in-the-Loop" + | Principle | Description | + | :-------- | :---------- | + | **Visibility** | What is the system doing ==right now==? | + | **Interruptibility** | Pause / cancel / retry at any point | + | **Editability** | Allow user to modify strategy before execute | + | **Reconciliation** | Detect if user changed sandbox files mid-run and handle it | ### UI / Interaction Model @@ -13845,16 +26094,13 @@ So CleverAgents should aim for: #### CLI-first + TUI + Web App + IDE -The system intends to be CLI-first, with: +!!! abstract "Multi-Frontend Architecture" + The system is ==CLI-first==, with a single UI codebase powering multiple frontends: -* a TUI built using Textual, -* which can generate a web app "for free," -* and later an IDE plugin that embeds the TUI in the IDE. - -This implies a "single UI codebase" model: - -* same underlying view logic, -* multiple frontends. + - [x] **CLI** — Primary interface for all operations + - [x] **TUI** — Built using Textual for rich terminal experiences + - [x] **Web App** — Generated from TUI "for free" + - [ ] **IDE Plugin** — Future: embeds the TUI in the IDE #### Plan Tree Visualization @@ -13920,7 +26166,12 @@ In the TOML configuration file, the hierarchy maps directly to TOML's native tab Both forms are valid and can be mixed. The TOML parser normalizes them to the same internal representation. -Every key follows a resolution chain: CLI flag > environment variable > project-scoped config > global config file > built-in default. +!!! note "Configuration Precedence (highest to lowest)" + 1. ==CLI flag== (`--format`, `--data-dir`, etc.) + 2. ==Environment variable== (`CLEVERAGENTS_FORMAT`, etc.) + 3. ==Project-scoped config== (per-project overrides) + 4. ==Global config file== (`~/.cleveragents/config.toml`) + 5. ==Built-in default== #### Key Reference diff --git a/mkdocs.yml b/mkdocs.yml index b9f1072c7..7bddd90d3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -110,6 +110,22 @@ plugins: markdown_extensions: - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.critic + - pymdownx.caret + - pymdownx.keys + - pymdownx.mark + - pymdownx.tilde + - pymdownx.tasklist: + custom_checkbox: true + - attr_list + - def_list + - footnotes + - md_in_html + - tables - codehilite - toc: permalink: true