@with-logic/elwood 0.1.0 → 0.1.2

package/docs/codex/cli.md

@@ -0,0 +1,57 @@
+# Codex CLI Notes
+
+Sources researched:
+
+- https://developers.openai.com/codex/cli/features
+- https://developers.openai.com/codex/cli/reference
+- local `codex --help` and `codex --version` output
+
+## Interactive Mode
+
+`codex` launches an interactive full-screen terminal UI. That is the mode Elwood
+must wrap. The parent app should control Codex through PTY input and observe it
+through hooks, not through `codex exec`, the SDK, or app-server APIs.
+
+Codex accepts an optional initial prompt, but Elwood starts without one by
+default and sends prompts later through the terminal input path.
+
+Useful CLI capabilities for Elwood:
+
+- `codex` starts a new interactive session.
+- `codex resume <SESSION_ID>` resumes a specific interactive session.
+- `codex resume --last` resumes the most recent interactive session for the
+  current working directory.
+- `--cd <DIR>` tells Codex which project root to use.
+- `--config key=value` applies one-off TOML configuration overrides.
+- `--model <MODEL>`, `--profile <NAME>`, `--sandbox <MODE>`, and
+  `--ask-for-approval <POLICY>` map naturally to adapter launch options.
+- Some Codex versions expose `--dangerously-bypass-hook-trust`, which lets
+  generated Elwood hooks run for one invocation without requiring a persisted
+  trust prompt. Elwood must detect support before passing it because other Codex
+  versions reject unknown flags. Detection is cached for the lifetime of the
+  Elwood process.
+- Codex can also render interactive trust and update prompts before the session
+  is usable. Elwood should select `Trust all and continue` for hook prompts, and
+  skip TUI update prompts because API-level `autoupdate` runs `codex update`
+  before launch when requested. Detection should use Elwood's headless xterm.js
+  screen snapshot, not raw ANSI/PTY byte parsing.
+- Codex may print non-fatal environment warnings before the session is ready,
+  such as MCP servers that are not logged in. Elwood should preserve raw
+  terminal output and also project recognized warnings into typed `warning`
+  events with remediation commands.
+
+## Resume Implications
+
+Codex stores transcripts locally under Codex-owned state. Elwood should persist
+only the Codex session id needed to call `codex resume <SESSION_ID>`. If that id
+has not arrived through hooks yet, Elwood fails with `resume_unavailable`.
+Elwood must not silently fall back to `codex resume --last` because that can
+attach the caller's Elwood session id to the wrong Codex conversation. A future
+API may add an explicit opt-in fallback, but it is not part of the current
+contract.
+
+## Shell Implications
+
+The process should still be launched from the user's normal interactive login
+shell so `codex` resolution, auth environment, and user shell startup behavior
+match opening Terminal.app manually.

package/docs/codex/config.md

@@ -0,0 +1,47 @@
+# Codex Configuration Notes
+
+Sources researched:
+
+- https://developers.openai.com/codex/config-basic
+- https://developers.openai.com/codex/config-advanced
+- https://developers.openai.com/codex/config-reference
+- https://developers.openai.com/codex/hooks
+
+## Layers
+
+Codex reads configuration from CLI flags and `--config` overrides first, then
+profiles, trusted project `.codex/config.toml` files, user config, system config,
+and built-in defaults.
+
+Project-local `.codex` layers are only loaded when Codex trusts the project.
+Because Elwood should be minimally invasive, it should not edit user or project
+Codex config by default.
+
+## Elwood Strategy
+
+Elwood should generate session-scoped hook bridge files under `.elwood/` and
+inject Codex hook configuration through `--config` one-off overrides. This keeps
+existing `.codex/config.toml` and `~/.codex/config.toml` intact while still
+letting Codex merge user defaults and policies normally.
+Elwood applies `hookTrust="trust-all"` after caller overrides so parent apps
+cannot accidentally create an unusable wrapper session.
+
+The generated command should enable or configure:
+
+- hooks for every supported Codex hook event;
+- the bridge command and timeout for each event;
+- `hookTrust="trust-all"`, because Elwood cannot observe or control Codex
+  without trusted hooks;
+- optional launch policy such as model, profile, sandbox, approval policy, and
+  caller-supplied raw config overrides;
+- `--dangerously-bypass-hook-trust` when the installed Codex CLI advertises it,
+  because the generated hooks are ephemeral Elwood-owned bridge commands. Elwood
+  must omit this flag for Codex versions that do not support it.
+
+If Codex still renders a `Hooks need review` TUI prompt, Elwood should select
+`Trust all and continue` through the headless xterm.js input path so the session
+is usable headlessly.
+
+If a managed Codex requirement disallows unmanaged hooks, Codex may ignore or
+reject Elwood hook config. Elwood should surface startup/bridge failures through
+typed errors where possible and hook runtime failures through `hookError`.

