@with-logic/elwood 0.1.1 → 0.1.3

package/prd/05-api/5.3-claude-session-api.md

@@ -0,0 +1,658 @@
+## 5.3 ClaudeSessionApi (the raw live session)
+
+```ts
+interface ClaudeSessionApi {
+  readonly elwoodSessionId: string;
+  readonly cwd: string;
+  readonly status: ElwoodSessionStatus;
+  readonly terminal: ElwoodTerminal;
+
+  statusDecisions(): readonly ElwoodStatusDecision[];
+  waitForStatus(
+    match: (status: ElwoodSessionStatus) => boolean,
+    timeoutMs?: number,
+  ): Promise<ElwoodSessionStatus>;
+  waitForActivity(
+    match: (event: ElwoodActivityEvent) => boolean,
+    timeoutMs?: number,
+  ): Promise<ElwoodActivityEvent>;
+
+  on<E extends ClaudeEventName>(event: E, handler: ClaudeEventHandler<E>): Unsubscribe;
+  off<E extends ClaudeEventName>(event: E, handler: ClaudeEventHandler<E>): void;
+
+  sendPrompt(prompt: string, options?: SendOptions): Promise<void>;
+  sendMessage(message: string, options?: SendOptions): Promise<void>;
+  sendGuidance(message: string, options?: SendOptions): Promise<void>;
+  sendKeys(input: string | Uint8Array): Promise<void>;
+  resize(size: TerminalSize): Promise<void>;
+  interrupt(options?: { readonly timeoutMs?: number }): Promise<void>;
+  compact(options?: { readonly timeoutMs?: number }): Promise<void>;
+  listModels(options?: { readonly timeoutMs?: number }): Promise<readonly AgentModelOption[]>;
+  setModel(id: string, options?: { readonly timeoutMs?: number }): Promise<void>;
+  createLoop(request: ElwoodLoopRequest): Promise<ElwoodLoopSnapshot>;
+  listLoops(): Promise<readonly ElwoodLoopSnapshot[]>;
+  cancelLoop(loopId: string): Promise<void>;
+  // Claude-only re-authentication recovery; NOT part of CodexSession or the
+  // common ElwoodAgentSession surface (C-API-43).
+  login(options: ClaudeLoginOptions): Promise<void>;
+
+  stop(): Promise<void>;
+  kill(): Promise<void>;
+  teardown(): Promise<void>;
+}
+
+interface SendOptions {
+  // Images to attach to this submission. Attached content: the submission is the
+  // text plus this ordered list of images (images have no position within the
+  // text, but array order determines attachment/chip order), attached by the
+  // adapter's native path before the text is submitted (C-API-44).
+  readonly images?: readonly ImageInput[];
+}
+
+// An image to attach, given either as a filesystem path or as in-memory bytes
+// with an explicit format (never both — the alternatives are mutually exclusive).
+// Bytes are written to a short-lived temp file so the adapter attach paths (which
+// are file- or clipboard-based) have something to read; the temp file is removed
+// (best-effort) after the submission is attached.
+type ImageInput =
+  | { readonly path: string }
+  | { readonly data: Uint8Array; readonly format: "png" | "jpeg" | "gif" | "webp" };
+
+type ClaudeLoginMethod = "claudeai" | "console" | "third_party";
+
+interface ClaudeLoginOptions {
+  // Which method to pick from the "Select login method" list if it renders;
+  // defaults to "claudeai". Skipped when the list never appears.
+  readonly method?: ClaudeLoginMethod;
+  // Called with the (validated https, approved-host) browser authorization URL
+  // once it is scraped off screen, so the caller can open/show it. Optional.
+  readonly onAuthUrl?: (url: string) => void;
+  // REQUIRED for the default account flow: called when the CLI reaches its
+  // "paste code here" prompt; the returned code is validated then submitted.
+  readonly provideCode: () => string | Promise<string>;
+  readonly timeoutMs?: number; // default 300000
+}
+```
+
+`login` is Claude-only and drives the interactive `/login` flow to recover a
+session whose login lapsed (C-CLAUDE-18); it is NOT on `CodexSession` or the
+common `ElwoodAgentSession`. It runs as an EXCLUSIVE control-queue transaction:
+it serializes behind and ahead of all other queued operations and no message,
+prompt, model-picker command, or second `login` may interleave with its picker
+keys, authorization code, or Enters. It writes exactly one library-controlled
+Enter after a submitted code, never sends raw keystrokes into a blocking dialog,
+and validates both untrusted inputs — the scraped URL (rejected unless `https:`
+on an approved Anthropic host with no embedded credentials) and the human code
+(rejected as `login_failed` if empty, oversized, or control-bearing). Screen
+stages are recognized only when they NEWLY appear after this `/login` submission,
+so stale on-screen text cannot settle the wrong attempt or disclose the code. It
+resolves only after the CLI reports success AND a fresh `ready` transition proves
+the session is usable again; it rejects with `login_failed` on an explicit
+failure/invalid code or a failing `provideCode` callback, `login_timeout` after
+`timeoutMs`, and `session_not_running` if the session terminates first or is
+already terminal. A flow that self-completes without a code prompt never calls
+`provideCode`.
+
+`login` defends against untrusted on-screen text with layered checks — exclusive
+queue ownership, approved-host/`https:` URL validation, active-tail + baseline
+scoping of stage markers, blocking-dialog write holds, and a re-check that the
+paste prompt is still current immediately before the code is written. Two
+residual limitations are accepted by design: a single frame that renders BOTH a
+genuine approved-host OAuth URL and a paste-code prompt in the active region can
+still advance the flow (coherent per-frame dialog identity on a text-only TUI is
+not attempted — callers should invoke `login` only when the session is genuinely
+at `/login`, not while untrusted output streams), and the version-coupled login
+screen matchers are covered by unit tests against real captured CLI strings
+rather than a live-CLI e2e (which would mutate real auth and cannot run in CI).
+
+`sendPrompt` submits a user prompt through the terminal input path, as if a
+human typed or pasted it into Claude and pressed Enter. It MUST support
+multi-line prompts. The implementation should use bracketed paste or an
+equivalent robust terminal-input strategy so newline characters are entered as
+prompt content rather than premature submissions.
+
+`sendMessage` is the adapter-neutral API for the common chat-loop operation:
+send a user message when the wrapped agent can accept one. Parent apps that only
+need to send a user message and wait for activity/status should prefer
+`sendMessage`. If the session is ready, Elwood submits the message immediately
+through the same PTY input path as `sendPrompt`. If the session is alive but not
+ready, Elwood queues the message and submits it when the adapter reports semantic
+readiness through adapter-specific lifecycle signals. Initial readiness MUST be
+hook-backed whenever the CLI emits a pre-input readiness event: Claude's
+`InstructionsLoaded` and Codex's `SessionStart` both fire only once the CLI is
+initialized and accepting input, so Elwood submits the first queued message on
+that hook. The rendered terminal is NOT a reliable pre-input signal on Codex:
+the input composer marker (a line-leading `›`) is painted as a boot-time
+placeholder roughly a second before the TUI accepts input, and it is
+byte-for-byte identical to the ready composer, so a message submitted on the
+composer marker alone races Codex's input loop and is silently swallowed
+(observed: the queued persona never reaches `SessionStart`/`UserPromptSubmit`).
+Elwood therefore never treats the rendered composer as a readiness signal on a
+COLD START. On RESUME the contract differs: the CLI is reattaching to an
+already-established conversation, so it does not re-fire its pre-input readiness
+hook (`SessionStart` for Codex; observed), and its input loop is live the moment
+the composer paints — a message submitted when the composer marker first appears
+on resume is accepted, not swallowed (verified against the real CLI). So on a
+resumed session Elwood treats the first rendered composer marker as the readiness
+signal, submitting the first queued message on it rather than waiting out the
+deadline; this brings a resumed session to readiness in roughly a second instead
+of the full deadline. (A resumed adapter whose readiness hook DOES re-fire —
+Claude's `InstructionsLoaded` re-fires on resume — still marks ready on that hook,
+whichever comes first.) The bounded deadline remains the ultimate fallback for
+BOTH start and resume: a continuously animating screen region (for example a
+failing MCP server's retry spinner) or a session whose readiness hook never
+arrives (a missing or failed hook bridge) must not starve readiness forever, so
+initial readiness fires no later than a fixed deadline after the first rendered
+frame even when neither a hook nor (on cold start) any composer signal arrives.
+Subsequent turn readiness comes from
+completion signals such as an unblocked `Stop` hook. Queued messages are
+submitted in FIFO order, one message per ready transition, so back-to-back calls
+do not accidentally paste multiple user turns into one active agent prompt. A
+queued `sendMessage` promise resolves when that message has been written to the
+PTY. If the session terminates before a queued message is written, the promise
+rejects with `session_not_running`.
+
+The ergonomic `stream`/`send` turn owner additionally requires positive turn
+acceptance before an idle `ready` transition may complete a turn. A matching
+`UserPromptSubmit`, turn content, or `Stop` hook is positive acceptance. This
+closes the cold-start deadline race: under load, Codex may repaint a boot spinner
+and composer after the deadline-released paste, swallow that paste, and otherwise
+look exactly like a completed empty turn. When `ready` returns without positive
+acceptance, Elwood waits the normal no-oracle quiet window and replays the same
+submission at the now-idle composer, at most twice. A still-unaccepted turn fails
+with `wait_timeout`; it never reports a false empty success. A positive acceptance
+arriving during the quiet window cancels recovery and lets the observed `ready`
+settle normally.
+
+`sendGuidance` is the adapter-neutral intervention API. Before the session has
+ever reached semantic readiness, and while a blocking dialog is visible, it has
+the same readiness-safe behavior as `sendMessage`. During a real running turn
+after initial readiness, it bypasses turn readiness and enters the live TUI
+immediately, like `sendPrompt`. Guidance may overtake readiness-waiting messages,
+but queue-backed prompt, message, and command submissions remain serialized so
+their bracketed pastes and delayed Enter keystrokes never interleave. Its promise
+resolves only after the first submitting Enter is dispatched.
+
+Prompt submission MUST NOT race the TUI's paste ingestion. The CLIs ingest a
+bracketed paste asynchronously, and an Enter concatenated into the same PTY
+write can be consumed by the paste boundary — leaving the prompt staged in
+the composer, never submitted (long multi-line prompts such as personas hit
+this reliably). Elwood therefore writes the bracketed paste and the
+submitting Enter as separate PTY writes, with the Enter following after a
+short settle delay, and then confirms submission against the rendered
+screen: while the composer still shows staged content (Claude's
+"[Pasted text" chip; for Codex the paste's final line still in the
+composer), Elwood re-sends Enter a bounded number of times. A surplus Enter
+on an empty composer is a no-op on both CLIs, so the recovery cannot
+double-submit.
+
+Message text is DATA, never terminal control. `sendPrompt`, `sendMessage`, and
+`sendGuidance` submit caller- or model-controlled text as the content of a
+bracketed paste, so that text MUST NOT be able to escape paste mode or inject
+live keystrokes. Before framing the paste, Elwood sanitizes the text: it removes
+the bracketed-paste sentinels (`ESC [ 200~` and `ESC [ 201~`) so an embedded end
+sentinel cannot terminate the paste early and turn following bytes — an Enter, an
+Escape, a permission-dialog confirmation — into live input, and it strips other
+C0/C1 control characters except the horizontal tab, newline, and carriage return
+that are legitimate multi-line text. This sanitization applies only to the
+queued text-submission APIs; `sendKeys` is the explicit raw-input escape hatch
+and is never sanitized. Newlines inside a sanitized paste remain paste content
+(the whole point of bracketed paste) rather than premature submissions.
+
+`sendPrompt`, `sendMessage`, and `sendGuidance` accept an optional `images`
+list (file paths or in-memory bytes with an explicit format). A submission is
+then the text plus that list of attached images: images have no position WITHIN
+the text (an attached-content model, not interleaving), but the list is ORDERED
+— array order determines attachment order and the CLI's `[Image #N]` chip
+numbering. Elwood attaches every image through the SAME native ingestion path a
+human would use in that CLI, as part of the SAME serialized queue operation that
+submits the text, BEFORE the text's submitting Enter, so a single call produces
+a single agent turn carrying both. An image given as bytes is written to a
+short-lived temp file (the adapter attach paths are file- or clipboard-based);
+Elwood attempts to remove every such temp file after the submission is attached,
+on success or failure (best-effort — see the residual limitations below).
+
+Inputs are validated and bounded BEFORE any temp file is written or any input
+reaches the composer, and a validation failure rejects the whole call so nothing
+is partially attached. The limits are: at most 16 images per submission; each
+byte input at most 25 MiB and each path input's file at most 25 MiB; at most 50
+MiB total across a submission. A `format` that is not one of `png`/`jpeg`/`gif`/
+`webp`, empty bytes, a `path` that is not a readable regular file (its readability
+is checked, not merely its existence), or any count/size past those limits
+reject with `invalid_image`. Malformed inputs from JavaScript callers (a non-object
+entry, or one lacking a valid `path`/`data`) also reject with `invalid_image`
+rather than a raw type error.
+
+Image attachment is CONFIRMED, never assumed. For each image Elwood waits for the
+CLI's `[Image #N]` chip to appear in the composer region; if the chip is not
+observed within the per-image confirmation timeout (10 s), or the OS clipboard
+cannot be read or written, the call rejects with `image_attach_failed` and Elwood
+submits NO text and attaches no further images. A confirmation timeout therefore
+surfaces (e.g. on TUI-wording drift) rather than silently degrading to a text-only
+turn. A session that TERMINATES mid-attach rejects the call with
+`session_not_running`, like any other queued operation. Chip confirmation is
+scoped to the composer region so unrelated on-screen text containing a literal
+`[Image #N]` cannot spoof it.
+
+The attach path is adapter-specific because the two CLIs ingest images
+differently, and this is a version-coupled TUI behavior verified against real
+CLIs (Claude 2.1.215, codex-cli 0.144.6):
+
+- Claude reads a pasted ABSOLUTE image path itself: Elwood bracketed-pastes each
+  image's absolute path into the composer (the same delivery a terminal produces
+  on drag-and-drop), Claude reads and encodes the file, and the composer shows an
+  `[Image #N]` chip. This is pure PTY text and works on every platform.
+- Codex ingests an interactive image ONLY from the OS clipboard via Ctrl+V (it
+  reads `public.tiff` off the macOS `NSPasteboard`); a pasted path is treated as
+  pasted TEXT, not an image. Elwood snapshots the user's clipboard ONCE before
+  the attachment, then for each image in order writes it onto the clipboard as a
+  native image, sends Ctrl+V, and waits for the `[Image #N]` chip; after all
+  images it restores the single snapshotted clipboard text. The whole
+  snapshot/set/paste/confirm/restore sequence holds a process-wide clipboard lock
+  so two concurrent Codex sessions cannot cross-attach each other's images. If
+  the initial clipboard snapshot itself fails, the attach rejects with
+  `image_attach_failed` before mutating the clipboard. Because this drives the
+  macOS clipboard, Codex image attachment is macOS-only; a `sendMessage`/
+  `sendPrompt`/`sendGuidance` with `images` on a non-macOS Codex session rejects
+  with `unsupported_platform` and submits nothing. Restoring the clipboard is
+  best-effort and covers text contents; a brief window where the injected image
+  is the clipboard contents is accepted by design. When the restore itself fails,
+  the attach result is unchanged (still success) but Elwood surfaces a content-free
+  `clipboard_restore_failed` warning (no clipboard contents) so the possible loss
+  of the user's prior clipboard is diagnosable rather than silent.
+
+Image attachment carries several accepted residual limitations. First, temp-file
+removal after an attach is best-effort: the primary attach/materialize error is
+always preserved (a cleanup failure never masks it), but a failed removal is not
+retried and leaves the file in the OS temp directory for the OS to reap rather
+than surfacing a distinct error. Second, the
+Codex clipboard lock serializes attachments within a SINGLE Elwood process only;
+two Elwood processes sharing one OS clipboard are not coordinated, so a
+cross-process cross-attach remains possible (callers running concurrent
+Elwood processes that attach Codex images should serialize that themselves).
+Third, session close during an in-flight attach rejects the operation and blocks
+the text write, but does not join the attach's temp-cleanup and clipboard-restore
+finalizers; on an abrupt teardown those may not complete before process exit
+(clipboard restore is already best-effort, and temp files fall to OS reaping).
+Fourth, composer isolation on a failed attach is best-effort: when an attach
+fails after staging began, Elwood clears the composer draft (kill-to-line-start
+plus kill-to-line-end) so the rejected images do not leak into a later caller's
+turn, but it does not run an adapter-specific transactional confirm-and-restore
+of the exact prior composer baseline; a partially-staged draft that those keys do
+not fully clear could still carry over (mitigated because a caller does not
+interleave submissions on one session). Fifth, chip confirmation identifies the
+composer by the adapter's prompt-glyph line (`›`/`❯`) rather than adapter cursor
+metadata: this defeats stray transcript/assistant `[Image #N]` text on
+non-composer lines, but a running-turn render that puts a prompt-glyph line
+on-screen at the confirmation moment, or a chip on a wrapped composer
+continuation row, is a known edge the glyph heuristic does not perfectly resolve.
+
+Turn boundaries MUST be observable even when no completion hook fires. Claude
+does not fire a `Stop` hook when a running turn is interrupted (Escape), so
+hook-driven readiness alone leaves the session in `running` forever after an
+interrupt. Elwood therefore also derives turn state from the rendered TUI:
+each adapter has a documented working indicator (a footer token rendered only
+while a turn is running) and an idle indicator (the input composer). When the
+working indicator appears after initial readiness, the session transitions to
+`running`; when it disappears and the composer is visible again, the session
+transitions to `ready` — emitting the standard `status` lifecycle activities
+on every real turn boundary regardless of how the turn ended (completion,
+interrupt, or otherwise). A screen that shows neither indicator (for example
+a modal permission dialog) holds the current state so queued messages are
+never submitted into a dialog. Detection MUST be robust to terminal width:
+Claude elides the footer working token below roughly 66 columns, so each
+adapter also has a documented interrupt end banner (Claude renders
+"⎿ Interrupted", Codex renders "Conversation interrupted") whose appearance
+fires the turn-end transition even when the working token was never visible.
+Together the sources cover every width. Turn start is a rendered-state signal:
+the on-screen working token where it fits, plus the OSC window-title braille
+spinner (C-TURN-05) which is width-independent and reveals a running turn even
+when the footer token is elided; a caller `sendMessage`/`sendPrompt` also moves
+the session to `running`. Normal completion comes from the `Stop` hook, and
+interrupts from the working-token edge on wide screens or the end banner
+anywhere. Hook-driven readiness (`Stop`) remains a redundant turn-end source;
+transitions are idempotent, and rendered-state watching only activates after
+initial readiness so startup spinners that borrow the same wording cannot
+fabricate turns. On a RESUME the same guard extends to the transcript replay: a
+resumed session that reached readiness on its first composer frame then repaints
+prior turns, whose footer lines carry the working token — so rendered turn edges
+are suppressed until the composer has stayed quiet and non-blocking (composer
+visible, no working token, no blocking dialog) for a SUSTAINED run of consecutive
+frames, not merely one. The replay repaints those footers in bursts separated by
+brief quiet gaps, so a single quiet frame does not prove the replay finished; any
+working or blocking frame during suppression resets the run. Once the quiet run is
+reached, detection behaves exactly as it does post-readiness on a cold start.
+Explicit running evidence (a caller submission,
+a hook) releases that suppression IMMEDIATELY — a real turn has begun, so the replay
+is over by definition — and synchronizes the watcher into the running state without
+re-announcing a start; the CURRENT frame is still evaluated, so if the turn ended
+exactly as the evidence arrived (the first post-release frame is already the quiet
+composer or the interrupt banner) that frame's end edge is retained, not discarded.
+This ensures a resume never fabricates a phantom rendered turn from replayed history
+and never swallows a real turn's only end edge. These
+indicators (working token, title spinner, composer markers, interrupt banners, and
+blocking-dialog shapes) are version-coupled TUI wording and MUST live in the
+documented per-adapter screen-fact tables, each recording the CLI version it was
+verified against.
+
+Elwood MUST NOT require callers or examples to inspect the terminal screen or
+match adapter-specific prompt text before calling `sendMessage`. Adapter-specific
+terminal behavior belongs inside Elwood. Because terminal prompts are a rendered
+UI rather than a stable machine protocol, Elwood should prefer lifecycle hooks
+and startup health checks over fragile prompt-text regular expressions.
+
+`sendPrompt` does not gate on readiness. If a caller sends a prompt while Claude
+is busy, Elwood does NOT wait for `ready`: the prompt bypasses readiness and
+dispatches as soon as no other submission is in flight, matching human terminal
+behavior. Like guidance, it may overtake readiness-waiting messages, but it never
+interleaves with an in-flight submission — any paste/Enter sequence already
+underway completes first (C-API-07, queue ordering above).
+This readiness guarantee applies while the agent process is alive, including
+`starting`, `running`, and `ready` states. It does not require Elwood to write to
+terminated sessions; calls made after `stopped`, `exited`, `killed`, or
+`torn_down` should fail with `session_not_running`. Promise-returning session
+methods MUST report that failure by rejecting the returned promise; they never
+throw synchronously, so `promise.catch` alone is a complete error-handling
+strategy for callers.
+
+`sendKeys` is the low-level escape hatch for raw terminal input. String input
+flows through the headless xterm input path so terminal semantics match visual
+input. `Uint8Array` input is written to the PTY as bytes instead of being decoded
+as UTF-8, because callers use this overload for raw escape/binary input. It
+bypasses the control queue intentionally so interrupts remain immediate, and
+may therefore interleave with a prompt's paste and delayed Enter.
+
+`interrupt` cancels the in-flight turn: the programmatic equivalent of a human
+pressing Escape in the adapter's TUI. An interrupt exists to stop work already
+in flight, so like `sendKeys` it bypasses the control queue and writes Escape
+to the terminal immediately; it never waits behind queued submissions. Once the
+session has reached initial readiness at least once and is `running` or
+`blocked`, Elwood sends a single Escape and the returned promise resolves when
+the session next reaches `ready`, driven by the same turn-end and
+dialog-dismissal signals as a human interrupt (turn-state watching and blocked
+detection above). When no turn is in flight, `interrupt` resolves immediately
+and MUST NOT write anything: Escape at an idle composer is not neutral (Claude
+clears staged composer text; Codex arms its edit-previous-message affordance),
+so an idle interrupt is a safe no-op. "No turn in flight" covers both an idle
+`ready` session AND the pre-readiness startup window, where the session is
+`running` only because startup is usable, not because a user turn has begun —
+Escape into a booting TUI MUST NOT fire. Concurrent `interrupt` calls coalesce:
+while one interrupt is in flight, a second joins it rather than writing a second
+Escape, which could otherwise land on the composer the first interrupt just made
+idle. If the session does not reach `ready` within `timeoutMs` (default 10000
+ms), the promise rejects with `interrupt_failed`; if the session terminates
+first, it rejects with `session_not_running` — as does an `interrupt` on an
+already-terminated session.
+
+`listModels` and `setModel` drive the adapter's own `/model` picker UI through
+the headless terminal, because neither CLI exposes a stable machine protocol
+for session model selection. The row model is:
+
+```ts
+type AgentModelOption = {
+  readonly id: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly isCurrent: boolean;
+  readonly isDefault: boolean;
+  readonly raw: string;
+};
+```
+
+`id` is a stable lowercase selector (the Claude option label, such as `haiku`,
+or the Codex model slug, such as `gpt-5.4`). `isCurrent` reflects the model the
+session is using now; `isDefault` reflects the CLI's configured default. When
+Codex renders only a `(current)` marker, that row is also the default.
+
+`listModels` opens the picker, parses the rendered rows, cancels the picker
+with Escape, and MUST leave the session's model unchanged. `setModel` selects
+the requested row through cursor navigation. Elwood itself MUST NOT persist a
+new default model into the user's configuration (§4.5): for Claude it applies
+with the session-only key rather than Enter, and it never selects rows via
+number keys because Claude's number shortcut immediately saves the choice as
+the user's default. Claude may next show its built-in `Switch model?` or
+`Change effort level?` cache warning before applying the session-only change.
+When the dialog carries Claude's standard cache-warning copy, Elwood MUST find
+the rendered affirmative row across numbered and unnumbered layouts, navigate
+to it from the rendered cursor position, confirm it, and resolve `setModel`
+only after the dialog has cleared and the idle composer has returned. Recognition
+MUST use one bottom-most, contiguous dialog region and revalidate that live
+region before confirmation; transcript text elsewhere in the viewport cannot
+supply cache-warning copy, action rows, or a composer signal. A confirmation
+requested by a `PreModelSwitch` hook is NOT the built-in cache warning: Elwood
+MUST leave that decision to the human and keep it classified as a blocking
+prompt. For Codex, the Codex CLI itself persists the confirmed
+picker selection (model and reasoning effort) into the user's `config.toml` —
+there is no session-only affordance — so Elwood compensates: it snapshots
+`config.toml` before opening the picker and, after the switch is confirmed,
+restores the prior contents if and only if the file differs solely in the
+root-level `model` and `model_reasoning_effort` keys the picker writes
+(compare-and-swap on the untouched remainder). The restore never affects the
+live session, which keeps the switched model because Codex reads its config
+at launch. When the compare fails — for example the user edited `config.toml`
+concurrently — Elwood MUST NOT clobber the file; it leaves the CLI's write in
+place and emits the `codex_default_model_persisted` warning so the deviation
+is surfaced rather than silent. Elwood confirms the CLI's own default
+reasoning level for the chosen Codex model. The whole snapshot/apply/restore
+transaction holds a process-wide lock so two concurrent `setModel` switches in
+the SAME Elwood process cannot interleave and leave the wrong default. This lock
+is process-local: two SEPARATE Elwood processes sharing one `config.toml` can
+still interleave their transactions. That cross-process race is an accepted
+current limitation (the compare-and-swap still refuses to clobber an unrelated
+edit; the residual risk is a transiently-persisted picker model surviving as the
+default). Closing it requires an inter-process lock on the resolved config path
+and is scoped as separate work.
+`listModels` and `setModel` are transient TUI control: they open and drive the
+adapter's own picker overlay and MUST dispatch even while a turn is in flight
+(for example an MCP-server boot spinner at startup), rather than waiting for
+the session to reach `ready`. Waiting would stall picker automation behind a
+turn that has not completed. Failures to recognize or drive the rendered
+picker reject with `model_automation_failed`; an unknown `id` rejects with the
+same error and includes the available ids in the error details.
+
+Elwood also exposes the model list WITHOUT an active session, for callers that
+only want to enumerate available models (for example to populate a UI selector):
+
+```ts
+type ListModelsOptions = {
+  readonly cwd: string;
+  readonly stateDir?: string;
+  readonly autoupdate?: boolean;
+  readonly hookTimeoutMs?: number;
+  readonly strictVersionCheck?: boolean;
+  readonly timeoutMs?: number;
+};
+
+declare function listClaudeModels(
+  options: ListModelsOptions,
+): Promise<readonly AgentModelOption[]>;
+declare function listCodexModels(
+  options: ListModelsOptions,
+): Promise<readonly AgentModelOption[]>;
+```
+
+Each starts a throwaway session and, as a documented and deliberate exception to
+the opt-in workspace-trust default (§5.1), implies `autotrust: true` so a
+workspace-trust prompt cannot silently stall the probe at `blocked`. This
+exception is scoped: the probe never runs a user turn — it only opens and cancels
+the `/model` picker, then tears the session down — so a trusted workspace's
+integrations are loaded but never exercised. A caller that must NOT auto-trust an
+untrusted workspace should probe from a directory it already trusts. Elwood then
+waits for the session to reach first readiness, calls `listModels`, and ALWAYS
+tears the session down — including when readiness or the picker fails, AND when
+adapter startup itself fails after allocating a state directory — so no probe
+session, PTY process tree, or state directory is ever leaked. The returned
+options are exactly the `listModels` rows, so
+`isCurrent` reflects the throwaway session's launch model and `isDefault`
+reflects the user's configured default. Because the probe opens and cancels the
+picker only (it never selects a row), it leaves the user's saved model default
+untouched, exactly as `listModels` does on a live session (Codex's own boot-time
+config bookkeeping is outside Elwood's control and is not a model change). A
+start failure surfaces the adapter's normal typed start error
+(`claude_not_found`, `codex_start_failed`, and so on); a picker failure rejects
+with `model_automation_failed`. The `timeoutMs` bounds the picker automation as
+it does on a live session; readiness uses the normal startup deadline.
+
+Command submissions (`compact`, `listModels`, `setModel`) MUST NOT consume the
+session's ready transition: typing a slash command does not start a user turn,
+no completion hook will re-arm readiness afterwards, and consuming readiness
+would deadlock every later queued submission.
+
+Queue ordering is FIFO by default, with two documented overtaking exceptions.
+An operation is *readiness-waiting* (a `sendMessage`, a persona message, or a
+`compact`) when it may only reach the terminal once the session is ready; the
+rest are *immediate* (a `sendPrompt`; a `listModels`/`setModel` picker command;
+and a `sendGuidance` that was submitted during an already-ready running turn —
+see §5.3 guidance). When the head of the queue is readiness-waiting and the
+session is not ready, it holds every OTHER readiness-waiting operation behind it
+in FIFO order, but an immediate operation queued behind it overtakes the head
+and reaches the terminal first. Among operations of the same class, and once the
+session is ready, order is strict FIFO. Overtaking never interleaves two
+submissions: the bracketed paste and delayed Enter of one operation always
+complete before the next operation writes. Guidance's eligibility to overtake is
+fixed when it is submitted (§5.3), so guidance queued before first readiness or
+while blocked stays readiness-waiting for its whole lifetime and never reclassifies
+into a later turn.
+
+`compact` asks the wrapped agent to compact its conversation. The compact
+command submission goes through the same readiness queue as `sendMessage`, so
+a compact requested mid-turn runs after the active turn completes. Elwood
+types the adapter's `/compact` command through terminal input and resolves the
+returned promise when the adapter reports completion through its `PostCompact`
+hook. If no `PostCompact` hook arrives within `timeoutMs` (default 120000 ms),
+the promise rejects with `compact_failed`. If the session terminates first,
+the promise rejects with `session_not_running`. Hook and activity events for
+`PreCompact`/`PostCompact` flow to the parent app exactly as for any other
+hook.
+
+`ElwoodSessionStatus` values are `starting`, `running`, `ready`, `blocked`,
+`stopped`, `exited`, `killed`, and `torn_down`.
+
+After startup health checks pass, a newly started or resumed session may enter
+`ready` only when that adapter's first-input readiness signal has fired.
+Otherwise it remains `running` until an adapter lifecycle hook or terminal
+lifecycle signal proves the interactive prompt is ready. Sending a message
+through `sendMessage` or a prompt through `sendPrompt` keeps or moves the session
+in `running`. Adapter readiness signals move the session back to `ready`.
+
+`blocked` reports that the wrapped agent is waiting on a human decision it
+cannot answer itself: a tool permission or approval dialog, or a workspace
+trust prompt Elwood was not authorized to answer (`autotrust: false`).
+Blocked detection derives from the rendered screen via the adapter's
+documented screen-fact rules. A session enters `blocked` from any live status
+(`running` or `ready`) when a blocking dialog appears — an adapter may finish
+its working indicator before the dialog settles, so the block can follow a
+`ready` beat — and settles to `ready` when the dialog resolves, since the
+composer is then waiting for input again. Prompts Elwood answers automatically
+(startup prompt automation, or workspace trust with `autotrust: true`) MUST
+NOT produce a `blocked` transition. Terminal statuses absorb blocking
+evidence. On the transition into `blocked`, Elwood also emits an `activity`
+event with `source: "terminal"`, `kind: "attention"`, a label naming the
+matched screen-fact rule ids, and text describing that the agent is waiting on
+a human decision.
+
+`statusDecisions()` returns a live-only log of at most the 50 most recent
+status decisions, oldest first. Each `ElwoodStatusDecision` records the evidence that
+arrived, the status it moved `from`, the status it moved `to` (undefined when
+the evidence was ignored rather than applied), and a human-readable `reason`.
+It explains why lifecycle transitions did or did not fire — including which
+evidence was ignored — for diagnostics and the local dev app. The log is never
+persisted and never contains prompt, terminal, or hook payload content.
+
+`waitForStatus(match, timeoutMs?)` and `waitForActivity(match, timeoutMs?)` are
+typed helpers over the session's own `status` and `activity` event streams.
+`waitForStatus` resolves with the current status if `match` already accepts it,
+otherwise on the first matching `status` event. `waitForActivity` resolves on
+the first `activity` event `match` accepts. Both reject with `wait_timeout`
+after `timeoutMs` (default 60000 ms), and reject with `session_not_running` if
+the session reaches a terminal status the caller was not waiting for before the
+condition is met (for `waitForActivity`, this includes a session that is
+already terminal when the call is made). The helpers unsubscribe on settle and
+add no persistence; they are convenience wrappers over events parent apps could
+observe directly.
+
+If `initialSize` is omitted, Elwood MUST default the terminal to 189 columns by
+48 rows. Parent apps with a visible terminal should still pass and maintain the
+visual xterm size explicitly.
+
+Claude sessions requested below 100 columns MUST bootstrap the PTY and headless
+terminal at 100 columns because Claude Code can silently discard input when it
+initializes below that width. Elwood holds only the PHYSICAL pty/terminal resize
+during this bootstrap; a caller `resize` in this window is recorded in memory as
+the latest requested size (terminal size is never persisted, §8.2). Elwood
+restores that latest requested size at the one-shot initial-ready transition,
+before the queued persona or caller message is submitted. Later resizes retain
+their ordinary exact behavior. Codex sessions do not apply this bootstrap.
+
+If restoring the latest requested size at the initial-ready transition fails with
+a real (non-closed) native PTY resize error, Elwood MUST NOT report that resize as
+applied: the session stays at its safe bootstrap width, the failure is surfaced as
+a typed `resize_restore_failed` warning, and the queued persona or caller message
+is still released so a failed restore never starves input. A closed-fd resize at
+this transition is the ordinary benign race and is a no-op, not a warning.
+
+`terminal` exposes the session's headless xterm.js terminal handle. The handle
+MUST expose the underlying headless xterm instance, current size, the latest
+OSC window title, and a snapshot API with visible lines, joined visible text,
+and cursor position. Parent apps may
+use this handle for diagnostics or to bridge Elwood's terminal state into their
+own renderer, while `terminal:data` remains the live raw stream for browser
+renderers. The handle also exposes terminal-control methods used internally
+(`sendInput`, `writeOutput`, `resize`, `settled`, and `dispose`); callers should
+prefer the session-level `sendPrompt`, `sendMessage`, `sendKeys`, `resize`,
+`stop`, `kill`, and `teardown` APIs unless they are building advanced terminal
+integrations. Consumers that need diagnostics may await `terminal.settled()` and
+read `terminal.snapshot()`, but visual terminal renderers SHOULD render the raw
+`terminal:data` byte stream instead of repainting from snapshots.
+`sendInput` resolves after input has been forwarded to the PTY and rejects when
+that forwarding fails.
+Because parent apps often attach listeners after `startClaude` or `startCodex`
+resolves, sessions MUST maintain a bounded live-only replay buffer of raw PTY
+output emitted during the current process lifetime (128 KB by default). New
+`terminal:data` subscribers receive that buffer immediately, then receive future
+live chunks. When the bound trims the oldest retained output, it trims on a UTF-8
+code-point boundary so the replayed data never begins with a split multibyte
+sequence (U+FFFD).
+This replay buffer MUST NOT be written to Elwood session state. Parent apps that
+embed their own visual xterm.js instance should feed it the replayed and live
+`terminal:data` chunks; Elwood does not require sharing the same JavaScript
+terminal object between Node and the browser.
+
+`stop` attempts graceful process termination while preserving Elwood metadata and
+loop definitions for resume. It should wait for process exit for a bounded grace period, then escalate
+to force termination so callers do not get a terminal status while the process is
+still indefinitely alive. `kill` force-terminates the process and permanently
+clears its loop definitions. `teardown` removes
+Elwood-owned state for the session and must not remove Claude-owned transcripts,
+auth, or project/user settings that Elwood did not create.
+
+`stop`, `kill`, and `teardown` MUST reap the full PTY process tree, not only the
+PTY leader. The adapter CLI spawns helper subprocesses that are descendants of
+the PTY leader — notably the per-session hook bridge (`node hook-bridge.mjs`) the
+CLI runs on each hook — and signaling only the leader can orphan them, leaking a
+process tree that accumulates across launch/quit cycles. Elwood MUST reap these
+by SIGKILLing the leader's process group: node-pty starts the leader as its own
+session leader, so every descendant inherits its process group, and a group
+SIGKILL reaches them even after a descendant has been reparented to PID 1 by the
+leader's exit — which a parent-pid walk cannot. The reap MUST run for `stop()`,
+`kill()`, and `teardown()`, including when the leader has already exited on its
+own (an already-terminal session still reaps the group). A dead or empty group
+is a no-op. A `teardown()` that rejects in-flight control-queue operations MUST
+still complete: rejecting a pending `sendMessage`/`compact`/model operation does
+not skip the group reap or the rest of teardown.
+
+### Automated input and pending decisions
+
+All queued text, including slash-command text and its delayed Enter, MUST wait
+while a human-decision dialog is visible. Permission menus remain blocking
+regardless of the highlighted option or wrapped question. Model commands may
+bypass startup readiness but never this dialog guard. Their timeout includes a
+held submission and cancels it, so no expired command or retry executes later.
+Input blocking follows live rendered facts even before startup usability or
+semantic readiness. Timeout cleanup MUST NOT write control keys into a blocking
+dialog; text already staged may remain for the caller to inspect. Picker navigation
+and apply keystrokes MUST revalidate their expected current screen immediately
+before writing; only the existing first-party cache-confirmation policy may own
+its specific blocking screen. Compaction recovery Enter must also respect the dialog guard. Explicit caller
+`sendKeys` and narrowly scoped login/picker confirmation automation retain their
+existing contracts. C-API-23/24/37 and C-ATTN-01.