@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/tool-system/mcp-tool-policy.js

@@ -0,0 +1,34 @@
+export function buildMcpToolPolicies(servers) {
+    const policies = new Map();
+    for (const [serverName, config] of Object.entries(servers)) {
+        if (config.enabled === false)
+            continue;
+        if (config.allowedTools === undefined && config.disabledTools === undefined)
+            continue;
+        policies.set(serverName, {
+            allowedTools: config.allowedTools === undefined ? undefined : new Set(config.allowedTools),
+            disabledTools: new Set(config.disabledTools ?? []),
+        });
+    }
+    return policies;
+}
+export function isMcpToolNameAllowed(policies, serverName, toolName) {
+    const policy = policies?.get(serverName);
+    if (!policy)
+        return true;
+    if (policy.allowedTools && !policy.allowedTools.has(toolName))
+        return false;
+    return !policy.disabledTools.has(toolName);
+}
+export function isRegisteredMcpToolAllowed(tool, policies) {
+    if (tool.source !== "mcp")
+        return true;
+    const policy = policies?.get(tool.serverName ?? "");
+    if (!policy)
+        return true;
+    // Restricted servers fail closed for registry entries created by an older
+    // or third-party adapter that did not preserve the original MCP tool name.
+    if (!tool.mcpToolName)
+        return false;
+    return isMcpToolNameAllowed(policies, tool.serverName ?? "", tool.mcpToolName);
+}

package/dist/tool-system/panel-bridge.d.ts

@@ -0,0 +1,53 @@
+/** One panel the active host can present to the user. */
+export interface AgentPanelDescriptor {
+    id: string;
+    title: string;
+    source: "builtin" | "builtin-panel-app" | "panel-app";
+}
+export interface PanelOpenResult {
+    ok: boolean;
+    panelId: string;
+    detail?: string;
+}
+export interface AgentPanelToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    readOnly: boolean;
+}
+export interface PanelInvokeResult {
+    ok: boolean;
+    panelId: string;
+    toolName: string;
+    result?: unknown;
+    detail?: string;
+}
+/**
+ * A discovery result that can distinguish "the host has none" from "the request
+ * never completed".
+ *
+ * `list` / `tools` used to return a bare array, so every failure — a user Stop, a
+ * closed session, a timeout — collapsed to `[]`, which the Panel tool then
+ * reported as the factual claim "(no panels available)". That is worse than a
+ * refusal: it tells the model panel hosting is unavailable, so it stops trying.
+ * `failed` carries the reason instead, and an absent `failed` means the empty
+ * list is real.
+ */
+export interface PanelDiscoveryResult<T> {
+    items: T[];
+    /** Present only when the request did not complete; `items` is then empty. */
+    failed?: string;
+}
+/**
+ * UI-agnostic bridge used by agent tools to discover and focus host panels.
+ *
+ * Core never imports a renderer. Desktop implements this through its protocol
+ * host; headless/TUI engines leave it undefined. Plugin-contributed tools may
+ * use the same bridge to open their own panel by stable registry id.
+ */
+export interface PanelHostBridge {
+    list(): Promise<PanelDiscoveryResult<AgentPanelDescriptor>>;
+    open(panelId: string): Promise<PanelOpenResult>;
+    tools?(panelId: string): Promise<PanelDiscoveryResult<AgentPanelToolDescriptor>>;
+    invoke?(panelId: string, toolName: string, args: Record<string, unknown>): Promise<PanelInvokeResult>;
+}

package/dist/tool-system/panel-bridge.js

@@ -0,0 +1 @@
+export {};

package/dist/tool-system/path-policy.js

@@ -29,11 +29,12 @@
  * approval round-trip; it is not an authority to write anywhere on disk.
  * Callers must consult classifyPath before honoring acceptEdits.
  */
-import { constants, realpathSync, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, } from "node:fs";
+import { constants, realpathSync, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, statSync, } from "node:fs";
 import { open } from "node:fs/promises";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
