@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/tool-system/external-tool-exposure.js

@@ -0,0 +1,304 @@
+/**
+ * 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 const FIRST_PHASE_EXPOSURE_RATIONALE = [
+    {
+        tool: "Panel",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Only list/open/tools. These are read-or-focus, and they have a broadcast " +
+            "fallback, so they work without an owning window. invoke stays out for now " +
+            "for a DIFFERENT reason than originally recorded: the owner claim it was " +
+            "waiting on now exists and is wired (ExternalRuntimeService claims before " +
+            "the runtime starts), so the blocker is no longer technical. What is still " +
+            "missing is a per-Panel-App risk review — invoke runs third-party Panel App " +
+            "code with whatever arguments the model supplies, and argsPatterns cannot " +
+            "constrain a nested payload. Enabling it is a policy decision, not a wiring " +
+            "one, and it belongs to whoever reviews the first Panel App to be trusted.",
+    },
+    {
+        // NOTE the names: there is no tool called "Browser". The registry exposes
+        // three separate browser tools, and an allowlist entry for a name that does
+        // not exist is silently inert — it neither grants nor denies anything,
+        // which is the worst of both (a reviewer reads it as covered).
+        tool: "browser_navigate",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "The browser capability the runtime genuinely lacks — the differentiator, " +
+            "not a duplicate — and the owner argument it was waiting on is the same one " +
+            "Panel now has: ExternalRuntimeService registers the session and claims the " +
+            "owning window before the runtime starts. Stays under ToolExecutor plus the " +
+            "user's permission rules; without an owning window it fails closed on " +
+            "routing rather than broadcasting.",
+    },
+    {
+        tool: "browser_observe",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Reads page content. Same owner story as browser_navigate, no mutation.",
+    },
+    {
+        tool: "browser_act",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Click / type / interact — the mutating third of the browser surface, and " +
+            "the one that combines with InjectCredential to act as the logged-in user. " +
+            "Exposed on the product owner's call, under the same ToolExecutor rules as " +
+            "every other entry here.",
+    },
+    {
+        tool: "InjectCredential",
+        kind: "host-loopback",
+        status: "exposed",
+        reason: "Injects saved cookie credentials into the built-in browser to restore a " +
+            "login. This is the single highest-risk entry in this file and the one " +
+            "reviewers should look at first: it hands a live session cookie to a page, " +
+            "and a model that can also drive the Browser can then act as the logged-in " +
+            "user. §12.4 excluded credential-bearing tools outright; that blanket rule " +
+            "is relaxed here on the product owner's explicit call because credential " +
+            "restore is what makes browser automation usable at all. The mitigation is " +
+            "NOT the allowlist — it is the tool's own in-tool approval, which stays " +
+            "mandatory (see builtin/index.ts) and is never auto-approved for an " +
+            "external runtime. If that approval is ever made skippable, this entry must " +
+            "go back to excluded.",
+    },
+    // ── Still excluded, and for a different KIND of reason ───────────
+    // The four below are not held back out of caution — widening the allowlist
+    // does not make them work. Each is excluded by a structural property that
+    // would have to be designed away first, so listing them would produce a tool
+    // that is advertised and then fails or misbehaves.
+    {
+        tool: "Agent",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Can spawn another agent, so an external runtime could recurse into itself, " +
+            "nest approvals, and escape concurrency/budget limits (§12.5). Unlike Bash " +
+            "or Browser, this is not a permission question: the recursion has no owner " +
+            "and no budget to charge, so exposing it would need a nesting model first.",
+    },
+    {
+        tool: "DriveAgent",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Same recursion hazard as Agent (§12.5).",
+    },
+    {
+        tool: "EnterPlanMode",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Engine state-machine tool. Exposing it lets the runtime and the Native " +
+            "Engine drive each other's plan state (§12.3) — and an external runtime has " +
+            "no Engine plan state of its own to enter, so the call has no coherent " +
+            "meaning on this path.",
+    },
+    {
+        tool: "ExitPlanMode",
+        kind: "self-contained",
+        status: "excluded",
+        reason: "Engine state-machine tool; same reason as EnterPlanMode.",
+    },
+    {
+        tool: "Read",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Overlaps a tool the runtime already has, which was the original reason to " +
+            "exclude it. That reasoning was wrong about which risk matters: the runtime's " +
+            "OWN Read answers to the runtime's sandbox, while this one answers to " +
+            "ToolExecutor — path policy, project trust and the user's permission rules. " +
+            "Exposing it means the model has a reachable path that IS governed by " +
+            "CodeShell, which is the point of augmented mode. Naming overlap is a " +
+            "presentation problem (the MCP server prefixes its tools); sandbox " +
+            "divergence is a security one.",
+    },
+    {
+        tool: "Bash",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Same argument as Read, and it is the tool where it matters most: the " +
+            "runtime's own shell runs under the runtime's approval policy, which the " +
+            "user did not configure and cannot see. Routing a shell call through " +
+            "ToolExecutor puts it under the user's own permission rules and the " +
+            "approval UI. Note this does NOT remove the runtime's own shell — it adds a " +
+            "governed alternative.",
+    },
+    // ── Skills, memory and planning ──────────────────────────────────
+    // These are the reason someone runs a model inside CodeShell rather than in a
+    // bare terminal. A runtime that cannot reach them is a stranger in the app: it
+    // cannot load the user's skills, cannot recall anything, and forgets the
+    // session the moment it ends. Phase one excluded them by omission rather than
+    // by argument — no rationale entry existed at all, which is how a surface ends
+    // up shipping at 1 tool out of 48 without anyone deciding that.
+    {
+        tool: "Skill",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Loads a SKILL.md body and returns it as the tool result — it reads from " +
+            "the scanner, never the disk directly, and executes nothing itself. A skill " +
+            "body may TELL the model to run commands, but those become ordinary tool " +
+            "calls that face the same authorization as any other. Withholding Skill " +
+            "does not withhold that capability; it only withholds the user's own " +
+            "curated instructions.",
+    },
+    {
+        tool: "MemoryRead",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Reads the user's memory store. No side effects.",
+    },
+    {
+        tool: "MemoryList",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Enumerates memory entries. No side effects.",
+    },
+    {
+        tool: "MemorySave",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Writes to the memory store, so it is a mutation — but a scoped one, into " +
+            "a store the user can read and edit, and it carries the same permission " +
+            "rules as on the native path.",
+    },
+    {
+        tool: "MemoryDelete",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Mutation, same store and same rules as MemorySave.",
+    },
+    {
+        tool: "TodoWrite",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Session-scoped task list. Visible to the user, trivially reversible.",
+    },
+    {
+        tool: "Glob",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Path search under the same path policy as Read.",
+    },
+    {
+        tool: "Grep",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Content search under the same path policy as Read.",
+    },
+    {
+        tool: "Write",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "File mutation governed by ToolExecutor. Same argument as Bash.",
+    },
+    {
+        tool: "Edit",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "File mutation governed by ToolExecutor. Same argument as Bash.",
+    },
+    {
+        tool: "WebSearch",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Read-only network lookup; already available to the model by other means.",
+    },
+    {
+        tool: "WebFetch",
+        kind: "self-contained",
+        status: "exposed",
+        reason: "Read-only fetch, subject to the same URL handling as the native path.",
+    },
+];
+/**
+ * Action-level narrowing for tools that multiplex several operations behind one
+ * name. Anchored automatically — see `matchesWholeValue`.
+ *
+ * This is a second, independent layer from the tool's own
+ * `defaultPermissionRules`: those decide allow/ask for a call that IS permitted,
+ * while this decides whether the action is reachable from an external runtime at
+ * all. Both are narrowed to read-only actions in phase one, and `Panel.invoke`
+ * additionally fails closed on owner routing — three independent barriers, by
+ * design.
+ */
+const FIRST_PHASE_ARGS_PATTERNS = new Map([
+    // Panel.invoke remains the one action-level restriction. It runs third-party
+    // Panel App code with whatever arguments the model supplies, and argsPatterns
+    // cannot constrain a nested payload — so unlike every tool widened above, the
+    // authorization layer genuinely cannot see what is being authorized. Enabling
+    // it belongs to whoever reviews the first Panel App to be trusted.
+    ["Panel", { action: "list|open|tools" }],
+]);
+/**
+ * `ReadonlySet` / `ReadonlyMap` are compile-time only — the underlying `Set` and
+ * `Map` stay mutable at runtime, and this policy is a process-wide singleton read
+ * live on every `execute()`. Without this, one `argsPatterns.delete("Panel")`
+ * anywhere in the process would re-enable `Panel.invoke` for every already-running
+ * host: exactly the capability held back pending the §9.3.2 owner claim.
+ */
+function reject() {
+    throw new TypeError("The external tool exposure policy is frozen and cannot be widened.");
+}
+/**
+ * Hand out a plain object implementing the read half of `Set`, not a real `Set`.
+ *
+ * Shadowing `add`/`delete`/`clear` on a `Set` is not enough: the prototype method
+ * is still reachable (`Set.prototype.add.call(policySet, "Bash")`), and `delete
+ * s.add` un-shadows it. Returning a non-`Set` object removes the mutators
+ * entirely — there is no `Set` internal slot to target — and `Object.freeze`
+ * stops the read methods from being swapped out.
+ */
+function frozenSet(values) {
+    const inner = new Set(values);
+    const view = Object.freeze({
+        has: (value) => inner.has(value),
+        get size() {
+            return inner.size;
+        },
+        keys: () => inner.keys(),
+        values: () => inner.values(),
+        entries: () => inner.entries(),
+        // Pass the VIEW as the third argument, never `inner`. Set.prototype.forEach
+        // hands the callback the collection itself, so forwarding `inner` would leak
+        // a live mutable handle to the very object this wrapper exists to protect —
+        // `policy.forEach((_a, _b, s) => s.add("Bash"))` would widen it in one line,
+        // through the public frozen API, with no prototype tricks at all.
+        forEach: (fn, thisArg) => inner.forEach((a, b) => fn.call(thisArg, a, b, view)),
+        [Symbol.iterator]: () => inner[Symbol.iterator](),
+        add: reject,
+        delete: reject,
+        clear: reject,
+    });
+    return view;
+}
+/** Same reasoning as {@link frozenSet}, for the args-pattern map. */
+function frozenMap(entries) {
+    const inner = new Map(entries);
+    const view = Object.freeze({
+        get: (key) => inner.get(key),
+        has: (key) => inner.has(key),
+        get size() {
+            return inner.size;
+        },
+        keys: () => inner.keys(),
+        values: () => inner.values(),
+        entries: () => inner.entries(),
+        // See frozenSet.forEach — arg 3 must be the view, not `inner`.
+        forEach: (fn, thisArg) => inner.forEach((v, k) => fn.call(thisArg, v, k, view)),
+        [Symbol.iterator]: () => inner[Symbol.iterator](),
+        set: reject,
+        delete: reject,
+        clear: reject,
+    });
+    return view;
+}
+/** The phase-one policy. Pass to `createSessionToolHost({ exposure })`. */
+export const FIRST_PHASE_EXPOSURE = Object.freeze({
+    mode: "allowlist",
+    toolNames: frozenSet(FIRST_PHASE_EXPOSURE_RATIONALE.filter((entry) => entry.status === "exposed").map((entry) => entry.tool)),
+    argsPatterns: frozenMap([...FIRST_PHASE_ARGS_PATTERNS].map(([tool, patterns]) => [
+        tool,
+        Object.freeze({ ...patterns }),
+    ])),
+});

