@gtc6244/immediacy-daemon 0.1.0

package/dist/src/actions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Prompt-backed agent actions.
+ *
+ * Each {@link WorkspaceActionKind} is a one-tap workflow the client can trigger
+ * on a workspace (review the diff, open a PR, fix build errors, resolve merge
+ * conflicts, rename the branch). The daemon doesn't hard-code the behavior: it
+ * seeds the workspace's *agent* with a built-in base instruction plus the user's
+ * matching `prompts.*` custom text, then lets the agent do the work with its own
+ * tools (Read/Edit/Bash/gh) through the normal permission-gated flow.
+ *
+ * So these consume the previously-reserved prompt config, and adding a new
+ * action is just another entry here — no new agent plumbing.
+ */
+import type { PromptsConfig, WorkspaceActionKind } from "./protocol.js";
+/** True for the one action that mutates the branch name (so the manager can
+ *  re-sync the workspace record afterwards). */
+export declare function actionRenamesBranch(kind: WorkspaceActionKind): boolean;
+/**
+ * The full prompt text injected into the agent for an action: the built-in
+ * instruction, plus the user's custom prompt for that action when set.
+ */
+export declare function composeActionPrompt(kind: WorkspaceActionKind, prompts: PromptsConfig): string;

package/dist/src/actions.js

@@ -0,0 +1,44 @@
+/**
+ * Prompt-backed agent actions.
+ *
+ * Each {@link WorkspaceActionKind} is a one-tap workflow the client can trigger
+ * on a workspace (review the diff, open a PR, fix build errors, resolve merge
+ * conflicts, rename the branch). The daemon doesn't hard-code the behavior: it
+ * seeds the workspace's *agent* with a built-in base instruction plus the user's
+ * matching `prompts.*` custom text, then lets the agent do the work with its own
+ * tools (Read/Edit/Bash/gh) through the normal permission-gated flow.
+ *
+ * So these consume the previously-reserved prompt config, and adding a new
+ * action is just another entry here — no new agent plumbing.
+ */
+/** Built-in instruction per action; the user's custom prompt is appended. */
+const BASE_INSTRUCTION = {
+    code_review: "Review the current changes on this branch versus the base branch. Point out bugs, security issues, and anything that breaks repository conventions; call out missing tests. Do not modify files — just report findings.",
+    create_pr: "Open a pull request for this branch using the `gh` CLI. Write a concise title and a body with a summary, the motivation, and a test plan. If a PR already exists for the branch, report its URL instead.",
+    fix_errors: "Build and/or run the tests for this project, diagnose whatever is failing, and fix the root cause (not the symptom). Re-run the relevant checks to confirm they pass.",
+    resolve_merge_conflicts: "Resolve the outstanding merge conflicts in this worktree. Preserve the intent of both sides; when a resolution is ambiguous, explain the choice you made. Leave the tree in a buildable state.",
+    rename_branch: "Choose a short, kebab-case git branch name that summarizes the work on this branch, then rename the current branch to it with `git branch -m <name>`. Report the new name.",
+};
+/** The prompts.* field whose custom text augments each action. */
+const PROMPT_FIELD = {
+    code_review: "codeReview",
+    create_pr: "createPr",
+    fix_errors: "fixErrors",
+    resolve_merge_conflicts: "resolveMergeConflicts",
+    rename_branch: "renameBranch",
+};
+/** True for the one action that mutates the branch name (so the manager can
+ *  re-sync the workspace record afterwards). */
+export function actionRenamesBranch(kind) {
+    return kind === "rename_branch";
+}
+/**
+ * The full prompt text injected into the agent for an action: the built-in
+ * instruction, plus the user's custom prompt for that action when set.
+ */
+export function composeActionPrompt(kind, prompts) {
+    const custom = prompts[PROMPT_FIELD[kind]]?.trim();
+    const base = BASE_INSTRUCTION[kind];
+    return custom ? `${base}\n\nAdditional instructions:\n${custom}` : base;
+}
+//# sourceMappingURL=actions.js.map

