@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/tool-system/registry.js

@@ -2,22 +2,26 @@
  * Unified tool registry — built-in tools + MCP tools.
  */
 import { ConfigError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, } from "../exceptions.js";
-import { BUILTIN_TOOLS } from "./builtin/index.js";
+import { BUILTIN_TOOLS, toToolExecutionResult, } from "./builtin/index.js";
 import { validateToolMetadata } from "./validate-tool-metadata.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 const DEFAULT_TOOL_TIMEOUT_MS = 120_000;
 export class ToolRegistry {
     tools = new Map();
     builtinExecutors = new Map();
+    availabilityGuards = new Map();
     constructor(options = {}) {
-        this.registerBuiltins(options.builtinTools);
+        this.registerBuiltins(options.builtinTools, options.toolCatalog ?? BUILTIN_TOOLS);
     }
-    registerBuiltins(selectedBuiltinTools) {
-        const availableNames = new Set(BUILTIN_TOOLS.map((tool) => tool.definition.name));
+    registerBuiltins(selectedBuiltinTools, toolCatalog) {
+        const availableNames = new Set(toolCatalog.map((tool) => tool.definition.name));
+        if (availableNames.size !== toolCatalog.length) {
+            throw new ConfigError("Tool catalog contains duplicate names");
+        }
         const selectedNames = selectedBuiltinTools ? new Set(selectedBuiltinTools) : null;
         if (selectedNames) {
             const unknown = [...selectedNames].filter((name) => !availableNames.has(name));
@@ -27,7 +31,7 @@ export class ToolRegistry {
                 });
             }
         }
-        for (const tool of BUILTIN_TOOLS) {
+        for (const tool of toolCatalog) {
             if (selectedNames && !selectedNames.has(tool.definition.name)) {
                 continue;
             }
@@ -36,24 +40,36 @@ export class ToolRegistry {
             validateToolMetadata(tool.definition);
             this.tools.set(tool.definition.name, tool.definition);
             this.builtinExecutors.set(tool.definition.name, tool.execute);
+            if (tool.exposure.availability) {
+                this.availabilityGuards.set(tool.definition.name, tool.exposure.availability);
+            }
         }
     }
     registerTool(tool, executor) {
         validateToolMetadata(tool);
         this.tools.set(tool.name, tool);
         if (executor) {
-            this.builtinExecutors.set(tool.name, executor);
+            this.builtinExecutors.set(tool.name, async (args, ctx) => toToolExecutionResult(await executor(args, ctx)));
         }
     }
+    /** Create an engine-local registry view without sharing mutable maps. */
+    fork() {
+        const fork = new ToolRegistry({ builtinTools: [] });
+        fork.tools = new Map(this.tools);
+        fork.builtinExecutors = new Map(this.builtinExecutors);
+        return fork;
+    }
     unregisterTool(name) {
         this.tools.delete(name);
         this.builtinExecutors.delete(name);
+        this.availabilityGuards.delete(name);
     }
     getToolDefinitions() {
         return [...this.tools.values()].map((t) => ({
             name: t.name,
             description: t.description,
             inputSchema: t.inputSchema,
+            sensitiveResult: t.sensitiveResult,
         }));
     }
     getTool(name) {
@@ -62,6 +78,15 @@ export class ToolRegistry {
     hasTool(name) {
         return this.tools.has(name);
     }
+    /** Test/harness introspection: definitions without implementations are valid
+     * for some dynamic registrations, but every builtin catalog entry must have
+     * an executor. */
+    hasExecutor(name) {
+        return this.builtinExecutors.has(name);
+    }
+    getAvailabilityGuard(name) {
+        return this.availabilityGuards.get(name);
+    }
     async executeTool(name, args, options) {
         const tool = this.tools.get(name);
         if (!tool) {
@@ -73,7 +98,7 @@ export class ToolRegistry {
         }
         // Tool timeout precedence:
         //   options.timeoutMs (per-call override) > tool.timeoutMs (declared at registration) > default 120s.
-        // To run longer, declare timeoutMs on the tool (e.g. Agent/Arena: 30min, Bash: 1h).
+        // To run longer, declare timeoutMs on the tool (e.g. Agent: 30min, Bash: 1h).
         const timeout = options?.timeoutMs ?? tool.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
         const parentSignal = options?.signal;
         const id = `tool_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
@@ -88,61 +113,78 @@ export class ToolRegistry {
         }
         // Create a child AbortController that aborts on timeout OR parent abort
         const childController = new AbortController();
+        let timedOut = false;
         const timerId = timeout > 0
-            ? setTimeout(() => childController.abort(new ToolTimeoutError(name, timeout)), timeout)
+            ? setTimeout(() => {
+                timedOut = true;
+                childController.abort(new ToolTimeoutError(name, timeout));
+            }, timeout)
             : undefined;
         // Cascade parent abort to child
         const onParentAbort = () => childController.abort(parentSignal?.reason);
         parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+        if (parentSignal?.aborted)
+            onParentAbort();
         // Inject the abort signal into args so tools (like Agent) can use it
         const argsWithSignal = { ...args, __signal: childController.signal };
         // Build per-call ctx: caller's ctx (if any) + this call's signal
         const ctx = options?.ctx
             ? { ...options.ctx, signal: childController.signal }
             : undefined;
-        try {
-            const result = await Promise.race([
-                executor(argsWithSignal, ctx),
-                new Promise((_, reject) => {
-                    childController.signal.addEventListener("abort", () => {
-                        const reason = childController.signal.reason;
-                        reject(reason instanceof ToolTimeoutError ? reason : new Error("Tool aborted"));
-                    }, { once: true });
-                }),
-            ]);
+        let onChildAbort;
+        const aborted = new Promise((_, reject) => {
+            onChildAbort = () => {
+                const reason = childController.signal.reason;
+                reject(reason instanceof Error
+                    ? reason
+                    : Object.assign(new Error("Tool aborted"), { name: "AbortError" }));
+            };
+            childController.signal.addEventListener("abort", onChildAbort, { once: true });
+            if (childController.signal.aborted)
+                onChildAbort();
+        });
+        const cleanup = () => {
             clearTimeout(timerId);
             parentSignal?.removeEventListener("abort", onParentAbort);
-            // executor 可返回纯字符串,或 { contentBlocks, result? }(view_image
-            // 用后者回传图片块)。归一化成 ToolResult:有 contentBlocks 就带上,
-            // result 始终保留一份文本镜像供 transcript / 摘要使用。
-            if (typeof result === "string") {
-                return { id, toolName: name, result };
+            if (onChildAbort)
+                childController.signal.removeEventListener("abort", onChildAbort);
+        };
+        try {
+            const rawResult = await Promise.race([executor(argsWithSignal, ctx), aborted]);
+            const result = toToolExecutionResult(rawResult);
+            if (childController.signal.aborted) {
+                throw childController.signal.reason instanceof Error
+                    ? childController.signal.reason
+                    : Object.assign(new Error("Tool aborted"), { name: "AbortError" });
+            }
+            cleanup();
+            if (!result.ok) {
+                return {
+                    id,
+                    toolName: name,
+                    error: result.error,
+                    isError: true,
+                    sandbox: result.sandbox,
+                };
             }
-            // 结构化返回:图片块(view_image)或沙箱标记(Bash 等)。两者互斥,
-            // 各取所有,缺的字段为 undefined。
-            const contentBlocks = "contentBlocks" in result ? result.contentBlocks : undefined;
-            const sandbox = "sandbox" in result ? result.sandbox : undefined;
-            const sensitive = "sensitive" in result ? result.sensitive : undefined;
-            const displayResult = "displayResult" in result ? result.displayResult : undefined;
-            const transcriptResult = "transcriptResult" in result ? result.transcriptResult : undefined;
             return {
                 id,
                 toolName: name,
-                result: result.result ?? (contentBlocks ? "(image)" : ""),
-                contentBlocks,
-                sandbox,
-                sensitive,
-                displayResult,
-                transcriptResult,
+                result: result.result ?? (result.contentBlocks ? "(image)" : ""),
+                contentBlocks: result.contentBlocks,
+                sandbox: result.sandbox,
+                sensitive: result.sensitive,
+                displayResult: result.displayResult,
+                transcriptResult: result.transcriptResult,
+                isError: false,
             };
         }
         catch (err) {
-            clearTimeout(timerId);
-            parentSignal?.removeEventListener("abort", onParentAbort);
+            cleanup();
             // Always return error as ToolResult, never throw
             let errorMsg;
             const isAbort = err?.name === "AbortError" || parentSignal?.aborted === true;
-            if (err instanceof ToolTimeoutError) {
+            if (timedOut || err instanceof ToolTimeoutError) {
                 errorMsg = `Tool timed out after ${timeout}ms: ${name}`;
             }
             else if (isAbort) {

package/dist/tool-system/sandbox/index.js

@@ -26,7 +26,8 @@ import { SandboxUnavailableError } from "../../exceptions.js";
 export function detectSandboxCapabilities() {
     return {
         seatbelt: process.platform === "darwin" && binaryExists("/usr/bin/sandbox-exec"),
-        bwrap: process.platform === "linux" && (binaryExists("/usr/bin/bwrap") || binaryExists("/usr/local/bin/bwrap")),
+        bwrap: process.platform === "linux" &&
+            (binaryExists("/usr/bin/bwrap") || binaryExists("/usr/local/bin/bwrap")),
     };
 }
 function binaryExists(path) {
@@ -119,13 +120,7 @@ export function defaultSandboxConfig(mode = "auto") {
     return {
         mode,
         writableRoots: ["${workspace}", ...tmpRoots],
-        deniedReads: [
-            "~/.ssh",
-            "~/.aws",
-            "~/.config/gcloud",
-            "~/.code-shell",
-            "~/.claude",
-        ],
+        deniedReads: ["~/.ssh", "~/.aws", "~/.config/gcloud", "~/.code-shell", "~/.claude"],
         network: "allow",
     };
 }

package/dist/tool-system/sandbox/seatbelt.js

@@ -54,12 +54,8 @@ export function createSeatbeltBackend(config) {
     };
 }
 function buildProfile(config) {
-    const writeAllows = config.writableRoots
-        .map((p) => `  (subpath ${quote(p)})`)
-        .join("\n");
-    const readDenies = config.deniedReads
-        .map((p) => `  (subpath ${quote(p)})`)
-        .join("\n");
+    const writeAllows = config.writableRoots.map((p) => `  (subpath ${quote(p)})`).join("\n");
+    const readDenies = config.deniedReads.map((p) => `  (subpath ${quote(p)})`).join("\n");
     const networkClause = config.network === "deny" ? "(deny network-outbound)" : "(allow network*)";
     // SBPL evaluation note: when a broad `(allow file-read*)` and a specific
     // `(deny file-read* (subpath …))` both match, the more specific subpath

package/dist/tool-system/session-tool-host.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Session-scoped tool host for external Agent Runtimes.
+ *
+ * An external runtime (Codex, Claude Code) drives its own agent loop and its own
+ * native tools. When it wants a CODESHELL tool it comes back in over MCP, and
+ * this is what it reaches: a narrow, per-business-session surface that exposes an
+ * explicitly allowlisted subset of the registry.
+ *
+ * The single rule that matters: **every call goes through
+ * `ToolExecutor.executeSingle()`**. `ToolRegistry` is not a security boundary —
+ * calling it directly would skip visibility, plan mode, argument validation, path
+ * policy, permission, sandbox, hooks, and result redaction. The MCP transport,
+ * the model's chosen tool name, and its arguments are all untrusted; the business
+ * session context is bound here by the host, out of band.
+ *
+ * Deliberately domain-agnostic: no Claude/Codex/Electron/coding literals. The
+ * runtime adapters live in the coding capability and talk to this through the
+ * `SessionToolHost` interface.
+ */
+import type { PermissionMode, ToolDefinition, ToolResult } from "../types.js";
+import type { ToolContext } from "./context.js";
+import { ToolRegistry } from "./registry.js";
+import { type ApprovalBackend } from "./permission.js";
+import { HookRegistry } from "../hooks/registry.js";
+import { type ToolVisibilityInputs } from "../engine/run-tooling.js";
+/**
+ * Permission modes an external session may use.
+ *
+ * `bypassPermissions` and `dontAsk` are excluded at the type level because they
+ * short-circuit `PermissionClassifier` entirely (it returns allow / deny before
+ * consulting any rule). Under either one, "the call went through ToolExecutor"
+ * becomes true but meaningless. The external runtime's OWN permission mode is a
+ * separate thing and is unaffected by this — it governs that runtime's native
+ * tools, not CodeShell's.
+ */
+export type ExternalSessionPermissionMode = Exclude<PermissionMode, "bypassPermissions" | "dontAsk">;
+/**
+ * Which tools an external runtime may see and call.
+ *
+ * Allowlist only — no "everything in the registry", no prefix matching. A tool
+ * that is not named here does not exist as far as the runtime is concerned, and
+ * naming it anyway is an error rather than a silent no-op.
+ */
+export interface ExternalToolExposurePolicy {
+    mode: "allowlist";
+    toolNames: ReadonlySet<string>;
+    /**
+     * Optional per-tool argument narrowing, for tools that multiplex several
+     * operations behind one name (e.g. a Panel tool with list/open/tools/invoke).
+     * Each value is a regex source matched against the whole argument value —
+     * patterns are anchored for you, see {@link matchesWholeValue}.
+     *
+     * This binds on `execute()`, not just `listTools()`: describing a limit only in
+     * the advertised schema would leave it advisory, and the arguments come from
+     * the model.
+     *
+     * **Scope, stated plainly:** this constrains only the keys it names. Keys the
+     * pattern does not mention pass through untouched, so it is a good fit for
+     * "which action may run" and a poor one for "what may that action do".
+     * Restricting a nested payload (e.g. the arguments a Panel tool forwards to a
+     * Panel App) is the tool's own schema validation, not this. Do not treat an
+     * `argsPatterns` entry as a sandbox for everything a tool might accept.
+     */
+    argsPatterns?: ReadonlyMap<string, Readonly<Record<string, string>>>;
+}
+export interface SessionToolHost {
+    readonly businessSessionId: string;
+    /**
+     * The assembled session ToolContext.
+     *
+     * Exposed read-only so a host can inspect what the executor will actually see
+     * — most usefully `toolVisibility` (absent means ToolExecutor SKIPS its
+     * availability guard) and `allowedToolNames`. Do not mutate it; narrow the
+     * exposure policy instead.
+     */
+    readonly toolContext: ToolContext;
+    listTools(): readonly ToolDefinition[];
+    execute(call: {
+        id: string;
+        name: string;
+        input: unknown;
+    }, signal?: AbortSignal): Promise<ToolResult>;
+    dispose(): Promise<void>;
+}
+export interface CreateSessionToolHostOptions {
+    businessSessionId: string;
+    cwd: string;
+    registry: ToolRegistry;
+    permissionMode: ExternalSessionPermissionMode;
+    /**
+     * The agent preset's permission rules (e.g.
+     * `BUILTIN_AGENT_PRESETS.general.defaultPermissionRules`).
+     *
+     * Only the PRESET layer is supplied here. The rest of the stack — the standing
+     * memory-scope carve-outs, mode-derived rules, and the user's own
+     * `settings.permissions.rules` — is composed internally by
+     * {@link composePermissionRules}, the same function the Native Engine uses.
+     *
+     * That composition is deliberately not left to the caller. An earlier revision
+     * took a finished rule array, which turned an equivalence guarantee into an
+     * unenforceable obligation: nothing checked that a caller reproduced
+     * `PermissionController.build()`, and the easy mistake — omitting
+     * `settings.permissions.rules` — meant a user's explicit "deny this tool" bound
+     * the Native Engine but not the external runtime.
+     */
+    presetRules: readonly import("../types.js").PermissionRule[];
+    /** Settings scope used to resolve the user's own permission rules. */
+    settingsScope?: import("../settings/manager.js").SettingsScope;
+    /**
+     * Whether the project at `cwd` has been trusted by the user.
+     *
+     * **Required, and there is no default** — `permissions` is the first entry in
+     * `DANGEROUS_PROJECT_FIELDS`, so an untrusted project's
+     * `settings.permissions.rules` are stripped precisely to stop a cloned repo
+     * self-authorizing. Every protocol-layer caller resolves this explicitly and
+     * defaults it to `false`; an optional field defaulting to "trusted" here would
+     * let a hostile repo grant an external runtime tools the user never trusted,
+     * without the approval backend ever being consulted.
+     *
+     * Optional-plus-unsafe-default is the exact shape of the bug this whole
+     * options object has now been bitten by twice. Hence: required.
+     */
+    projectTrusted: boolean;
+    planMode: boolean;
+    exposure: ExternalToolExposurePolicy;
+    /**
+     * Availability-guard inputs. Required, not optional: `ToolExecutor` SKIPS its
+     * visibility gate when `toolCtx.toolVisibility` is absent, so omitting this
+     * would not merely under-expose tools — it would make host-gated tools
+     * callable in a context their guard was written to exclude.
+     */
+    visibility: ToolVisibilityInputs;
+    approvalBackend?: ApprovalBackend;
+    hooks?: HookRegistry;
+    /** Extra ToolContext seams the host supplies (panels, browser, askUser, …). */
+    contextOverrides?: Partial<ToolContext>;
+    signal?: AbortSignal;
+}
+export declare function createSessionToolHost(options: CreateSessionToolHostOptions): SessionToolHost;

package/dist/tool-system/session-tool-host.js

@@ -0,0 +1,167 @@
+import { ToolExecutor } from "./executor.js";
+import { PermissionClassifier } from "./permission.js";
+import { HookRegistry } from "../hooks/registry.js";
+import { buildToolVisibility } from "../engine/run-tooling.js";
+import { composePermissionRules } from "../engine/permission-controller.js";
+const FORBIDDEN_MODES = new Set(["bypassPermissions", "dontAsk"]);
+/**
+ * Whole-string match for an exposure pattern.
+ *
+ * Patterns are ANCHORED here rather than trusting the author to write `^…$`.
+ * An unanchored `action: "list"` would also admit `"invoke_list"` — a silent
+ * widening of a rule whose entire purpose is to narrow. Anchoring in one place
+ * makes the safe reading the only reading; an author who deliberately writes
+ * `^(list|open)$` gets the same result either way.
+ */
+function matchesWholeValue(source, value) {
+    let re;
+    try {
+        re = new RegExp(`^(?:${source})$`, "u");
+    }
+    catch {
+        // A malformed pattern must not silently permit everything.
+        return false;
+    }
+    return re.test(value);
+}
+function argsMatch(patterns, input) {
+    if (!patterns)
+        return true;
+    for (const [key, source] of Object.entries(patterns)) {
+        // Read own properties only: a model-supplied JSON body cannot smuggle a
+        // match through the prototype chain.
+        const value = Object.prototype.hasOwnProperty.call(input, key) ? input[key] : undefined;
+        // Only primitives are comparable. Objects/arrays are rejected rather than
+        // stringified — `String(["list"])` is `"list"`, which would let an array
+        // satisfy a scalar pattern.
+        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+            return false;
+        }
+        if (!matchesWholeValue(source, String(value)))
+            return false;
+    }
+    return true;
+}
+export function createSessionToolHost(options) {
+    if (FORBIDDEN_MODES.has(options.permissionMode)) {
+        throw new Error(`SessionToolHost refuses permission mode '${options.permissionMode}': it short-circuits ` +
+            `PermissionClassifier, so CodeShell tool authorization would not actually run. ` +
+            `An external runtime's own permission mode is separate and unaffected.`);
+    }
+    const { registry, exposure } = options;
+    const hooks = options.hooks ?? new HookRegistry();
+    // Composed HERE, by the same function the Native Engine uses, so the two paths
+    // cannot drift. In particular this is what pulls in the user's own
+    // `settings.permissions.rules` — a deny the user wrote must bind an external
+    // runtime exactly as it binds the Native Engine.
+    const permission = new PermissionClassifier(composePermissionRules({
+        mode: options.permissionMode,
+        cwd: options.cwd,
+        presetRules: options.presetRules,
+        projectTrusted: options.projectTrusted,
+        ...(options.settingsScope ? { settingsScope: options.settingsScope } : {}),
+    }), options.permissionMode, options.approvalBackend);
+    // Every in-flight call is chained to this, so dispose() can actually stop work
+    // that is mid-execution or parked on an approval prompt (§13.4).
+    const lifetime = new AbortController();
+    const sessionSignal = options.signal
+        ? AbortSignal.any([options.signal, lifetime.signal])
+        : lifetime.signal;
+    const toolCtx = {
+        cwd: options.cwd,
+        toolRegistry: registry,
+        // The COMBINED signal, not just the caller's: a tool that cooperates with
+        // ctx.signal must observe session disposal too.
+        signal: sessionSignal,
+        // Caller-supplied host seams (panels, browser, askUser, …) come FIRST so the
+        // security-relevant fields below always win. Spreading them last would let a
+        // caller — or a careless refactor — set `toolVisibility: undefined` (which
+        // makes ToolExecutor skip its availability guard entirely), widen
+        // `allowedToolNames`, or re-introduce a permission mode the throw above
+        // just rejected.
+        ...options.contextOverrides,
+        sessionId: options.businessSessionId,
+        planMode: options.planMode,
+        permissionMode: options.permissionMode,
+        toolVisibility: buildToolVisibility(options.visibility),
+        // Belt and braces with the exposure check in execute(): the executor
+        // enforces this too, so a future refactor that loses one still fails closed.
+        allowedToolNames: new Set(exposure.toolNames),
+    };
+    const executor = new ToolExecutor(registry, permission, hooks);
+    executor.setContext(toolCtx);
+    executor.setSignal(sessionSignal);
+    let disposed = false;
+    const failClosed = (id, name, error) => ({
+        id,
+        toolName: name,
+        error,
+        isError: true,
+    });
+    return {
+        businessSessionId: options.businessSessionId,
+        toolContext: toolCtx,
+        listTools() {
+            if (disposed)
+                return [];
+            return registry
+                .getToolDefinitions()
+                .filter((definition) => exposure.toolNames.has(definition.name));
+        },
+        async execute(call, callSignal) {
+            if (disposed) {
+                return failClosed(call.id, call.name, "This tool session has been closed.");
+            }
+            if (!exposure.toolNames.has(call.name)) {
+                // Fail closed on a KNOWN-but-unexposed name too. Not listing a tool is a
+                // boundary, not a hint to the model.
+                return failClosed(call.id, call.name, `Tool ${call.name} is not exposed to this session. Do NOT retry this tool call.`);
+            }
+            const input = call.input && typeof call.input === "object" && !Array.isArray(call.input)
+                ? call.input
+                : {};
+            if (!argsMatch(exposure.argsPatterns?.get(call.name), input)) {
+                return failClosed(call.id, call.name, `Tool ${call.name} was called with arguments outside the scope exposed to this ` +
+                    `session. Do NOT retry this tool call with the same arguments.`);
+            }
+            // `sessionSignal` folds in the session lifetime and the caller-supplied
+            // signal; `callSignal` is the optional per-call one (an MCP cancellation).
+            if (sessionSignal.aborted || callSignal?.aborted) {
+                return failClosed(call.id, call.name, `Tool aborted before execution: ${call.name}`);
+            }
+            // Forward the per-call signal rather than only checking it at entry: an MCP
+            // cancellation arriving mid-flight has to actually stop the work.
+            //
+            // A `ToolExecutor` holds exactly one signal, and swapping it per call would
+            // race with concurrent calls carrying different signals. So a call that
+            // brings its own signal gets its own executor — cheap (it is a thin wrapper
+            // over the shared registry/permission/hooks) and free of shared mutable
+            // state. Calls without one use the shared executor unchanged.
+            if (!callSignal) {
+                // The one authorized path. Everything above only NARROWS what may reach it.
+                return await executor.executeSingle({
+                    id: call.id,
+                    toolName: call.name,
+                    args: input,
+                });
+            }
+            const scoped = new ToolExecutor(registry, permission, hooks);
+            scoped.setContext(toolCtx);
+            scoped.setSignal(AbortSignal.any([sessionSignal, callSignal]));
+            return await scoped.executeSingle({
+                id: call.id,
+                toolName: call.name,
+                args: input,
+            });
+        },
+        async dispose() {
+            // Order matters (§13.4): stop accepting new calls, THEN abort in-flight
+            // ones. Marking disposed without aborting would let a call that is already
+            // running — or parked on an approval prompt — continue and complete after
+            // the session is gone.
+            disposed = true;
+            lifetime.abort();
+            executor.setContext(undefined);
+        },
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { BuiltinTool } from "../builtin/index.js";
+import type { ToolContext } from "../context.js";
+import { ToolRegistry } from "../registry.js";
+import type { ToolResult } from "../../types.js";
+export interface FakeToolContextOptions {
+    cwd?: string;
+    sessionId?: string;
+    signal?: AbortSignal;
+    /** Shallow overrides for tool-family-specific host bridges. */
+    overrides?: Partial<ToolContext>;
+}
+export interface ToolRegistryHarnessOptions extends FakeToolContextOptions {
+    builtinTools?: readonly string[];
+    toolCatalog?: readonly BuiltinTool[];
+    registry?: ToolRegistry;
+    timeoutMs?: number;
+}
+export interface ToolRegistryHarness {
+    registry: ToolRegistry;
+    context: ToolContext;
+    execute(name: string, args?: Record<string, unknown>): Promise<ToolResult>;
+}
+/**
+ * Shared fake ToolContext for builtin integration tests. It intentionally
+ * supplies only stable harness defaults; tests opt into browser/workspace/MCP/
+ * sub-agent behavior through `overrides`, so missing host seams fail visibly.
+ */
+export declare function createFakeToolContext(registry: ToolRegistry, options?: FakeToolContextOptions): ToolContext;
+/** Build a real ToolRegistry and execute through its timeout/signal/result
+ * protocol while keeping host dependencies deterministic and injectable. */
+export declare function createToolRegistryHarness(options?: ToolRegistryHarnessOptions): ToolRegistryHarness;

package/dist/tool-system/testing/tool-registry-harness.js

@@ -0,0 +1,51 @@
+import { resolve } from "node:path";
+import { ToolRegistry } from "../registry.js";
+/**
+ * Shared fake ToolContext for builtin integration tests. It intentionally
+ * supplies only stable harness defaults; tests opt into browser/workspace/MCP/
+ * sub-agent behavior through `overrides`, so missing host seams fail visibly.
+ */
+export function createFakeToolContext(registry, options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const context = {
+        cwd,
+        setCwd(next) {
+            context.cwd = resolve(next);
+        },
+        llmConfig: {},
+        toolRegistry: registry,
+        planMode: false,
+        sessionId: options.sessionId ?? "tool-harness-session",
+        signal: options.signal,
+        allowBackgroundShells: false,
+        toolVisibility: { hasGoal: true },
+        engine: {
+            getPlanMode: () => context.planMode,
+            setPlanMode: (enabled) => {
+                context.planMode = enabled;
+            },
+        },
+        askUser: async () => "harness-answer",
+        ...options.overrides,
+    };
+    return context;
+}
+/** Build a real ToolRegistry and execute through its timeout/signal/result
+ * protocol while keeping host dependencies deterministic and injectable. */
+export function createToolRegistryHarness(options = {}) {
+    const registryOptions = {
+        ...(options.builtinTools ? { builtinTools: options.builtinTools } : {}),
+        ...(options.toolCatalog ? { toolCatalog: options.toolCatalog } : {}),
+    };
+    const registry = options.registry ?? new ToolRegistry(registryOptions);
+    const context = createFakeToolContext(registry, options);
+    return {
+        registry,
+        context,
+        execute: async (name, args = {}) => await registry.executeTool(name, args, {
+            ctx: context,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs ?? 5_000,
+        }),
+    };
+}