@with-logic/elwood 0.1.3 → 0.2.0

package/docs/cli-output.md

@@ -212,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
@@ -141,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"
@@ -166,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.3",
+  "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

package/prd/05-api/5.10-questions.md

@@ -0,0 +1,117 @@
+## 5.10 Native questions
+
+`ElwoodAgentSession`, both raw adapter interfaces, and both lazy session classes
+expose `listQuestions(): Promise<readonly ElwoodQuestionRequest[]>` and
+`answerQuestions(requestId, answers, options?): Promise<void>`. These controls
+bypass the ergonomic turn queue; answering never creates a user turn or finishes
+an existing `send`/`stream`. Lazy controls start the session before delegation.
+
+A request has readonly `id`, `agent`, `delivery` (`blocking` or `queued`), and
+ordered `questions`. Each question has readonly `id`, `prompt`, optional `header`,
+`options` (ordered readonly `id`, `label`, optional `description`), `selection`
+(`single`, `multiple`, or `none`), `textMode` (`none`, `alternative`, or
+`additional`), and `supportsSecretInput`. IDs are opaque and scoped to the live process.
+`alternative` permits text instead of options; `additional` permits text alongside
+options. Capabilities describe only supported native input, not model intent.
+
+The snapshot lists currently available requests in discovery order and is deeply immutable.
+Redraws and mirrored source records retain identities. A semantic replacement
+closes the old request as unavailable and raises a new ID. No question or answer
+is stored in Elwood session state or restored by Elwood on resume.
+
+`question` events carry `elwoodSessionId`, `agent`, `request`, and `phase`
+(`raised` or `closed`). Closed events also carry `reason`: `answered`,
+`cancelled`, or `unavailable`. `answered` requires native acceptance evidence;
+`cancelled` requires native dismissal evidence; withdrawal, turn end, replacement,
+and shutdown use `unavailable` when no stronger evidence exists. Matching
+normalized activities have `kind: "question"`, `source: "terminal"`, the same
+structured event in `question`, and a phase label. They contain request prompts,
+not answer values. Existing raw hook/transcript observations remain unredacted.
+Question activity is telemetry and never ergonomic answer text. The request, event
+and normalized activity agents agree, including in their public discriminated types.
+
+Each answer contains `questionId`, optional ordered `optionIds`, and optional
+`text`. Exactly one answer for every question in the selected request is required.
+Unknown/duplicate IDs, unsupported text, multiple options on single-select,
+empty answers, and control-bearing text reject as `invalid_question_answer`
+before any write. The complete validated answer batch is limited to 8 MiB: the sum of UTF-8 bytes
+in its question IDs, selected option IDs and text. JSON syntax and unknown fields
+do not count toward this limit. Malformed UTF-16 is rejected. Multiline text is safely bracketed-pasted. An unknown, closed,
+retired, or previous-process request rejects as `question_not_found` before input.
+
+`options` accepts optional positive finite `timeoutMs` (default 20,000) and
+`signal: AbortSignal`. Long deadlines use bounded timer chunks. A single answer transaction owns the physical question
+input lane; overlapping calls reject as `question_answer_failed` before reading
+caller answer or options fields, including stale IDs and invalid batches. When
+no attempt owns the lane, unknown or retired IDs reject as `question_not_found`
+before input. It operates
+even while an ordinary queued writer or ergonomic turn is waiting. Every write
+revalidates current completed native frames, live request ownership and caller
+intervention. Raw keys and interruption revoke the transaction. Timeout,
+cancellation, changed/unsupported layout, rejected input and uncertain acceptance
+reject with content-free `question_answer_failed`; a submitting Enter is never
+blindly retried. Closing the session prevents further writes. Failures may expose
+only fixed `details.category` categories: `frame_wait`, `adapter`, `terminal_write`,
+`native_acceptance`, or `aborted`; they never retain raw exceptions or answer text.
+
+A failed attempt that has not started a physical write can remain answerable. If
+input may have reached the CLI and native acceptance is unconfirmed, the API
+request closes once as `unavailable` and disappears from snapshots. Retrying its
+ID rejects as `question_not_found` before input. Elwood retains the native identity
+and holds ordinary automation until correlated native closure, turn end or
+shutdown releases it. Redraws, changed metadata for that same reserved identity
+and late write completion cannot republish or reauthorize the request. Native
+closure releases this reservation silently, without a second question closure.
+Both the physical write and the correlated native reservation must settle before
+ordinary input can resume, whichever settles first. The API closure alone does
+not mean the CLI is ready for ordinary input.
+
+Pending requests and native question editors hold ordinary prompt, command,
+loop and login writes. Native lifecycle status remains independent of queued
+question availability. Unknown question layouts are hold-only, observable through
+the existing terminal/attention surfaces, and never receive guessed keys.
+
+Claude `AskUserQuestion` hooks supply grouped request metadata. A request is
+published only when its matching native questionnaire is visible; direct caller
+hook answers and denials retain precedence and do not create a phantom pending
+request, even if a matching stale screen is still visible. Initial hook activity
+keeps its existing timing; discovery waits for that exact caller decision and
+then a fresh completed native paint.
+Overlapping Claude hooks retain independent native tool-use identities and exact
+caller outcomes, including out-of-order resolution and completion. A pending
+outcome withholds only its matching candidate; it cannot suppress discovery of an
+unrelated resolved request. Matching `PermissionRequest` mirrors retain the
+original candidate even when their hook IDs differ. A native panel that matches
+multiple independent candidates grants no answer authority; ownership remains
+held until native evidence disambiguates it. ID-less completion requires one
+uniquely matching candidate and cannot retire an ambiguous group.
+The adapter supports the captured single-choice, checkbox, tabbed sequential
+question and review stages, with alternative free text. It requires a recognized
+initial first-question stage; a human-navigated unsupported partial stage rejects
+safely. Only a matching `AskUserQuestion` completion acknowledges the whole
+request. A supplied native completion ID must match the active request; without an ID,
+ordered question definitions must match its prompts, headers, selection modes and
+ordered option labels/descriptions. Unrelated tools or mismatched question
+metadata cannot acknowledge, cancel or retire that request. The standard hook
+timeout is unchanged and never waits for a human answer.
+
+Codex native text acceptance normalizes CRLF and CR to LF, then trims Rust
+Unicode White_Space at both ends (U+FEFF is retained); interior whitespace is
+preserved. Queued selected labels are trimmed; modal selected labels remain
+exact and optional notes use the text normalization. Long, clipped, multiline and literal placeholder text is accepted only while
+the submitted text remains in the same native question editor. The complete
+committed native answer must match the submitted answer before success.
+Unsupported or opaque Codex native identities reserve ordinary automation until
+explicit native turn end; raw human terminal input remains available.
+Codex metadata budget overflow emits one content-free `question_automation_disabled`
+warning and normalized warning activity per session, then disables automation.
+
+A successful Claude final submission awaits matching native completion through
+a newly empty composer. An interrupted, unconfirmed answer retires the API
+request while retaining its native identity and input hold until native closure;
+a later acknowledgement releases that reservation without another closure event.
+
+Question notification failures are contained without changing request state or
+native input holds. The first failed question or companion question-activity
+observer in a live session produces the content-free `question_observer_failed`
+warning and normalized warning activity specified in [§5.4](5.4-events.md).