@byok-sdk/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ancienttwo
+
+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,11 @@
+# @byok-sdk/client
+
+The local BYOK daemon. It pairs a device, durably journals tasks, connects over
+WebSocket or long poll, dispatches to local Claude Code, Codex, or pi adapters,
+and exposes authenticated local diagnostics/control commands.
+
+The package installs `byok-agent` and `byok-approval-mcp` binaries. Provider
+credentials are not read by the dispatch plane; `@byok-sdk/keys` is separate.
+
+MIT licensed. Node.js 20 or newer; SQLite-backed journaling requires a runtime
+with `node:sqlite` support.

package/dist/adapters/claude/claude-adapter.d.ts

@@ -0,0 +1,155 @@
+import type { TaskOfferPayload } from '@byok-sdk/protocol';
+import { type RuntimeAdapter, type RuntimeCapabilities, type RuntimeDetectResult, type RuntimeEnvironmentRequirements, type Session, type TaskContext } from '../../types';
+import { type ResolvedBin } from './resolve-bin';
+import { type ResolvedApprovalMcpBin } from './resolve-approval-mcp-bin';
+import { type SpawnFn } from './process-client';
+export interface ClaudeAdapterOptions {
+    /** Override bin resolution — tests substitute the fake-claude fixture script. */
+    resolveBin?: () => ResolvedBin;
+    /** Override process spawning — tests substitute a fake spawn. */
+    spawnFn?: SpawnFn;
+    /** M4 Phase 3: override `byok-approval-mcp` bin resolution — tests substitute a fixture script instead of computing a real dist path. Mirrors `resolveBin` above. */
+    resolveApprovalMcpBin?: () => ResolvedApprovalMcpBin;
+}
+/**
+ * Claude Code runtime adapter (`claude -p --input-format stream-json
+ * --output-format stream-json`) — the M2-a counterpart to `../pi/pi-adapter.ts`.
+ * Every behavioral claim in this file's own doc comments and its sibling
+ * modules (`events.ts`, `permission-mapping.ts`, `process-client.ts`) was
+ * empirically reproduced against the real installed `claude` 2.1.212 binary
+ * on a logged-in machine (per this task's own "do NOT trust docs over the
+ * real binary" mandate — `claude --help` was actively wrong/misleading for
+ * `--allowedTools`, see `permission-mapping.ts`) — not inferred from
+ * training-data recall or the Claude API/Agent-SDK docs, which describe a
+ * DIFFERENT product surface (the Messages API, not this CLI's headless
+ * wire format).
+ *
+ * ## The central finding: claude's headless approval model has no
+ * `needs_approval` pause, at all
+ *
+ * This is the first real use of the `needs_approval` /
+ * `Session.resolveApproval` seam any adapter in this codebase has
+ * implemented (pi never emits `needs_approval` — see `PiSession
+ * .resolveApproval`'s own doc comment) — so this finding directly informs
+ * the M2-c protocol-freeze decision on that seam.
+ *
+ * Empirically (see the M2-a report for the full live-capture evidence):
+ * spawning `claude -p` **non-interactively** with a tool call that would
+ * normally prompt a human is resolved **synchronously, before the turn
+ * continues** — there is no pause, no wait, no later resumption point:
+ *
+ * - Under `--permission-mode default` (or no flag at all — headless has no
+ *   TTY to interactively ask), an unapproved tool call is immediately
+ *   AUTO-DENIED with a synthesized `tool_result`
+ *   (`"Claude requested permissions to write to <path>, but you haven't
+ *   granted it yet."`, `is_error:true`) and the run continues normally to
+ *   its own `result` frame — no hang, and nothing this adapter could ever
+ *   resume later even if it wanted to.
+ * - Under a permissive `--permission-mode` (`acceptEdits`/`bypassPermissions`),
+ *   the call is auto-GRANTED, again synchronously, again with nothing to
+ *   pause on.
+ *
+ * There is consequently no claude stream-json frame this adapter could
+ * ever map to the protocol's `needs_approval` `AgentEvent` — the decision
+ * is always already made by the time any frame reaches this adapter at
+ * all. `resolveApproval()` below throws a descriptive error rather than
+ * silently no-op'ing, mirroring `PiSession.resolveApproval`'s own
+ * documented reasoning exactly: a caller that ever receives
+ * `task.approve`/`task.reject` for one of this adapter's tasks implies
+ * something upstream expected approval support this adapter genuinely does
+ * not have.
+ *
+ * `PermissionPolicy.mode: 'confirm'` — the policy mode whose whole point is
+ * "ask a human, then proceed" — was therefore rejected outright at
+ * `start()` through M2/M3 (fail-closed, see `permission-mapping.ts`), never
+ * silently downgraded to auto-accept or auto-deny.
+ *
+ * ## M4 Phase 3 update: a genuine out-of-band pause DOES exist — it is
+ * just invisible to everything written above
+ *
+ * `--permission-prompt-tool` (a DIFFERENT flag from `--permission-mode`,
+ * undocumented in `claude --help`'s own output on the installed 2.1.216
+ * binary but empirically confirmed accepted — an unrecognized flag is
+ * rejected outright with `error: unknown option`, this one is not) makes
+ * claude block a turn on a real MCP round-trip to a server it spawns
+ * itself, waiting for that server to answer allow/deny before continuing —
+ * genuinely pausing, for real wall-clock time (live-verified: an instant
+ * allow/deny, AND a deliberate multi-second delayed answer, both worked
+ * identically; only a permission-prompt-tool call that never answers AT
+ * ALL was found to make claude abandon the turn on its own, after roughly
+ * 1.5s — never actually reachable by this design, since the bundled
+ * `bin/byok-approval-mcp.ts` always eventually answers within its own
+ * configured ceiling).
+ *
+ * Everything above this section remains true and is NOT superseded by
+ * this: claude's own stream-json output still emits nothing while this
+ * pause is in progress — the gap between a `tool_use` frame and its
+ * `tool_result` is indistinguishable from ordinary model latency on the
+ * wire, and there is still no `needs_approval`-shaped frame this adapter's
+ * event mapper could ever produce. The pause is real, but it is invisible
+ * to `ClaudeSession.events` and to `task-runner.ts`'s `pump()` entirely —
+ * it is only ever observable from OUTSIDE this adapter's own process, by
+ * the separate MCP-server child process claude itself spawns. This is why
+ * `confirm` mode's daemon-side wiring (`task-runner.ts`'s `requestApproval`,
+ * `types.ts`'s `ApprovalChannel`) is driven from the control socket, not
+ * from any `AgentEvent` — see those files' own doc comments for the full
+ * design this finding drove. `confirm` is now SUPPORTED (see
+ * `permission-mapping.ts` and `resolveApproval()` below), still fail-closed
+ * whenever no approval channel was actually wired up for this session.
+ *
+ * ## Steering was also found unsupported (a second, related finding)
+ *
+ * Live-probed via a persistent `--input-format stream-json` process:
+ * writing a second `{"type":"user",...}` message to stdin WHILE a turn is
+ * still generating does NOT redirect that in-flight turn — it QUEUES as a
+ * separate, subsequent turn, processed only after the first one reaches
+ * its own `result`. This is genuinely useful for `followUp()` (a new turn
+ * "after [the session] has gone idle" — exactly the queued-after-result
+ * case), but it is not what `Session.steer`'s "inject steering text into a
+ * running turn (mid-stream)" contract promises. `capabilities().steer` is
+ * therefore `false`, and `steer()` throws rather than silently behaving
+ * like a queued follow-up under a name that implies live redirection.
+ */
+export declare class ClaudeAdapter implements RuntimeAdapter {
+    private readonly options;
+    readonly id = "claude";
+    constructor(options?: ClaudeAdapterOptions);
+    detect(): Promise<RuntimeDetectResult>;
+    capabilities(): RuntimeCapabilities;
+    /**
+     * M5: deliberate product-boundary decision, not an oversight — byok's
+     * current ToS posture for claude is login-state-only (`claude auth
+     * login`'s own OAuth session — see `probeAuthPresent` below), so this
+     * adapter declares NO credential env vars at all; env-based API-key
+     * passthrough for claude is a separate, still-pending product decision.
+     * A product that genuinely needs it can opt in locally per-device via
+     * `DaemonConfig.runtimeEnvironment.claude.allow` (`create-daemon.ts`).
+     * `baseNames` is empty too: nothing in this adapter reads a
+     * claude-specific config-discovery variable (e.g. `CLAUDE_CONFIG_DIR`)
+     * today — if a future version of this adapter starts reading one, it
+     * belongs here, not left to rely on the platform baseline alone.
+     */
+    environmentRequirements(): RuntimeEnvironmentRequirements;
+    start(task: TaskOfferPayload, ctx: TaskContext): Promise<Session>;
+    /**
+     * `claude auth status --json` is claude's OWN non-secret login-state
+     * signal (see the credential-isolation rule on `RuntimeAdapter` in
+     * `../../types.ts`) — empirically confirmed live on this logged-in
+     * machine to report `{"loggedIn":true,"authMethod":"claude.ai",
+     * "apiProvider":"firstParty","email":"...","orgId":"...","orgName":"...",
+     * "subscriptionType":"max"}`, with no token/key material anywhere in it.
+     * This spawns the binary and parses ONLY its own reported status — it
+     * never reads `~/.claude` or any credential file itself, matching pi's
+     * `authPresent` computation being limited to environment-variable
+     * *names* (`../pi/pi-adapter.ts`'s `KNOWN_PROVIDER_ENV_VARS`), just via
+     * claude's own equivalent non-secret probe instead (claude's auth is
+     * OAuth-session-based via `claude auth login`, not primarily an env var,
+     * so pi's env-var-presence approach doesn't apply here the same way).
+     * A failed/unparseable probe (binary present but not logged in, a future
+     * claude release changing this output shape, etc.) fails closed to
+     * `false` — this never affects `present`, which is solely about whether
+     * `--version` itself succeeded.
+     */
+    private probeAuthPresent;
+    private resolveBin;
+}

