@zhijiewang/openharness 2.20.0 → 2.22.0

package/dist/mcp/elicitation.d.ts

@@ -0,0 +1,66 @@
+/**
+ * MCP `elicitation/create` responder (audit B4).
+ *
+ * MCP servers can ask the client to elicit user input — for confirmations
+ * ("are you sure?"), for form fills, or for free-form text. The spec defines
+ * three response actions:
+ *   - `accept`   → user agreed; `content` may contain form values
+ *   - `decline`  → user explicitly said no
+ *   - `cancel`   → user dismissed without choosing (e.g. closed the prompt)
+ *
+ * Default behavior is **fail-safe decline** — when nothing decides, OH
+ * returns `{ action: "decline" }`. This keeps OH from accepting actions
+ * silently in headless / unattended mode. To accept, configure an
+ * `elicitation` hook that returns `permissionDecision: "allow"`, or wire an
+ * interactive handler via `setElicitationHandler` (the REPL will plug in
+ * when its UX support lands; until then the hook path is the supported
+ * extension point).
+ *
+ * Two hook events fire per elicitation:
+ *   - `elicitation`        — request received, before any decision
+ *   - `elicitationResult`  — final action + content, after decision is made
+ *
+ * Both carry the server name and message so audit hooks can log the
+ * full request/response pair.
+ */
+export type ElicitationAction = "accept" | "decline" | "cancel";
+export interface ElicitationRequest {
+    /** Server name — for hook context. Not part of the MCP wire format. */
+    serverName: string;
+    /** Human-readable message the server wants to show the user. */
+    message: string;
+    /** JSON Schema describing the structured content the server expects on accept. */
+    requestedSchema: unknown;
+}
+export interface ElicitationResponse {
+    action: ElicitationAction;
+    content?: Record<string, unknown>;
+}
+/**
+ * Optional interactive handler — called when no hook decided. The REPL is
+ * the natural caller; until that lands, leaving this unset means OH falls
+ * straight from the hook to the auto-decline default.
+ */
+export type InteractiveElicitationHandler = (req: ElicitationRequest) => Promise<ElicitationResponse>;
+/**
+ * Register / replace the interactive elicitation handler. Pass `undefined`
+ * to clear (for tests / REPL teardown). Idempotent.
+ */
+export declare function setElicitationHandler(handler: InteractiveElicitationHandler | undefined): void;
+/**
+ * Resolve an MCP `elicitation/create` request into an `ElicitationResponse`.
+ *
+ * Decision priority:
+ *   1. `elicitation` hook returns a decision → honor it (allow → accept, deny → decline)
+ *   2. Interactive handler is registered → delegate to it
+ *   3. Default → `{ action: "decline" }`
+ *
+ * Always fires the symmetric `elicitationResult` hook last, so audit hooks
+ * see the full request/response pair regardless of which branch decided.
+ *
+ * @internal Exported for tests; transport.ts is the production caller.
+ */
+export declare function resolveElicitation(req: ElicitationRequest): Promise<ElicitationResponse>;
+/** @internal Test-only reset. */
+export declare function _resetElicitationForTest(): void;
+//# sourceMappingURL=elicitation.d.ts.map

package/dist/mcp/elicitation.js

