@with-logic/elwood 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -12,10 +12,57 @@ back each entry are listed in PRD.md §14.
 
 ## [Unreleased]
 
-First public release.
+## [0.1.1]
+
+First usable public release.
+
+0.1.0 was published from a checkout that sat 18 commits behind `main`. It
+shipped without the `resume`, `sessions`, `interactive` and `models`
+subcommands, without `--high-trust`, without agent auto-detection, and with a
+stale README. Nothing was wrong with 0.1.0's own code; it was simply built from
+the wrong commit. 0.1.1 is the same work published from `main`, and is the
+version to install.
 
 ### Added
 
+- **The `elwood` CLI now explains and cleanly overrides its effective behavior.**
+  `--no-stream` and `--no-verbose` reverse inherited boolean defaults,
+  `--no-defaults` bypasses saved config and `ELWOOD_*` run settings, and
+  `elwood config effective` reports validated launch/output values with their
+  provenance without starting an agent. Routine warnings now reach stderr for
+  text and JSON runs, `--verbose` is a concise elapsed progress view, and
+  `--debug` retains full sanitized event detail. JSONL records include elapsed
+  timing plus tool-call correlation IDs when available. Help, validation errors,
+  resume/persona/ephemeral wording, and the new scripting guide now make defaults,
+  recovery actions, and lifecycle effects explicit. (§5.8/§12A,
+  C-API-48/C-CLI-02/03/08/10/11/14/19/20)
+- **The `elwood` CLI can now mirror the live agent TUI in the current terminal.**
+  `--head` sends the agent's ordered raw VT/ANSI stream to terminal stderr while
+  preserving the final text or JSON result on stdout, including cursor-addressed
+  redraws, alternate screens, colors, spinners, and OSC title changes. It follows
+  terminal resizes, restores terminal modes on every handled outcome, and treats
+  Ctrl-C like the existing interrupt lifecycle. The display is intentionally
+  view-only and cannot be combined with `--stream`, `--verbose`, or JSONL.
+  Pending terminal writes are bounded by bytes and frame count, so a stalled
+  terminal becomes a clean run failure instead of an unbounded memory queue.
+  An argument-free `elwood` invocation now prints help instead of waiting for a
+  prompt. (§12A.1/§12A.6, C-CLI-02/C-CLI-18)
+- **The `elwood` CLI gained `sessions`, `resume`, `interactive`, and `models`
+  commands.** `elwood sessions` lists Elwood-owned session records (id, agent,
+  workspace, `createdAt`/`lastUsedAt`, `resumable`, socket-presence `live`) as an
+  aligned table or one `{"type":"sessions"}` JSON document without starting an
+  agent. `elwood resume <id> [prompt...]` is a parse-time rewrite of
+  `run --resume <id>`. `elwood interactive [id]` runs the real `claude`/`codex`
+  TUI in the foreground with Elwood's resolved agent, model, effort, workspace,
+  and posture passed as the agent's own flags — no PTY, automation, observation,
+  or state — resuming a stored session's own conversation when given an id.
+  `elwood models` starts the agent briefly, reads its model picker through the
+  public `listModels` operation, tears the session down, and prints a table or a
+  `{"type":"models"}` document of `AgentModelOption` rows. The adapters' launch
+  flag mapping now lives in shared `claudeLaunchArguments`/`codexLaunchArguments`
+  builders so interactive and headless launches cannot drift. (§12A.7–§12A.10,
+  C-CLI-21 through C-CLI-24)
+
 - Claude Code and Codex CLI adapters that run the real interactive CLI in a
   PTY, launched through the user's login shell, and observe it through a
   headless xterm.js model. macOS only; Claude Code 2.1.144+ and Codex CLI
@@ -86,10 +133,27 @@ First public release.
   `agent`, a new run tries `claude` then `codex` in the login shell and fails
   with `no_agent_found` (status 2) when neither resolves. Error records
   emitted before an agent was selected report `agent: null`.
+- An agent-neutral "never ask for permissions" switch: `--high-trust` /
+  `--no-high-trust`, `ELWOOD_HIGH_TRUST`, the `highTrust` config key, and
+  `highTrust?: boolean` on both session classes and both resume functions. It
+  expands to Claude `permissionMode: "bypassPermissions"` or Codex
+  `sandbox: "danger-full-access"` with `approvalPolicy: "never"` before the
+  posture is persisted and the process spawned. Combining it with an explicit
+  per-agent posture is rejected: the CLI names both sources as a usage error and
+  the library throws `claude_high_trust_conflict` / `codex_high_trust_conflict`.
+  `config effective` reports `highTrust` and attributes the posture it decided
+  to the high-trust source. Claude's one-time "running in Bypass Permissions
+  mode" acceptance dialog is an allowlisted trust prompt answered under
+  `autotrust` (`startup_prompt` label `bypass_permissions`).
 
 ### Changed
 
 - Published as `@with-logic/elwood` under the MIT license.
