@with-logic/elwood 0.1.0 → 0.1.2

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.

package/prd/05-api/5.2-resuming-claude.md

@@ -0,0 +1,86 @@
+## 5.2 Resuming Claude
+
+```ts
+type ResumeClaudeOptions = {
+  readonly elwoodSessionId: string;
+  readonly cwd?: string;
+  readonly stateDir?: string;
+  readonly hooks?: ClaudeHookHandlers;
+  readonly initialSize?: TerminalSize;
+  readonly reasoningEffort?: ClaudeReasoningEffort;
+  readonly permissionMode?: ClaudePermissionMode;
+  readonly allowedTools?: readonly ClaudeToolRule[];
+  readonly disallowedTools?: readonly ClaudeToolRule[];
+  readonly tools?: readonly ClaudeToolRule[];
+  readonly highTrust?: boolean;
+  readonly autoupdate?: boolean;
+  readonly autotrust?: boolean;
+  readonly hookTimeoutMs?: number;
+  readonly strictVersionCheck?: boolean;
+};
+
+declare function resumeClaude(options: ResumeClaudeOptions): Promise<ClaudeSessionApi>;
+```
+
+Resume uses Elwood's minimal persisted session record (§8.2) to relaunch or
+reattach the wrapped Claude session through Claude Code's own resume mechanism. Callers should
+not need Claude's session ID. Because the default state store is project-local,
+callers that resume from a different process working directory must pass the
+original `cwd` or the explicit `stateDir` used at start time. Calling
+`resumeClaude({ elwoodSessionId })` without `cwd` or `stateDir` uses the current
+process working directory to discover the project-local state store.
+
+`resumeClaude` must verify that the persisted Elwood session record belongs to
+the Claude adapter before launching. Passing a Codex session ID to `resumeClaude`
+must fail with a typed error instead of launching a Claude process.
+If Elwood has not observed and persisted Claude Code's internal session id from
+`SessionStart`, `resumeClaude` must fail explicitly with `resume_unavailable`.
+It must not silently launch a fresh Claude conversation under the same Elwood
+session ID.
+
+Decision note: MVP resume re-establishes the Elwood wrapper, hook routing, and the
+agent's internal conversation resume id. It does NOT restore a persisted terminal
+size — that is not persisted (§8.2); the caller passes
+`initialSize` on resume (it otherwise falls back to the default). The launch
+posture (privilege and tool policy) is persisted in the session record at
+start, and resume defaults to it: a bare `resumeClaude` relaunches with the
+same `permissionMode`, `allowedTools`, `disallowedTools`, and `tools` the
+session started with, so tool restrictions cannot silently loosen across a
+resume. Explicit resume options override the persisted posture field by
+field, and the effective posture is re-persisted. Other adapter launch policy
+such as model, reasoning effort, and caller config overrides remains
+caller-supplied-per-call and is intentionally not persisted yet — a resumed
+session that wants a non-default reasoning effort must re-supply `reasoningEffort`,
+exactly as it must re-supply `model`. `highTrust: true` on resume expands to the
+same explicit `permissionMode: "bypassPermissions"` override as on start (and
+conflicts with an explicit `permissionMode` the same way); a bare resume keeps
+the persisted posture, including one that a high-trust start persisted.
+
+Because every persisting parent writes the same try-resume-else-start dance,
+Elwood provides it directly:
+
+```ts
+type StartOrResumeClaudeOptions = StartClaudeOptions & {
+  readonly elwoodSessionId?: string;
+};
+
+declare function startOrResumeClaude(
+  options: StartOrResumeClaudeOptions,
+): Promise<{ readonly session: ClaudeSessionApi; readonly resumed: boolean }>;
+```
+
+When `elwoodSessionId` is set, `startOrResumeClaude` attempts a resume,
+forwarding every start option the resume entry point accepts: `cwd`,
+`stateDir`, `hooks`, `initialSize`, `reasoningEffort`, `permissionMode`,
+`allowedTools`, `disallowedTools`, `tools`, `autoupdate`, `autotrust`,
+`highTrust`, `hookTimeoutMs`, and `strictVersionCheck` (for Codex: the same shared options
+plus `sandbox` and `approvalPolicy`). Non-persisted per-call policy such as
+`reasoningEffort` therefore reaches a resumed session exactly as it reaches a
+fresh one. It falls back to a fresh `startClaude` only for the
+error names that mean "no resumable session": `state_not_found`,
+`resume_unavailable`, and `adapter_mismatch`. Every other error — including
+`state_corrupt` — is a real failure and is rethrown, so data problems are
+never silently papered over by a fresh session. The result reports which path
+ran so callers can re-persist a new `elwoodSessionId` after a fallback.
+`startOrResumeCodex` behaves identically for Codex. `persona` follows its
+normal rules: delivered on a fresh start, never re-sent on resume.