@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/server/claude-slash-commands.ts

@@ -0,0 +1,234 @@
+/**
+ * Standalone slash-commands loader helpers for AgentCoordinator.
+ *
+ * Extracted from agent.ts so the slash-command loading logic lives in its
+ * own testable module. The coordinator delegates to these functions by passing
+ * an object literal that satisfies `SlashCommandsDeps`.
+ *
+ * Side-effect seal: this module contains NO direct IO (no node:fs, no HTTP
+ * calls, no Bun primitives). Every effectful operation is injected through
+ * the deps interface.
+ */
+
+import type { SlashCommand, Subagent, McpServerConfig, ClaudeDriverPreference } from "../shared/types"
+import { resolveClaudeApiModelId } from "../shared/types"
+import type { ClaudeSessionHandle, HarnessToolRequest } from "./harness-types"
+import type { StartClaudeSessionPtyArgs } from "./claude-pty/driver"
+import { log } from "../shared/log"
+import { buildKannaSystemPromptAppend } from "../shared/kanna-system-prompt"
+import { maskOauthKey } from "../shared/mask-oauth-key"
+import { normalizeClaudeModelOptions, normalizeServerModel } from "./provider-catalog"
+import type { AnyValue } from "../shared/errors"
+
+// ---------------------------------------------------------------------------
+// Structural sub-interfaces — only the operations this module calls.
+// ---------------------------------------------------------------------------
+
+/** Subset of EventStore used by the slash-commands loader. */
+interface SlashCommandsStore {
+  getChat(id: string):
+    | {
+        provider: string | null
+        slashCommands?: SlashCommand[] | null
+        planMode?: boolean | null
+        projectId: string
+        sessionTokensByProvider: { claude?: string | null }
+      }
+    | null
+    | undefined
+  getProject(id: string): { id: string; localPath: string } | null | undefined
+  recordSessionCommandsLoaded(chatId: string, commands: SlashCommand[]): Promise<void>
+}
+
+/** Subset of the active Claude sessions map. */
+interface SlashCommandsSessionEntry {
+  session: { getSupportedCommands(): Promise<SlashCommand[]> }
+}
+
+/** Subset of OAuthTokenPool used by the slash-commands loader. */
+interface SlashCommandsOAuthPool {
+  pickEphemeral(): { token: { id: string; token: string; label: string }; release(): void } | null
+  hasAnyToken(): boolean
+  markUsed(id: string): void
+}
+
+/** Subset of LocalCatalogService used by mergeLocalCatalog. */
+interface SlashCommandsLocalCatalog {
+  list(cwd: string): SlashCommand[]
+}
+
+/** Minimal SDK session starter (only the args ensureSlashCommandsLoaded passes). */
+type SlashCommandsSDKStarter = (args: {
+  projectId: string
+  localPath: string
+  model: string
+  effort?: string
+  planMode: boolean
+  sessionToken: string | null
+  forkSession: boolean
+  oauthToken: string | null
+  onToolRequest: (request: HarnessToolRequest) => Promise<AnyValue>
+  systemPromptAppend?: string
+  customMcpServers?: readonly McpServerConfig[]
+}) => Promise<ClaudeSessionHandle>
+
+// ---------------------------------------------------------------------------
+// Dependency bundle injected by AgentCoordinator
+// ---------------------------------------------------------------------------
+
+export interface SlashCommandsDeps {
+  store: SlashCommandsStore
+  claudeSessions: { get(chatId: string): SlashCommandsSessionEntry | undefined }
+  oauthPool: SlashCommandsOAuthPool | null
+  /** Mutable set of chatIds whose slash-command fetch is currently in-flight. */
+  slashCommandsInFlight: Set<string>
+  emitStateChange: (chatId: string) => void
+  resolveClaudeDriverPreference: () => ClaudeDriverPreference
+  startClaudeSessionPTY: (args: StartClaudeSessionPtyArgs) => Promise<ClaudeSessionHandle>
+  startClaudeSessionSDK: SlashCommandsSDKStarter
+  getSubagents: () => Subagent[]
+  getGlobalPromptAppend: () => string | undefined
+  getEnabledCustomMcpServers: () => readonly McpServerConfig[]
+  claudePtyRegistry:
+    | import("./claude-pty/pid-registry.adapter").ClaudePtyRegistry
+    | null
+    | undefined
+  ptyInstanceRegistry:
+    | import("./claude-pty/pty-instance-registry").PtyInstanceRegistry
+    | null
+    | undefined
+  workflowRegistry: import("./workflow-registry").WorkflowRegistry | null | undefined
+  subagentTranscriptRegistry:
+    | import("./subagent-transcript-registry").SubagentTranscriptRegistry
+    | null
+    | undefined
+  localCatalog: SlashCommandsLocalCatalog | null
+}
+
+// ---------------------------------------------------------------------------
+// Exported functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the slash-command catalog for a chat session (no-op if already loaded
+ * or a load is in-flight). Spawns an ephemeral Claude session if the chat has
+ * no active session, reuses the existing one if it does.
+ */
+export async function ensureSlashCommandsLoaded(
+  deps: SlashCommandsDeps,
+  chatId: string,
+): Promise<void> {
+  const chat = deps.store.getChat(chatId)
+  if (!chat) return
+  if (chat.provider === "codex") return
+  if (chat.slashCommands && chat.slashCommands.length > 0) return
+  if (deps.slashCommandsInFlight.has(chatId)) return
+
+  const project = deps.store.getProject(chat.projectId)
+  if (!project) return
+
+  deps.slashCommandsInFlight.add(chatId)
+  deps.emitStateChange(chatId)
+  try {
+    let commands: SlashCommand[]
+    const existing = deps.claudeSessions.get(chatId)
+    if (existing) {
+      commands = await existing.session.getSupportedCommands()
+    } else {
+      const defaultModel = normalizeServerModel("claude")
+      const defaultOptions = normalizeClaudeModelOptions(defaultModel)
+      // Ephemeral spawn: reserve under a synthetic key so two concurrent
+      // ensureSlashCommandsLoaded calls (different chats) cannot be handed
+      // the same token by lastUsedAt ordering. The lease MUST be released
+      // once the throwaway session closes (audit #2).
+      const lease = deps.oauthPool?.pickEphemeral() ?? null
+      // Skip the ephemeral spawn entirely when the pool has tokens but
+      // nothing is usable — avoids 401 against the CLI's keychain fallback
+      // and an opaque "supportedCommands failed" warning. Slash commands
+      // will load on the next turn once a token is available.
+      if (deps.oauthPool && deps.oauthPool.hasAnyToken() && !lease) {
+        return
+      }
+      const picked = lease?.token ?? null
+      if (picked) deps.oauthPool!.markUsed(picked.id)
+      const usePtyEphemeral = deps.resolveClaudeDriverPreference() === "pty"
+      const ephemeralSystemPromptAppend = buildKannaSystemPromptAppend(deps.getSubagents(), {
+        globalPromptAppend: deps.getGlobalPromptAppend(),
+      })
+      try {
+        const ephemeral = usePtyEphemeral
+          ? await deps.startClaudeSessionPTY({
+              chatId,
+              projectId: project.id,
+              localPath: project.localPath,
+              model: resolveClaudeApiModelId(defaultModel, defaultOptions.contextWindow),
+              effort: defaultOptions.reasoningEffort,
+              planMode: chat.planMode ?? false,
+              sessionToken: chat.sessionTokensByProvider.claude ?? null,
+              forkSession: false,
+              oauthToken: picked?.token ?? null,
+              oauthLabel: picked?.label,
+              oauthKeyMasked: picked ? maskOauthKey(picked.token) : undefined,
+              onToolRequest: async () => null,
+              systemPromptAppend: ephemeralSystemPromptAppend,
+              ptyRegistry: deps.claudePtyRegistry ?? undefined,
+              ptyInstanceRegistry: deps.ptyInstanceRegistry ?? undefined,
+              workflowRegistry: deps.workflowRegistry ?? undefined,
+              subagentTranscriptRegistry: deps.subagentTranscriptRegistry ?? undefined,
+              customMcpServers: deps.getEnabledCustomMcpServers(),
+            })
+          : await deps.startClaudeSessionSDK({
+              projectId: project.id,
+              localPath: project.localPath,
+              model: resolveClaudeApiModelId(defaultModel, defaultOptions.contextWindow),
+              effort: defaultOptions.reasoningEffort,
+              planMode: chat.planMode ?? false,
+              sessionToken: chat.sessionTokensByProvider.claude ?? null,
+              forkSession: false,
+              oauthToken: picked?.token ?? null,
+              onToolRequest: async () => null,
+              systemPromptAppend: ephemeralSystemPromptAppend,
+              customMcpServers: deps.getEnabledCustomMcpServers(),
+            })
+        try {
+          commands = await ephemeral.getSupportedCommands()
+        } finally {
+          ephemeral.close()
+        }
+      } finally {
+        lease?.release()
+      }
+    }
+    const merged = mergeLocalCatalog(deps, commands, project.localPath)
+    await deps.store.recordSessionCommandsLoaded(chatId, merged)
+    deps.emitStateChange(chatId)
+  } catch (error) {
+    log.warn("[kanna/agent] ensureSlashCommandsLoaded failed", String(error))
+  } finally {
+    deps.slashCommandsInFlight.delete(chatId)
+    deps.emitStateChange(chatId)
+  }
+}
+
+/**
+ * Merge the local command catalog (user/project scans) into the CLI-provided
+ * commands list. CLI entries take precedence; local entries with duplicate
+ * names (case-insensitive) are filtered out.
+ */
+export function mergeLocalCatalog(
+  deps: Pick<SlashCommandsDeps, "localCatalog">,
+  commands: SlashCommand[],
+  cwd: string,
+): SlashCommand[] {
+  if (!deps.localCatalog) return commands
+  let local: SlashCommand[]
+  try {
+    local = deps.localCatalog.list(cwd)
+  } catch (error) {
+    log.warn("[kanna/agent] localCatalog.list failed", String(error))
+    return commands
+  }
+  const cliKeys = new Set(commands.map((c) => c.name.toLowerCase()))
+  const filtered = local.filter((entry) => !cliKeys.has(entry.name.toLowerCase()))
+  return [...commands, ...filtered]
+}

