@cjhyy/code-shell-core 0.7.0 → 0.8.0

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

@@ -1,8 +1,8 @@
 /**
  * ToolContext — runtime services injected into every tool execution.
  *
- * Replaces the legacy module-level singletons (`setAskUserFn`,
- * `setArenaLLMConfig`, `setSubAgentConfig`, `setToolSearchRegistry`).
+ * Replaces the legacy module-level singleton setters used by built-ins and
+ * product capabilities.
  *
  * Each Engine instance builds its own ToolContext when run() starts and
  * passes it through ToolExecutor → ToolRegistry → executor function.
@@ -12,14 +12,17 @@
  * Tools that don't need any context (Read/Write/Bash/...) just ignore
  * the second argument; the type is purely additive.
  */
-import type { LLMConfig, StreamCallback } from "../types.js";
+import type { LLMConfig, StreamCallback, TokenUsage } from "../types.js";
 import type { ModelPool } from "../llm/model-pool.js";
 import type { ToolRegistry } from "./registry.js";
 import type { AgentPresetName } from "../preset/index.js";
-import type { SandboxBackend } from "./sandbox/index.js";
+import type { SandboxBackend, SandboxMode } from "./sandbox/index.js";
 import type { HookRegistry } from "../hooks/registry.js";
 import type { SessionManager } from "../session/session-manager.js";
 import type { SessionWorkspace } from "../types.js";
+import type { ApprovalRouter } from "./permission.js";
+import type { ChildWriterLease, LiveChildControl } from "./builtin/agent-registry.js";
+import type { McpToolPolicy } from "./mcp-tool-policy.js";
 /**
  * Narrow view of the owning Engine that tools are allowed to call back into.
  * Defined here (in the low-level tool-system) rather than importing the
@@ -33,19 +36,6 @@ export interface ToolRuntimeHost {
     readonly planMode: boolean;
     /** Toggle plan mode (EnterPlanMode / ExitPlanMode tools). */
     setPlanMode(value: boolean): void;
-    /** Per-worktree setup scripts, or undefined for sub-agents / no cwd. */
-    readWorktreeSetupScripts(cwd?: string): {
-        default?: string;
-        macos?: string;
-        linux?: string;
-        windows?: string;
-    } | undefined;
-    /** Branch prefix used for CodeShell-managed worktree branches. */
-    readWorktreeBranchPrefix?(cwd?: string): string | undefined;
-    /** Resolve a setup-only sandbox for a newly-created worktree root. */
-    resolveWorktreeSetupSandbox?(cwd: string): Promise<SandboxBackend | undefined>;
-    /** Resolve setup-only shell env for a newly-created worktree root. */
-    readWorktreeSetupShellEnv?(cwd?: string): Record<string, string> | undefined;
     /** Session state store used by session-scoped tools such as worktree switching. */
     getSessionManager?(): SessionManager;
 }
