@with-logic/elwood 0.1.0 → 0.1.2

package/prd/14-conformance.md

@@ -0,0 +1,333 @@
+## 14. Conformance
+
+This section defines what it means for an Elwood implementation to satisfy this
+PRD. Every criterion below should have one or more tests. Test names should
+include the criterion ID.
+
+### 14.1 Criteria Structure
+
+Each criterion has:
+
+- an ID such as `C-API-01`;
+- a reference to the section it validates;
+- a concrete externally observable behavior.
+
+### 14.2 Criteria
+
+#### C-API: Public API (§5)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-API-01 | §5.1 | `startClaude({ cwd })` returns a `ClaudeSessionApi` with a stable non-empty `elwoodSessionId`. |
+| C-API-02 | §5.1 | `startClaude` accepts launch-time hook handlers before Claude starts. |
+| C-API-03 | §5.2 | `resumeClaude({ elwoodSessionId })` resumes using Elwood metadata without requiring a Claude session ID from the caller, provided project-local state is discoverable from the current process cwd or caller-supplied `cwd`/`stateDir`. |
+| C-API-04 | §5.3 | `ClaudeSessionApi` exposes `sendPrompt`, `sendKeys`, `resize`, `stop`, `kill`, and `teardown`. |
+| C-API-05 | §5.3 | `sendPrompt` writes through the PTY input path, not through Claude print mode or SDK APIs. |
+| C-API-06 | §5.3 | `sendPrompt` supports multi-line prompt text as one submitted user prompt. |
+| C-API-07 | §5.3 | Calling `sendPrompt` while Claude is busy writes input immediately rather than waiting for turn readiness, serializes against queue-backed prompt/message/command submissions, and resolves after its submitting Enter is dispatched; terminated sessions may still fail with `session_not_running`. |
+| C-API-08 | §5.4 | Consumers can subscribe and unsubscribe from typed session events. |
+| C-API-09 | §5.5 | `startCodex({ cwd })` returns a `CodexSessionApi` with a stable non-empty `elwoodSessionId`. |
+| C-API-10 | §5.6 | `resumeCodex({ elwoodSessionId })` resumes using Elwood metadata without requiring a Codex session ID from the caller, provided project-local state is discoverable from the current process cwd or caller-supplied `cwd`/`stateDir`. |
+| C-API-11 | §5.7 | `CodexSessionApi` exposes the same terminal control and lifecycle methods as `ClaudeSessionApi`. |
+| C-API-12 | §5.4 | Claude and Codex sessions emit adapter-neutral `activity` events for common lifecycle, message, tool, transcript, and hook-error observations, with normalized metadata for common timeline rendering. |
+| C-API-13 | §5.3 | Claude and Codex sessions expose `sendMessage` as the adapter-neutral queued message submission API. |
+| C-API-14 | §5.7 | Sessions emit typed `warning` events (and projected `warning` activities) for non-fatal environment issues. Warnings are LIVE-ONLY: emitted once when observed, never persisted, never replayed to a late subscriber, and never accumulated into a snapshot or running count. A warning known BEFORE the session is returned (the version/preflight warning) is delivered on a deferred tick AFTER `startClaude`/`startCodex` resolves, so a caller that attaches a `warning` listener in the same turn it receives the session still observes it — without restoring general late-subscriber replay. |
+| C-API-15 | §5.3 | Sessions expose a typed headless xterm terminal handle with snapshot and underlying xterm access. |
+| C-API-16 | §5.1 | Omitted `initialSize` defaults to a 189 column by 48 row terminal. |
+| C-API-17 | §5.4 | Hook dispatch emits adapter-neutral hook-result activity, and hook failures also appear in the activity stream. |
+| C-API-18 | §5.1 | Claude and Codex start/resume options expose `autotrust` for opt-in workspace trust prompt automation. |
+| C-API-19 | §5.3 | Calling `sendMessage` while the session is alive but not ready queues the message until the next ready transition and rejects only if the session terminates first. |
+| C-API-20 | §5.7 | Codex transcript activity is flushed before terminal exit and terminal lifecycle status are emitted. |
+| C-API-21 | §5.1 §5.5 | A caller-provided `persona` is submitted as the session's first user message on the first ready transition, ahead of caller-queued messages; it is not persisted and not re-sent on resume. |
+| C-API-22 | §5.3 §5.7 | `compact()` submits the adapter's `/compact` command through the readiness queue, resolves on the adapter's `PostCompact` hook, rejects with `compact_failed` on timeout, and rejects with `session_not_running` if the session terminates first. |
+| C-API-23 | §5.3 §5.7 | `listModels()` parses the adapter's rendered model picker into typed options with current/default markers, cancels with Escape, and leaves the session model unchanged. |
+| C-API-24 | §5.3 §5.7 | `setModel(id)` switches the session model through cursor navigation; Elwood itself never persists a new default into user-owned configuration (Claude uses the session-only key; the Codex CLI persists its own picker selection, documented as a §4.5 deviation) and unknown ids reject with `model_automation_failed` listing available ids. When Claude interposes its built-in model- or effort-cache warning, Elwood selects the affirmative row from one bottom-most contiguous live dialog across numbered/unnumbered layouts, revalidates it before confirmation, and resolves only after the idle composer returns; transcript text cannot participate and a `PreModelSwitch` hook confirmation remains human-controlled. |
+| C-API-35 | §5.3 §5.7 | `listModels()`/`setModel()` dispatch the picker command even while a turn is in flight (they do not wait for `ready`), so picker automation is not stalled by an in-flight turn such as an MCP-server boot spinner; `compact` and messages still wait for the active turn. Ordering is FIFO except for the documented overtaking of a readiness-waiting head by an immediate operation (a picker command, a `sendPrompt`, or already-ready running-turn guidance); same-class and post-ready ordering stays FIFO, and no two submissions interleave. |
+| C-API-36 | §5.3 | A Claude session requested below 100 columns bootstraps at 100 columns and holds only the PHYSICAL pre-ready resize while recording each pre-ready requested size in memory (multiple pre-ready resizes leave the last one as the latest requested size; terminal size is never persisted, §8.2); it restores the latest requested size before its initial ready queue drains, so narrow visible terminals do not lose their first prompt. |
+| C-API-37 | §5.3 §5.7 | Claude and Codex expose `sendGuidance(message)`: before first readiness and while blocked it queues safely like `sendMessage`; during a post-ready running turn it overtakes readiness-waiting operations and enters the TUI immediately. Guidance serializes with queue-backed prompt/message/command submissions and resolves only after the submitting Enter is dispatched; raw `sendKeys` intentionally bypasses that queue. |
+| C-API-38 | §5.3 §5.7 | `interrupt()` bypasses the control queue and writes a single Escape immediately while the session is `running` or `blocked` AND has reached initial readiness at least once, resolving when the session next reaches `ready`; with no turn in flight — an idle `ready` session or the pre-readiness startup `running` window — it resolves without writing anything; concurrent calls coalesce into one Escape; it rejects with `interrupt_failed` after `timeoutMs` (default 10000 ms) and with `session_not_running` when the session terminates first or is already terminal. |
+| C-API-39 | §5.3 §5.7 | When restoring the latest requested size at Claude's initial-ready transition fails with a real (non-closed) native PTY resize error, Elwood keeps the safe bootstrap width, does not report the resize as applied, and surfaces a typed `resize_restore_failed` warning (content-free: only the requested size and an allowlisted error code), while still releasing the queued persona/caller message so input is never starved; a closed-fd resize at that transition stays a silent no-op. |
+| C-API-25 | §5.3 | Promise-returning session methods called after a terminal status reject with `session_not_running` instead of throwing synchronously. |
+| C-API-26 | §5.2 §5.6 | `startOrResumeClaude`/`startOrResumeCodex` resume when possible, fall back to a fresh start only on `state_not_found`, `resume_unavailable`, or `adapter_mismatch`, rethrow all other errors, and report `resumed` in the result. |
+| C-API-27 | §5.7 | `ElwoodAgentSession` is exported and both `ClaudeSessionApi` and `CodexSessionApi` (the raw live sessions the `ClaudeSession`/`CodexSession` classes wrap) are assignable to it, covering common events, io, commands, and lifecycle. |
+| C-API-28 | §5.3 | Initial readiness fires from the adapter's pre-input readiness hook — Codex's `SessionStart`, Claude's `InstructionsLoaded`. On a COLD start the rendered composer is never a readiness signal — the boot-time composer placeholder alone never releases the first queued message (it is painted before the input loop is live and would be swallowed). On a RESUME the CLI reattaches to an existing conversation without re-firing its pre-input hook and its input loop is live when the composer paints, so a resumed session fires initial readiness on the FIRST rendered composer marker (or on the readiness hook if it re-fires, whichever is first), reaching readiness in ~1s instead of the full deadline. A blocking dialog's option caret is byte-identical to the composer marker, so the resume-composer path does NOT fire while a blocking dialog is on screen — readiness waits for the dialog to clear, so a draining queued message can never approve it. This dialog gate applies to EVERY readiness source, not just the resume-composer path: a blocking dialog on screen — including one that first rendered while the session was still `starting`, before it could latch the `blocked` status — defers a hook OR deadline readiness mark too, so no readiness source ever drains the queue into a dialog. The deferred mark is reconciled the moment a rendered frame shows the dialog cleared (readiness is neither drained into the dialog nor permanently starved by it). A bounded deadline after the first rendered frame is the ultimate fallback on BOTH adapters and BOTH start/resume, so a missing/failed readiness hook (and, on cold start, an absent composer signal) cannot starve queued persona/messages forever. Readiness fires exactly once (idempotent): whichever of hook, resume-composer signal, or deadline comes first releases the first queued message, and the others are no-ops. |
+| C-TURN-01 | §5.3 | While a turn runs the session is `running`; when the turn ends by any means — completion, Escape interrupt, or otherwise — the session transitions to `ready` and emits the corresponding `status` activity, on both adapters. |
+| C-TURN-02 | §5.3 | An Escape interrupt of a running turn produces the `ready` transition from rendered TUI state alone, with no dependency on a `Stop` hook. |
+| C-TURN-03 | §5.3 | Turn-state detection uses documented per-adapter indicator constants over `snapshot().text`; redundant edges are idempotent, and screens showing neither indicator hold state. Watching activates only after initial readiness. On resume, rendered edges remain suppressed through transcript replay until the first quiet, non-blocking composer; explicit running evidence releases that suppression immediately and synchronizes the watcher, and the CURRENT frame is still evaluated so the real turn's rendered end is retained even when it is the first frame after release (the turn ended exactly as the evidence arrived). |
+| C-TURN-04 | §5.3 | The interrupt `ready` transition fires at any terminal width: via the working-token edge where the footer fits, and via the adapter's interrupt end banner (which Claude's footer elision below ~66 columns makes necessary) on narrow screens. |
+| C-TURN-05 | §5.3 | Turn-state detection also consumes the OSC window title as a width-independent working signal: both adapters render a braille-spinner glyph (U+2800–U+28FF) in the title while a turn runs, so a turn `started` edge can fire from the title alone when the on-screen footer token is elided. The title is exposed on the terminal handle and is not persisted. |
+| C-ATTN-01 | §5.3 | A tool permission dialog rendered mid-turn transitions the session to `blocked` and emits an `attention` activity whose label names the matched screen-fact rule ids, on both adapters. |
+| C-ATTN-02 | §5.3 | A session enters `blocked` from either `running` or `ready` when a blocking dialog appears, and settles to `ready` when the dialog resolves; blocking evidence never moves a session out of a terminal status. |
+| C-ATTN-03 | §5.3 | Startup prompts Elwood answers automatically never produce `blocked`; a workspace trust prompt left unanswered because `autotrust` is false does. |
+| C-ATTN-04 | §5.3 | Claude's model/effort switch confirmation dialogs are blocking prompts even though their selection caret resembles the composer marker. The built-in cache warning is automatically confirmed only as part of `setModel`; hook-requested confirmations remain blocked for a human decision. |
+| C-API-33 | §5.3 | `statusDecisions()` returns a live-only log of at most the 50 most recent status decisions, oldest first, each recording the evidence, the from/to statuses (`to` undefined when ignored), and a human-readable reason; it is never persisted and carries no prompt, terminal, or hook payload content. |
+| C-API-34 | §5.3 | `waitForStatus`/`waitForActivity` resolve from current state or the next matching event, reject with `wait_timeout` after the timeout (default 60000 ms), and reject with `session_not_running` when the session reaches an unwaited terminal status first; both unsubscribe on settle. |
+| C-API-29 | §5.2 §5.6 | Resume accepts the same launch-policy options as start and forwards them into the relaunched command: `resumeClaude` forwards `permissionMode`, `allowedTools`, `disallowedTools`, `tools`, and `reasoningEffort`; `resumeCodex` forwards `sandbox`, `approvalPolicy`, and `reasoningEffort`. A resumed agent stays exactly as privileged and as tool-restricted as it started, and applies a re-supplied reasoning effort (which Elwood does not persist across resume). |
+| C-API-32 | §5.2 §5.6 | Resume defaults launch-policy options from the record's persisted posture; explicit resume options override field by field, and the effective posture is re-persisted. |
+| C-API-30 | §5.4 | `tool_call` activity carries the tool's input as a serialized `toolInput` and `tool_result` activity carries the tool's output as a serialized `toolOutput`, sourced from the committed transcript for Claude (`tool_use.input`/`tool_result.content`, per C-CLAUDE-15) and from the transcript for Codex (`arguments`/`output`); absent sources leave the field absent. |
+| C-API-31 | §5.3 | The submitting Enter is a separate PTY write after a settle delay, and bounded re-Enters fire while the rendered composer still shows the staged paste, so a first long prompt cannot be left staged-but-unsubmitted. |
+| C-API-40 | §5.3 | `sendPrompt`/`sendMessage`/`sendGuidance` text is sanitized before it is framed as a bracketed paste: the `ESC [ 200~`/`ESC [ 201~` sentinels and all other C0/C1 control characters except tab, newline, and carriage return are removed, so caller/model text cannot escape paste mode and inject live keystrokes (e.g. an Enter that confirms a permission dialog). `sendKeys` is the raw escape hatch and is never sanitized. |
+| C-API-41 | §5.3 | `listClaudeModels(options)`/`listCodexModels(options)` return the available models WITHOUT a caller-held session: each starts a throwaway session with `autotrust: true` (a documented §5.1 exception — the probe only opens/cancels the picker and never runs a turn), waits for first readiness, calls `listModels`, and ALWAYS removes ALL probe state afterward — on success, on a readiness/picker failure, AND on an adapter start failure that has already allocated a state directory or runtime files — so no probe session, process tree, socket, or state directory is leaked. A readiness/picker error is the error surfaced to the caller; teardown still runs, and when teardown ITSELF fails (which can leave a probe process tree alive) a bounded diagnostic naming the teardown failure — an allowlisted errno or the error's name, never a raw message — is attached to the surfaced error's `cause`, so a leaked probe is never silently invisible. The rows are exactly `listModels`' output and the probe leaves the user's saved MODEL default untouched (the picker is opened and cancelled, never applied), just as `listModels` does on a live session. |
+| C-API-42 | §5.3 §5.7 | When recording a session's one-shot initial-ready transition throws (a lifecycle-event listener) — on EITHER adapter — Elwood still releases the control queue directly FIRST so queued persona/caller input is never starved, then surfaces a typed, content-free `initial_ready_fallback` warning (`agent: "claude" \| "codex"`) whose delivery is itself isolated so a rogue warning sink cannot re-starve the queue. |
+| C-API-43 | §5.3 | `ClaudeSession.login(options)` drives the interactive `/login` re-authentication flow to recover a session whose login lapsed (per C-CLAUDE-18) without a caller-held restart. It submits `/login` as a picker command, selects the requested login `method` (default `claudeai`) from the "Select login method" list if that list renders, and scrapes the authorization URL off screen and reports it via the optional `onAuthUrl` callback. Because the default account flow completes with a human-entered authorization code, Elwood awaits the CLI's "paste code" prompt and, when it renders, calls the required `provideCode` callback and submits the returned code as raw input; a flow that self-completes without prompting for a code never calls `provideCode`. `login` resolves once the CLI reports login success AND the session is usable again, and rejects with `login_failed` on an explicit failure/invalid-code banner or with `login_timeout` after `timeoutMs` (default 300000 ms); like every other command method it rejects with `session_not_running` when the session is terminal. It serializes with other queued commands and never sends raw keystrokes into a blocking dialog. |
+| C-API-44 | §5.3 | `sendPrompt`/`sendMessage`/`sendGuidance` accept an optional `images` list (file paths or `{data,format}` bytes) attached to the submission. Images have no position within the text, but the list is ORDERED (array order = attachment/chip order). Elwood attaches every image through the CLI's own native ingestion path, as part of the SAME serialized queue operation that submits the text and BEFORE that text's submitting Enter, so one call yields one agent turn carrying text and all images. Inputs are validated and bounded before any temp file is written or any input reaches the composer: at most 16 images, ≤25 MiB per image and ≤50 MiB total; an unsupported/empty `format`, a `path` that is not a readable regular file (its readability checked, not merely its existence), or any count/size past the limits rejects with `invalid_image`. A non-array `images`, an entry that is not exactly one of `{path}`/`{data,format}`, a non-string `path`, or non-`Uint8Array` `data` also rejects with `invalid_image` (never a raw type error). Every input is defensively SNAPSHOTTED — byte buffers cloned, paths absolutized — SYNCHRONOUSLY at the public send boundary, BEFORE the op is enqueued, so a caller that mutates its buffer (or changes `cwd`) after the call cannot change what is attached; the shape, format, count, and byte-size limits are enforced in that same synchronous pass, so a malformed or over-limit input rejects with `invalid_image` before it ever occupies a queue slot. The remaining filesystem checks that need I/O — a path's readability, regular-file-ness, and size against the per-image and shared aggregate ceilings — run inside the queued op at dispatch (so a path made unreadable after the call still rejects, and no temp file is written for a still-queued submission). The synchronous snapshot completes before the queue insertion, so an image submission is still enqueued in call order and a later plain submission cannot overtake it. Beyond the per-submission 50 MiB ceiling, a PER-SESSION aggregate ceiling (200 MiB) bounds the cloned image bytes held across ALL not-yet-attached queued submissions at once: a submission whose clone would push the session past that ceiling rejects with `invalid_image`, and each submission's reserved bytes are released when it settles (attach done, reject, or the session closing), so a slow paste/confirmation cannot let a caller retain unbounded queued-clone memory. Because a send on a TERMINAL session is guarded first, a malformed/over-limit `images` on a stopped/killed/torn-down session rejects with `session_not_running` (the terminal contract), not `invalid_image`. The lifecycle turn transition is deferred until AFTER a successful attach, so an attach rejection leaves readiness untouched and never wedges the queue; a raw materialization failure (e.g. disk-full) is surfaced as the typed `image_attach_failed`, not a raw platform error. Each image's attach is CONFIRMED by its `[Image #N]` chip on the composer prompt-glyph line (so unrelated screen text cannot spoof it); an unconfirmed image (chip not seen within 10 s) or a clipboard read/write failure rejects with `image_attach_failed`, submits no text, and best-effort clears the composer draft so staged images do not leak into a later turn (a session that terminates mid-attach rejects with `session_not_running`). Bytes are written to a short-lived temp file Elwood attempts to remove after the submission is attached (best-effort; a persistently failing removal falls to OS temp reaping). |
+| C-API-45 | §5.3 | Claude attaches an image by bracketed-pasting its ABSOLUTE path into the composer (the delivery a terminal produces on drag-and-drop); Claude reads and encodes the file itself and shows an `[Image #N]` chip. This is pure PTY text and works on every platform. |
+| C-API-46 | §5.3 | Codex attaches an image from the OS clipboard: Elwood snapshots the user's clipboard ONCE (rejecting with `image_attach_failed` if the snapshot fails, before mutating anything), then for each image in order writes it onto the macOS `NSPasteboard` as a native image (`public.tiff`), sends Ctrl+V, and waits for the `[Image #N]` chip; after all images it restores the single snapshotted clipboard (best-effort, text contents). The whole snapshot/set/paste/confirm/restore sequence holds a process-wide clipboard lock so concurrent Codex sessions cannot cross-attach. A pasted path is NOT an image on Codex. Codex image attachment is macOS-only: `images` on a non-macOS Codex session rejects with `unsupported_platform` and submits nothing. |
+| C-API-47 | §5.8 | The ergonomic `ClaudeSession`/`CodexSession` construct synchronously with the same options as `startClaude`/`startCodex` (with `cwd` defaulting to `process.cwd()`), do NOT start the underlying session at construction, and start it lazily on the first `send`/`stream` or on an explicit `start()`. `start()` is idempotent and concurrent-safe (a second `start()`, or a `send`/`stream` during startup, awaits the same in-flight start), and a startup failure rejects the triggering call with the same typed `ElwoodError` the factory would throw. The started underlying session is exposed via a read-only `session` accessor (undefined until started). |
+| C-API-48 | §5.8 | `stream(prompt, options?)` returns an async iterable that yields the SIMPLIFIED typed events of exactly one turn in arrival order — `{type:"text"}` for `assistant_message`, `{type:"thinking"}` for `reasoning`, `{type:"tool_call",name,input?,toolCallId?}` for `tool_call`, `{type:"tool_result",name?,output?,toolCallId?}` for `tool_result` — and no other activity kind. A tool event carries the adapter's normalized `toolUseId` as `toolCallId` when available so calls and results can be correlated. The facade subscribes to `activity` BEFORE submitting the prompt (no early event of the turn is missed); turn isolation rests on SERIALIZATION — the serialized slot is held until the agent reaches its real boundary (not until the consumer stops reading) so a prior turn's activity never bleeds into the next — with `turnId` binding as an additional refinement where the adapter tags it (Codex; Claude transcript activity has none). An idle `ready` may complete the turn only after positive acceptance from `UserPromptSubmit`, turn content, or `Stop`; an unaccepted idle transition waits the no-oracle quiet window, replays the same submission at most twice, and then fails with `wait_timeout` instead of reporting an empty success. The iterator ends via the completeness oracle: once an accepted `ready` is observed, it ends the instant the collected assistant text contains the `Stop` hook's `last_assistant_message` (used as a completeness signal only, never displayed); with no such signal it ends after a bounded quiet window; a terminal status ends it IMMEDIATELY. There is NO whole-turn timeout by default (a live turn may run for hours); a caller may pass an opt-in `timeoutMs` ceiling, ARMED ONLY AFTER submission (a turn begins on submission, so the ceiling never rejects a prompt still queued behind readiness that then submits), and a `catchUpMs` cap (default 10000 ms) armed once an accepted `ready` fires throws `wait_timeout` if the transcript never catches up — including when a NON-EMPTY expected text never appears (a promised completion that never arrives is a failure, not a quiet settle). |
+| C-API-49 | §5.8 | `send(prompt, options?)` resolves with the turn's assistant text: the `text` of every `type:"text"` stream event, in order, joined by `\n\n` between distinct assistant messages, and NOTHING else (no thinking or tool text). A turn with no assistant text resolves to the empty string. `send` and `stream` share one turn boundary, so a `send` resolves exactly when the equivalent `stream` iterator ends. |
+| C-API-50 | §5.8 | Ergonomic turns are SERIALIZED: overlapping `send`/`stream` calls queue and run one at a time in call order, so one turn's yielded/collected activity never interleaves with another's. |
+| C-API-51 | §5.8 | `close()` stops the underlying session (falling back to `kill` on a stop failure) and is a no-op when the session never started, so it is safe to call in a `finally`. When a lazy start is IN FLIGHT, `close()` awaits that same start and stops the resulting session (never orphaning a session whose launch resolves after `close()` returned); a launch that REJECTS leaves nothing to close. When BOTH stop and kill fail, `close()` throws `termination_failed` carrying BOTH the stop `cause` and the kill `killCause` (neither diagnostic is lost). |
+| C-API-52 | §5.8 | `ClaudeSession`/`CodexSession` expose the FULL control surface in addition to `send`/`stream`, in THREE categories. (1) OPERATIONAL methods — `sendMessage`, `sendPrompt`, `sendGuidance`, `sendKeys`, `resize`, `interrupt`, `compact`, `listModels`, `setModel`, `waitForStatus`, `waitForActivity`, and Claude's `login` — lazy-start the underlying session on first use and delegate to it. (2) `on`/`off` BUFFER before start (attached on start, so subscribing never forces a start). (3) SHUTDOWN methods — `stop`/`kill`/`teardown` — only delegate when a live session already exists and are no-ops before start (so `close()` is safe in a `finally`). `status` reads `starting` until the session exists. Only `send`/`stream` serialize; operational control methods go through immediately (not queued behind a running turn). `startClaude`/`startCodex` are deprecated in favor of the class but remain functional. |
+| C-API-53 | §5.8 | An ergonomic turn's buffered state is BOUNDED even with no whole-turn timeout: the oracle matches a rolling window of recent assistant text (bounded even when the `Stop` hook's expected text is itself large, and large enough BEFORE the oracle is installed to retain text that arrives ahead of a lagging `Stop` hook), and UNCONSUMED events are capped by BOTH count and total UTF-8 bytes. A turn whose pending backlog exceeds either cap fails with `wait_timeout` rather than growing without limit; the byte cap is required because a single event may carry an arbitrarily large agent-controlled payload that the count cap alone would not bound. |
+| C-API-54 | §5.1 §5.2 §5.5 §5.6 | `highTrust: true` on `startClaude`/`resumeClaude`/`ClaudeSession` expands to `permissionMode: "bypassPermissions"`, and on `startCodex`/`resumeCodex`/`CodexSession` to `sandbox: "danger-full-access"` with `approvalPolicy: "never"`, before the posture is persisted and the process spawned (the record and launch command carry the expanded values). Combining it with an explicit `permissionMode` (Claude) or `sandbox`/`approvalPolicy` (Codex) rejects before spawn with `claude_high_trust_conflict` / `codex_high_trust_conflict`; the lazy session classes reject at construction. |
+
+#### C-LOOP: Recurring Session Loops (§5.9, §8, §9, §10)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-LOOP-01 | §5.9 | Raw Claude/Codex sessions, `ElwoodAgentSession`, and both lazy classes expose async `createLoop`, `listLoops`, and `cancelLoop` with adapter-neutral behavior and no native scheduler command. |
+| C-LOOP-02 | §5.9 | `ElwoodLoopRequest` is a readonly fixed/idle union; `parseLoopCommand` is explicit and package-root exported, while `sendMessage`/`sendPrompt` preserve literal `/loop` text. |
+| C-LOOP-03 | §5.9 | The parser recognizes only a positive integer plus `s`, `m`, `h`, or `d` as the first-token interval; every other remainder is an idle message. |
+| C-LOOP-04 | §5.9 | Fixed intervals are `>= 60,000` and `< 604,800,000` ms, messages are 1..65,536 UTF-8 bytes, and a fifty-first unexpired loop fails without eviction. |
+| C-LOOP-05 | §5.9 | A fixed loop first becomes due after its full interval plus delay-only jitter and submits only through the ordinary readiness-safe path. |
+| C-LOOP-06 | §5.9 | Idle loops use five continuous non-loop-activity-free minutes plus jitter; non-loop activity resets all, while a completed loop turn rearms only its origin and leaves peers eligible. |
+| C-LOOP-07 | §5.9 | Stable jitter is derived from ID at creation, falls in `0..min(10% cadence, 30s)`, never advances a due time, and is persisted as restore authority. |
+| C-LOOP-08 | §5.9 | A due loop blocked by liveness/readiness submits at most once at the next ready transition; missed occurrences do not accumulate and stop/exit discards transient due state. |
+| C-LOOP-09 | §5.9 | Due loops commit serially, one per ready transition, ordered by due time then ID; fixed clocks restart from submission and idle origin clocks from completing readiness. |
+| C-LOOP-10 | §5.9 | Live scheduling/submission failure emits redacted failure evidence and rearms fresh unless the session is non-live, when the persisted definition waits for resume. |
+| C-LOOP-11 | §8.2 | The loop sidecar stores stable identity, cadence, exact prompt, jitter, creation, and expiry but no live timer or transient scheduling state. |
+| C-LOOP-12 | §5.9 §9.3 | Resume discards missed runs and starts fresh clocks for surviving definitions from restored readiness. |
+| C-LOOP-13 | §5.9 | Loops expire seven wall-clock days after original creation; expiry beats pending submission, emits live only, and is pruned silently during resume or stopped/exited management. |
+| C-LOOP-14 | §5.9 §8.4 | Stop, unexpected exit, and process failure preserve loops; kill clears them permanently; teardown removes them with session state. |
+| C-LOOP-15 | §5.9 | `listLoops` orders immutable snapshots by creation then ID and exposes exact message, cadence, interval when fixed, jitter, times, state, and only a scheduled next-due time. |
+| C-LOOP-16 | §5.4 §5.9 | `loop` events match the specified `created`/`fired`/`cancelled`/`expired`/`failed` union and never contain a stored message or serialized request. |
+| C-LOOP-17 | §5.9 | Cancelling a known loop removes its definition and all future submissions without interrupting an already-committed active turn. |
+| C-LOOP-18 | §5.9 | Cancelling an unknown or finished loop fails with `loop_not_found` and cannot affect a different loop. |
+| C-LOOP-19 | §5.9 §10 | Loop validation, capacity, cancellation, persistence, and scheduling/submission use the five stable loop error names; diagnostics identify only loop ID. |
+| C-LOOP-20 | §5.9 | Listing/cancellation work on stopped/exited raw sessions, creation requires live state, lazy methods retain lazy-start semantics, and delivery uses current readiness/security posture. |
+| C-LOOP-21 | §8.2 | Core schema-version-1 records remain readable; absent sidecar means no loops, while the versioned `0600`, current-user-owned sidecar rejects malformed/unsafe reads as `state_corrupt`. |
+
+#### C-PTY: Terminal Process Behavior (§4, §9)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-PTY-01 | §4.1 | Claude runs inside a real PTY rather than a plain pipe subprocess. |
+| C-PTY-02 | §4.2 | The launched process sees environment from the user's normal interactive macOS shell startup. |
+| C-PTY-03 | §4.1 | Raw PTY output is emitted through `terminal:data` for live rendering, and late subscribers receive a bounded live-only replay of earlier process-lifetime PTY output. |
+| C-PTY-04 | §5.3 | `sendKeys` writes through the headless xterm input path, which emits PTY input. |
+| C-PTY-05 | §5.3 | `resize({ cols, rows })` resizes both the underlying PTY and the headless terminal model, while closed-fd resize races during process exit are ignored. |
+| C-PTY-06 | §9.4 | Process exit emits a terminal/process exit event and updates session status. |
+| C-PTY-07 | §4.1 | Cursor-addressed PTY output renders into the headless xterm snapshot before startup prompt detection runs. |
+| C-PTY-08 | §4.2 §9.2 | Non-PTY CLI probes (`--version`, `update`, `--help`) and the agent PTY run through the same interactive login shell, so every lifecycle operation resolves the same CLI installation. |
+
+#### C-PERF: Startup Performance (§9)
+
+| ID | PRD | Criterion |
+|---|---|---|
+| C-PERF-01 | §9.2 | Version/capability probes run asynchronously and never block the host process's event loop, so a roster of concurrent spawns does not serialize on a single thread. |
+| C-PERF-02 | §9.2 | Each adapter's `--version` is read at most once per parent process; concurrent first reads share a single subprocess, later reads reuse the cached result, and the cache is invalidated after every coordinated `autoupdate` attempt, including a failed or peer-owned attempt. |
+| C-PERF-03 | §9.2 | Any non-PTY probe (`--version`, `--help`, `update`) that exceeds the default runtime timeout (15s) or per-stream byte cap (1,000,000 bytes) is killed. A killed/failed `--version`/`--help` probe surfaces through `*_start_failed` with `cause`/`errno` (`ETIMEDOUT`/`E2BIG`) preserved in `details`; a killed/failed `update` probe is best-effort and instead surfaces the live `agent_update_failed` warning (same bounded diagnostics) without blocking startup. Probes that exit or fail to spawn on their own are not signaled. |
+| C-PERF-04 | §9.2 | With `autoupdate`, concurrent callers in one parent process share one update, and separate Elwood parent processes for the same macOS user and adapter serialize through an atomic lease in a stable account cache independent of `TMPDIR`. A contender waits asynchronously for the active updater, skips its duplicate attempt, invalidates its local caches, and validates the installed version; none races a second global update. The lease records owner identity and a unique generation: a live owner is never evicted solely because the stale bound elapsed, dead-owner recovery is serialized, and cleanup cannot remove a successor generation. |
+
+#### C-CLAUDE: Claude Startup And Settings (§4, §7, §9)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-CLAUDE-01 | §4.3 | Elwood does not mutate `.claude/settings.local.json` during normal startup. |
+| C-CLAUDE-02 | §4.3 | Elwood launches Claude with session-scoped generated settings passed through Claude's settings override mechanism. |
+| C-CLAUDE-03 | §7 | `permissionMode`, `allowedTools`, and `disallowedTools` options are reflected in Claude launch policy. |
+| C-CLAUDE-04 | §9.2 | Startup checks Claude Code version and fails with `claude_version_unsupported` when below the configured minimum. |
+| C-CLAUDE-05 | §10 | Missing `claude` fails with `claude_not_found` and a useful message. |
+| C-CLAUDE-06 | §10 | An immediately failing or unusable Claude process fails with `claude_start_failed` or a more specific typed error. |
+| C-CLAUDE-07 | §5.1 | `autoupdate: true` runs `claude update` before spawning Claude. |
+| C-CLAUDE-08 | §5.2 | `resumeClaude` fails explicitly when Elwood has not persisted a Claude resume id. |
+| C-CLAUDE-09 | §9.2 | `autoupdate: true` rechecks the Claude version after running `claude update`. |
+| C-CLAUDE-10 | §5.1 | `autotrust: true` answers Claude's workspace trust prompt through PTY input and emits `startup_prompt` activity, supporting both older numbered-option layouts and current cursor-selectable layouts. |
+| C-CLAUDE-11 | §5.1 | Claude's browser tools onboarding prompt is declined through PTY input regardless of `autotrust`, with `startup_prompt` activity emitted under the `browser_tools` label. |
+| C-CLAUDE-12 | §5.1 | `startClaude` forwards `model` to Claude's `--model` launch flag. |
+| C-CLAUDE-13 | §4.3 | `tools` emits Claude's `--tools` allowlist flag as one comma-separated value, with an empty array encoding `--tools ""` (all tools disabled); it is forwarded across resume like the other tool options. |
+| C-CLAUDE-14 | §5.1 | Under `autotrust`, Claude's allowlisted skill/plugin/MCP trust prompts are each answered once and emit `startup_prompt` activity under their `skill_trust`/`plugin_trust`/`mcp_trust` labels. Recognition is the only guard: a prompt is recognized solely by its HEADER wording outside the numbered or cursor-selectable option region (so an option-only trust phrase cannot spoof one), and once recognized Elwood sends or navigates to the first affirmative option in the current frame — the agent is never left waiting. When a recognized prompt's affirmative option has not rendered in the current frame yet, Elwood emits a fire-once transient `attention` activity and keeps watching so a later frame carrying the option is still answered; this render-delay state is TRANSIENT and no warning is emitted for it. An off-allowlist first-run prompt is never auto-answered. Per the say-yes policy there is deliberately no per-dialog region binding, so a second stacked dialog's affirmative in the same frame is an accepted consequence, not a defended boundary. |
+| C-CLAUDE-15 | §5.4 | Claude `assistant_message`, `tool_call`, and `tool_result` activities are sourced from the committed transcript the CLI writes at `transcript_path`, never from the `Stop` hook's `last_assistant_message`; an un-sent ghost-text / composer draft therefore never becomes an `assistant_message`. |
+| C-CLAUDE-16 | §5.1 §5.4 §5.7 | A Claude startup prompt Elwood auto-answers is marked settled and emits its `startup_prompt` activity only after its PTY `sendInput` write fulfills. A rejected write emits NO `startup_prompt` activity, leaves the prompt un-settled so a later frame re-attempts it, and surfaces a bounded, content-free `startup_prompt_write_failed` warning carrying only the prompt label. |
+| C-CLAUDE-17 | §5.1 | A Claude startup banner showing a lapsed, revoked, or absent login that only directs the user to re-run `/login` (`Login expired`, `Session expired`, `OAuth token revoked`, or `Not logged in`, each paired with a `run /login` recovery hint) is treated as an authentication failure and rejects `startClaude` with `claude_not_authenticated`, exactly like the explicit `not authenticated` banners — the session is torn down rather than reported as usable. Matching is anchored on the `/login` recovery directive so an unrelated mention of "login" does not trip it. |
+| C-CLAUDE-18 | §5.3 §5.7 | When a lapsed/revoked-login banner (per C-CLAUDE-17) appears on a Claude session that has ALREADY reached readiness — i.e. login expires mid-session — Elwood surfaces a typed, content-free `login_expired` warning (and its `warning` activity) carrying only a bounded `recoveryCommand` of `/login`. Detection is edge-based so a banner persisting across many frames does not re-emit, so a session warns at most once for its login expiring; the session is left ALIVE (no forced terminal transition) so the caller can recover in place via `session.login()`, tear down, or re-authenticate out of band. |
+| C-CLAUDE-19 | §5.4 §7A.4 | A committed Claude assistant `thinking` content block surfaces its plaintext extended-thinking as a `reasoning` activity carrying that text, sourced from the committed transcript exactly like `assistant_message` (C-CLAUDE-15) — no hook exposes it. Only ASSISTANT thinking is surfaced and empty thinking is dropped; a `redacted_thinking` block (opaque encrypted `data`, no readable text) produces no activity. |
+| C-CLAUDE-20 | §5.1 §5.2 | `reasoningEffort`, when supplied to `startClaude`/`resumeClaude`, is validated against the `ClaudeReasoningEffort` enum (`low`, `medium`, `high`, `xhigh`, `max`) before spawn — an out-of-enum value rejects with `claude_invalid_reasoning_effort` (message listing the valid values) and no process is spawned — and a valid value is forwarded to Claude's `--effort` launch flag. It is independent of `model`, applies to the launched session only, and is not persisted across resume (a resume must re-supply it). |
+| C-CLAUDE-21 | §5.1 §5.4 | Claude's one-time bypass-permissions acceptance dialog (header wording `Claude Code running in Bypass Permissions mode`, affirmative `Yes, I accept`, decline `No, exit`) is an allowlisted trust prompt: under `autotrust` it is recognized by its header wording outside the option region, answered once by selecting the affirmative in numbered or cursor layouts, and reported as `startup_prompt` activity with label `bypass_permissions`; with `autotrust` off it is a blocking prompt. The persistent `bypass permissions on` footer of a running session never matches, and a CLI refusal of bypass mode surfaces as the ordinary start failure. |
+
+#### C-CODEX: Codex Startup And Config (§4, §7A, §9)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-CODEX-01 | §4.4 | Elwood does not mutate `.codex/config.toml`, `.codex/hooks.json`, or user Codex config during normal startup. |
+| C-CODEX-02 | §4.4 | Elwood launches Codex with session-scoped hook config passed through `--config` overrides. |
+| C-CODEX-03 | §5.5 | `model`, `profile`, `sandbox`, `approvalPolicy`, and `configOverrides` options are reflected in Codex launch policy. |
+| C-CODEX-04 | §9.2 | Startup checks Codex CLI version and fails with `codex_version_unsupported` when below the configured minimum. |
+| C-CODEX-05 | §10 | Missing `codex` fails with `codex_not_found` and a useful message. |
+| C-CODEX-06 | §4.4 | Codex hooks are trusted by `hookTrust="trust-all"`, the bypass flag when supported, or by answering the allowlisted `Hooks need review` TUI prompt once regardless of `autotrust` (hook trust is Elwood's own integration; see C-CODEX-15). |
+| C-CODEX-07 | §5.6 | `resumeCodex` fails explicitly when Elwood has not persisted a Codex resume id. |
+| C-CODEX-08 | §5.5 | `autoupdate: true` runs `codex update` before spawning Codex. |
+| C-CODEX-09 | §5.7 | Codex MCP startup warnings are parsed from terminal output into typed warning events with server names and recovery commands. |
+| C-CODEX-10 | §9.2 | `autoupdate: true` rechecks the Codex version after running `codex update`. |
+| C-CODEX-11 | §5.5 | `autotrust: true` answers Codex's directory trust prompt through PTY input and emits `startup_prompt` activity. |
+| C-CODEX-12 | §5.5 | If Codex still shows an interactive update prompt inside the TUI, Elwood selects the skip/continue-without-updating option by label. The skip is EDGE-triggered: a persistent update screen starts one bounded response operation (not one per rendered frame), but that operation re-reads the current rendered frame before every retry and writes only when the original first-party prompt generation remains active and the frame exposes its safe numbered choice. It stops without writing when the generation clears or changes and fails boundedly if that prompt loses its safe choice or exhausts retries; the CLI converts an unanswerable blocked update into `blocked_prompt` even without a whole-run timeout. The skip RE-ARMS once the update screen leaves the frame, so an update prompt that REAPPEARS after Codex restarts (e.g. the update did not take and the same screen returns) is skipped again rather than leaving the session stuck on it. Every recognized update screen is input-blocking until its rendered frame clears: a captured first-party banner blocks before its options render, and a following safe-option-only continuation frame stays latched as the same prompt. Generic agent prose containing "update available" and Codex's passive installation notice do not activate the blocker. Readiness and queued persona/caller input therefore cannot select the default "Update now" action. |
+| C-CODEX-13 | §10 | An immediately failing or unusable Codex process fails with `codex_start_failed` or a more specific typed error. |
+| C-CODEX-14 | §5.3 | `setModel` on Codex restores the user's prior `config.toml` default via compare-and-swap after the CLI persists its picker selection, skipping with the `codex_default_model_persisted` warning instead of clobbering concurrent edits. The restore is written atomically (sibling temp file + rename, mode preserved, a symlinked config written through to its target) so a crash mid-restore can never leave the user's config truncated. When no `config.toml` existed before the switch and the CLI created one, there is no snapshot to restore: the new file is left in place and the same warning code carries a message saying so (not a false "changed in other ways"). |
+| C-CODEX-15 | §5.5 | Codex's directory-trust prompt is answered only under `autotrust` (blocking on the human when off); Codex hook trust — Elwood's own integration — is answered regardless of `autotrust` and is NOT classified as blocking. Each is recognized only by its HEADER wording on a non-option line (so an option-only phrase cannot spoof it) and, once recognized, answered from the frame's affirmative option — the agent is never left waiting. When a recognized prompt's affirmative option has not rendered yet, a fire-once transient `attention` activity is emitted and Elwood keeps watching so a later frame answers it; this render-delay state is TRANSIENT and no warning is emitted for it. Each is answered once, from the shared allowlist. |
+| C-CODEX-16 | §5.1 | Codex `assistant_message`, `tool_call`, and `tool_result` activities are sourced only from the committed transcript, never re-projected from the `Stop`/`PreToolUse`/`PostToolUse` hook payloads; those hooks emit plain `hook` activity, so a single reply or tool step is surfaced exactly once (mirrors C-CLAUDE-15). |
+| C-CODEX-17 | §5.4 §5.5 §5.7 | A Codex startup prompt Elwood auto-answers (directory/hook trust, `update` skip) is marked settled and emits its `startup_prompt` activity only after its PTY `sendInput` write fulfills. A rejected write emits NO `startup_prompt` activity, leaves the prompt un-settled so a later frame re-attempts it, and surfaces a bounded, content-free `startup_prompt_write_failed` warning carrying only the prompt label (mirrors C-CLAUDE-16). |
+| C-CODEX-18 | §5.4 §7A.4 | A committed Codex `reasoning` transcript item surfaces its human-readable text on the `reasoning` activity's `text` field: the `text` of every `summary[]` entry of type `summary_text`, or — when the reasoning is un-summarized — every `content[]` entry of type `reasoning_text`, joined by newlines. The always-present `encrypted_content` blob is never readable and is never surfaced. When neither carries prose (the common case with reasoning summaries disabled), the activity carries no `text`, exactly as a bare reasoning marker. |
+| C-CODEX-19 | §5.4 §7A.4 | A committed Codex shell/exec transcript item surfaces the ACTUAL command it ran as `tool_call` activity with its `toolInput`, and its output as `tool_result` activity with its `toolOutput`, across every representation the CLI emits — and the command is UNWRAPPED from the CLI's invocation machinery so consumers see the bare command, not the harness. The modern `exec` tool is a `custom_tool_call` whose `input` is a JavaScript snippet wrapping the call (e.g. `const r = await tools.exec_command({"cmd":"echo hi","workdir":…,"yield_time_ms":…}); text(r.output);`): Elwood extracts the inner `cmd`/`command` string (a `command` array is joined with spaces) and surfaces THAT as `toolInput`, discarding the JS wrapper and the non-command fields (`workdir`, `yield_time_ms`, `max_output_tokens`). A `function_call` (`shell`/`exec_command`) whose command is a JSON string in `arguments` is likewise unwrapped to its `command`/`cmd`. When the wrapper cannot be parsed, the raw `input`/`arguments` is surfaced unchanged rather than dropped. A `custom_tool_call_output` is classified as `tool_result` (not `other`), and a result's `output` — a plain string OR an array of `{ type: "input_text", text }` entries — is surfaced as `toolOutput` with the array entries' text joined; the `tool_result` `label` carries the `call_id` correlating it to its `tool_call`. So the real command and its output are surfaced as a clean paired call/result, never the JS harness and never a content-free `other` row. |
+| C-CODEX-21 | §5.5 §5.6 | `reasoningEffort`, when supplied to `startCodex`/`resumeCodex`, is validated against the `CodexReasoningEffort` enum (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) before spawn — an out-of-enum value rejects with `codex_invalid_reasoning_effort` (message listing the valid values) and no process is spawned — and a valid value is forwarded as the reserved `-c model_reasoning_effort=<value>` override, applied AFTER caller `configOverrides` so it wins over a hand-rolled duplicate. It is independent of `model`, applies to the launched session only, and is not persisted across resume (a resume must re-supply it). |
+| C-CODEX-20 | §5.4 | The Codex transcript reader is BOUNDED like Claude's: it reads in fixed-size chunks, discards any un-terminated record past a max-pending ceiling as an `"oversized"` drop, streams a large backlog across poll ticks under a per-scan chunk budget, and at PTY-exit drains only within a bounded chunk budget and wall-clock slice — accounting leftover bytes as an `"unread_backlog"` drop — so a hundreds-of-MiB transcript never OOMs or blocks the event loop. An unblocked `Stop` reads the committed turn with the per-pass scan budget, never the PTY-exit drain budget, so an arbitrarily long session (hundreds of turns) never exhausts that budget into false `unread_backlog` drops. Lost data is surfaced as the content-free, count-free `transcript_records_dropped` warning (a live event, cause-tagged, not persisted or counted) and a scan that throws is contained as `transcript_poll_stopped` (both `agent: "codex" | "claude"`). `finish()` is idempotent and terminal — a late `observe()` never restarts polling past `terminal:exit`. |
+
+#### C-HOOK: Hook Bridge Coverage And Semantics (§6)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-HOOK-01 | §6.1 | Generated Claude settings include bridge handlers for every supported Claude hook event. |
+| C-HOOK-02 | §6.2 | Hook bridge invocations route to the correct Elwood session using session-scoped identity. |
+| C-HOOK-03 | §6.3 | A hook event with no registered parent handler returns no decision to Claude. |
+| C-HOOK-04 | §6.3 | A timed-out hook handler returns no decision to Claude and emits `hookError`. |
+| C-HOOK-05 | §6.3 | A throwing/rejecting hook handler returns no decision to Claude and emits `hookError`. |
+| C-HOOK-06 | §6.3 | An invalid handler result returns no decision to Claude and emits `hookError`. |
+| C-HOOK-07 | §6.4 | Hook IPC input is runtime-validated before dispatch to parent handlers. |
+| C-HOOK-08 | §6.4 | `hook_event_name` narrows valid handler response types at compile time. |
+| C-HOOK-09 | §6.4 | Known Claude built-in tool names narrow `tool_input` types at compile time. |
+| C-HOOK-10 | §6.4 | Unknown or MCP tool names are represented through a safe extensibility path. |
+| C-HOOK-11 | §6.5 | `Stop` marks the session ready only when the Stop event is not blocked. |
+| C-HOOK-12 | §7A.1 | Generated Codex config includes bridge handlers for every supported Codex hook event. |
+| C-HOOK-13 | §7A.2 | Codex hook IPC input is runtime-validated before dispatch to parent handlers. |
+| C-HOOK-14 | §7A.2 | Codex `hook_event_name` narrows valid handler response types at compile time. |
+| C-HOOK-15 | §7A.3 | Codex `Stop` marks the session ready only when the Stop event is not blocked. |
+| C-HOOK-16 | §6.2 | Hook IPC waits for a complete framed request before dispatching and fails open on malformed complete requests. A single request is capped at exactly 8 MiB (8,388,608 bytes) measured on the ENCODED wire envelope (`{token, elwoodSessionId, input}` JSON plus its framing newline) — the identical byte count in the child bridge script (before it connects) and the parent server (as bytes arrive), so an escape-heavy input whose JSON encoding expands past the cap is rejected by both, never accepted by one and dropped by the other. An over-cap request fails open before auth/parse (child exits with no decision; server responds no-decision and closes) and does not emit a `hookError`. |
+| C-HOOK-17 | §6.4 | Claude hook IPC input validates event-specific payload fields and known tool input schemas before dispatch. |
+
+#### C-HRESP: Hook Response Mapping (§6, §7)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-HRESP-01 | §6.4 | `PreToolUse` handlers can return allow, deny, ask, defer, updated input, and additional context according to Claude's schema. |
+| C-HRESP-02 | §7 | `AskUserQuestion` input is strongly typed and can be answered through `updatedInput.answers`. |
+| C-HRESP-03 | §6.4 | `Stop` handlers can block stopping with a reason. |
+| C-HRESP-04 | §6.4 | Observe-only events such as `Notification` cannot return blocking decisions through the public type API. |
+| C-HRESP-05 | §6.4 | `Elicitation` and `ElicitationResult` support typed accept/decline/cancel response shapes. |
+| C-HRESP-06 | §6.4 | Hook responses serialize to Claude-compatible JSON or no-output results. |
+| C-HRESP-07 | §7A.2 | Codex `PreToolUse` handlers can deny, allow, allow with rewritten input, or add context according to Codex's schema. |
+| C-HRESP-08 | §7A.2 | Codex `PermissionRequest` handlers can allow or deny and cannot return future-only invalid fields. |
+| C-HRESP-09 | §7A.2 | Codex `Stop` and `SubagentStop` handlers can request continuation with a reason. |
+| C-HRESP-10 | §7A.2 | Codex hook responses serialize to Codex-compatible JSON or no-output results. |
+
+#### C-STATE: State And Resume (§8, §9)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-STATE-01 | §8.1 | Default state is written under `<cwd>/.elwood/`; planted state-directory and generated-file links are rejected before changing external contents or modes (§8.1/8.2). |
+| C-STATE-02 | §8.1 | Passing `stateDir` stores state under the caller-provided directory. |
+| C-STATE-03 | §8.2 | Session metadata is written atomically. |
+| C-STATE-04 | §8.2 | Session metadata contains enough information to resume after parent process restart. |
+| C-STATE-05 | §8.3 | Raw PTY input/output is not persisted by default. |
+| C-STATE-06 | §8.3 | Hook payloads and responses are not persisted by default. |
+| C-STATE-07 | §8.4 | `stop()` preserves session metadata and generated files. |
+| C-STATE-08 | §8.4 | `teardown()` removes Elwood-owned session metadata and generated files. |
+| C-STATE-09 | §8.4 | `teardown()` does not remove Claude-owned auth, transcripts, or user/project settings. |
+| C-STATE-10 | §5.2, §5.6 | Resume APIs reject session records whose persisted adapter does not match the requested adapter. |
+| C-STATE-11 | §8.1 | Elwood does not overwrite an existing `.elwood/.gitignore` or create gitignore files in custom `stateDir` directories. |
+| C-STATE-13 | §8.2 | The session record persists the resolved launch posture (privilege and tool policy) at start, validates it on read, and resume updates it to the effective values. |
+| C-STATE-12 | §8.1 | Sessions start successfully with arbitrarily long `stateDir` paths because the hook bridge socket binds in a short Elwood-owned temp home. The home is STABLE per session (a bounded fingerprint of the session's full identity — `stateDir`, adapter, and id), so every start/resume resolves the same one while a shared explicit id in a different state dir resolves a DISTINCT home; each launch binds a fresh socket FILE inside it, and teardown removes the whole home so no per-launch socket leaks across restart/resume. |
+| C-LIFE-09 | §9.2 | `autoupdate` runs the adapter's update command at most once per parent process per adapter, so fleet spawns do not race N concurrent same-binary updates. Separate Elwood parent processes for the same macOS user and adapter also hold an atomic cross-process lease around that global update; contenders wait asynchronously, skip the duplicate update, invalidate their own caches, and validate the installed binary after the owner settles. The stable per-account lease records owner identity and generation, never evicts a live owner solely for age, serializes dead-owner recovery, and cannot be removed by an old owner after a successor claims it. A FAILED in-process shared update is shared once too — concurrent callers observe the same failure and proceed through the compatibility gate — and is not retried per start nor retained as a rejected result that poisons later starts. |
+| C-LIFE-11 | §9.2 | Autoupdate is BEST-EFFORT: when the update command fails but the installed CLI still meets the minimum version, startup emits a live `agent_update_failed` warning (safe diagnostics only) and reaches `ready` from the installed binary; startup fails only when the installed version is below the minimum. Version and capability caches are invalidated even after a failed attempt because the installer may have partially changed the binary. No per-process cached probe (version read, capability detection, update) retains a rejected result — a later caller re-attempts rather than inheriting a prior failure. |
+| C-ERR-08 | §10 | Startup failures carry the underlying cause, and errno/syscall/path details when the underlying error provides them. |
+
+#### C-LIFE: Lifecycle Controls (§5, §9)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-LIFE-01 | §9.1 | Startup initializes state, generated settings, IPC, PTY, and Claude before resolving `startClaude`. |
+| C-LIFE-02 | §5.3 | `stop()` attempts graceful termination and updates status. |
+| C-LIFE-03 | §5.3 | `kill()` force-terminates the Claude process and updates status. |
+| C-LIFE-04 | §9.3 | `resumeClaude` restores hook routing and PTY control for a saved Elwood session. |
+| C-LIFE-05 | §5.3 | A live `ClaudeSessionApi` (the started session) owns exactly one main Claude process; the lazy `ClaudeSession` wrapper (§5.8) owns none before start and that one after. |
+| C-LIFE-10 | §5.3 | `stop()`, `kill()`, and `teardown()` reap the full PTY process tree by SIGKILLing the leader's process group, so a descendant reparented to PID 1 after the leader exits (e.g. the CLI-spawned `hook-bridge.mjs`) is still killed and no process tree leaks across launch/quit cycles. |
+| C-LIFE-11 | §5.3 | A `teardown()` that rejects in-flight control-queue operations still completes: the rejected `sendMessage`/`compact`/model operation does not skip the process-group reap or remaining teardown steps. |
+
+#### C-ERR: Error Model (§10)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-ERR-01 | §10 | Public failures use stable typed error names. |
+| C-ERR-02 | §10 | Unsupported platforms fail with `unsupported_platform`. |
+| C-ERR-03 | §10 | Missing state for resume/teardown fails with `state_not_found`. |
+| C-ERR-04 | §10 | Corrupt state fails with `state_corrupt`. |
+| C-ERR-05 | §10 | PTY startup failure fails with `pty_start_failed`. |
+| C-ERR-06 | §10 | Hook IPC initialization failure fails with `hook_bridge_failed`. |
+| C-ERR-07 | §9.2 | Unparseable non-strict CLI versions produce a typed `version_unparseable` warning. |
+
+#### C-APP: Local Test App (§11)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-APP-01 | §11 | The test app can start a Claude session for a selected cwd. |
+| C-APP-02 | §11 | The test app can resume a saved Elwood session ID. |
+| C-APP-03 | §11 | The test app renders live PTY output in a terminal view. |
+| C-APP-04 | §11 | The test app can send single-line and multi-line prompts. |
+| C-APP-05 | §11 | The test app shows a chronological live hook/event log. |
+| C-APP-06 | §11 | The event log summarizes handler result semantics: no decision, allow, deny, block, context, or error. |
+| C-APP-07 | §11 | The test app can resize the terminal and the Claude TUI responds. |
+| C-APP-08 | §11 | The web dev app immediately force-kills itself and child processes on SIGINT, and cleans up owned resources and child processes on SIGTERM/SIGHUP/job-control signals without reading from stdin. |
+| C-APP-09 | §11 | The web dev app emits structured debugger entries for hooks, activity, warnings, hook errors, lifecycle status, terminal exits, and runtime errors. |
+| C-APP-10 | §11 | The web dev app renders filterable, visually delineated debugger rows with a formatted JSON detail inspector. |
+| C-APP-11 | §11 | Runnable example package scripts execute PTY-owning TypeScript examples under a Node supervisor, remain invokable through `npm run`, and do not mirror raw wrapped-agent terminal output into the caller's shell. |
+
+#### C-CLI: Headless Command-Line Interface (§12A)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-CLI-01 | §12A | Local, git, and packed-tarball installs expose an executable `elwood` bin and an importable library entry backed only by emitted JavaScript and declarations under `dist`, on Node.js 24 or newer. The published package declares NO install scripts of its own (`prepare`, `install`, `postinstall`): `dist` is built before publish and shipped in the tarball, so `npm install -g @with-logic/elwood` yields a working executable without building and without an install-script approval prompt for Elwood. |
+| C-CLI-02 | §12A.1 | Direct and explicit `run` forms are equivalent; an argument-free invocation, top-level/config help, and version complete without stdin/config reads or agent launch; `elwood run` still requires input; and reserved command words are commands only in first-argument position before `--`. |
+| C-CLI-03 | §12A.1 | New sessions default to the invocation cwd and, when nothing selects an agent, to the first available of Claude then Codex (C-CLI-21); explicit cwd overrides the workspace, an unavailable selected adapter never falls back, and resume uses its validated stored adapter and cwd exactly while rejecting `--cwd`. |
+| C-CLI-04 | §12A.1 | Positional and piped input compose with one blank line, terminal stdin is not read, whitespace-only input fails before launch, UTF-8 input is incrementally limited to 8 MiB, and ordered image flags attach on the user turn. |
+| C-CLI-05 | §12A.2 | A CLI turn preserves Elwood's real interactive environment and auto-authorizes only its documented trust classes; disabled or unrecognized trust automation fails as `blocked_prompt` without submitting into the dialog. |
+| C-CLI-06 | §12A.2 | Built-in and selected per-agent permission, sandbox, approval, model, effort, and persona settings validate against the effective adapter before launch. |
+| C-CLI-07 | §12A.2 | An optional duration bounds launch, setup, and turn; first and repeated `SIGINT` perform interrupt then force-kill behavior; timeout and interruption exit 124 and 130 respectively. |
+| C-CLI-08 | §12A.2 §12A.5 | New Elwood state tears down unless kept, resumed state preserves unless ephemeral, exact resume never falls back, teardown does not undo workspace/agent-owned state, and persona is one output-discarded but side-effect-capable new-session setup turn that is rejected on resume. |
+| C-CLI-09 | §12A.2 | Premature agent exit and cleanup failure retain collected response data; cleanup runs once, never replaces a primary failure, and changes otherwise-successful execution to status 1. |
+| C-CLI-10 | §12A.3 | Default text output contains only the combined observed assistant messages with exact separator/newline semantics; text/JSON warnings surface concisely on stderr; verbose emits concise elapsed progress without assistant/thinking duplication; debug detail stays on stderr; and streamed text is emitted once with partial output retained on failure. |
+| C-CLI-11 | §12A.3 | JSON emits one version-1 terminal document and JSONL emits ordered normalized records plus exactly one terminal record, including structured validation errors when explicitly selected; every JSONL record has `elapsedMs` and tool records carry `toolCallId` when available. An error record emitted before any adapter was selected reports `agent: null`; otherwise `agent` is the selected or running adapter. |
+| C-CLI-12 | §12A.3 | Output excludes terminal and secret-bearing internals, honors backpressure, and treats downstream `EPIPE` as graceful consumer closure followed by cleanup. |
+| C-CLI-13 | §12A.4 | Config path resolution follows explicit, absolute XDG, then home fallback order; config is strict version 1 with only documented keys, and project-local config is ignored. |
+| C-CLI-14 | §12A.4 | Flag, environment, config, and built-in precedence is deterministic, environment booleans are strict, negative flags reverse inherited stream/verbose/high-trust values, `--no-defaults` bypasses Elwood run defaults, and config path/show/get/set/unset/effective never launches an agent (agent auto-detection only asks the login shell whether a command resolves). |
+| C-CLI-15 | §12A.4 §12A.5 | Config and state reads and writes enforce private ownership, regular-file, symlink-safety, and atomicity constraints. |
+| C-CLI-16 | §12A.5 | CLI state defaults to the absolute XDG state base or `~/.local/state/elwood`, never the workspace, and one session identity has at most one live owner. |
+| C-CLI-17 | §12A.5 | Success, agent/cleanup failure, usage/config failure, timeout, and interruption map to statuses 0, 1, 2, 124, and 130 without cleanup masking a primary status. |
+| C-CLI-18 | §12A.6 | `--head` fails before launch without terminal stdin/stderr and rejects stream/verbose/debug/JSONL; otherwise it mirrors ordered raw PTY bytes (including full-screen VT/ANSI control sequences) only to terminal stderr, uses and follows its size, keeps final text/JSON stdout clean, treats raw Ctrl-C like SIGINT, and restores terminal input/display modes before final output on every handled outcome. Outstanding mirror work is capped at 4 MiB or 1,024 frames; overflow fails the run after draining accepted bytes and restoring the terminal instead of growing memory without bound. A terminal-gone error from an input handle already closed by its host is contained because only that host can then restore the terminal, and it does not replace a completed result. |
+| C-CLI-19 | §12A.4 | `config effective` prints validated effective launch/output values (including `head` and the full Claude tool posture) with config location/load state and per-setting provenance (including `auto-detected` for a probed agent), supports exact stored resume inspection using the same posture merge as launch, reads no prompt input, and starts no agent. |
+| C-CLI-20 | §12A.5 | Text validation errors use user-facing language, identify relevant paths and inherited-setting sources, suggest an unambiguous nearby long option, and retain the stable structured error code. |
+| C-CLI-21 | §12A.1 §12A.4 | When no flag, environment variable, or config key selects an agent, a new session (and `config effective`) probes the user's login shell for `claude` and `codex` concurrently and uses the first in that order whose command resolves, reporting source `auto-detected`; the probe never runs an agent, resume never probes, and when neither resolves the invocation fails before launch with code `no_agent_found` and status 2, naming both agents, an install hint, and the `--agent`/`ELWOOD_AGENT`/config selection paths. A probe that cannot run (missing or broken login shell, probe timeout) fails with the same code and status but names the shell and underlying error rather than claiming no agent is installed; adapter-option conflicts with an auto-detected agent say so and offer `--agent` for the other adapter. |
+| C-CLI-22 | §12A.2 §12A.4 | `--high-trust` / `--no-high-trust`, `ELWOOD_HIGH_TRUST` (strict boolean), and the `highTrust` config key layer with normal precedence and expand, for the effective adapter, to Claude `bypassPermissions` or Codex `danger-full-access` + `never`; an effective flag/environment `true` combined with an explicit per-agent posture flag or variable is a usage error naming both sources on new and resumed runs; saved per-agent posture keys are overridden by high trust while a saved `highTrust` yields field by field to explicit per-agent flags/variables; and `config effective` reports `highTrust` plus posture values whose source is the deciding high-trust source. |
+| C-CLI-23 | §12A.7 | `elwood resume <id> [options] [prompt...]` is a parse-time rewrite of `elwood run --resume <id>` sharing one resolution/execution path: stored adapter and workspace loading, `--cwd`/explicit-adapter/`--keep`/persona/`--ephemeral` rules, and positional-plus-piped prompt composition are identical; a missing id or an additional `--resume` is a usage error. |
+| C-CLI-24 | §12A.8 | `elwood sessions` lists private, owner-matched session records under the effective state directory without launching an agent, reporting id, adapter, workspace, ISO-8601 `createdAt`/`lastUsedAt`, `resumable`, and socket-presence `live`, ordered by most recent use; unreadable records are skipped with a stderr warning, an empty or absent state directory is a status-0 empty listing (stderr notice in text, empty array in JSON), text is an aligned header table, JSON is one version-1 `sessions` document, and JSONL, prompt words, or other run options are usage errors. |
+| C-CLI-25 | §12A.9 | `elwood interactive [id]` spawns the selected agent's own CLI in the foreground with inherited stdio, no PTY/bridge/automation/state, `SIGINT` passed through, and the agent's exit status; it fails with status 2 before spawning without terminal stdin and stdout or with `--output json|jsonl`, `--stream`, `--verbose`, `--debug`, `--head`, `--timeout`, `--persona`, `--image`, `--keep`, `--ephemeral`, `--resume`, or extra positionals; explicitly selected agent, model, effort, workspace, and posture map through the adapters' shared launch-argument builders while built-in posture defaults are omitted; and `[id]` loads the stored record with `--resume` semantics, merges stored posture field by field, and passes the agent's own conversation id or fails as `resume_unavailable`. |
+| C-CLI-26 | §12A.10 | `elwood models` starts a fresh headless session with normal setting precedence, lists models through the public picker operation without changing the model, always tears the session and its state down, prints an aligned table (`*` current, `(default)`) or one version-1 `models` document of `AgentModelOption` rows, maps timeout/interruption/blocked-prompt/agent-exit/picker failures to the existing error conventions and statuses, and rejects stream, head, persona, image, keep, resume, ephemeral, positional, and JSONL inputs as usage errors. |
+
+#### C-E2E: Real Adapter Flows (§12)
+
+| ID | Section | Criterion |
+|---|---:|---|
+| C-E2E-01 | §12 | `npm run test:e2e` runs real public API session flows outside the default `npm run check` gate. |
+| C-E2E-02 | §12 | Claude e2e coverage starts a real Claude PTY, observes terminal data, sends input/message text, observes hooks/activity, resizes, stops, resumes when possible, and tears down Elwood-owned state. |
+| C-E2E-03 | §12 | Codex e2e coverage starts a real Codex PTY, observes terminal data, sends input/message text, observes hooks/activity/transcript where available, resizes, stops, resumes when possible, and tears down Elwood-owned state. |
+| C-E2E-04 | §12 | Real adapter e2e tests skip only for local prerequisite failures such as a missing CLI; they do not replace adapter flows with fake PTYs, fake CLIs, or fake hook bridges. |
+| C-E2E-05 | §12 | `npm run check:all` runs the default `npm run check` gate followed by `npm run test:e2e`, without changing the composition of `npm run check`. |
+| C-E2E-06 | §4.5 | A real session started in a project with its own agent configuration loads that configuration additively: project-defined hooks fire alongside Elwood's bridge hooks and project instruction files are loaded by the agent. |
+| C-E2E-07 | §5.4 | A real committed Claude turn surfaces an `assistant_message` with `source: "transcript"` and a `transcriptPath`, and no `assistant_message` is emitted with `source: "hook"` (C-CLAUDE-15). |
+| C-E2E-08 | §5.4 | A real Claude tool turn surfaces `tool_call` and `tool_result` with `source: "transcript"`, correlated `toolUseId`s, and serialized input/output, and no `tool_call`/`tool_result` is emitted with `source: "hook"` (C-CLAUDE-15). |
+| C-E2E-10 | §5.1 | A real committed Codex turn surfaces exactly one `assistant_message` (with `source: "transcript"`), never a second copy from the `Stop` hook (C-CODEX-16). |
+| C-E2E-11 | §5.3 | A real Codex session with a queued initial persona delivers that message to Codex (a `UserPromptSubmit` with the persona text is observed) rather than swallowing it — the queue is released on `SessionStart`, not on the boot-time composer placeholder (C-API-28). |
+| C-E2E-12 | §5.3 | A real Claude session attaches an image supplied via `sendMessage(message, { images })` — pasting the absolute path drives the CLI to show its `[Image #N]` chip in the rendered composer — verified against the installed CLI (C-API-45). |
+| C-E2E-13 | §5.3 | A real Codex session on macOS attaches an image supplied via `sendMessage(message, { images })` — the clipboard-injection + Ctrl+V path drives the CLI to show its `[Image #N]` chip in the rendered composer, and the user's prior clipboard is restored afterward — verified against the installed CLI (C-API-46). |
+| C-E2E-09 | §5.1 | The trust-prompt allowlist recognizes and answers the REAL folder-trust frame the installed Claude CLI renders in a fresh untrusted directory (header-anchored recognition + numbered or cursor affirmative selection), verifies the trust screen clears before readiness, and fails if a fully rendered trust frame is visible but unanswerable; it skips loudly only when no trust frame renders (for example, an already trusted directory). |
+| C-E2E-14 | §5.8 | Against a REAL Claude (or Codex) CLI, a lazily-started `ClaudeSession`/`CodexSession` answers two sequential `send` calls: the first returns non-empty assistant text, and the second — referring back to the first — returns text consistent with retained conversation context, proving `send` collects a turn's assistant text and the ergonomic layer preserves multi-turn context (C-API-47, C-API-49). |
+| C-E2E-15 | §5.8 | Against a REAL CLI, `stream(prompt)` for a task that DETERMINISTICALLY uses a workspace tool (reading a planted file) yields the turn's simplified typed events in arrival order — a `tool_call` FOLLOWED by its `tool_result`, and at least one `text` — and ends when the turn settles, verified against the installed CLI (C-API-48). |
+| C-E2E-16 | §5.1 §5.5 | Against the REAL CLIs, a session started with `highTrust: true` reaches `ready` on both adapters: Claude's rendered composer shows its bypass-permissions footer with no acceptance dialog left visible (answered when the installed CLI renders one), and Codex's persisted launch posture is `danger-full-access` / `never` (C-API-54, C-CLAUDE-21). |

package/prd/15-open-notes.md

@@ -0,0 +1,8 @@
+## 15. Open Implementation Notes
+
+- The preferred PTY implementation is still to be selected. The public behavior
+  requires a real PTY; the library choice is not part of this PRD.
+- The hook bridge should start with Unix domain sockets on macOS unless an
+  implementation spike shows a better local-only IPC path.
+- A future PRD revision should define the adapter interface for non-Claude tools
+  after the Claude adapter proves the core model.

package/prd/README.md

@@ -0,0 +1,45 @@
+# Elwood — Product Requirements Document
+
+**A headless control layer for real interactive agentic coding CLIs.**
+
+Status: Draft specification, ready for implementation planning
+Platform: macOS for MVP
+Primary surface: TypeScript library
+First adapter: Claude Code CLI
+Second adapter: OpenAI Codex CLI
+
+This document specifies Elwood in enough detail that an engineer can implement
+the first version without losing product intent. Anything observable by a
+library consumer belongs here: public APIs, lifecycle behavior, hook semantics,
+state layout, failure modes, and conformance criteria. Internal implementation
+choices are left open where they do not change the public contract.
+
+This specification is split across the files below. Each file keeps its
+original section number, so a reference like §12A.7 or C-CLI-23 still
+resolves exactly as it did when this was one document.
+
+| Section | Topic | File |
+|---|---|---|
+| §1 | Overview | [01-overview.md](01-overview.md) |
+| §2 | Goals and non-goals | [02-goals.md](02-goals.md) |
+| §3 | Terminology | [03-terminology.md](03-terminology.md) |
+| §4 | Product architecture | [04-architecture.md](04-architecture.md) |
+| §5 | Public TypeScript API | [05-api/README.md](05-api/README.md) |
+| §6 | Claude hook bridge | [06-claude-hook-bridge.md](06-claude-hook-bridge.md) |
+| §7 | Claude tool and permission policy | [07-claude-policy.md](07-claude-policy.md) |
+| §7A | Codex hook bridge and policy | [07a-codex-hook-bridge.md](07a-codex-hook-bridge.md) |
+| §8 | State and persistence | [08-state.md](08-state.md) |
+| §9 | Process lifecycle | [09-lifecycle.md](09-lifecycle.md) |
+| §10 | Error model | [10-errors.md](10-errors.md) |
+| §11 | Local test app | [11-test-app.md](11-test-app.md) |
+| §12 | End-to-end testing | [12-e2e.md](12-e2e.md) |
+| §12A | Headless command-line interface | [12a-cli.md](12a-cli.md) |
+| §13 | Implementation latitude | [13-latitude.md](13-latitude.md) |
+| §14 | Conformance | [14-conformance.md](14-conformance.md) |
+| §15 | Open implementation notes | [15-open-notes.md](15-open-notes.md) |
+
+## Conformance criteria
+
+Every criterion ID (`C-API-*`, `C-CLI-*`, `C-CLAUDE-*`, `C-E2E-*`, and the
+rest) is defined in [14-conformance.md](14-conformance.md). Tests name the
+criterion they cover in their titles.

package/dist/claude/hook-dispatch.d.ts

@@ -1,9 +0,0 @@
-/**
- * Claude hook handler dispatch: the shared fail-open dispatcher bound to the
- * Claude result validator, plus block detection for `Stop`.
- * Implements PRD §6.3 and §6.4.
- */
-import type { ClaudeHookEvent, ClaudeHookResult } from "./hooks.ts";
-export declare const requestHook: import("../core/hook-dispatch.ts").HookDispatcher<ClaudeHookEvent, ClaudeHookResult>;
-export declare function isBlock(result: ClaudeHookResult): boolean;
-//# sourceMappingURL=hook-dispatch.d.ts.map

package/dist/claude/hook-dispatch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hook-dispatch.d.ts","sourceRoot":"","sources":["../../src/claude/hook-dispatch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGpE,eAAO,MAAM,WAAW,sFAGvB,CAAC;AAEF,wBAAgB,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAEzD"}

package/dist/claude/hook-dispatch.js

@@ -1,12 +0,0 @@
-/**
- * Claude hook handler dispatch: the shared fail-open dispatcher bound to the
- * Claude result validator, plus block detection for `Stop`.
- * Implements PRD §6.3 and §6.4.
- */
-import { createHookDispatcher } from "../core/hook-dispatch.js";
-import { isClaudeHookResult } from "./validate-result.js";
-export const requestHook = createHookDispatcher("claude", isClaudeHookResult);
-export function isBlock(result) {
-    return Boolean(result && "decision" in result && result.decision === "block");
-}
-//# sourceMappingURL=hook-dispatch.js.map

package/dist/claude/hook-dispatch.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hook-dispatch.js","sourceRoot":"","sources":["../../src/claude/hook-dispatch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,CAAC,MAAM,WAAW,GAAG,oBAAoB,CAC7C,QAAQ,EACR,kBAAkB,CACnB,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,MAAwB;IAC9C,OAAO,OAAO,CAAC,MAAM,IAAI,UAAU,IAAI,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;AAChF,CAAC"}

package/dist/claude/hook-events-extra.d.ts

@@ -1,81 +0,0 @@
-/**
- * Less central Claude hook event payload fragments.
- * Implements PRD §6.
- */
-import type { ClaudeStopFailureError, ClaudeStopFields, ClaudeTaskFields } from "./hook-events.ts";
-import type { ClaudeCommonHookFields } from "./hook-names.ts";
-export type TaskCreatedEvent = ClaudeCommonHookFields & ClaudeTaskFields & {
-    readonly hook_event_name: "TaskCreated";
-};
-export type TaskCompletedEvent = ClaudeCommonHookFields & ClaudeTaskFields & {
-    readonly hook_event_name: "TaskCompleted";
-};
-export type StopEvent = ClaudeCommonHookFields & ClaudeStopFields & {
-    readonly hook_event_name: "Stop";
-};
-export type StopFailureEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "StopFailure";
-    readonly error: ClaudeStopFailureError | string;
-    readonly error_details?: string;
-    readonly last_assistant_message?: string;
-};
-export type TeammateIdleEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "TeammateIdle";
-    readonly teammate_name: string;
-    readonly team_name: string;
-};
-export type ConfigChangeEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "ConfigChange";
-    readonly source: "user_settings" | "project_settings" | "local_settings" | "policy_settings" | "skills" | string;
-    readonly file_path?: string;
-};
-export type CwdChangedEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "CwdChanged";
-    readonly old_cwd: string;
-    readonly new_cwd: string;
-};
-export type FileChangedEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "FileChanged";
-    readonly file_path: string;
-    readonly event: "change" | "add" | "unlink";
-};
-export type WorktreeCreateEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "WorktreeCreate";
-    readonly name: string;
-};
-export type WorktreeRemoveEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "WorktreeRemove";
-    readonly worktree_path: string;
-};
-export type PreCompactEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "PreCompact";
-    readonly trigger: "manual" | "auto";
-    readonly custom_instructions?: string | null;
-};
-export type PostCompactEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "PostCompact";
-    readonly trigger: "manual" | "auto";
-    readonly compact_summary: string;
-};
-export type SessionEndEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "SessionEnd";
-    readonly reason: "clear" | "resume" | "logout" | "prompt_input_exit" | "bypass_permissions_disabled" | "other" | string;
-};
-export type ElicitationEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "Elicitation";
-    readonly mcp_server_name: string;
-    readonly message: string;
-    readonly mode?: "form" | "url" | string;
-    readonly url?: string;
-    readonly elicitation_id?: string;
-    readonly requested_schema?: Readonly<Record<string, unknown>>;
-};
-export type ElicitationResultEvent = ClaudeCommonHookFields & {
-    readonly hook_event_name: "ElicitationResult";
-    readonly mcp_server_name: string;
-    readonly action: string;
-    readonly mode?: "form" | "url" | string;
-    readonly elicitation_id?: string;
-    readonly content?: Readonly<Record<string, unknown>>;
-};
-//# sourceMappingURL=hook-events-extra.d.ts.map