package/dist/adapters/claude/events.d.ts

@@ -0,0 +1,91 @@
+import type { AgentEvent } from '@byok-sdk/protocol';
+/**
+ * A raw parsed line from `claude --output-format stream-json`. Shapes vary
+ * a lot by `type` (and, for `system`, by `subtype`) — see the doc comments
+ * on the individual mapping functions below for the concrete shapes this
+ * was empirically captured against. Kept as a loose bag rather than a full
+ * discriminated union for the same reason pi's `PiRpcMessage` is: this
+ * module only needs a handful of fields off of each frame.
+ */
+export interface ClaudeStreamMessage {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Cross-message correlation state a single {@link ClaudeSession} (in
+ * `../claude-adapter.ts`) owns for its whole lifetime.
+ *
+ * Unlike pi's `tool_execution_start`/`tool_execution_end` frames (which
+ * both carry `toolName` directly, so `../pi/events.ts` can stay a pure,
+ * stateless function), claude's Messages-API-shaped transcript splits a
+ * tool call across two DIFFERENT frame types: the `assistant` frame's
+ * `tool_use` content block carries `{id, name, input}`, but the later
+ * `user` frame's `tool_result` content block carries only `{tool_use_id,
+ * content, is_error}` — no tool name at all. Since this protocol's own
+ * `AgentEvent` schema requires `tool_result.tool: string`, this mapper has
+ * no choice but to remember `tool_use_id -> name` from the `tool_use` block
+ * and look it up when the matching `tool_result` arrives later. This is a
+ * genuine, disclosed structural difference from pi, not an arbitrary
+ * design choice — see the M2-a report for the full reasoning.
+ */
+export interface ToolUseCorrelation {
+    readonly toolNameByUseId: Map<string, string>;
+}
+export declare function createToolUseCorrelation(): ToolUseCorrelation;
+export interface MapClaudeMessageOptions {
+    /** `ctx.workspaceDir` for the task — used only to compute a workspace-relative `name` for a possible `artifact` AgentEvent (see `tryBuildArtifactEvent`'s doc comment). */
+    workspaceDir: string;
+}
+export interface MapClaudeMessageResult {
+    events: AgentEvent[];
+    /**
+     * Set when this exact frame (or, for `assistant`/`user` frames, one
+     * content block inside it) was genuinely unrecognized — a frame/subtype/
+     * block-type this adapter has never been told to expect — as opposed to
+     * routine bookkeeping this mapper deliberately ignores (see
+     * `ROUTINE_CLAUDE_SYSTEM_SUBTYPES` and the `thinking`/`redacted_thinking`
+     * cases below). The caller (`ClaudeSession`'s event iterator) is
+     * responsible for actually recording it (via
+     * `ClaudeProcessClient.recordUnmappedFrame`) — mirrors pi's
+     * `ROUTINE_PI_EVENT_TYPES` check living in `PiSession`'s iterator rather
+     * than inside `mapPiMessageToAgentEvent` itself. At most one label per
+     * call even if a frame has several unmapped things in it — sufficient
+     * for the "did this regress" self-diagnosing purpose this exists for,
+     * without needing a list.
+     */
+    unmappedLabel?: string;
+}
+/**
+ * `system` frame subtypes empirically observed on real stream-json output
+ * from the installed claude 2.1.212 binary that carry no `AgentEvent`
+ * equivalent — routine bookkeeping, deliberately ignored:
+ *
+ * - `init`: session/turn start. Carries `session_id`, `tools`, `cwd`,
+ *   `permissionMode`, etc. `session_id` specifically is NOT read here —
+ *   `ClaudeProcessClient.waitForInit()` (`process-client.ts`) captures it
+ *   directly off the raw line as part of this adapter's own
+ *   `start()`/sessionRef bookkeeping, since it's needed before any
+ *   `AgentEvent` mapping is even relevant.
+ * - `hook_started` / `hook_response`: fired when the user's own Claude Code
+ *   installation has configured lifecycle hooks (e.g. `SessionStart`) —
+ *   machine/config-specific, not part of this protocol's surface at all.
+ * - `thinking_tokens`: periodic token-count-estimate bookkeeping emitted
+ *   while the model is reasoning; no user-visible content.
+ *
+ * A `system` frame whose `subtype` is NOT in this set is treated as
+ * genuinely unmapped (see `mapClaudeMessageToAgentEvents`'s `system` case)
+ * rather than silently folded into "system frames are always routine" —
+ * this is deliberately finer-grained than lumping the whole `system` type
+ * together, so a future/unobserved subtype (e.g. something compaction- or
+ * budget-related) shows up as a one-time warning instead of disappearing
+ * the way the pi adapter's own root-cause hang (a real settle event with no
+ * mapping, silently swallowed) did before that bug was found.
+ */
+export declare const ROUTINE_CLAUDE_SYSTEM_SUBTYPES: ReadonlySet<string>;
+/**
+ * Map one raw claude stream-json line to zero or more normalized
+ * `AgentEvent`s (a single `user` frame can produce two: `tool_result` plus
+ * a derived `artifact`). See the per-`type` mapping functions above for the
+ * concrete, empirically-captured shapes each branch handles.
+ */
+export declare function mapClaudeMessageToAgentEvents(msg: ClaudeStreamMessage, correlation: ToolUseCorrelation, options: MapClaudeMessageOptions): MapClaudeMessageResult;

package/dist/adapters/claude/permission-mapping.d.ts

@@ -0,0 +1,142 @@
+import type { PermissionPolicy } from '@byok-sdk/protocol';
+export interface ClaudePermissionMapping {
+    ok: boolean;
+    /** CLI args to append to `claude -p ...`. Only meaningful when `ok` is true. */
+    args: string[];
+    /** Present when `ok` is false. */
+    reason?: string;
+    /**
+     * M4 Phase 3: set only for `policy.mode === 'confirm'` — tells
+     * `claude-adapter.ts`'s `start()` to additionally spin up the out-of-band
+     * approval channel (write the temp `--mcp-config` file pointing at
+     * `bin/byok-approval-mcp.ts`, then append `--permission-prompt-tool`) on
+     * top of the base `args` returned here. Kept out of `args` itself because
+     * generating that config is a real filesystem side effect (a temp
+     * directory + file write) that has no business happening inside this
+     * otherwise-pure, I/O-free mapping function — see `claude-adapter.ts`'s
+     * `start()` for where it actually happens.
+     */
+    needsApprovalMcp?: boolean;
+}
+/**
+ * Map an effective {@link PermissionPolicy} to `claude -p ...` CLI args,
+ * fail-closed. Empirically grounded against the real installed `claude`
+ * 2.1.212 binary (see the M2-a report) — every claim below was reproduced
+ * live, not inferred from `--help` text or training-data recall (`--help`
+ * text alone was actively misleading in at least one case: `--allowedTools`
+ * reads like a hard allowlist but is NOT one — see the finding below).
+ *
+ * ## Two DIFFERENT, easily-confused tool-control flags (the central finding)
+ *
+ * `claude --help` documents two separate flag families that look
+ * interchangeable but are not:
+ *
+ * - `--allowedTools` / `--disallowedTools`: a PERMISSION pre-grant/deny
+ *   list. Empirically, this only affects whether a tool call needs an
+ *   interactive prompt — it does NOT reliably restrict what the model can
+ *   do once a broadly-permissive `--permission-mode` (acceptEdits,
+ *   bypassPermissions, dontAsk) is also in effect. Confirmed two ways: (a)
+ *   `--permission-mode acceptEdits --allowedTools Read` still let a Write
+ *   call succeed (zero `permission_denials`) — the allowlist was silently
+ *   ignored once the broad grant was in effect; (b) `--permission-mode
+ *   acceptEdits --disallowedTools Write` correctly blocked the *named*
+ *   `Write` tool call (`<tool_use_error>Error: No such tool available:
+ *   Write...`), but the model then simply used `Bash` instead (still
+ *   enabled) to write the same file — `(Bash completed with no output)`,
+ *   file created anyway. A single denied tool name is not a security
+ *   boundary when a general-purpose Bash tool remains available.
+ * - `--tools`: REPLACES the entire active built-in tool set (pi's own
+ *   `--tools` flag works the same way — this is the one place claude and pi
+ *   share an identical convention). Confirmed: `--tools Read` shrinks
+ *   `system/init`'s reported `tools` array to just `['Read', ...MCP
+ *   tools]`; the model then cannot even attempt Write (no tool definition
+ *   to call), regardless of `--permission-mode`. `--tools ""` disables
+ *   every built-in tool outright (confirmed: only the always-on MCP tool
+ *   remained). This is the ONLY mechanism this mapper trusts to actually
+ *   restrict the model's capability surface — never `--allowedTools`/
+ *   `--disallowedTools` for that purpose.
+ *
+ * ## Mode mapping
+ *
+ * - `auto` (no `allowTools`): `--permission-mode acceptEdits`. Empirically
+ *   confirmed to auto-accept BOTH file edits (Write) and Bash execution
+ *   with zero `permission_denials` — broader than the interactive-mode
+ *   folklore that acceptEdits only covers file edits. Verified for a
+ *   benign `echo ... > file` Bash command specifically; not exhaustively
+ *   verified across every possible Bash command shape.
+ * - `auto` with `allowTools` (no `denyTools`): adds `--tools
+ *   <allowTools.join(',')>` (the replacive flag) on top of `acceptEdits`,
+ *   mirroring pi's own `allowTools`-only branch.
+ * - `readonly`: ALWAYS `--permission-mode default` (never acceptEdits/
+ *   bypassPermissions/dontAsk — see the finding above: a permissive mode
+ *   defeats any restriction) plus `--tools
+ *   <intersect(allowTools ?? READONLY_TOOLS, READONLY_TOOLS) - denyTools>`.
+ *   An empty resulting set emits `--tools ""` explicitly — never an absent
+ *   `--tools` flag, which would default to claude's full active set and
+ *   silently widen a readonly request (the exact class of bug pi's own
+ *   `--no-tools` fallback exists to prevent).
+ * - `plan`: `--permission-mode plan`. Empirically confirmed to never
+ *   execute the requested mutating tool call against its real target — the
+ *   model instead writes a plan document and stops. **Caveat, flagged for
+ *   the M2-c freeze decision, not silently hidden**: it writes that plan
+ *   file to `~/.claude/plans/<slug>.md` — the real user's home directory,
+ *   OUTSIDE `ctx.workspaceDir` — unconditionally, regardless of cwd. This
+ *   is a genuine, confirmed workspace-confinement gap specific to plan
+ *   mode's own bookkeeping (the path is fixed/product-owned by Claude Code
+ *   itself, not attacker/model-directed, and no destructive action runs
+ *   against the actual task target) — mapped as supported rather than
+ *   failed-closed because refusing would make an entire policy mode whose
+ *   name and semantics match this protocol's own `plan` mode 1:1
+ *   completely unusable over a relatively minor, fixed-path side effect,
+ *   but this is a judgment call for a human to weigh in on, not a fact.
+ * - `confirm`: SUPPORTED as of M4 Phase 3 — `--permission-mode default`
+ *   (deny-by-default baseline, same as `readonly`'s own choice above) plus
+ *   `allowTools`/`denyTools` mapped exactly like `auto` does (finding F2,
+ *   fixed same session as the confirm-mode support itself first shipped —
+ *   see the function body below): an explicit `--tools <allowTools>` when
+ *   only `allowTools` is set, and a fail-closed refusal whenever `denyTools`
+ *   is non-empty, since confirm — like `auto`/`plan` and unlike
+ *   `readonly` — has no bounded, known-safe base tool list to subtract
+ *   from; the only trustworthy restriction mechanism (`--tools`) is
+ *   replacive, not subtractive. This composes with, rather than replaces,
+ *   `--permission-prompt-tool` pointed at a small bundled MCP server
+ *   (`bin/byok-approval-mcp.ts`) that forwards the pending permission
+ *   decision to this device's own daemon over its control socket and blocks
+ *   until a human (or the daemon's own timeout) resolves it. This directly
+ *   supersedes the M2-a finding that `confirm` was inexpressible: that
+ *   finding was empirically true for `--permission-mode` ALONE (every
+ *   decision resolved synchronously, no pause) — `--permission-prompt-tool`
+ *   is a DIFFERENT flag, undocumented in `claude --help`'s output on the
+ *   installed 2.1.216 binary (confirmed accepted anyway — an unrecognized
+ *   flag is rejected outright with `error: unknown option`, this one is
+ *   not), that genuinely pauses the turn on a real MCP round-trip while
+ *   claude waits for an answer (M4 Phase 3 STEP 0: live-verified allow,
+ *   deny, and multi-second-delayed-then-allow, against the real installed
+ *   binary — see `../../bin/byok-approval-mcp.ts`'s own doc comment for the
+ *   full empirical writeup, including the one caveat found: a permission-
+ *   prompt-tool call that NEVER answers at all triggers claude's own
+ *   internal abandonment of the turn after roughly 1.5s — never actually hit
+ *   by this design, since `byok-approval-mcp` always eventually answers
+ *   within its own configured ceiling, but disclosed rather than silently
+ *   assumed away).
+ * - `denyTools` non-empty under `auto`: FAILS CLOSED. Given the
+ *   `--allowedTools`/`--disallowedTools`-under-a-permissive-mode escape
+ *   hatch above, the only mechanism this mapper trusts (`--tools`) is
+ *   REPLACIVE, not subtractive — pi can resolve `denyTools` to an
+ *   equivalent allowlist because pi's own default active tool set is
+ *   fixed and known from its installed source; claude's active tool
+ *   surface is NOT reliably known ahead of time (empirically, this exact
+ *   dev machine's own installed build exposes a bespoke, non-vanilla tool
+ *   set — see `READONLY_TOOLS`'s doc comment), so there is no reliable
+ *   "default set minus these" this mapper can construct. Refusing is the
+ *   fail-closed choice over guessing a set that might not match reality.
+ *
+ * `network: false` fails closed for the same reason as pi: no verified
+ * network sandbox exists for claude's Bash tool either (`claude --help`
+ * exposes no network/sandbox flag at all) — this was not independently
+ * re-verified against real network traffic the way the tool-restriction
+ * findings above were (doing so would require an actual network probe this
+ * task didn't run), but is the same conservative, precedent-consistent
+ * default pi already applies for an unverifiable constraint.
+ */
+export declare function mapPermissionPolicyToClaudeArgs(policy: PermissionPolicy): ClaudePermissionMapping;

package/dist/adapters/claude/process-client.d.ts

@@ -0,0 +1,103 @@
+import { spawn } from 'node:child_process';
+import type { ClaudeStreamMessage } from './events';
+export type SpawnFn = typeof spawn;
+export interface ClaudeProcessClientOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    spawnFn?: SpawnFn;
+}
+/**
+ * NDJSON process transport for `claude -p --input-format stream-json
+ * --output-format stream-json`.
+ *
+ * Structurally simpler than pi's `PiRpcClient` in one real way, and
+ * different (not simpler) in another:
+ *
+ * - No request/response correlation. pi's RPC mode replies to each command
+ *   with a `{type:"response", id, success, ...}` — claude's stream-json has
+ *   no such acknowledgement at all; writing a `{"type":"user",...}` line
+ *   just starts (or queues) a turn, and the ONLY confirmation is the
+ *   ordinary event stream itself (starting with a `system/init` frame).
+ *   There is therefore no `pending` id->resolver map here.
+ * - `waitForInit()` exists specifically to compensate for that missing
+ *   ack: pi's `start()` fails fast because a bad flag/auth error rejects
+ *   the pending `send()` promise for the first command. Claude's own
+ *   `AsyncQueue.end()` (used for the `events` stream) is a CLEAN,
+ *   non-throwing end — a process that crashes before ever emitting a line
+ *   would otherwise look, from the async-iteration protocol alone, exactly
+ *   like a session that legitimately produced zero events, silently
+ *   swallowing the real failure. `waitForInit()` is a dedicated promise
+ *   that resolves with the real `session_id` once claude's own
+ *   `system/init` frame arrives, or rejects with the same enriched
+ *   exit-error `events` would otherwise swallow — this is what lets
+ *   `ClaudeAdapter.start()` fail loudly and immediately for a bad
+ *   `--resume` target etc., mirroring pi's own fail-fast contract with a
+ *   mechanism suited to claude's ack-less protocol instead of copying pi's
+ *   request/response one verbatim.
+ *
+ * Framing, stderr-ring, and unmapped-frame-tally-in-exit-error all mirror
+ * `../pi/rpc-client.ts`'s already-proven design directly (LF-delimited
+ * JSONL, `node:readline` avoided for the same U+2028/U+2029 reason pi's
+ * doc comment explains, `close` not `exit` for the same complete-stderr
+ * guarantee) — these are generic, sound patterns, not pi-specific logic,
+ * so re-implementing them independently here (rather than importing from
+ * `../pi/`) keeps this adapter fully self-contained, matching this repo's
+ * existing per-adapter isolation.
+ */
+export declare class ClaudeProcessClient {
+    private readonly child;
+    private buffer;
+    private readonly eventQueue;
+    private closed;
+    private exitError;
+    private readonly stderrRing;
+    private readonly unmappedFrameCounts;
+    private sessionId;
+    private initWaiter;
+    constructor(options: ClaudeProcessClientOptions);
+    /**
+     * Write a new user turn onto stdin (`--input-format stream-json`'s wire
+     * shape: `{"type":"user","message":{"role":"user","content":[{"type":
+     * "text","text":...}]}}`). Used identically for the very first turn
+     * (`ClaudeAdapter.start()`) and any later same-session turn
+     * (`ClaudeSession.followUp()`) — empirically confirmed live that claude
+     * keeps a `--input-format stream-json` process alive across multiple
+     * sequential turns on ONE persistent process/session (same `session_id`
+     * reported on each turn's own `system/init` and `result` frames), only
+     * exiting when stdin is closed or the process is killed. This is the
+     * mechanism `followUp()` relies on instead of spawning a fresh
+     * `--resume`'d process per follow-up.
+     */
+    writeUserMessage(text: string): void;
+    /**
+     * Resolves with claude's own `session_id` once its `system/init` frame
+     * arrives (see this class's doc comment for why this exists at all).
+     * Idempotent: once resolved, further calls resolve immediately with the
+     * same id; if the process already closed before init ever arrived,
+     * every call rejects with that same exit error.
+     */
+    waitForInit(): Promise<string>;
+    /** Every parsed stream-json line — `system/init` is consumed internally (see `waitForInit`) but is also forwarded here like any other frame, so routine-frame accounting in `ClaudeSession`'s mapper stays uniform. */
+    get events(): AsyncIterable<ClaudeStreamMessage>;
+    /**
+     * Record a claude stream-json frame/subtype/content-block label that
+     * `ClaudeSession`'s event iterator (`../claude-adapter.ts`) decided has
+     * no `AgentEvent` mapping and isn't routine bookkeeping (see
+     * `events.ts`'s `MapClaudeMessageResult.unmappedLabel` doc comment) —
+     * i.e. genuinely unexpected traffic. Mirrors pi's
+     * `PiRpcClient.recordUnmappedFrame` exactly: logs once per distinct
+     * label, folds the running tally into a later exit error for a
+     * post-mortem without separate log scraping.
+     */
+    recordUnmappedFrame(label: string): void;
+    /** Best-effort teardown. SIGTERM on POSIX; `taskkill /T /F` on Windows to also reap child processes claude itself spawned (e.g. Bash) — mirrors pi's cross-platform `kill()` exactly. Empirically confirmed on this (POSIX) machine: a running claude process exits cleanly within ~1s of SIGTERM (observed exit code 143 = 128+SIGTERM, i.e. claude catches and handles the signal itself rather than needing a harder kill). */
+    kill(): void;
+    private onData;
+    private onLine;
+    private onStderr;
+    /** Mirrors pi's `buildExitError` exactly — stderr tail + unmapped-frame tally folded into one self-diagnosing message. */
+    private buildExitError;
+    private onClosed;
+}

package/dist/adapters/claude/resolve-approval-mcp-bin.d.ts

@@ -0,0 +1,45 @@
+export interface ResolvedApprovalMcpBin {
+    command: string;
+    args: string[];
+    source: 'env' | 'dist';
+}
+/**
+ * Resolve `byok-approval-mcp` — the small stdio MCP server
+ * (`bin/byok-approval-mcp.ts`) `claude`'s own `--permission-prompt-tool`
+ * spawns as ITS child process (see that file's doc comment, and
+ * `permission-mapping.ts`'s `confirm`-mode doc comment, for the full design).
+ *
+ * Unlike `resolveClaudeBin` (the end user's own separately-installed,
+ * separately-authenticated CLI, resolved via bare-name PATH lookup),
+ * `byok-approval-mcp` is a script THIS SAME `@byok-sdk/client` package ships —
+ * bare-name PATH lookup is NOT safe for it: `@byok-sdk/client` is typically a
+ * project-local dependency, so its `node_modules/.bin/byok-approval-mcp`
+ * symlink is only on PATH for processes that inherit THAT project's own
+ * shell/PATH, not reliably for a background OS service (launchd/systemd
+ * often run with a stripped-down PATH that omits project-local
+ * `node_modules/.bin` entirely — see `templates/service/**`). Resolving an
+ * ABSOLUTE path to this package's own compiled bin avoids depending on PATH
+ * at all.
+ *
+ * `BYOK_APPROVAL_MCP_BIN` overrides everything when set — the injectable
+ * seam for tests (mirrors `BYOK_CLAUDE_BIN`/`BYOK_PI_BIN`), letting a test
+ * substitute a fixture script instead of computing any real path. The
+ * override is a single command string with no separate args (tests don't
+ * need to invoke it any differently than `node <script>`); the real default
+ * below is `node <absolute-path-to-the-built-bin>`.
+ *
+ * The default computation is deliberately anchored to THIS module's own
+ * `import.meta.url`, resolved once at the real production entry point: when
+ * `@byok-sdk/client` is built (`tsup.config.ts`), this file's code ends up
+ * bundled into `dist/index.js` at the package root, with `dist/bin/
+ * byok-approval-mcp.js` as its direct sibling (same layout `byok-agent.js`
+ * already uses) — `path.join(path.dirname(fileURLToPath(import.meta.url)),
+ * 'bin', 'byok-approval-mcp.js')` is therefore correct for that one real
+ * shape. It is NOT correct for this file's own unbundled TypeScript source
+ * location (`src/adapters/claude/` is two directories deeper than `src/`),
+ * but nothing in this codebase ever reaches this fallback unbundled — every
+ * test that exercises `confirm` mode sets `BYOK_APPROVAL_MCP_BIN` explicitly
+ * (see `claude-adapter.test.ts`), exactly like `BYOK_CLAUDE_BIN` already
+ * does for the real `claude` binary.
+ */
+export declare function resolveApprovalMcpBin(): ResolvedApprovalMcpBin;

