@iowarp/clio-coder 0.3.9 → 0.4.0

package/docs/exit-codes-and-output.md

@@ -1,6 +1,6 @@
 # Exit Codes & Machine-Readable Output Contracts
 
-This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.3.7`.
+This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.4.0`.
 
 Source implementations: `src/cli/` and `src/entry/`.
 

package/docs/extensions-and-sharing.md

@@ -1,7 +1,7 @@
 # Extensions, Prompt Templates, Skills, and Share Archives
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.4.0).
 
 Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that contribute prompts and skills. Share archives are portable JSON files for moving project/user Clio resources between machines or collaborators. Themes are built into the engine and are no longer loaded from extensions.
 
@@ -199,6 +199,30 @@ IDs must be lowercase and may include numbers, dots, underscores, and hyphens; t
 
 `compatibility.clio` is optional. When present, it must be a valid SemVer range such as `>=0.3.8`, `^0.3.8`, or `0.3.x`. Installation refuses a package whose range excludes the running Clio version and names the extension, its declared range, and that running version. Clio repeats the check whenever it loads installed extensions, so a package that becomes incompatible after a Clio version change stays visible in `extensions list` with its diagnostic but contributes no resources. An incompatible project package does not hide a compatible user package with the same ID. A manifest without `compatibility.clio` keeps the existing unrestricted behavior.
 
+### Extensions that dispatch
+
+An extension that builds a `DispatchRequest` against the `DispatchContract` is a
+dispatch producer and is bound by the typed-intent compatibility rules like any
+other. Build the declaration with `declaredScopeIntent()` from the dispatch
+domain rather than assembling the normalized object by hand: it runs the same
+path grammar, caps, deduplication, and provenance construction the dispatch tool
+uses, so an extension cannot mint an intent shape the tool could not.
+
+```ts
+import { declaredScopeIntent } from "../domains/dispatch/index.js";
+
+const built = declaredScopeIntent({ readRoots: ["src/"], writeRoots: ["src/generated/"] });
+if (!built.ok) throw new Error(`${built.reason}: ${built.message}`);
+await dispatch.dispatch({ agentId: "coder", executionRole: "builder", task, intent: built.intent });
+```
+
+An extension that declares nothing keeps working: scope falls back to legacy
+inference over its task and briefing text, and the request is refused only when
+it states a contradiction, such as a legacy `writeRoots` disagreeing with a
+declared `write_roots`. Declaring is what stops an applicable project rule from
+being missed because the task text happened not to spell a path. See
+[dispatch-typed-intent.md](dispatch-typed-intent.md).
+
 ---
 
 ## Extension CLI

package/docs/fleet-dispatch.md

@@ -1,6 +1,6 @@
 # Fleet Dispatch
 
-> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.4.0).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -216,6 +216,27 @@ concurrent. Waiting writers follow the plan's declared step order and then the
 request order. Agent ledger claims remain advisory and do not enforce the
 token.
 
+### Declared step scope
+
+A v4+ contract's per-step `writes:` declaration has two consumers. The
+write-boundary enforcer verifies the step window afterwards, which is where the
+boundary is enforced; pre-emptive confinement for declared commands would need a
+command sandbox that does not exist. The same declaration also compiles into the
+step's typed dispatch intent as `relevant_paths`, so the paths the contract
+already named select the project rules that apply to them and pin the worker's
+context instead of being reconstructed from path-like tokens in the rendered
+prompt.
+
+It is carried as declared scope rather than as intent `write_roots` on purpose.
+Intent write roots become the enforced boundary at the per-tool worker seam,
+which refuses outright on the subprocess and ACP runtimes a fleet may
+legitimately route a step to, so restating the contract's boundary there would
+mint a second grant in a second place and fail closed on contracts that run
+correctly today. A pre-v4 contract and every readonly step declare nothing and
+keep the legacy inference path. See
+[dispatch-typed-intent.md](dispatch-typed-intent.md) for the full producer
+table and the refusal reason codes.
+
 The first checkout writer acquires a process-owned lease under the Clio state
 directory. Its key is the canonical checkout path, and its record contains the
 owner pid, process birth token, and acquisition time. A live sibling process

package/docs/installation-and-lifecycle.md

@@ -3,7 +3,19 @@
 Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.9). You can open it directly in any web browser to view details dynamically.
+> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.4.0). You can open it directly in any web browser to view details dynamically.
+
+### Optional dependency: the Claude Agent SDK
+
+`@anthropic-ai/claude-agent-sdk` is an `optionalDependencies` entry, not a hard dependency. Its platform package carries a proprietary binary of roughly 224MB per platform, and only the `claude-sdk` runtime uses it. Skip it with:
+
+```bash
+npm install -g @iowarp/clio-coder --omit=optional
+```
+
+Measured on Linux x64 with a production install (`--omit=dev`): 387MB across 118 packages with the SDK, 143MB across 109 packages without it. That is 244MB and nine packages saved, a 63% smaller tree, and what remains is fully open-licensed.
+
+Everything except the `claude-sdk` runtime works on the smaller install: boot, `clio-coder doctor`, every other target and worker runtime. Dispatching a `claude-sdk` target on an install that omitted the package fails that run with a diagnostic naming the package and the command that fixes it (`npm install @anthropic-ai/claude-agent-sdk@0.3.186`); nothing else degrades, and nothing fails at startup.
 
 ---
 
@@ -84,6 +96,7 @@ The core files are created automatically during the first run. `credentials.yaml
 | **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install), `upgradedAt` and `upgradedFrom` (stamped on a version change), and `noticedVersion` (the version whose one-time upgrade notice the interactive launch has shown). | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **State** | `migrations.json` | Log of successfully applied schema/state migrations. | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **Data** | `memory/records.json` | Long-term learning memories (up to 500 records) proposed/approved from runs. | Writer/umask default | Removed by uninstall / `reset --data`. |
+| **Data** | `tools/<id>/<version>/` | One pinned external program Clio downloaded on request (`clio-coder tools install <id>`), with its upstream license text and a `clio-install.json` recording url, sha256, platform and install time. Binaries `0o755`, documents `0o644`. Only the pinned version is kept: a successful install prunes the versions it supersedes. | `0o755` dir | `clio-coder tools remove <id>` deletes every version of one tool; removed by uninstall / `reset --data`. |
 | **State** | `audit/YYYY-MM-DD.jsonl` | Daily safety audit logs showing allowed/blocked tool actions. | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **State** | `sessions/<cwdHash>/<id>/` | Session details: `meta.json`, `current.jsonl`, and fork hierarchies `tree.json`. | Writer/umask default | Removed by uninstall / `reset --state`. |
 
@@ -256,7 +269,7 @@ inventory of what a level covers, because a remembered list drifts as soon as a
 new artifact is written into a root.
 
 *   `--state` *(Default)*: Deletes the state root only. It holds every session transcript and the audit trail beside it, so a reset is the end of `resume`, `/view`, and their history. This is the level a bare `clio-coder reset` selects, and it carries that note in its preview.
-*   `--data`: Deletes the data root only: memory, evidence, evals (durable products).
+*   `--data`: Deletes the data root only: memory, evidence, evals, and any vendored external tools (durable products). The vendored tools are the one entry a reset cannot regenerate locally; `clio-coder tools install <id>` downloads them again.
 *   `--cache`: Deletes the cache root only.
 *   `--auth`: Deletes `credentials.yaml`. Removes all saved keys.
 *   `--config`: Deletes `settings.yaml` to revert preferences to default.

package/docs/middleware-and-components.md

@@ -1,7 +1,7 @@
 # Middleware and Component Registry
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.4.0).
 
 Clio Coder has two related but separate surfaces:
 

package/docs/model-catalog.md

@@ -1,7 +1,7 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.4.0).
 
 Clio Coder treats a selectable model as the intersection of three sources:
 
@@ -161,6 +161,15 @@ The Context Engine evaluates thinking mechanisms per model target and manages li
 
 - **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
 - **LM Studio (`lmstudio`):** Chat uses the OpenAI-compatible `/v1/chat/completions` surface, including its `reasoning` stream field. Clio controls thinking only with `reasoning_effort` and never sends `chat_template_kwargs` to LM Studio. See <https://lmstudio.ai/docs/developer/openai-compat/chat-completions>.
+- **LiteLLM (`litellm`):** This is a gateway runtime, not an `openai-compat`
+  alias. Discovery checks `/health/liveliness`, reads aliases and capability
+  metadata from `/v1/model/info`, and records the physical deployment reported
+  by `x-litellm-*` response headers. Defaults stay conservative when metadata is
+  absent: tools, vision, and reasoning are not inferred. The runtime advertises
+  standard `json_schema` structured output and treats schema-plus-tools as a
+  conflict because the gateway alias does not identify one stable upstream.
+  Residency is observe-only because LiteLLM owns loading and eviction behind the
+  alias.
 - **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
 - **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
 - **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.

package/docs/observability.md

@@ -1,7 +1,7 @@
 # Observability Viewer
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.4.0).
 
 `/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