package/dist/src/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,6EAA6E;AAC7E,MAAM,gBAAgB,GAAwC;IAC5D,WAAW,EACT,yNAAyN;IAC3N,SAAS,EACP,0MAA0M;IAC5M,UAAU,EACR,uKAAuK;IACzK,uBAAuB,EACrB,gMAAgM;IAClM,aAAa,EACX,4KAA4K;CAC/K,CAAC;AAEF,kEAAkE;AAClE,MAAM,YAAY,GAAqD;IACrE,WAAW,EAAE,YAAY;IACzB,SAAS,EAAE,UAAU;IACrB,UAAU,EAAE,WAAW;IACvB,uBAAuB,EAAE,uBAAuB;IAChD,aAAa,EAAE,cAAc;CAC9B,CAAC;AAEF;gDACgD;AAChD,MAAM,UAAU,mBAAmB,CAAC,IAAyB;IAC3D,OAAO,IAAI,KAAK,eAAe,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAyB,EACzB,OAAsB;IAEtB,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,iCAAiC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC"}

package/dist/src/agent/agent.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent backend abstraction.
+ *
+ * A workspace owns exactly one Agent. Two implementations:
+ *   - ClaudeAgent — real headless Claude via the Agent SDK (default).
+ *   - MockAgent   — scripted, deterministic; real worktree writes + real diff,
+ *                   no credits burned. Used for local/emulator testing and CI.
+ *
+ * The seam is identical, so the daemon, protocol, permission flow, diff, and UI
+ * are all exercised for real regardless of which backend is behind it. Select
+ * with AGENT_MODE=claude | mock.
+ */
+import { EventEmitter } from "node:events";
+import type { AgentEvent } from "../types.js";
+import type { QuestionAnswers } from "../protocol.js";
+/**
+ * How a client can answer a permission request. `allow`/`deny` are one-shot;
+ * `allow_all` also persists a category rule (see permission-scope.ts) so future
+ * matching calls auto-approve. The gate itself still resolves to a plain
+ * {@link PermissionDecision} — the agent turns `allow_all` into a rule + allow.
+ */
+export type PermissionResponse = "allow" | "deny" | "allow_all";
+/**
+ * The slice of the daemon-global allowlist an agent needs. AllowlistStore
+ * satisfies this structurally, so agent.ts stays free of a store import.
+ */
+export interface PermissionAllowlist {
+    /** True when a persisted rule already covers this call. */
+    isAllowed(tool: string, input: Record<string, unknown>, worktreePath: string): boolean;
+    /** Persist an "allow all" rule for this call (dedup + on-disk). */
+    allowFromCall(tool: string, input: Record<string, unknown>, worktreePath: string, fromWorkspace?: string): Promise<unknown>;
+}
+export interface AgentContext {
+    workspaceId: string;
+    worktreePath: string;
+    /** Existing session id to resume, if any (Claude session / Codex thread). */
+    resumeSessionId?: string;
+    /** Model id to run; backend-specific, undefined → backend default. */
+    model?: string;
+    /**
+     * Custom text (from prompts.general) appended to the session's system prompt.
+     * Empty/undefined → no append. Applied by SDK-backed agents (Claude /
+     * OpenRouter); backends without a system-prompt seam ignore it.
+     */
+    appendSystemPrompt?: string;
+    /**
+     * Daemon-global "Allow all" list. Consulted before a call defers to the phone
+     * (a match auto-approves) and appended to when a client answers `allow_all`.
+     * Undefined → no persisted allowlist (every escape still gates).
+     */
+    allowlist?: PermissionAllowlist;
+}
+/**
+ * A file attached to a prompt (image or document), structurally identical to the
+ * wire `PromptAttachment` but kept here so the agent layer doesn't import the
+ * protocol. `data` is base64-encoded bytes.
+ */
+export interface AgentAttachment {
+    name: string;
+    mediaType: string;
+    data: string;
+}
+export interface Agent {
+    /**
+     * Send a user prompt into the (possibly already running) session. Optional
+     * `attachments` (images / documents) ride along as model content blocks.
+     */
+    prompt(text: string, attachments?: AgentAttachment[]): void;
+    /** Resolve a deferred tool-call permission (allow/deny, or allow_all). */
+    respondPermission(requestId: string, decision: PermissionResponse): void;
+    /**
+     * Supply the user's answers to a deferred `AskUserQuestion` call. Backends
+     * without an interactive-question seam (mock/codex) ignore it — only the
+     * SDK-backed ClaudeAgent gates on it. `response` is an optional freeform reply
+     * used in place of the structured `answers`.
+     */
+    answerQuestion(requestId: string, answers: QuestionAnswers, response?: string): void;
+    /** Tear down the session and deny anything outstanding. */
+    stop(): Promise<void>;
+}
+/** Agents emit a single typed "event" carrying AgentEvent. */
+export declare abstract class BaseAgent extends EventEmitter implements Agent {
+    protected emitEvent(e: AgentEvent): void;
+    abstract prompt(text: string, attachments?: AgentAttachment[]): void;
+    abstract respondPermission(requestId: string, decision: PermissionResponse): void;
+    /** Default no-op; only interactive-question backends (ClaudeAgent) override. */
+    answerQuestion(_requestId: string, _answers: QuestionAnswers, _response?: string): void;
+    abstract stop(): Promise<void>;
+}

