@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/tool-system/permission.js

@@ -6,6 +6,96 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "
 import { randomUUID } from "node:crypto";
 import { logger as rootPermLogger } from "../logging/logger.js";
 import { READ_ONLY_TOOLS } from "./plan-mode-allowlist.js";
+/**
+ * Process-local connection owner router. Handlers are connection-scoped while
+ * session ownership is an explicit binding with a monotonic generation.
+ */
+export class ApprovalRouter {
+    handlers = new Map();
+    owners = new Map();
+    fallbackConnections = new Set();
+    nextGeneration = 1;
+    addConnection(connectionId, handler, options) {
+        if (!connectionId)
+            throw new Error("approval connectionId is required");
+        if (this.handlers.has(connectionId)) {
+            throw new Error(`approval connection already registered: ${connectionId}`);
+        }
+        this.handlers.set(connectionId, handler);
+        if (options?.claimUnownedSessions)
+            this.fallbackConnections.add(connectionId);
+        return () => this.deregister(connectionId);
+    }
+    register(sessionId, connectionId) {
+        if (!sessionId)
+            throw new Error("approval sessionId is required");
+        if (!this.handlers.has(connectionId)) {
+            throw new Error(`approval connection is not registered: ${connectionId}`);
+        }
+        const current = this.owners.get(sessionId);
+        if (current?.connectionId === connectionId)
+            return { ok: true, target: current };
+        if (current)
+            return { ok: false, conflict: current };
+        const target = { connectionId, sessionId, generation: this.nextGeneration++ };
+        this.owners.set(sessionId, target);
+        return { ok: true, target };
+    }
+    resolve(request) {
+        if (!request.sessionId)
+            return null;
+        let target = this.owners.get(request.sessionId);
+        if (!target && this.fallbackConnections.size === 1) {
+            const connectionId = this.fallbackConnections.values().next().value;
+            if (connectionId) {
+                const registration = this.register(request.sessionId, connectionId);
+                if (registration.ok)
+                    target = registration.target;
+            }
+        }
+        if (!target)
+            return null;
+        const handler = this.handlers.get(target.connectionId);
+        if (!handler) {
+            this.owners.delete(request.sessionId);
+            return null;
+        }
+        return handler.requestApproval(request, target);
+    }
+    matches(target) {
+        const current = this.owners.get(target.sessionId);
+        return (current?.connectionId === target.connectionId && current.generation === target.generation);
+    }
+    current(sessionId) {
+        return this.owners.get(sessionId) ?? null;
+    }
+    release(sessionId, connectionId, reason = "approval session released") {
+        const current = this.owners.get(sessionId);
+        if (!current || current.connectionId !== connectionId)
+            return;
+        this.owners.delete(sessionId);
+        this.handlers.get(connectionId)?.ownershipLost?.([current], reason);
+    }
+    deregister(connectionId, reason = "approval connection disconnected") {
+        const handler = this.handlers.get(connectionId);
+        if (!handler)
+            return;
+        this.handlers.delete(connectionId);
+        this.fallbackConnections.delete(connectionId);
+        const lost = [];
+        for (const [sessionId, target] of this.owners) {
+            if (target.connectionId !== connectionId)
+                continue;
+            this.owners.delete(sessionId);
+            lost.push(target);
+        }
+        if (lost.length > 0)
+            handler.ownershipLost?.(lost, reason);
+    }
+    hasConnections() {
+        return this.handlers.size > 0;
+    }
+}
 export class HeadlessApprovalBackend {
     mode;
     constructor(mode) {
@@ -117,6 +207,7 @@ export const CLOSED_SESSION_TOMBSTONE_LIMIT = 4096;
  * the next time the user opens the project.
  */
 export class InteractiveApprovalBackend {
+    approvalRouter;
     // Session-scoped grants are bucketed by ApprovalRequest.sessionId and then
     // keyed on the OPERATION (tool + narrowed argsPattern via buildProjectRule),
     // NOT just the tool name. Approving `git status` for one session must not
@@ -132,18 +223,25 @@ export class InteractiveApprovalBackend {
         savedProjectRules: [],
         onProjectRules: null,
     };
+    constructor(approvalRouter = new ApprovalRouter()) {
+        this.approvalRouter = approvalRouter;
+    }
     setPromptFn(fn) {
         this.promptFn = fn;
     }
+    clearPromptFn() {
+        this.promptFn = null;
+    }
     /**
      * Has someone installed a real prompt callback? Engine consults this
      * to decide whether to use the interactive backend (= talk to a UI)
      * or fall back to HeadlessApprovalBackend (= deny-all). Without it,
-     * the agent-server-stdio entry — which wires setInteractiveApprovalFn
-     * during server boot — would still fall through to deny-all because
+     * a protocol host registers its connection with ApprovalRouter during boot
+     * but before the first session is bound — without this check Engine would
+     * still fall through to deny-all because
      * the engine couldn't tell the difference. */
     hasPromptFn() {
-        return this.promptFn !== null;
+        return this.promptFn !== null || this.approvalRouter.hasConnections();
     }
     /** Inject the project root so persistence writes to the right settings file. */
     setCwd(cwd) {
@@ -220,7 +318,7 @@ export class InteractiveApprovalBackend {
         const cached = state ? this.checkSessionRules(req, state) : null;
         if (cached)
             return cached;
-        if (!this.promptFn) {
+        if (!this.promptFn && !this.approvalRouter.hasConnections()) {
             return { approved: false, reason: "interactive approval backend has no prompt function" };
         }
         // Serialize prompts and re-check rules when our turn comes (see promptTurn
@@ -261,10 +359,27 @@ export class InteractiveApprovalBackend {
     }
     /** The actual interactive ask + rule recording (runs inside the prompt turn). */
     async promptAndRecord(req, state) {
-        if (!this.promptFn) {
+        const hasOwner = !!req.sessionId && this.approvalRouter.current(req.sessionId) !== null;
+        const routed = hasOwner ? this.approvalRouter.resolve(req) : null;
+        let result;
+        if (routed) {
+            result = await routed;
+        }
+        else if (this.promptFn) {
+            result = await this.promptFn(req);
+        }
+        else if (req.sessionId && this.approvalRouter.hasConnections()) {
+            const fallback = this.approvalRouter.resolve(req);
+            result = fallback
+                ? await fallback
+                : {
+                    approved: false,
+                    reason: `no approval connection owns session ${req.sessionId}`,
+                };
+        }
+        else {
             return { approved: false, reason: "interactive approval backend has no prompt function" };
         }
-        const result = await this.promptFn(req);
         const scope = result.scope ?? (result.always ? "session" : "once");
         const activeState = this.isActiveSessionState(req.sessionId, state) ? state : null;
         const context = activeState ?? (!req.sessionId ? this.legacyContext : null);
@@ -521,11 +636,15 @@ function persistProjectRule(cwd, rule) {
     writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", "utf-8");
     renameSync(tmp, file);
 }
-// Singleton interactive backend for use by the UI
+// Singleton interactive backend and its multi-connection owner router.
+const _approvalRouter = new ApprovalRouter();
 let _interactiveBackend = null;
+export function getApprovalRouter() {
+    return _approvalRouter;
+}
 export function getInteractiveApprovalBackend() {
     if (!_interactiveBackend) {
-        _interactiveBackend = new InteractiveApprovalBackend();
+        _interactiveBackend = new InteractiveApprovalBackend(_approvalRouter);
     }
     return _interactiveBackend;
 }
@@ -535,9 +654,6 @@ export function openInteractiveApprovalSession(sessionId) {
 export function clearInteractiveApprovalSession(sessionId) {
     getInteractiveApprovalBackend().clearSession(sessionId);
 }
-export function setInteractiveApprovalFn(fn) {
-    getInteractiveApprovalBackend().setPromptFn(fn);
-}
 const DANGEROUS_PATTERNS = [
     /rm\s+-rf/,
     /rm\s+-r\s+\//,
@@ -570,9 +686,6 @@ const SAFE_READ_PATTERNS = [
     // are NOT classified safe-read. Plain predicates (-name, -type, -print) stay.
     /^find\s(?!.*\s-(delete|exec(dir)?|ok(dir)?|fprintf?|fls)\b)/,
     /^(grep|rg|ag|ack|fgrep|egrep)\s/,
-    // Word-boundary the git read subcommands so `git difftool -x <cmd>` (which
-    // runs an arbitrary external command) does NOT match on the `diff` branch.
-    /^(git\s+(status|log|diff|branch|show|blame|remote|tag|stash\s+list|rev-parse|describe))\b/,
     /^(node|python|ruby|go|rustc|java|javac)\s+--version/,
     /^(npm|pnpm|yarn|cargo|pip|gem|brew)\s+(list|ls|info|show|view|outdated|audit)/,
     /^pwd$/,
@@ -583,6 +696,151 @@ const SAFE_READ_PATTERNS = [
     /^env$/,
     /^printenv/,
 ];
+/** Split a command conservatively enough to validate git's argument shape. */
+function splitShellWords(input) {
+    const words = [];
+    let word = "";
+    let quote = null;
+    let hasWord = false;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (quote === null && /\s/.test(ch)) {
+            if (hasWord) {
+                words.push(word);
+                word = "";
+                hasWord = false;
+            }
+            continue;
+        }
+        if (ch === "\\" && quote !== "'") {
+            const next = input[++i];
+            if (next === undefined)
+                return null;
+            word += next;
+            hasWord = true;
+            continue;
+        }
+        // Single quotes make expansion syntax literal. Outside them, reject all
+        // parameter/command expansion rather than let expansion change a vetted
+        // git argument into an unsafe option or action at execution time.
+        if (quote !== "'" && (ch === "$" || ch === "`"))
+            return null;
+        if (ch === "'" || ch === '"') {
+            if (quote === null) {
+                quote = ch;
+                hasWord = true;
+                continue;
+            }
+            if (quote === ch) {
+                quote = null;
+                continue;
+            }
+        }
+        word += ch;
+        hasWord = true;
+    }
+    if (quote !== null)
+        return null;
+    if (hasWord)
+        words.push(word);
+    return words;
+}
+const GIT_LIST_STANDALONE_OPTIONS = new Set([
+    "--all",
+    "--color",
+    "--column",
+    "--ignore-case",
+    "--no-abbrev",
+    "--no-color",
+    "--no-column",
+    "--omit-empty",
+    "--remotes",
+    "--show-current",
+    "--verbose",
+    "-a",
+    "-r",
+    "-v",
+    "-vv",
+]);
+const GIT_LIST_VALUE_OPTIONS = new Set([
+    "--contains",
+    "--format",
+    "--merged",
+    "--no-contains",
+    "--no-merged",
+    "--points-at",
+    "--sort",
+]);
+const GIT_SAFE_GLOBAL_OPTIONS = new Set(["--no-pager", "--no-optional-locks"]);
+function isSafeGitListArgs(args) {
+    let listMode = false;
+    let positionalOnly = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (positionalOnly)
+            continue;
+        if (arg === "--") {
+            if (!listMode)
+                return false;
+            positionalOnly = true;
+            continue;
+        }
+        if (arg === "-l" || arg === "--list") {
+            listMode = true;
+            continue;
+        }
+        if (GIT_LIST_STANDALONE_OPTIONS.has(arg))
+            continue;
+        if ([...GIT_LIST_STANDALONE_OPTIONS, ...GIT_LIST_VALUE_OPTIONS].some((option) => arg.startsWith(`${option}=`))) {
+            continue;
+        }
+        if (GIT_LIST_VALUE_OPTIONS.has(arg)) {
+            if (++i >= args.length)
+                return false;
+            continue;
+        }
+        if (listMode && !arg.startsWith("-"))
+            continue;
+        return false;
+    }
+    return true;
+}
+/**
+ * Git is safe-read only for an explicit read subcommand and a read-only
+ * argument shape. In particular, branch/tag positional creation and all
+ * remote sub-actions fail closed instead of inheriting safety from the
+ * subcommand name.
+ */
+function isSafeReadGitCommand(segment) {
+    const words = splitShellWords(segment.trim());
+    if (!words || words[0] !== "git")
+        return false;
+    let subcommandIndex = 1;
+    while (GIT_SAFE_GLOBAL_OPTIONS.has(words[subcommandIndex]))
+        subcommandIndex++;
+    const subcommand = words[subcommandIndex];
+    const args = words.slice(subcommandIndex + 1);
+    const hasWriteOrExecutionOption = (gitArgs) => gitArgs.some((arg) => arg === "--ext-diff" ||
+        arg === "--textconv" ||
+        arg === "--output" ||
+        arg.startsWith("--output="));
+    if (["status", "log", "diff", "show", "blame", "rev-parse", "describe"].includes(subcommand)) {
+        return !hasWriteOrExecutionOption(args);
+    }
+    if (subcommand === "stash") {
+        return args[0] === "list" && !hasWriteOrExecutionOption(args.slice(1));
+    }
+    if (subcommand === "branch" || subcommand === "tag")
+        return isSafeGitListArgs(args);
+    if (subcommand === "remote") {
+        return args.every((arg) => arg === "-v" || arg === "--verbose");
+    }
+    return false;
+}
+function matchesSafeReadPattern(segment, allowArgumentless = false) {
+    return (isSafeReadGitCommand(segment) ||
+        SAFE_READ_PATTERNS.some((pattern) => pattern.test(segment) || (allowArgumentless && pattern.test(`${segment} `))));
+}
 // ─── Sensitive safe-read downgrade ────────────────────────────────
 //
 // `Read ~/.ssh/id_rsa` routes through path-policy (asks); the equivalent
@@ -643,17 +901,61 @@ const SAFE_WRITE_PATTERNS = [
 //   - top-level `;`, `&&`, `||`, newline split the command into
 //     segments. Every segment must independently classify as safe
 //     for the whole command to be safe.
-//   - unquoted command substitution (` ` ` or `$(` ), redirection
+//   - command substitution (` ` ` or `$(` ) outside single quotes, redirection
 //     (`>` `>>` `<` `<<`), process substitution (`<(` `>(`), and
 //     pipe-to-shell (`| sh`, `| bash`, ...) flag the command as
 //     dangerous.
-//   - quoted (`'…'`, `"…"`) and backslash-escaped characters are
-//     ignored — `echo "a; b"` is a single segment.
+//   - single quotes make command-substitution syntax literal; double quotes
+//     do not. Other quoted and backslash-escaped metacharacters are ignored —
+//     `echo "a; b"` is a single segment.
 //
 // This is intentionally detection-only, not a full shell parser. We
 // only need to find unquoted metacharacters and split safely.
-const PIPE_TO_SHELL_RE = /\|\s*(sh|bash|zsh|dash|ksh|fish|python|python3|node|nodejs|ruby|perl|php)\b/;
+const PIPE_SHELL_COMMAND_RE = /^(sh|bash|zsh|dash|ksh|fish|python|python3|node|nodejs|ruby|perl|php)\b/;
+/** Apply Bash line continuation before inspecting shell syntax. */
+function normalizeShellLineContinuations(input) {
+    let normalized = "";
+    let quote = null;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        const next = input[i + 1];
+        // Backslash-newline remains literal inside single quotes.
+        if (quote === "'") {
+            if (ch === quote)
+                quote = null;
+            normalized += ch;
+            continue;
+        }
+        if (ch === "\\") {
+            if (next === "\n") {
+                i++;
+                continue;
+            }
+            if (next === "\r" && input[i + 2] === "\n") {
+                i += 2;
+                continue;
+            }
+            // Preserve other escapes verbatim and do not treat an escaped quote as
+            // changing the quote state used by this normalization pass.
+            normalized += ch;
+            if (next !== undefined) {
+                normalized += next;
+                i++;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            if (quote === null)
+                quote = ch;
+            else if (quote === ch)
+                quote = null;
+        }
+        normalized += ch;
+    }
+    return normalized;
+}
 function scanShellCommand(input) {
+    const normalizedInput = normalizeShellLineContinuations(input);
     const segments = [];
     let buf = "";
     let dangerous = false;
@@ -668,9 +970,9 @@ function scanShellCommand(input) {
             segments.push(s);
         buf = "";
     };
-    while (i < input.length) {
-        const ch = input[i];
-        const next = input[i + 1];
+    while (i < normalizedInput.length) {
+        const ch = normalizedInput[i];
+        const next = normalizedInput[i + 1];
         if (quote === null) {
             // Escape: skip the next character
             if (ch === "\\" && next !== undefined) {
@@ -727,12 +1029,28 @@ function scanShellCommand(input) {
             i++;
             continue;
         }
-        // Inside a quote
+        // Inside single quotes, every character other than the closing quote is
+        // literal. In particular, `$(` and backticks do not execute.
+        if (quote === "'") {
+            if (ch === quote)
+                quote = null;
+            buf += ch;
+            i++;
+            continue;
+        }
+        // Inside double quotes, escapes still suppress substitution syntax, but
+        // unescaped `$(` and backticks execute and must fail closed.
         if (ch === "\\" && next !== undefined) {
             buf += ch + next;
             i += 2;
             continue;
         }
+        if (ch === "`" || (ch === "$" && next === "(")) {
+            dangerous = true;
+            buf += ch;
+            i++;
+            continue;
+        }
         if (ch === quote) {
             quote = null;
             buf += ch;
@@ -751,6 +1069,37 @@ function scanShellCommand(input) {
         dangerous = true;
     return { segments, dangerous };
 }
+/** Split only on real shell pipes, preserving pipes inside quotes or escapes. */
+function splitUnquotedPipes(input) {
+    const parts = [];
+    let buf = "";
+    let quote = null;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        const next = input[i + 1];
+        if (ch === "\\" && quote !== "'" && next !== undefined) {
+            buf += ch + next;
+            i++;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            if (quote === null)
+                quote = ch;
+            else if (quote === ch)
+                quote = null;
+            buf += ch;
+            continue;
+        }
+        if (ch === "|" && quote === null) {
+            parts.push(buf.trim());
+            buf = "";
+            continue;
+        }
+        buf += ch;
+    }
+    parts.push(buf.trim());
+    return parts;
+}
 function classifySegment(segment) {
     if (DANGEROUS_PATTERNS.some((p) => p.test(segment)))
         return "dangerous";
@@ -762,13 +1111,15 @@ function classifySegment(segment) {
     // `| nc ...` exfil tail — declaring a piped-to-network command safe-read.
     // We did not split on `|` in the scanner because pipes are not statement
     // boundaries; they're per-segment data flow.
-    if (segment.includes("|")) {
+    const parts = splitUnquotedPipes(segment);
+    if (parts.length > 1) {
         // A pipe part may be an argument-less command (`ls`, `pwd`) whose trailing
         // space was stripped along with the `|`. Test each part both as-is (for
         // `$`-anchored patterns like /^pwd$/) and with a trailing space appended
         // (for `\s`-delimited patterns like /^ls\s/), so neither form is missed.
-        const parts = segment.split("|").map((p) => p.trim());
-        const partIsSafeRead = (p) => SAFE_READ_PATTERNS.some((re) => re.test(p) || re.test(`${p} `));
+        if (parts.slice(1).some((part) => PIPE_SHELL_COMMAND_RE.test(part)))
+            return "dangerous";
+        const partIsSafeRead = (p) => matchesSafeReadPattern(p, true);
         if (parts.every(partIsSafeRead)) {
             // A sensitive read anywhere in the pipe (`cat ~/.ssh/id_rsa | base64`,
             // `env | grep KEY`) downgrades the whole pipe.
@@ -778,7 +1129,7 @@ function classifySegment(segment) {
         }
         return "unsafe";
     }
-    if (SAFE_READ_PATTERNS.some((p) => p.test(segment))) {
+    if (matchesSafeReadPattern(segment)) {
         return segmentIsSensitiveRead(segment) ? "unsafe" : "safe-read";
     }
     if (SAFE_WRITE_PATTERNS.some((p) => p.test(segment)))
@@ -803,8 +1154,6 @@ export function classifyBashCommand(command) {
     // separators we would split on.
     if (DANGEROUS_PATTERNS.some((p) => p.test(trimmed)))
         return "dangerous";
-    if (PIPE_TO_SHELL_RE.test(trimmed))
-        return "dangerous";
     const scan = scanShellCommand(trimmed);
     if (scan.dangerous)
         return "dangerous";
@@ -888,6 +1237,9 @@ export class PermissionClassifier {
      * tests and ad-hoc usages still write log lines.
      */
     log = rootPermLogger;
+    approvalStateListener;
+    approvalEventListener;
+    activeApprovalCount = 0;
     constructor(rules, defaultMode = "default", approvalBackend = new HeadlessApprovalBackend("deny-all")) {
         this.rules = rules;
         this.defaultMode = defaultMode;
@@ -896,6 +1248,27 @@ export class PermissionClassifier {
     setLogger(log) {
         this.log = log;
     }
+    setApprovalStateListener(listener) {
+        this.approvalStateListener = listener;
+    }
+    /**
+     * Observe interactive-approval lifecycle (requested → resolved). The engine
+     * wires this to the `notification` hook so plugins / settings hooks can
+     * react to "waiting for the user's decision" moments (system notification,
+     * IM ping, …). Listener errors are swallowed — observation must never
+     * affect the approval outcome.
+     */
+    setApprovalEventListener(listener) {
+        this.approvalEventListener = listener;
+    }
+    emitApprovalEvent(event) {
+        try {
+            this.approvalEventListener?.(event);
+        }
+        catch {
+            /* observers must not affect approval flow */
+        }
+    }
     /** Replace mode + backend in place so live tool execution sees the change. */
     reconfigure(mode, approvalBackend, rules) {
         this.defaultMode = mode;
@@ -919,12 +1292,16 @@ export class PermissionClassifier {
         // YOLO classifier for Bash commands
         if (toolName === "Bash") {
             const level = classifyBashCommand(String(args.command ?? ""));
+            // acceptEdits opts into workspace edits through the tool allowlist below;
+            // it never opts into unattended shell execution. Explicit rules were
+            // already honored above, and bypassPermissions returned before them.
+            if (this.defaultMode === "acceptEdits")
+                return "ask";
             if (level === "dangerous")
                 return "ask";
             if (level === "safe-read")
                 return "allow";
-            if (level === "safe-write" &&
-                (this.defaultMode === "acceptEdits" || this.defaultMode === "auto")) {
+            if (level === "safe-write" && this.defaultMode === "auto") {
                 return "allow";
             }
             if (level === "unsafe")
@@ -977,6 +1354,14 @@ export class PermissionClassifier {
             riskLevel,
         });
         let result;
+        this.activeApprovalCount++;
+        this.approvalStateListener?.(true, toolName);
+        this.emitApprovalEvent({
+            phase: "requested",
+            toolName,
+            riskLevel,
+            ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+        });
         try {
             const baseDescription = this.describeToolCall(toolName, args);
             const description = reason ? `${baseDescription}\n\nReason:\n${reason}` : baseDescription;
@@ -992,12 +1377,24 @@ export class PermissionClassifier {
             span.fail(err, { tool: toolName });
             throw err;
         }
+        finally {
+            this.activeApprovalCount = Math.max(0, this.activeApprovalCount - 1);
+            if (this.activeApprovalCount === 0)
+                this.approvalStateListener?.(false, toolName);
+        }
         if (result.approved) {
             this.denialTracker.recordSuccess(toolName);
         }
         else {
             this.denialTracker.record(toolName);
         }
+        this.emitApprovalEvent({
+            phase: "resolved",
+            toolName,
+            riskLevel,
+            approved: result.approved,
+            ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+        });
         span.end({
             tool: toolName,
             approved: result.approved,
@@ -1032,6 +1429,8 @@ export class PermissionClassifier {
             return "medium";
         if (toolName === "Bash")
             return "medium";
+        if (toolName === "Panel")
+            return args.action === "invoke" ? "medium" : "low";
         // Only genuinely read-only built-ins are "low" (the sole tier
         // AutoApprovalBackend approves with no delegate). Everything else —
         // crucially every MCP tool, which can delete records, send messages, or

package/dist/tool-system/registry.d.ts

@@ -2,27 +2,38 @@
  * Unified tool registry — built-in tools + MCP tools.
  */
 import type { RegisteredTool, ToolDefinition, ToolResult } from "../types.js";
-import { type BuiltinToolFn } from "./builtin/index.js";
+import { type BuiltinTool, type BuiltinToolGuard } from "./builtin/index.js";
 import type { ToolContext } from "./context.js";
 /**
  * Default execution timeout for any tool that does not declare its own
  * timeoutMs at registration time. Tools that need to run longer (Agent,
- * Arena, Bash, custom long-running tools) should set timeoutMs explicitly.
+ * Bash, or custom capability tools) should set timeoutMs explicitly.
  */
 export declare const DEFAULT_TOOL_TIMEOUT_MS = 120000;
 export interface ToolRegistryOptions {
     builtinTools?: readonly string[];
+    /** Core catalog plus any tools contributed by host capability packages. */
+    toolCatalog?: readonly BuiltinTool[];
 }
+type ToolImplementation = (args: Record<string, unknown>, ctx?: ToolContext) => Promise<unknown>;
 export declare class ToolRegistry {
     private tools;
     private builtinExecutors;
+    private availabilityGuards;
     constructor(options?: ToolRegistryOptions);
     private registerBuiltins;
-    registerTool(tool: RegisteredTool, executor?: BuiltinToolFn): void;
+    registerTool(tool: RegisteredTool, executor?: ToolImplementation): void;
+    /** Create an engine-local registry view without sharing mutable maps. */
+    fork(): ToolRegistry;
     unregisterTool(name: string): void;
     getToolDefinitions(): ToolDefinition[];
     getTool(name: string): RegisteredTool | undefined;
     hasTool(name: string): boolean;
+    /** Test/harness introspection: definitions without implementations are valid
+     * for some dynamic registrations, but every builtin catalog entry must have
+     * an executor. */
+    hasExecutor(name: string): boolean;
+    getAvailabilityGuard(name: string): BuiltinToolGuard | undefined;
     executeTool(name: string, args: Record<string, unknown>, options?: {
         timeoutMs?: number;
         signal?: AbortSignal;
@@ -31,3 +42,4 @@ export declare class ToolRegistry {
     listTools(): string[];
     listToolsDetailed(): RegisteredTool[];
 }
+export {};