@with-logic/elwood 0.1.1 → 0.1.2

package/examples/README.md

@@ -0,0 +1,56 @@
+# Elwood Examples
+
+## Minimal: ask and answer (`minimal.ts`)
+
+The smallest possible use of Elwood. Construct a session, `send` a message, get the
+assistant's reply back as a string, ask a follow-up. The session starts lazily on the
+first `send`, so there is no start ceremony and no manual "wait for ready".
+
+```sh
+npm run example:minimal
+```
+
+```ts
+const session = new CodexSession({ autotrust: true });
+const joke = await session.send("Tell me a joke that involves a dog.");
+const rewrite = await session.send("Now rewrite it to be about a cat.");
+await session.close();
+```
+
+## Streaming: watch the work (`stream.ts`)
+
+When you want the intermediate steps, `stream` yields typed events (`thinking`,
+`tool_call`, `tool_result`, `text`) as they arrive. `send` is just this generator
+drained for the `text`, so the two share one turn boundary.
+
+```sh
+npm run example:stream
+```
+
+```ts
+for await (const event of session.stream("List the files, then summarize the project.")) {
+  if (event.type === "text") process.stdout.write(event.text);
+  // event.type is also "thinking" | "tool_call" | "tool_result"
+}
+```
+
+## Full: the raw control surface (`full.ts`)
+
+`full.ts` drops below the ergonomic facade to the low-level API: `startClaude`/
+`startCodex`, raw `activity`/`warning`/`terminal:exit` events, an explicit
+`waitForSettled` helper (from `support.ts`) that watches `status` and
+`terminal:exit`, and CLI flags for agent/cwd/prompt/timeout. Reach for this when you
+need full control over the session lifecycle; most callers want `send`/`stream` above.
+
+```sh
+npm run example:full
+npm run example:full -- --agent codex --cwd . --prompt "Summarize this repo in one paragraph."
+npm run example:full -- --agent claude --cwd . --prompt "Summarize this repo in one paragraph."
+```
+
+All examples use `autotrust: true` so embedded sessions can move past known workspace
+trust prompts. The package scripts run the TypeScript examples under a small Node
+supervisor because `node-pty` owns real PTYs more reliably there and the supervisor can
+kill the example process tree on Ctrl-C. The examples import from `../src/index.ts`
+so they run from a checkout without a build; in your own project import the same
+symbols from `@with-logic/elwood`.

package/examples/full.ts