package/dist/src/agent/agent.js

@@ -0,0 +1,22 @@
+/**
+ * Agent backend abstraction.
+ *
+ * A workspace owns exactly one Agent. Two implementations:
+ *   - ClaudeAgent — real headless Claude via the Agent SDK (default).
+ *   - MockAgent   — scripted, deterministic; real worktree writes + real diff,
+ *                   no credits burned. Used for local/emulator testing and CI.
+ *
+ * The seam is identical, so the daemon, protocol, permission flow, diff, and UI
+ * are all exercised for real regardless of which backend is behind it. Select
+ * with AGENT_MODE=claude | mock.
+ */
+import { EventEmitter } from "node:events";
+/** Agents emit a single typed "event" carrying AgentEvent. */
+export class BaseAgent extends EventEmitter {
+    emitEvent(e) {
+        this.emit("event", e);
+    }
+    /** Default no-op; only interactive-question backends (ClaudeAgent) override. */
+    answerQuestion(_requestId, _answers, _response) { }
+}
+//# sourceMappingURL=agent.js.map

package/dist/src/agent/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/agent/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA+E3C,8DAA8D;AAC9D,MAAM,OAAgB,SAAU,SAAQ,YAAY;IACxC,SAAS,CAAC,CAAa;QAC/B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxB,CAAC;IAGD,gFAAgF;IAChF,cAAc,CAAC,UAAkB,EAAE,QAAyB,EAAE,SAAkB,IAAS,CAAC;CAE3F"}