-import { dirname, isAbsolute, join, resolve as resolvePath, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
+import { readInstalledPlugins } from "../plugins/installedPlugins.js";
 const FINAL_WRITE_PATH_SNAPSHOT = Symbol("codeshell.finalWritePathSnapshot");
 /**
  * Default sensitive path patterns. These are evaluated AFTER home-expansion
@@ -392,6 +393,88 @@ function isInsideDir(child, parent) {
     const p = par.endsWith(sep) ? par : par + sep;
     return c === par || c.startsWith(p);
 }
+function configuredUserHome() {
+    return process.env.HOME ?? homedir();
+}
+/**
+ * Whether `resolved` belongs to one concrete Skill tree rooted below
+ * `<skillsRoot>/<skill>/`.
+ *
+ * Both the root and manifest are realpathed, so a reference symlink cannot
+ * turn this read-only exception into access outside the managed Skill tree.
+ */
+function isSkillTreeResource(resolved, skillsRoot) {
+    try {
+        const realSkillsRoot = realpathSync(skillsRoot);
+        if (!isInsideDir(resolved, realSkillsRoot))
+            return false;
+        const rel = relative(realSkillsRoot, resolved);
+        const skillName = rel.split(sep).filter(Boolean)[0];
+        if (!skillName || skillName === "..")
+            return false;
+        const skillRoot = realpathSync(join(realSkillsRoot, skillName));
+        if (!isInsideDir(skillRoot, realSkillsRoot))
+            return false;
+        const manifest = realpathSync(join(skillRoot, "SKILL.md"));
+        if (!isInsideDir(manifest, skillRoot) || !statSync(manifest).isFile())
+            return false;
+        return isInsideDir(resolved, skillRoot);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Skill instructions routinely link to sibling references/scripts/assets.
+ * The Skill builtin can already read the registered SKILL.md, so asking again
+ * for every referenced file is both inconsistent and capable of wedging a
+ * headless run.
+ *
+ * Keep the exception narrow:
+ *   - read-only (the caller checks the operation);
+ *   - user Skills, or an installed plugin recorded in the V2 registry;
+ *   - plugin installs must realpath beneath the managed plugin cache;
+ *   - the target must remain inside a directory containing a real SKILL.md.
+ */
+function isRegisteredSkillResourceRead(resolved) {
+    let codeShellRoot;
+    try {
+        codeShellRoot = realpathSync(join(configuredUserHome(), ".code-shell"));
+    }
+    catch {
+        return false;
+    }
+    if (!isInsideDir(resolved, codeShellRoot))
+        return false;
+    if (isSkillTreeResource(resolved, join(codeShellRoot, "skills")))
+        return true;
+    let cacheRoot;
+    try {
+        cacheRoot = realpathSync(join(codeShellRoot, "plugins", "cache"));
+    }
+    catch {
+        return false;
+    }
+    const installed = readInstalledPlugins();
+    for (const entries of Object.values(installed.plugins)) {
+        for (const entry of entries) {
+            try {
+                const installRoot = realpathSync(entry.installPath);
+                if (installRoot === cacheRoot || !isInsideDir(installRoot, cacheRoot))
+                    continue;
+                const skillsRoot = realpathSync(join(installRoot, "skills"));
+                if (!isInsideDir(skillsRoot, installRoot))
+                    continue;
+                if (isSkillTreeResource(resolved, skillsRoot))
+                    return true;
+            }
+            catch {
+                // A stale/tampered registry entry must never broaden read authority.
+            }
+        }
+    }
+    return false;
+}
 /**
  * Returns the matching sensitive-dir entry (with the user's home prefix) if
  * `resolved` lives underneath any sensitive directory, else undefined.
@@ -476,6 +559,20 @@ export function classifyPath(rawPath, opts) {
     const sensitiveFile = matchSensitiveFile(resolved);
     const sensitiveLabel = sensitiveDir ?? sensitiveFile;
     const insideWorkspace = isInsideDir(resolved, workspace);
+    // Registered Skill resources are managed runtime inputs. Their SKILL.md is
+    // already readable through the Skill builtin; allow its contained reference
+    // files through the ordinary Read tool as well. A credential-shaped basename
+    // (.env, token.txt, key files, ...) deliberately keeps the sensitive-file
+    // gate even inside a Skill tree.
+    if (opts.operation === "read" &&
+        !sensitiveFile &&
+        isRegisteredSkillResourceRead(resolved)) {
+        return {
+            decision: "allow",
+            reason: "registered Skill resource read",
+            resolvedPath: resolved,
+        };
+    }
     // Sensitive: write is always denied, read always asks. Workspace placement
     // doesn't soften the rule — an `.env` in the project still asks on read.
     if (sensitiveLabel) {

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

@@ -6,6 +6,19 @@ import { logger as rootPermLogger } from "../logging/logger.js";
 export interface ApprovalBackend {
     requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
 }
+/**
+ * Interactive-approval lifecycle observation (see
+ * PermissionClassifier.setApprovalEventListener). "requested" fires right
+ * before the backend prompt is awaited; "resolved" fires after the user (or
+ * backend policy) answered, with the outcome.
+ */
+export interface ApprovalLifecycleEvent {
+    phase: "requested" | "resolved";
+    toolName: string;
+    riskLevel: "low" | "medium" | "high";
+    approved?: boolean;
+    sessionId?: string;
+}
 export interface ApprovalRouteTarget {
     connectionId: string;
     sessionId: string;
@@ -185,8 +198,21 @@ export declare class PermissionClassifier {
      * tests and ad-hoc usages still write log lines.
      */
     private log;
+    private approvalStateListener?;
+    private approvalEventListener?;
+    private activeApprovalCount;
     constructor(rules: PermissionRule[], defaultMode?: PermissionMode, approvalBackend?: ApprovalBackend);
     setLogger(log: typeof rootPermLogger): void;
+    setApprovalStateListener(listener: ((waiting: boolean, toolName: string) => void) | undefined): void;
+    /**
+     * 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: ((event: ApprovalLifecycleEvent) => void) | undefined): void;
+    private emitApprovalEvent;
     /** Replace mode + backend in place so live tool execution sees the change. */
     reconfigure(mode: PermissionMode, approvalBackend: ApprovalBackend, rules?: PermissionRule[]): void;
     getMode(): PermissionMode;

package/dist/tool-system/permission.js

@@ -1237,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;
@@ -1245,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;
@@ -1330,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;
@@ -1345,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,
@@ -1385,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 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?: 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;

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, toToolExecutionResult } 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,6 +40,9 @@ 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) {
@@ -45,9 +52,17 @@ export class ToolRegistry {
             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) => ({
@@ -63,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) {
@@ -74,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)}`;

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;