@@ -0,0 +1,88 @@
+/**
+ * MCP `elicitation/create` responder (audit B4).
+ *
+ * MCP servers can ask the client to elicit user input — for confirmations
+ * ("are you sure?"), for form fills, or for free-form text. The spec defines
+ * three response actions:
+ *   - `accept`   → user agreed; `content` may contain form values
+ *   - `decline`  → user explicitly said no
+ *   - `cancel`   → user dismissed without choosing (e.g. closed the prompt)
+ *
+ * Default behavior is **fail-safe decline** — when nothing decides, OH
+ * returns `{ action: "decline" }`. This keeps OH from accepting actions
+ * silently in headless / unattended mode. To accept, configure an
+ * `elicitation` hook that returns `permissionDecision: "allow"`, or wire an
+ * interactive handler via `setElicitationHandler` (the REPL will plug in
+ * when its UX support lands; until then the hook path is the supported
+ * extension point).
+ *
+ * Two hook events fire per elicitation:
+ *   - `elicitation`        — request received, before any decision
+ *   - `elicitationResult`  — final action + content, after decision is made
+ *
+ * Both carry the server name and message so audit hooks can log the
+ * full request/response pair.
+ */
+import { emitHook, emitHookWithOutcome } from "../harness/hooks.js";
+let interactiveHandler;
+/**
+ * Register / replace the interactive elicitation handler. Pass `undefined`
+ * to clear (for tests / REPL teardown). Idempotent.
+ */
+export function setElicitationHandler(handler) {
+    interactiveHandler = handler;
+}
+/**
+ * Resolve an MCP `elicitation/create` request into an `ElicitationResponse`.
+ *
+ * Decision priority:
+ *   1. `elicitation` hook returns a decision → honor it (allow → accept, deny → decline)
+ *   2. Interactive handler is registered → delegate to it
+ *   3. Default → `{ action: "decline" }`
+ *
+ * Always fires the symmetric `elicitationResult` hook last, so audit hooks
+ * see the full request/response pair regardless of which branch decided.
+ *
+ * @internal Exported for tests; transport.ts is the production caller.
+ */
+export async function resolveElicitation(req) {
+    const hookCtx = {
+        elicitationServer: req.serverName,
+        elicitationMessage: req.message.slice(0, 500),
+        // Schema can be large; cap at 2 KB so hooks don't OOM env vars.
+        elicitationSchema: JSON.stringify(req.requestedSchema).slice(0, 2_000),
+    };
+    let response;
+    const hookOutcome = await emitHookWithOutcome("elicitation", hookCtx);
+    if (hookOutcome.permissionDecision === "allow") {
+        response = { action: "accept", content: {} };
+    }
+    else if (hookOutcome.permissionDecision === "deny" || !hookOutcome.allowed) {
+        response = { action: "decline" };
+    }
+    else if (interactiveHandler) {
+        try {
+            response = await interactiveHandler(req);
+        }
+        catch {
+            // Interactive handler crashed — fail-safe decline rather than swallow.
+            response = { action: "cancel" };
+        }
+    }
+    else {
+        // Headless default — never accept silently.
+        response = { action: "decline" };
+    }
+    emitHook("elicitationResult", {
+        elicitationServer: req.serverName,
+        elicitationMessage: req.message.slice(0, 500),
+        elicitationAction: response.action,
+        elicitationContent: response.content ? JSON.stringify(response.content).slice(0, 2_000) : undefined,
+    });
+    return response;
+}
+/** @internal Test-only reset. */
+export function _resetElicitationForTest() {
+    interactiveHandler = undefined;
+}
+//# sourceMappingURL=elicitation.js.map

package/dist/mcp/loader.d.ts

@@ -1,6 +1,33 @@
+import type { McpServerConfig } from "../harness/config.js";
 import type { Tool } from "../Tool.js";
-/** Load MCP tools from .oh/config.yaml mcpServers list. Returns empty array if none configured. */
-export declare function loadMcpTools(): Promise<Tool[]>;
+/**
+ * Parse a `--mcp-config <path>` file. Format:
+ *   - `{ "mcpServers": [...] }` — Claude Code convention (preferred)
+ *   - `[ ... ]` — bare array of server configs (also accepted)
+ *   - `{ "name": ..., ... }` — single-server object (also accepted)
+ *
+ * Validation is shape-only: each entry must be an object with a `name`.
+ * Connection-time validation happens in `McpClient.connect`. Throws on
+ * malformed JSON or unrecognised top-level shape.
+ */
+export declare function parseMcpConfigFile(path: string): McpServerConfig[];
+export interface LoadMcpOptions {
+    /**
+     * MCP servers loaded from sources outside `.oh/config.yaml` — typically
+     * a `--mcp-config <path>` file. Merged with the config-file servers
+     * unless `strict` is set, in which case these REPLACE the config-file
+     * servers entirely.
+     */
+    extraServers?: import("../harness/config.js").McpServerConfig[];
+    /**
+     * When `true`, ignore `cfg.mcpServers` and use only `extraServers`.
+     * No-op when `extraServers` is undefined (the config-file servers
+     * still load). Mirrors Claude Code's `--strict-mcp-config`.
+     */
+    strict?: boolean;
+}
+/** Load MCP tools from .oh/config.yaml mcpServers list (and/or `--mcp-config` overrides). Returns empty array if none configured. */
+export declare function loadMcpTools(opts?: LoadMcpOptions): Promise<Tool[]>;
 /** Disconnect all MCP clients (call on exit) */
 export declare function disconnectMcpClients(): void;
 /** Names of connected MCP servers */

