The proposal survives contact with the code with three amendments, per
the RFCs-are-proposals rule. (1) A mode transition logs a
request/header-delta only when expressible: adding exit_plan_mode
resorts the canonical tool list, and a pure reordering has no delta
form, so entering plan mode logs the full fallback snapshot — the
attributability claim holds either way. (2) The proposed/ skeleton
converts to the implemented grammar: Proposal → Decision, the roadmap's
staging (now history) drops to the standing Deferred list, and
Acceptance criteria + Risks fold into Consequences (what holds, then the
accepted costs, including the ACP v2 mode-removal migration). (3) The
two recorded scenarios stay pending a with-key session, recorded in
Deferred.
The docs tail completes: the cookbook's plan-mode row upgrades from
sketch to the shipped package, architecture.md gains the ctx.modes
capability row (ceiling 1640 → 1650: a new capability service's table
row does not fit the old budget), and every reference repoints to
implemented/.
The RFC seated the exit approval on the approval seam because that was
the only asking machinery in flight when it was written. ask_user_question
has since merged (PR #108): the exit moment is a question, not a
permission — the user-interaction seam gives the review options plus a
free-text channel, so a keep-planning answer carries the user's feedback
to the model verbatim, and an approval can later grow options. The gate
no longer returns ask (that vocabulary stays free for genuine permission
gating); the tool conducts the review inside its own execution and
degrades to manual mode-toggling without a provider. The approval-seam
shape moves to Alternatives considered with the reasoning.
Consequences: the roadmap's hard prerequisite on the sandbox branch
disappears (this stack bases on master), the recorded scenarios script
elicitation answers instead of permission answers, and the ACP v2
session-mode-removal direction is recorded as an accepted migration
risk.
'validates against config' plus "'default' rejected as a key" read
together let an implementer reject set(agent, 'default'), which would
contradict the picker's default entry and block the user-driven exit
the no-answerer degrade relies on. Validation is against list()'s
vocabulary: config keys plus the reserved default.
Reorganize along Problem / Proposal / High-level API / Detailed design /
Roadmap / FAQ / Prior art / Alternatives / Acceptance / Risks. The
product survey and Pi failure shapes move to Prior art; user-facing
behavior (walkthrough, cordis.yml config, stdio, ACP, ctx.modes) gets
its own High-level API section; FAQ collects behavioral clarifications
of the chosen design, disjoint from Alternatives (rejected designs) and
Risks (accepted costs). The zh counterpart and its pairing metadata are
removed; the RFC is English-only (not in the required-pairs manifest).
Brings in the refreshed base (master merged through the stack after #203
and #205 landed), including the acp-snapshot extraction (#204), and
re-ports this PR's snapshot-suite extensions onto the extracted package:
- dsh-acp-snapshot's Scenario gains headerClass and configPath; the suite
factory pins the request header PER CLASS (construction rejects a
missing or duplicated class pin), forwards a scenario's configPath to
the harness (RunOptions.configPath overrides AgentUnderTest.configPath),
and a new fixtures meta-test asserts every pinning fixture carries
exactly one request/header and no deltas.
- The acp-agent example's thin scenario table re-registers code-mode-turn
and both-mode-turn with their overlay configs and per-class pins; the
committed fixtures replay unchanged.
- The package's synthetic suites cover the new surface (explicit
headerClass on one suite, the default on the other, a configPath
override through the fake bin, and the two construction throws).
The dsh-tools half of the Code Mode RFC (its fourth, final change): the
registry gains its first config — mode: native | code | both — and OWNS how
its tools reach the model. 'code' contributes exactly one wire tool,
run_code, plus a lazy tools:sdk prompt section declaring every other tool
as a generated TypeScript API (jsonSchemaToTs: total over the defineTool
subset, unknown degradation, lexicographic byte-identical rendering);
'both' ships both representations; 'native' is byte-for-byte the old
behavior. Non-native modes fail every assembly loudly without a
typescript-language ctx.codeRuntime.
run_code's dispatch bridge: JSON-normalizes each binding argument before
dispatch (what dispatches is what the tool/code-dispatch event logs — the
append can never fail on payload shape; BigInt/circulars reject that one
call), serializes all program tool calls through a per-run queue (even
Promise.all — no concurrency-safety metadata yet), routes every sub-call
through tools/pre-execute → tools/post-execute (a deny rejects the
program-side promise), drops sub-call additionalContext (no safe outlet
mid-run; pinned), owns a run-scoped abort that follows the outer signal in
and fires on settlement (in-flight sub-dispatch aborted, queued abandoned,
queue drained before returning), and converts a failed run into
CodeRunFailedError → a structured isError carrying kind + captured logs.
tool/code-dispatch joins SessionEventMap by declaration merging (log-only;
deriveMessages ignores it).
The composed surface: the tools config forwards through agent-core and
both app packages; examples/code-agent + demo:code run the worker runtime
under mode code (keyless boot smoke + a with-key e2e proving the collapsed
[run_code] header, the dispatch events, and the file the program wrote);
two new snapshot scenarios (code-mode-turn, both-mode-turn) record the SDK
section, collapsed header, dispatch events, and result card — each its own
header-pinning class (the harness gains per-scenario config overlays and
per-class pins). Catalogs, graphs, cookbook, hooks-bridge notes, and the
RFC (moved to implemented/, restructured to decision-era headings) updated
in the same change.
The seam's structured-clone boundary admits values JSON does not (BigInt,
Map, circulars), while tool/code-dispatch events must be JSON-appendable —
left unhandled, a sub-call could execute and then fail at logging time.
The bridge now JSON-normalizes binding arguments BEFORE dispatch (a value
that does not survive rejects that one call), so the dispatched form and
the logged form are the same JSON value by construction.
New group packages/code-runtime/ with the interface package
@deepseek-ai/dsh-code-runtime, per the Code Mode RFC: abstract CodeRuntime
service (run() resolves program failures as an error field, rejects only
for seam misuse), the CodeRunRequest/CodeBindingNamespace/CodeRunResult/
CodeLogEntry/CodeRunFailure vocabulary, and readonly language/isolation
backend descriptors. Registered in the tsconfig maps, packages/README,
architecture service map, and the doc-graph service-role classification;
catalogs regenerated.
The RFC's one forward path token to the worker package becomes an npm-name
mention until PR3 creates that directory (verify-package-paths is
drift-scoped: the now-existing group made the token checkable).
docs/architecture.md ceiling 1630 -> 1640: the doc gained a genuinely new
capability-service row; the row itself is already minimal.
Budget expiry terminated the worker but nothing cancelled an in-flight
host-side sub-dispatch, and a late dispatch could append events after
run_code returned. The bridge now owns a run-scoped AbortController
(follows exec.signal; fired on any run settlement), sub-dispatches get
the run signal, and run_code returns only after the dispatch queue
drains — no post-settlement appends, per dispose-to-quiescence.
(A1) Scope the wire-collapse guarantee honestly: systemPrompt.tools() is
a public multi-provider API, so the mode governs the registry's
contribution (the only shipped source); deliberate extra providers own
what they add, and the shipped-configuration invariant is test-pinned.
(A2) Replace pause-on-pending-RPC timeout with two independent budgets:
computeMs metered by worker.performance.eventLoopUtilization() busy time
(unfoolable by an un-awaited decoy dispatch; probe-verified) plus a
never-pausing maxWallMs ceiling.
(A3) Specify sub-call additionalContext as deliberately suppressed in
the MVP (immediate inject would break call/result adjacency; the plural
channel is named follow-up work).
(B) Orphan-process caveat vs bash-local's group kill; null-prototype
binding namespaces (__proto__/constructor names); per-PR doc artifacts
(packages/README row, architecture service map in PR2, config/tool/
persistence catalogs per owning PR); engines range corrected to
^22.19.0 || >=24.0.0.
Research finding: a SessionEventMap member is a log event — JSDoc prose
required, @mode is a hard error there, and docs/persistence-catalog.md
must be regenerated (todo/write is the log-only precedent). PR4's plan
now names both.
Own adversarial pass finding: a static inject on the registry would gate
ctx.tools (and every tool plugin) on a code runtime existing even under
mode 'native'. The RFC now names the sanctioned pattern: soft
ctx.get('codeRuntime') at use time (the agent-loop sessionPersistence
precedent) with absence failing loud in the provider thunk.
Supersedes the add-on-plugin + node:vm-stub draft in place (still proposed/):
code mode becomes a first-class ToolRegistry presentation mode
('native' | 'code' | 'both'), execution goes behind a new ctx.codeRuntime
capability seam whose shipped backend is one fresh Node worker thread per
run (type-strip, empty env, resource limits, hard terminate), at
bash-equivalent trust with no unsafe-flag ceremony. Renames the file to
2026-06-15-code-mode.md and regenerates the RFC index.
Out-of-process delegation to external coding agents as two new subagent
seam backends, exposed as subagent_claude_code / subagent_codex tools.
Verified against @anthropic-ai/claude-agent-sdk 0.3.202 and codex CLI
0.142.5 via keyless spikes; includes the dsh-subagent-process extraction
plan, isolation/permission stances, and tiered test coverage.
A folded mode name the current config no longer defines behaves as default
plus one boundary notice naming the dropped definition — set()'s loud
validation covers only the write path.
The deliverable is plan mode — retitle and reorder the proposal opener so
the feature leads and the logged session-mode state is its implementation
property. Fix the Codex citation in the boolean-planMode alternative: Codex
has plan mode (/plan); its ACP mode list carries its approval presets — two
different surfaces. Durable vocabulary (mode/set, ctx.modes, dsh-mode) stays
string-shaped so a second mode never renames logged event types.
The zh.md counterpart (section-for-section mirror per the i18n contract:
identical heading structure, byte-identical text fences, same link targets)
plus the recorded i18n.yaml and the language-switcher lines on both sides —
matching the approval / sandbox / env-state RFC practice.
Re-audited against origin: master unmoved; approval seam still on
feat/sandbox-support; three relevant branches appeared since drafting.
- env-state-visibility RFC (fold-from-log + boundary application for env
facts): adopt its boundary-narration principle for user-driven mode flips
(one coalesced notice when the flushed mode differs from the last request
header's fold; net-zero silent; tool exits self-narrate via result), and
resolve the one real collision — its config-phase sketch routes ACP
session/set_mode to env facts while this RFC claims the picker. Proposed
division: picker-to-modes / knobs-to-config-options; a mode definition may
later bundle env facts; second lander amends. Also note the source-field
contrast (env drift has no log-adjacent cause; every mode/set does).
- sandbox-escalation: first live approval composition — named as the
precedent our recorded scenarios follow.
- ask-user-question / user-interaction seam: the stdio approval answerer
rides its one-prompt-owns-stdin queue where mounted.
- Config: pin the allowlist as the degenerate form of a per-tool
allow|deny|ask map so execution-phase ask policies arrive without a
config migration (deferred on approval's allow_always).
- Dedup the ACP mapping (one home: Protocol and UI surfaces).
Adds the Detailed design block: the mode/set vocabulary (no provenance
field — cause is log-adjacent; bare-string mode names), ModeConfig with an
explicit resolve step, the cursor-cached fold + ctx.modes service with
turn/start|step/end pending flush, the computed mode:policy section (order
50) + post-next() assembly filter (exit_plan_mode visible IFF plan mode —
what keeps default-mode assemblies byte-identical), the fold-only gate with
its ask on exit_plan_mode (no dsh-approval dependency — the registry
routes), the exit tool contract and render intent, dependency edges and the
stdio/ACP surfaces, the input.json setMode op + plan-mode/plan-mode-reject
scenarios (mode set before turn 1 → the initial header snapshot is already
in plan shape; the widening delta appears at exit), and the mechanical tail.
Consistency fixes: the plan allowlist names real tools (no grep tool
exists); the re-widen risk now states the post-next() mechanism instead of
a listener-order convention.
A session mode is a named, logged, per-agent policy state: mode/set as a
log-only SessionEventMap member (todo/write shape), a foldMode over the log,
soft enforcement at system-prompt/assemble (filtered schemas + mode section,
auto-logged as request/header-delta), hard enforcement at tools/pre-execute
(deny-by-default against the mode allowlist), and a thin ctx.modes service
with turn-boundary pending-intent flush for user flips. One new product
package dsh-mode (packages/mode/mode, the approval-group shape); plan is the
only shipped definition.
Lands as ONE feature — a plan mode without a model-driven, approvable exit is
not a smaller version of the feature. The roadmap's two stages are build-and-
review order for a single stacked landing: the mode core, then exit_plan_mode
(ask-gated through the approval seam; the plan text rides the tool args as
the reviewable log artifact), the stdio readline answerer, and the ACP
session-mode surface (session/set_mode, current_mode_update, available
modes). Hard prerequisite: the approval seam lands first; the stack bases on
feat/sandbox-support meanwhile.
The compact-basic README's opening line still described summarization
as routed through the agent request pipeline — corrected to the direct
one-shot llm/stream contract the rest of the package documents. The
proposed Code Mode RFC gets a premise-stale note: it names the old
full-request agent/request seam, which now shapes call config only —
re-map onto the log channels and system-prompt/assemble before
implementing from it.
Define the in-file RFC contract in docs/rfc/README.md § The file format:
the header block (`# RFC: <title>` plus a dateless Status enum
cross-checked against the lifecycle folder), the per-lifecycle body
skeleton (a Problem opener everywhere; Proposal/Alternatives considered/
Acceptance criteria/Risks in proposed/; present-tense Decision/
Consequences with proposal-era headings banned in implemented/; the
frozen proposal shape in rejected/), and a mandatory Alternatives
considered section with a date-fenced grandfather comment for pre-format
RFCs whose alternatives are not reconstructible from the record.
Enforce it with a new doc-sync gate, scripts/verify-rfc-format.ts, and
normalize all 112 RFCs to it: ~15 Status-line spellings collapse to the
enum, 29 Context openers become Problem, the 39 legacy-format XXX debt
markers are resolved and banned from reappearing, proposal-era sections
in implemented RFCs are rewritten to shipped reality (including the
web/fs/subagent seam RFCs' migration plans and test checklists, closing
the doc-tiers deferred-work item on the web seam), every RFC gains an
Alternatives considered section or the grandfather comment, and the
bilingual pair is re-mirrored and re-recorded.
Move the generated index tables out of README.md into a fully generated
docs/rfc/INDEX.md — gen-rfc-index now writes the whole file, and
verify-rfc-classification checks its freshness and rejects index-shaped
rows in the curated README — which makes room for the format contract to
live in the README front door instead of a separate FORMAT.md.
The decision record, and the first RFC written in the new format, is
docs/rfc/implemented/process/2026-07-05-uniform-rfc-format.md.
