@with-logic/elwood 0.1.3 → 0.2.1

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.1",
   "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).