@with-logic/elwood 0.1.2 → 0.2.0

package/docs/cli-output.md

@@ -5,9 +5,9 @@ exit codes, and safe shell recipes. Start with [cli.md](cli.md) for usage.
 
 ## Text, verbose, and stream
 
-Text is the default output protocol. Warnings and diagnostics go to stderr,
-never into the answer on stdout. `--verbose` adds compact elapsed phase,
-tool-name, warning, and cleanup progress; it does not repeat assistant or
+Text is the default output protocol. Live session warnings are quiet by default,
+including during `elwood models`. Errors remain visible. `--verbose` adds compact
+elapsed phase, tool-name, warning, and cleanup progress on stderr; it does not repeat assistant or
 thinking text. `--debug` adds full sanitized event details. `--stream` emits
 assistant text as it arrives and is valid only with text output; use
 `--no-stream` when config enabled streaming but a script needs JSON.
@@ -26,7 +26,9 @@ a downstream pipe closing early triggers cleanup without an uncaught `EPIPE`.
 
 `--output json` emits exactly one version-1 document. Its stable fields are
 `schemaVersion`, `type`, `agent`, `response`, `sessionId`, `durationMs`,
-`cleanup`, and, on failure, `error`:
+`cleanup`, and, on failure, `error`. The examples below use `--ephemeral`, so
+cleanup removes session state and `sessionId` is null. By default, CLI turns
+preserve state and return a resumable session ID once one is available:
 
 ```json
 {
@@ -66,7 +68,8 @@ a usage error or `no_agent_found`) reports `"agent": null`.
 `--output jsonl` emits sequenced version-1 `text`, `thinking`, `tool`,
 `status`, and `warning` records followed by exactly one `result` or `error`
 record. Every record has `sequence` and `elapsedMs`; tool calls and results
-share `toolCallId` when the agent supplies one:
+share `toolCallId` when the agent supplies one. This example also uses
+`--ephemeral`:
 
 ```jsonl
 {"schemaVersion":1,"type":"status","status":"running","sequence":1,"elapsedMs":114}
@@ -77,7 +80,9 @@ share `toolCallId` when the agent supplies one:
 ```
 
 JSONL warning records stay on stdout so the machine protocol remains ordered;
-text and JSON runs surface warnings on stderr.
+text and JSON runs surface session warnings on stderr only with `--verbose`
+or `--debug`. `ELWOOD_VERBOSE=true` or config `verbose: true` also enables them;
+`--no-verbose` overrides inherited verbosity (but not explicit `--debug`).
 
 ## Session and model listings
 
@@ -108,10 +113,35 @@ in JSON mode, and `sessions` never starts an agent:
 check, so a force-killed owner can leave a stale "live" until the session is
 next started or torn down. An empty state directory yields an empty `sessions`
 array (text mode prints a notice on stderr and nothing on stdout). Unreadable
-records are skipped with one stderr warning each.
+records are skipped with one stderr warning each, even without verbosity,
+because the listing omits those results.
 
-`elwood models` starts the agent briefly to read its own model picker, then
-tears the session down:
+`elwood models` probes Claude then Codex, regardless of saved or environment
+agent defaults. Text includes an `AGENT` column. JSON contains successful
+catalogs and canonical per-agent error records in one document:
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "models",
+  "agents": [
+    { "agent": "claude", "models": [] },
+    { "agent": "codex", "models": [] }
+  ],
+  "errors": []
+}
+```
+
+Each probe opens and cancels its model picker and always removes its session
+state. An empty `models` array means that probe succeeded with no rows. If an
+adapter fails, its catalog is absent from `agents` and its canonical error
+record appears in `errors`, including `agent`, `error`, `durationMs`, and
+`cleanup`. Available catalogs remain present. Incomplete results exit nonzero:
+130 for interruption, then 124 for timeout, 2 for usage errors, or 1 for other
+failures, in that precedence order. `--timeout` is a whole-command budget; no
+next probe starts after timeout or Ctrl-C.
+
+Explicit `elwood models --agent claude` retains its single-agent document:
 
 ```json
 {
@@ -125,7 +155,7 @@ tears the session down:
 }
 ```
 