+- The published package runs no install scripts. `dist/` is built before publish
+  (`prepublishOnly`) and shipped in the tarball, so `npm install -g
+  @with-logic/elwood` needs no build step and raises no npm allow-scripts
+  prompt for Elwood itself. Working from a checkout now requires an explicit
+  `npm run build` before `npm link`.
 - Warnings are live-only events. Nothing is persisted, replayed, or counted;
   there is no `session.warnings` property.
 - The persisted session record holds only schema version, `elwoodSessionId`,
@@ -109,6 +173,107 @@ First public release.
 
 ### Fixed
 
+- **Headed runs no longer suspend themselves or leave the invoking terminal unusable.**
+  Interactive version and capability probes now run in an isolated process session,
+  preventing their shell-managed commands from stealing the real terminal's foreground
+  process group. `--head` can therefore restore cooked input and display modes before
+  returning to an interactive shell, without a cleanup-time `SIGTTOU` stop or leaked
+  terminal-protocol replies. Its defensive restore now also pops the Kitty keyboard
+  enhancement mode used by current agent TUIs, so subsequent shell keystrokes remain
+  ordinary text instead of encoded key-event sequences. (§12A.6, C-CLI-18)
+- **Codex's startup update dialog no longer wedges headed or headless runs.**
+  Codex 0.153.x can paint its numbered update menu before its input loop accepts
+  the first safe Skip hotkey. Elwood now retries that hotkey for a bounded interval
+  only after revalidating the complete current update dialog, and the CLI no longer
+  mistakes the responder-owned dialog's replayed blocking edge for a human prompt.
+  A persistent or unanswerable update dialog now fails and cleans up boundedly even
+  without `--timeout`; no retry can escape into the composer or another dialog.
+  (§5.5/§12A.2, C-CODEX-12/C-CLI-05)
+- **Headless turns now survive real-CLI startup, resume, and teardown races.**
+  Codex 0.153.3 can accept the 10-second fallback paste into its cold-start
+  placeholder, swallow it during a later boot repaint, and appear to finish an
+  empty turn; ergonomic turns now require positive submission evidence, replay
+  an unaccepted prompt at most twice, and fail explicitly instead of reporting
+  false success. A resumed Claude turn no longer treats its stale composer as
+  an immediate end before real work paints. The headless owner also ignores
+  transient attention from trust prompts it is already authorized to answer,
+  and macOS teardown retries the short-lived post-exit `EPERM` process-group
+  window instead of surfacing `cleanup_failed`. (§5.3/§5.8/§12A, C-API-48,
+  C-TURN-03, C-CLI-05/09)
+- **Claude model switches now complete through model/effort cache warnings.**
+  Claude 2.1.258 may interpose `Switch model?` or `Change effort level?` after
+  Elwood applies a session-only picker choice; Elwood previously treated that
+  dialog as successful picker closure and returned while the session was still
+  waiting. Elwood now recognizes numbered and unnumbered variants, navigates
+  from the rendered cursor to the affirmative action, confirms the built-in
+  cache warning, and waits for the idle composer before resolving `setModel`.
+  Recognition is scoped to the bottom-most live dialog and revalidated before
+  Enter, so transcript text cannot spoof a cache warning or composer. Hook-requested
+  `PreModelSwitch` confirmations remain blocking and human-controlled. (§5.3,
+  C-API-24/C-ATTN-04)
+- **Concurrent Codex starts no longer race global npm updates.** Codex's live
+  update dialog is now input-blocking until its rendered frame clears, so queued
+  persona/caller input cannot press Enter on the default "Update now" action when
+  a prompt layout is partial or drifts. Elwood still skips every recognized safe
+  option automatically. Separately, `autoupdate` now holds an atomic per-user,
+  per-adapter cross-process lease around the global updater; another Elwood host
+  waits asynchronously, skips its duplicate install, and validates the resulting
+  binary. The lease uses a stable account cache across differing `TMPDIR` values,
+  records its owner/generation so live or successor updates cannot be evicted,
+  and recovers dead owners safely. Failed partial installs also invalidate version
+  and capability caches before validation. Coal Harbor and other consumers need
+  no API or configuration changes. (§5.5/§9.2, C-CODEX-12/C-PERF-04/C-LIFE-09)
+- **Claude's current cursor-style workspace trust prompt is auto-approved again.**
+  Claude 2.1.252 replaced the older numbered, affirmative-first layout with an
+  unnumbered menu that defaults to `No, exit`; the responder recognized its header
+  but found no numbered affirmative, wrote nothing, and the readiness fallback
+  could report `ready` over the still-visible gate. Elwood now supports both
+  layouts, navigates cursor menus to the affirmative before Enter, keeps their
+  entire option region out of header recognition, and verifies the real trust
+  screen clears before readiness. The gate remains independent of Claude's
+  `bypassPermissions` / `--dangerously-skip-permissions` policy. (§5.1/§5.3,
+  C-CLAUDE-10/C-CLAUDE-14/C-E2E-09)
+- **Modern Codex final replies now carry their text on `assistant_message`
+  activity.** Codex 0.149.1 writes replies as assistant `message` response items
+  with `phase: "final_answer"` and `content[].output_text`; Elwood previously
+  expected a plain string (or a legacy `agent_message` duplicate), so consumers
+  received a textless event and could silently discard the reply. Elwood now
+  extracts the full final-answer text—including `@mentions`—while keeping
+  commentary and user/developer transcript records out of assistant activity.
+  (§5.4/§7A.4, C-API-12/C-CODEX-16)
+- **Claude's `Not logged in · Run /login` sign-out is now detected mid-session.**
+  A ready Claude session that gets logged out mid-run renders `Not logged in`
+  (paired with a `run /login` hint) — a different wording than the `Login expired`
+  / `Session expired` / `OAuth token revoked` banners Elwood already recognized.
+  That form previously went undetected mid-session, so no `login_expired` warning
+  fired. It now surfaces the same content-free `login_expired` warning (+ `warning`
+  activity), leaving the session alive to recover via `session.login()`. (§5.3/§5.7,
+  C-CLAUDE-17/18)
+- **Codex's in-TUI update prompt is now re-skipped on the restart loop.** Elwood
+  always skips Codex's interactive "update available" prompt (it never selects
+  "Update now"; the real update is the `autoupdate` preflight). The skip was latched
+  once per session, so if Codex restarted and the SAME update screen reappeared — the
+  update did not take — the session got stuck looping on it. The skip is now
+  edge-triggered: it re-arms when the update screen leaves the frame and re-skips the
+  reappearance. (§5.5, C-CODEX-12)
+- **Autoupdate is now best-effort and never fails a start on its own.** When
+  `autoupdate: true` and `claude update` / `codex update` fails (a flaky network,
+  a partial native-installer download, contention during a fleet launch), Elwood no
+  longer rejects `startClaude`/`startCodex` with `claude_update_failed` /
+  `codex_update_failed`. If the INSTALLED CLI still meets the minimum version, the
+  session starts from it and Elwood emits a live `agent_update_failed` warning (safe
+  diagnostics only: installed version, an allowlisted error code, bounded stderr).
+  Startup fails only when the installed version is actually below the minimum. The
+  warning is zero-burden — a consumer that does not subscribe to `warning` is
+  unaffected and the session still reaches `ready`. (§9.2, C-LIFE-11)
+- **A failed shared update no longer poisons the process.** A once-per-process
+  update/probe cache that rejected was retained and replayed, so one failed
+  `claude update` could reject every concurrent roster start AND every later start
+  until the process restarted. Cached probes (autoupdate, version read, capability
+  detection) now never retain a rejected result: concurrent callers share one attempt
+  and a later caller re-attempts rather than inheriting the failure. (§9.2,
+  C-LIFE-09/11)
+
 - Trust, update, and model-switch dialogs on current Claude and Codex releases
   are recognized and answered; unrecognized dialogs block instead of guessing.
 - Hook payloads are measured identically on both sides of the bridge, and

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Logic, Inc.
+Copyright (c) 2026 Logic App, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,14 +1,52 @@
-# Elwood
-
-Elwood is a TypeScript library and command-line tool for driving interactive
-agentic coding CLIs through real terminal sessions. It starts tools like Claude
-Code and Codex the way they are designed to run, inside an interactive PTY, and
-lets a host application send prompts and key presses, render the live terminal,
-and observe a typed event stream for hooks, tool calls, transcript activity,
-warnings, and lifecycle state. The governing constraint is that the agent should
-not know it is wrapped: the process stays interactive, runs in the user's normal
-shell environment, and is controlled through the hooks and transcripts the CLI
-already provides. The first supported adapters are Claude Code and Codex CLI.
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="site/assets/landing/robot-mark-dark.webp" />
+    <img src="site/assets/landing/robot-mark-light.webp" alt="" width="96" height="96" />
+  </picture>
+  <h1>Elwood</h1>
+  <p><a href="https://elwood.bot">elwood.bot</a></p>
+</div>
+
+**Automate real Claude Code and Codex sessions in headless PTYs.**
+
+Write scripts that control normal interactive Claude Code and Codex sessions,
+which use your regular subscription rather than metered API billing. Elwood
+starts the actual agent CLI in a hidden terminal and types into it the way you
+would. The agent keeps its tools, hooks, configuration, and login.
+
+```sh
+npm install -g @with-logic/elwood
+elwood "Explain this project's architecture."
+```
+
+```ts
+import { ClaudeSession } from "@with-logic/elwood";
+
+const session = new ClaudeSession({ cwd: "/path/to/project" });
+console.log(await session.send("Explain this project."));
+await session.close();
+```
+
+---
+
+## Why Elwood
+
+> **The agent should not know it is wrapped.**
+
+Headless agent APIs give you a different product than the CLI your team
+actually uses: different tools, different hooks, different billing. Elwood
+drives the real interactive CLI instead. The process stays interactive, runs in
+your normal shell environment, and is controlled through the hooks and
+transcripts the CLI already provides.
+
+- **Your subscription, not an API key.** It is the same interactive session you
+  run by hand, so it bills the way that session already bills.
+- **A small API over a real terminal.** `send()` returns a string. `stream()`
+  yields typed events. The CLI keeps its own tools and history.
+- **Typed activity, not screen scraping.** Assistant text, reasoning, tool
+  calls and results, hooks, warnings, and lifecycle arrive as one event stream.
+- **Two ways in.** A TypeScript library for applications, and an `elwood`
+  command for shell scripts and pipelines.
 
 `PRD.md` is the source of truth for observable behavior. If this README, the
 tests, or the implementation disagree with the PRD, the PRD wins.
