Tianyi Cui
9f6b96c555
Codex + an independent review pass found three real defects in the prior commit: 1. parseExitStatus could misreport a SUCCESSFUL command as a failure: a clean exit 0 appends no marker, so output ending in "[exit code: 5]" (no trailing newline) was read as the marker. Anchor the parse to a LEADING newline — renderResult always inserts one before a real marker, so a body that merely ends in marker-like text no longer matches. A narrow residual (a clean exit 0 whose final line is exactly the marker) is inherent to the replay-only-sees- text design and documented; the complete fix (a structured exit on the event) is the RFC's named escape hatch. 2. A run_in_background start and an isError result were rendered as exited terminal cards with a false exit-0 pill. A background start returns a task-id ack (not a streamed terminal) and is no longer marked terminal; an isError result (spawn failure / abort) carries no exit pill. 3. The terminal capability was re-read live on the result path, so a second initialize between a call and its result could desync them (orphan terminal_output or clobbered card). Snapshot the capability per session at creation (SessionRecord.terminalEnabled) so call and result always agree. Also reword the reference-parity claim: keeping the description as a content block in terminal mode is a DELIBERATE divergence (claude-agent-acp drops it). Tests added for each; with-key e2e still green.
RFCs
One kind of design doc lives here. An RFC records a decision or proposal that shapes this codebase — the why and what we gave up, the parts code and docs can't carry. (Earlier this split into separate "ADR" and "RFC" trees; they were unified, since most ADRs were simply implemented RFCs.)
Layout and naming
Files are grouped by lifecycle into three folders, and an RFC moves between them as its status changes:
proposed/— proposals reviewed before implementation; not yet built (or only partly).implemented/— the decision shipped. The file records what was decided and what was rejected.rejected/— the proposal was considered and declined. Kept for the record so the rejection isn't re-litigated.
Each file is named yyyy-mm-dd-topic-title.md, where the date is when the topic was first proposed (per git history). Cross-references between RFCs use relative markdown links ([topic](../implemented/2026-…-….md)) — never bare prose or numbers — so they are mechanically checkable and survive moves between folders.
When to write one
Write an RFC when a decision is durable (it shapes the codebase beyond a single function or package), contested (there was a real alternative a reasonable engineer might have chosen), and surprising (a future reader would otherwise ask "why on earth is it done this way?"). A proposal for substantial future work starts in proposed/; a decision already made starts in implemented/.
Do NOT write one for a mechanical or local choice (a variable name, a one-file refactor), for anything already enforced and explained by a gate or a convention in AGENTS.md, or for a still-provisional decision tagged TODO(...) in the code — record those as TODOs and promote to an RFC only once they settle. An RFC is never edited into a different decision: supersede it with a new one and cross-link.
Proposed
| Title | First proposed |
|---|---|
| Mutation testing as the coverage counterweight | 2026-06-11 |
| Deterministic tests, the replay invariant fixture, and race stress | 2026-06-11 |
| Architectural conformance — dependency rules and the adapter kit | 2026-06-11 |
| API extractor reports | 2026-06-11 |
| Supply chain checks and vendor drift verification | 2026-06-11 |
| Agent Client Protocol (ACP) support for external editors | 2026-06-14 |
| Multiplex concurrent ACP sessions over one connection | 2026-06-14 |
| Optional Code Mode — model writes TypeScript against an SDK of all tools | 2026-06-15 |
| Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern) | 2026-06-16 |
Implemented
Rejected
| Title | First proposed |
|---|---|
| Deep-readonly public surfaces | 2026-06-11 |