@asterxsk/kiln 0.1.0 → 0.2.0

package/agent/extensions/subagents/src/backends/claude.ts

@@ -1,701 +1,701 @@
-/**
- * Claude Code backend — real implementation over the Claude Agent SDK.
- *
- * One SDK `query()` and one streaming-input bridge live for the whole scoped
- * session. User sends are pushed into that bridge, while the query iterator is
- * pumped in the background and translated to normalized SubagentEvents. The
- * CLI therefore owns conversation continuity, tool execution, and persisted
- * `~/.claude/projects` transcripts; this file only owns lifecycle guarantees
- * and the normalized view consumed by the manager.
- */
-
-import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import {
-  query,
-  type SDKAssistantMessage,
-  type SDKMessage,
-  type SDKResultMessage,
-  type SDKUserMessage,
-} from "@anthropic-ai/claude-agent-sdk";
-import type { Cause, Scope } from "effect";
-import { Effect, Queue, Stream } from "effect";
-import type { SubagentBackend, SubagentSession } from "../backend.ts";
-import type {
-  QueuedMessage,
-  ReasoningEffort,
-  RunOutcome,
-  SpawnTask,
-  SubagentEvent,
-  SubagentMeta,
-  TranscriptPart,
-} from "../domain.ts";
-import { SendError, SpawnError } from "../domain.ts";
-
-const CLAUDE_CONTEXT_WINDOW = 200_000;
-const INTERRUPT_TIMEOUT_MS = 2_000;
-const PREVIEW_MAX_LENGTH = 4_096;
-
-// --- Binary resolution --------------------------------------------------------
-
-let cachedClaudeBinary: string | null | undefined;
-
-function executable(file: string) {
-  try {
-    fs.accessSync(file, fs.constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Resolve the Claude Code CLI once from PATH. The SDK can also run without
- * this (it bundles a CLI), but pointing it at the user's installed binary
- * keeps versions, settings, and login state consistent with their terminal.
- */
-function resolveClaudeBinary() {
-  if (cachedClaudeBinary !== undefined) return cachedClaudeBinary ?? undefined;
-  const names =
-    process.platform === "win32"
-      ? ["claude.exe", "claude.cmd", "claude"]
-      : ["claude"];
-  for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
-    if (!directory) continue;
-    for (const name of names) {
-      const candidate = path.join(directory, name);
-      if (executable(candidate)) {
-        cachedClaudeBinary = candidate;
-        return candidate;
-      }
-    }
-  }
-  cachedClaudeBinary = null;
-  return undefined;
-}
-
-// --- Streaming input ---------------------------------------------------------
-
-/** A single-consumer push queue adapted to the SDK's AsyncIterable input. */
-class ClaudeInput implements AsyncIterable<SDKUserMessage> {
-  private pending: SDKUserMessage[] = [];
-  private waiter:
-    ((result: IteratorResult<SDKUserMessage>) => void) | undefined;
-  private closed = false;
-
-  push(text: string) {
-    if (this.closed) return undefined;
-    const message: SDKUserMessage = {
-      type: "user",
-      message: { role: "user", content: text },
-      parent_tool_use_id: null,
-      // Stamped UUIDs make queued messages visible in interrupt receipts.
-      uuid: randomUUID(),
-    };
-    const waiter = this.waiter;
-    if (waiter) {
-      this.waiter = undefined;
-      waiter({ value: message, done: false });
-    } else {
-      this.pending.push(message);
-    }
-    return message;
-  }
-
-  clear() {
-    return this.pending.splice(0);
-  }
-
-  end() {
-    if (this.closed) return;
-    this.closed = true;
-    const waiter = this.waiter;
-    this.waiter = undefined;
-    waiter?.({ value: undefined, done: true });
-  }
-
-  async *[Symbol.asyncIterator]() {
-    while (true) {
-      const message = this.pending.shift();
-      if (message) {
-        yield message;
-        continue;
-      }
-      if (this.closed) return;
-      const next = await new Promise<IteratorResult<SDKUserMessage>>(
-        (resolve) => {
-          this.waiter = resolve;
-        },
-      );
-      if (next.done) return;
-      yield next.value;
-    }
-  }
-}
-
-// --- Model, effort, and transcript helpers ----------------------------------
-
-/**
- * Claude's deprecated-but-supported maxThinkingTokens is the closest match to
- * the shared numeric scale requested by this extension. Zero explicitly
- * disables extended thinking in SDK 0.3.207; an omitted effort leaves the CLI
- * default untouched.
- */
-const THINKING_BUDGETS = {
-  off: 0,
-  minimal: 1_024,
-  low: 4_096,
-  medium: 10_000,
-  high: 16_000,
-  xhigh: 32_000,
-  max: 63_999,
-} satisfies Record<ReasoningEffort, number>;
-
-function boundedError(error: unknown) {
-  return (error instanceof Error ? error.message : String(error)).slice(
-    0,
-    4_096,
-  );
-}
-
-function singleLine(text: string) {
-  const flattened = text.replace(/\s+/g, " ").trim();
-  return flattened ? flattened.slice(0, PREVIEW_MAX_LENGTH) : undefined;
-}
-
-function safeJson(value: unknown) {
-  try {
-    const text = JSON.stringify(value);
-    if (!text || text === "{}") return undefined;
-    return singleLine(text);
-  } catch {
-    return undefined;
-  }
-}
-
-function outputPreview(value: unknown): string | undefined {
-  if (typeof value === "string") return singleLine(value);
-  if (Array.isArray(value)) {
-    const text = value
-      .flatMap((part) => {
-        if (!part || typeof part !== "object") return [];
-        const record = part as { type?: unknown; text?: unknown };
-        return record.type === "text" && typeof record.text === "string"
-          ? [record.text]
-          : [];
-      })
-      .join(" ");
-    return singleLine(text) ?? safeJson(value);
-  }
-  return safeJson(value);
-}
-
-function assistantParts(message: SDKAssistantMessage): TranscriptPart[] {
-  const parts: TranscriptPart[] = [];
-  for (const block of message.message.content) {
-    if (block.type === "text") {
-      parts.push({ type: "text", text: block.text });
-    } else if (block.type === "thinking") {
-      parts.push({ type: "thinking", text: block.thinking });
-    } else if (block.type === "redacted_thinking") {
-      parts.push({ type: "thinking", text: "", redacted: true });
-    } else if (block.type === "tool_use") {
-      parts.push({
-        type: "toolCall",
-        toolId: block.id,
-        name: block.name,
-        argsPreview: safeJson(block.input),
-      });
-    }
-  }
-  return parts;
-}
-
-/** Claude Code's project-directory escaping, verified against CLI 2.1.207. */
-function sessionFilePath(cwd: string, sessionId: string) {
-  const projectDirectory = cwd.replace(/[/.]/g, "-");
-  return path.join(
-    os.homedir(),
-    ".claude",
-    "projects",
-    projectDirectory,
-    `${sessionId}.jsonl`,
-  );
-}
-
-/**
- * Context occupancy after one API request. An assistant message's `usage`
- * describes only that request: the full prompt (fresh + cache-read +
- * cache-written input) plus this response's output — exactly what now sits
- * in the context window. The result message's `usage` instead sums these
- * per-request counts across the whole run, so a multi-request turn
- * re-counts cached context once per request and quickly exceeds the real
- * window; it must never be treated as occupancy.
- */
-export function contextOccupancyTokens(
-  usage:
-    | {
-        input_tokens?: number | null;
-        cache_read_input_tokens?: number | null;
-        cache_creation_input_tokens?: number | null;
-        output_tokens?: number | null;
-      }
-    | null
-    | undefined,
-) {
-  if (!usage || typeof usage.input_tokens !== "number") return undefined;
-  const count = (value: number | null | undefined) =>
-    typeof value === "number" && Number.isFinite(value) ? value : 0;
-  return (
-    count(usage.input_tokens) +
-    count(usage.cache_read_input_tokens) +
-    count(usage.cache_creation_input_tokens) +
-    count(usage.output_tokens)
-  );
-}
-
-function resultContextWindow(result: SDKResultMessage) {
-  return Object.values(result.modelUsage)[0]?.contextWindow;
-}
-
-function waitBounded(operation: Promise<unknown>, timeoutMs: number) {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<void>((resolve) => {
-    timer = setTimeout(resolve, timeoutMs);
-  });
-  return Promise.race([
-    operation.then(
-      () => undefined,
-      () => undefined,
-    ),
-    timeout,
-  ]).finally(() => {
-    if (timer) clearTimeout(timer);
-  });
-}
-
-// --- The session -------------------------------------------------------------
-
-interface NativeQueuedMessage extends QueuedMessage {
-  readonly uuid: string;
-  /** Raw response sequence after which this steer can be consumed. */
-  readonly afterResponse: number;
-}
-
-const makeClaudeSession = (
-  task: SpawnTask,
-): Effect.Effect<SubagentSession, SpawnError, Scope.Scope> =>
-  Effect.gen(function* () {
-    const input = new ClaudeInput();
-    const abortController = new AbortController();
-    const events = yield* Queue.make<SubagentEvent, Cause.Done>();
-    const emit = (event: SubagentEvent) => {
-      Queue.offerUnsafe(events, event);
-    };
-
-    const state = {
-      closed: false,
-      activeRun: false,
-      interruptRequested: false,
-      runVersion: 0,
-      lastSettledVersion: 0,
-      responseSequence: 0,
-      queued: [] as NativeQueuedMessage[],
-      submittedUuids: new Set<string>(),
-      currentText: "",
-      liveText: "",
-      tools: new Map<string, string>(),
-      settleWaiters: new Set<() => void>(),
-      meta: {
-        backend: "claude",
-        modelLabel: task.model,
-        // Claude models used by this backend currently expose 200k context;
-        // result.modelUsage replaces this fallback when the CLI knows better.
-        contextWindow: CLAUDE_CONTEXT_WINDOW,
-      } satisfies SubagentMeta as SubagentMeta,
-    };
-
-    const thinkingBudget = task.reasoningEffort
-      ? THINKING_BUDGETS[task.reasoningEffort]
-      : undefined;
-    const claudeBinary = resolveClaudeBinary();
-    const nativeQuery = yield* Effect.try({
-      try: () =>
-        query({
-          prompt: input,
-          options: {
-            cwd: task.cwd,
-            // Headless children cannot answer approval prompts. The caller
-            // already chose to launch an autonomous subagent, so let it use
-            // its tools without interactive permission checks.
-            permissionMode: "bypassPermissions",
-            allowDangerouslySkipPermissions: true,
-            // Keep child orchestration inside this extension's global manager
-            // and concurrency cap rather than Claude Code's native subagents.
-            disallowedTools: ["Agent", "Task"],
-            // For cwds pi marked untrusted, restrict to user-level settings so
-            // an untrusted project's config cannot reconfigure the child.
-            ...(task.parent.projectTrusted
-              ? {}
-              : { settingSources: ["user" as const] }),
-            includePartialMessages: true,
-            abortController,
-            ...(claudeBinary
-              ? { pathToClaudeCodeExecutable: claudeBinary }
-              : {}),
-            ...(task.model ? { model: task.model } : {}),
-            ...(thinkingBudget !== undefined
-              ? { maxThinkingTokens: thinkingBudget }
-              : {}),
-          },
-        }),
-      catch: (error) => new SpawnError({ message: boundedError(error) }),
-    });
-
-    let resolvePumpDone: (() => void) | undefined;
-    const pumpDone = new Promise<void>((resolve) => {
-      resolvePumpDone = resolve;
-    });
-
-    const queuedView = (): ReadonlyArray<QueuedMessage> =>
-      state.queued.map(({ text, kind }) => ({ text, kind }));
-
-    const notifySettled = () => {
-      for (const waiter of state.settleWaiters) waiter();
-      state.settleWaiters.clear();
-    };
-
-    const partialText = () => state.liveText || state.currentText || undefined;
-
-    const settle = (outcome: RunOutcome) => {
-      if (!state.activeRun) return;
-      emit({ _tag: "RunSettled", outcome });
-      state.activeRun = false;
-      state.lastSettledVersion = state.runVersion;
-      state.interruptRequested = false;
-      state.liveText = "";
-      notifySettled();
-    };
-
-    const updateMeta = (patch: Partial<SubagentMeta>) => {
-      state.meta = { ...state.meta, ...patch };
-      emit({ _tag: "MetaChanged", meta: patch });
-    };
-
-    const beginQueuedRunIfNeeded = () => {
-      if (state.activeRun || state.queued.length === 0) return;
-      // A steer arriving too late for the prior turn becomes a fresh queued
-      // turn. The repeated init is the first reliable signal that it started.
-      state.activeRun = true;
-      state.runVersion++;
-      state.currentText = "";
-      state.liveText = "";
-      emit({ _tag: "RunStarted" });
-    };
-
-    const clearConsumedSteers = () => {
-      const remaining = state.queued.filter(
-        (message) => message.afterResponse >= state.responseSequence,
-      );
-      if (remaining.length === state.queued.length) return;
-      state.queued = remaining;
-      emit({ _tag: "QueueChanged", queued: queuedView() });
-    };
-
-    const handleAssistant = (message: SDKAssistantMessage) => {
-      const parts = assistantParts(message);
-      if (parts.length > 0) emit({ _tag: "AssistantMessage", parts });
-
-      // Top-level messages only: subagent (sidechain) requests have their own
-      // context and must not overwrite this conversation's occupancy.
-      if (message.parent_tool_use_id == null) {
-        const tokens = contextOccupancyTokens(message.message.usage);
-        if (tokens !== undefined) emit({ _tag: "UsageChanged", tokens });
-      }
-
-      const text = message.message.content
-        .filter((block) => block.type === "text")
-        .map((block) => block.text)
-        .join("\n")
-        .trim();
-      if (text) state.currentText = text;
-      state.liveText = "";
-
-      if (message.message.model !== state.meta.modelLabel) {
-        updateMeta({ modelLabel: message.message.model });
-      }
-      for (const block of message.message.content) {
-        if (block.type !== "tool_use") continue;
-        state.tools.set(block.id, block.name);
-        emit({
-          _tag: "ToolStart",
-          toolId: block.id,
-          name: block.name,
-          argsPreview: safeJson(block.input),
-        });
-      }
-    };
-
-    const handleUser = (message: SDKUserMessage) => {
-      const content = message.message.content;
-      if (!Array.isArray(content)) return;
-      for (const block of content) {
-        if (block.type !== "tool_result") continue;
-        const name = state.tools.get(block.tool_use_id) ?? "Tool";
-        state.tools.delete(block.tool_use_id);
-        emit({
-          _tag: "ToolEnd",
-          toolId: block.tool_use_id,
-          name,
-          isError: block.is_error ?? false,
-          outputPreview: outputPreview(block.content),
-        });
-      }
-      // External prompts are emitted synchronously by submit(); ignoring text
-      // here prevents a future CLI echo from duplicating the transcript row.
-    };
-
-    const handleResult = (result: SDKResultMessage) => {
-      // result.usage is a whole-run aggregate, not occupancy (see
-      // contextOccupancyTokens); only the capacity is trustworthy here. The
-      // occupancy itself was already emitted by the last assistant message.
-      const contextWindow = resultContextWindow(result);
-      emit({
-        _tag: "UsageChanged",
-        contextWindow: contextWindow ?? state.meta.contextWindow,
-      });
-      if (
-        contextWindow !== undefined &&
-        contextWindow !== state.meta.contextWindow
-      ) {
-        updateMeta({ contextWindow });
-      }
-
-      if (state.interruptRequested) {
-        settle({ _tag: "Interrupted", partialText: partialText() });
-      } else if (result.subtype === "success") {
-        settle({
-          _tag: "Completed",
-          finalText: result.result.trim() || state.currentText,
-        });
-      } else {
-        const details =
-          result.errors.filter((error) => error.trim()).join("\n") ||
-          result.stop_reason ||
-          `Claude Code ended with ${result.subtype}`;
-        settle({
-          _tag: "Failed",
-          errorText: boundedError(details),
-          partialText: partialText(),
-        });
-      }
-    };
-
-    const handleMessage = (message: SDKMessage) => {
-      if (state.closed) return;
-      // A queued steer's turn normally announces itself with a repeated
-      // system/init, but any turn activity is an equally valid begin signal —
-      // without this, a missed init would stream events into a "done" run
-      // that could then never settle.
-      if (
-        message.type === "stream_event" ||
-        message.type === "assistant" ||
-        message.type === "result"
-      ) {
-        beginQueuedRunIfNeeded();
-      }
-      if (message.type === "system" && message.subtype === "init") {
-        beginQueuedRunIfNeeded();
-        updateMeta({
-          modelLabel: message.model,
-          nativeSessionId: message.session_id,
-          sessionFilePath: sessionFilePath(message.cwd, message.session_id),
-          contextWindow: CLAUDE_CONTEXT_WINDOW,
-        });
-      } else if (message.type === "stream_event") {
-        if (message.parent_tool_use_id !== null) return;
-        if (message.event.type === "message_start") {
-          state.responseSequence++;
-          clearConsumedSteers();
-        } else if (message.event.type === "content_block_delta") {
-          const delta = message.event.delta;
-          if (delta.type === "text_delta") {
-            state.liveText += delta.text;
-            emit({ _tag: "AssistantDelta", kind: "text", delta: delta.text });
-          } else if (delta.type === "thinking_delta") {
-            emit({
-              _tag: "AssistantDelta",
-              kind: "thinking",
-              delta: delta.thinking,
-            });
-          }
-        }
-      } else if (message.type === "assistant") {
-        handleAssistant(message);
-      } else if (message.type === "user") {
-        handleUser(message);
-      } else if (message.type === "result") {
-        handleResult(message);
-      }
-    };
-
-    const pump = async () => {
-      let failure: string | undefined;
-      try {
-        for await (const message of nativeQuery) handleMessage(message);
-      } catch (error) {
-        if (!state.closed && !abortController.signal.aborted) {
-          failure = boundedError(error);
-        }
-      } finally {
-        if (!state.closed) {
-          if (state.activeRun) {
-            settle(
-              state.interruptRequested
-                ? { _tag: "Interrupted", partialText: partialText() }
-                : {
-                    _tag: "Failed",
-                    errorText:
-                      failure ?? "Claude Code query ended unexpectedly",
-                    partialText: partialText(),
-                  },
-            );
-          } else if (failure) {
-            emit({ _tag: "BackendError", message: failure });
-          }
-          state.closed = true;
-          Queue.endUnsafe(events);
-        }
-        resolvePumpDone?.();
-      }
-    };
-
-    yield* Effect.addFinalizer(() =>
-      Effect.promise(async () => {
-        // Settle before marking closed: the pump's finally skips settlement
-        // once closed, and every run must end in a RunSettled even when the
-        // scope closes mid-run.
-        if (state.activeRun) {
-          settle({ _tag: "Interrupted", partialText: partialText() });
-        }
-        state.closed = true;
-        input.end();
-        abortController.abort();
-        nativeQuery.close();
-        await waitBounded(pumpDone, INTERRUPT_TIMEOUT_MS);
-        Queue.endUnsafe(events);
-      }),
-    );
-
-    void pump();
-
-    const submit = (text: string) => {
-      const wasActive = state.activeRun;
-      const message = input.push(text);
-      if (!message) return false;
-      if (!wasActive) {
-        state.activeRun = true;
-        state.runVersion++;
-        state.currentText = "";
-        state.liveText = "";
-      }
-      state.submittedUuids.add(message.uuid ?? "");
-      // Idle restarts flip status synchronously (like pi's startRun); a steer
-      // into an active run must NOT re-emit RunStarted — its own turn begins
-      // later via beginQueuedRunIfNeeded.
-      if (!wasActive) emit({ _tag: "RunStarted" });
-      emit({ _tag: "UserMessage", text });
-      if (wasActive) {
-        state.queued.push({
-          text,
-          kind: "steer",
-          uuid: message.uuid ?? "",
-          afterResponse: state.responseSequence,
-        });
-        emit({ _tag: "QueueChanged", queued: queuedView() });
-      }
-      return true;
-    };
-
-    const waitForVersion = (version: number) => {
-      if (state.lastSettledVersion >= version) return Promise.resolve();
-      return new Promise<void>((resolve) => {
-        const waiter = () => {
-          if (state.lastSettledVersion < version && !state.closed) return;
-          state.settleWaiters.delete(waiter);
-          resolve();
-        };
-        state.settleWaiters.add(waiter);
-      });
-    };
-
-    emit({ _tag: "MetaChanged", meta: state.meta });
-    submit(task.prompt);
-
-    return {
-      meta: Effect.sync(() => state.meta),
-      events: Stream.fromQueue(events),
-      send: (text) =>
-        Effect.suspend((): Effect.Effect<void, SendError> => {
-          if (state.closed) {
-            return new SendError({ message: "Subagent session is closed." });
-          }
-          return submit(text)
-            ? Effect.void
-            : new SendError({ message: "Subagent session is closed." });
-        }),
-      interrupt: Effect.promise(async () => {
-        if (state.closed || !state.activeRun) return;
-        const version = state.runVersion;
-        state.interruptRequested = true;
-        input.clear();
-        state.queued = [];
-        emit({ _tag: "QueueChanged", queued: [] });
-
-        const interruptAndSettle = (async () => {
-          try {
-            const receipt = await nativeQuery.interrupt();
-            const hasOwnQueuedMessage = receipt?.still_queued?.some((uuid) =>
-              state.submittedUuids.has(uuid),
-            );
-            if (hasOwnQueuedMessage) {
-              // 0.3.207 exposes cancellation receipts but no public per-message
-              // cancel method. Closing is the only way to prevent a cancelled
-              // queued prompt from immediately starting another turn.
-              input.end();
-              nativeQuery.close();
-            }
-          } catch (error) {
-            if (!state.closed) {
-              emit({ _tag: "BackendError", message: boundedError(error) });
-            }
-          }
-          await waitForVersion(version);
-        })();
-
-        await waitBounded(interruptAndSettle, INTERRUPT_TIMEOUT_MS);
-        if (!state.closed && state.activeRun && state.runVersion === version) {
-          // Covers pre-init/pending races and SDK versions that acknowledge an
-          // interrupt without delivering a result. Force-close after settling
-          // so a late native result cannot resurrect or re-settle this run.
-          settle({ _tag: "Interrupted", partialText: partialText() });
-          state.closed = true;
-          input.end();
-          abortController.abort();
-          nativeQuery.close();
-          Queue.endUnsafe(events);
-        }
-      }),
-    } satisfies SubagentSession;
-  });
-
-// --- Backend -----------------------------------------------------------------
-
-export const claudeBackend: SubagentBackend = {
-  name: "claude",
-  capabilities: { steering: true, modelSelection: true, reasoningEffort: true },
-  available: Effect.sync(() => resolveClaudeBinary() !== undefined),
-  spawn: makeClaudeSession,
-};
+/**
+ * Claude Code backend — real implementation over the Claude Agent SDK.
+ *
+ * One SDK `query()` and one streaming-input bridge live for the whole scoped
+ * session. User sends are pushed into that bridge, while the query iterator is
+ * pumped in the background and translated to normalized SubagentEvents. The
+ * CLI therefore owns conversation continuity, tool execution, and persisted
+ * `~/.claude/projects` transcripts; this file only owns lifecycle guarantees
+ * and the normalized view consumed by the manager.
+ */
+
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+  query,
+  type SDKAssistantMessage,
+  type SDKMessage,
+  type SDKResultMessage,
+  type SDKUserMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import type { Cause, Scope } from "effect";
+import { Effect, Queue, Stream } from "effect";
+import type { SubagentBackend, SubagentSession } from "../backend.ts";
+import type {
+  QueuedMessage,
+  ReasoningEffort,
+  RunOutcome,
+  SpawnTask,
+  SubagentEvent,
+  SubagentMeta,
+  TranscriptPart,
+} from "../domain.ts";
+import { SendError, SpawnError } from "../domain.ts";
+
+const CLAUDE_CONTEXT_WINDOW = 200_000;
+const INTERRUPT_TIMEOUT_MS = 2_000;
+const PREVIEW_MAX_LENGTH = 4_096;
+
+// --- Binary resolution --------------------------------------------------------
+
+let cachedClaudeBinary: string | null | undefined;
+
+function executable(file: string) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the Claude Code CLI once from PATH. The SDK can also run without
+ * this (it bundles a CLI), but pointing it at the user's installed binary
+ * keeps versions, settings, and login state consistent with their terminal.
+ */
+function resolveClaudeBinary() {
+  if (cachedClaudeBinary !== undefined) return cachedClaudeBinary ?? undefined;
+  const names =
+    process.platform === "win32"
+      ? ["claude.exe", "claude.cmd", "claude"]
+      : ["claude"];
+  for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+    if (!directory) continue;
+    for (const name of names) {
+      const candidate = path.join(directory, name);
+      if (executable(candidate)) {
+        cachedClaudeBinary = candidate;
+        return candidate;
+      }
+    }
+  }
+  cachedClaudeBinary = null;
+  return undefined;
+}
+
+// --- Streaming input ---------------------------------------------------------
+
+/** A single-consumer push queue adapted to the SDK's AsyncIterable input. */
+class ClaudeInput implements AsyncIterable<SDKUserMessage> {
+  private pending: SDKUserMessage[] = [];
+  private waiter:
+    ((result: IteratorResult<SDKUserMessage>) => void) | undefined;
+  private closed = false;
+
+  push(text: string) {
+    if (this.closed) return undefined;
+    const message: SDKUserMessage = {
+      type: "user",
+      message: { role: "user", content: text },
+      parent_tool_use_id: null,
+      // Stamped UUIDs make queued messages visible in interrupt receipts.
+      uuid: randomUUID(),
+    };
+    const waiter = this.waiter;
+    if (waiter) {
+      this.waiter = undefined;
+      waiter({ value: message, done: false });
+    } else {
+      this.pending.push(message);
+    }
+    return message;
+  }
+
+  clear() {
+    return this.pending.splice(0);
+  }
+
+  end() {
+    if (this.closed) return;
+    this.closed = true;
+    const waiter = this.waiter;
+    this.waiter = undefined;
+    waiter?.({ value: undefined, done: true });
+  }
+
+  async *[Symbol.asyncIterator]() {
+    while (true) {
+      const message = this.pending.shift();
+      if (message) {
+        yield message;
+        continue;
+      }
+      if (this.closed) return;
+      const next = await new Promise<IteratorResult<SDKUserMessage>>(
+        (resolve) => {
+          this.waiter = resolve;
+        },
+      );
+      if (next.done) return;
+      yield next.value;
+    }
+  }
+}
+
+// --- Model, effort, and transcript helpers ----------------------------------
+
+/**
+ * Claude's deprecated-but-supported maxThinkingTokens is the closest match to
+ * the shared numeric scale requested by this extension. Zero explicitly
+ * disables extended thinking in SDK 0.3.207; an omitted effort leaves the CLI
+ * default untouched.
+ */
+const THINKING_BUDGETS = {
+  off: 0,
+  minimal: 1_024,
+  low: 4_096,
+  medium: 10_000,
+  high: 16_000,
+  xhigh: 32_000,
+  max: 63_999,
+} satisfies Record<ReasoningEffort, number>;
+
+function boundedError(error: unknown) {
+  return (error instanceof Error ? error.message : String(error)).slice(
+    0,
+    4_096,
+  );
+}
+
+function singleLine(text: string) {
+  const flattened = text.replace(/\s+/g, " ").trim();
+  return flattened ? flattened.slice(0, PREVIEW_MAX_LENGTH) : undefined;
+}
+
+function safeJson(value: unknown) {
+  try {
+    const text = JSON.stringify(value);
+    if (!text || text === "{}") return undefined;
+    return singleLine(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function outputPreview(value: unknown): string | undefined {
+  if (typeof value === "string") return singleLine(value);
+  if (Array.isArray(value)) {
+    const text = value
+      .flatMap((part) => {
+        if (!part || typeof part !== "object") return [];
+        const record = part as { type?: unknown; text?: unknown };
+        return record.type === "text" && typeof record.text === "string"
+          ? [record.text]
+          : [];
+      })
+      .join(" ");
+    return singleLine(text) ?? safeJson(value);
+  }
+  return safeJson(value);
+}
+
+function assistantParts(message: SDKAssistantMessage): TranscriptPart[] {
+  const parts: TranscriptPart[] = [];
+  for (const block of message.message.content) {
+    if (block.type === "text") {
+      parts.push({ type: "text", text: block.text });
+    } else if (block.type === "thinking") {
+      parts.push({ type: "thinking", text: block.thinking });
+    } else if (block.type === "redacted_thinking") {
+      parts.push({ type: "thinking", text: "", redacted: true });
+    } else if (block.type === "tool_use") {
+      parts.push({
+        type: "toolCall",
+        toolId: block.id,
+        name: block.name,
+        argsPreview: safeJson(block.input),
+      });
+    }
+  }
+  return parts;
+}
+
+/** Claude Code's project-directory escaping, verified against CLI 2.1.207. */
+function sessionFilePath(cwd: string, sessionId: string) {
+  const projectDirectory = cwd.replace(/[/.]/g, "-");
+  return path.join(
+    os.homedir(),
+    ".claude",
+    "projects",
+    projectDirectory,
+    `${sessionId}.jsonl`,
+  );
+}
+
+/**
+ * Context occupancy after one API request. An assistant message's `usage`
+ * describes only that request: the full prompt (fresh + cache-read +
+ * cache-written input) plus this response's output — exactly what now sits
+ * in the context window. The result message's `usage` instead sums these
+ * per-request counts across the whole run, so a multi-request turn
+ * re-counts cached context once per request and quickly exceeds the real
+ * window; it must never be treated as occupancy.
+ */
+export function contextOccupancyTokens(
+  usage:
+    | {
+        input_tokens?: number | null;
+        cache_read_input_tokens?: number | null;
+        cache_creation_input_tokens?: number | null;
+        output_tokens?: number | null;
+      }
+    | null
+    | undefined,
+) {
+  if (!usage || typeof usage.input_tokens !== "number") return undefined;
+  const count = (value: number | null | undefined) =>
+    typeof value === "number" && Number.isFinite(value) ? value : 0;
+  return (
+    count(usage.input_tokens) +
+    count(usage.cache_read_input_tokens) +
+    count(usage.cache_creation_input_tokens) +
+    count(usage.output_tokens)
+  );
+}
+
+function resultContextWindow(result: SDKResultMessage) {
+  return Object.values(result.modelUsage)[0]?.contextWindow;
+}
+
+function waitBounded(operation: Promise<unknown>, timeoutMs: number) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, timeoutMs);
+  });
+  return Promise.race([
+    operation.then(
+      () => undefined,
+      () => undefined,
+    ),
+    timeout,
+  ]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+
+// --- The session -------------------------------------------------------------
+
+interface NativeQueuedMessage extends QueuedMessage {
+  readonly uuid: string;
+  /** Raw response sequence after which this steer can be consumed. */
+  readonly afterResponse: number;
+}
+
+const makeClaudeSession = (
+  task: SpawnTask,
+): Effect.Effect<SubagentSession, SpawnError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const input = new ClaudeInput();
+    const abortController = new AbortController();
+    const events = yield* Queue.make<SubagentEvent, Cause.Done>();
+    const emit = (event: SubagentEvent) => {
+      Queue.offerUnsafe(events, event);
+    };
+
+    const state = {
+      closed: false,
+      activeRun: false,
+      interruptRequested: false,
+      runVersion: 0,
+      lastSettledVersion: 0,
+      responseSequence: 0,
+      queued: [] as NativeQueuedMessage[],
+      submittedUuids: new Set<string>(),
+      currentText: "",
+      liveText: "",
+      tools: new Map<string, string>(),
+      settleWaiters: new Set<() => void>(),
+      meta: {
+        backend: "claude",
+        modelLabel: task.model,
+        // Claude models used by this backend currently expose 200k context;
+        // result.modelUsage replaces this fallback when the CLI knows better.
+        contextWindow: CLAUDE_CONTEXT_WINDOW,
+      } satisfies SubagentMeta as SubagentMeta,
+    };
+
+    const thinkingBudget = task.reasoningEffort
+      ? THINKING_BUDGETS[task.reasoningEffort]
+      : undefined;
+    const claudeBinary = resolveClaudeBinary();
+    const nativeQuery = yield* Effect.try({
+      try: () =>
+        query({
+          prompt: input,
+          options: {
+            cwd: task.cwd,
+            // Headless children cannot answer approval prompts. The caller
+            // already chose to launch an autonomous subagent, so let it use
+            // its tools without interactive permission checks.
+            permissionMode: "bypassPermissions",
+            allowDangerouslySkipPermissions: true,
+            // Keep child orchestration inside this extension's global manager
+            // and concurrency cap rather than Claude Code's native subagents.
+            disallowedTools: ["Agent", "Task"],
+            // For cwds pi marked untrusted, restrict to user-level settings so
+            // an untrusted project's config cannot reconfigure the child.
+            ...(task.parent.projectTrusted
+              ? {}
+              : { settingSources: ["user" as const] }),
+            includePartialMessages: true,
+            abortController,
+            ...(claudeBinary
+              ? { pathToClaudeCodeExecutable: claudeBinary }
+              : {}),
+            ...(task.model ? { model: task.model } : {}),
+            ...(thinkingBudget !== undefined
+              ? { maxThinkingTokens: thinkingBudget }
+              : {}),
+          },
+        }),
+      catch: (error) => new SpawnError({ message: boundedError(error) }),
+    });
+
+    let resolvePumpDone: (() => void) | undefined;
+    const pumpDone = new Promise<void>((resolve) => {
+      resolvePumpDone = resolve;
+    });
+
+    const queuedView = (): ReadonlyArray<QueuedMessage> =>
+      state.queued.map(({ text, kind }) => ({ text, kind }));
+
+    const notifySettled = () => {
+      for (const waiter of state.settleWaiters) waiter();
+      state.settleWaiters.clear();
+    };
+
+    const partialText = () => state.liveText || state.currentText || undefined;
+
+    const settle = (outcome: RunOutcome) => {
+      if (!state.activeRun) return;
+      emit({ _tag: "RunSettled", outcome });
+      state.activeRun = false;
+      state.lastSettledVersion = state.runVersion;
+      state.interruptRequested = false;
+      state.liveText = "";
+      notifySettled();
+    };
+
+    const updateMeta = (patch: Partial<SubagentMeta>) => {
+      state.meta = { ...state.meta, ...patch };
+      emit({ _tag: "MetaChanged", meta: patch });
+    };
+
+    const beginQueuedRunIfNeeded = () => {
+      if (state.activeRun || state.queued.length === 0) return;
+      // A steer arriving too late for the prior turn becomes a fresh queued
+      // turn. The repeated init is the first reliable signal that it started.
+      state.activeRun = true;
+      state.runVersion++;
+      state.currentText = "";
+      state.liveText = "";
+      emit({ _tag: "RunStarted" });
+    };
+
+    const clearConsumedSteers = () => {
+      const remaining = state.queued.filter(
+        (message) => message.afterResponse >= state.responseSequence,
+      );
+      if (remaining.length === state.queued.length) return;
+      state.queued = remaining;
+      emit({ _tag: "QueueChanged", queued: queuedView() });
+    };
+
+    const handleAssistant = (message: SDKAssistantMessage) => {
+      const parts = assistantParts(message);
+      if (parts.length > 0) emit({ _tag: "AssistantMessage", parts });
+
+      // Top-level messages only: subagent (sidechain) requests have their own
+      // context and must not overwrite this conversation's occupancy.
+      if (message.parent_tool_use_id == null) {
+        const tokens = contextOccupancyTokens(message.message.usage);
+        if (tokens !== undefined) emit({ _tag: "UsageChanged", tokens });
+      }
+
+      const text = message.message.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n")
+        .trim();
+      if (text) state.currentText = text;
+      state.liveText = "";
+
+      if (message.message.model !== state.meta.modelLabel) {
+        updateMeta({ modelLabel: message.message.model });
+      }
+      for (const block of message.message.content) {
+        if (block.type !== "tool_use") continue;
+        state.tools.set(block.id, block.name);
+        emit({
+          _tag: "ToolStart",
+          toolId: block.id,
+          name: block.name,
+          argsPreview: safeJson(block.input),
+        });
+      }
+    };
+
+    const handleUser = (message: SDKUserMessage) => {
+      const content = message.message.content;
+      if (!Array.isArray(content)) return;
+      for (const block of content) {
+        if (block.type !== "tool_result") continue;
+        const name = state.tools.get(block.tool_use_id) ?? "Tool";
+        state.tools.delete(block.tool_use_id);
+        emit({
+          _tag: "ToolEnd",
+          toolId: block.tool_use_id,
+          name,
+          isError: block.is_error ?? false,
+          outputPreview: outputPreview(block.content),
+        });
+      }
+      // External prompts are emitted synchronously by submit(); ignoring text
+      // here prevents a future CLI echo from duplicating the transcript row.
+    };
+
+    const handleResult = (result: SDKResultMessage) => {
+      // result.usage is a whole-run aggregate, not occupancy (see
+      // contextOccupancyTokens); only the capacity is trustworthy here. The
+      // occupancy itself was already emitted by the last assistant message.
+      const contextWindow = resultContextWindow(result);
+      emit({
+        _tag: "UsageChanged",
+        contextWindow: contextWindow ?? state.meta.contextWindow,
+      });
+      if (
+        contextWindow !== undefined &&
+        contextWindow !== state.meta.contextWindow
+      ) {
+        updateMeta({ contextWindow });
+      }
+
+      if (state.interruptRequested) {
+        settle({ _tag: "Interrupted", partialText: partialText() });
+      } else if (result.subtype === "success") {
+        settle({
+          _tag: "Completed",
+          finalText: result.result.trim() || state.currentText,
+        });
+      } else {
+        const details =
+          result.errors.filter((error) => error.trim()).join("\n") ||
+          result.stop_reason ||
+          `Claude Code ended with ${result.subtype}`;
+        settle({
+          _tag: "Failed",
+          errorText: boundedError(details),
+          partialText: partialText(),
+        });
+      }
+    };
+
+    const handleMessage = (message: SDKMessage) => {
+      if (state.closed) return;
+      // A queued steer's turn normally announces itself with a repeated
+      // system/init, but any turn activity is an equally valid begin signal —
+      // without this, a missed init would stream events into a "done" run
+      // that could then never settle.
+      if (
+        message.type === "stream_event" ||
+        message.type === "assistant" ||
+        message.type === "result"
+      ) {
+        beginQueuedRunIfNeeded();
+      }
+      if (message.type === "system" && message.subtype === "init") {
+        beginQueuedRunIfNeeded();
+        updateMeta({
+          modelLabel: message.model,
+          nativeSessionId: message.session_id,
+          sessionFilePath: sessionFilePath(message.cwd, message.session_id),
+          contextWindow: CLAUDE_CONTEXT_WINDOW,
+        });
+      } else if (message.type === "stream_event") {
+        if (message.parent_tool_use_id !== null) return;
+        if (message.event.type === "message_start") {
+          state.responseSequence++;
+          clearConsumedSteers();
+        } else if (message.event.type === "content_block_delta") {
+          const delta = message.event.delta;
+          if (delta.type === "text_delta") {
+            state.liveText += delta.text;
+            emit({ _tag: "AssistantDelta", kind: "text", delta: delta.text });
+          } else if (delta.type === "thinking_delta") {
+            emit({
+              _tag: "AssistantDelta",
+              kind: "thinking",
+              delta: delta.thinking,
+            });
+          }
+        }
+      } else if (message.type === "assistant") {
+        handleAssistant(message);
+      } else if (message.type === "user") {
+        handleUser(message);
+      } else if (message.type === "result") {
+        handleResult(message);
+      }
+    };
+
+    const pump = async () => {
+      let failure: string | undefined;
+      try {
+        for await (const message of nativeQuery) handleMessage(message);
+      } catch (error) {
+        if (!state.closed && !abortController.signal.aborted) {
+          failure = boundedError(error);
+        }
+      } finally {
+        if (!state.closed) {
+          if (state.activeRun) {
+            settle(
+              state.interruptRequested
+                ? { _tag: "Interrupted", partialText: partialText() }
+                : {
+                    _tag: "Failed",
+                    errorText:
+                      failure ?? "Claude Code query ended unexpectedly",
+                    partialText: partialText(),
+                  },
+            );
+          } else if (failure) {
+            emit({ _tag: "BackendError", message: failure });
+          }
+          state.closed = true;
+          Queue.endUnsafe(events);
+        }
+        resolvePumpDone?.();
+      }
+    };
+
+    yield* Effect.addFinalizer(() =>
+      Effect.promise(async () => {
+        // Settle before marking closed: the pump's finally skips settlement
+        // once closed, and every run must end in a RunSettled even when the
+        // scope closes mid-run.
+        if (state.activeRun) {
+          settle({ _tag: "Interrupted", partialText: partialText() });
+        }
+        state.closed = true;
+        input.end();
+        abortController.abort();
+        nativeQuery.close();
+        await waitBounded(pumpDone, INTERRUPT_TIMEOUT_MS);
+        Queue.endUnsafe(events);
+      }),
+    );
+
+    void pump();
+
+    const submit = (text: string) => {
+      const wasActive = state.activeRun;
+      const message = input.push(text);
+      if (!message) return false;
+      if (!wasActive) {
+        state.activeRun = true;
+        state.runVersion++;
+        state.currentText = "";
+        state.liveText = "";
+      }
+      state.submittedUuids.add(message.uuid ?? "");
+      // Idle restarts flip status synchronously (like pi's startRun); a steer
+      // into an active run must NOT re-emit RunStarted — its own turn begins
+      // later via beginQueuedRunIfNeeded.
+      if (!wasActive) emit({ _tag: "RunStarted" });
+      emit({ _tag: "UserMessage", text });
+      if (wasActive) {
+        state.queued.push({
+          text,
+          kind: "steer",
+          uuid: message.uuid ?? "",
+          afterResponse: state.responseSequence,
+        });
+        emit({ _tag: "QueueChanged", queued: queuedView() });
+      }
+      return true;
+    };
+
+    const waitForVersion = (version: number) => {
+      if (state.lastSettledVersion >= version) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        const waiter = () => {
+          if (state.lastSettledVersion < version && !state.closed) return;
+          state.settleWaiters.delete(waiter);
+          resolve();
+        };
+        state.settleWaiters.add(waiter);
+      });
+    };
+
+    emit({ _tag: "MetaChanged", meta: state.meta });
+    submit(task.prompt);
+
+    return {
+      meta: Effect.sync(() => state.meta),
+      events: Stream.fromQueue(events),
+      send: (text) =>
+        Effect.suspend((): Effect.Effect<void, SendError> => {
+          if (state.closed) {
+            return new SendError({ message: "Subagent session is closed." });
+          }
+          return submit(text)
+            ? Effect.void
+            : new SendError({ message: "Subagent session is closed." });
+        }),
+      interrupt: Effect.promise(async () => {
+        if (state.closed || !state.activeRun) return;
+        const version = state.runVersion;
+        state.interruptRequested = true;
+        input.clear();
+        state.queued = [];
+        emit({ _tag: "QueueChanged", queued: [] });
+
+        const interruptAndSettle = (async () => {
+          try {
+            const receipt = await nativeQuery.interrupt();
+            const hasOwnQueuedMessage = receipt?.still_queued?.some((uuid) =>
+              state.submittedUuids.has(uuid),
+            );
+            if (hasOwnQueuedMessage) {
+              // 0.3.207 exposes cancellation receipts but no public per-message
+              // cancel method. Closing is the only way to prevent a cancelled
+              // queued prompt from immediately starting another turn.
+              input.end();
+              nativeQuery.close();
+            }
+          } catch (error) {
+            if (!state.closed) {
+              emit({ _tag: "BackendError", message: boundedError(error) });
+            }
+          }
+          await waitForVersion(version);
+        })();
+
+        await waitBounded(interruptAndSettle, INTERRUPT_TIMEOUT_MS);
+        if (!state.closed && state.activeRun && state.runVersion === version) {
+          // Covers pre-init/pending races and SDK versions that acknowledge an
+          // interrupt without delivering a result. Force-close after settling
+          // so a late native result cannot resurrect or re-settle this run.
+          settle({ _tag: "Interrupted", partialText: partialText() });
+          state.closed = true;
+          input.end();
+          abortController.abort();
+          nativeQuery.close();
+          Queue.endUnsafe(events);
+        }
+      }),
+    } satisfies SubagentSession;
+  });
+
+// --- Backend -----------------------------------------------------------------
+
+export const claudeBackend: SubagentBackend = {
+  name: "claude",
+  capabilities: { steering: true, modelSelection: true, reasoningEffort: true },
+  available: Effect.sync(() => resolveClaudeBinary() !== undefined),
+  spawn: makeClaudeSession,
+};