@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/{prompt-envelope-and-tools.md → architecture/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.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Prompt Envelope and Tools visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tools_blueprint.html).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 
@@ -9,7 +9,12 @@ Source of truth: `src/core/tool-names.ts`, `src/tools/agent-tools.ts`, `src/tool
 
 ## One system prompt per session
 
-The chat loop compiles one provider-facing system prompt for a session. The compile key is `target|model|autonomy|sessionId|workingContextPaths`, with the working-context paths sorted before hashing into the key.
+The chat loop compiles one provider-facing system prompt for a session. The
+version-2 compile identity hashes the target id, runtime id, wire model id,
+autonomy, session id, working directory, sorted working-context paths, context
+window source, prompt-input epoch, resolved session inputs, and the exact
+attached tool-schema bytes. `mainPromptCacheIdentity` in
+`src/interactive/prompt-cache-identity.ts` owns that list.
 
 The compiled prompt is reused byte-for-byte on ordinary submits. It recompiles only when that key changes or when config hot-reload invalidates the prompt cache. Path-scoped project rules can therefore recompile the prompt when a matching file enters working context. When recompilation changes the text, the session ledger records a `promptRecompiled` entry with the previous hash, new hash, and token estimate.
 
@@ -31,17 +36,17 @@ The first is a terseness rule. It is tempting to cap the prose a model emits bet
 
 The second is anything that varies with the wall clock or the working tree. No timestamp, no `git status`, no branch name, no session id, and no run id belongs anywhere in the compiled prefix. Every backend Clio targets caches by exact prefix and re-prefills from the earliest changed byte, so one such field turns the whole prompt into a cache miss on every turn for no information the model could not have asked a tool for. On the sprint's measurement server that is a whole 2,778-token prompt re-prefilled at 2.6 s where the same change behind the stable sections cost 516 tokens and 0.72 s. Volatile facts belong in the user message, in a tool result, or in the runtime block, which is last for this reason.
 
-The disk fragments under `src/domains/prompts/fragments/` are layered by who reads them. `identity.clio` and `operating.contract` are constitutional: they render for every reader, name no tool, and state what is always true about Clio and her harness. `operating.delegation` (fleet coordination, receipts, spot-checks, shared `[worker result]` notes) renders only when `dispatch` is on the session's tool surface, and `operating.skills` (skill-shaped tasks, `/skill <name>` suggestions) only when `context` is; a fragment that teaches a tool is absent when the tool is, the same rule the Fleet block follows. `identity.docs-routing`, the directive to call `context(scope="docs")` before answering a question about Clio herself, follows the `context` gate too, while `identity.self-awareness` (installed paths, code outranks docs, configuration locations) names no tool and is unconditional. `operating.worker` (the assigned-task contract) renders only for dispatched workers, which never see the coordinator fragments. `safety.<level>` states what runs, what is approval-required, and what is blocked at the effective autonomy, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name, so the same body is true on every surface; the session and every worker read that one body, and what "approval-required" resolves to is the only role text (one operator confirmation for the session, the worker's `onPermission` routing for a worker).
+The disk fragments under `src/domains/prompts/fragments/` are layered by who reads them. `identity.clio` and `operating.contract` are constitutional: they render for every reader, name no tool, and state what is always true about Clio and her harness. `operating.delegation` (the delegation threshold as a count taken before the first edit, with the dispatch call shape beside it; receipts, spot-checks, shared `[worker result]` notes) renders only when `dispatch` is on the session's tool surface, and `operating.skills` (skill-shaped tasks, `/skill <name>` suggestions) only when `context` is; a fragment that teaches a tool is absent when the tool is, the same rule the Fleet block follows. `identity.docs-routing`, the directive to call `context(scope="docs")` before answering a question about Clio herself, follows the `context` gate too, while `identity.self-awareness` (installed paths, code outranks docs, configuration locations) names no tool and is unconditional. `operating.worker` (the assigned-task contract) renders only for dispatched workers, which never see the coordinator fragments. `safety.<level>` states what runs, what is approval-required, and what is blocked at the effective autonomy, in the safety net's action-class vocabulary (read, write, command, `system_modify`, `git_destructive`) and never by tool name, so the same body is true on every surface; the session and every worker read that one body, and what "approval-required" resolves to is the only role text (one operator confirmation for the session, the worker's `onPermission` routing for a worker).
 
 Prompt extensions can add dynamic fragments for project rules, the operator profile, and Clio source-tree awareness. Pending skill requests and middleware reminders are visible text in the user message, not hidden prompt machinery.
 
 ## Prompt template expansion
 
-Prompt templates expand into the operator's user message before submission. They do not alter the compiled system prompt or bypass the trust check on project-scope compatibility roots. The prompt-root locations, frontmatter fields, and trust rules are documented in [extensions-and-sharing.md](extensions-and-sharing.md#prompt-templates).
+Prompt templates expand into the operator's user message before submission. They do not alter the compiled system prompt or bypass the trust check on project-scope compatibility roots. The prompt-root locations, frontmatter fields, and trust rules are documented in [extensions-and-sharing.md](../guide/extensions-and-sharing.md#prompt-templates).
 
 The first whitespace character after `/template-name` is the command delimiter; CRLF counts as one delimiter. Leading whitespace before the slash is also command framing. Every byte after that delimiter is the argument payload, including leading or trailing whitespace, repeated spaces, tabs, quotes, and line breaks.
 
-The template body may use `$ARGUMENTS` to insert that raw payload byte-for-byte. Raw insertion is not recursively substituted, so placeholder-like text such as `$1` remains data. `$1` through `$9`, `$@`, `${@:N}`, and `${@:N:L}` retain shell-style parsing: single or double quotes group spaces within one argument, `$@` joins all parsed arguments with single spaces, `${@:N}` selects parsed arguments from one-based position `N`, and `${@:N:L}` selects `L` arguments beginning there. A positional placeholder with no matching argument expands to an empty string. Template names that collide with built-in slash commands fail closed with a diagnostic and are excluded from `/prompts`.
+The template body may use `$ARGUMENTS` to insert that raw payload byte-for-byte. Raw insertion is not recursively substituted, so placeholder-like text such as `$1` remains data. `$1` through `$9`, `$@`, `${@:N}`, and `${@:N:L}` retain shell-style parsing: single or double quotes group spaces within one argument, `$@` joins all parsed arguments with single spaces, `${@:N}` selects parsed arguments from one-based position `N`, and `${@:N:L}` selects `L` arguments beginning there. A positional placeholder with no matching argument expands to an empty string. Template names that collide with built-in slash commands fail closed with a diagnostic and are excluded from `/resources prompts`.
 
 ## Directory-scoped handbook overrides
 
@@ -54,11 +59,11 @@ In addition to project root `CLIO-CODER.md` handbooks, Clio supports directory-s
 
 `wiki.page` and `wiki.plan` (`src/domains/prompts/fragments/wiki/*.md`) load through this same loader, with the same id/version/content-hash contract as every other fragment, but they are consumed differently: `context/wiki/prompts.ts` reads them by id, substitutes per-dispatch `{{token}}` placeholders (a page's path, title, and relative path; the plan file's path), and sends the result as a wiki-generation dispatch's `task`, never as a compiled system prompt. `{{token}}` substitution has no home in the fragment loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders use in `compiler.ts`: the loader hands back a raw body, and the one caller that needs live values fills them in. Both files' bodies open and close on a standalone `---` line that predates their frontmatter and was kept unchanged as body text so the substituted prompt stays byte-identical to what the old hand-rolled `readFileSync` produced.
 
-The Tool Contract section of the prompt renders a fixed set of base lines plus one optional guidance sentence per tool, sourced from the tool registry (`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in `src/tools/bootstrap.ts`). The base lines cover the complete-surface rule, the harness model (direct tools, fleet workers, skills as distinct capability sets), the capability-inventory rule, tool-free answering, the narrow-orientation tool list, validation before final claims, and failure recovery through `context(scope="docs")` instead of blind retries. Delegation, the tasks board, and skill listing are not restated here: `operating.delegation`, the `tasks` hint, and `operating.skills` each say their rule once and render exactly when their tool is on the surface. The one fleet-routing sentence (`FLEET_ROUTING_GUIDANCE`) renders when `dispatch` carries a hint and says only that the `agent` id is pinned from the Fleet section and `agent:"auto"` is a fallback. The chat loop derives the hint list once from the session's frozen tool surface at compile time, and the compiler renders the hints sorted by tool name, so the compiled text depends only on which hinted tools are on the surface. Today five tools carry hints: `ask_user`, `code_nav`, `context`, `dispatch`, and `tasks`. Removing a tool from the surface removes its hint with no compiler change; adding a hint to a tool is a deliberate prompt-text change that must land with updated prompt contract tests and a CHANGELOG note.
+The Tool Contract section of the prompt renders a fixed set of base lines plus one optional guidance sentence per tool, sourced from the tool registry (`ToolMetadata.promptHint` in `src/tools/registry.ts`, assigned in `src/tools/bootstrap.ts`). The base lines cover the complete-surface rule, the harness model (direct tools, fleet workers, skills as distinct capability sets), the capability-inventory rule, tool-free answering, the narrow-orientation tool list, validation before final claims, and failure recovery through `context(scope="docs")` instead of blind retries. Delegation, the tasks board, and skill listing are not restated here: `operating.delegation`, the `tasks` hint, and `operating.skills` each say their rule once and render exactly when their tool is on the surface. Fleet routing, including the sentence that `agent:"auto"` is a fallback rather than a router, lives in the Fleet block next to the roster ids and is not restated here; the threshold that says when to delegate at all is the opening of `operating.delegation`, not a Fleet line, because on the round-2 drive with Qwen3.8-27B the bare threshold after the tool contract lost to inertia on every run, while the same count stated up front with the call shape next to it dispatched both workers on every two-changes run and scout on every reconnaissance run once the sentence about repository size was in place. The chat loop derives the hint list once from the session's frozen tool surface at compile time, and the compiler renders the hints sorted by tool name, so the compiled text depends only on which hinted tools are on the surface. The frozen name list is the surface: a hint renders only for a tool in that list, and the gates that decide whether the Delegation, Skills, and docs-routing passages render read the same list, so a stale hint can neither render itself nor pull in a passage for a tool the model cannot call. Today six tools carry hints: `ask_user`, `bash`, `code_nav`, `context`, `panes`, and `tasks`. A hint carries only a decision-local call shape the tool's own description cannot; policy that applies across tools is said once in its prompt section, so `dispatch` carries no hint. Removing a tool from the surface removes its hint with no compiler change; adding a hint to a tool is a deliberate prompt-text change that must land with updated prompt contract tests and a CHANGELOG note.
 
 ## One tool surface per session
 
-For tool-capable providers, Clio sends the full registry as the session tool surface. The list is deterministic and sorted through the worker-tool resolver (`resolveAgentTools` in `src/tools/agent-tools.ts`), so the serialized schemas stay byte-identical on every submit. `src/tools/agent-tools.ts` is the single agent-tool adapter across the codebase. Both the orchestrator session and worker subprocesses resolve their tool set through the same `effectiveToolNames` narrowing function, ensuring that the attested signature and runtime surface cannot diverge.
+For tool-capable providers, Clio sends the full registry as the session tool surface. The list is deterministic and sorted through the worker-tool resolver (`resolveAgentTools` in `src/tools/agent-tools.ts`), so the serialized schemas stay byte-identical on every submit. The schema handed to the agent loop is `wireParameterSchema(spec.parameters)`: a copy with every `~`-prefixed key removed, because TypeBox 1.x stamps string-keyed markers such as `~unsafe` and `~optional` on the schemas it builds and, unlike the older symbol keys, those survive JSON serialization and reach the model as properties. Validation is unaffected (`Value.Check` answers identically with and without them) and the registry keeps the original object. `src/tools/agent-tools.ts` is the single agent-tool adapter across the codebase. Both the orchestrator session and worker subprocesses resolve their tool set through the same `effectiveToolNames` narrowing function, ensuring that the attested signature and runtime surface cannot diverge.
 
 Tools are keyed strictly by the canonical `ToolName` union defined in `src/core/tool-names.ts` with no alias table. Pure and idempotent `prepareArguments` normalizers defined on `ToolSpec` serve as the sole leniency layer for coercing legacy or weak-model parameter formats.
 
@@ -76,9 +81,16 @@ The compiler runs after target capability and tool-profile admission. Its canoni
 
 Project context, memory, bounded dispatch briefing, pipeline input, the assigned task, and the per-run safety-posture reminder remain dynamic user messages. A briefing is a separately delimited message labeled as untrusted task context/data; it is never concatenated into the task or stable system prompt. Dynamic ordering is project, safety, memory, briefing, then pipeline input, with pipeline input last. These messages do not affect the stable composition hash. Persona, effective autonomy, target tool capability, or final toolkit changes do affect it.
 
-## Seven planes, twenty tools
+## Seven planes, twenty-one tools
 
-The builtin surface is 20 registered tools organized in seven planes. Each plane is one policy unit: its tools share an action class, a size posture, a details schema, and a concurrency rule. `src/tools/policy.ts` asserts these invariants at bootstrap, so drift between the plane design, the safety classifier, and the registered specs fails loudly instead of shipping a surface that behaves differently from what the policy engine assumes.
+The canonical builtin catalog contains 21 tools organized in seven planes. A
+particular session or worker receives the subset whose dependencies and policy
+allow it to register. Each plane is one policy unit: its tools share an action
+class, a size posture, a details schema, and a concurrency rule.
+`src/tools/policy.ts` asserts these invariants at bootstrap, so drift between
+the plane design, the safety classifier, and the registered specs fails loudly
+instead of shipping a surface that behaves differently from what the policy
+engine assumes.
 
 | Plane | Tools | Action class | Concurrency |
 | --- | --- | --- | --- |
@@ -90,13 +102,36 @@ The builtin surface is 20 registered tools organized in seven planes. Each plane
 | ORCHESTRATE | `monitor` | read | parallel |
 | ORCHESTRATE | `tasks` | read | sequential |
 | ORCHESTRATE | `ledger` | read | sequential |
+| ORCHESTRATE | `panes` | read | sequential |
 | RETRIEVE | `web_fetch` | read | parallel |
 | INTERACT | `ask_user` | read | sequential |
 | ARTIFACT | `artifact` | write | sequential |
 
-Three tools sit in a plane for containment rather than class. `git` is read-only inspection (op=status/diff/log) that runs on the safe-exec spine, so it lives in the EXECUTE plane with read-class safety disposition. `monitor` never mutates a run, so it stays read class and parallel inside the ORCHESTRATE plane. `tasks` orchestrates the agent's own work rather than workers: it mutates only the session's task ledger, never the workspace, so it keeps read class (never gated behind a confirmation) but runs sequential so two board mutations in one batch cannot interleave. `ledger` is the agent ledger, the coordination board concurrent dispatch workers share: a post reaches a one-way control lane and a read answers from a local mirror, so it touches no workspace and stays read class, and reviewers and judges are pinned to read-only autonomy where a write class would block the peer review the board exists for.
-
-Registration is conditional on wiring: `context` gains its workspace scope only when a session contract is bound, `dispatch`/`monitor`/`steer` register only with a dispatch contract, and `ask_user` registers only when an interactive handler exists. Dispatch tool profiles narrow the surface for workers: `minimal-local` is `read`, `grep`, `find`, `ls`, `git`, `context`, `code_nav`; `science-local` adds `verify`; `full-agent` keeps everything.
+Several tools sit in a plane for containment rather than class. `git` is
+read-only inspection (op=status/diff/log) that runs on the safe-exec spine, so
+it lives in the EXECUTE plane with read-class safety disposition. `monitor`
+never mutates a run, so it stays read class and parallel inside the ORCHESTRATE
+plane. `tasks` orchestrates the agent's own work rather than workers: it mutates
+only the session's task ledger, never the workspace, so it keeps read class
+(never gated behind a confirmation) but runs sequential so two board mutations
+in one batch cannot interleave. `ledger` is the agent ledger, the coordination
+board concurrent dispatch workers share: a post reaches a one-way control lane
+and a read answers from a local mirror, so it touches no workspace and stays
+read class, and reviewers and judges are pinned to read-only autonomy where a
+write class would block the peer review the board exists for. `panes` controls
+only Clio-owned terminal panes through the live mux; it stays read class but is
+sequential so two operations cannot race the same pane registry.
+
+Registration is conditional on wiring: `context` gains its workspace scope only
+when a session contract is bound, `dispatch`/`monitor`/`steer` register only
+with a dispatch contract, `ask_user` registers only when an interactive handler
+exists, `ledger` registers only when a worker bound its dispatch's agent-ledger
+port (the session never does, and without a port the tool could only answer
+"no ledger"), and `panes` registers only when a pane host answered detection and
+the mux is live. Dispatch tool profiles narrow the surface for workers:
+`minimal-local` is `read`, `grep`, `find`, `ls`, `git`, `context`, `code_nav`,
+and `ledger`; `science-local` adds `verify`; `full-agent` keeps everything that
+the runtime registered and the recipe allows.
 
 `ask_user` keeps its typed `exposure: local | outward` admission fact separate from caller prose. The registry uses exposure only in the enforced autonomy mapping. After admission, the host carries the normalized fact into the shared decision-presentation classifier; question text, headers, options, summaries, and requested color or severity words cannot select a consequence tier. The resulting presentation object contains no admission disposition and cannot grant authority.
 
@@ -111,7 +146,7 @@ Several tools absorb what used to be separate tools:
 - `artifact(kind="plan"|"review"|"report", content, ...)` writes named artifacts behind one surface: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is written with the ordinary write tool and validated by the skills loader.
 - `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona`, `tool_profile`, and a typed `budget: {toolCalls, readReserve, retryRevision?}`. The budget must fit the recipe's authored range and the operator lifetime cap. `retryRevision` is the only authority for a later retry, result-contract revision, or review revision to grow its phase. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
 - `monitor(run_id?, mode?)` is read-only visibility into known synchronous and detached runs: `list` enumerates, `status` reports one, `peek` returns the in-process event tail, `receipt` exposes the stored evidence, and `wait` observes one run without collecting or canceling it. `collect` is the authoritative terminal batch operation over a detached batch or run-id list; collect before final synthesis. Completed output reports receipt integrity, evidence verification, briefing provenance, and bounded project-context provenance as different fields.
-- `steer(run_id, action, message?)` controls a running worker: `guide` writes a canonical trimmed steering message to an HTTP or SDK worker and `cancel` terminates it. Successfully written steers gain ordered byte/hash/timestamp provenance; after the runtime accepts the guidance, `clio_steer_received` acknowledges the exact matching sequence, and prose is never stored in ledger or receipt. Single-shot subprocess runtimes and ACP remain non-steerable. Interactive operators can steer synchronous live-input runs; parent-model steering requires detached ids because model tools are sequential.
+- `steer(run_id, action, message?)` controls a running worker: `guide` writes a canonical trimmed steering message to an HTTP or SDK worker and `cancel` terminates it. Successfully written steers gain ordered byte/hash/timestamp provenance; after the runtime accepts the guidance, `clio_coder_steer_received` acknowledges the exact matching sequence, and prose is never stored in ledger or receipt. Single-shot subprocess runtimes and ACP remain non-steerable. Interactive operators can steer synchronous live-input runs; parent-model steering requires detached ids because model tools are sequential.
 
 ### One ignore policy for path walkers
 
@@ -137,15 +172,15 @@ Unknown segments are omitted. `<total>` renders as `N+` when the search was kill
 {"error":"result exceeded <cap>","offloadPath":"...","next":"..."}
 ```
 
-**One turn budget.** All six envelope tools draw from a single per-turn pool keyed `sessionId:turnId`, default 192KB, overridable with `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES`. Each call reserves the minimum of its self cap and the remaining budget before doing the work. An exhausted pool short-circuits with an `[observation budget exhausted ...]` notice naming the tool, the subject, and the used/limit sizes, instead of paying for a search whose output could not be returned. A call whose cap was reduced by the pool appends a budget note telling the model to narrow its arguments or continue in a follow-up turn.
+**One turn budget.** All six envelope tools draw from a single per-turn pool keyed `sessionId:turnId`, default 192KB and configured by `safety.limits.observationBytesPerTurn`. Each call reserves the minimum of its self cap and the remaining budget before doing the work. An exhausted pool short-circuits with an `[observation budget exhausted ...]` notice naming the tool, the subject, and the used/limit sizes, instead of paying for a search whose output could not be returned. A call whose cap was reduced by the pool appends a budget note telling the model to narrow its arguments or continue in a follow-up turn.
 
-Per-call self caps: `read` 50KB (`CLIO_CODER_READ_MAX_BYTES`), `grep` 16KB for `mode=content` and 8KB for `files`/`count`, `find` 8KB, `ls` 8KB, `code_nav` 16KB, `context` 16KB for docs and 50KB for skills/workspace. The registry backstop cap for each envelope tool is its self cap plus 2KB slack, so a tool's own notice with its exact continuation call survives shaping instead of being cut again and replaced by a generic hint; the bootstrap policy assertion fails loudly if a cap ever drops below that.
+Per-call self caps: `read` 50KB (`safety.limits.readBytesPerCall`), `grep` 16KB for `mode=content` and 8KB for `files`/`count`, `find` 8KB, `ls` 8KB, `code_nav` 16KB, `context` 16KB for docs and 50KB for skills/workspace. The registry backstop cap for each envelope tool is its self cap plus 2KB slack, so a tool's own notice with its exact continuation call survives shaping instead of being cut again and replaced by a generic hint; the bootstrap policy assertion fails loudly if a cap ever drops below that.
 
 Every envelope result carries `details.observation` (`{tool, unit, shownCount, totalCount, shownBytes, totalBytes, truncated, format, next?, offloadPath?, budget?}`) for the TUI ledger, session turns, and observers.
 
 ## Description tiering
 
-Tool descriptions are tiered by how much a wrong call costs. The hot tools the model calls constantly (`read`, `grep`, `find`, `dispatch`) embed their operational contract in the description: caps, modes, ignore semantics, and how truncated results continue. Every other tool carries a one-to-two-sentence statement of what it does, and deep usage guidance lives in the bundled docs corpus ([tool-usage.md](tool-usage.md)) rather than the prompt prefix, retrievable on demand through `context(scope="docs")`. This keeps the serialized schema block small and byte-stable while still giving the model a path to depth when it needs one.
+Tool descriptions are tiered by how much a wrong call costs. The hot tools the model calls constantly (`read`, `grep`, `find`, `dispatch`) embed their operational contract in the description: caps, modes, ignore semantics, and how truncated results continue. Every other tool carries a one-to-two-sentence statement of what it does, and deep usage guidance lives in the bundled docs corpus ([tool-usage.md](../guide/tool-usage.md)) rather than the prompt prefix, retrievable on demand through `context(scope="docs")`. This keeps the serialized schema block small and byte-stable while still giving the model a path to depth when it needs one.
 
 ## The gateway reservation
 
@@ -155,8 +190,8 @@ Tool descriptions are tiered by how much a wrong call costs. The hot tools the m
 
 Clio uses two context-protection mechanisms.
 
-1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
-2. Auto-compaction uses one pressure threshold. The default threshold is 0.8. When pressure crosses the threshold, Clio first masks stale tool observations and stale thinking older than `excludeLastTurns`. If pressure remains above the threshold, it runs the LLM summary compaction path and replays from the compacted session view.
+1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ledger` uses 16KB; `panes` uses 8KB; and `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
+2. Auto-compaction uses one pressure threshold. The default threshold is 0.8. When pressure crosses the threshold, Clio first applies a non-destructive working-set eviction and records the evicted items in the session ledger. If pressure remains above the threshold, it runs the LLM summary compaction path and replays from the compacted session view. The older destructive observation/thinking mask is available only as a compatibility escape hatch when `CLIO_CODER_LEGACY_MASK=1`.
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the LLM summary path directly.
 
@@ -166,11 +201,13 @@ Compaction rewrites history, so the next turn on a local single-slot backend is
 
 Timing and cache behavior are persisted per API call, so a finished session can be inspected from its stored artifacts alone. Each assistant entry in the session ledger (`current.jsonl`, under the directory reported by `clio-coder paths`) carries `timing { ttftMs, apiMs }` and `promptCache { input, cacheRead, cacheWrite, backendVerdict }`, and the run's first persisted call also carries `expectedColdReasons`. Cache verdicts are `hot`, `partial`, `cold`, or `small`.
 
+Native session timing uses a monotonic clock from each stream invocation, before the provider's response-header wait, to its first observed output (`ttftMs`) and completion (`apiMs`). A tool-loop continuation starts a new clock; no output leaves TTFT null, and a genuine rounded zero remains zero. Historical values are not rewritten and may omit the pre-header wait. Eval prefers these durable native call records. Its stdout-only fallback starts at the provider's `message_start` event, which can arrive after headers, so fallback spans are not complete request latency and must not be compared as equivalent measurements.
+
 For aggregate cost and token facts across sessions, use `clio-coder usage report --days <n>`. Inside the TUI, `/cost` shows session totals and `/context` opens the context-window ledger overlay.
 
 ## Self-documentation retrieval
 
-`context(scope="docs")` is the model-facing companion to the human `clio-coder docs` server. The server serves bundled `docs/html/**` blueprints for people; the docs scope indexes the bundled markdown corpus for agents. It is deterministic and offline: no embeddings service, network call, or filesystem write is needed.
+`context(scope="docs")` is the model-facing companion to the human `clio-coder docs` server. From a source checkout, the server serves `docs/html/**` blueprints for people; in every installation, the docs scope indexes the bundled Markdown corpus for agents. It is deterministic and offline: no embeddings service, network call, or filesystem write is needed.
 
 The search index splits markdown into heading-delimited sections, records heading breadcrumbs and line ranges, and ranks results with light stemming, controlled Clio vocabulary aliases, phrase boosts, and BM25-style body scoring. The tool returns compact JSON containing corpus metadata, normalized and expanded query terms, and ranked hits with `file`, `heading`, `breadcrumb`, `anchor`, section `lines`, `snippetLines`, a bounded `snippet`, `matchedTerms`, `signals`, `coverage`, and `score`. `limit` defaults to 5 sections and caps at 12. The per-file filter the pre-consolidation docs tool accepted was dropped; narrow with more specific query terms instead. Even an empty result is valid JSON with empty arrays and a populated `next` continuation.
 

package/docs/{provider-adapter-cookbook.md → architecture/provider-adapter-cookbook.md}

@@ -1,17 +1,17 @@
 # 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.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Provider Adapter Cookbook visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/provider_adapter_blueprint.html).
 
 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.
 
 Source of truth:
-- Runtime descriptor types: [src/domains/providers/types/runtime-descriptor.ts](../src/domains/providers/types/runtime-descriptor.ts)
-- Registry loader: [src/domains/providers/registry.ts](../src/domains/providers/registry.ts)
-- Probe reasoning helpers: [src/domains/providers/probe/reasoning.ts](../src/domains/providers/probe/reasoning.ts)
-- Model capabilities resolver: [src/domains/providers/model-capabilities.ts](../src/domains/providers/model-capabilities.ts)
-- Inference capability flags: [src/domains/providers/types/capability-flags.ts](../src/domains/providers/types/capability-flags.ts)
-- Model target resolution: [src/domains/providers/runtime-resolution.ts](../src/domains/providers/runtime-resolution.ts)
+- Runtime descriptor types: [src/domains/providers/types/runtime-descriptor.ts](../../src/domains/providers/types/runtime-descriptor.ts)
+- Registry loader: [src/domains/providers/registry.ts](../../src/domains/providers/registry.ts)
+- Probe reasoning helpers: [src/domains/providers/probe/reasoning.ts](../../src/domains/providers/probe/reasoning.ts)
+- Model capabilities resolver: [src/domains/providers/model-capabilities.ts](../../src/domains/providers/model-capabilities.ts)
+- Inference capability flags: [src/domains/providers/types/capability-flags.ts](../../src/domains/providers/types/capability-flags.ts)
+- Model target resolution: [src/domains/providers/runtime-resolution.ts](../../src/domains/providers/runtime-resolution.ts)
 
 ---
 
@@ -72,12 +72,13 @@ export const myCustomRuntime: RuntimeDescriptor = {
 
 ## 2. Probing Mechanisms
 
-Probes discover the current state of a target inference server when Clio starts or when `/targets` or `/model` are refreshed.
+Probes discover the current state of a target inference server when Clio starts
+or when `/settings targets` or `/model` is refreshed.
 
 ### 2.1 Endpoint Probing (`probe`)
 The `probe` method validates endpoint reachability and collects loaded models:
 
-* **Inputs:** `TargetDescriptor` (which holds target `url`, optional `apiKey`, and connection metadata) and `ProbeContext` (which provides timeout signals and credentials). Request paths that resolve OAuth through `providers.auth.resolveForTarget` must pass `{ signal }`; Pi 0.84's `AuthOperationOptions` keeps cancellation attached while Clio waits for or mutates its credential store.
+* **Inputs:** `TargetDescriptor` (which holds target `url`, optional `auth` metadata, and connection metadata) and `ProbeContext` (which provides timeout signals, credential-presence keys, and an optional resolved `authToken`). Request paths that resolve OAuth through `providers.auth.resolveForTarget` must pass `{ signal }`; Pi 0.84's `AuthOperationOptions` keeps cancellation attached while Clio waits for or mutates its credential store.
 * **Return Value:** A `ProbeResult` indicating:
   * `ok`: True if reachable.
   * `serverVersion`: String identifier of the backend (e.g. `"Ollama/0.1.48"`).
@@ -87,7 +88,10 @@ The `probe` method validates endpoint reachability and collects loaded models:
 ### 2.2 Reasoning Probing (`probeReasoning`)
 For local endpoints where models are loaded dynamically, the runtime can supply a `probeReasoning` method. It sends a short mock completion request to inspect whether the model outputs reasoning/thinking tags (such as `reasoning_content` in OpenAI completions or `<think>` tags in raw text streams).
 
-Clio caches this result under the session's provider cache, preventing redundant network requests.
+Clio caches this result in the providers domain by exact target and model id for
+the current process. Provider reinitialization, configuration reload, and target
+disconnect paths clear the relevant cache rather than persisting it in a
+session ledger.
 
 ### 2.3 Exact-ID Capability Selection (`probeCapabilitiesForModel`)
 `probeCapabilitiesForModel` is the one exact-id selector during capability resolution. When a router target serves several models, `probeCapabilitiesForModel` matches `probeModelCapabilities` keyed strictly to the requested wire model ID. A router serving multiple models thus answers only from the `/v1/models` row keyed to its own wire model, preventing capability flags or token limits from bleeding across different models on the same target.
@@ -124,14 +128,14 @@ The `synthesizeModel` method acts as the factory that creates the `pi-ai` compat
   ): Model<Api>
   ```
 * **Tasks:**
-  1. Retrieve configured API credentials using `providers.auth` persisted through `openAuthStorage()`.
-  2. Instantiate the adapter client (e.g., building a `pi-ai` OpenAI or Anthropic provider instance).
-  3. Bind custom prompt templates and FIM (Fill-in-the-Middle) properties where supported.
+  1. Combine target, catalog, probe, and capability metadata into a `pi-ai` model descriptor.
+  2. Select the API family, endpoint, pricing, token limits, and Clio runtime metadata required by the streaming adapter.
+  3. Leave secrets and request-time authentication to `providers.auth.resolveForTarget` at the call site. Optional FIM support belongs to the descriptor's separate `infill` method rather than to prompt binding in `synthesizeModel`.
 
 
 ### 3.1 Stream Filters and Sentinel Stripping
 
-When a model family requires response parsing or sentinel stripping before the payload reaches the core logic, Clio applies runtime-agnostic stream filters during model synthesis. For example, if the resolved model family is `gemma-4`, a dedicated `createGemmaChannelFilter` is applied to intercept and reclassify `<|channel>thought` markers directly from the `text_delta` stream into `thinking_delta` events, dropping orphan channel closers and own-thought labels seamlessly.
+When a model family requires response parsing or sentinel stripping before the payload reaches the core logic, Clio applies runtime-agnostic stream filters in the engine stream adapter after model synthesis. For example, if the resolved model family is `gemma-4`, a dedicated `createGemmaChannelFilter` intercepts and reclassifies `<|channel>thought` markers directly from the `text_delta` stream into `thinking_delta` events, dropping orphan channel closers and own-thought labels seamlessly.
 
 ### 3.2 OpenAI-compatible sampling and vLLM budgets
 
@@ -160,9 +164,74 @@ level onto `thinking.type: "adaptive"` plus `output_config.effort` (read from th
 `thinkingLevelMap` and `compat.forceAdaptiveThinking`) or onto a bounded `budget_tokens` for
 budget-based models. Clio's `onPayload` hook no longer rewrites those fields; it only sets the
 OpenAI Responses `reasoning.summary` verbosity, which the agent loop cannot express as an option.
-`tests/contracts/thinking-runtime.test.ts` captures the wire payload Pi builds and proves Clio
-leaves it untouched.
-
+`tests/contracts/thinking-off-wire.test.ts` locks the local LM Studio and
+llama.cpp controls used when thinking is off. Anthropic request assembly is
+inherited from the pinned Pi dependency; Clio no longer carries a separate
+contract test that reconstructs Pi's whole adaptive or budget payload.
+
+
+
+### 3.3 Thinking controls through LiteLLM
+
+Dedicated memory and compaction roles read a cold LiteLLM target's metadata
+before synthesizing the completion model. The read disables reasoning probes;
+it does not run an extra inference request. Each selected target owns its probe
+state, even when two targets share a gateway URL. A successful unknown or mixed
+runtime declaration remains unknown and is not repeatedly probed for a preferred
+answer. Memory includes discovery and auth in its existing generation/deadline
+boundary; cancellation cannot launch a later completion or mark the endpoint
+down. Fresh discovered output limits also bound its request. After metadata and auth,
+memory rechecks actual endpoint occupancy immediately before registering its
+inference hold. Late saturation stays a dropped `endpoint_busy` boundary with
+no usage or cache-disturbance claim. Compaction checks
+the originating session/branch after preparation and uses the existing simple
+stream API with thinking off, rather than inferring an active level from the
+model's reasoning capability.
+
+Native worker admission also prepares the selected cold LiteLLM target before
+freezing its capabilities and thinking controls into the worker specification
+and receipt. Tool cancellation and the original admission deadline bound that
+wait, including a delayed metadata response body. Failed preparation releases
+the existing plan reservation and cannot launch a late worker or publish
+cancelled health data. The approved target, model, endpoint and node remain
+binding; changed route identity requires fresh admission. Metadata discovery
+does not infer capacity or residency from another route sharing the gateway,
+and does not bypass the existing capacity or approved tool-surface checks.
+
+
+A gateway alias is not an upstream runtime identity. Clio consumes the optional
+`model_info.runtime` deployment declaration from LiteLLM's `/v1/model/info` only
+when every deployment of the alias names the same recognized control runtime:
+`lm-studio` or `llama.cpp`. Missing, unknown, or mixed declarations produce no
+runtime-specific control hint. The probe-only `thinkingControlRuntime` capability
+travels through the existing main, background and worker model capability path;
+`runtimeId`, authentication, the gateway URL and residency ownership stay LiteLLM.
+Clio never infers this declaration from ports or model names and never loads or
+unloads the gateway's upstream models.
+
+The family still determines whether thinking is switchable and which active
+levels exist. A declared LM Studio route receives `reasoning_effort: "none"` for
+an effective off choice; a llama.cpp route uses its template switch. LiteLLM's
+generic OpenAI adapter may silently filter a resolved effort for local model
+names. Clio therefore adds `allowed_openai_params: ["reasoning_effort"]` only when
+it sends that model/runtime's resolved `reasoning_effort`; unrelated parameters
+and unknown off mechanisms are not newly allowed. This is a request control,
+not a change to gateway configuration. See [LiteLLM parameter forwarding](https://docs.litellm.ai/docs/completion/drop_params).
+
+[Qwen3.8-27B's pinned template](https://huggingface.co/Qwen/Qwen3.8-27B/blob/1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0/chat_template.jinja)
+accepts active `low`, `medium`, and `xhigh`, with thinking enabled and `xhigh`
+when the template receives no override. Clio shows off/low/medium/xhigh and maps
+released high/max selections to xhigh. That vendor default does not overwrite
+Clio's explicit chat preference or saved low setting. Disabling thinking does
+not remove historical reasoning or discard reasoning a server actually returns.
+
+Controlled gateway filtering tests cover discovery, capability transfer, actual
+HTTP payloads, off/on switching, and built CLI persistence. Live same-route
+probes on the selected LiteLLM deployment returned reasoning with the flag or
+none alone, zero reasoning on two calls with none plus the explicit allowance,
+and positive reasoning for an allowed low control. This verifies the measured
+route and request contract; unknown or heterogeneous gateway aliases need their
+own declared capabilities and acceptance.
 
 ---
 
@@ -172,11 +241,16 @@ Clio supports diverse thinking mechanisms. If your model family uses a custom fo
 
 | Mechanism | Behavior |
 | --- | --- |
-| `none` | **Reasoning-Never:** Clio strips thinking request fields (e.g., effort levels), avoids replaying thinking blocks in history, emits no TUI thinking events, and records no reasoning token usage metrics. |
-| `ollama-native` | Standard Ollama native thinking streams. |
-| `lmstudio` | Uses OpenAI-compatible chat and consumes streamed `reasoning`; thinking control uses only `reasoning_effort`. |
-| `openai-completions` | Replays thinking blocks via `reasoning_content` message parameters. |
-| `anthropic-max` | Anthropic extended thinking block protocol. |
+| `none` | The family does not reason; the effective level is `off` and thinking controls are omitted. |
+| `effort-levels` | Named levels map to provider effort values, such as LM Studio `reasoning_effort`. |
+| `budget-tokens` | Named levels map to explicit reasoning-token budgets. |
+| `on-off` | The runtime exposes a binary thinking switch rather than graduated effort. |
+| `always-on` | The model cannot disable reasoning; Clio reports the effective level as forced and allows extra completion headroom where required. |
+
+Wire formats such as `anthropic-extended`, `qwen-chat-template`, and
+`deepseek-r1` live in capability metadata. Runtime API families such as
+`openai-completions` and `ollama-native` are separate descriptor fields; neither
+set is a valid value for `quirks.thinking.mechanism`.
 
 ---
 
@@ -185,7 +259,7 @@ Clio supports diverse thinking mechanisms. If your model family uses a custom fo
 Once your runtime adapter descriptor is implemented:
 
 ### 5.1 Static Built-in Registration
-Add your descriptor to the static array export in [src/domains/providers/runtimes/builtins.ts](../src/domains/providers/runtimes/builtins.ts):
+Add your descriptor to the static array export in [src/domains/providers/runtimes/builtins.ts](../../src/domains/providers/runtimes/builtins.ts):
 ```typescript
 import { myCustomRuntime } from "./custom/my-custom-runtime.js";
 
@@ -198,4 +272,4 @@ export const BUILTIN_RUNTIMES = [
 ### 5.2 Dynamic Plugin Loading
 Clio's `RuntimeRegistry` can load custom runtimes dynamically at startup:
 * **Directories:** Place compiled Javascript descriptors (`.js`) inside `$CLIO_CODER_CONFIG_DIR/runtimes/` (defaulting to `~/.config/clio-coder/runtimes/`).
-* **Package exports:** Publish an npm package that exports a `clioRuntimes` array containing your runtime descriptors, then list the package name under `runtimePlugins` in your configuration settings.
+* **Package exports:** Publish an npm package that exports a `clioRuntimes` array containing your runtime descriptors, then list the package name under `integrations.runtimePlugins` in your configuration settings.

package/docs/{safety-model.md → architecture/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.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder Safety Model visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/safety_blueprint.html).
 
 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.
 
@@ -11,9 +11,9 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 ## Two axes: autonomy and the safety net
 
-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.
+The `safety.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.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.
+In the current source tree, 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
 
@@ -38,7 +38,7 @@ The exposure tier is the one row keyed by the call rather than by its action cla
 
 The `system_modify` confirm is level-invariant, so it is enforced and attributed as a safety-net confirm rail: the overlay, notices, and audit ledger name the net (reason code `system-modify-confirm`, policy source `builtin-classifier`), not the autonomy level. The matrix row above is unchanged in outcome at every level; only `read-only` converts the ask to a denial. `unknown` remains in the autonomy mapping because the registry substitutes a registered tool's base action class after the net evaluates.
 
-The level is persisted as `autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
+The level is persisted as `safety.autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
 
 ### Consequence tier is presentation, not authority
 
@@ -69,7 +69,7 @@ Every tool call, orchestrator or worker, evaluates in this order:
 
 1. **Safety net** (policy engine + middleware guards): `block` is final at every level; `ask` is a confirm rail (damage-control `ask` rules, project `requireConfirmation`, `system_modify`) that parks at every level; `pass` hands off to step 2. Blocks precede asks: a damage-control `ask` rule never bypasses a hard block, so confirming an ask-rule command that targets a zero-access path still blocks. The built-in path protection (which includes zero-access blocklists for critical files like `.git/config` and `credentials.yaml`, resolved with symlink canonicalization to prevent bypasses) is evaluated even when `.clio-coder/safety.yaml` is malformed, invalid, or attempts to override it. A malformed project policy cannot disable built-in default path protection, so credential protection never fails open.
 2. **Autonomy mapping**: the action class plus the level produce allow, ask, or deny per the matrix above.
-3. **Approvals**: whatever asked in step 1 or 2 parks interactively, denies deterministically headless, resolves per `workers.onPermission` in workers, and non-stall denies in delegations.
+3. **Approvals**: whatever asked in step 1 or 2 parks interactively, denies deterministically headless, resolves per `fleet.permissions.mode` in workers, and non-stall denies in delegations.
 
 ```mermaid
 graph TD
@@ -88,15 +88,20 @@ Net `confirm` is never auto-allowed by autonomy, including full-auto. Net `block
 
 ### Worker permission escalation
 
-Dispatched workers run non-interactively, so step 3 resolves per `workers.onPermission`: `deny` turns the parked call into a structured denial, `fail` ends the run, and `escalate` hands the ask up to the interactive operator. Under `escalate` the worker parks the call, emits a `clio_permission_escalated` event, and waits; dispatch republishes the ask on the bus tagged with the run id; the operator resolves it in the same permission overlay used for the main agent; and the decision returns down the worker's stdin. Resolution is human-only by construction: no model-facing tool can approve a worker permission, and the dispatch `resolveWorkerPermission` method is reachable only from the interactive layer. This preserves the receipt's honesty, since a model approving its own fleet's asks would collapse the audit trail.
+Dispatched workers run non-interactively, so step 3 resolves per `fleet.permissions.mode`: `deny` turns the parked call into a structured denial, `fail` ends the run, and `escalate` hands the ask up to the interactive operator. Under `escalate` the worker parks the call, emits a `clio_coder_permission_escalated` event, and waits; dispatch republishes the ask on the bus tagged with the run id; the operator resolves it in the same permission overlay used for the main agent; and the decision returns down the worker's stdin. Resolution is human-only by construction: no model-facing tool can approve a worker permission, and the dispatch `resolveWorkerPermission` method is reachable only from the interactive layer. This preserves the receipt's honesty, since a model approving its own fleet's asks would collapse the audit trail.
 
-Escalation can never hang a run. Every escalated ask resolves by an operator decision or by the `workers.escalation` timeout fallback (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`); a headless session has no subscriber, so the timeout fallback always governs there. The worker keeps emitting heartbeats while parked, so the reconciler does not reap it, and every escalation and its resolution source (operator or timeout) is recorded on the receipt.
+Escalation can never hang a run. Every escalated ask resolves by an operator decision or by the `fleet.permissions.escalation` timeout fallback (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`); a headless session has no subscriber, so the timeout fallback always governs there. The worker keeps emitting heartbeats while parked, so the reconciler does not reap it, and every escalation and its resolution source (operator or timeout) is recorded on the receipt.
 
 ---
 
 ## Operating Posture and Visible Tools
 
-Clio operates under a single operating posture with a standard, unified visible toolset. The 20 built-in tools are organized in seven planes; each plane is one policy unit for action class, size posture, and concurrency, asserted at bootstrap by `src/tools/policy.ts` so the classifier and the registered specs can never drift apart silently.
+Clio operates under a single operating posture. The canonical catalog contains
+21 built-in tools organized in seven planes; each plane is one policy unit for
+action class, size posture, and concurrency, asserted at bootstrap by
+`src/tools/policy.ts` so the classifier and registered specs cannot drift apart
+silently. Dependency wiring, target capability, worker profile, and recipe
+policy determine which subset is visible in a particular context.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
@@ -105,12 +110,12 @@ Clio operates under a single operating posture with a standard, unified visible
 | EXECUTE | `bash`, `verify` | `execute` |
 | EXECUTE | `git` | `read` |
 | ORCHESTRATE | `dispatch`, `steer` | `dispatch` |
-| ORCHESTRATE | `monitor`, `tasks` | `read` |
+| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes` | `read` |
 | RETRIEVE | `web_fetch` | `read` |
 | INTERACT | `ask_user` | `read` |
 | ARTIFACT | `artifact` | `write` |
 
-`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
+`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
 
 Target capability, dispatch tool profiles, and recipe constraints can further narrow the tools available to a run. That narrowing is convenience and budget control; safety still lives in code gates.
 
@@ -124,11 +129,12 @@ The `/view` workspace category treats a recorded successful write as a durable f
 
 A `SKILL.md` may declare `allowed-tools` and `disallowed-tools`. The declaration is enforced at tool admission, between the safety net and the autonomy mapping, on every surface that activates skills (interactive turns, headless `clio-coder run` turns, and dispatched workers whose recipes declare skills).
 
-- **Window.** Narrowing arms when `context` (scope="skills") successfully loads the skill and lasts for the lifetime of the pending-skill policy: to the end of the current turn for the main agent, and to the end of the run for a worker. A later turn is unrestricted until a skill is requested and loaded again.
+- **Window.** Narrowing arms when `context` (scope="skills") successfully loads the skill and lasts for the lifetime of the pending-skill policy. Interactively that is the session: the surface stays armed across the operator's later turns, because a multi-turn skill workflow is still the same workflow on the operator's next message. It ends when a different skill replaces it (the new skill's declaration replaces the old one, it is never merged into it), when the operator clears it with `/skill off`, or when the session ends. A worker keeps the run-scoped lifetime. Activation and clearing each emit one transcript line naming the armed skills.
+- **Who activates.** At `read-only` and `suggest` only the operator activates a skill: a model `context(scope="skills", name=...)` call is refused and the model's move is the suggestion anchor. At `auto-edit` and `full-auto` the model activates an installed skill itself, under the same per-run policy `/skill` produces, because the operator has already chosen to let it act and narrowing can only subtract from the surface. The autonomy level is the whole opt-in; there is no frontmatter flag. A skill that is not installed stays operator-gated at every level, and the transcript line names who activated. This holds on every surface that resolves effective autonomy through the chat loop, which is all three: interactive turns, headless `clio-coder run --autonomy ...`, and ACP prompts (including a per-session level an ACP client sets). Dispatched workers are unaffected: a worker loads only the skills its recipe declares.
 - **Merge.** Denials win: a tool named in any loaded skill's `disallowed-tools` is blocked. Allow-narrowing applies only while every loaded skill declares `allowed-tools`; the merged surface is the union of those lists. A loaded skill that declares no `allowed-tools` keeps the full surface for its own workflow, which lifts the allow-narrowing (never the denials) for that window.
 - **Exemptions.** `context` (the remaining requested skills of the turn must still load) and `ask_user` (the escape hatch the block message points at) are always admitted.
 - **Direction.** Narrowing only blocks. It never grants a tool the safety net, damage-control rules, or autonomy mapping would refuse, and an out-of-surface call blocks terminally instead of parking for confirmation.
-- **Block message.** The rejection names the tool, the active skill(s), and the merged surface, and states the remediation: work within the declared surface, or use `ask_user` (when available) to hand the step to the operator. The audit row carries reason code `skill_surface`.
+- **Block message.** The rejection names the tool, the active skill(s), the merged surface, and the lifetime that actually applies (session-scoped for a carried surface, turn/run-scoped otherwise), and states the remediation: work within the declared surface, or use `ask_user` (when available) to hand the step to the operator. The audit row carries reason code `skill_surface`.
 
 ---
 
@@ -231,7 +237,8 @@ Path-policy behavior:
 The default damage-control policy populates `noWritePaths` from the interop
 agent registry: `~/.claude/`, `.claude/`, `~/.codex/`, `.codex/`, `~/.config/opencode/`,
 `.opencode/`, `~/.gemini/`, `.gemini/`, `~/.copilot/`, `~/.cursor/`, `.cursor/`,
-`~/.antigravitycli/`, `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
+`~/.gemini/antigravity-cli/`, `.gemini/antigravity-cli/`, the legacy
+`~/.antigravitycli/` and `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
 into another coding agent's directory. It reads those roots for skills, prompts, and
 rule prose and has no reason to author them. A `write` or `edit` targeting any of
 these paths is refused at every posture including `auto-edit` and `full-auto`, with reason
@@ -285,14 +292,22 @@ Fleet dispatch is admitted only when the requested worker scope is a subset of t
 
 Dispatch workers can run the same HTTP or native runtimes as the orchestrator. Clio observes and governs those tool calls directly, so every worker run is subject to the same safety mapping and receipt accounting as an interactive turn.
 
-Three integration paths exist for driving Claude Code, ranging from fully enforced to advisory gating:
+Three worker-runtime safety categories range from fully enforced to advisory gating:
 
-- **`claude-sdk` (Enforced Safety):** Drives [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) directly. This is the **strong safety path** because Clio enforces tool gating before execution. Clio registers a `PreToolUse` hook (which fires for all tool uses, including auto-allowed reads) and wraps `canUseTool` for permission paths. Every tool request is mapped into a Clio tool/action class, evaluated by the safety net, and passed through the active autonomy matrix. Because a dispatched worker is noninteractive, any `ask` decision is resolved as a non-stall denial (`workers.onPermission=deny` returns denial; `workers.onPermission=fail` terminates the run with a permission-required code).
-- **`claude-code` (Subprocess Gating):** Drives `claude -p` as a subprocess. Because the CLI lacks a direct callback hook, Clio cannot evaluate each tool invocation. Instead, Clio maps the active autonomy level to the binary's command-line parameters (such as `--permission-mode` and tool allowlists). Unrecognized tools are gated by the subprocess runtime itself. Dispatch at autonomy `suggest` is refused outright (the same applies to `antigravity-code`): a subprocess cannot park a tool call for approval, so `suggest` has no honest mapping and the runner fails closed before launching the external CLI. A dangerous bypass (`--allow-dangerously-skip-permissions`) is only sent when autonomy is `full-auto` and `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1`, and it is never silent: the run's receipt records it (see the enforcement grades below) and evidence raises an external-bypass finding.
+- **`claude-sdk` (Enforced Safety):** Drives [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) directly. This is the **strong safety path** because Clio enforces tool gating before execution. Clio registers a `PreToolUse` hook (which fires for all tool uses, including auto-allowed reads) and wraps `canUseTool` for permission paths. Every tool request is mapped into a Clio tool/action class, evaluated by the safety net, and passed through the active autonomy matrix. Because a dispatched worker is noninteractive, any `ask` decision is resolved as a non-stall denial (`fleet.permissions.mode=deny` returns denial; `fleet.permissions.mode=fail` terminates the run with a permission-required code).
+- **External CLI subprocesses:** `claude-code` drives `claude -p`; the experimental, dispatch-only `antigravity-code` runtime drives the operator's local `agy` through one literal stdin `stream-json` work order. Neither exposes a callback through which Clio can evaluate each tool invocation, so Clio maps autonomy onto each CLI's command-line controls. Antigravity launches always name an explicit mode and disable slash-command expansion rather than inheriting mutable interactive settings. Dispatch at autonomy `suggest` is refused outright: a subprocess cannot park a tool call for approval, so `suggest` has no honest mapping and the runner fails closed before launch. A dangerous bypass (`--allow-dangerously-skip-permissions` for Claude or `--dangerously-skip-permissions` for Antigravity) is sent only when autonomy is `full-auto` and `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1`; otherwise Antigravity full-auto is capped at `accept-edits`. A bypass is never silent: the run's receipt records it (see the enforcement grades below) and evidence raises an external-bypass finding. Clio sends an allowlisted child environment rather than its provider keys or external-full-access gate, bounds stdout/stderr and persisted diagnostics, validates the admitted workspace, and owns the deadline and cancellation. POSIX cancellation targets the process group with direct-child fallback and bounded SIGTERM-to-SIGKILL escalation; Windows uses the strongest honest direct-child termination available here.
 - **Claude Code over ACP (Advisory Gating):** Drives Zed's `@zed-industries/claude-code-acp` (or `@agentclientprotocol/claude-agent-acp`) bridge as an [Agent Client Protocol (ACP)](https://agentclientprotocol.com) delegation agent. Clio's ACP mediator intercepts tool calls and filters them against the safety net, but gating is ultimately **advisory** as Claude governs its own runtime execution. For strict, code-enforced per-tool safety, `claude-sdk` is preferred over ACP.
 
 All Claude Code runtimes rely on the user's existing CLI authentication and store no credentials in Clio.
 
+External one-shot receipts also say what budget Clio can and cannot enforce. Clio
+controls one process launch, its wall-clock deadline, cumulative output cap,
+cancellation, and result-contract validation. Recipe per-tool calls, read reserve,
+and synthesis numbers remain in the envelope but are explicitly
+`unobserved-not-enforced`, because Antigravity owns its internal tools, network,
+prompts, and approvals. Clio schedules no automatic retry of an external
+generating agent loop.
+
 ### Autonomy enforcement grades
 
 How faithfully a runtime can honor the autonomy model is a recorded fact, not an assumption. Worker receipts carry an optional `autonomyEnforcement` block sealed into the integrity digest:
@@ -330,8 +345,8 @@ When executing tasks in headless mode through `clio-coder run`, there is no term
 
 ### Workers and delegations
 
-- **Workers** inherit the session's autonomy level, capped by dispatch scope admission. A worker ask resolves per `workers.onPermission`: `deny` continues the run with a rejection; `fail` ends it; `escalate` forwards it to the interactive operator (see the escalation section above). All three values are editable in the `/settings` center.
-- **Delegations (ACP)** under `clio-policy` governance evaluate through the same net and autonomy mapping; an ask resolves as a non-stall deny so the external agent never hangs waiting for an operator.
+- **Workers** inherit the session's autonomy level, capped by dispatch scope admission. A worker ask resolves per `fleet.permissions.mode`: `deny` continues the run with a rejection; `fail` ends it; `escalate` forwards it to the interactive operator (see the escalation section above). All three values are editable in the `/settings` center.
+- **Delegations (ACP)** under `clio-coder-policy` governance evaluate through the same net and autonomy mapping; an ask resolves as a non-stall deny so the external agent never hangs waiting for an operator.
 - **ACP server sessions** (a remote client driving Clio) snapshot the autonomy level at `session/new`, so a mid-session settings change on the host cannot alter an in-flight remote session's admission decisions.
 
 ---
@@ -348,7 +363,7 @@ It is critical to distinguish these two control axes:
 
 | Setting | Axis | Governed By | Handled In |
 | --- | --- | --- | --- |
-| **Autonomy** | Authority | `autonomy` settings dial, `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | `src/tools/registry.ts`, `src/domains/safety/` |
+| **Autonomy** | Authority | `safety.autonomy` settings dial, `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | `src/tools/registry.ts`, `src/domains/safety/` |
 | **Rigor** | Validation | `CLIO_CODER_RIGOR` override, workspace validation contracts | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract-registration.ts` |
 
 ---