-Failures use the same `error` document and statuses as a run. Useful recipes:
+Single-agent failures use the same `error` document and statuses as a run. Useful recipes:
 
 ```sh
 id=$(elwood sessions --output json | jq -r '.sessions[0].id')
@@ -182,3 +212,7 @@ fi
 Do not use `jq -r .response` alone as a success check. Error documents can
 carry a partial `response`, and streamed text can be partial when the process
 exits nonzero.
+
+For retained text runs, `--show-session-id` opts into a session-ID footer on stderr.
+Without it, use `elwood sessions` to find the ID. JSON and JSONL always keep their
+existing `sessionId` field.

package/docs/cli.md

@@ -15,8 +15,9 @@ elwood run --output json < prompt.txt
 ```
 
 `elwood "prompt"` runs in the current directory, waits for one complete turn,
-prints the combined assistant text to stdout, then tears its Elwood session
-state down. It does not undo files the agent changed or remove history owned by
+prints the combined assistant text to stdout, then stops the agent and preserves
+its Elwood session state for later listing or resumption. Use `--ephemeral` to
+remove that state afterward. It does not undo files the agent changed or remove history owned by
 the agent CLI. `elwood run "prompt"` is the same command in explicit form.
 
 Positional words are joined with spaces. Non-empty piped stdin is appended after
@@ -83,8 +84,9 @@ Boolean environment values are exactly `true` or `false`.
 Run `elwood --help` for the full flag list. Launch controls include `--model`,
 `--reasoning-effort`, `--persona`, `--claude-permission-mode`,
 `--codex-sandbox`, `--codex-approval-policy`, `--state-dir`, `--verbose`,
-`--debug`, and `--trust` / `--no-trust`. The built-in non-interactive posture
-is Claude `dontAsk`, or Codex `workspace-write` with approval policy `never`.
+`--debug`, and `--trust` / `--no-trust`. Live session warnings are quiet by
+default; use `--verbose` or `--debug` to see them, including for `elwood models`.
+The built-in non-interactive posture is Claude `dontAsk`, or Codex `workspace-write` with approval policy `never`.
 
 For an unattended run that must never stop on a permission prompt, prefer the
 agent-neutral `--high-trust` over per-agent posture flags. It selects Claude
@@ -140,11 +142,13 @@ combined with `--stream`, `--verbose`, `--debug`, or `--output jsonl`.
 
 ## Continuation and cleanup
 