package/dist/adapters/claude/resolve-bin.d.ts

@@ -0,0 +1,27 @@
+export interface ResolvedBin {
+    command: string;
+    source: 'env' | 'path';
+}
+/**
+ * Resolve the `claude` (Claude Code) CLI executable.
+ *
+ * Unlike pi (`../pi/resolve-bin.ts`), this package does NOT bundle a
+ * matched `claude` build as an optionalDependency. Claude Code is the end
+ * user's own globally-installed, individually-authenticated CLI (`claude
+ * auth login`, tied to their Anthropic/claude.ai account) — there is
+ * nothing useful to vendor: a bundled copy could never carry the user's own
+ * login state, and the credential-isolation rule (see `../../types.ts`'s
+ * `RuntimeAdapter` doc comment — this adapter must never read, proxy, or
+ * forward `~/.claude`'s own auth storage) means this adapter has no
+ * business managing a claude install at all, only spawning whatever `claude`
+ * the user already has authenticated on their PATH.
+ *
+ * Resolution is therefore deliberately two-tier, not three like pi's:
+ * `BYOK_CLAUDE_BIN` overrides everything when set (the injectable seam for
+ * in-process tests — mirrors `BYOK_PI_BIN` and substitutes the
+ * `fake-claude.mjs` fixture ahead of a real claude install, exactly as pi's
+ * own override does), otherwise this falls back to the literal command name
+ * `claude`, resolved via the child process's own PATH lookup — there is no
+ * optionalDependency tier in between.
+ */
+export declare function resolveClaudeBin(): ResolvedBin;