package/dist/src/agent/claude.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ClaudeAgent — real headless Claude via the Agent SDK.
+ *
+ * - Streaming input: prompts are pushed into an async queue so one long-lived
+ *   session handles many turns (reuse, per §3 billing guidance — no session
+ *   spam).
+ * - Session continuity: the first `system/init` message yields the session id;
+ *   we persist it for `resume`.
+ * - Permissions: `canUseTool` fires before EVERY tool execution. Calls confined
+ *   to the worktree (the workspace folder) are auto-approved — the same trust
+ *   boundary Codex enforces with `-s workspace-write`, so bash/scripts/edits
+ *   inside the workspace just run. Anything that escapes the worktree becomes an
+ *   `event.permission_request` and blocks on the phone via the shared gate
+ *   (default-deny on timeout). Set WORKSPACE_AUTO_APPROVE=0 to gate everything.
+ *   No `bypassPermissions`, ever.
+ * - Bandwidth: we emit message-level assistant text only; partial/token deltas
+ *   stay off (includePartialMessages disabled).
+ */
+import { BaseAgent, AgentContext, AgentAttachment, PermissionResponse } from "./agent.js";
+import type { QuestionAnswers } from "../protocol.js";
+export declare class ClaudeAgent extends BaseAgent {
+    private ctx;
+    private sdkEnv?;
+    private gate;
+    /**
+     * Deferred `AskUserQuestion` calls, keyed by requestId. Separate from the
+     * permission gate because the answer is structured data fed back as the tool
+     * result — not an allow/deny — and it waits far longer for the user.
+     */
+    private questionGate;
+    /**
+     * Live gated calls, keyed by requestId, kept only while the phone is deciding.
+     * `allow_all` needs the call's (tool, input) to derive the category rule, so
+     * we stash it here rather than round-tripping it back from the client.
+     */
+    private pendingCalls;
+    private inputQueue;
+    private inputResolver;
+    private closed;
+    private started;
+    private sessionId?;
+    /**
+     * @param sdkEnv Optional environment overrides for the Agent SDK subprocess.
+     *   Used to retarget the same streaming/permission machinery at an
+     *   Anthropic-compatible endpoint (e.g. OpenRouter — see OpenRouterAgent).
+     *   The SDK's `env` option *replaces* the subprocess environment, so these
+     *   are merged over `process.env` at query time (below), never mutating it —
+     *   a Claude and an OpenRouter workspace can run side by side.
+     */
+    constructor(ctx: AgentContext, sdkEnv?: Record<string, string | undefined> | undefined);
+    prompt(text: string, attachments?: AgentAttachment[]): void;
+    respondPermission(requestId: string, decision: PermissionResponse): void;
+    answerQuestion(requestId: string, answers: QuestionAnswers, response?: string): void;
+    /**
+     * Sweep the still-pending calls after a new "allow all" rule lands and let
+     * through any the allowlist now covers, emitting a `permission_resolved` per
+     * released call so clients collapse those (no-longer-actionable) cards. Safe
+     * to call with no allowlist or nothing pending — it just does nothing.
+     *
+     * Relies on AllowlistStore.allowFromCall having added the rule to its
+     * in-memory map synchronously (before its async persist), so `isAllowed`
+     * already reflects it by the time we sweep.
+     */
+    private releaseCoveredPending;
+    stop(): Promise<void>;
+    /** Push-based async iterable of user messages for the SDK's streaming input. */
+    private inputStream;
+    private runLoop;
+    private handleMessage;
+}

package/dist/src/agent/claude.js

