@falkenslab/agent-kit 0.10.1

package/dist/core/promptTemplate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Builds a `loadPrompt(relativePath, vars)` bound to `rootDir` — so each agent built on this kit supplies its own
+ * prompts directory (its own domain content) and gets the same `{{key}}`
+ * substitution/fail-loudly behavior for free.
+ */
+export declare function createPromptLoader(rootDir: string): (relativePath: string, vars?: Record<string, string>) => string;

package/dist/core/promptTemplate.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Builds a `loadPrompt(relativePath, vars)` bound to `rootDir` — so each agent built on this kit supplies its own
+ * prompts directory (its own domain content) and gets the same `{{key}}`
+ * substitution/fail-loudly behavior for free.
+ */
+export function createPromptLoader(rootDir) {
+    return (relativePath, vars = {}) => {
+        const raw = readFileSync(path.join(rootDir, relativePath), "utf-8");
+        return raw
+            .replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+            if (!(key in vars)) {
+                throw new Error(`Prompt "${relativePath}": missing variable "${key}"`);
+            }
+            return vars[key];
+        })
+            .trimEnd();
+    };
+}

package/dist/core/runner.d.ts

@@ -0,0 +1,137 @@
+import { type Options, type SDKUserMessage, type SlashCommand } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * A transport-agnostic view of one turn's worth of output from `query()` — the same
+ * normalized shape whether the caller is going to print it to a console, forward it to a
+ * chat REPL, or serialize it over Electron IPC (a real consuming agent had four
+ * separate entry points — CLI run, CLI chat, an exploration mode and a desktop chat — that
+ * all parsed the SDK's raw message stream themselves, nearly identically).
+ *
+ * Deliberately thin: no formatting (no "[agent]"/"[action]" prefixes, no friendly tool
+ * labels — those are domain/presentation concerns the caller owns), and no filtering
+ * beyond what's always correct regardless of caller (see `action` below).
+ */
+export type AgentEvent = 
+/** One streamed text token from the agent's own reply. No separate "block started"
+ * event: a caller that wants a prefix before a new run of text (e.g. "\n[agent] ") can
+ * track "was the previous event also `text`?" itself — simpler than mirroring the SDK's
+ * own content-block boundaries, and equivalent in practice. */
+{
+    type: "text";
+    text: string;
+}
+/** A tool call the main agent itself made — never from inside a subagent's own private
+ * turn (an `assistant` message with a non-null `parent_tool_use_id`, e.g. a subagent
+ * spawned via the `Agent` tool): those are already reported back to the `Agent` tool
+ * call that started them, so surfacing their *internal* tool use here would make it
+ * look like a subagent had taken over the session, not just handed a result back to the
+ * main agent. This filtering is the one piece of interpretation this module always
+ * applies, since it's correct for every caller, not a presentation choice. */
+ | {
+    type: "action";
+    toolName: string;
+    input: unknown;
+    toolUseId?: string;
+}
+/** A tool call made inside a subagent's own turn (see `action` above for why those are
+ * kept apart). Only for showing that a subagent is busy: a console log ignores it. */
+ | {
+    type: "subagent-action";
+    toolName: string;
+    input: unknown;
+    toolUseId?: string;
+    parentToolUseId?: string;
+}
+/** What one of the main agent's tool calls returned, paired with its `action` by
+ * `toolUseId`, as plain text (images and other non-text parts left out). Subagents'
+ * results stay out, as their actions do. A console log ignores it. */
+ | {
+    type: "tool-result";
+    toolUseId: string;
+    toolName: string;
+    isError: boolean;
+    text: string;
+}
+/** One or more MCP servers failed to connect at session startup. */
+ | {
+    type: "mcp-error";
+    failedServers: string[];
+}
+/** A turn (one full `query()` response cycle) has finished. `failed` is the real
+ * failure signal — the SDK can report `status: "success"` even when the turn actually
+ * failed on an API error (billing/access denied, etc.), with the real message landing
+ * in `resultText` instead of `errorText` in that specific case (confirmed empirically:
+ * an org-level access error came back as subtype "success", is_error: true, with the
+ * real message in `result`) — check `failed`, not `status === "success"`. */
+ | {
+    type: "turn-end";
+    status: string;
+    failed: boolean;
+    resultText: string | null;
+    errorText: string;
+    usage?: SessionUsage;
+}
+/** Out-of-band text from the CLI loop itself, not from the model: local-command output
+ * (e.g. built-in `/usage`) or an informational banner (hook feedback, an unrecognized
+ * `/slash-command` notice, ...). Without this, those `system` messages fell through
+ * `generateEvents()` unhandled — confirmed empirically: typing an unrecognized/
+ * unnamespaced plugin slash command produced total silence (no text, no error, nothing),
+ * because the SDK's own response to it arrives as exactly this message shape and this
+ * module simply dropped it. */
+ | {
+    type: "info";
+    text: string;
+    level: "info" | "notice" | "suggestion" | "warning" | "local-command";
+}
+/** The predicted next prompt, when `Options.promptSuggestions` is on. It arrives after
+ * that turn's `turn-end`, so a reader that stops at `turn-end` sees it first thing in the
+ * next turn; a console log ignores it. */
+ | {
+    type: "prompt-suggestion";
+    suggestion: string;
+};
+/**
+ * Running totals for the whole `query()` session so far, not for one turn: the SDK's own
+ * `total_cost_usd` and `modelUsage` are cumulative across turns in a streaming-input
+ * session, so the latest `turn-end` carries the session total (never sum them).
+ */
+export interface SessionUsage {
+    /** Input tokens, cache reads and writes included, across every model the session used. */
+    inputTokens: number;
+    outputTokens: number;
+    /** An estimate, not a billing statement. */
+    costUsd: number;
+}
+/**
+ * A turn's errors without the CLI's internal diagnostics: an interrupted turn ends with
+ * one like "[ede_diagnostic] result_type=user ... stop_reason=tool_use" (seen on Esc),
+ * which says nothing to a person.
+ */
+export declare function visibleErrors(errors: readonly string[]): string[];
+/** A tool result's content as plain text: its text parts joined, anything else skipped. */
+export declare function toolResultText(content: unknown): string;
+export interface ContextUsage {
+    /** 0-100. */
+    percentage: number;
+    totalTokens: number;
+    maxTokens: number;
+}
+export interface AgentRun {
+    /** Normalized events for this run — iterate with `for await`. */
+    events: AsyncIterable<AgentEvent>;
+    /** Interrupts the current turn (doesn't end the session — a caller wanting a full stop should also call `close()`). */
+    interrupt: () => Promise<unknown>;
+    /** Ends the session. No further events arrive after this; safe to call even if `events` is still being iterated elsewhere (e.g. from a SIGINT handler racing the main loop). */
+    close: () => void;
+    /** This session's own slash commands (skills doubling as typable commands, etc.) — only meaningful once the session has actually started (see the SDK's own `Query.supportedCommands()`). */
+    supportedCommands: () => Promise<SlashCommand[]>;
+    /** How full the context window is now, or null if the session can't tell (see the SDK's `Query.getContextUsage()`). */
+    contextUsage: () => Promise<ContextUsage | null>;
+}
+/**
+ * Thin wrapper around the SDK's own `query()`: same two-argument shape (a plain string
+ * for a one-shot run, or an `AsyncIterable<SDKUserMessage>` — see `createInputQueue()` —
+ * for a multi-turn chat), translating its raw message stream into `AgentEvent`s as
+ * described above. Every other control surface of the underlying `Query` (`interrupt`,
+ * `close`, `supportedCommands`) is passed through unchanged.
+ */
+export declare function runQuery(prompt: string | AsyncIterable<SDKUserMessage>, options: Options): AgentRun;

package/dist/core/runner.js

@@ -0,0 +1,115 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * A turn's errors without the CLI's internal diagnostics: an interrupted turn ends with
+ * one like "[ede_diagnostic] result_type=user ... stop_reason=tool_use" (seen on Esc),
+ * which says nothing to a person.
+ */
+export function visibleErrors(errors) {
+    return errors.filter((error) => !error.startsWith("[ede_diagnostic]"));
+}
+/** A tool result's content as plain text: its text parts joined, anything else skipped. */
+export function toolResultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((part) => typeof part === "object" && part !== null && part.type === "text")
+        .map((part) => part.text)
+        .join("\n");
+}
+/**
+ * Thin wrapper around the SDK's own `query()`: same two-argument shape (a plain string
+ * for a one-shot run, or an `AsyncIterable<SDKUserMessage>` — see `createInputQueue()` —
+ * for a multi-turn chat), translating its raw message stream into `AgentEvent`s as
+ * described above. Every other control surface of the underlying `Query` (`interrupt`,
+ * `close`, `supportedCommands`) is passed through unchanged.
+ */
+export function runQuery(prompt, options) {
+    const result = query({ prompt, options });
+    // The main agent's tool calls by id, to name the results that come back for them.
+    const toolNames = new Map();
+    async function* generateEvents() {
+        for await (const message of result) {
+            if (message.type === "system" && message.subtype === "init") {
+                const failedServers = message.mcp_servers.filter((s) => s.status === "failed").map((s) => s.name);
+                if (failedServers.length > 0)
+                    yield { type: "mcp-error", failedServers };
+                continue;
+            }
+            if (message.type === "system" && message.subtype === "informational") {
+                yield { type: "info", text: message.content, level: message.level };
+                continue;
+            }
+            if (message.type === "system" && message.subtype === "local_command_output") {
+                yield { type: "info", text: message.content, level: "local-command" };
+                continue;
+            }
+            if (message.type === "stream_event") {
+                const event = message.event;
+                if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
+                    yield { type: "text", text: event.delta.text };
+                }
+                continue;
+            }
+            if (message.type === "assistant") {
+                const type = message.parent_tool_use_id === null ? "action" : "subagent-action";
+                for (const block of message.message.content) {
+                    if (block.type === "tool_use") {
+                        if (type === "action")
+                            toolNames.set(block.id, block.name);
+                        yield {
+                            type,
+                            toolName: block.name,
+                            input: block.input,
+                            toolUseId: block.id,
+                            ...(message.parent_tool_use_id === null ? {} : { parentToolUseId: message.parent_tool_use_id }),
+                        };
+                    }
+                }
+                continue;
+            }
+            if (message.type === "user" && message.parent_tool_use_id === null && Array.isArray(message.message.content)) {
+                for (const block of message.message.content) {
+                    if (block.type !== "tool_result")
+                        continue;
+                    const toolName = toolNames.get(block.tool_use_id);
+                    if (!toolName)
+                        continue;
+                    yield { type: "tool-result", toolUseId: block.tool_use_id, toolName, isError: block.is_error === true, text: toolResultText(block.content) };
+                }
+            }
+            if (message.type === "prompt_suggestion") {
+                yield { type: "prompt-suggestion", suggestion: message.suggestion };
+                continue;
+            }
+            if (message.type === "result") {
+                const failed = message.is_error;
+                const resultText = message.subtype === "success" ? message.result : null;
+                const errorText = message.subtype === "success" ? message.result : visibleErrors(message.errors).join("; ");
+                const models = Object.values(message.modelUsage ?? {});
+                const usage = {
+                    inputTokens: models.reduce((sum, m) => sum + m.inputTokens + m.cacheReadInputTokens + m.cacheCreationInputTokens, 0),
+                    outputTokens: models.reduce((sum, m) => sum + m.outputTokens, 0),
+                    costUsd: message.total_cost_usd,
+                };
+                yield { type: "turn-end", status: message.subtype, failed, resultText, errorText, usage };
+            }
+        }
+    }
+    return {
+        events: generateEvents(),
+        interrupt: () => result.interrupt(),
+        close: () => result.close(),
+        supportedCommands: () => result.supportedCommands(),
+        contextUsage: async () => {
+            try {
+                const usage = await result.getContextUsage();
+                return { percentage: usage.percentage, totalTokens: usage.totalTokens, maxTokens: usage.maxTokens };
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/core/session.d.ts

@@ -0,0 +1,63 @@
+import type { Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { type TranscriptLogger } from "./hooks/transcriptLogger.js";
+import type { AgentSpec, BaseSessionConfig, Mode } from "./agentSpec.js";
+/**
+ * Builds the `options` object passed to the Agent SDK's `query()` — everything about
+ * *how* the agent runs a session (system prompt, tools, MCP servers, hooks), independent
+ * of *what* is said to start it off (that's the caller's `prompt`, a plain string for a
+ * one-shot run or an `AsyncIterable` for a multi-turn chat).
+ *
+ * Everything actually *about the domain* (which system prompt, which MCP servers besides
+ * the generic human-in-the-loop/knowledge ones below, which plugin roots, which
+ * subagents) is behind `spec` (see agentSpec.ts) — this function only knows the generic
+ * fields on `BaseSessionConfig`.
+ *
+ * The per-mode behavioral differences (whether the approval/manual-intervention tools
+ * exist, whether the interactive step gate hook runs) all fall out of `config.mode`
+ * alone.
+ */
+export declare function buildSessionOptions<TConfig extends BaseSessionConfig>(config: TConfig, runDir: string, spec: AgentSpec<TConfig>, options?: {
+    autoCompactEnabled?: boolean;
+}): Promise<{
+    options: Options;
+    transcriptLogger: TranscriptLogger;
+    transcriptPath: string;
+    modeControl: ModeControl;
+}>;
+/**
+ * The supervision mode of a running session. Only "guided" and "interactive" can switch into
+ * each other: they share the same tools (the approval tool) and the step gate is registered
+ * in both, asking only in "interactive". "autonomous" has no approval tool at all, and a tool
+ * can't appear or vanish mid-session, so a session that starts autonomous stays autonomous,
+ * and one that doesn't can't become autonomous. The system prompt keeps the mode it was
+ * built with.
+ */
+export interface ModeControl {
+    readonly mode: Mode;
+    /** The modes this session can be in; fewer than two means it can't switch. */
+    readonly switchable: readonly Mode[];
+    /** Switches to `next` if this session allows it; returns whether it did. */
+    set(next: Mode): boolean;
+}
+export declare function createModeControl(initial: Mode): ModeControl;
+/**
+ * User message queue backed by a single long-lived generator, for any multi-turn
+ * (chat-shaped) caller of `query()`.
+ *
+ * The SDK closes the transport as soon as the AsyncIterable passed as `prompt` (or to
+ * `streamInput()`) finishes iterating — so a "one message and done" generator leaves the
+ * transport closed right after sending that message, and the next call blows up with
+ * "ProcessTransport is not ready for writing". A real multi-turn conversation needs a
+ * single generator that never finishes on its own: messages get pushed into it with
+ * `push()` and it's only explicitly closed with `end()` when leaving the chat.
+ */
+export declare function createInputQueue(): {
+    push: (text: string) => void;
+    end: () => void;
+    iterable: AsyncIterable<SDKUserMessage>;
+};
+/** Externally-controllable promise — used to know when a chat turn has finished. */
+export declare function createDeferred(): {
+    promise: Promise<void>;
+    resolve: () => void;
+};

package/dist/core/session.js

@@ -0,0 +1,222 @@
+import path from "node:path";
+import { createTranscriptLogger } from "./hooks/transcriptLogger.js";
+import { createStepGate } from "./hooks/stepGate.js";
+import { createSubagentBashGate } from "./hooks/subagentBashGate.js";
+import { createSubagentTypeGate } from "./hooks/subagentTypeGate.js";
+import { createSubagentForegroundGate } from "./hooks/subagentForegroundGate.js";
+import { createFileScopeGate } from "./hooks/fileScopeGate.js";
+import { createHumanApprovalServer } from "./tools/humanApproval.js";
+import { createManualLoginServer } from "./tools/manualLogin.js";
+import { createSaveToSourcesServer } from "./tools/saveToSources.js";
+import { allowAnyMcpTool } from "./mcpPermissions.js";
+import { knowledgePluginRoot, knowledgePromptSection } from "./knowledge.js";
+/**
+ * Builds the `options` object passed to the Agent SDK's `query()` — everything about
+ * *how* the agent runs a session (system prompt, tools, MCP servers, hooks), independent
+ * of *what* is said to start it off (that's the caller's `prompt`, a plain string for a
+ * one-shot run or an `AsyncIterable` for a multi-turn chat).
+ *
+ * Everything actually *about the domain* (which system prompt, which MCP servers besides
+ * the generic human-in-the-loop/knowledge ones below, which plugin roots, which
+ * subagents) is behind `spec` (see agentSpec.ts) — this function only knows the generic
+ * fields on `BaseSessionConfig`.
+ *
+ * The per-mode behavioral differences (whether the approval/manual-intervention tools
+ * exist, whether the interactive step gate hook runs) all fall out of `config.mode`
+ * alone.
+ */
+export async function buildSessionOptions(config, runDir, spec, options = {}) {
+    const { mode } = config;
+    const modeControl = createModeControl(mode);
+    // The human approval server only exists outside autonomous mode: the point of
+    // autonomous is that the agent has no channel to ask for human intervention at all.
+    const includeApprovalTool = mode !== "autonomous";
+    // Manual intervention only makes sense for a domain that drives some live UI a human
+    // could actually step into by hand — `spec.manualInterventionTexts` being set is that
+    // domain's own opt-in signal (see its doc comment in agentSpec.ts), not a generic
+    // boolean this kit could infer on its own.
+    const manualInterventionTexts = mode !== "autonomous" ? spec.manualInterventionTexts : undefined;
+    // The file tools exist as soon as the project has a place for the agent's notes
+    // (`knowledgeDir`) or for original files (`sourcesDir`) — there is no separate "context"
+    // folder: material the user provides is just more of `sourcesDir`.
+    const includeFileTools = Boolean(config.knowledgeDir || config.sourcesDir);
+    const fileTools = includeFileTools ? ["Read", "Write", "Edit", "Glob", "Grep"] : [];
+    // Where Write/Edit may act and Grep may search (see hooks/fileScopeGate.ts): the
+    // project's own folders, never the whole cwd — which would include whatever else the
+    // project directory holds (the user's config...). `sourcesDir` is searchable but
+    // deliberately NOT writable: originals stay as obtained, and the only way to add to it is
+    // the `save_to_sources` tool (which never overwrites).
+    const writableDirs = [config.knowledgeDir, ...(config.extraWritableDirs ?? [])].filter((d) => Boolean(d));
+    const searchableDirs = [config.knowledgeDir, config.sourcesDir, ...(config.extraWritableDirs ?? [])].filter((d) => Boolean(d));
+    const readOnlyDirs = config.sourcesDir ? [config.sourcesDir] : [];
+    // Skills/commands/plugins are a separate concern from the file tools: an agent that
+    // wants a plugin-provided skill/command but has no notes or sources folder shouldn't have
+    // to invent one just to get `cwd`/`skills: "all"`/`plugins` wired up. Gated on either
+    // signal, not on `pluginRoots` alone, so an agent with file tools keeps getting the SDK's
+    // own project-level `.claude/skills`/`.claude/commands` discovery.
+    // The built-in knowledge base (rules in the system prompt + its skills/commands as a plugin) needs
+    // somewhere to keep the wiki, so it follows `knowledgeDir`; `spec.knowledgeBase: false` opts out.
+    const includeKnowledgeBase = Boolean(config.knowledgeDir) && spec.knowledgeBase !== false;
+    const pluginRoots = [...spec.pluginRoots(config), ...(includeKnowledgeBase ? [knowledgePluginRoot()] : [])];
+    const includeSkillsAndPlugins = includeFileTools || pluginRoots.length > 0;
+    const skillTools = includeSkillsAndPlugins ? ["Skill"] : [];
+    // Whatever opt-in subagents `spec` wants for this config, or undefined if none apply.
+    // Either opt-in feature needs the Agent tool (to delegate to a subagent) and Bash (used
+    // only by the subagent itself — see createSubagentBashGate() below, which denies Bash
+    // to the main agent regardless of which one put it in `tools`) — Bash has to be present
+    // in this session's own tools for any subagent to be allowed to use it at all
+    // (confirmed empirically the SDK refuses to spawn a subagent whose own tools list names
+    // anything not already present here — which is why the hook, not just omitting "Bash"
+    // from this list, is what actually confines it to subagent use).
+    const subagents = spec.buildSubagents(config);
+    const includeSubagentTools = subagents !== undefined;
+    // The exact set of subagent_type values the Agent tool may spawn in this session — see
+    // createSubagentTypeGate() below for why this can't just be "whatever's in `agents`
+    // below": the SDK's own built-in "general-purpose" type is spawnable regardless of that
+    // map, and inherits the full session tools (Bash included) rather than the narrow list
+    // each declared subagent actually declares.
+    const allowedSubagentTypes = subagents?.allowedSubagentTypes ?? [];
+    const transcriptPath = path.join(runDir, "transcript.jsonl");
+    const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
+    const sdkOptions = {
+        systemPrompt: includeKnowledgeBase && config.knowledgeDir
+            ? `${spec.buildSystemPrompt(config)}\n\n${knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir)}`
+            : spec.buildSystemPrompt(config),
+        settings: { autoCompactEnabled: options.autoCompactEnabled ?? true },
+        // No built-in tools except, if applicable, Read/Write/Edit/Glob/Grep scoped to the
+        // project's own folders (fileScopeGate below), and WebFetch/WebSearch
+        // with no domain restriction (not conditioned on includeFileTools: it's read-only,
+        // doesn't depend on there being a project directory) — any priority order between
+        // them is the domain's own system prompt's job to establish, not this function's.
+        // "Skill" has to be listed explicitly: with an explicit `tools` list the SDK loads the
+        // skills (they show up in the init message) but doesn't offer the tool to invoke them,
+        // so the model ends up looking for SKILL.md files by hand (confirmed empirically).
+        tools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
+        allowedTools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
+        // Every mcp__* tool (whatever spec.buildMcpServers() registers, approvals/manualLogin
+        // when enabled below, sourceFiles, and any server a project's own .mcp.json
+        // declares) is approved generically here rather than listed one by one — see
+        // mcpPermissions.ts for why a fixed allowedTools wildcard can't cover a server whose
+        // name isn't known ahead of time.
+        canUseTool: allowAnyMcpTool,
+        disallowedTools: spec.disallowedTools ?? [],
+        // Real text streaming instead of silently waiting for the turn's complete message —
+        // see the caller's message loop.
+        includePartialMessages: true,
+        ...(includeSkillsAndPlugins
+            ? {
+                // With cwd pointing at the project, the SDK's own "project settings" discovery
+                // finds <project>/.claude/skills/ on its own — the user's own custom
+                // skills, on top of the plugin-provided built-ins from spec.pluginRoots()
+                // below. skipMcpDiscovery: true on those plugins is the caller's choice.
+                cwd: config.projectDir,
+                // Empty when there's no knowledgeDir/sourcesDir (the plugin-only case) — an
+                // empty array is a valid, no-op value for this SDK option, not omitted, since
+                // this whole block is already conditioned on includeSkillsAndPlugins.
+                additionalDirectories: searchableDirs,
+                // "skills" acts as a name whitelist, not an addition: "all" enables both the
+                // SDK's own official skills (pdf/docx), the project's own custom ones, and the
+                // plugin-provided built-ins below.
+                skills: "all",
+                plugins: pluginRoots.map((pluginPath) => ({ type: "local", path: pluginPath, skipMcpDiscovery: true })),
+            }
+            : {}),
+        maxTurns: 400,
+        ...(subagents ? { agents: subagents.agents } : {}),
+        mcpServers: {
+            ...spec.buildMcpServers(config, runDir),
+            ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts) } : {}),
+            ...(manualInterventionTexts ? { manualLogin: createManualLoginServer(runDir, manualInterventionTexts) } : {}),
+            ...(config.sourcesDir ? { sourceFiles: createSaveToSourcesServer(runDir, config.sourcesDir, spec.saveToSourcesDescription) } : {}),
+        },
+        hooks: {
+            PreToolUse: [
+                { hooks: [transcriptLogger.preToolUse] },
+                ...(includeFileTools
+                    ? [{ hooks: [createFileScopeGate({ projectDir: config.projectDir, writableDirs, searchableDirs, readOnlyDirs, deniedPaths: config.deniedPaths ?? [] })] }]
+                    : []),
+                // Registered wherever the approval tool is, and asking only while the current mode is
+                // "interactive": a guided session can switch to interactive and back (ModeControl).
+                ...(includeApprovalTool ? [{ hooks: [createStepGate(runDir, () => modeControl.mode === "interactive")] }] : []),
+                ...(includeSubagentTools
+                    ? [
+                        { hooks: [createSubagentTypeGate(allowedSubagentTypes)] },
+                        { hooks: [createSubagentBashGate()] },
+                        { hooks: [createSubagentForegroundGate(allowedSubagentTypes)] },
+                    ]
+                    : []),
+            ],
+            PostToolUse: [{ hooks: [transcriptLogger.postToolUse] }],
+        },
+    };
+    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl };
+}
+export function createModeControl(initial) {
+    let current = initial;
+    const switchable = initial === "autonomous" ? ["autonomous"] : ["guided", "interactive"];
+    return {
+        get mode() {
+            return current;
+        },
+        switchable,
+        set(next) {
+            if (!switchable.includes(next))
+                return false;
+            current = next;
+            return true;
+        },
+    };
+}
+/**
+ * User message queue backed by a single long-lived generator, for any multi-turn
+ * (chat-shaped) caller of `query()`.
+ *
+ * The SDK closes the transport as soon as the AsyncIterable passed as `prompt` (or to
+ * `streamInput()`) finishes iterating — so a "one message and done" generator leaves the
+ * transport closed right after sending that message, and the next call blows up with
+ * "ProcessTransport is not ready for writing". A real multi-turn conversation needs a
+ * single generator that never finishes on its own: messages get pushed into it with
+ * `push()` and it's only explicitly closed with `end()` when leaving the chat.
+ */
+export function createInputQueue() {
+    const pending = [];
+    let wake = null;
+    let ended = false;
+    async function* generator() {
+        while (!ended) {
+            const text = pending.shift();
+            if (text === undefined) {
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+                continue;
+            }
+            yield {
+                type: "user",
+                message: { role: "user", content: text },
+                parent_tool_use_id: null,
+            };
+        }
+    }
+    return {
+        push(text) {
+            pending.push(text);
+            wake?.();
+            wake = null;
+        },
+        end() {
+            ended = true;
+            wake?.();
+            wake = null;
+        },
+        iterable: generator(),
+    };
+}
+/** Externally-controllable promise — used to know when a chat turn has finished. */
+export function createDeferred() {
+    let resolveFn;
+    const promise = new Promise((resolve) => {
+        resolveFn = resolve;
+    });
+    return { promise, resolve: resolveFn };
+}