-New runs are ephemeral unless `--keep` is supplied. A kept text run reports its
-session ID on stderr; JSON and JSONL include it in the terminal record:
+New and resumed runs preserve state by default; `--keep` explicitly selects
+that default. Text output contains only the agent response. Add
+`--show-session-id` to print the retained ID on stderr, or run `elwood sessions`
+to find it later. JSON and JSONL include it in the terminal record:
 
 ```sh
-first=$(elwood --keep --output json "Remember that the release color is teal")
+first=$(elwood --output json "Remember that the release color is teal")
 id=$(printf '%s' "$first" | jq -r .sessionId)
 elwood --resume "$id" "What is the release color?"
 elwood --resume "$id" --ephemeral "Finish this conversation"
@@ -165,10 +169,13 @@ remain. It is supported only for new sessions, never with `--resume`.
 ## Trust and security
 
 Headless mode is non-interactive. With the default `--trust`, Elwood answers
-only its allowlisted workspace-directory and extension trust dialogs, plus the
-Elwood-owned Codex hook trust needed for operation. `--no-trust` disables the
-workspace and extension approvals. Any other recognized dialog fails safely as
-`blocked_prompt` instead of hanging or guessing.
+only its allowlisted workspace-directory and extension trust dialogs.
+`--no-trust` disables those approvals. Codex hook trust is always bypassed for
+the entire session, including third-party hooks configured in Codex, because
+Elwood needs its own hook bridge to run. This bypass is independent of `--trust`.
+Other recognized dialogs fail as `blocked_prompt`. The same error applies when
+safe trust automation cannot clear a gate within five seconds; queued prompt
+input is never sent into that gate.
 
 Piped text and image paths are prompt input with the same authority as text
 typed by the caller. Do not combine untrusted input with broad filesystem

package/docs/codex/cli.md

@@ -40,6 +40,50 @@ Useful CLI capabilities for Elwood:
   terminal output and also project recognized warnings into typed `warning`
   events with remediation commands.
 
+## Commentary and final replies
+
+Subscribe to `activity` to display Codex's committed user-facing progress:
+
+```ts
+session.on("activity", (event) => {
+  if (event.kind === "assistant_progress" && event.text) {
+    appendProgress(event.text);
+  } else if (event.kind === "assistant_message" && event.text) {
+    appendFinalReply(event.text);
+  }
+});
+```
+
+Progress uses `source: "transcript"`, `label: "assistant"`, the session ID,
+transcript path and optional native turn ID. It preserves string content and
+ordered array-form `output_text` blocks from `response_item` messages explicitly
+marked `phase: "commentary"`. Analysis and unknown phases never become progress.
+Readable reasoning retains its separate `reasoning` channel; encrypted reasoning
+is never normalized into text.
+
+Response items are the canonical progress source. Explicit non-final legacy
+`agent_message` mirrors remain raw transcript events with `other` summaries and
+no normalized text, avoiding duplicate publication and false final replies.
+Legacy unphased and final-answer behavior is preserved.
+
+Keep progress separate from final-reply handlers: it must not clear working
+state, consume reply context, finalize a trace, or route mentions to other
+agents. Progress does not end a turn or change session status. Ergonomic
+`send()` and `stream()` keep collecting their existing final-answer content;
+use `on("activity", ...)` for progress. These are live observations, not token
+deltas or replayed history, and their text may contain sensitive conversation
+content just like final replies.
+
+## Native questions
+
+Codex modal and queued question tools surface through Elwood's shared
+`question` event, normalized `question` activity, `listQuestions()` and
+`answerQuestions()`. Modal question sets are one request; queued asynchronous
+questions are independently answerable requests and can coexist with ongoing
+work. Question-bearing asynchronous messages remain distinct from final replies,
+even when their native record says `phase: "final_answer"`. See
+[native questions](../questions.md) for consumer usage and lifecycle details.
+
 ## Resume Implications
 
 Codex stores transcripts locally under Codex-owned state. Elwood should persist

package/docs/login-recovery.md

@@ -13,6 +13,30 @@ surfaces this so a session never wedges silently:
   matching `warning` activity) carrying `recoveryCommand: "/login"`, and leaves
   the session alive so you can recover without restarting.
 
+## Advance renewal notices
+
+Claude can show `Your login expires in 3 days · run /login to renew` while the
+session is still usable. Elwood exposes this separately from `login_expired`:
+
+```ts
+session.on("warning", (warning) => {
+  if (warning.code === "login_expiring") {
+    // Notify a human or schedule renewal according to your application's policy.
+    showRenewalNotice(warning.expiresInDays, warning.recoveryCommand);
+  }
+});
+```
+
+Subscribe immediately after `startClaude` or `resumeClaude` returns to receive
+startup observations. The same payload appears in `activity` with
+`kind: "warning"`, `label: "login_expiring"`, and the typed warning in `raw`.
+The CLI-reported `expiresInDays` is a duration, not an exact expiry timestamp.
+Each distinct countdown value emits once per live session. Warnings are never
+persisted or replayed to later subscribers. Native welcome banners and empty
+composer footers are recognized; arbitrary transcript text is ignored. Elwood
+does not change status or initiate login. A consumer can offer the existing
+`session.login()` flow when the human is ready.
+
 ## Driving `/login`
 
 `ClaudeSession.login(options)` drives the interactive `/login` flow. The

package/docs/native-question-proofs.md

@@ -0,0 +1,57 @@
+# Native question proofs
+
+These opt-in tests exercise `listQuestions()` and `answerQuestions()` against
+real authenticated CLI processes. Each entrypoint uses two valid-model turns.
+Run them separately after `npm run check`; they consume model quota.
+
+## Claude: C-E2E-18
+
+```sh
+ELWOOD_NATIVE_QUESTIONS_PROOF=1 node --no-warnings --test --test-concurrency=1 tests/e2e/claude-questions.e2e.ts
+```
+
+The proof pins Claude Code 2.1.305 and uses `haiku`. It prefers that exact binary
+in `~/.local/share/claude/versions/`, falling back to the installed binary only
+when its version matches. It copies credentials into a private temporary home
+and writes a minimal temporary configuration. Parent configuration is checked
+for changes; it is not copied into the proof's home. The parent CLI installation
+remains unchanged.
+
+The first turn submits grouped single and multiple choices. The second submits
+multiline alternative text. Both compare the native `AskUserQuestion`
+PostToolUse answers, require an answered closure and an empty pending list,
+and keep the original `send()` waiting for the final assistant reply.
+
+Question events and normalized activities must correspond exactly and contain
+no submitted answer marker. The proof recursively checks Elwood-owned state
+before and after shutdown. Diagnostic artifacts use private, exclusive files
+inside the sandbox. Teardown removes the sandbox and verifies that parent
+configuration, authentication and process environment remain unchanged.
+
+## Codex: C-E2E-19
+
+```sh
+ELWOOD_NATIVE_QUESTIONS_PROOF=1 node --no-warnings --test --test-concurrency=1 tests/e2e/codex-questions.e2e.ts
+```
+
+The proof pins Codex 0.163.0 and uses `gpt-6-luna` with low effort. The first
+turn asks three queued questions in one asynchronous call. It answers Note,
+Literal, then Color through the public API, checking the other requests remain
+available and the original turn remains running. The second turn submits one
+three-question Plan modal, including None of the above and a named choice with
+additional notes.
+
+Both long answers exceed 700 characters and include CRLF and CR line endings,
+interior tabs, indented caret rows, interior trailing spaces and outer Unicode
+whitespace. Complete committed native free-text answers and notes must match
+after newline normalization and outer Unicode White_Space trimming. Queued
+selected labels are trimmed; modal selected labels remain exact (PRD §5.10).
+The literal answers
+`Type your answer` and `Add notes` must also match exactly; a clipped viewport
+or placeholder rendering is not accepted as proof of the submitted value.
+
+The proof compares complete queued reply envelopes and grouped modal answer
+arrays, requires four answered request closures and final-only ergonomic
+replies, and applies the same telemetry/state privacy and parent-state checks
+as the Claude proof. Native transcripts and diagnostic captures stay inside
+private sandbox directories that teardown removes.

package/docs/performance.md

@@ -0,0 +1,73 @@
+# Performance checks
+
+Elwood's parent process renders terminal output, classifies frames, retains a
+bounded replay buffer, and watches transcripts for each session. Native Claude
+and Codex processes consume additional resources outside this process.
+
+## Repeatable terminal load
+
+Run these from the repository root after `npm ci`, using Node 24 or newer:
+
+```sh
+ELWOOD_BENCH_AGENT=claude node --expose-gc --no-warnings scripts/performance/terminal.ts 8 1 8 32
+ELWOOD_BENCH_AGENT=codex node --expose-gc --no-warnings scripts/performance/terminal.ts 8 1 8 32
+```
+
+Each child writes 8 MiB through a real PTY. The probe checks byte counts and a
+final rendered marker, then reports elapsed time, memory, event-loop delay,
+pending output, and resources remaining after cleanup. The selected observer
+runs the production startup-prompt, screen-fact, turn, attention, and replay
+code. Omit `ELWOOD_BENCH_AGENT` to measure rendering and snapshots alone.
+
+This is a synthetic output burst. It does not launch agent CLIs, make model
+requests, exercise hook or transcript traffic, or measure child-process memory.
+Use it to detect regressions in Elwood's output processing; real workloads need
+their own measurements.
+
+### September 16, 2026 baseline
+
+Measured on the development Mac with Node 24.7.0. Results vary with machine and
+concurrent workload; these are observations, not performance guarantees.
+
+| Observer | Sessions | Total output | Elapsed | Peak parent RSS | Event-loop p99 / max |
+|---|---:|---:|---:|---:|---:|
+| Claude | 1 | 8 MiB | 0.185 s | 110 MiB | 11.3 / 11.3 ms |
+| Claude | 8 | 64 MiB | 0.969 s | 240 MiB | 14.4 / 16.0 ms |
+| Claude | 32 | 256 MiB | 7.608 s | 363 MiB | 26.2 / 31.9 ms |
+| Codex | 1 | 8 MiB | 0.243 s | 117 MiB | 19.5 / 19.5 ms |
+| Codex | 8 | 64 MiB | 1.537 s | 248 MiB | 17.4 / 23.4 ms |
+| Codex | 32 | 256 MiB | 9.270 s | 364 MiB | 23.9 / 42.3 ms |
+
+At 32 sessions, final rendering finished within 10 ms of child exit. Neither
+run retained PTY resources after cleanup, and post-GC heap usage did not increase
+over that trial's starting heap. The remaining `PipeWrap` was the probe's stdout.
+
+Before output batching, the snapshot-only probe took 14.497 s for one 8 MiB
+session, queued about 8.19 MiB, and spent 14.19 s rendering after child exit.
+The corresponding post-fix trial took 0.544 s. These two trials used the same
+snapshot-only workload; the table above also includes production frame observers.
+
+A separate ten-second idle probe used 128 real empty transcript files, split
+evenly between Claude and Codex watchers at their default polling intervals. It
+used 97.9 ms of CPU time (about 0.98% of one core), with 19.0 ms p99 event-loop
+delay. It reported no errors, no retained heap increase, and no active resources
+after closing the watchers. This measures idle polling, not transcript parsing
+under active output.
+
+## Bounds and regression coverage
+
+- Adjacent PTY output is batched for at most 4 ms or 64 KiB, preserving order and
+  content. Renderer observations occur at batch boundaries.
+- Real PTYs pause at 1 MiB of pending output and resume below 512 KiB. An already
+  delivered chunk can exceed the threshold. Custom PTY factories must provide
+  flow control to receive this backpressure.
+- Runtime cleanup gives received output up to one second to render before
+  disposal. Process exit and reaping remain immediate; direct terminal disposal
+  discards pending output immediately.
+- Tests cover batch ordering, Unicode/ANSI boundaries, slow-renderer
+  backpressure, disposal, final output on exit, and cancellation of late
+  readiness timers.
+
+Re-run the probe after changes to rendering, frame classification, replay,
+transcript polling, or cleanup. Compare output correctness and cleanup as well
+as throughput, memory, and event-loop delay.

package/docs/questions.md

@@ -0,0 +1,181 @@
+# Native agent questions
+
+Elwood exposes structured questions from the real Claude Code and Codex terminal
+interfaces. A host such as Coal Harbor renders the questions, collects answers,
+and calls Elwood to submit them through the native editor.
+
+Subscribe before starting a turn. Keep the question handler active while awaiting
+`send()` or consuming `stream()`; a blocking question needs an answer before that
+turn can finish.
+
+```ts
+import { ClaudeSession, type ElwoodQuestionAnswer } from "@with-logic/elwood";
+
+const session = new ClaudeSession({ cwd: "/path/to/project", autotrust: true });
+
+session.on("question", (event) => {
+  if (event.phase === "raised") showQuestionRequest(event.request);
+  else removeQuestionRequest(event.request.id, event.reason);
+});
+
+// After the user fills every question in one request:
+async function submit(requestId: string, answers: readonly ElwoodQuestionAnswer[]) {
+  await session.answerQuestions(requestId, answers, { timeoutMs: 20_000 });
+}
+
+const reply = await session.send("Help me choose and implement the right approach.");
+```
+
+The same methods and event exist on `CodexSession`, the low-level adapter
+interfaces, and the shared `ElwoodAgentSession` interface. Lazy session controls
+start their session when needed. A late subscriber can reconcile its UI with
+`await session.listQuestions()`, an immutable list of available requests in
+discovery order. Subscribe first and buffer lifecycle events while loading the
+snapshot; install the snapshot, then replay those buffered edges by request ID.
+This prevents a request closed during loading from reappearing in the UI.
+
+## Request and answer contract
+
+A request contains an opaque `id`, `agent`, `delivery` (`blocking` or `queued`),
+and ordered `questions`. Each question contains:
+
+- An opaque `id`, `prompt`, optional `header`, and ordered `options` with opaque
+  IDs, labels, and optional descriptions.
+- `selection`: `single`, `multiple`, or `none`.
+- `textMode`: `none`, `alternative` (text instead of a choice), or `additional`
+  (text may accompany a choice).
+- `supportsSecretInput`: whether the supported native editor accepts secret input. Current
+  characterized editors advertise `false`; do not infer masking from model text.
+
+Render these capabilities as supplied. Send one complete batch for one request:
+
+```ts
+const [request] = await session.listQuestions();
+if (request) {
+  const answers: readonly ElwoodQuestionAnswer[] = await collectUserAnswers(request);
+  await session.answerQuestions(request.id, answers);
+}
+```
+
+For a choice, use `{ questionId, optionIds: userSelectedOptionIds }`. For text,
+use `{ questionId, text: "The user's answer" }`. For multiple choice, pass all
+selected `optionIds`. Include both only when `textMode` is `additional`.
+Every question in the selected request needs exactly one answer; the host chooses
+when to submit. Elwood never selects defaults or answers automatically.
+
+Unknown or duplicate question/option IDs, missing answers, unsupported
+combinations, empty answers, and unsafe control characters reject before any
+input. Multiline text uses bracketed paste. The 8 MiB answer-batch limit is the
+sum of UTF-8 bytes in validated question IDs, selected option IDs and text;
+JSON syntax and unknown fields do not count. Text must contain well-formed
+UTF-16. Invalid answers produce `invalid_question_answer`; unknown, stale, closed
+or previous-process request IDs produce `question_not_found`. Do not retain
+request IDs across process restarts or resume.
+
+## Lifecycle and input ownership
+
+The typed `question` event has `phase: "raised"` or `"closed"`, plus the request,
+agent and `elwoodSessionId`. Closure reasons are `answered`, `cancelled`, and
+`unavailable`. `answered` means native acceptance was observed. Turn completion,
+withdrawal, replacement or shutdown uses `unavailable` unless stronger native
+evidence exists. Redraws and mirrored source records do not raise duplicates.
+
+The normalized activity stream carries the same event in `activity.question`
+with `kind: "question"`. Choose one surface, or deduplicate matching deliveries
+by request ID, phase and closure reason when listening to both. A request's
+`closed` event must still be processed after its `raised` event. Question
+activities contain question metadata, not the user's submitted answers. They are
+separate from final assistant text and excluded from ergonomic reply text.
+
+A throwing or rejecting `question` or matching `activity` handler produces at
+most one content-free `question_observer_failed` warning per live session, plus
+its normalized warning activity. Its `phase` is `question` or `activity`, naming
+the first failing notification channel. Other handlers and question lifecycle
+delivery continue. The diagnostic contains no question, answer or error contents;
+it does not authorize retrying or replaying an answer.
+
+Answering uses a dedicated input lane and works while another send or turn is
+waiting. Pending questions hold ordinary text, slash commands, loops and login
+writes so those cannot enter the question editor or erase queued questions.
+`delivery: "queued"` can coexist with an agent that is still working. Question
+availability alone does not mean its turn has finished.
+
+An answer call resolves after native acceptance. The default timeout is 20
+seconds; pass a positive finite `timeoutMs` or an `AbortSignal` as `signal` to
+bound the operation. Concurrent answer calls, human keyboard takeover,
+interruption, shutdown, layout changes, rejected input or uncertain acceptance
+reject with `question_answer_failed`. A submitting Enter is never blindly
+retried. Failures may include a content-free `details.category`: `frame_wait`,
+`adapter`, `terminal_write`, `native_acceptance`, or `aborted`.
+
+If no physical write started, the request may remain available for another
+attempt. If input may have reached the CLI without confirmed acceptance, Elwood
+closes the API request once as `unavailable` and removes it from `listQuestions()`.
+Its old ID then rejects with `question_not_found` before writing. Refresh the list
+and terminal view; offer an answer form only for a currently available request.
+
+Elwood keeps the uncertain native identity reserved, holding ordinary input until
+native closure, turn end or shutdown. A redraw, changed metadata for the same
+identity or a late write completion cannot restore the answer form. A later
+native acknowledgement releases that reservation without a second closure event.
+Both the physical write and native reservation must settle before ordinary input
+resumes, in either order. An unavailable API request does not mean the CLI is
+ready; the terminal remains available for manual inspection and recovery.
+
+Requests and answers are live-only and are not added to Elwood's persisted state.
+Existing raw hooks and transcripts retain their normal contents and can include
+answers. Avoid logging them if your host treats those answers as sensitive.
+
+## Native differences
+
+Claude's `AskUserQuestion` can group tabbed questions into one request, including
+single choice, checkboxes and alternative text on single-select questions.
+Checkbox questions currently advertise `textMode: "none"`. Elwood submits the group through
+its review page. A caller's direct Claude hook answer keeps precedence and does
+not create a phantom terminal question. The supported automation starts from the
+recognized first question; unsupported partial navigation fails safely. Completion
+hooks must match the native Claude tool-use ID (`tool_use_id`), or the ordered
+question definitions when the hook omits that ID. Unrelated Claude hooks cannot
+acknowledge the request.
+
+Codex's modal `request_user_input` groups questions into one acceptance unit.
+Its current editor requires choices for every question; native Other/notes
+supports a custom answer, and the native “None of the above” row is exposed as
+its own option. Notes can accompany a selected choice. Queued
+`request_user_input_async` questions are accepted
+individually, so Elwood exposes one request per independently answerable question,
+even if the agent asked several at once. They can disappear when the native turn
+ends. Elwood does not extend their lifetime or invent a fixed expiry. Native Codex
+metadata must omit `isSecret` or use boolean `false` for every question; unsupported
+or malformed secret flags leave the complete request unavailable for automation.
+
+Ordinary prose questions, permission prompts, trust gates, model pickers and login
+flows retain their existing surfaces. Unknown question layouts remain available
+through the terminal view and do not receive guessed answer keys. Native behavior
+was characterized on Claude Code 2.1.305 and Codex 0.163.0; see
+[CLI behavior](cli-behavior.md#native-interactive-question-records-2026-10-20) for evidence.
+
+Codex question automation is bounded to 256 pending native requests and 1 MiB
+of candidate metadata; each call is limited to 256 definitions and 1 MiB of
+input metadata. Replay protection retains at most 4,096 retired identities and
+1 MiB of key data. Overflow closes exposed requests as `unavailable` and disables
+question automation until a new session is created. Ordinary text, slash-command,
+loop and login writes remain held until native turn-end evidence. Raw `sendKeys()`
+remains available for manual input and recovery. Unanswered requests have no
+invented expiry deadline.
+
+Codex normalizes CRLF and CR to LF and trims Rust Unicode White_Space from the
+ends of submitted text (U+FEFF is retained). Interior whitespace is preserved.
+Modal option labels remain exact; optional notes use the text normalization.
+Elwood checks that long, clipped and multiline text, including text matching an
+editor placeholder, remains in the same question editor. The call resolves only
+after the complete accepted text matches the normalized submitted answer.
+Budget disablement emits one content-free `question_automation_disabled` warning
+and its normalized warning activity. Raw human terminal input remains available.
+
+A successful Claude final submission waits for matching native completion even
+after an empty composer appears. An interrupted, unconfirmed answer closes its
+API request as unavailable while retaining the native identity and input hold
+until native closure.
+
+Aborting the call does not undo an answer already submitted to Claude.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@with-logic/elwood",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Control interactive agentic coding CLIs (Claude Code, Codex) through real terminal sessions: typed hooks, a unified activity stream, resumable sessions, and a headless CLI.",
   "license": "MIT",
   "author": "Logic App, Inc.",

package/prd/04-architecture.md

@@ -18,6 +18,21 @@ state, warnings, or startup prompts. Elwood MUST send `sendPrompt` and
 `sendKeys` input through the headless terminal input path so parent app input,
 programmatic prompts, and low-level keys share one terminal control mechanism.
 
+PTY output is submitted to xterm's ordered write buffer without serializing each
+chunk behind a separate timer. Adjacent chunks may be coalesced into bounded
+render batches of at most 64 KiB, flushing sooner when full or after a 4 ms
+scheduling window (subject to host event-loop scheduling); raw byte order is
+preserved, while event chunk boundaries and
+intermediate frames are not guaranteed. Render observers inspect each completed
+batch before subsequent terminal writes are parsed. Real PTY
+output pauses at 1 MiB of unrendered UTF-8 data and resumes below 512 KiB, without
+dropping output. A paused PTY resumes as soon as its child process exits, and is
+not paused again afterwards, so a backlog still draining at exit cannot strand
+unread output behind a pause. The high-water mark can be exceeded by the single
+chunk already delivered; OS/native buffers are outside this accounting. This is
+backpressure, not a total process-memory cap. Disposing the terminal cancels pending render
+notifications and settles outstanding write and `settled()` promises.
+
 ### 4.2 macOS shell behavior
 
 On macOS, Elwood MUST start the PTY in the user's configured shell in a way that

package/prd/05-api/5.1-starting-claude.md

@@ -97,7 +97,17 @@ tools onboarding prompt, declined through PTY input (Escape) with
 automation is unconditional because declining grants nothing and an unanswered
 onboarding prompt permanently wedges a headless session.
 
-`persona` is an optional instruction message for the agent. When set, Elwood
+This non-trust automation has the SAME lifetime as trust automation: it is bound
+to session disposal. Once the session begins closing — `stop()`, `kill()`, or PTY
+exit — no further decline is attempted, and a decline already in flight settles as
+a cancellation. Because the non-trust automation barrier parks on render settlement,
+a write suspended there re-checks disposal when it resumes and abandons the keystroke:
+nothing is written to a terminated PTY, and neither `startup_prompt` nor
+`startup_prompt_write_failed` is emitted after close.
+
+`persona` is an optional instruction message for the agent. A persona exceeding
+8 MiB of UTF-8 text rejects startup with `input_queue_full` before preflight,
+state creation, or process spawn. When set within this limit, Elwood
 enqueues it before control returns to the caller, so it is guaranteed to be the
 session's first submitted user message: it is delivered through the standard
 message queue as soon as the session first becomes ready, ahead of any