package/src/server/claude-spawn-helpers.test.ts

@@ -0,0 +1,221 @@
+import { describe, test, expect, mock } from "bun:test"
+import {
+  LOOP_BLOCKED_NATIVE_TOOLS,
+  buildCanUseTool,
+  buildClaudeEnv,
+  type BuildCanUseToolArgs,
+} from "./claude-spawn-helpers"
+import type { ToolCallbackService } from "./tool-callback"
+import type { AnyValue } from "../shared/errors"
+
+// ── Minimal stubs ────────────────────────────────────────────────────────────
+
+function makeArgs(overrides: Partial<BuildCanUseToolArgs> = {}): BuildCanUseToolArgs {
+  return {
+    localPath: "/tmp/test",
+    chatId: "chat-1",
+    sessionToken: "tok-1",
+    onToolRequest: async (_req) => ({ confirmed: true }),
+    ...overrides,
+  }
+}
+
+const TOOL_OPTIONS = { toolUseID: "tool-use-1", signal: new AbortController().signal }
+
+// ── LOOP_BLOCKED_NATIVE_TOOLS ────────────────────────────────────────────────
+
+describe("LOOP_BLOCKED_NATIVE_TOOLS", () => {
+  test("contains the expected blocked tool names", () => {
+    expect(LOOP_BLOCKED_NATIVE_TOOLS).toContain("Edit")
+    expect(LOOP_BLOCKED_NATIVE_TOOLS).toContain("Write")
+    expect(LOOP_BLOCKED_NATIVE_TOOLS).toContain("MultiEdit")
+    expect(LOOP_BLOCKED_NATIVE_TOOLS).toContain("NotebookEdit")
+    expect(LOOP_BLOCKED_NATIVE_TOOLS).toContain("Task")
+  })
+})
+
+// ── buildCanUseTool ──────────────────────────────────────────────────────────
+
+describe("buildCanUseTool", () => {
+  test("allows non-AskUserQuestion/ExitPlanMode tools unconditionally", async () => {
+    const canUseTool = buildCanUseTool(makeArgs())
+    const result = await canUseTool("Bash", { command: "ls" }, TOOL_OPTIONS)
+    expect(result.behavior).toBe("allow")
+  })
+
+  test("allows Read, Glob, Grep and other non-special tools", async () => {
+    const canUseTool = buildCanUseTool(makeArgs())
+    for (const tool of ["Read", "Glob", "Grep", "WebSearch"]) {
+      const result = await canUseTool(tool, {}, TOOL_OPTIONS)
+      expect(result.behavior).toBe("allow")
+    }
+  })
+
+  test("denies LOOP_BLOCKED_NATIVE_TOOLS when isLoopArmed() returns true", async () => {
+    const canUseTool = buildCanUseTool(makeArgs({ isLoopArmed: () => true }))
+    for (const tool of LOOP_BLOCKED_NATIVE_TOOLS) {
+      const result = await canUseTool(tool, {}, TOOL_OPTIONS)
+      expect(result.behavior).toBe("deny")
+      if (result.behavior === "deny") {
+        expect(result.message).toContain("autonomous loop is armed")
+      }
+    }
+  })
+
+  test("allows LOOP_BLOCKED_NATIVE_TOOLS when isLoopArmed() returns false", async () => {
+    const canUseTool = buildCanUseTool(makeArgs({ isLoopArmed: () => false }))
+    for (const tool of LOOP_BLOCKED_NATIVE_TOOLS) {
+      const result = await canUseTool(tool, {}, TOOL_OPTIONS)
+      expect(result.behavior).toBe("allow")
+    }
+  })
+
+  test("routes AskUserQuestion through legacy onToolRequest path and returns allow", async () => {
+    const onToolRequest = mock(async (_req: { tool: AnyValue }) => ({
+      answers: { q1: "yes" },
+    }))
+    const canUseTool = buildCanUseTool(makeArgs({ onToolRequest }))
+    const result = await canUseTool(
+      "AskUserQuestion",
+      { questions: [{ question: "Continue?", header: "Confirm", options: [], multiSelect: false }] },
+      TOOL_OPTIONS,
+    )
+    expect(result.behavior).toBe("allow")
+    expect(onToolRequest).toHaveBeenCalledTimes(1)
+  })
+
+  test("routes ExitPlanMode through legacy path — deny when confirmed is false", async () => {
+    const canUseTool = buildCanUseTool(
+      makeArgs({ onToolRequest: async () => ({ confirmed: false, message: "revise please" }) }),
+    )
+    const result = await canUseTool("ExitPlanMode", { plan: "the plan" }, TOOL_OPTIONS)
+    expect(result.behavior).toBe("deny")
+    if (result.behavior === "deny") {
+      expect(result.message).toContain("revise please")
+    }
+  })
+
+  test("routes ExitPlanMode through legacy path — allow when confirmed is true", async () => {
+    const canUseTool = buildCanUseTool(
+      makeArgs({ onToolRequest: async () => ({ confirmed: true }) }),
+    )
+    const result = await canUseTool("ExitPlanMode", { plan: "the plan" }, TOOL_OPTIONS)
+    expect(result.behavior).toBe("allow")
+  })
+
+  test("routes AskUserQuestion through toolCallback when KANNA_MCP_TOOL_CALLBACKS=1", async () => {
+    const originalEnv = process.env.KANNA_MCP_TOOL_CALLBACKS
+    process.env.KANNA_MCP_TOOL_CALLBACKS = "1"
+    try {
+      const toolCallback: ToolCallbackService = {
+        submit: mock(async () => ({
+          status: "answered" as const,
+          decision: {
+            kind: "allow" as const,
+            payload: { answers: { q1: "yes" }, questions: [] },
+          },
+        })),
+        answer: mock(async () => {}),
+        cancel: mock(async () => {}),
+        cancelAllForChat: mock(async () => {}),
+        recoverOnStartup: mock(async () => {}),
+      }
+      const canUseTool = buildCanUseTool(makeArgs({ toolCallback }))
+      const result = await canUseTool(
+        "AskUserQuestion",
+        { questions: [{ question: "OK?", header: "Check", options: [], multiSelect: false }] },
+        TOOL_OPTIONS,
+      )
+      expect(result.behavior).toBe("allow")
+      expect(toolCallback.submit).toHaveBeenCalledTimes(1)
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.KANNA_MCP_TOOL_CALLBACKS
+      } else {
+        process.env.KANNA_MCP_TOOL_CALLBACKS = originalEnv
+      }
+    }
+  })
+
+  test("routes ExitPlanMode through toolCallback when KANNA_MCP_TOOL_CALLBACKS=1 — deny on unconfirmed", async () => {
+    const originalEnv = process.env.KANNA_MCP_TOOL_CALLBACKS
+    process.env.KANNA_MCP_TOOL_CALLBACKS = "1"
+    try {
+      const toolCallback: ToolCallbackService = {
+        submit: mock(async () => ({
+          status: "answered" as const,
+          decision: {
+            kind: "allow" as const,
+            payload: { confirmed: false, message: "needs changes" },
+          },
+        })),
+        answer: mock(async () => {}),
+        cancel: mock(async () => {}),
+        cancelAllForChat: mock(async () => {}),
+        recoverOnStartup: mock(async () => {}),
+      }
+      const canUseTool = buildCanUseTool(makeArgs({ toolCallback }))
+      const result = await canUseTool("ExitPlanMode", { plan: "the plan" }, TOOL_OPTIONS)
+      expect(result.behavior).toBe("deny")
+      if (result.behavior === "deny") {
+        expect(result.message).toContain("needs changes")
+      }
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.KANNA_MCP_TOOL_CALLBACKS
+      } else {
+        process.env.KANNA_MCP_TOOL_CALLBACKS = originalEnv
+      }
+    }
+  })
+})
+
+// ── buildClaudeEnv ───────────────────────────────────────────────────────────
+
+describe("buildClaudeEnv", () => {
+  test("strips CLAUDECODE and CLAUDE_CODE_OAUTH_TOKEN from base env when oauthToken provided", () => {
+    const base: NodeJS.ProcessEnv = {
+      PATH: "/usr/bin",
+      CLAUDECODE: "1",
+      CLAUDE_CODE_OAUTH_TOKEN: "old-token",
+      HOME: "/home/user",
+    }
+    const result = buildClaudeEnv(base, "new-token")
+    expect(result).not.toHaveProperty("CLAUDECODE")
+    expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe("new-token")
+    expect(result.PATH).toBe("/usr/bin")
+    expect(result.HOME).toBe("/home/user")
+  })
+
+  test("injects oauthToken as CLAUDE_CODE_OAUTH_TOKEN", () => {
+    const result = buildClaudeEnv({ PATH: "/bin" }, "my-oauth-token")
+    expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe("my-oauth-token")
+  })
+
+  test("sets ANTHROPIC_BASE_URL for OpenRouter and clears ANTHROPIC_API_KEY", () => {
+    const base: NodeJS.ProcessEnv = {
+      PATH: "/usr/bin",
+      ANTHROPIC_API_KEY: "sk-ant-existing",
+      CLAUDECODE: "1",
+    }
+    const result = buildClaudeEnv(base, null, { apiKey: "sk-or-key" })
+    expect(result.ANTHROPIC_BASE_URL).toBe("https://openrouter.ai/api")
+    expect(result.ANTHROPIC_AUTH_TOKEN).toBe("sk-or-key")
+    expect(result.ANTHROPIC_API_KEY).toBe("")
+    expect(result).not.toHaveProperty("CLAUDECODE")
+  })
+
+  test("passes through non-oauth env when oauthToken is null and base has no token", () => {
+    const base: NodeJS.ProcessEnv = { PATH: "/bin", HOME: "/root" }
+    const result = buildClaudeEnv(base, null)
+    expect(result.PATH).toBe("/bin")
+    expect(result.HOME).toBe("/root")
+    expect(result).not.toHaveProperty("CLAUDE_CODE_OAUTH_TOKEN")
+  })
+
+  test("preserves existing CLAUDE_CODE_OAUTH_TOKEN from base when oauthToken is null", () => {
+    const base: NodeJS.ProcessEnv = { CLAUDE_CODE_OAUTH_TOKEN: "existing" }
+    const result = buildClaudeEnv(base, null)
+    expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe("existing")
+  })
+})

