Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(mode): the access cap — plan mode composes with the sandbox instead of banning bash

Browse Source 
A ModeDefinition may declare access: the widest sandbox access shell
commands run under while the mode holds, on the SANDBOX_MODES ladder.
The bash seam gains the resolution point to hang it on: BashExecutor.
resolveMode(session) folds override ?? default and dispatches the new
bash/resolve-mode waterfall; dsh-tool-bash consults it at both the
stamping site and the escalation baseline; dsh-mode's clamp listener
takes the ladder minimum per call. Two independent log folds compose at
read time — the mode never writes the sandbox knob, so the two switch
in any order and the knob re-emerges intact on exit.

The built-in plan definition ships access: read-only with the bash trio
allowlisted CONDITIONALLY: both policy layers admit bash/bash_output/
bash_kill only while a confining executor is mounted (an unconfinable
shell cannot honor the cap), and a bash call carrying sandbox_permissions
under a cap is denied at the gate — no widening mid-mode; the widened
step belongs in the plan.

examples/plan-acp-agent swaps bash-local for sandbox-local +
bash-sandbox (workspace-write default, clamped read-only inside plan)
plus the approval seam; the re-recorded plan-mode arc runs a real cat
inside plan under the clamped sandbox, and modes-advertise now pins the
sandbox-mode and approval config options. RFC amended to the landed
shape (access cap section, orthogonality FAQ, deferred item resolved
into effects self-declaration).
This commit is contained in:
kingwl
2026-07-12 22:51:09 +08:00
parent 88db403d9f
commit 99650a201b
31 changed files with 1844 additions and 1237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/config-catalog.md
View File