@@ -30,8 +68,11 @@ continues. Pass `strictVersionCheck: true` to fail closed instead.
 npm install @with-logic/elwood
 ```
 
-The package installs an `elwood` executable for the headless CLI. To work from a
-checkout instead, run `npm install && npm run build && npm link`.
+The package installs an `elwood` executable for the headless CLI. It ships a
+prebuilt `dist/`, so a global install runs no build step and no install scripts
+of its own. To work from a checkout instead, run
+`npm install && npm run build && npm link`; the build is explicit because
+`dist/` is not committed.
 
 ## Quickstart: library
 
@@ -105,6 +146,194 @@ and `blocked` (a dialog needs a human) and ends in `stopped`, `exited`,
 `<cwd>/.elwood` by default, or under an explicit `stateDir`. It holds what
 resume needs and nothing else.
 
+## Headless CLI
+
+### Live terminal view
+
+Add `--head` when you want to watch the real agent interface while retaining a
+pipeline-friendly final result:
+
+```sh
+elwood --head "Run the test suite and fix the failure"
+elwood --head --output json "Review this repository" >result.json
+elwood --head --agent claude "Explain the architecture"
+```
+
+The display stays in the current terminal and receives the raw PTY byte stream on
+stderr. It is a real VT/ANSI mirror, so full-screen layouts, cursor-addressed
+updates, alternate-screen buffers, colors, spinners, and title changes render as
+they do in the underlying Claude or Codex client. Stdout remains only the final
+text or JSON protocol and can be redirected independently. Pending display work
+is capped at 4 MiB or 1,024 frames; a terminal that remains backpressured fails
+the run cleanly after draining accepted bytes instead of growing memory without
+bound.
+
+Head mode is deliberately view-only: while attached, ordinary keyboard, mouse,
+paste, and terminal-response bytes are discarded; Ctrl-C still interrupts using
+Elwood's normal first-interrupt/repeated-force-kill lifecycle. Terminal resizes
+propagate to the agent. Elwood restores raw/cooked input state, mouse and paste
+modes, attributes, cursor visibility, and the main screen before printing the
+final result. Both stdin and stderr must be terminals, and `--head` cannot be
+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:
+
+```sh
+first=$(elwood --keep --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"
+```
+
+Resume uses the exact stored agent and workspace; conflicting `--agent` and any
+`--cwd` are rejected. Resumed sessions stay preserved after success or failure unless
+`--ephemeral` requests teardown. Ephemeral teardown removes Elwood's session
+record and loop definitions; it does not undo workspace changes or delete
+conversation history owned by Claude or Codex. CLI state defaults to absolute
+`$XDG_STATE_HOME/elwood` or `~/.local/state/elwood`; its private records contain
+resume metadata, not ordinary prompts or output.
+
+Before launching, `elwood config effective [run options]` prints the resolved
+settings and where each came from. The JSON includes `head` and, for Claude,
+the effective `permissionMode`, `allowedTools`, `disallowedTools`, and `tools`;
+resume inspection reports persisted tool rules with stored-session provenance.
+
+Exit status is `0` for success or a closed consumer, `1` for agent/runtime or
+cleanup failure, `2` for usage/configuration failure, `124` for timeout, and
+`130` for interruption. The first Ctrl-C requests a clean interrupt; a repeated
+Ctrl-C force-kills before cleanup.
+
+`--persona` runs an actual extra agent turn before the requested turn. Elwood
+discards that setup turn's answer, but any tools it invokes or files it changes
+remain. It is therefore supported only for new sessions, never `--resume`.
+
+### Sessions, resume, and interactive mode
+
+`elwood sessions` lists the Elwood-owned session records in the effective state
+directory without starting an agent, and `elwood resume <id>` is the subcommand
+form of `--resume <id>`:
+
+```sh
+elwood sessions
+elwood sessions --state-dir ./state --output json | jq -r '.sessions[] | .id'
+elwood resume "$id" "What is the release color?"
+git diff | elwood resume "$id" --ephemeral "Does this diff match what we agreed?"
+```
+
+The table (or the `sessions` array in JSON) reports each session's id, agent,
+workspace, `createdAt`/`lastUsedAt` timestamps, whether it is `resumable`
+(the agent's own conversation id is stored), and `live` — whether a launch's
+bridge socket file is currently present. `live` is a cheap file-presence
+signal: a socket left behind by a force-killed owner reads as live until that
+session is next started or torn down. Unreadable records are skipped with a
+stderr warning, and an empty state directory is a normal empty result.
+`resume <id>` follows every `--resume` rule: stored agent and workspace, no
+`--cwd`, no `--keep`, no persona, and piped stdin composes the same way.
+
+`elwood interactive [id]` opens the real `claude` or `codex` TUI in the current
+terminal — no hidden PTY, no automation, no observation, no Elwood state — with
+Elwood's resolved agent, model, reasoning effort, workspace, and posture passed
+as the agent's own flags. It exits with the agent's exit status and needs a
+terminal on stdin and stdout:
+
+```sh
+elwood interactive                      # the configured agent, its own defaults
+elwood interactive --agent claude --model opus --claude-permission-mode plan
+elwood interactive "$id"                # the stored conversation, workspace, and posture
+```
+
+Built-in headless posture defaults (Claude `dontAsk`, Codex `workspace-write`
+and `never`) are not applied unless a flag, environment variable, config key,
+or stored record selected them, so an unconfigured launch is the agent's own
+default experience. A session kept by a headless run does store its headless
+posture; pass `--claude-permission-mode default` (or the Codex flags) to get the
+agent's prompts back when resuming one interactively. Because the agent owns
+the resumed conversation, a later `elwood resume <id>` sees what you said. The
+command rejects `--output json|jsonl`, `--stream`, `--verbose`, `--debug`,
+`--head`, `--timeout`, `--persona`, `--image`, `--keep`, `--ephemeral`, and
+`--resume`.
+
+### Listing models
+
+`elwood models` starts the selected agent briefly, opens and cancels its own
+model picker, tears the session down, and prints the rows. Text marks the
+current model with `*` and the default with `(default)`; JSON is one
+`{"schemaVersion":1,"type":"models",...}` document of `AgentModelOption` rows:
+
+```sh
+elwood models
+elwood models --agent claude --output json | jq -r '.models[] | select(.isCurrent) | .id'
+```
+
+Starting the agent is unavoidable because the picker is the only source of the
+list. The command honors `--agent`, `--cwd`, `--model`, `--reasoning-effort`,
+`--timeout`, `--state-dir`, trust, and posture flags, leaves no Elwood state
+behind, and maps failures (timeout, interruption, blocked prompts) to the usual
+statuses and error documents.
+
+### 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/extension approvals. Any other recognized dialog fails safely as
+`blocked_prompt` instead of hanging or guessing.
+
+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 permissions.
+Global config is never loaded from the repository being opened.
+
+Head mode renders agent-controlled terminal escape sequences verbatim, just as
+running the selected interactive CLI directly would. Use it only with agents and
+workspaces you trust to control the current terminal display.
+
+## Try It Locally
+
+Elwood includes two local test apps.
+
+```sh
+# Terminal smoke app, Claude by default.
+npm run dev:app -- --cwd /path/to/project
+
+# Terminal smoke app with Codex.
+npm run dev:app -- --agent codex --cwd /path/to/project
+
+# Resume from Elwood metadata.
+npm run dev:app -- --cwd /path/to/project --resume <elwoodSessionId>
+
+# Browser debugger with xterm.js terminal mirror and structured event inspector.
+npm run dev:web
+```
+
+`dev:web` serves `http://localhost:4317`. It shows the live terminal on the left
+and a structured event timeline on the right. Use it to inspect hooks,
+activities, warnings, startup automation, status changes, and raw event payloads.
+
+The script is still invoked through npm, but the browser dev server process runs
+under Node so `node-pty` can own a real interactive PTY reliably.
+
+## Runnable Examples
+
+For the smallest real usage sample, run the minimal example. It constructs a
+`CodexSession`, which starts Codex lazily on the first `send`, then makes two
+ergonomic `send` calls — an initial prompt and a follow-up that refers back to it —
+printing each assistant response, and closes the session:
+
+```sh
+npm run example:minimal
+```
+
+For a fuller sample with Claude/Codex selection, custom prompts, richer logging,
+timeouts, and cleanup options, run `examples/full.ts`:
+
+```sh
+npm run example:full
+npm run example:full -- --agent codex --cwd . --prompt "Summarize this repo in one paragraph."
+```
+
 ## Hooks and policy
 
 Handlers return `undefined` for "no decision". Claude:
@@ -228,6 +457,11 @@ immediate; both are safe after the process has already exited.
   `autotrust`), Codex hook-trust and update dialogs, and Claude's browser-tools
   onboarding. Any other dialog leaves the session `blocked` for a human; the
   CLI fails such runs as `blocked_prompt`.