@@ -128,6 +118,10 @@ export interface SubAgentSpawnRequest {
      * tool. Undefined → child inherits the parent's full skill pool.
      */
     skillAllowlist?: string[];
+    /** Optional role-level sandbox mode. Undefined → inherit the parent sandbox. */
+    sandboxMode?: SandboxMode;
+    /** Optional MCP server allowlist. Undefined → inherit all; [] → no MCP. */
+    mcpAllowlist?: string[];
     /**
      * Optional per-call system prompt appended to the child Engine's prompt
      * (the role definition's Markdown body). Undefined → child inherits only
@@ -146,6 +140,15 @@ export interface SubAgentSpawnRequest {
      * See AgentSendInput in builtin/agent.ts.
      */
     resumeSessionId?: string;
+    /** Trusted live-runtime generation; never exposed in the Agent tool schema. */
+    runtimeGeneration?: number;
+    /** Bind the existing child runtime to the registry's single-writer lease. */
+    bindLiveControl?: (control: LiveChildControl, ownerToken: string) => ChildWriterLease | true | false;
+    /** Atomically close intake before the child publishes its terminal result. */
+    closeLiveControl?: (control: LiveChildControl, lease?: ChildWriterLease) => boolean | void;
+    /** Raw child stream tap used to deterministically reduce structured progress. */
+    onProgressEvent?: (event: Parameters<StreamCallback>[0]) => void;
+    onAgentProgress?: import("../engine/run-types.js").EngineRunOptions["onAgentProgress"];
 }
 export interface SubAgentSpawner {
     /**
@@ -154,16 +157,15 @@ export interface SubAgentSpawner {
      * (or `resumeSessionId` when resuming), so the parent can address follow-up
      * input at the same session via AgentSendInput (transcript replay).
      */
-    spawn(req: SubAgentSpawnRequest): Promise<{
-        text: string;
-        sessionId: string;
-    }>;
+    spawn(req: SubAgentSpawnRequest): Promise<SubAgentSpawnResult>;
     /**
      * Whether a child session id exists on disk. Lets AgentSendInput resume an
      * agent across a process restart (when the in-memory registry is empty but
      * the session transcript is still persisted). Optional for legacy callers.
      */
     sessionExists?(sessionId: string): boolean;
+    /** Persisted direct-parent metadata used to authorize cross-restart continuation. */
+    getSessionParentId?(sessionId: string): string | null | undefined;
     /** Stream callback to forward sub-agent events back to the parent UI. */
     parentStream?: StreamCallback;
     /** Static config used to describe what the spawned engine looks like. */
@@ -173,6 +175,12 @@ export interface SubAgentSpawner {
         permissionMode: string;
     };
 }
+export interface SubAgentSpawnResult {
+    text: string;
+    sessionId: string;
+    /** Complete billed usage returned by the child Engine run. */
+    usage?: TokenUsage;
+}
 /**
  * The full context object handed to every tool invocation.
  *
@@ -182,7 +190,20 @@ export interface SubAgentSpawner {
 export interface ToolVisibilityContext {
     cwd: string;
     hasGoal: boolean;
+    /** Resolved Session identity for per-session extension-tool visibility. */
+    sessionId?: string;
     settingsScope?: import("../settings/manager.js").SettingsScope;