@@ -457,18 +457,29 @@ export interface ModeConfig {
}
/**
* One mode's deployment-configured policy: the guidance section the model sees
* and the allowlist of tool names that stay visible and executable.
* One mode's deployment-configured policy: the guidance section the model sees,
* the allowlist of tool names that stay visible and executable, and an
* optional cap on the sandbox access shell commands run under.
*/
export interface ModeDefinition {
/** Guidance text rendered as the `mode:policy` prompt section while the mode is in force. */
section: string
/** Allowlist of tool NAMES; names may reference not-yet-registered tools (registration is dynamic). */
tools: string[]
/**
* The widest sandbox access shell commands may run under while this mode is
* in force — a per-call CAP on the bash seam's resolved mode (a
* `bash/resolve-mode` clamp), not a switch: the session's own sandbox knob
* keeps its setting and re-emerges intact when the mode ends. Omitted, the
* mode leaves the resolution alone. A mode with `access` set exposes the
* bash tools only while a confining executor is mounted (an unconfinable
* shell cannot honor the cap) and denies sandbox escalation outright.
*/
access?: (typeof SANDBOX_MODES)[number]
}
```
Source: [`packages/mode/mode/src/index.ts:96`](../packages/mode/mode/src/index.ts)
Source: [`packages/mode/mode/src/index.ts:115`](../packages/mode/mode/src/index.ts)
## `@deepseek-ai/dsh-repeat-tool-guard`

14
docs/cordis-catalog/events.md
View File

@@ -177,6 +177,20 @@ Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalReques
Source: [`packages/ui/user-approval/src/index.ts:64`](../../packages/ui/user-approval/src/index.ts)
## `bash/*`
### `bash/resolve-mode` — waterfall
Waterfall around BashExecutor.resolveMode's base — the session's standing override falling back to the executor's configured default. A policy plugin narrows the resolution per call by clamping `await next()` (a session mode's `access` cap is the shipped example); returning without `next()` replaces the resolution outright. Dispatched only for a confining executor — a never-confining one resolves `undefined` without consulting listeners, so a listener always receives a real base mode from `next()`.
```ts cordis-catalog
'bash/resolve-mode'(this: BashExecutor, session: Session | undefined, next: () => Promise<SandboxMode>): Promise<SandboxMode>
```
Types: [SandboxMode](../core-data-structures/sandbox.md)
Source: [`packages/bash/bash/src/index.ts:57`](../../packages/bash/bash/src/index.ts)
## `fs/*`
### `fs/edit-intent` — waterfall

7
docs/cordis-catalog/services.md
View File

@@ -66,6 +66,7 @@ Semantics every implementation must honor:
- Disposal kills every running task and awaits their exit (no orphan processes survive `fiber.dispose()`).
```ts cordis-catalog
async resolveMode(session: Session | undefined): Promise<SandboxMode | undefined>
abstract resolve(request: BashExecRequest): BashExecSpec
abstract run(spec: BashExecSpec): Promise<BashRunResult>
abstract start(spec: BashExecSpec): BashTask
@@ -77,9 +78,9 @@ abstract kill(id: BashTaskId): boolean
onTaskDone(listener: BashTaskListener): () => void
```
Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) · [BashTask](../core-data-structures/bash.md) · [BashTaskRead](../core-data-structures/bash.md)
Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) · [BashTask](../core-data-structures/bash.md) · [BashTaskRead](../core-data-structures/bash.md) · [SandboxMode](../core-data-structures/sandbox.md)
Source: [`packages/bash/bash/src/index.ts:62`](../../packages/bash/bash/src/index.ts)
Source: [`packages/bash/bash/src/index.ts:82`](../../packages/bash/bash/src/index.ts)
## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
@@ -173,7 +174,7 @@ set(agent: Agent, mode: string): void
Types: [Agent](../core-data-structures/core.md)
Source: [`packages/mode/mode/src/index.ts:210`](../../packages/mode/mode/src/index.ts)
Source: [`packages/mode/mode/src/index.ts:255`](../../packages/mode/mode/src/index.ts)
## `ctx.sandbox` — `SandboxProvider` (abstract seam)

1
docs/event-producer-consumer.md
View File

@@ -20,6 +20,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:451`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:464`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
| `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:64`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) |
| `bash/resolve-mode` | `waterfall` | [`packages/bash/bash/src/index.ts:57`](../packages/bash/bash/src/index.ts) | [`bash`](../packages/bash/bash) (`waterfall`) | [`mode`](../packages/mode/mode) |
| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |

3
docs/module-graph.md
View File

@@ -219,6 +219,7 @@ flowchart TD
pkg_tool_todo --> pkg_session
pkg_tool_todo --> pkg_tools
pkg_mode --> pkg_agent
pkg_mode --> pkg_bash
pkg_mode --> pkg_session
pkg_mode --> pkg_system_prompt
pkg_mode --> pkg_tools
@@ -363,7 +364,7 @@ flowchart TD
| [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
| [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
| [`mode`](../packages/mode/mode) | `mode` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
| [`mode`](../packages/mode/mode) | `mode` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
| [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`tools`](../packages/core/tools) |
| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |

4
docs/persistence-catalog.md
View File

@@ -81,7 +81,7 @@ The session's sandbox mode was switched — log-only (like `approval/*`; NOT a s
'bash/sandbox-mode': { mode: SandboxMode }
```
Source: [`packages/bash/bash/src/session-mode.ts:31`](../packages/bash/bash/src/session-mode.ts)
Source: [`packages/bash/bash/src/session-mode.ts:34`](../packages/bash/bash/src/session-mode.ts)
### `compact/*`
@@ -163,7 +163,7 @@ The session mode in force from this point on: log-only, non-surface, whole-value
'mode/set': { mode: string }
```
Source: [`packages/mode/mode/src/index.ts:41`](../packages/mode/mode/src/index.ts)
Source: [`packages/mode/mode/src/index.ts:49`](../packages/mode/mode/src/index.ts)
### `prompt/*`

37
docs/rfc/implemented/feature/2026-07-07-plan-mode.md
View File

@@ -24,7 +24,7 @@ The model leaves plan mode through the **`exit_plan_mode`** tool: its single arg
The user switches the session to plan mode — the ACP mode picker or the stdio `/mode plan` — and from the next turn every request ships the filtered read-only toolset plus the plan-mode guidance section.
The model explores and designs with what remains; if it attempts a write anyway, the gate denies with a reason naming the mode and pointing at `exit_plan_mode`, and the transcript keeps planning.
The model explores and designs with what remains — the bash tools included when the composition confines them: plan mode's `access: read-only` cap clamps every command to a read-only sandbox, so exploration runs for real; if the model attempts a write anyway, the gate denies with a reason naming the mode and pointing at `exit_plan_mode`, and the transcript keeps planning.
When ready, the model calls `exit_plan_mode` with the plan markdown as its argument; the UI renders the plan as the call card and the review question arrives through the user-interaction channel — approve, or keep planning, with free-text feedback welcome — so what the human reviews is exactly the logged artifact.
@@ -43,10 +43,11 @@ Mode definitions are validated plugin Config — per repo convention, changeable
section: |
You are in plan mode: explore and design, then present the
plan for approval through exit_plan_mode.
tools: [read, todo_write, web_search, web_fetch, ask_user_question, structured_output, exit_plan_mode]
tools: [read, todo_write, web_search, web_fetch, ask_user_question, structured_output, bash, bash_output, bash_kill, exit_plan_mode]
access: read-only
```
`plan`'s shipped default allowlist is the read-only surface (`read`, `todo_write`, `web_search`/`web_fetch`, `ask_user_question`, `structured_output`, `exit_plan_mode` — the last three are the pure ask/report class) with `bash` and `subagent` excluded until the sandbox family can actually confine them — a deployment that accepts the risk widens its own config today. `default` is reserved (the absence of policy) and rejected as a key; an unknown mode name fails validation loudly at `set()` time.
`plan`'s shipped default allowlist is the read-only surface: `read`, `todo_write`, `web_search`/`web_fetch`, `ask_user_question`, `structured_output`, `exit_plan_mode` (the last three are the pure ask/report class), plus the bash trio under the `access: read-only` cap — CONDITIONAL on a confining executor ([the access cap](#the-access-cap-clamping-the-bash-resolution)); `subagent` stays excluded until mode inheritance lands. `default` is reserved (the absence of policy) and rejected as a key; an `access` outside the `SANDBOX_MODES` ladder fails validation at load; an unknown mode name fails loudly at `set()` time.
### In the terminal
@@ -75,10 +76,13 @@ The payload carries no reason/provenance field: a tool-driven flip sits next to
### Config and the resolve step
```text
interface ModeDefinition { section: string; tools: string[] } // prompt text; allowlist of tool NAMES
interface ModeDefinition { section: string; tools: string[]; access?: SandboxMode }
// prompt text; allowlist of tool NAMES; optional cap on the
// sandbox access shell commands run under while the mode holds
interface ModeConfig { modes?: Record<string, ModeDefinition> } // plan's built-in definition merged unless overridden
resolveConfig(config): ResolvedModes // explicit resolve (the dsh-bash template), fail-loud:
// 'default' as a key rejected; allowlists may name
// 'default' as a key rejected; access validated against
// the SANDBOX_MODES ladder; allowlists may name
// not-yet-registered tools (registration is dynamic)
```
@@ -111,6 +115,14 @@ tools/pre-execute: no exec.agent → next() // agent-less calls have no
The gate folds the LOGGED mode only, never the pending intent — enforcement judges by the same state the request's header shipped under. The gate never returns `{ kind: 'ask' }`: the exit review is a question with options and feedback, not a permission, so it lives inside the tool's own execution over the user-interaction seam and the registry's `ask` vocabulary stays free for genuine permission gating. A call to `exit_plan_mode` outside plan mode reaches the tool only from the default mode (any other mode's allowlist excludes it), and the tool's own folded-mode recheck rejects it there.
### The access cap: clamping the bash resolution
A definition's `access` is the widest sandbox access shell commands run under while the mode is in force — the `SANDBOX_MODES` ladder from `dsh-bash` (`read-only` | `workspace-write` | `danger-full-access`); the built-in `plan` ships `access: 'read-only'`. The cap is made real on the bash seam's own resolution point: `BashExecutor.resolveMode(session)` computes `session override ?? executor default` and dispatches it through the **`bash/resolve-mode` waterfall** (declared in `dsh-bash`; consulted by `dsh-tool-bash` at both its stamping site and its escalation baseline), and `dsh-mode` registers the clamp listener — `min(await next(), access)` on the ladder, per call.
The composition is read-time over two independent log folds. The session's sandbox knob (`bash/sandbox-mode` events, the sandbox RFC) is never written by the mode: a knob flipped during plan stays logged but capped, exiting plan uncovers it unchanged, the two switch in any order without interference, and there is no restore step for a crash to strand. Attribution stays log-adjacent on both axes — a clamped call's width is explained by the standing `mode/set`, a knob change by its own `bash/sandbox-mode` event.
Two rules ride with a declared cap. The bash trio (`bash`/`bash_output`/`bash_kill`) is CONDITIONAL: both policy layers admit it only while a confining executor is mounted (`ctx.get('bash')?.sandboxMode` set) — an unconfinable shell cannot honor the cap, so under `dsh-bash-local` the trio is hidden by the filter and denied by the gate exactly like a non-allowlisted tool. And sandbox ESCALATION is denied at the gate: a `bash` call carrying `sandbox_permissions` in a capped mode gets a deny that points the model at putting the widened step in the plan — without this rule the clamped resolution would read as a legitimate escalation baseline and one approval prompt could pierce the cap mid-mode. A mode that allowlists `bash` WITHOUT `access` is the deployment's explicit uncapped choice; neither rule applies.
### `exit_plan_mode`
`defineTool` with one required `plan: string` argument — the plan is thereby a durable, replayable log artifact riding the ordinary `tool/call` event. `execute` rejects an agent-less call (the [`todo_write` precedent](../../implemented/feature/2026-06-29-todo-write-tool.md)), re-checks the folded mode as defense in depth, then conducts the review: one single-select `ctx.userInteraction.ask()` question — approve, or keep planning — with the free-text channel open for feedback. Approve records the switch back to `default` as a SILENT boundary-applied pending intent (flushed at this step's end, still in-turn) and returns a short confirmation; the gate therefore stays plan-mode for every remaining call of the SAME assistant response — a same-batch `exit_plan_mode` + `write` pair cannot smuggle the write past a request assembled under the plan header — and the next step's assembly restores the full toolset and logs the widening header event. Every other outcome — keep-planning (the user's feedback text carried verbatim), an aborted question, a missing provider — returns the corrective `isError` that tells the model to revise and re-present, and the mode stays `plan`.
@@ -119,19 +131,19 @@ Its [render intent](../../implemented/architecture/2026-07-02-tool-render-intent
### Dependencies and surfaces
`dsh-mode` is one product package, not a capability-seam trio ([Alternatives considered](#alternatives-considered)): it peers on `cordis`, `dsh-session`, `dsh-agent`, `dsh-tools`, `dsh-system-prompt` (manifest shape mirrors `dsh-tool-todo`), injects `['tools', 'systemPrompt']`, reads `ctx.userInteraction` opportunistically at execute time (a type-only peer edge on `dsh-user-interaction`), and depends on no UI package. Beyond the `ctx.modes` call surface everything participates through listeners, so dropping the package gracefully removes modes rather than breaking a consumer. The stdio app adds a `/mode [name]` line-handler branch — the exit review needs nothing there, because the stdio user-interaction provider already owns the prompt queue. The ACP wire mapping is pinned in [High-level API](#over-acp); package-wise the bridge takes a type-only peer edge on `dsh-mode` and reads the service opportunistically, so a bridge without the plugin behaves exactly as today.
`dsh-mode` is one product package, not a capability-seam trio ([Alternatives considered](#alternatives-considered)): it peers on `cordis`, `dsh-session`, `dsh-agent`, `dsh-tools`, `dsh-system-prompt`, and `dsh-bash` (the `SANDBOX_MODES` vocabulary and the `bash/resolve-mode` clamp listener; the executor itself is read opportunistically via `ctx.get('bash')`, so the composition works without one), injects `['tools', 'systemPrompt']`, reads `ctx.userInteraction` opportunistically at execute time (a type-only peer edge on `dsh-user-interaction`), and depends on no UI package. Beyond the `ctx.modes` call surface everything participates through listeners, so dropping the package gracefully removes modes rather than breaking a consumer. The stdio app adds a `/mode [name]` line-handler branch — the exit review needs nothing there, because the stdio user-interaction provider already owns the prompt queue. The ACP wire mapping is pinned in [High-level API](#over-acp); package-wise the bridge takes a type-only peer edge on `dsh-mode` and reads the service opportunistically, so a bridge without the plugin behaves exactly as today.
### The recorded scenario and the harness op
`input.json` gains one step op, `{ "op": "setMode", "modeId": "plan" }`, driven through the real `session/set_mode` RPC, and a scripted `elicitationAnswers` queue (FIFO, consumed by the harness client's elicitation callback — the review question's answer). The `plan-mode` scenario: initialize → newSession → setMode(plan) → a prompt that explores and attempts a `write` (denied by the gate, pinned verbatim) → the model presents the plan via `exit_plan_mode` → a scripted approve → a follow-up prompt that writes for real. Because the mode is set before turn 1, the FIRST `request/header` snapshot is already in plan shape (filtered tools + section, reason `initial`) — the widening header event appears at the exit; the scenario pins both, plus the `mode/set` pair. A sibling `plan-mode-reject` scenario scripts the keep-planning answer with feedback text and pins the corrective result. Both need a with-key recording session; the deny/reject texts are meanwhile pinned at the unit tier.
`input.json` gains one step op, `{ "op": "setMode", "modeId": "plan" }`, driven through the real `session/set_mode` RPC, and a scripted `elicitationAnswers` queue (FIFO, consumed by the harness client's elicitation callback — the review question's answer). The `plan-mode` scenario: initialize → newSession → setMode(plan) → a prompt the model answers by running a real `cat` through the bash tool INSIDE plan (executed under the clamped read-only sandbox on replay — Seatbelt on macOS, bwrap on Linux CI) and presenting the plan via `exit_plan_mode` → a scripted approve → the same turn's next step writes for real under the restored toolset. Because the mode is set before turn 1, the FIRST `request/header` snapshot is already in plan shape (filtered tools + section, reason `initial`) — the widening header event appears at the exit; the scenario pins both, plus the `mode/set` pair. A sibling `plan-mode-reject` scenario scripts the keep-planning answer with feedback text and pins the corrective result. Both need a with-key recording session; the deny/reject texts — and the sandbox-denial marker, whose recorded stderr would be the backend's dialect and replay only where it was recorded — are pinned at the unit tier.
### The mechanical tail
No new cordis event is declared (`mode/set` rides `session/event`; the listeners attach to existing waterfalls), so the events catalog is untouched; regenerated in the same change: the persistence log catalog (`mode/set`), the services catalog (`ctx.modes`, JSDoc-complete), the config catalog (`ModeConfig`), the tool catalog (`exit_plan_mode`), the producer/consumer map and doc graphs, and the module graph. Repo plumbing: a root tsconfig `paths` entry, the new group's README plus a [packages map](../../../../packages/README.md) row (a new top-level group is the deliberate act that table names), an `architecture.md` capability-services row for `ctx.modes` (budget-checked), and the cookbook row upgrade.
No new cordis event is declared IN `dsh-mode` (`mode/set` rides `session/event`; the policy listeners attach to existing waterfalls) — the one new event, the `bash/resolve-mode` waterfall the access cap clamps, lives in `dsh-bash` where the resolution it wraps lives. Regenerated in the same change: the events catalog (`bash/resolve-mode`), the persistence log catalog (`mode/set`), the services catalog (`ctx.modes`, JSDoc-complete), the config catalog (`ModeConfig`), the tool catalog (`exit_plan_mode`), the producer/consumer map and doc graphs, and the module graph. Repo plumbing: a root tsconfig `paths` entry, the new group's README plus a [packages map](../../../../packages/README.md) row (a new top-level group is the deliberate act that table names), an `architecture.md` capability-services row for `ctx.modes` (budget-checked), and the cookbook row upgrade.
## Deferred
Each behind its own decision: subagent mode inheritance via a forwarded `AgentOptions.mode` (the option field itself ships), per-tool `ask` policies inside mode definitions (an OpenCode-style "bash asks in plan mode"), preset modes beyond `plan` (read-only, accept-edits), sandbox-backed bash confinement in plan mode, and the idle-record primitive if pending-intent loss proves real.
Each behind its own decision: subagent mode inheritance via a forwarded `AgentOptions.mode` (the option field itself ships), per-tool `ask` policies inside mode definitions (an OpenCode-style "bash asks in plan mode"), preset modes beyond `plan` (read-only, accept-edits), effects self-declaration on tool definitions (so the conditional-tool rule generalizes past the hardcoded bash trio — the MCP `ToolAnnotations` vocabulary is the natural template), and the idle-record primitive if pending-intent loss proves real.
The recorded snapshot scenarios are landed: `plan-mode` (the pinned-header arc — plan-shaped initial header, scripted elicitation approve, the boundary-flushed flip and widened fallback header, a real edit) and `plan-mode-reject` (keep-planning feedback carried verbatim in the corrective `isError`), beside the keyless `modes-advertise` wire golden. The gate's deny path stays pinned at the unit tier — the recorded model never calls a filtered tool, which is the behavior the soft layer exists to produce.
@@ -149,6 +161,8 @@ Behavioral clarifications of the chosen design; rejected designs live in [Altern
**Do subagents inherit the parent's mode?** A fork child inherits for free — the parent's `mode/set` is inside the seeded prefix. A spawn child starts in the default mode unless its creator seeds `AgentOptions.mode`; automatic forwarding by subagent providers is deferred ([Deferred](#deferred)).
**How does plan mode's read-only relate to the sandbox knob's read-only?** They are two independent folds over the same log with different owners: the knob (`bash/sandbox-mode`, [the sandbox RFC](2026-07-06-sandbox.md)) is the session's standing choice, the mode's `access` is a cap that rides the mode — and the cap is a clamp, never a write. `resolveMode` folds `override ?? default` and the clamp takes the ladder minimum at read time, per call, so the two switch in any order without interference: a knob flipped during plan stays logged but capped, exiting plan uncovers it unchanged, and there is no restore step for a crash to strand. The log attributes each axis to its own event — a clamped call's width to the standing `mode/set`, a knob change to its `bash/sandbox-mode` event.
**Why aren't sandbox mode, approval policy, or the model themselves modes?** They are individual environment knobs and belong to ACP's `session/set_config_option`; the division this proposal pins is picker-to-modes / knobs-to-config-options. The in-flight sandbox branch already ships both knobs as config-option selects and its feature-matrix stance records session modes as deliberately unmodeled — the one overlap between the two stacks; landing the picker supersedes that stance, and whichever side lands second amends the matrix rows. A mode definition may later bundle env facts (applied through `ctx.envState` where mounted) so a Codex-style preset stays a single mode; fusing approval policy into the mode CONCEPT itself is rejected in [Alternatives considered](#alternatives-considered).
## Prior art
@@ -191,8 +205,9 @@ What holds now, pinned by the unit, protocol, and snapshot tiers:
- A user-driven flip narrates exactly once at the next boundary and a net-zero flip sequence narrates nothing; a tool-driven exit narrates only through its tool result.
- In the default mode the plugin is invisible: assemblies are byte-identical with and without `dsh-mode` loaded, and every pre-existing snapshot golden is unchanged.
- In plan mode the filtered schemas and mode section reach both the wire request and the logged header; a call to a registered-but-filtered mutating tool is denied at `tools/pre-execute` with the mode-naming reason.
- Mode definitions (allowlist, section text) are changeable from `cordis.yml` with no code edit; an unknown mode name fails validation loudly at `set()` time.
- Under a confining executor the bash trio stays available in plan mode with every call's sandbox resolution clamped to `read-only` (the `bash/resolve-mode` waterfall); the session's sandbox knob is never written by the mode and re-emerges intact on exit; a `sandbox_permissions` escalation inside a capped mode is denied at the gate. Without a confining executor the trio is hidden and denied.
- Mode definitions (allowlist, section text, `access` cap) are changeable from `cordis.yml` with no code edit; an unknown mode name fails validation loudly at `set()` time.
- `exit_plan_mode`'s approve path flips the mode and restores the full toolset on the next step; the keep-planning path returns the corrective `isError` carrying the user's feedback and stays in plan mode; the ACP `session/set_mode` round-trip updates `current_mode_update`, and the exit review prompts through each surface's user-interaction provider.
- The docs tail shipped with the landing: READMEs, regenerated catalogs (persistence log, config, cordis services, tools), the packages map and architecture rows, and the cookbook row.
The accepted costs: a pending user flip set while idle is lost if the process dies before the next turn (the UI re-applies; the idle-record primitive is the escape hatch if this bites in practice). Every mode transition is a logged header change and therefore a prefix-cache reset at the provider — inherent, visible in per-step usage, and an argument against mode-flapping UIs, not against the design. The mode filter prepends, so only a listener that ALSO prepends after `dsh-mode` loads can wrap outside it and re-widen filtered schemas — the one shipped instance is the structured runtime's per-spawn final-assembly wrapper, whose `structured_output` is on the plan allowlist precisely so the filter, that wrapper, and the gate agree; for any future such listener the hard gate keeps a re-widened tool non-executable, and the residual cost is cosmetic (the model sees a tool it cannot use), accepted rather than mechanized. Plan mode's shipped allowlist excludes `bash` and `subagent`, which costs real exploration power until the sandbox family and mode inheritance land — a deployment that accepts the risk can widen its own config today. Two in-flight stacks touch the ACP mode surface (this one and the sandbox branch's config options, whose feature-matrix stance records session modes as deliberately unmodeled): the picker-to-modes / knobs-to-config-options division pinned in the [FAQ](#faq) is the contract, and the sandbox branch owes its matrix rows an amendment on merge-down. The ACP spec's draft v2 direction reportedly slates session modes for removal in favor of config options; if that lands, the picker migrates to a config-option select mechanically — the mode state and both enforcement layers are wire-agnostic — accepted.
The accepted costs: a pending user flip set while idle is lost if the process dies before the next turn (the UI re-applies; the idle-record primitive is the escape hatch if this bites in practice). Every mode transition is a logged header change and therefore a prefix-cache reset at the provider — inherent, visible in per-step usage, and an argument against mode-flapping UIs, not against the design. The mode filter prepends, so only a listener that ALSO prepends after `dsh-mode` loads can wrap outside it and re-widen filtered schemas — the one shipped instance is the structured runtime's per-spawn final-assembly wrapper, whose `structured_output` is on the plan allowlist precisely so the filter, that wrapper, and the gate agree; for any future such listener the hard gate keeps a re-widened tool non-executable, and the residual cost is cosmetic (the model sees a tool it cannot use), accepted rather than mechanized. Plan mode's bash power is exactly as real as the composition: under `dsh-bash-local` (or no executor) the trio is withheld in plan — hidden and denied, because an unhonorable cap must not be offered — and `subagent` stays excluded until mode inheritance lands; a deployment that accepts the risk can still define an uncapped mode that allowlists bash. The conditional-trio rule names the three bash tools rather than deriving them from tool metadata — the generalization is the effects self-declaration item in [Deferred](#deferred). The ACP mode surface carries both this stack's picker and the sandbox stack's config options under the picker-to-modes / knobs-to-config-options division pinned in the [FAQ](#faq), recorded in [the feature matrix](../../../../packages/ui/acp/acp-feature-support.md). The ACP spec's draft v2 direction reportedly slates session modes for removal in favor of config options; if that lands, the picker migrates to a config-option select mechanically — the mode state and both enforcement layers are wire-agnostic — accepted.