@with-logic/elwood 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable **consumer-facing** changes to Elwood are recorded here: new or
+changed public API, session/lifecycle behavior, activity/event shapes, and bug
+fixes a host application would notice. Internal refactors, test-only changes,
+and doc tweaks are omitted. The format follows
+[Keep a Changelog](https://keepachangelog.com); this project is pre-1.0, so
+everything lands under **Unreleased** until the first tagged release.
+
+Observable behavior is specified in `PRD.md`; the conformance criteria that
+back each entry are listed in PRD.md §14.
+
+## [Unreleased]
+
+First public release.
+
+### Added
+
+- Claude Code and Codex CLI adapters that run the real interactive CLI in a
+  PTY, launched through the user's login shell, and observe it through a
+  headless xterm.js model. macOS only; Claude Code 2.1.144+ and Codex CLI
+  0.124.0+ with a `strictVersionCheck` option to fail closed on unparseable
+  versions.
+- `ClaudeSession` / `CodexSession` classes as the primary API: synchronous
+  construction, lazy start on first use, `send(prompt)` returning the turn's
+  assistant text, `stream(prompt)` yielding typed `text` / `thinking` /
+  `tool_call` / `tool_result` events, and `close()`. Turns end on a
+  deterministic transcript boundary, with no whole-turn timeout unless
+  `timeoutMs` is passed. The eager `startClaude` / `startCodex` factories are
+  deprecated but remain available.
+- The full control surface on every session: `sendMessage`, `sendPrompt`,
+  `sendGuidance`, `sendKeys` (string or raw `Uint8Array`), `resize`,
+  `interrupt`, `compact`, `listModels`, `setModel`, `waitForStatus`,
+  `waitForActivity`, `stop`, `kill`, and `teardown`, plus the exported
+  `ElwoodAgentSession` type for code generic over either adapter.
+- Typed hook handlers for Claude and Codex hook events, delivered over a
+  local, token-protected IPC bridge with runtime validation. Handlers fail
+  open; failures surface as `hookError`.
+- A unified `activity` event stream (messages, reasoning, tool calls and
+  results, web searches, hooks, warnings, lifecycle) with normalized
+  `toolName` / `toolInput` / `toolOutput` / `turnId` fields, alongside `hook`,
+  `hook:<Name>`, `warning`, `loop`, `status`, `terminal:data`,
+  `terminal:exit`, and Codex-only `codex:transcript`.
+- Raw `terminal:data` output for host-rendered terminals, with a 128 KB
+  replay buffer for late subscribers and exactly-once `terminal:exit`.
+- Persisted, resumable sessions: a minimal session record under
+  `<cwd>/.elwood` or a caller `stateDir`, `resumeClaude` / `resumeCodex`, and
+  `startOrResumeClaude` / `startOrResumeCodex`, which fall back to a fresh
+  start only on `state_not_found`, `resume_unavailable`, or
+  `adapter_mismatch`. Resume restores the persisted launch posture and
+  reaches readiness in about one second.
+- Recurring loops (`createLoop`, `listLoops`, `cancelLoop`, and the opt-in
+  `parseLoopCommand` helper) with fixed or idle cadence, per-session limits,
+  seven-day expiry, a redacted `loop` event, and a private sidecar that
+  survives stop and resume.
+- Image attachment on `send`, `stream`, and every send method via `images`
+  (`{ path }` or `{ data, format }`), validated and bounded before submission
+  and confirmed by the CLI's `[Image #N]` chip. Codex attachment drives the
+  macOS clipboard under a process-wide lock.
+- Model control: `listModels` / `setModel` through the adapter's `/model`
+  picker without touching the user's saved defaults, `model` and
+  `reasoningEffort` start options on both adapters, and the standalone
+  `listClaudeModels` / `listCodexModels` probes.
+- Claude login recovery: `claude_not_authenticated` at startup, a live
+  `login_expired` warning mid-session, and `ClaudeSession.login()` to drive
+  `/login` with a human-supplied authorization code.
+- A `persona` start option delivered as the guaranteed first user message,
+  and an optional best-effort `autoupdate` preflight that never fails a start
+  when the installed CLI already meets the minimum version.
+- Automatic answers for a narrow allowlist of startup prompts: workspace trust
+  (opt-in `autotrust`), Codex hook-trust and update dialogs, and Claude's
+  browser-tools onboarding. Any other dialog leaves the session `blocked`.
+- The `elwood` executable: one headless turn with text, `--output json`, or
+  `--output jsonl` protocols, `--stream`, `--verbose`, `--debug`, stdin and
+  ordered `--image` input, `--timeout`, `--persona`, model and posture flags,
+  `--keep` / `--resume` / `--ephemeral` continuation, signal-safe cleanup, and
+  stable exit statuses (`0`, `1`, `2`, `124`, `130`).
+- `--head` mode that mirrors the live agent TUI in the current terminal on
+  stderr while keeping the final result on stdout, view-only, with terminal
+  state restored on every outcome.
+- `elwood config` with one strict global JSON file, typed keys, `ELWOOD_*`
+  environment overrides, flag > environment > config > built-in precedence,
+  `--no-defaults`, and `config effective` to explain resolved values and their
+  sources without starting an agent.
+- CLI agent auto-detection: with no `--agent`, `ELWOOD_AGENT`, or config
+  `agent`, a new run tries `claude` then `codex` in the login shell and fails
+  with `no_agent_found` (status 2) when neither resolves. Error records
+  emitted before an agent was selected report `agent: null`.
+
+### Changed
+
+- Published as `@with-logic/elwood` under the MIT license.
+- Warnings are live-only events. Nothing is persisted, replayed, or counted;
+  there is no `session.warnings` property.
+- The persisted session record holds only schema version, `elwoodSessionId`,
+  adapter, `cwd`, and per-adapter resume state. Terminal size is not
+  persisted; pass `initialSize` on resume.
+- Codex `tool_call` activity reports the bare exec command as `toolInput`
+  rather than the CLI's JavaScript harness wrapper.
+- `ClaudeEventMap`, `ClaudeEventName`, and `ClaudeEventHandler` are the
+  primary names for the Claude session event map; `ElwoodEventMap`,
+  `ElwoodEventName`, and `ElwoodEventHandler` remain as deprecated aliases.
+- An object-form Codex `PreToolUse` handler's `unknown` entry now receives only
+  `mcp__*` / `unknown:*` tools; a `Bash` / `apply_patch` event with no per-tool
+  handler yields no decision.
+- The local dev apps are no longer compiled into `dist/`, and their `ws` and
+  browser xterm dependencies moved to `devDependencies`, so consumers install
+  only what the library uses.
+
+### Fixed
+
+- Trust, update, and model-switch dialogs on current Claude and Codex releases
+  are recognized and answered; unrecognized dialogs block instead of guessing.
+- Hook payloads are measured identically on both sides of the bridge, and
+  multibyte characters split across socket chunks are decoded correctly.
+- Cleanup is retryable: a failed `stop` / `kill` / `teardown` never latches,
+  and post-exit `stop` / `kill` reject with the typed `termination_failed`
+  rather than a bare `Error`.
+- Headed CLI runs restore the invoking terminal's input and keyboard modes.
+- `startOrResumeClaude` / `startOrResumeCodex` forward `reasoningEffort` (and
+  every other resume option) on the resume path; a resumed session no longer
+  silently loses the requested effort.
+- A hook event other than `Stop` arriving after `Stop` (for example
+  `Notification` or `FileChanged`) no longer clears the turn-completeness
+  oracle, so late assistant text cannot leak into the next `send` / `stream`
+  turn.
+- Codex sessions no longer emit a false `transcript_records_dropped`
+  (`unread_backlog`) warning on every turn after roughly 256 turns; each `Stop`
+  now reads the transcript with a bounded per-pass scan.
+- `terminal:data` replay never begins with U+FFFD; the 128 KB replay buffer
+  trims on a UTF-8 code-point boundary.
+- `compact()` no longer sends a stray Enter when the `/compact` write resolves
+  after the compact timeout has already rejected.
+- `send` / `stream` bind a turn to the first event that carries a `turnId`
+  (Codex) rather than the first event of any kind.
+- A transcript truncation or rotation discards the old file's buffered partial
+  line instead of gluing it onto the new file's first record.
+- A `PostToolUse` handler returning `{}` is accepted as "no decision" instead of
+  failing open with a spurious `invalid_response` `hookError`.
+- The per-hook `timeout` written into generated Claude settings and Codex
+  overrides is now `hookTimeoutMs` rounded up plus five seconds, so the CLI
+  never kills a hook before Elwood's fail-open reply arrives.
+- `ClaudeSession.login()` no longer accumulates abort listeners and pending
+  promises over a long polling flow.
+- Codex `setModel` restores `config.toml` atomically (temp file plus rename,
+  symlink written through, mode preserved); a crash can no longer leave the
+  user's config empty. When no `config.toml` existed before the switch, the
+  `codex_default_model_persisted` warning now says the picker created the file
+  and Elwood left it in place.
+- `setModel` reports "Could not locate the picker cursor." (still
+  `model_automation_failed`) when rows parse but no cursor is rendered.
+- Session records and the loop sidecar are read without following symlinks and
+  are rejected as `state_corrupt` unless they are private (`0600`) regular
+  files owned by the current user. Socket homes are keyed on the resolved
+  `stateDir`, so relative spellings of one state directory share one home.
+- A loop cancelled before its submission rejects with the typed
+  `loop_submission_failed` error (with `details.loopId`) instead of a bare
+  `Error`.
+- A CLI version or update probe that times out or overflows now kills its whole
+  process group, so a grandchild cannot outlive the bound or pin the event
+  loop.
+- Hook-bridge decisions larger than about 64 KiB are no longer truncated on
+  macOS.
+- The node-pty spawn helper's executable bit is checked before it is set, and a
+  failed `chmod` is tolerated on read-only installs.
+- `elwood` structured error records emitted before an agent was selected report
+  `agent: null` instead of a hard-coded `"codex"`; auto-detection probes both
+  agents concurrently; a login shell that cannot run the probe fails with
+  `no_agent_found` naming the shell and errno; adapter-option conflicts with an
+  auto-detected agent say so and suggest `--agent <other>`; config write
+  failures name the path and errno; text-mode error diagnostics are suppressed
+  only when stderr has closed, not stdout.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Logic, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+# Elwood
+
+Elwood is a TypeScript library and command-line tool for driving interactive
+agentic coding CLIs through real terminal sessions. It starts tools like Claude
+Code and Codex the way they are designed to run, inside an interactive PTY, and
+lets a host application send prompts and key presses, render the live terminal,
+and observe a typed event stream for hooks, tool calls, transcript activity,
+warnings, and lifecycle state. The governing constraint is that the agent should
+not know it is wrapped: the process stays interactive, runs in the user's normal
+shell environment, and is controlled through the hooks and transcripts the CLI
+already provides. The first supported adapters are Claude Code and Codex CLI.
+
+`PRD.md` is the source of truth for observable behavior. If this README, the
+tests, or the implementation disagree with the PRD, the PRD wins.
+
+## Requirements
+
+- macOS. Both adapters reject other platforms at startup with
+  `unsupported_platform`.
+- Node.js 24 or newer.
+- Claude Code `2.1.144` or newer, and/or Codex CLI `0.124.0` or newer,
+  installed and authenticated.
+
+An unparseable CLI version becomes a `version_unparseable` warning and startup
+continues. Pass `strictVersionCheck: true` to fail closed instead.
+
+## Install
+
+```sh
+npm install @with-logic/elwood
+```
+
+The package installs an `elwood` executable for the headless CLI. To work from a
+checkout instead, run `npm install && npm run build && npm link`.
+
+## Quickstart: library
+
+```ts
+import { ClaudeSession } from "@with-logic/elwood";
+
+// Construct synchronously; the session starts lazily on the first turn.
+const session = new ClaudeSession({ cwd: "/path/to/project", autotrust: true });
+
+// `send` returns the assistant's reply as a string; a follow-up keeps context.
+const summary = await session.send("Summarize this repo's test strategy in two sentences.");
+const risks = await session.send("Now list the biggest gaps you'd address first.");
+
+// `stream` yields typed events as they happen.
+for await (const event of session.stream("Run the test suite and report failures.")) {
+  if (event.type === "text") process.stdout.write(event.text);
+  // event.type is also "thinking" | "tool_call" | "tool_result"
+}
+
+await session.close();
+```
+
+`CodexSession` has the same shape. `autotrust: true` lets Elwood answer the
+CLI's workspace trust prompt for `cwd` on your behalf; leave it off when a human
+should make that decision. There is no default turn timeout; pass
+`send(prompt, { timeoutMs })` (a `TurnOptions` field) to bound one turn.
+
+## Quickstart: CLI
+
+```sh
+elwood "Summarize this repository"
+git diff | elwood --agent claude "Review this diff for correctness"
+elwood --output json "Run the tests and summarize failures" | jq -r .response
+elwood --keep --output json "Remember that the release color is teal"
+elwood --resume <sessionId> "What is the release color?"
+```
+
+When nothing selects an agent, Elwood tries `claude` and then `codex` in your
+login shell and uses the first that resolves; if neither does, the run fails
+with `no_agent_found`. See [docs/cli.md](docs/cli.md) for configuration,
+output protocols, head mode, and continuation.
+
+## Core concepts
+
+**Sessions.** A session is one agent process in one PTY, identified by an
+`elwoodSessionId`. `ClaudeSession` / `CodexSession` add `send`, `stream`, and
+`close` on top of the full control surface (`sendMessage`, `sendPrompt`,
+`sendGuidance`, `sendKeys`, `interrupt`, `compact`, `listModels`, `setModel`,
+loops, `waitForStatus`, `stop`, `kill`, `teardown`). The eager `startClaude` /
+`startCodex` factories are deprecated but still available.
+
+**Hooks.** Claude and Codex hook events are delivered to typed handlers you pass
+at start. Elwood runs a local bridge that the CLI's hook scripts call over IPC
+with a per-session token. Handlers can allow, deny, block a stop, or add
+context; they fail open on error.
+
+**Activity stream.** The `activity` event is one adapter-neutral timeline:
+assistant messages, reasoning, tool calls and results, web searches, hooks,
+warnings, and lifecycle. Most host UIs render this and nothing else.
+
+**Terminal stream.** `terminal:data` carries the raw PTY bytes so a host can
+mirror the agent in its own xterm. A late subscriber first receives up to
+128 KB of replayed history as one chunk. `sendKeys(Uint8Array)` forwards a
+user's keystrokes verbatim.
+
+**Status lifecycle.** `status` moves through `starting`, `ready`, `running`,
+and `blocked` (a dialog needs a human) and ends in `stopped`, `exited`,
+`killed`, or `torn_down`. Every real turn is a `running` to `ready` beat.
+
+**State directory.** Elwood keeps a minimal session record under
+`<cwd>/.elwood` by default, or under an explicit `stateDir`. It holds what
+resume needs and nothing else.
+
+## Hooks and policy
+
+Handlers return `undefined` for "no decision". Claude:
+
+```ts
+const claude = new ClaudeSession({
+  cwd,
+  autotrust: true,
+  hooks: {
+    PreToolUse(event) {
+      if (event.tool_name === "Bash" && event.tool_input.command.includes("rm -rf")) {
+        return { permissionDecision: "deny", permissionDecisionReason: "Dangerous shell command." };
+      }
+      return undefined;
+    },
+    Stop(event) {
+      if (event.last_assistant_message?.includes("tests are failing")) {
+        return { decision: "block", reason: "Tests are still failing." };
+      }
+      return undefined;
+    },
+  },
+});
+```
+
+Codex:
+
+```ts
+const codex = new CodexSession({
+  cwd,
+  autotrust: true,
+  approvalPolicy: "never",
+  hooks: {
+    PermissionRequest(event) {
+      if (event.tool_name === "Bash") return { behavior: "allow", message: "Approved by policy." };
+      return { behavior: "deny", message: "Only Bash is allowed in this mode." };
+    },
+    Stop(event) {
+      if (event.last_assistant_message?.includes("TODO")) {
+        return { decision: "block", reason: "Do not stop with TODOs remaining." };
+      }
+      return undefined;
+    },
+  },
+});
+```
+
+Hooks fail open: a handler that throws, times out, returns an invalid result,
+or receives invalid input is reported as a `hookError` event and the agent
+proceeds as if no handler ran. Empty objects are invalid Codex results and fail
+open the same way.
+
+## Events
+
+Subscribe with `session.on(eventName, handler)`; `on` returns an unsubscribe
+function and may be called before the session starts.
+
+```ts
+session.on("activity", (event) => {
+  switch (event.kind) {
+    case "assistant_message":
+    case "reasoning":
+    case "tool_call":
+    case "tool_result":
+    case "web_search":
+      renderTimelineItem(event);
+      break;
+  }
+});
+```
+
+| Event | Purpose |
+|---|---|
+| `activity` | Adapter-neutral live stream for messages, reasoning, tools, warnings, hooks, hook results, and lifecycle. |
+| `hook` | Every parsed and validated adapter hook event. |
+| `hook:<Name>` | Hook-specific handler registration with typed response guidance. |
+| `hookError` | Handler timeout, thrown handler, invalid input, invalid response, or bridge error. Hooks fail open. |
+| `warning` | Non-fatal environment issue, such as an unparseable version or a failed autoupdate. |
+| `loop` | Redacted lifecycle for persisted recurring prompts. |
+| `terminal:data` | Raw PTY output for a visual terminal renderer. |
+| `terminal:exit` | PTY process exit, emitted exactly once. |
+| `status` | Session status change. |
+| `codex:transcript` | Codex-only best-effort transcript observations not covered by hooks. |
+
+`activity` events carry normalized fields for timeline rendering:
+`hookEventName`, `turnId`, `toolName`, `toolUseId`, `toolInput`, `toolOutput`,
+`status`, `exitCode`, `failedOpen`, and `transcriptPath` when Elwood can derive
+them. `raw` is available for deep inspection.
+
+## Resume and teardown
+
+Persist two things: the `elwoodSessionId` and the `stateDir` it lives in. At
+boot, let Elwood decide whether to resume:
+
+```ts
+import { startOrResumeClaude } from "@with-logic/elwood";
+
+const { session, resumed } = await startOrResumeClaude({
+  cwd,
+  stateDir,
+  elwoodSessionId: persisted?.elwoodSessionId,
+  autotrust: true,
+});
+if (!resumed) persist({ elwoodSessionId: session.elwoodSessionId });
+```
+
+`startOrResumeClaude` / `startOrResumeCodex` fall back to a fresh start only on
+`state_not_found`, `resume_unavailable` (the CLI never reported a conversation
+id), or `adapter_mismatch`, and rethrow anything else. Resume restores the
+persisted launch posture (permission mode and tool rules for Claude, sandbox
+and approval policy for Codex); `model`, hooks, and trust options are per call.
+
+`teardown()` removes only Elwood-owned files: the session record, loop sidecar,
+generated settings, bridge script, and socket home. It never touches the agent
+CLI's own auth, transcripts, or settings. `stop()` is graceful; `kill()` is
+immediate; both are safe after the process has already exited.
+
+## Security and privacy
+
+- Elwood answers only a narrow allowlist of prompts: workspace trust (opt-in via
+  `autotrust`), Codex hook-trust and update dialogs, and Claude's browser-tools
+  onboarding. Any other dialog leaves the session `blocked` for a human; the
+  CLI fails such runs as `blocked_prompt`.
+- `autotrust` changes the security posture of the launched agent. Point it only
+  at directories you already trust. The standalone `listClaudeModels` /
+  `listCodexModels` probes always start with `autotrust: true`.
+- The persisted session record holds schema version, `elwoodSessionId`,
+  adapter, `cwd`, and per-adapter resume state. Loop definitions are the only
+  persisted prompt text, in an owner-only `0600` sidecar.
+- Prompts, terminal output, hook payloads, hook responses, transcripts,
+  warnings, bridge tokens, and socket paths are never persisted. Tokens are
+  minted fresh on every start and never trusted from disk.
+- Hook bridge traffic stays on local IPC with a per-session token and an 8 MiB
+  request cap.
+- Elwood does not modify the user's global agent configuration. Claude gets
+  session-scoped `--settings`; Codex gets session-scoped `-c` overrides, and
+  Elwood restores `config.toml` after `setModel`.
+- Codex image attachment goes through the macOS clipboard; the injected image
+  is briefly the clipboard's contents. See [docs/images.md](docs/images.md).
+- `ClaudeSession.login()` drives `/login` with a human-supplied code and
+  validates the URL and code it handles, but should only run at a genuine login
+  prompt. See [docs/login-recovery.md](docs/login-recovery.md).
+- CLI output excludes ANSI frames, hook payloads, screen contents, credentials,
+  and stack traces. Head mode renders agent-controlled escape sequences
+  verbatim, so use it only with agents and workspaces you trust.
+
+## Limitations
+
+- macOS only.
+- Codex transcript observation is best-effort because not every TUI-visible
+  activity is exposed as a hook.
+- Codex subagent transcripts are not observed. A Codex `SubagentStop` still
+  carries `agent_transcript_path`, so a host that wants those records reads the
+  file itself. Claude subagent transcripts are observed.
+- Model picker automation (`listModels` / `setModel`) is pinned to current CLI
+  picker layouts; drift surfaces as `model_automation_failed`.
+- The `/login` recovery flow needs a human to supply the authorization code.
+- Screen matchers (trust prompts, update dialogs, login banners) are
+  version-coupled to the CLIs; `docs/cli-behavior.md` records what has been
+  verified against which versions.
+
+## Documentation
+
+- [docs/cli.md](docs/cli.md): the `elwood` command, configuration, head mode,
+  continuation, and trust.
+- [docs/cli-output.md](docs/cli-output.md): text, JSON, and JSONL output
+  fields, exit codes, and shell recipes.
+- [docs/api.md](docs/api.md): the low-level session API, send semantics,
+  commands, and model listing.
+- [docs/lifecycle.md](docs/lifecycle.md): event delivery guarantees, terminal
+  size, and persisting/resuming.
+- [docs/embedding.md](docs/embedding.md): wiring a session into a host
+  application (Electron and similar).
+- [docs/loops.md](docs/loops.md): recurring prompts and `/loop` parsing.
+- [docs/images.md](docs/images.md): attaching images to a turn.
+- [docs/login-recovery.md](docs/login-recovery.md): detecting and recovering an
+  expired Claude login.
+- [docs/design-notes.md](docs/design-notes.md): design decisions and the
+  state, privacy, and safety model.
+- [docs/cli-behavior.md](docs/cli-behavior.md): empirically verified real-CLI
+  behavior that unit tests cannot catch.
+- [docs/codex/](docs/codex/): short sourced notes on the Codex CLI, config,
+  and hooks.
+- [examples/README.md](examples/README.md): runnable minimal, streaming, and
+  low-level examples.
+- [PRD.md](PRD.md): the behavior specification and conformance criteria.
+- [CHANGELOG.md](CHANGELOG.md): consumer-facing changes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Contributing
+
+Setup, the merge gate, the e2e suite, the dev apps, and the repository map are
+in [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately as
+described in [SECURITY.md](SECURITY.md).

package/dist/bridge/limits.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared hook bridge request byte ceiling.
+ * Implements PRD §6.3 (fail-open-on-overflow request size cap).
+ */
+/**
+ * Maximum raw byte size of a single hook request envelope on the wire, counted
+ * identically by the child bridge script and the parent IPC server. A request
+ * that exceeds this cap fails open immediately without authentication, parsing,
+ * or dispatch. Hook payloads carry arbitrary tool output, so both readers bound
+ * buffering here to keep an unauthenticated sender from forcing unbounded growth.
+ */
+export declare const MAX_HOOK_REQUEST_BYTES: number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/bridge/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/bridge/limits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAkB,CAAC"}

package/dist/bridge/limits.js

@@ -0,0 +1,13 @@
+/**
+ * Shared hook bridge request byte ceiling.
+ * Implements PRD §6.3 (fail-open-on-overflow request size cap).
+ */
+/**
+ * Maximum raw byte size of a single hook request envelope on the wire, counted
+ * identically by the child bridge script and the parent IPC server. A request
+ * that exceeds this cap fails open immediately without authentication, parsing,
+ * or dispatch. Hook payloads carry arbitrary tool output, so both readers bound
+ * buffering here to keep an unauthenticated sender from forcing unbounded growth.
+ */
+export const MAX_HOOK_REQUEST_BYTES = 8 * 1024 * 1024;
+//# sourceMappingURL=limits.js.map

package/dist/bridge/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/bridge/limits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/bridge/parse.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Bridge request parsing and fail-open result helpers.
+ * Implements PRD §6.2 and §6.3.
+ */
+import type { HookErrorEvent } from "../core/types.ts";
+import type { BridgeProcessResult } from "./types.ts";
+export type BridgeMessage = {
+    readonly kind: "ok";
+    readonly token: string;
+    readonly elwoodSessionId?: string;
+    readonly input: string;
+} | {
+    readonly kind: "unauthenticated";
+} | {
+    readonly kind: "malformed";
+};
+export declare function parseBridgeMessage(data: string): BridgeMessage;
+export declare function parseHookInput(input: string): unknown;
+export declare function hookEventNameFrom(input: unknown): HookErrorEvent["hookEventName"];
+export declare function noDecision(): BridgeProcessResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/bridge/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/bridge/parse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAsB9D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC,eAAe,CAAC,CAQjF;AAED,wBAAgB,UAAU,IAAI,mBAAmB,CAEhD"}

package/dist/bridge/parse.js

@@ -0,0 +1,45 @@
+/**
+ * Bridge request parsing and fail-open result helpers.
+ * Implements PRD §6.2 and §6.3.
+ */
+export function parseBridgeMessage(data) {
+    try {
+        const parsed = JSON.parse(data);
+        if (parsed.token === undefined)
+            return { kind: "unauthenticated" };
+        if (typeof parsed.token === "string" && typeof parsed.input === "string") {
+            return {
+                kind: "ok",
+                token: parsed.token,
+                input: parsed.input,
+                ...(typeof parsed.elwoodSessionId === "string"
+                    ? { elwoodSessionId: parsed.elwoodSessionId }
+                    : {}),
+            };
+        }
+        return { kind: "malformed" };
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+}
+export function parseHookInput(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        return null;
+    }
+}
+export function hookEventNameFrom(input) {
+    const record = input && typeof input === "object" && !Array.isArray(input)
+        ? input
+        : {};
+    return typeof record["hook_event_name"] === "string"
+        ? record["hook_event_name"]
+        : "Unknown";
+}
+export function noDecision() {
+    return { exitCode: 0, stdout: "", stderr: "" };
+}
+//# sourceMappingURL=parse.js.map

package/dist/bridge/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/bridge/parse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAI7B,CAAC;QACF,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;QACnE,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACzE,OAAO;gBACL,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,GAAG,CAAC,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ;oBAC5C,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE;oBAC7C,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,MAAM,GACV,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzD,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,OAAO,MAAM,CAAC,iBAAiB,CAAC,KAAK,QAAQ;QAClD,CAAC,CAAE,MAAM,CAAC,iBAAiB,CAAqC;QAChE,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACjD,CAAC"}

package/dist/bridge/script.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates the standalone hook bridge script invoked by Claude hooks.
+ * Implements PRD §6.2 and §6.3 (request byte cap / fail-open on overflow).
+ */
+export declare function bridgeScriptSource(socketPath: string, token: string): string;
+//# sourceMappingURL=script.d.ts.map

package/dist/bridge/script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../../src/bridge/script.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAqE5E"}