@@ -0,0 +1,113 @@
+/**
+ * Full runnable Elwood example for starting one agent session, sending one
+ * message, logging rich events, and cleaning up the process.
+ */
+
+import { resolve } from "node:path";
+import { startClaude, startCodex } from "../src/index.ts";
+import {
+  type Agent,
+  cleanupSession,
+  type ExampleSession,
+  errorMessage,
+  isTerminalStatus,
+  textSuffix,
+  waitForSettled,
+} from "./support.ts";
+
+type Options = {
+  readonly agent: Agent;
+  readonly cwd: string;
+  readonly keep: boolean;
+  readonly prompt: string;
+  readonly timeoutMs: number;
+};
+
+const defaultPrompt = "Say hello from Elwood in one short sentence, then stop.";
+const options = parseArgs(process.argv.slice(2));
+let session: ExampleSession | undefined;
+
+try {
+  session = await startSession(options);
+  wireLogs(session);
+  process.stdout.write(`started ${options.agent} session ${session.elwoodSessionId}\n`);
+  await session.sendMessage(options.prompt);
+  if (!(await waitForSettled(session, options.timeoutMs))) {
+    throw new Error(`Timed out after ${options.timeoutMs}ms waiting for the agent to finish.`);
+  }
+} catch (error) {
+  process.stderr.write(`${errorMessage(error)}\n`);
+  process.exitCode = 1;
+} finally {
+  if (session && !options.keep && !isTerminalStatus(session.status)) await cleanupSession(session);
+}
+
+async function startSession(options: Options): Promise<ExampleSession> {
+  const common = { cwd: options.cwd, autotrust: true, initialSize: { cols: 120, rows: 40 } };
+  return options.agent === "claude" ? await startClaude(common) : await startCodex(common);
+}
+
+function wireLogs(session: ExampleSession): void {
+  session.on("activity", (event) => {
+    process.stdout.write(
+      `[activity] ${event.agent}:${event.kind}:${event.label}${textSuffix(event.text)}\n`,
+    );
+  });
+  session.on("warning", (event) => {
+    process.stdout.write(`[warning] ${event.agent}:${event.code} ${event.message}\n`);
+  });
+  session.on("hookError", (event) => {
+    process.stdout.write(`[hookError] ${event.hookEventName}:${event.category} ${event.message}\n`);
+  });
+  session.on("terminal:exit", (event) => {
+    process.stdout.write(`[terminal:exit] code=${event.exitCode}\n`);
+  });
+}
+
+function parseArgs(args: readonly string[]): Options {
+  let agent: Agent = "codex";
+  let cwd = process.cwd();
+  let keep = false;
+  let prompt = defaultPrompt;
+  let timeoutMs = 120_000;
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index];
+    if (arg === "--help") return printUsageAndExit();
+    if (arg === "--agent")
+      [agent, index] = [parseAgent(requireValue(args, index + 1, arg)), index + 2];
+    else if (arg === "--cwd")
+      [cwd, index] = [resolve(requireValue(args, index + 1, arg)), index + 2];
+    else if (arg === "--prompt") [prompt, index] = [requireValue(args, index + 1, arg), index + 2];
+    else if (arg === "--timeout-ms")
+      [timeoutMs, index] = [Number(requireValue(args, index + 1, arg)), index + 2];
+    else if (arg === "--keep") [keep, index] = [true, index + 1];
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  if (!prompt) throw new Error("--prompt must not be empty.");
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+    throw new Error("--timeout-ms must be positive.");
+  return { agent, cwd: resolve(cwd), keep, prompt, timeoutMs };
+}
+
+function requireValue(args: readonly string[], index: number, flag: string): string {
+  const value = args[index];
+  if (!value) throw new Error(`Missing value for ${flag}.`);
+  return value;
+}
+
+function parseAgent(value: string): Agent {
+  if (value === "claude" || value === "codex") return value;
+  throw new Error("--agent must be claude or codex.");
+}
+
+function printUsageAndExit(): never {
+  process.stdout.write(
+    [
+      "Usage: npm run example:full",
+      '       npm run example:full -- --agent codex --cwd . --prompt "Summarize this repo."',
+      "",
+    ].join("\n"),
+  );
+  process.exit(0);
+}

package/examples/minimal.ts

@@ -0,0 +1,15 @@
+/**
+ * The smallest Elwood example: ask a question, get the answer, ask a follow-up.
+ * The ergonomic facade starts Codex lazily on the first `send` and gives back the
+ * assistant's text as a string (PRD §5.8).
+ */
+
+import { CodexSession } from "../src/index.ts";
+
+const session = new CodexSession({ autotrust: true });
+try {
+  process.stdout.write(`${await session.send("Tell me a joke that involves a dog.")}\n`);
+  process.stdout.write(`${await session.send("Now rewrite it to be about a cat.")}\n`);
+} finally {
+  await session.close();
+}

package/examples/stream.ts

@@ -0,0 +1,39 @@
+/**
+ * Ergonomic streaming: watch a turn's typed events — thinking, tool calls/results, and
+ * assistant text — as they arrive, instead of waiting for the final string (PRD §5.8).
+ * `send` is just this generator drained for text; `stream` is the same turn, live.
+ */
+
+import { ClaudeSession } from "../src/index.ts";
+
+/** Compile-time exhaustiveness guard: reaching this with a real value means a case is missing. */
+function assertNever(value: never): never {
+  throw new Error(`unhandled turn event: ${JSON.stringify(value)}`);
+}
+
+const session = new ClaudeSession({ autotrust: true });
+try {
+  for await (const event of session.stream("List the files here, then summarize the project.")) {
+    switch (event.type) {
+      case "thinking":
+        process.stderr.write(`  (thinking) ${event.text}\n`);
+        break;
+      case "tool_call":
+        process.stdout.write(`→ ${event.name}${event.input ? ` ${event.input}` : ""}\n`);
+        break;
+      case "tool_result":
+        process.stdout.write(`← ${event.output ?? ""}\n`);
+        break;
+      case "text":
+        process.stdout.write(event.text);
+        break;
+      default:
+        // Exhaustiveness: adding a new TurnEvent variant makes this fail to compile, so the
+        // canonical example can never silently ignore a newly-surfaced event kind.
+        assertNever(event);
+    }
+  }
+  process.stdout.write("\n");
+} finally {
+  await session.close();
+}