package/src/server/claude-spawn-helpers.ts

@@ -0,0 +1,179 @@
+/**
+ * Spawn-preparation helpers for Claude SDK / PTY sessions.
+ *
+ * Pure module — no IO, no `*.adapter.ts` suffix needed.
+ * Extracted from agent.ts to keep that file under the 600-LOC target.
+ */
+
+import type { CanUseTool, PermissionResult } from "@anthropic-ai/claude-agent-sdk"
+import type { HarnessToolRequest } from "./harness-types"
+import { normalizeToolCall } from "../shared/tools"
+import { type AnyValue, isRecord } from "../shared/errors"
+import type { ToolCallbackService } from "./tool-callback"
+import type { ChatPermissionPolicy } from "../shared/permission-policy"
+import { POLICY_DEFAULT } from "../shared/permission-policy"
+
+/**
+ * Native tools blocked while an autonomous loop is armed on the chat. The loop
+ * orchestrator must delegate every code change to a subagent (fresh context
+ * each iteration); letting it edit directly is exactly the drift that produced
+ * the 7.5h marathon turn. `Task` (the native Agent tool) is blocked too — it
+ * runs inline in the same turn with no /clear.
+ */
+export const LOOP_BLOCKED_NATIVE_TOOLS: readonly string[] = [
+  "Edit",
+  "Write",
+  "MultiEdit",
+  "NotebookEdit",
+  "Task",
+]
+
+/** Args for the `buildCanUseTool` helper — exposed for unit testing. */
+export interface BuildCanUseToolArgs {
+  localPath: string
+  chatId?: string
+  sessionToken?: string | null
+  onToolRequest: (request: HarnessToolRequest) => Promise<AnyValue>
+  toolCallback?: ToolCallbackService
+  chatPolicy?: ChatPermissionPolicy
+  /** When present and returns true, block LOOP_BLOCKED_NATIVE_TOOLS (loop-armed turn). */
+  isLoopArmed?: () => boolean
+}
+
+/**
+ * Builds the `canUseTool` callback passed to the SDK `query()`.
+ * Exported so unit tests can exercise the dual-routing logic without
+ * going through the full `startClaudeSession` factory.
+ */
+export function buildCanUseTool(args: BuildCanUseToolArgs): CanUseTool {
+  return async (toolName, input, options) => {
+    // Loop-armed turns: the orchestrator may only Read/Bash(verify)/delegate.
+    // Block direct edits + the native Agent tool so it cannot self-implement.
+    if (args.isLoopArmed?.() && LOOP_BLOCKED_NATIVE_TOOLS.includes(toolName)) {
+      return {
+        behavior: "deny",
+        message:
+          `${toolName} is blocked while an autonomous loop is armed. You are the `
+          + "orchestrator: delegate the next chunk with delegate_subagent "
+          + "(run_in_background: true) and end your turn, or call stop_loop if the "
+          + "goal is met. Do not edit files directly.",
+      }
+    }
+
+    if (toolName !== "AskUserQuestion" && toolName !== "ExitPlanMode") {
+      return { behavior: "allow", updatedInput: input }
+    }
+
+    const tool = normalizeToolCall({
+      toolName,
+      toolId: options.toolUseID,
+      input: input ?? {},
+    })
+
+    if (tool.toolKind !== "ask_user_question" && tool.toolKind !== "exit_plan_mode") {
+      return { behavior: "deny", message: "Unsupported tool request" }
+    }
+
+    // ── Flag-on path: route through tool-callback ──────────────────────────
+    if (process.env.KANNA_MCP_TOOL_CALLBACKS === "1" && args.toolCallback) {
+      const result = await args.toolCallback.submit({
+        chatId: args.chatId ?? "",
+        sessionId: args.sessionToken ?? "",
+        toolUseId: options.toolUseID,
+        toolName: `mcp__kanna__${tool.toolKind}`,
+        args: isRecord(tool.rawInput) ? tool.rawInput : {},
+        chatPolicy: args.chatPolicy ?? POLICY_DEFAULT,
+        cwd: args.localPath,
+      })
+
+      if (result.decision.kind === "deny") {
+        return { behavior: "deny", message: result.decision.reason ?? "denied" }
+      }
+
+      const payload: Record<string, unknown> = isRecord(result.decision.payload) ? result.decision.payload : {}
+
+      if (tool.toolKind === "ask_user_question") {
+        return {
+          behavior: "allow",
+          updatedInput: {
+            ...(tool.rawInput ?? {}),
+            questions: payload.questions ?? tool.input.questions,
+            answers: payload.answers ?? result.decision.payload,
+          },
+        } satisfies PermissionResult
+      }
+
+      // exit_plan_mode
+      if (payload.confirmed) {
+        return {
+          behavior: "allow",
+          updatedInput: { ...(tool.rawInput ?? {}), ...payload },
+        } satisfies PermissionResult
+      }
+
+      return {
+        behavior: "deny",
+        message: typeof payload.message === "string"
+          ? `User wants to suggest edits to the plan: ${payload.message}`
+          : "User wants to suggest edits to the plan before approving.",
+      } satisfies PermissionResult
+    }
+
+    // ── Legacy path (flag off OR toolCallback not provided) ────────────────
+    const result = await args.onToolRequest({ tool })
+
+    if (tool.toolKind === "ask_user_question") {
+      const record: Record<string, unknown> = isRecord(result) ? result : {}
+      return {
+        behavior: "allow",
+        updatedInput: {
+          ...(tool.rawInput ?? {}),
+          questions: record.questions ?? tool.input.questions,
+          answers: record.answers ?? result,
+        },
+      } satisfies PermissionResult
+    }
+
+    const record: Record<string, unknown> = isRecord(result) ? result : {}
+    const confirmed = Boolean(record.confirmed)
+    if (confirmed) {
+      return {
+        behavior: "allow",
+        updatedInput: { ...(tool.rawInput ?? {}), ...record },
+      } satisfies PermissionResult
+    }
+
+    return {
+      behavior: "deny",
+      message: typeof record.message === "string"
+        ? `User wants to suggest edits to the plan: ${record.message}`
+        : "User wants to suggest edits to the plan before approving.",
+    } satisfies PermissionResult
+  }
+}
+
+export function buildClaudeEnv(
+  baseEnv: NodeJS.ProcessEnv,
+  oauthToken: string | null,
+  openrouter?: { apiKey: string } | null,
+): NodeJS.ProcessEnv {
+  const { CLAUDECODE: _unused, CLAUDE_CODE_OAUTH_TOKEN: _oauth, ...rest } = baseEnv
+  if (openrouter) {
+    // OpenRouter's Anthropic-compatible endpoint. ANTHROPIC_API_KEY MUST be
+    // explicitly empty or the SDK prefers it over the auth token and 401s.
+    return {
+      ...rest,
+      ANTHROPIC_BASE_URL: "https://openrouter.ai/api",
+      ANTHROPIC_AUTH_TOKEN: openrouter.apiKey,
+      ANTHROPIC_API_KEY: "",
+    }
+  }
+  // Empty string is treated the same as null. Blank tokens are rejected at persistence time
+  // by normalizeTokenEntry, so in practice oauthToken is either a non-empty string or null.
+  if (!oauthToken) {
+    return baseEnv.CLAUDE_CODE_OAUTH_TOKEN
+      ? { ...rest, CLAUDE_CODE_OAUTH_TOKEN: baseEnv.CLAUDE_CODE_OAUTH_TOKEN }
+      : rest
+  }
+  return { ...rest, CLAUDE_CODE_OAUTH_TOKEN: oauthToken }
+}