package/dist/claude/hook-events-extra.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hook-events-extra.d.ts","sourceRoot":"","sources":["../../src/claude/hook-events-extra.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GACnD,gBAAgB,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAA;CAAE,CAAC;AAEjE,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GACrD,gBAAgB,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,SAAS,GAAG,sBAAsB,GAC5C,gBAAgB,GAAG;IAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG;IACtD,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG;IACvD,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG;IACvD,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,MAAM,EACX,eAAe,GACf,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,GACjB,QAAQ,GACR,MAAM,CAAC;IACX,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG;IACrD,QAAQ,CAAC,eAAe,EAAE,YAAY,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG;IACtD,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,sBAAsB,GAAG;IACzD,QAAQ,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,sBAAsB,GAAG;IACzD,QAAQ,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG;IACrD,QAAQ,CAAC,eAAe,EAAE,YAAY,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAEpC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG;IACtD,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG;IACrD,QAAQ,CAAC,eAAe,EAAE,YAAY,CAAC;IACvC,QAAQ,CAAC,MAAM,EACX,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,mBAAmB,GACnB,6BAA6B,GAC7B,OAAO,GACP,MAAM,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG;IACtD,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,sBAAsB,GAAG;IAC5D,QAAQ,CAAC,eAAe,EAAE,mBAAmB,CAAC;IAC9C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD,CAAC"}