+    host?: string;
+    isSubAgent?: boolean;
+    behaviorProfile?: string;
+    /** Host-authorized targets available to the cross-Session messaging builtin. */
+    sessionMessageTargets?: readonly import("../session/session-message.js").SessionMessageTarget[];
+    /**
+     * Per-run metadata produced by the active behavior profile's
+     * buildVisibilityMeta. Availability guards / definition rewriters that share
+     * the profile's domain read their conventional keys from here.
+     */
+    profileMeta?: Readonly<Record<string, unknown>>;
 }
 export interface ExternalFileChangesRecord {
     jobId: string;
@@ -193,19 +214,43 @@ export interface ExternalFileChangesRecord {
     changedFiles: string[];
     originClientMessageId?: string;
 }
+export type ToolRunYieldReason = "background_notification";
+/** Run-scoped handoff from a trusted tool to the owning turn loop. */
+export interface ToolRunYieldController {
+    request(reason: ToolRunYieldReason): void;
+    /** Inspect without clearing so the loop can prioritize an accepted steer. */
+    peek?(): ToolRunYieldReason | undefined;
+    consume(): ToolRunYieldReason | undefined;
+}
 export interface ToolContext {
     /** Active working directory for this Engine. */
     cwd: string;
+    /**
+     * Active digital-human profile's portable memory root. Present only when
+     * the resolved WorkspaceProfile enables portableMemory for this run.
+     * Memory tools use it for location:"profile"; other tools should treat the
+     * path as trusted run metadata, not as model-supplied input.
+     */
+    profileMemoryDir?: string;
     /** Mutate the owning live context cwd. Worktree switching intentionally does not use this. */
     setCwd?(cwd: string): void;
-    /** Mutate the owning live session state after a session workspace switch. */
-    setSessionWorkspace?(workspace: SessionWorkspace): void;
+    /** Mutate/rebase the owning live session state after a workspace switch. */
+    setSessionWorkspace?(workspace: SessionWorkspace, stateRevision?: number): void;
     /** LLM credentials/endpoint for tools that need to make their own calls. */
     llmConfig: LLMConfig;
-    /** Active model pool (Arena reads this to pick participants). */
+    /** Active model pool for model-aware tools and product capabilities. */
     modelPool?: ModelPool;
     /** Tool registry (ToolSearch reads this to enumerate available tools). */
     toolRegistry: ToolRegistry;
+    /** Opaque services contributed by capability modules, keyed by capability id. */
+    capabilityServices?: Readonly<Record<string, unknown>>;
+    /**
+     * Run-scoped services produced by the active behavior profile's
+     * createRunServices. Tools that share the profile's domain conventions read
+     * their keys from here (e.g. DelegateWork reads the pet profile's
+     * petWorkspaces / requestPetWorkDelegation entries).
+     */
+    runScopedServices?: Readonly<Record<string, unknown>>;
     /** UI-backed AskUserQuestion handler. Undefined → headless mode. */
     askUser?: AskUserFn;
     /** Sub-agent spawner (Agent tool). Undefined → Agent tool unavailable. */
@@ -247,6 +292,14 @@ export interface ToolContext {
      * headless/test mode; tools must tolerate absence.
      */
     streamCallback?: StreamCallback;
+    /**
+     * Report provider usage produced by a tool or child Engine into the owning
+     * session and run-scoped Goal budget. This must not invoke the process-wide
+     * billing hook again; the originating provider client already did that.
+     */
+    recordBilledUsage?: (usage: TokenUsage) => void;
+    /** Connection-scoped approval owner router supplied by the protocol host. */
+    approvalRouter?: ApprovalRouter;
     /** Whether the owning Engine is currently in plan mode. Replaces the
      *  removed module-level `isInPlanMode()` singleton. */
     planMode: boolean;
@@ -270,6 +323,8 @@ export interface ToolContext {
      * narrow context, or standalone tool tests. (B2 — Gate 1, standard §S3.)
      */
     sessionId?: string;
+    /** Engine-owned, run-scoped cross-Session message sender. */
+    sessionMessages?: import("../session/session-message.js").SessionMessageToolService;
     /** Stable id of the real user turn that owns async work launched here. */
     originClientMessageId?: string;
     /**
@@ -279,6 +334,12 @@ export interface ToolContext {
      * launched it has already returned.
      */
     recordExternalFileChanges?: (record: ExternalFileChangesRecord) => void;
+    /**
+     * A tool that launched asynchronous work can yield the current model loop.
+     * The completion notification will wake the same Session later, avoiding
+     * model-authored status polling while no new evidence can exist yet.
+     */
+    runYield?: ToolRunYieldController;
     /**
      * Skill names the user has hidden from the LLM (full namespaced names
      * for plugin skills, e.g. "docs:pdf"). The skill builtin tool uses
@@ -327,6 +388,8 @@ export interface ToolContext {
      * sub-agents and no-cwd contexts (same as readBuiltinOverride).
      */
     disabledBuiltins?: Set<string>;
+    /** Run-profile execution allowlist; omitted keeps the normal tool surface. */
+    allowedToolNames?: ReadonlySet<string>;
     /**
      * Per-turn context used by builtin availability guards. Engine.run() uses the
      * same object to hide tools from the model; ToolExecutor reuses it to reject
@@ -342,6 +405,11 @@ export interface ToolContext {
      * no gating (sub-agents / tests whose registries carry no MCP tools).
      */
     allowedMcpServers?: Set<string>;
+    /**
+     * Exact per-server MCP tool policy for this run. The engine uses the same
+     * map for model visibility, ToolSearch, and the executor's direct-call gate.
+     */
+    mcpToolPolicies?: ReadonlyMap<string, McpToolPolicy>;
     /**
      * The engine's settings scope, so tools that read disk config directly (e.g.
      * the credential tools) can honor host-isolation instead of always merging
@@ -376,6 +444,8 @@ export interface ToolContext {
      * session workspace.
      */
     workspace?: import("./workspace-bridge.js").WorkspaceBridge;
+    /** Host panel discovery/focus bridge. Undefined in non-Desktop/headless engines. */
+    panels?: import("./panel-bridge.js").PanelHostBridge;
     /**
      * Inject a stored cookie credential into the built-in browser (restore its
      * login state so the AI can drive the page as that account). The host

package/dist/tool-system/executor.js

@@ -3,15 +3,14 @@
  */
 import { setMaxListeners } from "node:events";
 import { resolve as resolvePath, isAbsolute as isAbsolutePath } from "node:path";
+import { isMcpToolNameAllowed, isRegisteredMcpToolAllowed } from "./mcp-tool-policy.js";
 import { classifyBashCommand } from "./permission.js";
 import { ToolNotFoundError } from "../exceptions.js";
 import { logger as rootLogger, getCurrentSid } from "../logging/logger.js";
 import { recordToolCall, recordToolResult } from "../logging/session-recorder.js";
 import { validateToolArgs } from "./validation.js";
 import { PLAN_MODE_ALLOWED_TOOLS } from "./plan-mode-allowlist.js";
-import { enforcePathPolicyWithApproval } from "./path-policy.js";
-import { parsePatch } from "./builtin/apply-patch/parser.js";
-import { BUILTIN_TOOL_GUARDS } from "./builtin/index.js";
+import { attachFinalWritePathSnapshot, enforcePathPolicyWithApproval, } from "./path-policy.js";
 import { COMPLETE_GOAL_TOOL_NAME } from "./builtin/complete-goal.js";
 import { CANCEL_GOAL_TOOL_NAME } from "./builtin/cancel-goal.js";
 import { toolResultDisplayText } from "./tool-result-redaction.js";
@@ -119,6 +118,14 @@ export class ToolExecutor {
                 isError: true,
             };
         }
+        if (this.toolCtx?.allowedToolNames && !this.toolCtx.allowedToolNames.has(call.toolName)) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is not allowed by this run profile. Do NOT retry this tool call.`,
+                isError: true,
+            };
+        }
         // 0. Capability override: a builtin the project marked `off` is HIDDEN from
         // the model's tool list (engine.ts applyBuiltinOverrideVisibility), but the
         // model can still NAME it (hallucination, or a remembered earlier turn). The
@@ -142,7 +149,7 @@ export class ToolExecutor {
                 isError: true,
             };
         }
-        const visibilityGuard = BUILTIN_TOOL_GUARDS.get(call.toolName);
+        const visibilityGuard = this.registry.getAvailabilityGuard(call.toolName);
         if (visibilityGuard &&
             this.toolCtx?.toolVisibility &&
             !visibilityGuard(this.toolCtx.toolVisibility)) {
@@ -167,6 +174,19 @@ export class ToolExecutor {
                     isError: true,
                 };
             }
+            if (reg?.source === "mcp" &&
+                !isRegisteredMcpToolAllowed({
+                    source: "mcp",
+                    serverName: reg.serverName,
+                    mcpToolName: reg.mcpToolName,
+                }, this.toolCtx.mcpToolPolicies)) {
+                return {
+                    id: call.id,
+                    toolName: call.toolName,
+                    error: `MCP tool "${reg.mcpToolName ?? call.toolName}" is disabled by this project's tool policy. Do NOT retry this tool call.`,
+                    isError: true,
+                };
+            }
             // The generic MCP builtins (MCPTool / ReadMcpResource) take the target
             // server as an ARGUMENT and call MCPManager directly, so the source==="mcp"
             // check above can't see them — without this a session could invoke a tool
@@ -184,6 +204,17 @@ export class ToolExecutor {
                         isError: true,
                     };
                 }
