@with-logic/elwood 0.1.1 → 0.1.2

package/prd/05-api/5.4-events.md

@@ -0,0 +1,145 @@
+## 5.4 Events
+
+The primary event API is typed event-emitter style.
+
+Required event families:
+
+- `terminal:data`: raw PTY output bytes/string for live rendering.
+- `terminal:exit`: PTY process exit.
+
+`resize` should update both terminal models while the process is alive. If the
+native PTY reports that its file descriptor is already closed during a resize
+race with process exit, Elwood should treat that resize as a no-op and rely on
+the normal exit event to update lifecycle status. Other native PTY resize errors
+must still surface.
+- `status`: session lifecycle/status changes.
+- `warning`: typed non-fatal adapter or environment issues observed during the
+  session, such as Codex MCP startup warnings.
+- `loop`: adapter-neutral recurring-loop lifecycle and failure events (§5.9).
+- `activity`: adapter-neutral live events for common observability, including
+  lifecycle changes, user messages, assistant messages, reasoning, tool calls,
+  tool results, web search, notifications, warnings, startup prompt automation,
+  attention (blocked-on-a-human-decision) transitions, generic hooks, hook
+  results, and hook errors.
+- `hook`: every Claude hook event after parsing and validation.
+- `codex:transcript`: live, best-effort Codex transcript observations for
+  activity that Codex does not expose as hook events.
+- `hookError`: hook bridge or parent-handler errors that failed open.
+
+`activity` is the preferred event for parent apps that want a simple unified
+"send message, observe what happened, send another message" loop across
+adapters. Every activity event includes:
+
+- `elwoodSessionId`
+- `agent`: `claude` or `codex`
+- `source`: `hook`, `transcript`, `terminal`, or `lifecycle`
+- `kind`: normalized event kind
+- `label`: short display label
+- optional `text`
+- optional normalized metadata fields:
+  - `hookEventName`
+  - `turnId`
+  - `toolName`
+  - `toolUseId`
+  - `toolInput`: the tool call's input arguments, serialized to a string
+    (already-string inputs pass through; structured inputs are JSON-stringified),
+    present on `tool_call` activity when the source exposes it.
+  - `toolOutput`: the tool result's output, serialized to a string with the same
+    rules, present on `tool_result` activity when the source exposes it.
+  - `status`
+  - `exitCode`
+  - `failedOpen`
+  - `transcriptPath`
+- optional `raw` in-memory source payload
+
+`raw` is live-only but intentionally not redacted. Parent applications that
+subscribe to activity events should treat `raw` as potentially containing user
+prompts, tool inputs, tool outputs, and hook payload details.
+
+Parent apps should not need `raw` for common timeline rendering. Elwood MUST
+populate the normalized metadata fields whenever those values are present in the
+source hook, transcript item, or lifecycle event. Adapter-specific `raw` remains
+available for deep debugging and unsupported future payloads.
+
+When Elwood detects and answers an interactive startup prompt on behalf of the
+parent app, it MUST emit an activity event with `source: "terminal"`,
+`kind: "startup_prompt"`, a stable label, and text describing the key sent. This
+`startup_prompt` activity is emitted only after the prompt's PTY write actually
+fulfills; a rejected write emits no such activity and instead surfaces the
+`startup_prompt_write_failed` warning (§5.7) while leaving the prompt retryable.
+The stable startup-prompt label set is EXACTLY the following, and no other value
+may be emitted with `kind: "startup_prompt"`:
+
+| label             | agent          | defined by                  |
+| ----------------- | -------------- | --------------------------- |
+| `workspace_trust` | claude, codex  | C-CLAUDE-10, C-CODEX-11/15   |
+| `skill_trust`     | claude         | C-CLAUDE-14                 |
+| `plugin_trust`    | claude         | C-CLAUDE-14                 |
+| `mcp_trust`       | claude         | C-CLAUDE-14                 |
+| `bypass_permissions` | claude      | C-CLAUDE-21                 |
+| `browser_tools`   | claude         | C-CLAUDE-11                 |
+| `hook_trust`      | codex          | C-CODEX-06/15               |
+| `update`          | codex          | C-CODEX-12                  |
+
+The trust-prompt labels (`workspace_trust`, `skill_trust`, `plugin_trust`,
+`mcp_trust`, `bypass_permissions`, `hook_trust`) are exactly the ids in the
+trust-prompt allowlist; a second implementation MUST treat this table as the
+complete output union.
+
+Under a caller's full-trust launch (`autotrust`), an agent MUST NEVER be left
+waiting on a trust gate: when an allowlisted trust prompt is visible in the
+current rendered frame, Elwood selects its affirmative option and sends it —
+always say yes. The trust prompt family is folder/directory trust, the CLI's
+first-run prompts for loading a skill, a plugin, or an MCP server, and Claude's
+one-time bypass-permissions acceptance dialog (§5.1). This is an
+EXPLICIT ALLOWLIST: each entry names one prompt by its on-screen HEADER wording
+and an affirmative-option matcher. Recognition — and ONLY recognition — is the
+guard: (1) Elwood auto-answers only ALLOWLISTED prompts, so an off-allowlist
+first-run confirmation is left to the human and a future CLI security gate is
+never blanket-bypassed; and (2) a prompt is recognized ONLY by its HEADER wording
+outside the option region — a trust phrase appearing only inside a numbered or
+cursor-selectable option label (e.g. "1. Yes, trust this plugin and grant admin
+access") does NOT identify a prompt, so a hostile option cannot spoof one.
+Recognition matches the header against the frame's joined non-option lines, so a
+header wrapped across physical rows still matches; the affirmative is the first
+option whose label matches the prompt's affirmative pattern. Numbered layouts
+are answered by sending their option number; cursor layouts are answered by
+navigating from the rendered selection to the affirmative and pressing Enter.
+Elwood matches only against the CURRENT frame, never accumulated history. If an
+allowlisted prompt is recognized but its affirmative option has not rendered
+yet, Elwood emits an `attention` activity (labelled with the prompt id) at most
+once, and keeps watching so a later frame carrying the option is still answered —
+it never permanently wedges. These trust prompts are answered only when
+`autotrust` is set; with it off, an unanswered trust prompt is a blocking prompt
+that holds session state for the human. A prompt that Elwood
+auto-answers (including an always-answered one) MUST NOT be classified as a
+blocking prompt.
+
+Two prompts are exceptions to the `autotrust` gate. Codex hook trust
+(`hook_trust`) is Elwood's OWN integration — the session cannot function without
+its hook bridge trusted — so it is always answered, and `update` is not a trust
+decision at all; both are handled independently of `autotrust`.
+Every hook dispatch must also emit an adapter-neutral hook-result activity after
+parent handlers run. The result activity must include the hook event name,
+whether the dispatch failed open, and the raw in-memory result payload when
+present. Missing parent handlers are normal no-decision responses and must not
+be labeled as failed-open errors. Handler timeouts, invalid responses, thrown
+handlers, and bridge errors must emit both `hookError` and an adapter-neutral `activity` with
+`kind: "hook_error"`.
+
+`HookErrorEvent.category` values are `timeout`, `handler_error`,
+`invalid_input`, `invalid_response`, and `bridge_error`.
+
+Hook-specific events remain the source of truth for event-specific decisions,
+typed control responses, and adapter-specific payloads.
+
+Elwood may provide convenience registration by hook name:
+
+```ts
+session.on("hook:PreToolUse", async (event) => {
+  return { permissionDecision: "deny", permissionDecisionReason: "No writes" };
+});
+```
+
+The exact naming may vary, but the type system MUST narrow event payload and
+valid response shape by hook event name.

package/prd/05-api/5.5-starting-codex.md

@@ -0,0 +1,106 @@
+## 5.5 Starting Codex
+
+```ts
+type StartCodexOptions = {
+  readonly cwd: string;
+  readonly stateDir?: string;
+  readonly initialSize?: TerminalSize;
+  readonly hooks?: CodexHookHandlers;
+  readonly persona?: string;
+  readonly model?: string;
+  readonly reasoningEffort?: CodexReasoningEffort;
+  readonly profile?: string;
+  readonly sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+  readonly approvalPolicy?: "untrusted" | "on-request" | "never";
+  readonly configOverrides?: readonly string[];
+  readonly highTrust?: boolean;
+  readonly autoupdate?: boolean;
+  readonly autotrust?: boolean;
+  readonly hookTimeoutMs?: number;
+  readonly strictVersionCheck?: boolean;
+};
+
+type CodexReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
+
+declare function startCodex(options: StartCodexOptions): Promise<CodexSessionApi>;
+```
+
+Elwood sets the PTY working directory and also passes Codex `--cd <cwd>` so
+Codex's own session state and the shell's current directory agree.
+
+`reasoningEffort`, when set, is forwarded as the Codex `-c
+model_reasoning_effort=<value>` config override so the session starts at the
+requested reasoning effort. Codex validates this value SERVER-SIDE — an
+out-of-enum value launches successfully and then fails at the first turn with a
+provider error — so Elwood validates it against the `CodexReasoningEffort` set
+BEFORE spawning and rejects an out-of-enum value with the typed
+`codex_invalid_reasoning_effort` error (listing the valid values), turning a
+deferred mid-session failure into a fast, clear start-time rejection. Reasoning
+effort and model are independent axes programmatically (effort is its own `-c`
+key); Elwood emits the reserved `model_reasoning_effort` override AFTER caller
+`configOverrides`, so `reasoningEffort` wins over a hand-rolled duplicate. The
+effort applies to the launched session only and is NOT persisted by Elwood (the
+config-restore teardown already strips a root `model_reasoning_effort`, §5.3); a
+resumed session must re-supply it (§5.6), consistent with `model`.
+
+`configOverrides` contains raw Codex `key=value` overrides passed through
+`--config` after Elwood's generated hook command config so callers can
+intentionally override non-reserved Codex behavior. Callers own TOML correctness
+for these raw overrides; Elwood shell-quotes each override but does not parse or
+rewrite its TOML value. Elwood's generated `features.hooks=true` and
+`hookTrust="trust-all"` overrides are reserved and applied after caller config
+overrides because enabled, trusted hooks are required for Elwood to function.
+When `autoupdate` is true, Elwood runs `codex update` from the user's login
+shell before spawning Codex and rechecks the version after the update. If Codex
+later shows an interactive update prompt inside the TUI, Elwood skips that
+prompt through PTY input, including Codex's cursor-addressed update screen.
+Elwood never selects "Update now" inside the live TUI (an in-TUI update restarts
+Codex out from under the session); the real update is the preflight `codex update`
+above, and the in-TUI prompt is always skipped. The skip is edge-triggered, so if
+the same update screen reappears after a restart — the update did not take — Elwood
+skips it again rather than leaving the session stuck looping on it. While an
+update screen remains rendered, Elwood treats it as input-blocking even after the
+skip key is written: readiness and queued persona/caller input stay suspended until
+the screen clears. A captured first-party banner that renders before its options
+therefore fails safe, and a following safe-option-only frame remains latched as the
+same prompt; generic agent prose containing "update available" does not activate
+the blocker. Because current Codex versions can paint this menu before their input
+loop reliably accepts the first key, Elwood retries the safe numbered choice for a
+bounded interval. Before every write it re-reads the current frame and requires the
+still-active first-party prompt generation plus that frame's safe numbered option;
+this includes an option-only continuation belonging to a previously captured banner.
+It stops without another write once that generation clears or changes, and fails the
+startup operation if the update prompt remains but its safe option disappears or the
+retry interval is exhausted. A blocked update screen therefore becomes a bounded run
+failure even when the caller supplied no whole-run timeout; delayed input cannot
+reach the restored composer or a replacement dialog. This prevents a queued Enter
+from selecting Codex's default "Update now" action (C-CODEX-12).
+`strictVersionCheck` makes unparseable Codex versions fatal instead of
+warning-and-continuing.
+
+`highTrust` is the same agent-neutral "never ask for permissions" switch as on
+Claude (§5.1). On Codex, `highTrust: true` expands to `sandbox:
+"danger-full-access"` with `approvalPolicy: "never"` before the posture is
+persisted or the process is spawned. Supplying an explicit `sandbox` or
+`approvalPolicy` together with `highTrust: true` is a configuration error
+rejected before spawn with the typed `codex_high_trust_conflict` error.
+
+`autotrust` is an opt-in convenience for embedded/headless parent apps.
+When true, Elwood detects Codex's first-party directory trust prompt in the
+rendered terminal and chooses the trust/continue option through PTY input,
+emitting `startup_prompt` activity with label `workspace_trust`. The default is
+false because trusting a workspace is a security-sensitive decision. Independent
+of `autotrust`, Codex's `Hooks need review` prompt is answered once — hook trust
+is Elwood's own integration, required for the session to function, not
+third-party trust — emitting `startup_prompt` activity with label `hook_trust`.
+
+`persona` behaves exactly as specified for Claude in §5.1: enqueued before
+control returns to the caller, delivered as the first user message on the first
+ready transition, never persisted, and never re-sent on resume.

package/prd/05-api/5.6-resuming-codex.md

@@ -0,0 +1,48 @@
+## 5.6 Resuming Codex
+
+```ts
+type ResumeCodexOptions = {
+  readonly elwoodSessionId: string;
+  readonly cwd?: string;
+  readonly stateDir?: string;
+  readonly hooks?: CodexHookHandlers;
+  readonly initialSize?: TerminalSize;
+  readonly reasoningEffort?: CodexReasoningEffort;
+  readonly sandbox?: CodexSandboxMode;
+  readonly approvalPolicy?: CodexApprovalPolicy;
+  readonly highTrust?: boolean;
+  readonly autoupdate?: boolean;
+  readonly autotrust?: boolean;
+  readonly hookTimeoutMs?: number;
+  readonly strictVersionCheck?: boolean;
+};
+
+declare function resumeCodex(options: ResumeCodexOptions): Promise<CodexSessionApi>;
+```
+
+Resume uses Elwood's durable session metadata to relaunch `codex resume` with
+Codex's internal session id when Elwood has observed it through hooks.
+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 `resumeCodex({ elwoodSessionId })`
+without `cwd` or `stateDir` uses the current process working directory to
+discover the project-local state store.
+
+`resumeCodex` must verify that the persisted Elwood session record belongs to
+the Codex adapter before launching. Passing a Claude session ID to `resumeCodex`
+must fail with a typed error.
+
+If Elwood has not observed and persisted Codex's internal session id,
+`resumeCodex` must fail explicitly. It must not silently launch a fresh Codex
+conversation under the existing Elwood session ID. Future implementations may
+offer an explicit caller opt-in fallback such as `codex resume --last`, but the
+default behavior must be fail-closed.
+
+Like the start path, `resumeCodex` accepts the launch-policy privilege options
+`sandbox` and `approvalPolicy`. The session record persists the launch posture
+at start and resume defaults to it, so a bare `resumeCodex` relaunches with the
+same sandbox and approval policy the session started with; explicit resume
+options override field by field and the effective posture is re-persisted.
+`highTrust: true` on resume expands to the same explicit `danger-full-access` /
+`never` override as on start and conflicts with explicit `sandbox` /
+`approvalPolicy` the same way (`codex_high_trust_conflict`).