package/examples/support.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared helpers for runnable Elwood examples.
+ * Implements PRD §11 example behavior.
+ */
+
+import type {
+  ElwoodActivityEvent,
+  ElwoodSessionStatus,
+  ElwoodWarningEvent,
+  HookErrorEvent,
+  Unsubscribe,
+} from "../src/index.ts";
+
+export type Agent = "claude" | "codex";
+export type ExampleSession = {
+  readonly elwoodSessionId: string;
+  readonly status: ElwoodSessionStatus;
+  on(event: "activity", handler: (event: ElwoodActivityEvent) => void): Unsubscribe;
+  on(event: "warning", handler: (event: ElwoodWarningEvent) => void): Unsubscribe;
+  on(event: "hookError", handler: (event: HookErrorEvent) => void): Unsubscribe;
+  on(
+    event: "status",
+    handler: (event: { readonly status: ElwoodSessionStatus }) => void,
+  ): Unsubscribe;
+  on(event: "terminal:exit", handler: (event: { readonly exitCode: number }) => void): Unsubscribe;
+  sendMessage(message: string): Promise<void>;
+  stop(): Promise<void>;
+  kill(): Promise<void>;
+};
+
+export function waitForSettled(session: ExampleSession, timeoutMs: number): Promise<boolean> {
+  if (session.status === "ready" || isTerminalStatus(session.status)) return Promise.resolve(true);
+  return new Promise((resolveWait) => {
+    const done = (result: boolean) => {
+      clearTimeout(timer);
+      for (const unsubscribe of unsubs) unsubscribe();
+      resolveWait(result);
+    };
+    const timer = setTimeout(() => done(false), timeoutMs);
+    const unsubs: Unsubscribe[] = [
+      session.on("status", (event) => {
+        if (event.status === "ready" || isTerminalStatus(event.status)) done(true);
+      }),
+      session.on("terminal:exit", () => done(true)),
+    ];
+  });
+}
+
+export async function cleanupSession(session: ExampleSession): Promise<void> {
+  try {
+    await session.stop();
+  } catch (error) {
+    process.stderr.write(`stop failed, killing session: ${errorMessage(error)}\n`);
+    await session.kill();
+  }
+}
+
+export function isTerminalStatus(status: ElwoodSessionStatus): boolean {
+  return (
+    status === "stopped" || status === "exited" || status === "killed" || status === "torn_down"
+  );
+}
+
+export function textSuffix(text: string | undefined): string {
+  if (!text) return "";
+  return ` ${text.replace(/\s+/g, " ").slice(0, 120)}`;
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@with-logic/elwood",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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.",
@@ -26,7 +26,12 @@
   "type": "module",
   "files": [
     "dist",
-    "docs/*.md",
+    "docs/**/*.md",
+    "prd/**/*.md",
+    "examples/*.ts",
+    "examples/README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "CHANGELOG.md",
     "README.md"
   ],
@@ -60,9 +65,9 @@
     "check:lines": "node --no-warnings scripts/check-lines.ts",
     "check": "npm run build && npm run typecheck && npm run lint && npm run check:lines && npm test",
     "check:all": "npm run check && npm run test:e2e",
-    "test:e2e": "exec node --no-warnings --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/app/**' --test-coverage-exclude='tests/**' --test-timeout=240000 --test-concurrency=1 --test tests/e2e/*.e2e.ts",
-    "dev:app": "exec node --no-warnings src/app/dev.ts",
-    "dev:web": "exec node --no-warnings scripts/supervise.ts src/app/web-dev.ts",
+    "test:e2e": "exec node --no-warnings --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='tests/**' --test-timeout=240000 --test-concurrency=1 --test tests/e2e/*.e2e.ts",
+    "dev:app": "exec node --no-warnings dev/dev.ts",
+    "dev:web": "exec node --no-warnings scripts/supervise.ts dev/web/dev.ts",
     "example:minimal": "exec node --no-warnings scripts/supervise.ts examples/minimal.ts",
     "example:stream": "exec node --no-warnings scripts/supervise.ts examples/stream.ts",
     "example:full": "exec node --no-warnings scripts/supervise.ts examples/full.ts"

package/prd/01-overview.md

@@ -0,0 +1,21 @@
+## 1. Overview
+
+Elwood lets an application control an agentic coding CLI that is running in its
+native interactive terminal mode, without forcing a human to operate the TUI.
+
+The first supported tool is Claude Code. The second supported tool is OpenAI
+Codex CLI. Elwood starts the selected agent inside a real pseudoterminal,
+configured so the agent sees the same kind of interactive shell session it would
+see if the user opened Terminal.app and ran the CLI manually. Elwood then
+controls the session by writing terminal input, and observes the agent primarily
+through tool-specific hooks routed over local IPC.
+
+The core premise is deliberate: the agent should not know it is running in a
+special wrapper. Elwood does not replace Claude Code or Codex with print mode,
+non-interactive mode, SDKs, or custom protocols. It runs the real interactive
+TUI and wraps it.
+
+Parent applications can use Elwood headlessly, or attach a terminal renderer
+such as xterm.js to show the live session. A likely parent app is a local
+Tauri-style desktop app that manages many agent sessions, renders their status,
+and lets a user inspect the actual terminal when needed.

package/prd/02-goals.md

@@ -0,0 +1,47 @@
+## 2. Goals And Non-Goals
+
+### 2.1 Goals
+
+- Provide a TypeScript library for starting, controlling, stopping, killing,
+  resuming, and tearing down interactive Claude Code and Codex CLI sessions.
+- Run each agent in a real PTY so its TUI behaves as it would in a normal
+  terminal.
+- Start Claude from the user's normal macOS interactive login shell environment,
+  including startup files such as `~/.zshrc` when that is what Terminal.app
+  would load.
+- Route every Claude Code and Codex hook event through Elwood via a generated
+  per-session hook bridge.
+- Expose every hook event to the parent app with strong TypeScript types.
+- Let parent hook handlers return event-specific, strongly typed responses that
+  map to Claude Code's hook output protocol.
+- Provide a unified agent-control surface where callers can send messages and
+  observe a rich chronological activity stream without branching on the
+  underlying adapter for common chat-loop workflows.
+- Fail open when no hook handler exists, a handler times out, or a handler
+  fails at runtime.
+- Send prompts through terminal input exactly as a human would, including
+  multi-line prompts.
+- Persist only session metadata needed for resume and cleanup, plus loop
+  definitions that a caller explicitly creates as durable automation state.
+- Avoid persisting raw terminal contents, ordinary user prompts, hook payloads,
+  or conversation logs by default. A loop prompt is the narrow exception: its
+  exact text is persisted because explicit recurring automation cannot be
+  restored without it.
+- Provide a small local test app for manual development and acceptance testing.
+
+### 2.2 Non-Goals
+
+- Windows or Linux support in the MVP.
+- Additional non-Claude/non-Codex adapters in the MVP.
+- Using Claude Code print mode (`claude -p`) as the primary control mechanism.
+- Cloud execution, remote hosts, or multi-machine session sync.
+- Full visual parsing of Claude's TUI as the source of truth.
+- Installing or updating Claude Code or Codex, or performing the INITIAL
+  authentication for a fresh install. Elwood assumes `claude`/`codex` is
+  installed, on `PATH`, and initially authenticated. Elwood DOES detect a lapsed
+  Claude login and can drive the interactive `/login` re-authentication flow to
+  recover a session whose login expired mid-run (C-CLAUDE-17/18, C-API-43); it
+  never performs the human browser sign-in itself.
+- A first-class multi-session manager. Parent apps own orchestration across
+  many sessions.
+- Durable audit logging of terminal or hook activity.

package/prd/03-terminology.md

@@ -0,0 +1,32 @@
+## 3. Terminology
+
+**Elwood session.** One wrapped interactive agent CLI process. A successfully started
+session owns exactly one main CLI process: a live `ClaudeSessionApi` owns one main
+`claude` process, a live `CodexSessionApi` one main `codex` process. The ergonomic
+`ClaudeSession`/`CodexSession` classes (§5.8) are lazy wrappers that own NO process
+before start and at most one after — each wraps a single such live session.
+
+**Elwood session ID.** Stable opaque identifier generated by Elwood and exposed
+to callers as `elwoodSessionId`. Callers use this ID to resume or tear down a
+session. Claude's own session ID is internal metadata.
+
+**Agent adapter.** Tool-specific implementation layer. The MVP adapter is
+`claude` and `codex`. Future adapters might support other TUI-based agentic
+CLIs.
+
+**PTY session.** The pseudoterminal process and byte streams that make the CLI
+believe it is running in an interactive terminal.
+
+**Headless terminal.** Elwood-owned xterm.js terminal instance that renders PTY
+output into a screen model and emits terminal input back to the PTY. This model
+is required even when no UI is shown.
+
+**Terminal renderer.** Optional parent-app UI component, such as browser
+xterm.js, that renders the same live PTY stream for users.
+
+**Hook bridge.** Elwood-owned command installed into agent hook settings. The
+agent invokes it for hook events; it forwards hook input to the owning Elwood
+runtime over local IPC and returns the runtime's response to the agent.
+
+**Parent app.** The application embedding Elwood, commonly a Tauri or Electron
+desktop app.

package/prd/04-architecture.md

@@ -0,0 +1,121 @@
+## 4. Product Architecture
+
+### 4.1 Layers
+
+Elwood has three conceptual layers:
+
+1. **PTY layer.** Starts and owns the shell/agent process, terminal input,
+   terminal output, resize, graceful stop, force kill, and process status.
+2. **Agent adapter layer.** Adds tool-specific startup, generated config,
+   hook bridge, session metadata, and resume behavior. MVP adapters: Claude Code
+   and Codex CLI.
+3. **Public library layer.** Exposes TypeScript APIs and typed events to parent
+   applications.
+
+The PTY layer and a headless xterm.js terminal model are required. Elwood MUST
+write PTY output through the headless terminal before inspecting visible TUI
+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.
+
+### 4.2 macOS shell behavior
+
+On macOS, Elwood MUST start the PTY in the user's configured shell in a way that
+matches the effective environment of opening Terminal.app and running the agent.
+The implementation should use the user's login shell and interactive/login flags
+appropriate for that shell. For the common zsh case, this is expected to behave
+like an interactive login shell and load the user's normal startup files.
+
+This interactive login form (`-l -i` for zsh) applies to both the **agent PTY**
+and one-shot, non-PTY preflight probes (`--version`, `update`, `--help`). The
+same shell startup files MUST resolve the CLI for every lifecycle operation so
+preflight, update, launch, and resume cannot operate on different installations.
+
+Elwood MUST provide diagnostics or tests proving that environment variables from
+the user's shell startup are visible to the launched agent process.
+
+### 4.3 Claude settings behavior
+
+Elwood MUST NOT mutate `.claude/settings.local.json` by default.
+
+For each Claude session, Elwood generates a session-scoped settings file or JSON
+object containing only Elwood's necessary overrides:
+
+- hook bridge handlers for every Claude hook event;
+- any session-specific environment/settings required for routing.
+
+Elwood launches Claude with Claude Code's `--settings <file-or-json>` mechanism
+and relies on Claude Code's native settings merge precedence. Omitted keys in
+Elwood's generated settings must leave user, project, and local settings intact.
+Requested permission mode and allowed/disallowed tool policy may be supplied as
+Claude CLI flags instead of generated settings when Claude exposes a stable flag
+for that policy.
+
+Decision note: Claude currently advertises both camelCase and kebab-case aliases
+for tool-policy flags, but Claude's bundled docs and older CLI references name
+`--allowedTools` and `--disallowedTools`. Elwood uses those documented camelCase
+flags to maximize compatibility. The tool rule list is encoded as one
+comma-separated flag value because current `claude --help` explicitly accepts
+comma-separated or space-separated tool lists.
+
+Beyond the allow/deny rule pair, `tools` exposes Claude's `--tools` flag — a
+true allowlist over the built-in tool set where only the named tools exist
+and newly added CLI tools default to absent. An empty `tools` array encodes
+`--tools ""`, which Claude documents as disabling all tools. `allowedTools`/
+`disallowedTools` govern permission rules; `tools` governs existence.
+
+### 4.4 Codex configuration behavior
+
+Elwood MUST NOT mutate `.codex/config.toml`, `.codex/hooks.json`,
+`~/.codex/config.toml`, or `~/.codex/hooks.json` by default.
+
+For each Codex session, Elwood generates only Elwood-owned runtime files under
+the Elwood session metadata directory, then launches Codex with session-scoped
+`--config` overrides that install hook bridge handlers for every supported Codex
+hook event. Elwood reserves `features.hooks=true` and `hookTrust="trust-all"`
+as session-scoped Codex overrides because Codex hooks must be enabled and trusted
+for Elwood to function. User, project, managed, and system Codex config must
+still merge through Codex's normal precedence rules.
+
+Decision note: `features.hooks=true` is treated as Elwood-owned configuration,
+not caller configuration. Without it, some Codex versions can parse hook config
+without running hooks, which would make Elwood observe less than the parent app
+expects. Elwood-owned hook command overrides may be emitted before caller
+`configOverrides`, but reserved enablement/trust overrides MUST be emitted after
+caller overrides so callers cannot accidentally disable the bridge.
+
+Codex hook trust is a Codex security feature, but Elwood is not useful without
+trusted hooks. Elwood MUST always allow Codex hooks to run. It should use
+`hookTrust="trust-all"` in its session-scoped Codex config and should also use
+Codex's invocation-scoped hook-trust bypass flag when the installed CLI
+advertises it. If Codex still shows an interactive `Hooks need review` prompt,
+Elwood MUST select the numbered option whose label is `Trust all and continue`
+through PTY input; it must not assume that option always has the same number.
+Prompt detection MUST operate on raw PTY output, including ANSI-styled and
+cursor-addressed full-screen output where menu text may arrive as `2.Skip`
+rather than as line-oriented `2. Skip` text.
+
+### 4.5 Environment fidelity
+
+An Elwood session MUST behave like the same agent launched from the user's own
+terminal in the same working directory, plus Elwood's additive instrumentation.
+Concretely:
+
+- Sessions launch through the user's login+interactive shell in the caller's
+  `cwd`, inheriting the parent process environment plus Elwood's own session
+  variables (such as `ELWOOD_SESSION_ID`).
+- Elwood MUST NOT modify, move, or shadow user-owned configuration: user and
+  project Claude settings, `CLAUDE.md`/`AGENTS.md`, skills, MCP configuration,
+  and Codex `config.toml` all load exactly as they would without Elwood.
+- Elwood's hook wiring MUST be additive. User-configured hooks for the same
+  events continue to run alongside Elwood's bridge hooks. For Claude this holds
+  because `--settings` is a merged settings source; for Codex this holds
+  because CLI `-c hooks.*` overrides combine with `config.toml` hook groups
+  (verified against codex-cli 0.142).
+- Known deviations MUST be documented rather than silent. Current deviations:
+  Codex hook trust is bypassed inside Elwood sessions because Elwood's reserved
+  `hookTrust="trust-all"` and trust-bypass flag apply to the whole session, so
+  a user hook that Codex would normally prompt about runs without a prompt; and
+  caller-provided `settingsOverrides` (§5.1) may intentionally shadow
+  project-level Claude settings keys because the generated `--settings` file is
+  a high-precedence source.

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

@@ -0,0 +1,108 @@
+## 5.1 Starting Claude
+
+```ts
+type StartClaudeOptions = {
+  readonly cwd: string;
+  readonly stateDir?: string;
+  readonly name?: string;
+  readonly initialSize?: TerminalSize;
+  readonly hooks?: ClaudeHookHandlers;
+  readonly persona?: string;
+  readonly model?: string;
+  readonly reasoningEffort?: ClaudeReasoningEffort;
+  readonly permissionMode?: ClaudePermissionMode;
+  readonly allowedTools?: readonly ClaudeToolRule[];
+  readonly disallowedTools?: readonly ClaudeToolRule[];
+  readonly tools?: readonly ClaudeToolRule[];
+  readonly settingsOverrides?: ClaudeSettingsOverrides;
+  readonly highTrust?: boolean;
+  readonly autoupdate?: boolean;
+  readonly autotrust?: boolean;
+  readonly hookTimeoutMs?: number;
+  readonly strictVersionCheck?: boolean;
+};
+
+type ClaudeReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
+
+declare function startClaude(options: StartClaudeOptions): Promise<ClaudeSessionApi>;
+```
+
+`cwd` is the working directory where Claude should start. `stateDir` overrides
+the default Elwood state directory. `name` is a launch-time convenience forwarded
+to Claude's documented `--name` flag; it is not persisted in Elwood state (§8.2).
+`hooks` registers
+launch-time handlers before Claude starts. When `autoupdate` is true, Elwood
+runs `claude update` from the user's login shell before spawning Claude and
+rechecks the version after the update. The update command runs at most once
+per parent process per adapter, so a parent spawning a roster of sessions at
+launch does not run N concurrent same-binary updates (C-LIFE-09); later
+sessions in the same process reuse the already-updated binary. Separate Elwood
+parent processes for the same macOS user also coordinate through an atomic,
+per-adapter lease in a stable account cache independent of each process's temporary
+directory: one process runs the global updater while contenders wait asynchronously
+for it to finish, then skip their duplicate attempt and re-read the installed
+version. The lease records its owner and generation; an old owner cannot remove a
+successor's lease, a live owner is never evicted solely because of elapsed time,
+and a crashed owner's stale lease is recoverable after a fixed bound longer than
+the update probe's own timeout. `strictVersionCheck` makes unparseable Claude
+versions fatal instead of warning-and-continuing. `permissionMode`
+accepts Claude's documented launch values: `default`, `acceptEdits`, `plan`,
+`auto`, `dontAsk`, and `bypassPermissions`.
+
+`highTrust` is the agent-neutral "never ask for permissions" switch. On Claude,
+`highTrust: true` expands to `permissionMode: "bypassPermissions"` before the
+posture is persisted or the process is spawned, so the record, `config
+effective`, and the launched CLI all agree. It is an expansion, not a second
+axis: supplying an explicit `permissionMode` together with `highTrust: true` is a
+configuration error rejected before spawn with the typed
+`claude_high_trust_conflict` error. When Claude starts in bypass-permissions
+mode it may render a one-time acceptance dialog (header `WARNING: Claude Code
+running in Bypass Permissions mode`, affirmative `Yes, I accept`, decline `No,
+exit`); that dialog is an allowlisted trust prompt answered under `autotrust`
+with `startup_prompt` label `bypass_permissions`, and with `autotrust` off it is
+a blocking prompt like any other trust gate. Whether the installed CLI shows the
+dialog at all is version- and machine-dependent (the CLI may persist the
+acceptance), so Elwood answers it when present and otherwise proceeds. When the
+CLI itself refuses bypass mode (for example when running as root), Elwood does
+not special-case it: the refusal surfaces as the ordinary start failure carrying
+the CLI's own message.
+
+`model` is forwarded to Claude's documented `--model` launch flag so the
+session starts on the requested model. Elwood does not validate the value;
+Claude owns model-name resolution and its own failure behavior.
+
+`reasoningEffort`, when set, is forwarded to Claude's documented `--effort`
+launch flag so the session starts at the requested reasoning effort. Unlike
+`model`, the value is a fixed per-CLI enum, so Elwood validates it against the
+`ClaudeReasoningEffort` set BEFORE spawning and rejects an out-of-enum value with
+the typed `claude_invalid_reasoning_effort` error (listing the valid values), so a
+typo fails fast at start rather than deferring to the CLI. The effort applies to
+the current session only and is NOT persisted by Elwood; a resumed session must
+re-supply it (§5.2), consistent with `model`. Reasoning effort and model are
+independent axes on Claude (the flag is separate from `--model`).
+
+`autotrust` is an opt-in convenience for embedded/headless parent apps.
+When true, Elwood detects Claude's first-party workspace trust prompt in the
+rendered terminal and chooses the trust/continue option through PTY input. The
+default is false because trusting a workspace is a security-sensitive decision.
+When Elwood answers the prompt, the session emits adapter-neutral
+`startup_prompt` activity with label `workspace_trust`.
+
+Separately from `autotrust`, Elwood MUST dismiss Claude's non-security
+first-party onboarding prompts that would otherwise block readiness in an
+embedded session, always choosing the option that declines or defers the
+offered capability. The currently known prompt of this kind is the browser
+tools onboarding prompt, declined through PTY input (Escape) with
+`startup_prompt` activity emitted under the label `browser_tools`. This
+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
+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
+caller-queued messages. Persona delivery is observable through the normal hook
+and activity events, exactly like a caller-submitted message. The persona is
+not persisted in Elwood state (§8.3 applies) and is not re-sent on resume. If
+the session terminates before ever becoming ready, the undelivered persona is
+discarded silently.