+- `--high-trust` (library `highTrust: true`) is the agent-neutral "never ask"
+  switch: Claude `bypassPermissions`, or Codex `danger-full-access` with
+  approval policy `never`. It removes the agent's own guardrails, so point it
+  only at work you would let run unattended. Combining it with an explicit
+  per-agent posture is a usage error rather than a silent override.
 - `autotrust` changes the security posture of the launched agent. Point it only
   at directories you already trust. The standalone `listClaudeModels` /
   `listCodexModels` probes always start with `autotrust: true`.
@@ -292,6 +526,28 @@ immediate; both are safe after the process has already exited.
   low-level examples.
 - [PRD.md](PRD.md): the behavior specification and conformance criteria.
 - [CHANGELOG.md](CHANGELOG.md): consumer-facing changes.
+- [site/](site/): the landing page and the generated documentation site.
+
+## The website
+
+[`site/`](site/) is the landing page and the generated documentation site,
+deployed to Vercel from this repository and served at [elwood.bot](https://elwood.bot). It is a static site with no framework
+and no build step: HTML, CSS, ES modules, and the robot's sprite sheets.
+
+```sh
+cd site && python3 -m http.server 8766 --bind 127.0.0.1
+```
+
+The documentation page is generated from Markdown sources in
+[`site/docs/guide/`](site/docs/guide/) and reads the CLI's help text out of
+`src/cli/help.ts`, so the published flag reference cannot drift from the code:
+
+```sh
+cd site
+uv run scripts/build_docs.py        # regenerate guide/, llms.txt, llms-full.txt
+python3 scripts/check_doc_examples.py   # typecheck every documented example
+node --test tests/*.test.mjs        # the landing page's own tests
+```
 
 ## License
 
@@ -302,3 +558,10 @@ MIT. See [LICENSE](LICENSE).
 Setup, the merge gate, the e2e suite, the dev apps, and the repository map are
 in [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately as
 described in [SECURITY.md](SECURITY.md).
+
+---
+
+<div align="center">
+  Prompted with ❤️ by <a href="https://logic.inc">Logic, Inc</a> in Seattle, WA
+  <img src="site/assets/landing/space-needle.svg" alt="" width="13" height="13" />
+</div>

package/dist/claude/command.d.ts

@@ -1,8 +1,15 @@
 /**
- * Builds the shell command used to launch interactive Claude.
- * Implements PRD §4.2 and §9.1.
+ * Builds the launch arguments and shell command used to start interactive Claude.
+ * The argument list is shared by the headless PTY launch and `elwood interactive`
+ * (§12A.9), so the Elwood-to-Claude flag mapping cannot drift between them.
+ * Implements PRD §4.2, §9.1, and §12A.9.
  */
 import type { StartClaudeOptions } from "../core/types.ts";
+import { type LaunchArgument } from "../runtime/launch-arguments.ts";
+/** The subset of start options that become Claude's own command-line flags. */
+export type ClaudeLaunchArgumentOptions = Pick<StartClaudeOptions, "model" | "reasoningEffort" | "permissionMode" | "allowedTools" | "disallowedTools" | "tools" | "name">;
+/** Claude's native flags for a launch, in stable order (no `--settings`). */
+export declare function claudeLaunchArguments(options: ClaudeLaunchArgumentOptions, resumeId?: string): readonly LaunchArgument[];
 export declare function buildClaudeShellCommand(settingsPath: string, options: StartClaudeOptions, resumeId?: string): string;
 export declare function shellLaunch(shell: string, command: string): {
     readonly command: string;

package/dist/claude/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/claude/command.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAoBR;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAEhE"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/claude/command.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,KAAK,cAAc,EAAoB,MAAM,gCAAgC,CAAC;AAGvF,+EAA+E;AAC/E,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,kBAAkB,EAChB,OAAO,GACP,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,OAAO,GACP,MAAM,CACT,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,2BAA2B,EACpC,QAAQ,CAAC,EAAE,MAAM,GAChB,SAAS,cAAc,EAAE,CAgB3B;AAED,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAIR;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAEhE"}

package/dist/claude/command.js

@@ -1,31 +1,38 @@
 /**
- * Builds the shell command used to launch interactive Claude.
- * Implements PRD §4.2 and §9.1.
+ * Builds the launch arguments and shell command used to start interactive Claude.
+ * The argument list is shared by the headless PTY launch and `elwood interactive`
+ * (§12A.9), so the Elwood-to-Claude flag mapping cannot drift between them.
+ * Implements PRD §4.2, §9.1, and §12A.9.
  */
+import { launchShellWords } from "../runtime/launch-arguments.js";
 import { loginShellCommand, shellQuote } from "../runtime/shell.js";
-export function buildClaudeShellCommand(settingsPath, options, resumeId) {
-    const parts = ["exec", "claude", "--settings", shellQuote(settingsPath)];
+/** Claude's native flags for a launch, in stable order (no `--settings`). */
+export function claudeLaunchArguments(options, resumeId) {
+    const parts = [];
     if (resumeId)
-        parts.push("--resume", shellQuote(resumeId));
+        parts.push(["--resume", resumeId]);
     if (options.model)
-        parts.push("--model", shellQuote(options.model));
+        parts.push(["--model", options.model]);
     // Validated before spawn in the preflight (C-CLAUDE-20); forwarded verbatim here.
     if (options.reasoningEffort)
-        parts.push("--effort", shellQuote(options.reasoningEffort));
-    if (options.permissionMode) {
-        parts.push("--permission-mode", shellQuote(options.permissionMode));
-    }
+        parts.push(["--effort", options.reasoningEffort]);
+    if (options.permissionMode)
+        parts.push(["--permission-mode", options.permissionMode]);
     if (options.allowedTools && options.allowedTools.length > 0) {
-        parts.push("--allowedTools", shellQuote(options.allowedTools.join(",")));
+        parts.push(["--allowedTools", options.allowedTools.join(",")]);
     }
     if (options.disallowedTools && options.disallowedTools.length > 0)
-        parts.push("--disallowedTools", shellQuote(options.disallowedTools.join(",")));
+        parts.push(["--disallowedTools", options.disallowedTools.join(",")]);
     // --tools is a true allowlist; an empty list ("") disables all tools.
     if (options.tools !== undefined)
-        parts.push("--tools", shellQuote(options.tools.join(",")));
-    if (options.name) {
-        parts.push("--name", shellQuote(options.name));
-    }
+        parts.push(["--tools", options.tools.join(",")]);
+    if (options.name)
+        parts.push(["--name", options.name]);
+    return parts;
+}
+export function buildClaudeShellCommand(settingsPath, options, resumeId) {
+    const parts = ["exec", "claude", "--settings", shellQuote(settingsPath)];
+    parts.push(...launchShellWords(claudeLaunchArguments(options, resumeId)));
     return parts.join(" ");
 }
 export function shellLaunch(shell, command) {

package/dist/claude/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/claude/command.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEpE,MAAM,UAAU,uBAAuB,CACrC,YAAoB,EACpB,OAA2B,EAC3B,QAAiB;IAEjB,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;IACzE,IAAI,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3D,IAAI,OAAO,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,kFAAkF;IAClF,IAAI,OAAO,CAAC,eAAe;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IACzF,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,OAAO,CAAC,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QAC/D,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjF,sEAAsE;IACtE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5F,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,OAAe;IAEf,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/claude/command.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAuB,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvF,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAcpE,6EAA6E;AAC7E,MAAM,UAAU,qBAAqB,CACnC,OAAoC,EACpC,QAAiB;IAEjB,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,IAAI,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjD,IAAI,OAAO,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1D,kFAAkF;IAClF,IAAI,OAAO,CAAC,eAAe;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IAC/E,IAAI,OAAO,CAAC,cAAc;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,mBAAmB,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IACtF,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,CAAC,gBAAgB,EAAE,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,CAAC,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QAC/D,KAAK,CAAC,IAAI,CAAC,CAAC,mBAAmB,EAAE,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACvE,sEAAsE;IACtE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAClF,IAAI,OAAO,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,YAAoB,EACpB,OAA2B,EAC3B,QAAiB;IAEjB,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;IACzE,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,qBAAqB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,OAAe;IAEf,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;AAC9D,CAAC"}

package/dist/claude/session/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/claude/session/index.ts"],"names":[],"mappings":"AAAA,+HAA+H;AAM/H,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAK9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EAAE,oCAAoC,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAEjG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EACL,oCAAoC,IAAI,+BAA+B,EACvE,4BAA4B,GAC7B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAErF;AAED,gGAAgG;AAChG,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,kBAAkB,EAC9B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAe3B;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,EAChB,gBAAgB,EAAE,sBAAsB,GAAG,SAAS,sDAwBrD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/claude/session/index.ts"],"names":[],"mappings":"AAAA,+HAA+H;AAO/H,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAK9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EAAE,oCAAoC,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAEjG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EACL,oCAAoC,IAAI,+BAA+B,EACvE,4BAA4B,GAC7B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAErF;AAED,gGAAgG;AAChG,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,kBAAkB,EAC9B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAiB3B;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,EAChB,gBAAgB,EAAE,sBAAsB,GAAG,SAAS,sDAwBrD"}

package/dist/claude/session/index.js

@@ -1,6 +1,7 @@
 /** ClaudeSessionApi entry points: preflight, record creation, and socket-home-guarded start. Implements PRD §5, §6, §8, §9. */
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { applyClaudeHighTrust } from "../../core/high-trust.js";
 import { queuePersonaMessage } from "../../core/persona.js";
 import { claudeReasoningEfforts, validateReasoningEffort } from "../../core/reasoning-effort.js";
 import { withSocketHomeCleanup } from "../../runtime/startup/cleanup.js";
@@ -27,8 +28,10 @@ export async function startClaudeWithId(rawOptions, elwoodSessionId) {
     // path resolved after the await could point elsewhere if the caller's (or preflight's)
     // process.cwd() changed during it, splitting where state is written from where the CLI
     // launches (§8.1, §8.2). Thread the resolved cwd everywhere so the record, launch, and
-    // PTY spawn all agree.
-    const options = { ...rawOptions, cwd: resolve(rawOptions.cwd) };
+    // PTY spawn all agree. `highTrust` expands to its concrete posture (or rejects a
+    // conflicting explicit one) HERE, before preflight, so the persisted record and the
+    // launch command both carry the expanded posture (C-API-54).
+    const options = applyClaudeHighTrust({ ...rawOptions, cwd: resolve(rawOptions.cwd) });
     const stateDir = resolve(options.stateDir ?? defaultStateDir(options.cwd));
     const strict = options.strictVersionCheck ?? false;
     const warning = await preflightClaude(strict, options.autoupdate ?? false);