package/dist/core/toolLabels.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Turns a raw tool name + input into a short, readable console description, instead of
+ * the tool's technical name (e.g. "mcp__playwright__browser_click"). Covers the tools
+ * this kit itself provides (Read/Write/Edit/Glob/Grep/Bash/Agent/WebFetch/WebSearch/Skill,
+ * plus its own human-approval/manual-intervention/save-to-sources MCP tools)
+ * generically; a
+ * concrete agent supplies a `describe` callback for its own domain-specific tools (e.g.
+ * Playwright's browser_* cases) via `createFriendlyToolLabel()`.
+ */
+export declare function truncate(text: string, max?: number): string;
+export declare function truncatePath(text: string, max?: number): string;
+export type ToolDescriber = (shortName: string, input: Record<string, unknown>) => string | undefined;
+/**
+ * Builds a `friendlyToolLabel(toolName, toolInput)` — `describe` lets the host agent
+ * layer its own domain-specific cases (e.g. Playwright's browser_* tools) on top of this
+ * kit's generic ones; `extraLocalServers` names any *additional* MCP server (beyond this
+ * kit's own "approvals"/"manualLogin"/"sourceFiles") whose tools should be unwrapped
+ * without a "[server] " prefix, e.g. "playwright".
+ */
+export declare function createFriendlyToolLabel(options?: {
+    describe?: ToolDescriber;
+    extraLocalServers?: readonly string[];
+}): (toolName: string, toolInput: unknown) => string;