package/dist/mcp/loader.js

@@ -1,7 +1,52 @@
+import { readFileSync } from "node:fs";
 import { readOhConfig } from "../harness/config.js";
+import { debug } from "../utils/debug.js";
 import { McpClient } from "./client.js";
 import { DeferredMcpTool } from "./DeferredMcpTool.js";
 import { McpTool } from "./McpTool.js";
+/**
+ * Parse a `--mcp-config <path>` file. Format:
+ *   - `{ "mcpServers": [...] }` — Claude Code convention (preferred)
+ *   - `[ ... ]` — bare array of server configs (also accepted)
+ *   - `{ "name": ..., ... }` — single-server object (also accepted)
+ *
+ * Validation is shape-only: each entry must be an object with a `name`.
+ * Connection-time validation happens in `McpClient.connect`. Throws on
+ * malformed JSON or unrecognised top-level shape.
+ */
+export function parseMcpConfigFile(path) {
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--mcp-config '${path}' is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let servers;
+    if (Array.isArray(parsed)) {
+        servers = parsed;
+    }
+    else if (parsed && typeof parsed === "object" && "mcpServers" in parsed) {
+        const list = parsed.mcpServers;
+        if (!Array.isArray(list)) {
+            throw new Error(`--mcp-config '${path}': mcpServers must be an array`);
+        }
+        servers = list;
+    }
+    else if (parsed && typeof parsed === "object" && "name" in parsed) {
+        servers = [parsed];
+    }
+    else {
+        throw new Error(`--mcp-config '${path}': expected an mcpServers array, a bare array, or a single server object`);
+    }
+    for (const s of servers) {
+        if (!s || typeof s !== "object" || typeof s.name !== "string") {
+            throw new Error(`--mcp-config '${path}': every server entry must be an object with a 'name' string`);
+        }
+    }
+    return servers;
+}
 const connectedClients = [];
 let exitHandlerInstalled = false;
 function installExitHandler() {
@@ -28,11 +73,20 @@ function installExitHandler() {
 }
 /** Threshold: servers with more tools than this use deferred loading */
 const DEFERRED_THRESHOLD = 10;
-/** Load MCP tools from .oh/config.yaml mcpServers list. Returns empty array if none configured. */
-export async function loadMcpTools() {
+/** Load MCP tools from .oh/config.yaml mcpServers list (and/or `--mcp-config` overrides). Returns empty array if none configured. */
+export async function loadMcpTools(opts = {}) {
     installExitHandler();
     const cfg = readOhConfig();
-    const servers = cfg?.mcpServers ?? [];
+    const fromConfig = opts.strict ? [] : (cfg?.mcpServers ?? []);
+    const fromExtra = opts.extraServers ?? [];
+    // Dedup by name — extras win on conflict so --mcp-config can override a
+    // project-config entry without --strict.
+    const byName = new Map();
+    for (const s of fromConfig)
+        byName.set(s.name, s);
+    for (const s of fromExtra)
+        byName.set(s.name, s);
+    const servers = Array.from(byName.values());
     if (servers.length === 0)
         return [];
     const tools = [];
@@ -45,10 +99,12 @@ export async function loadMcpTools() {
     for (const result of results) {
         if (result.status === "rejected") {
             console.warn(`[mcp] Failed to connect: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+            debug("mcp", "connect failed", result.reason);
             continue;
         }
         const { client, defs, server } = result.value;
         connectedClients.push(client);
+        debug("mcp", "connected", { server: server.name, tools: defs.length, deferred: defs.length > DEFERRED_THRESHOLD });
         if (defs.length > DEFERRED_THRESHOLD) {
             for (const def of defs) {
                 tools.push(new DeferredMcpTool(client, def.name, def.description ?? "", server.riskLevel));

package/dist/mcp/roots.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP `roots/list` responder (audit B3).
+ *
+ * The MCP spec lets a server ask the client "which file system roots are in
+ * scope?" via the `roots/list` request. This module owns OH's answer.
+ *
+ * Roots are computed at request time (no caching) so a `cd` inside the REPL
+ * or a future `--add-dir` flag flip is reflected immediately. The set is:
+ *   - process.cwd() — always included
+ *   - any directories supplied via `setExtraRoots()` — for `--add-dir` /
+ *     `/add-dir` integrations once they're properly wired (audit A7 deferred).
+ *
+ * Pure module with one mutable Set; the SDK handler in `transport.ts` calls
+ * `getRoots()` at request time. Exported `setExtraRoots` lets later wiring
+ * extend the set without restarting the MCP connection.
+ */
+export interface McpRoot {
+    uri: string;
+    name?: string;
+}
+/**
+ * Build the current root list. Always includes the process cwd. Extra roots
+ * (added via `setExtraRoots`) are deduplicated against the cwd. Each root is
+ * a `file://` URI per the MCP spec; `name` is the basename for readability.
+ */
+export declare function getRoots(): McpRoot[];
+/**
+ * Replace the extra-roots set. Empty array clears it. Idempotent — passing
+ * the same set twice is a no-op for downstream observers.
+ *
+ * @internal Public for tests + future `--add-dir` wiring.
+ */
+export declare function setExtraRoots(paths: readonly string[]): void;
+/** @internal Test-only reset. */
+export declare function _resetRootsForTest(): void;
+//# sourceMappingURL=roots.d.ts.map

package/dist/mcp/roots.js

@@ -0,0 +1,56 @@
+/**
+ * MCP `roots/list` responder (audit B3).
+ *
+ * The MCP spec lets a server ask the client "which file system roots are in
+ * scope?" via the `roots/list` request. This module owns OH's answer.
+ *
+ * Roots are computed at request time (no caching) so a `cd` inside the REPL
+ * or a future `--add-dir` flag flip is reflected immediately. The set is:
+ *   - process.cwd() — always included
+ *   - any directories supplied via `setExtraRoots()` — for `--add-dir` /
+ *     `/add-dir` integrations once they're properly wired (audit A7 deferred).
+ *
+ * Pure module with one mutable Set; the SDK handler in `transport.ts` calls
+ * `getRoots()` at request time. Exported `setExtraRoots` lets later wiring
+ * extend the set without restarting the MCP connection.
+ */
+import { pathToFileURL } from "node:url";
+const extraRoots = new Set();
+/**
+ * Build the current root list. Always includes the process cwd. Extra roots
+ * (added via `setExtraRoots`) are deduplicated against the cwd. Each root is
+ * a `file://` URI per the MCP spec; `name` is the basename for readability.
+ */
+export function getRoots() {
+    const seen = new Set();
+    const out = [];
+    const push = (path) => {
+        if (!path || seen.has(path))
+            return;
+        seen.add(path);
+        const uri = pathToFileURL(path).toString();
+        const segments = path.split(/[\\/]/).filter(Boolean);
+        const name = segments[segments.length - 1] ?? path;
+        out.push({ uri, name });
+    };
+    push(process.cwd());
+    for (const p of extraRoots)
+        push(p);
+    return out;
+}
+/**
+ * Replace the extra-roots set. Empty array clears it. Idempotent — passing
+ * the same set twice is a no-op for downstream observers.
+ *
+ * @internal Public for tests + future `--add-dir` wiring.
+ */
+export function setExtraRoots(paths) {
+    extraRoots.clear();
+    for (const p of paths)
+        extraRoots.add(p);
+}
+/** @internal Test-only reset. */
+export function _resetRootsForTest() {
+    extraRoots.clear();
+}
+//# sourceMappingURL=roots.js.map

package/dist/mcp/transport.js

@@ -4,6 +4,9 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { ElicitRequestSchema, ListRootsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { resolveElicitation } from "./elicitation.js";
+import { getRoots } from "./roots.js";
 const pkg = createRequire(import.meta.url)("../../package.json");
 export class RemoteAuthRequiredError extends Error {
     serverName;
@@ -136,7 +139,30 @@ function hasAwaitCallback(p) {
  */
 export async function buildClient(cfg, opts = {}) {
     const transport = await buildTransport(cfg, opts);
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
+    // Advertise the `roots` capability (audit B3) so MCP servers know they
+    // can ask OH which file system roots are in scope, and the `elicitation`
+    // capability (audit B4) so they can request user input. listChanged on
+    // roots is false — OH doesn't push notifications when the cwd changes;
+    // servers re-query on demand.
+    const client = new Client(CLIENT_INFO, {
+        capabilities: { roots: { listChanged: false }, elicitation: {} },
+    });
+    client.setRequestHandler(ListRootsRequestSchema, () => ({ roots: getRoots() }));
+    // Elicitation handler — only the form-mode (requestedSchema) variant is
+    // supported. URL-mode elicitations decline by default — we don't open
+    // browsers from the MCP path. Cast `as never` lets the SDK's wide union
+    // accept our narrower response shape.
+    client.setRequestHandler(ElicitRequestSchema, async (request) => {
+        const params = request.params;
+        if (params.requestedSchema === undefined) {
+            return { action: "decline" };
+        }
+        return (await resolveElicitation({
+            serverName: cfg.name,
+            message: params.message,
+            requestedSchema: params.requestedSchema,
+        }));
+    });
     const timeoutMs = cfg.timeout ?? DEFAULT_TIMEOUT_MS;
     async function tryConnect() {
         let timer = null;
@@ -175,9 +201,25 @@ export async function buildClient(cfg, opts = {}) {
                 catch {
                     // best-effort
                 }
-                // Build a fresh transport + client for the authenticated retry
+                // Build a fresh transport + client for the authenticated retry — same
+                // capabilities + handlers as the initial client (audit B3 roots,
+                // audit B4 elicitation).
                 const freshTransport = await buildTransport(cfg, opts);
-                const freshClient = new Client(CLIENT_INFO, { capabilities: {} });
+                const freshClient = new Client(CLIENT_INFO, {
+                    capabilities: { roots: { listChanged: false }, elicitation: {} },
+                });
+                freshClient.setRequestHandler(ListRootsRequestSchema, () => ({ roots: getRoots() }));
+                freshClient.setRequestHandler(ElicitRequestSchema, async (request) => {
+                    const params = request.params;
+                    if (params.requestedSchema === undefined) {
+                        return { action: "decline" };
+                    }
+                    return (await resolveElicitation({
+                        serverName: cfg.name,
+                        message: params.message,
+                        requestedSchema: params.requestedSchema,
+                    }));
+                });
                 let freshTimer = null;
                 try {
                     await Promise.race([

package/dist/providers/index.d.ts

@@ -4,11 +4,35 @@
 import type { Provider, ProviderConfig } from "./base.js";
 /**
  * Create a provider from a model string like "ollama/llama3" or "gpt-4o".
+ *
+ * `opts.fallbackModel` (audit B2) is the CLI override path for the existing
+ * `fallbackProviders` config — when set, REPLACES the config-file fallbacks
+ * with a single entry derived from the model string. Mirrors Claude Code's
+ * `--fallback-model <model>` for one-shot CI runs that want a fallback
+ * without editing `.oh/config.yaml`. Format matches `modelArg`:
+ * `provider/model` or just `model` (provider guessed). When unset, the
+ * existing config-file path is unchanged.
  */
-export declare function createProvider(modelArg?: string, overrides?: Partial<ProviderConfig>): Promise<{
+export declare function createProvider(modelArg?: string, overrides?: Partial<ProviderConfig>, opts?: {
+    fallbackModel?: string;
+}): Promise<{
     provider: Provider;
     model: string;
 }>;
+/**
+ * Parse `--fallback-model <value>` into the same shape as a `fallbackProviders[]`
+ * entry. Accepts `provider/model` (explicit) or just `model` (provider guessed
+ * via `guessProviderFromModel`, same as the primary modelArg). Exposed for
+ * tests.
+ *
+ * @internal
+ */
+export declare function parseFallbackModel(raw: string): {
+    provider: string;
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+};
 export { createProviderInstance, guessProviderFromModel };
 declare function createProviderInstance(name: string, config: ProviderConfig): Provider;
 declare function guessProviderFromModel(model: string): string;

package/dist/providers/index.js

@@ -10,8 +10,16 @@ import { OpenAIProvider } from "./openai.js";
 import { OpenRouterProvider } from "./openrouter.js";
 /**
  * Create a provider from a model string like "ollama/llama3" or "gpt-4o".
+ *
+ * `opts.fallbackModel` (audit B2) is the CLI override path for the existing
+ * `fallbackProviders` config — when set, REPLACES the config-file fallbacks
+ * with a single entry derived from the model string. Mirrors Claude Code's
+ * `--fallback-model <model>` for one-shot CI runs that want a fallback
+ * without editing `.oh/config.yaml`. Format matches `modelArg`:
+ * `provider/model` or just `model` (provider guessed). When unset, the
+ * existing config-file path is unchanged.
  */
-export async function createProvider(modelArg, overrides) {
+export async function createProvider(modelArg, overrides, opts = {}) {
     let providerName = "ollama";
     let model = "llama3";
     if (modelArg) {
@@ -32,7 +40,9 @@ export async function createProvider(modelArg, overrides) {
         ...overrides,
     };
     const primary = createProviderInstance(providerName, config);
-    const fallbackCfgs = readOhConfig()?.fallbackProviders ?? [];
+    const fallbackCfgs = opts.fallbackModel
+        ? [parseFallbackModel(opts.fallbackModel)]
+        : (readOhConfig()?.fallbackProviders ?? []);
     if (fallbackCfgs.length === 0) {
         return { provider: primary, model };
     }
@@ -48,6 +58,21 @@ export async function createProvider(modelArg, overrides) {
     const wrapped = createFallbackProvider(primary, fallbacks);
     return { provider: wrapped, model };
 }
+/**
+ * Parse `--fallback-model <value>` into the same shape as a `fallbackProviders[]`
+ * entry. Accepts `provider/model` (explicit) or just `model` (provider guessed
+ * via `guessProviderFromModel`, same as the primary modelArg). Exposed for
+ * tests.
+ *
+ * @internal
+ */
+export function parseFallbackModel(raw) {
+    if (raw.includes("/")) {
+        const [p, m] = raw.split("/", 2);
+        return { provider: p, model: m };
+    }
+    return { provider: guessProviderFromModel(raw), model: raw };
+}
 export { createProviderInstance, guessProviderFromModel };
 function createProviderInstance(name, config) {
     switch (name) {

package/dist/query/index.js

@@ -311,7 +311,7 @@ export async function* query(userMessage, config, existingMessages = []) {
         // Execute remaining tools not started during streaming
         const remaining = toolCalls.filter((tc) => !executedIds.has(tc.id));
         if (remaining.length > 0) {
-            yield* executeToolCalls(remaining, config.tools, toolContext, config.permissionMode, config.askUser, state);
+            yield* executeToolCalls(remaining, config.tools, toolContext, config.permissionMode, config.askUser, state, config.permissionPromptTool);
         }
         state.lastTurnHadTools = toolCalls.length > 0;
         state.lastTurnToolCount = toolCalls.length;

package/dist/query/tools.d.ts

@@ -11,7 +11,7 @@ type Batch = {
     calls: ToolCall[];
 };
 export declare function partitionToolCalls(toolCalls: ToolCall[], tools: Tools): Batch[];
-export declare function executeSingleTool(toolCall: ToolCall, tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn): Promise<ToolResult>;
-export declare function executeToolCalls(toolCalls: ToolCall[], tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, state?: QueryLoopState): AsyncGenerator<StreamEvent, void>;
+export declare function executeSingleTool(toolCall: ToolCall, tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, permissionPromptTool?: string): Promise<ToolResult>;
+export declare function executeToolCalls(toolCalls: ToolCall[], tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, state?: QueryLoopState, permissionPromptTool?: string): AsyncGenerator<StreamEvent, void>;
 export {};
 //# sourceMappingURL=tools.d.ts.map

package/dist/query/tools.js

@@ -8,6 +8,42 @@ import { createToolResultMessage } from "../types/message.js";
 import { checkPermission } from "../types/permissions.js";
 const MAX_TOOL_RESULT_CHARS = 100_000;
 const TOOL_TIMEOUT_MS = 120_000;
+/**
+ * Invoke the configured `--permission-prompt-tool` (audit B1). The tool is
+ * looked up by name in the active tool registry (so MCP tools wired through
+ * `loadMcpTools` are reachable). Failure modes — missing tool, exception
+ * during call, malformed JSON, unknown `behavior` — collapse into
+ * `behavior: "fallthrough"` so the caller can try the next branch
+ * (interactive prompt or headless deny). A broken permission tool must
+ * not lock the user out.
+ */
+async function callPermissionPromptTool(toolName, tools, context, permissionedToolName, permissionedInput) {
+    const promptTool = findToolByName(tools, toolName);
+    if (!promptTool)
+        return { behavior: "fallthrough" };
+    let raw;
+    try {
+        raw = await promptTool.call({ tool_name: permissionedToolName, input: permissionedInput }, context);
+    }
+    catch {
+        return { behavior: "fallthrough" };
+    }
+    if (raw.isError)
+        return { behavior: "fallthrough" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.output);
+    }
+    catch {
+        return { behavior: "fallthrough" };
+    }
+    if (parsed.behavior === "allow")
+        return { behavior: "allow" };
+    if (parsed.behavior === "deny") {
+        return parsed.message ? { behavior: "deny", message: parsed.message } : { behavior: "deny" };
+    }
+    return { behavior: "fallthrough" };
+}
 export function partitionToolCalls(toolCalls, tools) {
     const batches = [];
     let currentConcurrent = [];
@@ -30,7 +66,7 @@ export function partitionToolCalls(toolCalls, tools) {
     }
     return batches;
 }
-export async function executeSingleTool(toolCall, tools, context, permissionMode, askUser) {
+export async function executeSingleTool(toolCall, tools, context, permissionMode, askUser, permissionPromptTool) {
     const tool = findToolByName(tools, toolCall.toolName);
     if (!tool) {
         return { output: `Error: Unknown tool '${toolCall.toolName}'`, isError: true };
@@ -72,6 +108,34 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 const reason = hookOutcome.reason ? `: ${hookOutcome.reason}` : "";
                 return denyAndEmit("hook", hookOutcome.reason ?? "hook denied", `Permission denied by hook${reason}`);
             }
+            else if (permissionPromptTool) {
+                // No hook decision → consult the configured MCP permission tool
+                // (audit B1). Mirrors Claude Code's --permission-prompt-tool. The
+                // tool returns JSON: { "behavior": "allow" | "deny", "message"?: string }.
+                // On any failure (tool missing, throws, malformed JSON, unknown
+                // behavior) we fall through to askUser / headless deny so a broken
+                // permission tool doesn't lock the user out.
+                const promptDecision = await callPermissionPromptTool(permissionPromptTool, tools, context, tool.name, parsed.data);
+                if (promptDecision.behavior === "allow") {
+                    // Permission tool granted — proceed.
+                }
+                else if (promptDecision.behavior === "deny") {
+                    return denyAndEmit("permission-prompt-tool", promptDecision.message ?? "denied", `Permission denied by ${permissionPromptTool}${promptDecision.message ? `: ${promptDecision.message}` : ""}`);
+                }
+                else if (askUser) {
+                    // promptDecision.behavior === "fallthrough" — tool was unavailable
+                    // or its response was malformed. Try the interactive prompt next.
+                    const { formatToolArgs } = await import("../utils/tool-summary.js");
+                    const description = formatToolArgs(tool.name, toolCall.arguments);
+                    const allowed = await askUser(tool.name, description, tool.riskLevel);
+                    if (!allowed) {
+                        return denyAndEmit("user", "user declined", "Permission denied by user.");
+                    }
+                }
+                else {
+                    return denyAndEmit("headless", "permission-prompt-tool unavailable and no interactive prompt", `Permission denied: ${permissionPromptTool} did not produce a usable decision and no interactive prompt is available.`);
+                }
+            }
             else if (askUser) {
                 // "ask" or no decision → interactive prompt when available
                 const { formatToolArgs } = await import("../utils/tool-summary.js");
@@ -209,7 +273,7 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
         return { output: `Tool error: ${errMsg}`, isError: true };
     }
 }
-export async function* executeToolCalls(toolCalls, tools, context, permissionMode, askUser, state) {
+export async function* executeToolCalls(toolCalls, tools, context, permissionMode, askUser, state, permissionPromptTool) {
     const batches = partitionToolCalls(toolCalls, tools);
     const outputChunks = [];
     const onOutputChunk = (callId, chunk) => {
@@ -218,7 +282,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
     const allToolNames = toolCalls.map((tc) => tc.toolName);
     for (const batch of batches) {
         if (batch.concurrent) {
-            const results = await Promise.all(batch.calls.map((tc) => executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser)));
+            const results = await Promise.all(batch.calls.map((tc) => executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser, permissionPromptTool)));
             for (const chunk of outputChunks.splice(0))
                 yield chunk;
             for (let i = 0; i < batch.calls.length; i++) {
@@ -230,7 +294,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
         }
         else {
             for (const tc of batch.calls) {
-                const result = await executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser);
+                const result = await executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser, permissionPromptTool);
                 for (const chunk of outputChunks.splice(0))
                     yield chunk;
                 yield { type: "tool_call_end", callId: tc.id, output: result.output, isError: result.isError };