package/docs/codex/hooks.md

@@ -0,0 +1,70 @@
+# Codex Hooks Notes
+
+Sources researched:
+
+- https://developers.openai.com/codex/hooks
+- https://github.com/openai/codex/tree/main/docs
+- local `codex features list` output
+
+## Events
+
+The current documented Codex hook events relevant to Elwood are:
+
+- `SessionStart`
+- `SubagentStart`
+- `PreToolUse`
+- `PermissionRequest`
+- `PostToolUse`
+- `PreCompact`
+- `PostCompact`
+- `UserPromptSubmit`
+- `SubagentStop`
+- `Stop`
+
+`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,
+`UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop` include a Codex
+permission mode field. Turn-scoped hooks include `turn_id`.
+
+## Matchers
+
+Hook matchers are regex strings. Tool hooks match `tool_name`; compaction hooks
+match `manual` or `auto`; `SessionStart` matches the source such as startup or
+resume; subagent hooks match agent type. `UserPromptSubmit` and `Stop` currently
+ignore matchers.
+
+For file edits, Codex reports the canonical tool name `apply_patch`, while
+matchers may also use `Edit` or `Write`.
+
+Tool hooks currently cover `Bash`, `apply_patch`, and MCP tool calls. They do
+not cover every TUI-visible activity. In particular, Codex docs state that web
+search and other non-shell/non-MCP tool calls do not trigger `PreToolUse` or
+`PostToolUse` today. Reasoning/status lines shown in the TUI are also not hook
+events.
+
+Elwood therefore treats hooks as the control/approval path and uses live-only
+transcript observation as a secondary rendering path for parent apps that need
+to display reasoning phases, web search calls, assistant messages, and other
+Codex-visible activity.
+
+## Response Model
+
+No output with exit code `0` means no decision and Codex continues.
+
+Codex accepts event-specific JSON output. Important shapes for Elwood:
+
+- `PreToolUse` can deny a supported tool call with `permissionDecision: "deny"`
+  and a reason, add additional context, or allow a rewritten tool input.
+- `PermissionRequest` can decide `allow` or `deny` with `{ hookSpecificOutput:
+  { hookEventName, decision: { behavior, message? } } }`. It must not return
+  updated input or permission edits.
+- `Stop` and `SubagentStop` can return `decision: "block"` with a reason to ask
+  Codex to continue instead of marking the turn done.
+- `PostToolUse`, `UserPromptSubmit`, `SubagentStart`, `PreCompact`, and
+  `PostCompact` are observe-only in Elwood until Codex documents a stable
+  response contract for them.
+
+Elwood should fail open when parent handlers are missing, time out, throw, or
+return an invalid response for the event.
+
+Handlers should return `undefined` for no decision. Empty objects are invalid so
+accidentally empty responses surface as `hookError` and fail open.

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,13 +1,14 @@
 {
   "name": "@with-logic/elwood",
-  "version": "0.1.0",
+  "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.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/with-logic/elwood.git"
   },
-  "homepage": "https://github.com/with-logic/elwood#readme",
+  "homepage": "https://elwood.bot",
   "bugs": {
     "url": "https://github.com/with-logic/elwood/issues"
   },
@@ -25,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"
   ],
@@ -45,11 +51,12 @@
     "node": ">=24"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/postbuild.mjs",
-    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
     "test": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
@@ -58,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"
@@ -69,11 +76,11 @@
     "@biomejs/biome": "2.4.15",
     "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-istanbul": "^4.1.9",
+    "@vitest/coverage-istanbul": "^4.1.11",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.11",
     "ws": "^8.21.0"
   },
   "dependencies": {

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.