@@ -0,0 +1,404 @@
+/**
+ * ClaudeAgent — real headless Claude via the Agent SDK.
+ *
+ * - Streaming input: prompts are pushed into an async queue so one long-lived
+ *   session handles many turns (reuse, per §3 billing guidance — no session
+ *   spam).
+ * - Session continuity: the first `system/init` message yields the session id;
+ *   we persist it for `resume`.
+ * - Permissions: `canUseTool` fires before EVERY tool execution. Calls confined
+ *   to the worktree (the workspace folder) are auto-approved — the same trust
+ *   boundary Codex enforces with `-s workspace-write`, so bash/scripts/edits
+ *   inside the workspace just run. Anything that escapes the worktree becomes an
+ *   `event.permission_request` and blocks on the phone via the shared gate
+ *   (default-deny on timeout). Set WORKSPACE_AUTO_APPROVE=0 to gate everything.
+ *   No `bypassPermissions`, ever.
+ * - Bandwidth: we emit message-level assistant text only; partial/token deltas
+ *   stay off (includePartialMessages disabled).
+ */
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { BaseAgent } from "./agent.js";
+import { PermissionGate, QuestionGate } from "../permission-gate.js";
+import { isWorkspaceScoped } from "./workspace-scope.js";
+import { classifyModelError } from "./model-error.js";
+import { detectUsageLimit } from "../usage-limit.js";
+import { extractTurnUsage } from "../usage.js";
+import { logger } from "../log.js";
+import { webRootUrl } from "../permission-scope.js";
+/** Escape hatch: WORKSPACE_AUTO_APPROVE=0 gates every tool call to the phone. */
+const AUTO_APPROVE_WORKSPACE = process.env.WORKSPACE_AUTO_APPROVE !== "0";
+export class ClaudeAgent extends BaseAgent {
+    ctx;
+    sdkEnv;
+    gate = new PermissionGate(120_000);
+    /**
+     * Deferred `AskUserQuestion` calls, keyed by requestId. Separate from the
+     * permission gate because the answer is structured data fed back as the tool
+     * result — not an allow/deny — and it waits far longer for the user.
+     */
+    questionGate = new QuestionGate();
+    /**
+     * Live gated calls, keyed by requestId, kept only while the phone is deciding.
+     * `allow_all` needs the call's (tool, input) to derive the category rule, so
+     * we stash it here rather than round-tripping it back from the client.
+     */
+    pendingCalls = new Map();
+    inputQueue = [];
+    inputResolver = null;
+    closed = false;
+    started = false;
+    sessionId;
+    /**
+     * @param sdkEnv Optional environment overrides for the Agent SDK subprocess.
+     *   Used to retarget the same streaming/permission machinery at an
+     *   Anthropic-compatible endpoint (e.g. OpenRouter — see OpenRouterAgent).
+     *   The SDK's `env` option *replaces* the subprocess environment, so these
+     *   are merged over `process.env` at query time (below), never mutating it —
+     *   a Claude and an OpenRouter workspace can run side by side.
+     */
+    constructor(ctx, sdkEnv) {
+        super();
+        this.ctx = ctx;
+        this.sdkEnv = sdkEnv;
+        this.sessionId = ctx.resumeSessionId;
+    }
+    prompt(text, attachments) {
+        if (this.closed)
+            return;
+        this.inputQueue.push({
+            type: "user",
+            message: { role: "user", content: buildContent(text, attachments) },
+            parent_tool_use_id: null,
+        });
+        this.inputResolver?.();
+        this.inputResolver = null;
+        if (!this.started) {
+            this.started = true;
+            void this.runLoop();
+        }
+    }
+    respondPermission(requestId, decision) {
+        if (decision === "allow_all") {
+            // Persist a category rule from the pending call, then let this one
+            // through. If the call can't be generalized (unmodeled shape) or is
+            // already gone, this still resolves as a plain allow.
+            const call = this.pendingCalls.get(requestId);
+            if (call && this.ctx.allowlist) {
+                void this.ctx.allowlist
+                    .allowFromCall(call.tool, call.input, this.ctx.worktreePath, this.ctx.workspaceId)
+                    .catch((err) => logger.error("model", "persisting allow-all rule failed", {
+                    ws: this.ctx.workspaceId,
+                    data: { message: err instanceof Error ? err.message : String(err) },
+                }));
+            }
+            this.pendingCalls.delete(requestId);
+            this.gate.resolve(requestId, "allow");
+            // The new rule may already cover other calls queued in this same burst
+            // (e.g. the model fired eight WebFetches to one site at once). Release
+            // them now instead of prompting for each — the whole point of "allow all".
+            this.releaseCoveredPending();
+            return;
+        }
+        this.pendingCalls.delete(requestId);
+        this.gate.resolve(requestId, decision);
+    }
+    answerQuestion(requestId, answers, response) {
+        this.questionGate.resolve(requestId, { answers, response });
+    }
+    /**
+     * Sweep the still-pending calls after a new "allow all" rule lands and let
+     * through any the allowlist now covers, emitting a `permission_resolved` per
+     * released call so clients collapse those (no-longer-actionable) cards. Safe
+     * to call with no allowlist or nothing pending — it just does nothing.
+     *
+     * Relies on AllowlistStore.allowFromCall having added the rule to its
+     * in-memory map synchronously (before its async persist), so `isAllowed`
+     * already reflects it by the time we sweep.
+     */
+    releaseCoveredPending() {
+        const allowlist = this.ctx.allowlist;
+        if (!allowlist)
+            return;
+        // Snapshot first: we mutate pendingCalls inside the loop.
+        for (const [reqId, call] of [...this.pendingCalls]) {
+            if (!allowlist.isAllowed(call.tool, call.input, this.ctx.worktreePath))
+                continue;
+            this.pendingCalls.delete(reqId);
+            this.gate.resolve(reqId, "allow");
+            this.emitEvent({ kind: "permission_resolved", requestId: reqId, decision: "allow" });
+        }
+    }
+    async stop() {
+        this.closed = true;
+        this.pendingCalls.clear();
+        this.gate.denyAll();
+        this.questionGate.denyAll();
+        this.inputResolver?.();
+    }
+    /** Push-based async iterable of user messages for the SDK's streaming input. */
+    async *inputStream() {
+        while (!this.closed) {
+            while (this.inputQueue.length) {
+                yield this.inputQueue.shift();
+            }
+            if (this.closed)
+                return;
+            await new Promise((r) => (this.inputResolver = r));
+        }
+    }
+    async runLoop() {
+        const ws = this.ctx.workspaceId;
+        const model = this.ctx.model ?? "default";
+        const startMs = Date.now();
+        let firstMessageSeen = false;
+        logger.info("model", "model request started", {
+            ws,
+            data: { model, resumed: Boolean(this.sessionId) },
+        });
+        try {
+            const response = query({
+                prompt: this.inputStream(),
+                options: {
+                    cwd: this.ctx.worktreePath,
+                    resume: this.sessionId,
+                    ...(this.ctx.model ? { model: this.ctx.model } : {}),
+                    ...(this.sdkEnv ? { env: { ...process.env, ...this.sdkEnv } } : {}),
+                    // prompts.general (app config): append to Claude Code's own system
+                    // prompt rather than replacing it. Omitted when empty.
+                    ...(this.ctx.appendSystemPrompt
+                        ? {
+                            systemPrompt: {
+                                type: "preset",
+                                preset: "claude_code",
+                                append: this.ctx.appendSystemPrompt,
+                            },
+                        }
+                        : {}),
+                    includePartialMessages: false,
+                    // Workspace-scoped calls run without a phone round-trip; anything
+                    // that escapes the worktree routes through canUseTool → the phone.
+                    canUseTool: async (toolName, input, opts) => {
+                        // AskUserQuestion is not a permission gate — it's an interactive
+                        // multiple-choice prompt whose *answers* become the tool result. Emit
+                        // a dedicated card, wait for the user's picks, and hand them back as
+                        // updatedInput (SDK contract: { questions, answers }). No tool_use
+                        // event, so it never renders as a collapsed generic tool call.
+                        if (toolName === "AskUserQuestion") {
+                            const requestId = opts.toolUseID;
+                            const questions = extractQuestions(input);
+                            this.emitEvent({ kind: "ask_question", requestId, questions });
+                            this.emitEvent({ kind: "status", status: "awaiting_permission" });
+                            const answer = await this.questionGate.wait(requestId);
+                            this.emitEvent({ kind: "status", status: "running" });
+                            if (!answer || (Object.keys(answer.answers).length === 0 && !answer.response)) {
+                                return { behavior: "deny", message: "User did not answer the question." };
+                            }
+                            return {
+                                behavior: "allow",
+                                updatedInput: {
+                                    questions: input.questions ?? questions,
+                                    answers: answer.answers,
+                                    ...(answer.response ? { response: answer.response } : {}),
+                                },
+                            };
+                        }
+                        const inputSummary = opts.title ?? summarize(toolName, input);
+                        this.emitEvent({ kind: "tool_use", tool: toolName, inputSummary });
+                        if (AUTO_APPROVE_WORKSPACE &&
+                            isWorkspaceScoped(toolName, input, this.ctx.worktreePath)) {
+                            return { behavior: "allow", updatedInput: input };
+                        }
+                        // A prior "Allow all" may already cover this category (same host,
+                        // folder, or tool) — auto-approve without a phone round-trip.
+                        if (this.ctx.allowlist?.isAllowed(toolName, input, this.ctx.worktreePath)) {
+                            return { behavior: "allow", updatedInput: input };
+                        }
+                        const requestId = opts.toolUseID;
+                        this.pendingCalls.set(requestId, { tool: toolName, input });
+                        this.emitEvent({ kind: "status", status: "awaiting_permission" });
+                        this.emitEvent({ kind: "permission", requestId, tool: toolName, inputSummary });
+                        const decision = await this.gate.wait(requestId);
+                        this.pendingCalls.delete(requestId);
+                        this.emitEvent({ kind: "status", status: "running" });
+                        return decision === "allow"
+                            ? { behavior: "allow", updatedInput: input }
+                            : { behavior: "deny", message: "Denied from phone" };
+                    },
+                },
+            });
+            this.emitEvent({ kind: "status", status: "running" });
+            for await (const msg of response) {
+                if (this.closed)
+                    break;
+                if (!firstMessageSeen) {
+                    firstMessageSeen = true;
+                    // First inbound SDK message = the model is reachable and answering.
+                    logger.info("model", "model reachable", {
+                        ws,
+                        data: { model, latencyMs: Date.now() - startMs },
+                    });
+                }
+                this.handleMessage(msg);
+            }
+        }
+        catch (err) {
+            const cls = classifyModelError(err);
+            logger.error("model", "model request failed", {
+                ws,
+                data: {
+                    model,
+                    class: cls,
+                    reachedModel: firstMessageSeen,
+                    message: err instanceof Error ? err.message : String(err),
+                },
+            });
+            const message = err instanceof Error ? err.message : String(err);
+            // A plan/session usage limit is a distinct, actionable case: strict
+            // matching keeps a transient 429/overload (also class `rate_limit`) out of
+            // the restart flow — only a real usage-limit notice surfaces the card.
+            const limit = detectUsageLimit(message, { strict: true });
+            if (limit) {
+                this.emitEvent({ kind: "limit", message: limit.message, resetAt: limit.resetAt });
+            }
+            else {
+                this.emitEvent({ kind: "error", message });
+            }
+            this.emitEvent({ kind: "status", status: "error" });
+        }
+    }
+    handleMessage(msg) {
+        const m = msg;
+        switch (m.type) {
+            case "system": {
+                if (m.subtype === "init" && typeof m.session_id === "string") {
+                    this.sessionId = m.session_id;
+                    this.emitEvent({ kind: "session", sessionId: m.session_id });
+                }
+                return;
+            }
+            case "assistant": {
+                const content = m.message?.content;
+                const text = extractText(content);
+                if (text)
+                    this.emitEvent({ kind: "assistant", text });
+                return;
+            }
+            case "result": {
+                const summary = typeof m.result === "string" ? m.result : undefined;
+                // A limit can arrive as an error result rather than a thrown exception.
+                // Strict matching is safe against a successful turn's own result text.
+                const isError = typeof m.subtype === "string" && m.subtype !== "success";
+                const limit = isError ? detectUsageLimit(summary, { strict: true }) : null;
+                if (limit) {
+                    this.emitEvent({ kind: "limit", message: limit.message, resetAt: limit.resetAt });
+                    this.emitEvent({ kind: "status", status: "error" });
+                    return;
+                }
+                this.emitEvent({ kind: "done", summary, usage: extractTurnUsage(m) });
+                this.emitEvent({ kind: "status", status: "done" });
+                return;
+            }
+            default:
+                return; // partial/status/etc. — not forwarded
+        }
+    }
+}
+/**
+ * Turn a prompt (+ optional attachments) into the SDK user-message `content`.
+ *
+ * With no attachments this stays a plain string — the original, backward-compatible
+ * shape. With attachments it becomes an array of Anthropic content blocks so the
+ * model sees the files directly (no tool round-trip):
+ *   - images       → an `image` block (base64 source);
+ *   - PDFs         → a `document` block (base64 source), titled with the filename;
+ *   - anything else → the bytes decoded as UTF-8 and wrapped in a labelled `text`
+ *                     block, which every model accepts (unlike document blocks).
+ */
+function buildContent(text, attachments) {
+    if (!attachments || attachments.length === 0)
+        return text;
+    const blocks = [];
+    if (text.trim().length > 0)
+        blocks.push({ type: "text", text });
+    for (const a of attachments) {
+        if (a.mediaType.startsWith("image/")) {
+            blocks.push({
+                type: "image",
+                source: { type: "base64", media_type: a.mediaType, data: a.data },
+            });
+        }
+        else if (a.mediaType === "application/pdf") {
+            blocks.push({
+                type: "document",
+                title: a.name,
+                source: { type: "base64", media_type: "application/pdf", data: a.data },
+            });
+        }
+        else {
+            const decoded = Buffer.from(a.data, "base64").toString("utf8");
+            blocks.push({
+                type: "text",
+                text: `<attached file: ${a.name}>\n${decoded}\n</attached file>`,
+            });
+        }
+    }
+    // All attachments were empty text and there was no prompt — fall back to a
+    // single empty text block so the message is never a zero-block array.
+    if (blocks.length === 0)
+        blocks.push({ type: "text", text });
+    return blocks;
+}
+/** Join text blocks of an assistant message into one string. */
+function extractText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((b) => b && typeof b === "object" && b.type === "text")
+        .map((b) => b.text ?? "")
+        .join("")
+        .trim();
+}
+/** Compact one-line summary of a tool input, for the permission card. */
+function summarize(tool, input) {
+    // Web requests (WebFetch, browser/MCP tools) read as a plain "web request to
+    // <site>" — the technical tool name, full path/query, and JSON aren't useful
+    // on a notification; the root URL is enough to tell what's being reached.
+    const url = webRootUrl(input);
+    if (url)
+        return `Web request to ${url}`;
+    const path = input.file_path ?? input.path ?? input.command ?? input.pattern;
+    if (typeof path === "string")
+        return `${tool}: ${path}`;
+    const json = JSON.stringify(input);
+    return `${tool}: ${json.length > 80 ? json.slice(0, 77) + "…" : json}`;
+}
+/**
+ * Normalize the AskUserQuestion tool input into our wire {@link AgentQuestion}[].
+ * Defensive against shape drift: coerces every field and drops nothing silently
+ * beyond malformed options, so a client always gets renderable questions.
+ */
+function extractQuestions(input) {
+    const raw = input.questions;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((q) => {
+        const obj = (q ?? {});
+        const opts = Array.isArray(obj.options) ? obj.options : [];
+        return {
+            question: String(obj.question ?? ""),
+            header: String(obj.header ?? ""),
+            multiSelect: Boolean(obj.multiSelect),
+            options: opts.map((o) => {
+                const oo = (o ?? {});
+                return {
+                    label: String(oo.label ?? ""),
+                    description: oo.description != null ? String(oo.description) : undefined,
+                    preview: typeof oo.preview === "string" ? oo.preview : undefined,
+                };
+            }),
+        };
+    });
+}
+//# sourceMappingURL=claude.js.map