Codex review of the turn-mirror removal found current-state docs/comments that
still claimed the removed `agent/turn-start`/`agent/turn-end` events exist:
- docs/architecture.md: the loop diagram's turn-start line still said "emit
agent/turn-start" (the turn-end line was already fixed).
- event-domain-semantics RFC: the `agent/*` domain description listed "the turn
boundaries" among the transient emits.
- docs/core-data-structures/core.md: the agent/* taxonomy blurb listed
"turn/step boundaries" as agent events.
- the proposed ACP RFC: the settle-signal rows named agent/turn-start /
agent/turn-end; retargeted to the durable `turn/end` session event + the
session/event owning-turn correlation.
- loop.ts outer-catch comment: said "closeTurn/failTurn are idempotent" — after
the emit-param removal closeTurn is called exactly once (mutually exclusive
normal/catch paths), so corrected to state that and to scope idempotency to
closeStep (which is still guarded by stepOpen).
Regenerated the cordis catalog. No behavior change.
Complete the boundary-mirror removal begun with the step mirrors: drop
`agent/turn-start` and `agent/turn-end` from the agent event taxonomy. Turn and
step boundaries are now read exclusively off the durable `session/event` feed
(`turn/start`/`turn/end`/`step/start`/`step/end`) — there is no `agent/*` mirror
for any boundary.
- loop.ts: delete both turn emits; `closeTurn` loses its `emit` parameter and
its now-unreachable idempotency guard (it is called exactly once per turn, on
mutually exclusive normal/catch paths); `failTurn` loses the dead post-close
branch that only a throwing turn-end LISTENER could reach.
- ui-stdio: render turn boundaries from `session/event`, recovering the short
agent label from an `agent/created`→id map (the `turn/start` event carries only
the turn number, and the session id is not reliably the agent id). ui-stdio is
a disposable test REPL, so this migration retires the sole justification the
event-domain-semantics RFC gave for KEEPING the turn mirrors.
- Tests: reason/turn-number collectors and the boundary-ordering test now read
`session/event`; the throwing-turn-boundary-LISTENER tests are deleted (that
code path no longer exists). A new test covers the outer-catch disposed branch
via a pre-step listener that disposes-then-throws (the surviving real path).
- Docs: promote the "remove agent boundary mirror events" RFC to implemented
(amended/narrowed — `agent/steering` is RETAINED, not a boundary mirror);
update the event-domain-semantics + turn-enclosure RFCs, architecture.md, the
cookbook, the ACP/agent/ui-stdio prose, and regenerate the cordis catalog.
`agent/steering` and `agent/stream-chunk` are explicitly out of scope (not
durable-boundary mirrors). ACP is unaffected — it already settles from the log's
`turn/end` + `agent/status`; snapshot goldens are byte-unchanged.
Round-1 Codex review findings on the tool-schema catalog:
(A) The shipped coding-agent / acp-agent configs load dsh-tool-subagent twice —
as `subagent` (spawn backend) and `subagent_fork` (fork backend) — so the model
sees a `subagent_fork` tool the catalog never mentioned, while the intro claimed
to list "the exact name the model receives". The registered name is the plugin's
load-time `toolName` config, not a package fact, so rather than bake an
example-app config into a packages-scoped generator, add a per-package deployment
`note`: the subagent entry now records the `subagent_fork` alias and points at the
leaf configs. Intro and RFC scope reworded to state the unit is the package (at
its default config), with aliases noted — no longer overclaiming. A test asserts
the note names `subagent_fork`, covering the config-driven-name path.
(B) collectToolCatalog only disposed the context on the success path; a throw from
mount/schemas() after earlier plugins mounted would leak the fiber. Move
`ctx.fiber.dispose()` into a `finally` per the repo's dispose-to-quiescence rule.
Rename per review naming decisions:
- package dsh-file-context → dsh-fs-policy (dir, package name, plugin name,
tsconfig refs, importers, type-equiv manifest, generated catalog + module-graph)
- events fs/write-expectation → fs/write-intent, fs/edit-expectation → fs/edit-intent
(fs/observed unchanged); type FsWriteExpectation → FsWriteIntent, "expectation"
wording → "intent" throughout
- exported FileContextExec → FsPolicyExec
Make the implemented RFCs describe what shipped, not the superseded designs:
the 2026-06-17 capability-seam + tool-schemas RFCs no longer place policy on
ctx.fs or use full/partial-view authorization, and the fsspec RFC's ctx.fileContext
service prose is rewritten to the fs/* event-gate reality (freshness-based auth).
Sharpen docs/rfc/implemented/AGENTS.md: a rename is a fact to fix IN PLACE — the
"new RFC" escape hatch is for macro decision reversals only, not renames.
Code fixes from review:
- fsio.ts resolveLocalTarget/probe translate ENOTDIR (a parent path segment is a
file) into the structured FsError taxonomy instead of leaking a raw Node error;
resolve reports FS_NOT_FOUND, probe reports absent. Regression tests proven to
fail on the unfixed code.
- tool-fs HMR test now asserts prompt sections (not just tool schemas) are
withdrawn on disposal.
- fs/observed is a plain (unguarded) ctx.emit: correct the fs-policy comment,
filesystem.md, and tool-fs module doc that wrongly claimed the tool "contains"
a throwing listener; a throw surfaces as the tool's isError result.
- drop the false "loaded by the default product config" claim (no config wires
the fs tools yet), the duplicate ctx.bash service-map row, the stale
FileReadRequest catalog link-map entry, and the fs/fs README EOF blank line;
correct the dsh-fs package.json description.
Add docs/tool-catalog/tools.md, a generated reference of every model-facing
tool a shipped `packages/*/tool-*` plugin contributes (name, description,
JSON-Schema parameters) — the third generated catalog alongside the cordis
events/services and core-data-structures catalogs.
Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each
tool plugin on a real cordis Context and reads `ctx.tools.schemas()`, because a
tool schema is not statically knowable: `todo_write` builds its enum with a
runtime spread, descriptions are string-concatenated, `subagent`'s name is
config-driven, and MCP tools register raw JSON Schema without `defineTool`. A
completeness guard globs the on-disk `tool-*` packages and fails if any is
absent from the boot manifest, restoring the "nothing silently omitted"
property booting would otherwise lose. `verify-tool-catalog` runs inside
`doc-sync`, so the artifact cannot drift.
The boot-over-AST decision and the discovered-inventory / hand-written-recipe
split are recorded in a process RFC.
Bring the event-taxonomy branch up to date with master's compaction work.
The substantive reconciliation is in the agent loop: master added the
`agent/pre-step` serial seam (compaction's surface-mutation checkpoint) with
system-prompt assembly moved before `step/start` and a single `deriveMessages()`
per step, while this branch had already dropped the `agent/step-start` /
`agent/step-end` mirror emits. Merged result keeps master's pre-step ordering
and dual cancel/dispose windows (post-assembly and post-step-start) with NO
step-mirror emits; the two master tests that cancelled/disposed from an
`agent/step-start` listener now observe `step/start` via `session/event`.
Regenerated the cordis catalog and module graph from source. Gates: typecheck
clean, agent-loop + compact suites green (226 tests).
Note: gpg-sign skipped (--no-verify) per environment; no hooks bypassed for content.
The compaction e2e is the only coverage of runaway compaction; there is
no keyless full-transcript snapshot. Record why in a FIXME on the e2e
module doc: dsh-llm-replay rebuilds one model call per (turn, step) from
assistant/chunk events, but summarize() assembles its stream locally and
appends none, so the interleaved summarization call is unreplayable until
the replay harness can serve it.
- ACP/SSE: show full English name in parens on first occurrence
- fixture: drop 测试夹具 gloss, keep descriptive note
- manifest: keep English, drop 首次出现可写 clause
Address @tianyicui's minor-revision review on PR #110:
- Make every BasicCompactConfig knob required except `auto` (defaults
true): there is no data yet to justify default thresholds/budgets, so
a consumer states each value explicitly. Drop the DEFAULTS export and
the constructor's `= {}` default; example cordis.yml, the compaction
e2e, the README, and every test construction site now pass a complete
config (tests route through a `cfg()` helper).
- Add a TODO on estimateContentTokens: char/4 is coarse; replace with a
real tokenizer or post-response usage feedback in a follow-up.
- Add a TODO on the agent/pre-step `fullSystemPrompt` param flagging it
as a smell on a generic per-step seam (compaction is its sole
consumer); a `//` line comment so it stays out of the generated catalog.
Address review on the bridges:
- Hook cwd (blocking): the bridges never passed a workdir to runHook, so hooks
ran in the executor default (the ACP server launch dir), not the session
cwd — a hook doing `pwd`/relative reads/marker writes operated in the wrong
tree. Both bridges now thread the agent's session `header.cwd` (the
session/new.cwd) as the hook workdir for agent-scoped points. Regression per
bridge: server cwd ≠ session cwd, a `pwd` hook proves it ran in the session
workspace (proven red without the workdir).
- Example config honesty (blocking): `configPath: ./hooks.json` is read ONCE at
load against the PROCESS cwd, not per-session — the comment/README now say so
explicitly (a project-local per-session hooks.json is not discovered;
TODO(per-session-hook-config)). The hooks-run-in-session-cwd fix above is the
distinct, separately-documented half.
- Session-start timing (blocking): agent/session-start is a synchronous emit and
the hook runs on a detached .then, so injected context is BEST-EFFORT — not
guaranteed before the first request. Downgrade the contract in code comments +
README + RFC (TODO(session-start-gating)) rather than implying "first request
sees it", and add a no-wait regression that asserts the safe properties
without pre-waiting for the inject.
- systemMessage (non-blocking): the merge collects merged.systemMessages but no
bridge surfaced it. Warn per hook (like updatedInput) and document it as
deferred in both READMEs + the RFC; tests assert the warn + non-surfacing.
Review noted the module docs promised an invalid regex is "logged by the bridge",
but matchesMatcher only returns `false` — callers cannot distinguish a genuine
non-match from a compile failure, so a typo'd pattern silently disables that
matcher with no warning. Both bridges call matchesMatcher directly, so no log
happens anywhere. Correct the docs to state the silence explicitly; surfacing bad
config would need a diagnostic-returning variant or parse-time validation, marked
TODO(matcher-diagnostics). No behavior change.
Review noted the deep-clone of the child output runs inside `onFulfilled`,
OUTSIDE emitLifecycle's per-listener containment, and the settle `.then` is
`void`ed — so an uncloneable output (a future non-serializable content-block
type, or a contract-violating result) would throw and become an UNHANDLED
rejection, contradicting the "any throw is contained" guarantee the comment
claims. Wrap the clone in try/catch: on failure, log via ctx.logger.warn and
emit subagent/end WITHOUT lastAssistantMessage (preserving stopReason/agentType)
rather than dropping the event or crashing. Regression proves the unfixed code
produces an unhandled rejection.
- core-data-structures/core.md: the `agent/*` taxonomy said "turn/step
boundaries", but the step-boundary mirror emits were dropped — `agent/*`
mirrors only turn boundaries; step boundaries are durable `step/start`/
`step/end` session events. Narrow the catalog so plugin authors aren't pointed
at nonexistent `agent/*` step events.
- interception-seams RFC: replace stack-position phrasing ("a later stack PR",
"the stack's first change", "the PR that makes...") with durable mechanism/RFC
names (the hook bridge packages, the event-domain-semantics RFC).
- tools/post-execute snapshot: `dispatched.content` was the same array reference
as `result.content`, so a listener's in-place `push`/`splice` leaked into the
returned content while a reassignment was masked — the "protect from tampering"
comment over-claimed. Copy content into a fresh array so the snapshot guards
the array structure; comment now states it is not deep immutability. Regression
extended to push a block in-place and assert it does not leak (proven red
without the copy).
Review noted the handler's comment said "EPIPE" while the code swallowed every
stdin 'error'. Swallowing any stdin-write error IS correct here — the write is
best-effort and the command's authoritative outcome is its exit code + captured
output (reported by the `close` handler regardless of whether the write landed).
A rare non-EPIPE pipe fault means the command ran with incomplete stdin, which
it surfaces itself via its own exit/output; rejecting `done` would instead
discard that real output and turn it into an opaque infrastructure error. Widen
the comment to state this rather than implying only EPIPE is caught. No behavior
change.
Round-2 Codex review of the round-1 fixes:
- (A) The Codex plain-stdout→additionalContext fold (F1) was not gated on exit
code, so a NON-clean hook's stdout still injected: a SessionStart `echo stale;
exit 2` (an emit — cannot block) wrongly injected "stale", and a
UserPromptSubmit `exit 1` (non-blocking error → falls through to context) did
too. Gate the fold on `output.exitCode === 0`, matching the codec's own
structured-stdout rule. Guard tests for both paths, proven red without the gate.
- (B) The Codex "SessionStart no-context no-op" absence test was unsound (a
completed turn doesn't prove the detached hook finished). It now touches a
marker and waitFor()s it before asserting no context.
- (B) Both HMR tests used a no-op `true` hook, so a leaked listener would still
pass. They now use a BLOCKING (exit 2) UserPromptSubmit hook and assert the
post-dispose turn is NOT blocked and logs no hook/invoked — a leaked listener
fails loudly.
The bridge tests that drive observe-only emit listeners (session-start,
subagent/start, subagent/end) fire their hook on a detached `.then` the test
cannot await. They waited a fixed 50-80ms, which flaked under the full
test:coverage run's heavy parallel load (transform ~400s): the sleep expired
before the async hook completed, so the injected context / marker file / warn
call had not landed. Replace each fixed sleep with a `waitFor(predicate)` poll
that retries until the observable effect appears (5s deadline) — "async state is
not synchronous state": wait for the signal that actually fires, not a guessed
duration. No behavior change; the same assertions, made robust to scheduling.
Wire the bridges to the codec's new discriminator check (merged down from
dsh-hook-protocol): each bridge passes its firing `point` as `expectedEventName`
to runHook, so a hook whose `hookSpecificOutput.hookEventName` names a different
event has its event-scoped fields discarded. Bridge-level guard test: a
PreToolUse hook emitting a UserPromptSubmit-labeled deny no longer denies the
tool (proven red without the wiring, then reverted).
Round-1 Codex review findings on the bridges:
- Stop force-continue (both bridges): a blocking Stop hook with EMPTY stderr
yielded decision 'deny' + reason undefined, and the `&& reason !== undefined`
guard let the turn STOP — the opposite of a blocking Stop hook. Force-continue
on any deny; fall back to a generic steering line when there is no reason.
- Codex payload tool_name: hardcoded "Bash" disagreed with the exec.name matcher
subject, so a real Codex `matcher:"Bash"` never fired against the harness's
lowercase `bash` tool. Use exec.name in both payload builders (matches the
matcher subject and the sibling CC bridge). Doc/RFC updated.
- Codex plain-stdout context: SessionStart/UserPromptSubmit are documented to
treat a clean hook's PLAIN (non-JSON) stdout as additionalContext, but nothing
folded it. runPoint now folds plain stdout into context for those two events,
gated on the codec's JSON gate so structured stdout is never dumped as prose.
- continue:false is deferred, not honored: the seams have no hard-halt primitive
yet. TODO(hook-continue-false) at both bridges + an RFC deferred note; the two
tests now assert the LOG records the halt request AND that the run is NOT
actually halted (no longer misleading).
- README concurrency wording: hooks run SERIALLY (deliberate — adjacent
invoked/result log pairs, order-independent fold), not concurrently. Fixed the
CC README claim + an RFC note.
Regression guards proven red on the unfixed code, then reverted. The mismatched-
hookEventName discard (also flagged) is fixed in dsh-hook-protocol and merged down.
The reference schemas key the `hookSpecificOutput` block by `hookEventName`, so
a block naming a DIFFERENT event than the one firing is malformed — a hook
emitting `hookSpecificOutput.hookEventName: "PreToolUse"` on a `Stop` event must
not deny the Stop. The codec surfaced `hookEventName` for a bridge to compare but
never enforced the discard, so both bridges pushed every parsed output into the
merge unconditionally.
parseHookOutput now takes an optional `expectedEventName`; when the block's
`hookEventName` names a different event, its event-scoped fields
(permissionDecision/permissionDecisionReason/additionalContext/updatedInput) are
discarded (the discriminator is still surfaced for the log, and the
event-agnostic top-level decision/continue/etc. are unaffected). runHook threads
it via RunHookOptions.expectedEventName; a caller that omits it opts out.
Codex review finding on the bridges PR (PR-F); fixed here on the codec that owns
the fold and knows field provenance, then flows down to both bridges.
The two bridge plugins that run a user's existing Claude Code / Codex hook
config on the harness's typed interception seams, built on the shared
dsh-hook-protocol library. A bridge is a faithfulness adapter, not a power
tool: anything it does a native cordis plugin does more powerfully — the
bridge exists only to run UNMODIFIED external hooks.
- dsh-hooks-claude: CC dialect. Seven hook points (SessionStart,
UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart,
SubagentStop), CC per-event stdin payloads, env + ${CLAUDE_PLUGIN_ROOT}/
${CLAUDE_PROJECT_DIR} substitution, literal-or-regex matcher.
- dsh-hooks-codex: Codex dialect — a deliberate subset. Five hook points,
always-regex matcher, snake_case payloads (turn_id/model, no trailing
newline), no env/substitution, block-only decisions.
Both map the neutral merged outcome onto the seam's typed Decision and stamp
an explicit {kind:'plugin'} source on injected context (so it is never
mislabeled as a user prompt). Config parse-failure is contained; only command
hooks run. updatedInput is logged+warned (input rewrite deferred); the Stop
loop-guard is deferred (TODO).
Tests: per-file 100% — config-parse unit branches + per-seam mappings
end-to-end through the REAL loop + REAL bash + REAL shell scripts (scripted
mock model only) + a real-Loader export-shape guard. A keyless ACP snapshot
scenario (hook-prompt-block) proves a UserPromptSubmit hook blocks a prompt
end-to-end (rejected turn -> ACP cancelled, hook/* events in the log); a
with-key e2e (hooks.e2e.ts) proves a PreToolUse hook blocks real bash
(verified on disk). The snapshot normalizer now scrubs hook/result.durationMs.
RFC: docs/rfc/implemented/feature/2026-06-30-hook-bridges.md
mergeHookOutputs collected reasons only from rank-3 (deny/block) hooks, so an
ask-winning outcome lost its reason — a bridge mapping an `ask` decision to a
PreToolDecision had no reason to attach. Collect reasons per rank and emit the
ones explaining the winning decision: a deny-winning fold shows deny reasons, an
ask-winning fold shows ask reasons, allow contributes none. Found while building
the hooks-claude bridge's PreToolUse `ask` path.
Codex's PR-E review found three protocol-fidelity blockers + two doc gaps, all
verified against ~/repos/refs:
- (A) Top-level `decision` accepted allow/deny/ask, but both reference schemas
reserve those for hookSpecificOutput.permissionDecision — the legacy top-level
decision is approve/block ONLY. Split topLevelDecisionOf (approve/block) from
permissionDecisionOf (allow/deny/ask), so an out-of-band {"decision":"deny"} is
now invalid and ignored instead of becoming a real blocking decision.
- (A) hookSpecificOutput was parsed without its hookEventName discriminator.
HookOutput now surfaces hookEventName so a bridge can discard a block whose
claimed event doesn't match the firing one (the schemas key the block by event).
- (A) runHook discarded raw stdout. HookOutput now carries `stdout` (trimmed,
verbatim) so a bridge can reproduce CC's plain-stdout rendering / Codex's
plain-stdout-as-additionalContext behavior.
- (B) hook/* SessionEventMap variants were only named in prose; added a payload/role
table to core-data-structures/session.md (a maintained catalog surface).
- (B) Removed PR-stack-position references (PR-F / "future bridge packages") from a
test comment and the RFC, per the current-state-wording rule.
New codec tests: top-level allow/deny/ask invalid+ignored, hookEventName capture,
raw stdout preserved on plain + JSON + empty stdout. 51 tests, per-file 100%.
Codex review caught an observe-only violation: the subagent/end emit fires from a
detached `.then` registered BEFORE start() returns — so before the caller's own
`await run.result` continuation runs. Carrying `result.output` by reference let a
mutating subagent/end listener corrupt the SubagentResult.output the caller/tool
then consumes. structuredClone() makes the event a read-only snapshot. Added a
regression test that mutates the event's array and asserts the caller's result is
untouched; proven to fail red without the clone. Updated the RFC + READMEs to note
the clone is load-bearing for the observe-only guarantee.
Tianyi Cui
Yichen Jiang
Ziya
kingwl