package/dist/tool-system/mcp-manager.d.ts

@@ -48,6 +48,12 @@ export declare function buildStdioEnv(serverName: string, config: MCPServerConfi
 export declare function buildHttpHeaders(serverName: string, config: MCPServerConfig, resolveCredential?: (id: string) => HttpCredentialResolverResult, options?: BuildHttpHeadersOptions): Record<string, string>;
 export declare function bearerTokenFromMcpCredential(serverName: string, credentialId: string, credential: ResolvedMcpCredential, options?: BuildHttpHeadersOptions): string;
 export declare function buildHttpHeadersWithCredentialAccess(serverName: string, config: MCPServerConfig, access?: Pick<CredentialAccess, "resolveValue"> & Partial<Pick<CredentialAccess, "resolveMeta">>, options?: BuildHttpHeadersOptions): Promise<Record<string, string>>;
+/**
+ * Fetch adapter for long-lived HTTP MCP transports. OAuth access tokens are
+ * resolved for every request, refreshed by the host inside the skew window,
+ * and force-refreshed once after a replayable 401.
+ */
+export declare function createMcpAuthenticatedFetch(serverName: string, config: MCPServerConfig, access?: CredentialAccess, baseFetch?: typeof fetch): typeof fetch;
 /**
  * Infer the transport when the config doesn't name one: a url-only entry is
  * HTTP, everything else stdio. This is the CC `.mcp.json` convention —
@@ -73,6 +79,16 @@ export declare function spillMcpImage(serverName: string, toolName: string, base
 export declare function wrapMcpOutput(serverName: string, toolName: string, body: string): string;
 export declare function stripInternalToolArgs(args: Record<string, unknown>): Record<string, unknown>;
 export declare function buildRegisteredTool(serverName: string, tool: McpTool): RegisteredTool;
+/**
+ * Per-server outcome of a connectAll() sweep (see the optional onServerEvent
+ * parameter). The engine forwards these onto the `notification` hook so hosts
+ * and plugins can surface MCP availability without polling.
+ */
+export interface McpServerLifecycleEvent {
+    type: "mcp_server_connected" | "mcp_server_failed";
+    server: string;
+    error?: string;
+}
 export declare class MCPManager {
     private readonly toolRegistry;
     private static instance;
@@ -98,7 +114,7 @@ export declare class MCPManager {
     /**
      * Connect to all configured MCP servers and register their tools.
      */
-    connectAll(servers: Record<string, MCPServerConfig>, owner?: unknown): Promise<void>;
+    connectAll(servers: Record<string, MCPServerConfig>, owner?: unknown, onServerEvent?: (event: McpServerLifecycleEvent) => void): Promise<void>;
     reconcile(servers: Record<string, MCPServerConfig>, owner?: unknown): Promise<void>;
     /**
      * Remove one owner from the shared desired-server pool and disconnect servers

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

@@ -11,6 +11,7 @@ import { getCredentialAccess } from "../credentials/access.js";
 import { buildOAuthRefreshRequest, oauthCredentialStatus, parseOAuthCredentialSecret, } from "../credentials/oauth.js";
 import { ENV_ALLOWLIST } from "../runtime/spawn-common.js";
 import { mkdir, readdir, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { diagnoseMcpStdioMissingCommand, previewPath } from "./mcp-stdio-diagnostics.js";
 import { codeShellHome } from "../session/session-manager.js";
@@ -153,6 +154,60 @@ export async function buildHttpHeadersWithCredentialAccess(serverName, config, a
     });
     return buildHttpHeaders(serverName, config, (id) => id === config.credentialRef ? { secret, type: meta?.type, label: meta?.label } : undefined, options);
 }
+/**
+ * Fetch adapter for long-lived HTTP MCP transports. OAuth access tokens are
+ * resolved for every request, refreshed by the host inside the skew window,
+ * and force-refreshed once after a replayable 401.
+ */
+export function createMcpAuthenticatedFetch(serverName, config, access = getCredentialAccess(), baseFetch = fetch) {
+    return (async (input, init) => {
+        const credentialId = config.credentialRef;
+        const meta = credentialId ? access.resolveMeta(undefined, credentialId, "full") : undefined;
+        const isOAuth = meta?.type === "oauth";
+        const headers = isOAuth
+            ? buildHttpHeaders(serverName, { ...config, credentialRef: undefined })
+            : await buildHttpHeadersWithCredentialAccess(serverName, config, access);
+        let token;
+        if (isOAuth) {
+            if (!access.resolveOAuthAccess) {
+                throw new Error(`MCP server "${serverName}": oauth credential "${credentialId}" requires host OAuth access`);
+            }
+            token = (await access.resolveOAuthAccess({ id: credentialId, scope: "full" })).accessToken;
+        }
+        // The SDK and Bun can contribute distinct undici-compatible Request types.
+        // Normalize once at the adapter boundary instead of leaking that ambient
+        // declaration mismatch through the authentication/replay logic.
+        const source = new Request(input, init);
+        let replayable = true;
+        try {
+            source.clone();
+        }
+        catch {
+            replayable = false;
+        }
+        const send = async (accessToken) => {
+            const request = replayable ? source.clone() : source;
+            const requestHeaders = new Headers(Array.from(request.headers.entries()));
+            for (const [name, value] of Object.entries(headers))
+                requestHeaders.set(name, value);
+            if (accessToken)
+                requestHeaders.set("Authorization", `Bearer ${accessToken}`);
+            return baseFetch(new Request(request, {
+                headers: Array.from(requestHeaders.entries()),
+            }));
+        };
+        const first = await send(token);
+        if (first.status !== 401 || !isOAuth || !credentialId || !replayable || source.signal.aborted) {
+            return first;
+        }
+        const refreshed = await access.resolveOAuthAccess({
+            id: credentialId,
+            scope: "full",
+            forceRefresh: true,
+        });
+        return send(refreshed.accessToken);
+    });
+}
 /**
  * Infer the transport when the config doesn't name one: a url-only entry is
  * HTTP, everything else stdio. This is the CC `.mcp.json` convention —
@@ -186,9 +241,7 @@ const MAX_MCP_IMAGE_SPILLS_PER_TOOL = 50;
 const MAX_MCP_IMAGE_BYTES = 8 * 1024 * 1024;
 function spillTimestamp(filename, prefix) {
     const suffix = filename.slice(prefix.length);
-    const dot = suffix.lastIndexOf(".");
-    const raw = dot === -1 ? suffix : suffix.slice(0, dot);
-    const timestamp = Number(raw);
+    const timestamp = Number(/^\d+/.exec(suffix)?.[0]);
     return Number.isFinite(timestamp) ? timestamp : 0;
 }
 async function pruneMcpImageSpills(baseDir, prefix) {
@@ -232,7 +285,7 @@ export async function spillMcpImage(serverName, toolName, base64, mimeType, opts
     const safeServer = serverName.replace(/[^\w.-]+/g, "_");
     const safeTool = toolName.replace(/[^\w.-]+/g, "_");
     const prefix = `${safeServer}-${safeTool}-`;
-    const filename = `${prefix}${now()}.${ext}`;
+    const filename = `${prefix}${now()}-${randomUUID().slice(0, 8)}.${ext}`;
     const filePath = join(baseDir, filename);
     try {
         await mkdir(baseDir, { recursive: true });
@@ -297,6 +350,7 @@ export function buildRegisteredTool(serverName, tool) {
         },
         source: "mcp",
         serverName,
+        mcpToolName: tool.name,
         permissionDefault: "ask",
         isConcurrencySafe: readOnly,
         isReadOnly: readOnly,
@@ -335,7 +389,7 @@ export class MCPManager {
     /**
      * Connect to all configured MCP servers and register their tools.
      */
-    async connectAll(servers, owner) {
+    async connectAll(servers, owner, onServerEvent) {
         const enabledNames = this.enabledServerNames(servers);
         // Register this owner's desired set up front (see reconcile's shared-pool
         // note) so a later reconcile from ANOTHER session can't disconnect servers
@@ -362,12 +416,21 @@ export class MCPManager {
         const results = await Promise.allSettled(entries.map(([name, config]) => this.connect(name, config)));
         for (let i = 0; i < results.length; i++) {
             const result = results[i];
+            const server = entries[i][0];
             if (result.status === "rejected") {
                 logger.warn("mcp.connect_failed", {
-                    server: entries[i][0],
+                    server,
                     error: result.reason.message,
                 });
             }
+            try {
+                onServerEvent?.(result.status === "rejected"
+                    ? { type: "mcp_server_failed", server, error: result.reason.message }
+                    : { type: "mcp_server_connected", server });
+            }
+            catch {
+                /* observers must not affect connection handling */
+            }
         }
     }
     async reconcile(servers, owner) {
@@ -472,9 +535,11 @@ export class MCPManager {
             // credentialRef resolves against user-scope credential access. The shared
             // MCPManager pool has no per-session cwd, and MCP-referenced credentials
             // (e.g. a Figma token) remain user-global by design.
-            const headers = await buildHttpHeadersWithCredentialAccess(name, config);
+            const access = getCredentialAccess();
+            const headers = buildHttpHeaders(name, { ...config, credentialRef: undefined });
             transport = new StreamableHTTPClientTransport(new URL(config.url), {
                 requestInit: Object.keys(headers).length ? { headers } : undefined,
+                fetch: createMcpAuthenticatedFetch(name, config, access),
             });
         }
         else {

package/dist/tool-system/mcp-tool-policy.d.ts

@@ -0,0 +1,9 @@
+import type { MCPServerConfig, RegisteredTool } from "../types.js";
+export interface McpToolPolicy {
+    /** Undefined means every tool is eligible before the denylist is applied. */
+    allowedTools?: ReadonlySet<string>;
+    disabledTools: ReadonlySet<string>;
+}
+export declare function buildMcpToolPolicies(servers: Record<string, MCPServerConfig>): ReadonlyMap<string, McpToolPolicy>;
+export declare function isMcpToolNameAllowed(policies: ReadonlyMap<string, McpToolPolicy> | undefined, serverName: string, toolName: string): boolean;
+export declare function isRegisteredMcpToolAllowed(tool: Pick<RegisteredTool, "source" | "serverName" | "mcpToolName">, policies: ReadonlyMap<string, McpToolPolicy> | undefined): boolean;

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.d.ts

@@ -49,11 +49,30 @@ export interface ClassifyOptions {
     /** "read" or "write" — different defaults for sensitive paths. */
     operation: PathOperation;
 }
+export interface FinalWritePathSnapshot {
+    resolvedPath: string;
+    workspacePath: string;
+    insideWorkspace: boolean;
+}
 export type PathApprovalScope = "once" | "session" | "project";
 /** Test seam: clear the in-memory session grants. */
 export declare function _resetSessionPathGrants(): void;
 export declare function openSessionPathApprovals(sessionId: string): void;
 export declare function clearSessionPathApprovals(sessionId: string): void;
+/**
+ * Capture the concrete target approved by the executor's first path-policy
+ * pass. The snapshot is carried on the internal args object via a symbol, so
+ * it cannot collide with an LLM-supplied schema property or leak into logs.
+ */
+export declare function attachFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string): Record<string, unknown>;
+export declare function getFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string): FinalWritePathSnapshot;
+export declare function revalidateFinalWritePath(filePath: string, workspaceRoot: string, approved: FinalWritePathSnapshot): {
+    resolvedPath: string;
+} | {
+    error: string;
+};
+/** Open the already-revalidated final path without following its last segment. */
+export declare function writeFileNoFollow(filePath: string, content: string): Promise<void>;
 /**
  * Classify a file path against the workspace + sensitive-path policy.
  *