@@ -257,8 +257,8 @@ The base provenance sets, steering, routing, quality, worker identity, result-co
 | `safety.toolTelemetry.ingestionErrors` | `number` | Current dispatch receipts | Malformed or lost frames, event-fold/source errors, and drain timeouts that make otherwise mediated telemetry incomplete | experimental |
 | `safety.toolTelemetry.unfinished` | `{ tool, count }[]` | Current dispatch receipts | Tool starts that had no matching finish when the receipt sealed | experimental |
 | `safety.toolTelemetry.workspaceMutationPossible` | `boolean` | Current dispatch receipts | Whether incomplete or unavailable telemetry could conceal a shared-workspace mutation; retry admission fails closed when true | experimental |
-| `autonomyEnforcement.grade` | `string` | Always in v0.3.7 | The autonomy grade level enforced for the run | experimental |
-| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.7 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
+| `autonomyEnforcement.grade` | `string` | Always in v0.4.0 | The autonomy grade level enforced for the run | experimental |
+| `autonomyEnforcement.autonomy` | `string` | Always in v0.4.0 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
 | `autonomyEnforcement.externalMode` | `string` | When running external worker | The execution mode of the external worker runtime | experimental |
 | `autonomyEnforcement.dangerousBypass` | `boolean` | When running external worker | Whether a safety bypass was explicitly activated | experimental |
 | `validationGrounding.claimed` | `number` | Validation grounding evaluated | Count of validations claimed by worker | experimental |

package/docs/proactive-memory.md

@@ -1,6 +1,6 @@
 # Proactive task memory
 
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.4.0).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still

package/docs/prompt-envelope-and-tools.md

@@ -1,7 +1,7 @@
 # Prompt Envelope and Tools
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.4.0).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 

package/docs/provider-adapter-cookbook.md

@@ -1,7 +1,7 @@
 # Provider Adapter Cookbook
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.4.0).
 
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 

package/docs/safety-model.md

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.4.0).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
@@ -13,7 +13,7 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 The `autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
 
-In Clio Coder v0.3.7, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
+In Clio Coder v0.4.0, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
 
 ### Autonomy levels
 

package/docs/scientific-validation.md

@@ -1,11 +1,11 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.4.0).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.7, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.4.0, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
 
 This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
 
@@ -95,7 +95,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## Common Scientific Artifact Families
 
-The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.7:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.4.0:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

package/docs/session-lifecycle.md

@@ -1,6 +1,6 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.7`.
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.4.0`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 

package/docs/skills-marketplace.md

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.4.0).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
 

package/docs/tool-usage.md

@@ -1,11 +1,11 @@
 # Tool Usage Reference
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.4.0).
 
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 
-In Clio Coder v0.3.7, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
+In Clio Coder v0.4.0, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
 
 ## Observation envelope: truncation notices, offload, next hints, and the turn budget
 
@@ -253,7 +253,7 @@ Arguments:
 - `cwd` (optional). Default agent working directory.
 - `timeout_ms` (optional). Aborts the whole dispatch; in sequential mode remaining tasks are skipped and the skip is reported.
 - `briefing` (optional string, top-level default or per-task override). Parent-composed context/data, not worker instructions: it cannot replace `task`. It is trimmed and omitted when blank, rejected above 12,000 UTF-8 bytes, sent as its own delimited untrusted dynamic message, and retained only as byte/hash provenance. The shared value applies to string tasks and object tasks without an override; an object-level briefing wins.
-- `intent` (optional object, top-level default or per-task override). Declares `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and `verification`. Path arrays contain normalized repository-relative POSIX paths. Verification entries contain a declared `check` id and optional `timeout_ms`; ids are resolved from package scripts and `.clio-coder/verifiers.yaml` before approval. Checks are ids, not shell commands.
+- `intent` (object, top-level default or per-task override, and the default way to dispatch). Declares `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and `verification`. Path arrays contain normalized repository-relative POSIX paths. Verification entries contain a declared `check` id and optional `timeout_ms`; ids are resolved from package scripts and `.clio-coder/verifiers.yaml` before approval. Checks are ids, not shell commands. Declared paths select the project rules that apply to them and pin worker context; omitting `intent` falls back to reading path-like tokens out of the task and briefing, which can miss an applicable rule. In a batch, per-task `intent` shallow-merges over the top-level object and is then checked against it as a ceiling: a task may narrow the shared scope and is refused with `intent_scope_widening` if it reaches outside. Declaring `write_roots` that disagree with a legacy `writeRoots`, an `expected_outputs` entry outside every declared write root, or an `intent.version` other than 2 are each terminal refusals carrying a stable reason code. See [dispatch-typed-intent.md](dispatch-typed-intent.md).
 - `gate` (optional string, top-level default or per-task override). Exact shorthand for `intent.verification=[{check: gate}]`. Supplying it together with `intent.verification` is refused.
 - `max_output_bytes` (optional). Summary byte budget; default 20000, split across runs with at least 1024 bytes each.
 
@@ -269,13 +269,23 @@ Sealed receipts are the durable evidence; worker prose remains advisory until ve
 
 ```text
 dispatch(list=true)