+                if (call.toolName === "MCPTool") {
+                    const tool = String(call.args.tool ?? "");
+                    if (!isMcpToolNameAllowed(this.toolCtx.mcpToolPolicies, server, tool)) {
+                        return {
+                            id: call.id,
+                            toolName: call.toolName,
+                            error: `MCP tool "${tool}" is disabled by this project's tool policy. Do NOT retry this tool call.`,
+                            isError: true,
+                        };
+                    }
+                }
             }
             else if (call.toolName === "ListMcpResources") {
                 const server = String(call.args.server ?? "");
@@ -244,6 +275,7 @@ export class ToolExecutor {
             toolName: call.toolName,
             args: call.args,
             toolCallId: call.id,
+            signal: this.signal ?? this.toolCtx?.signal,
         });
         if (hookResult.decision === "deny") {
             return {
@@ -280,6 +312,16 @@ export class ToolExecutor {
         // path surface on RegisteredTool.pathPolicy; the executor enforces it
         // after hooks have had a chance to rewrite args, but before permission
         // classification or the handler can touch the filesystem.
+        if ((call.toolName === "Write" || call.toolName === "Edit") &&
+            this.toolCtx?.cwd &&
+            typeof call.args.file_path === "string") {
+            const raw = call.args.file_path;
+            const target = isAbsolutePath(raw) ? raw : resolvePath(this.toolCtx.cwd, raw);
+            call = {
+                ...call,
+                args: attachFinalWritePathSnapshot(call.args, target, this.toolCtx.cwd),
+            };
+        }
         const pathPolicyError = await this.enforceDeclaredPathPolicy(toolDef, call.args);
         if (pathPolicyError) {
             return {
@@ -325,6 +367,7 @@ export class ToolExecutor {
             args: call.args,
             toolCallId: call.id,
             classifierDecision,
+            signal: this.signal ?? this.toolCtx?.signal,
         });
         const preClamped = clampHookDecision(classifierDecision, hookResult.decision);
         let decision = preClamped.decision;
@@ -383,6 +426,7 @@ export class ToolExecutor {
             toolName: call.toolName,
             args: call.args,
             toolCallId: call.id,
+            signal: this.signal ?? this.toolCtx?.signal,
         });
         // 3. Execute. Use a span so begin/end share one cat and end carries
         // duration_ms; widen args truncation from 200→2000 so Edit/Write payloads
@@ -431,25 +475,25 @@ export class ToolExecutor {
         result.id = call.id;
         // Prepend any non-blocking guard reminder onto a successful result so the
         // model sees it on its next turn alongside the content it just fetched.
-        if (guardDecision?.prepend && !result.error && result.result) {
+        if (guardDecision?.prepend && !result.isError && result.result) {
             result.result = `${guardDecision.prepend}\n${result.result}`;
         }
         const observerResult = toolResultDisplayText(result);
         const payload = observerResult ?? result.error ?? "";
         span.end({
-            ok: !result.error,
+            ok: !result.isError,
             chars: payload.length,
             // Snippet only on failure — successful tool output can be huge and is
             // already on the transcript. Failures are rare and the first 500 chars
             // usually contain the message we need.
-            ...(result.error ? { errorSnippet: payload.slice(0, 500) } : {}),
+            ...(result.isError ? { errorSnippet: payload.slice(0, 500) } : {}),
         });
         recordToolResult(sid, {
             id: call.id,
             toolName: call.toolName,
-            ok: !result.error,
+            ok: !result.isError,
             durationMs: Date.now() - toolStartedAt,
-            output: result.error ? undefined : observerResult,
+            output: result.isError ? undefined : observerResult,
             error: result.error,
         });
         // 4. Post-tool hook
@@ -458,6 +502,7 @@ export class ToolExecutor {
             toolCallId: call.id,
             result: observerResult,
             error: result.error,
+            signal: this.signal ?? this.toolCtx?.signal,
         });
         // 5. Post-tool-use hook (after execution, can observe/modify result)
         const postHook = await this.hooks.emit("post_tool_use", {
@@ -465,13 +510,14 @@ export class ToolExecutor {
             toolCallId: call.id,
             result: observerResult,
             error: result.error,
+            signal: this.signal ?? this.toolCtx?.signal,
         });
         // Append handler-supplied context (linter output, type-check result,
         // etc.) onto the tool result so the model sees it on the next turn.
         // Tagged with a separator so the model can tell hook output from
         // tool output. Skip when the tool errored — additional context on a
         // failed tool would be confusing.
-        if (postHook.additionalContext && !result.error) {
+        if (postHook.additionalContext && !result.isError) {
             const tag = "--- additional context from post_tool_use hook ---";
             result.result = result.result
                 ? `${result.result}\n\n${tag}\n${postHook.additionalContext}`
@@ -484,10 +530,11 @@ export class ToolExecutor {
             });
         }
         // 6. file_changed hook for Write/Edit tools
-        if ((call.toolName === "Write" || call.toolName === "Edit") && !result.error) {
+        if ((call.toolName === "Write" || call.toolName === "Edit") && !result.isError) {
             await this.hooks.emit("file_changed", {
                 toolName: call.toolName,
                 filePath: call.args.file_path,
+                signal: this.signal ?? this.toolCtx?.signal,
             });
         }
         return result;
@@ -504,6 +551,20 @@ export class ToolExecutor {
         return op.default;
     }
     async enforceDeclaredPathPolicy(tool, args) {
+        if (tool?.pathResolver) {
+            let targets;
+            try {
+                targets = tool.pathResolver.resolve(args, this.toolCtx?.cwd ?? process.cwd());
+            }
+            catch (err) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            for (const target of targets) {
+                const blocked = await enforcePathPolicyWithApproval(target, tool.pathResolver.operation, this.toolCtx);
+                if (blocked)
+                    return blocked;
+            }
+        }
         const policies = tool?.pathPolicy;
         if (!policies?.length)
             return null;
@@ -521,55 +582,35 @@ export class ToolExecutor {
         return null;
     }
     resolvePathPolicyTargets(policy, args) {
-        if (policy.kind === "arg") {
-            const raw = args[policy.arg];
-            if (typeof raw === "string" && raw.length > 0) {
-                // Resolve a RELATIVE single-string path arg against ctx.cwd before
-                // classification, mirroring the array branch below and the apply_patch
-                // branch — otherwise classifyPath's process.cwd()-based resolution
-                // mis-places an in-workspace relative path (e.g. Read "src/x.ts") as
-                // "outside workspace" and over-prompts. Absolute paths pass through.
-                const cwd = this.toolCtx?.cwd ?? process.cwd();
-                return [isAbsolutePath(raw) ? raw : resolvePath(cwd, raw)];
-            }
-            // Array path args (e.g. GenerateImage `referenceImages`, GenerateVideo
-            // `images`): enforce EVERY element. Without this an array yielded zero
-            // targets, so out-of-workspace reads bypassed the path-policy "ask" gate
-            // that Read/Write enforce. http(s) URLs aren't file reads → skip them.
-            // Relative paths resolve against ctx.cwd (the workspace) before
-            // classification, like the apply_patch branch — otherwise classifyPath's
-            // process.cwd()-based resolution would mis-place an in-workspace relative
-            // path as "outside" and over-prompt. Non-string / empty elements skipped.
-            if (Array.isArray(raw)) {
-                const cwd = this.toolCtx?.cwd ?? process.cwd();
-                const paths = raw
-                    .filter((v) => typeof v === "string" && v.length > 0)
-                    .filter((v) => !/^https?:\/\//i.test(v))
-                    .map((v) => (isAbsolutePath(v) ? v : resolvePath(cwd, v)));
-                if (paths.length > 0)
-                    return paths;
-            }
-            if (policy.defaultToCwd && this.toolCtx?.cwd)
-                return [this.toolCtx.cwd];
-            return [];
-        }
-        const rawPatch = args[policy.arg];
-        if (typeof rawPatch !== "string" || rawPatch.length === 0)
-            return [];
-        try {
-            const parsed = parsePatch(rawPatch, "lenient");
+        const raw = args[policy.arg];
+        if (typeof raw === "string" && raw.length > 0) {
+            // Resolve a RELATIVE single-string path arg against ctx.cwd before
+            // classification, mirroring the array branch below and the apply_patch
+            // branch — otherwise classifyPath's process.cwd()-based resolution
+            // mis-places an in-workspace relative path (e.g. Read "src/x.ts") as
+            // "outside workspace" and over-prompts. Absolute paths pass through.
             const cwd = this.toolCtx?.cwd ?? process.cwd();
-            const targets = [];
-            for (const hunk of parsed.hunks) {
-                targets.push(resolvePath(cwd, hunk.path));
-                if (hunk.kind === "update" && hunk.movePath) {
-                    targets.push(resolvePath(cwd, hunk.movePath));
-                }
-            }
-            return targets;
+            return [isAbsolutePath(raw) ? raw : resolvePath(cwd, raw)];
         }
-        catch (err) {
-            return `Error: ${err.message}`;
+        // Array path args (e.g. GenerateImage `referenceImages`, GenerateVideo
+        // `images`): enforce EVERY element. Without this an array yielded zero
+        // targets, so out-of-workspace reads bypassed the path-policy "ask" gate
+        // that Read/Write enforce. http(s) URLs aren't file reads → skip them.
+        // Relative paths resolve against ctx.cwd (the workspace) before
+        // classification, like the apply_patch branch — otherwise classifyPath's
+        // process.cwd()-based resolution would mis-place an in-workspace relative
+        // path as "outside" and over-prompt. Non-string / empty elements skipped.
+        if (Array.isArray(raw)) {
+            const cwd = this.toolCtx?.cwd ?? process.cwd();
+            const paths = raw
+                .filter((v) => typeof v === "string" && v.length > 0)
+                .filter((v) => !/^https?:\/\//i.test(v))
+                .map((v) => (isAbsolutePath(v) ? v : resolvePath(cwd, v)));
+            if (paths.length > 0)
+                return paths;
         }
+        if (policy.defaultToCwd && this.toolCtx?.cwd)
+            return [this.toolCtx.cwd];
+        return [];
     }
 }

package/dist/tool-system/external-tool-exposure.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The Host Tool allowlist for external Agent Runtimes.
+ *
+ * This is a policy artifact, not plumbing. It exists as one reviewable file —
+ * rather than scattered through the Claude/Codex adapters — because the design
+ * (§9.1) requires each entry to have been risk-reviewed individually, and a
+ * reviewer needs to see the whole surface at once.
+ *
+ * Two rules shape everything here:
+ *
+ *  1. **Allowlist only.** No "everything in the registry", no prefix matching.
+ *     A tool absent from this file does not exist for an external runtime.
+ *     Widening it is an edit to this file, which is the point: it leaves a diff.
+ *  2. **Host-loopback tools are special** (§9.3). `Panel`, `Browser`,
+ *     `SwitchSessionWorkspace` and `InjectCredential` reach back out to a
+ *     specific Desktop renderer window to do their work. Passing `ToolExecutor`
+ *     does NOT make them callable — owner routing decides that, and it lives
+ *     outside the executor. Any such tool needs its owner story argued before it
+ *     can be listed.
+ *
+ * ## Why this is much wider than the original phase-one list
+ *
+ * The first cut exposed exactly one tool (`Panel`). That was not the product of
+ * a risk judgement so much as of an ordering: tools were held back until each
+ * had an argument written, and only one did. The result was a runtime that
+ * could list panels and nothing else — no skills, no memory, no file access —
+ * which is not a usable Agent Runtime, and made the feature's real state easy
+ * to overstate.
+ *
+ * The widening below was an explicit product-owner decision. The governing
+ * principle it rests on: **every tool here still executes through
+ * `ToolExecutor`**, so path policy, project trust, the user's permission rules
+ * and the approval UI all still apply. An external runtime holding `Bash` from
+ * this list is strictly more governed than the same model calling its own
+ * built-in shell, which answers only to the runtime's sandbox. Exposure moves
+ * capability from an unobservable authorization domain into the user's.
+ *
+ * That argument does not extend to everything, and four tools remain excluded
+ * for structural reasons rather than caution — see the block below them.
+ * `InjectCredential` is the highest-risk entry and depends on an in-tool
+ * approval that must stay mandatory; if that ever changes, it goes back out.
+ */
+import type { ExternalToolExposurePolicy } from "./session-tool-host.js";
+/** Why a tool is in (or out of) the first-phase allowlist. */
+export interface ExposureRationale {
+    tool: string;
+    /** `self-contained` completes in-process; `host-loopback` calls back to a window. */
+    kind: "self-contained" | "host-loopback";
+    status: "exposed" | "deferred" | "excluded";
+    reason: string;
+}
+/**
+ * The audit trail behind {@link FIRST_PHASE_EXPOSURE}. Kept as data so the
+ * "excluded" decisions are visible too — a bare allowlist tells a reviewer what
+ * was included but not what was considered and rejected, which is the more
+ * useful half when judging whether the surface is sound.
+ */
+export declare const FIRST_PHASE_EXPOSURE_RATIONALE: readonly ExposureRationale[];
+/** The phase-one policy. Pass to `createSessionToolHost({ exposure })`. */
+export declare const FIRST_PHASE_EXPOSURE: ExternalToolExposurePolicy;