-dispatch(agent="debugger", task="Adversarially verify the strict v19 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", detach=true)
-dispatch(tasks=["Run the contract tests in tests/contracts/dispatch.test.ts and report each failure with its assertion"])
+dispatch(agent="debugger", task="Adversarially verify the strict v19 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", intent={read_roots: ["src/domains/dispatch/"]}, detach=true)
 dispatch(tasks=[
-  {agent: "researcher", task: "Map every caller of finalizeObservation and summarize the envelope shapes"},
-  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety.test.ts", intent: {write_roots: ["tests/contracts"], verification: [{check: "test"}]}}
+  {task: "Run the contract tests in tests/contracts/dispatch.test.ts and report each failure with its assertion",
+   intent: {read_roots: ["tests/contracts/", "src/domains/dispatch/"], verification: [{check: "test"}]}}
+])
+dispatch(tasks=[
+  {agent: "researcher", task: "Map every caller of finalizeObservation and summarize the envelope shapes",
+   intent: {read_roots: ["src/domains/"]}},
+  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety.test.ts",
+   intent: {write_roots: ["tests/contracts/"], expected_outputs: ["tests/contracts/safety.test.ts"], verification: [{check: "test"}]}}
 ], mode="parallel")
-dispatch(tasks=["Refactor step 1", "Refactor step 2"], mode="sequential", timeout_ms=600000)
+dispatch(
+  intent={read_roots: ["src/"], write_roots: ["src/domains/"]},
+  tasks=[
+    {task: "Refactor step 1", intent: {write_roots: ["src/domains/dispatch/"]}},
+    {task: "Refactor step 2", intent: {write_roots: ["src/domains/context/"]}}
+  ], mode="sequential", timeout_ms=600000)
 ```
 
 ## verify: run declared verification checks

package/docs/trace-store.md

@@ -1,7 +1,7 @@
 # Trace store contract
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.4.0).
 
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting & Error Remediation
 
-This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.7`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.4.0`.
 
 ---
 

package/docs/tui-design.md

@@ -1,7 +1,7 @@
 # Clio TUI Design System
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.4.0).
 
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
 

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.4.0).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.9",
+	"version": "0.4.0",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -96,8 +96,10 @@
 		"live:tui": "node --import tsx benchmarks/internal/pty-drive.ts",
 		"live:home": "node --import tsx benchmarks/internal/live-home.ts"
 	},
+	"optionalDependencies": {
+		"@anthropic-ai/claude-agent-sdk": "0.3.186"
+	},
 	"dependencies": {
-		"@anthropic-ai/claude-agent-sdk": "0.3.186",
 		"@earendil-works/pi-agent-core": "0.84.0",
 		"@earendil-works/pi-ai": "0.84.0",
 		"@earendil-works/pi-tui": "0.84.0",

package/src/cli/acp.ts

@@ -66,11 +66,15 @@ export async function runAcpCommand(
 	args: ReadonlyArray<string>,
 	options: { apiKey?: string; noContextFiles?: boolean; noSkills?: boolean; skillPaths?: ReadonlyArray<string> } = {},
 ): Promise<number> {
-	if (args.includes("--help") || args.includes("-h")) {
+	// The top-level argv parser normally rewrites --acp to the `acp` command
+	// sentinel. Keep the command boundary tolerant too, so another dispatcher
+	// can pass the flag spelling through without changing ACP option semantics.
+	const normalizedArgs = args[0] === "--acp" ? args.slice(1) : args;
+	if (normalizedArgs.includes("--help") || normalizedArgs.includes("-h")) {
 		process.stdout.write(HELP);
 		return 0;
 	}
-	const flags = parseAcpFlags(args);
+	const flags = parseAcpFlags(normalizedArgs);
 	if (typeof flags === "string") {
 		printError(flags);
 		process.stderr.write(HELP);

package/src/cli/argv.ts

@@ -70,6 +70,11 @@ export interface GlobalCliFlags {
 	noContextFiles: boolean;
 	noSkills: boolean;
 	skillPaths: string[];
+	/**
+	 * Panes activation from the command line. `--with-panes` and `--no-panes`
+	 * both beat the `panes.enabled` setting; absent means the setting decides.
+	 */
+	panes?: "with" | "without";
 	rest: string[];
 	error?: string;
 }
@@ -85,6 +90,8 @@ const GLOBAL_ONLY_FLAGS: ReadonlyMap<string, string> = new Map([
 	["--api-key", "--api-key <key>"],
 	["--no-context-files", "--no-context-files"],
 	["-nc", "-nc"],
+	["--with-panes", "--with-panes"],
+	["--no-panes", "--no-panes"],
 ]);
 
 /**
@@ -128,6 +135,7 @@ export function extractGlobalFlags(
 	let apiKey: string | undefined;
 	let noContextFiles = false;
 	let noSkills = false;
+	let panes: "with" | "without" | undefined;
 	const skillPaths: string[] = [];
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -140,6 +148,14 @@ export function extractGlobalFlags(
 			rest.push(...argv.slice(i));
 			break;
 		}
+		if (arg === "--acp") {
+			// Treat the global spelling as a command boundary. Rewriting only the
+			// sentinel keeps every trailing ACP option on the exact same dispatcher
+			// and parser path as `clio-coder acp`, without importing that command into
+			// the dependency-light startup graph.
+			rest.push("acp", ...argv.slice(i + 1));
+			break;
+		}
 		if (ROOT_FLAG_TOKENS.has(arg)) {
 			rest.push(arg);
 			continue;
@@ -152,6 +168,12 @@ export function extractGlobalFlags(
 			noSkills = true;
 			continue;
 		}
+		if (arg === "--with-panes" || arg === "--no-panes") {
+			// Last occurrence wins, so a wrapper script's baked-in choice can be
+			// overridden by appending the opposite flag.
+			panes = arg === "--with-panes" ? "with" : "without";
+			continue;
+		}
 		if (arg === "--api-key" || arg === "--skill") {
 			const value = argv[i + 1];
 			if (value === undefined || value.startsWith("-") || isSubcommand(value)) {
@@ -162,6 +184,7 @@ export function extractGlobalFlags(
 					rest,
 					error: `${arg} requires a value`,
 					...(apiKey === undefined ? {} : { apiKey }),
+					...(panes === undefined ? {} : { panes }),
 				};
 			}
 			if (arg === "--api-key") apiKey = value;
@@ -176,6 +199,7 @@ export function extractGlobalFlags(
 			rest,
 			error: unknownGlobalOptionError(arg),
 			...(apiKey === undefined ? {} : { apiKey }),
+			...(panes === undefined ? {} : { panes }),
 		};
 	}
 	return {
@@ -184,5 +208,6 @@ export function extractGlobalFlags(
 		skillPaths,
 		rest,
 		...(apiKey === undefined ? {} : { apiKey }),
+		...(panes === undefined ? {} : { panes }),
 	};
 }