@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/tool-system/builtin/sources.js

@@ -0,0 +1,137 @@
+/**
+ * 数据源只读读取面（ADR §5）。ListSources 只出 metadata（自动允许）；
+ * ReadSource 读内容（permissionDefault: ask，在 index.ts 注册处声明），
+ * 执行时对 source/scope/resource 二次校验（防审批后换参），结果带
+ * provenance + maxBytes 截断 + secret redaction + untrusted input 包裹。
+ */
+import { SettingsManager } from "../../settings/manager.js";
+import { connectorAdapterFor, registerConnectorAdapter } from "../../sources/adapter.js";
+import { LOCAL_FILES_SOURCE_ID, listLocalFiles, localFilesAdapter, } from "../../sources/adapters/local-files.js";
+import { defaultMcpResourceAdapter } from "../../sources/adapters/mcp-resource.js";
+import { mockAdapter } from "../../sources/adapters/mock.js";
+import { defaultCredentialStatus } from "../../sources/credential-status.js";
+import { resolveEffectiveSourceAccess } from "../../sources/resolve.js";
+import { truncateUtf8Text } from "../../sources/truncate-utf8.js";
+import { scrubSecrets } from "../../utils/secret-scrubber.js";
+import { wrapUntrustedInput } from "../../automation/write-policy.js";
+const DEFAULT_MAX_BYTES = 262_144;
+const mcpResourceAdapter = defaultMcpResourceAdapter();
+/** Registering the same adapter objects is safe to repeat across test/host imports. */
+export function registerBuiltinSourceAdapters() {
+    registerConnectorAdapter(mockAdapter);
+    registerConnectorAdapter(localFilesAdapter);
+    registerConnectorAdapter(mcpResourceAdapter);
+}
+registerBuiltinSourceAdapters();
+function accessFor(cwd) {
+    const settings = new SettingsManager(cwd, "full");
+    return resolveEffectiveSourceAccess({
+        cwd,
+        settings,
+        credentialStatus: defaultCredentialStatus,
+    });
+}
+async function resourcesFor(access, scope, cwd) {
+    if (access.sourceId === LOCAL_FILES_SOURCE_ID)
+        return listLocalFiles(cwd);
+    if (!access.definition)
+        return [];
+    return (await connectorAdapterFor(access.kind)?.listResources(access.definition, scope)) ?? [];
+}
+export const listSourcesToolDef = {
+    name: "ListSources",
+    description: "List the data sources bound to this workspace: names, scopes, availability status and resource names/sizes. Metadata only — use ReadSource to read content (requires approval).",
+    inputSchema: { type: "object", properties: {} },
+};
+export async function listSourcesTool(_args, ctx) {
+    const cwd = ctx?.cwd ?? process.cwd();
+    const access = accessFor(cwd);
+    if (access.length === 0)
+        return "No data sources are bound to this workspace.";
+    const lines = [];
+    for (const item of access) {
+        lines.push(`## ${item.label} (id: ${item.sourceId}, kind: ${item.kind}, status: ${item.status}, readPolicy: ${item.readPolicy})`);
+        if (item.status !== "ok")
+            continue;
+        for (const scope of item.scopes) {
+            let resources = [];
+            try {
+                resources = await resourcesFor(item, scope, cwd);
+            }
+            catch {
+                // Listing is metadata-only and best effort. A temporarily failing scope
+                // must not expose content or make the other bound sources disappear.
+            }
+            lines.push(`### scope: ${scope}`);
+            for (const resource of resources.filter((candidate) => candidate.scopeId === scope)) {
+                lines.push(`- ${resource.name} (resource: ${resource.id}${resource.sizeBytes === undefined ? "" : `, ${resource.sizeBytes}B`})`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+export const readSourceToolDef = {
+    name: "ReadSource",
+    description: "Read the content of one resource from a bound data source. Requires approval. Args must exactly match a bound source/scope and a listed resource id.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            source: { type: "string", description: "Bound source id (from ListSources)" },
+            scope: { type: "string", description: "Bound scope id" },
+            resource: { type: "string", description: "Resource id within that scope" },
+        },
+        required: ["source", "scope", "resource"],
+    },
+};
+export async function readSourceTool(args, ctx) {
+    const cwd = ctx?.cwd ?? process.cwd();
+    const source = String(args.source ?? "");
+    const scope = String(args.scope ?? "");
+    const resource = String(args.resource ?? "");
+    const signal = args.__signal;
+    // Second authorization gate after approval: the source must still be bound
+    // and healthy, and the requested scope must still be explicitly selected.
+    const access = accessFor(cwd).find((item) => item.sourceId === source);
+    if (!access)
+        return `Error: source "${source}" is not bound to this workspace.`;
+    if (access.status !== "ok")
+        return `Error: source "${source}" is ${access.status}.`;
+    if (access.readPolicy === "deny") {
+        return `Error: source "${source}" is metadata-only in this workspace (readPolicy: deny).`;
+    }
+    if (!access.scopes.includes(scope)) {
+        return `Error: scope "${scope}" is not bound for source "${source}".`;
+    }
+    if (!access.definition)
+        return `Error: source "${source}" is dangling.`;
+    const adapter = connectorAdapterFor(access.kind);
+    if (!adapter)
+        return `Error: no adapter for kind "${access.kind}".`;
+    try {
+        // Validate resource ownership from the selected scope's metadata before
+        // any content read. This prevents a valid id from another scope being used
+        // after approval with otherwise unchanged source/scope arguments.
+        const resources = await resourcesFor(access, scope, cwd);
+        const listed = resources.some((candidate) => candidate.id === resource && candidate.scopeId === scope);
+        if (!listed) {
+            return `Error: resource "${resource}" is not listed in scope "${scope}" for source "${source}".`;
+        }
+        const content = await adapter.read(access.definition, resource, {
+            maxBytes: DEFAULT_MAX_BYTES,
+            signal,
+            cwd,
+        });
+        if (content.resourceId !== resource) {
+            return `Error: source "${source}" returned a different resource id.`;
+        }
+        // Adapters enforce maxBytes too; keep this boundary-level cap so a future
+        // or injected adapter cannot bypass the 256 KiB context limit.
+        const capped = truncateUtf8Text(content.text, DEFAULT_MAX_BYTES);
+        const truncated = content.truncated || capped.truncated;
+        const provenance = `source=${source} scope=${scope} resource=${resource}${truncated ? " (truncated)" : ""}`;
+        return wrapUntrustedInput(scrubSecrets(capped.text), provenance);
+    }
+    catch (error) {
+        return `Error: read failed: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}

package/dist/tool-system/builtin/tool-search.js

@@ -5,6 +5,7 @@
  * The model uses ToolSearch to discover full schemas on demand,
  * saving context by not loading all MCP tool schemas upfront.
  */
+import { isRegisteredMcpToolAllowed } from "../mcp-tool-policy.js";
 export const toolSearchToolDef = {
     name: "ToolSearch",
     description: "Search for and discover available tools by name or keyword. " +
@@ -48,11 +49,15 @@ export async function toolSearchTool(args, ctx) {
         if (tool.source !== "mcp")
             return true;
         const allowed = ctx.allowedMcpServers;
-        return !allowed || allowed.has(tool.serverName ?? "");
+        return ((!allowed || allowed.has(tool.serverName ?? "")) &&
+            isRegisteredMcpToolAllowed(tool, ctx.mcpToolPolicies));
     };
     // "select:Name1,Name2" → exact match
     if (query.startsWith("select:")) {
-        const names = query.slice(7).split(",").map((n) => n.trim());
+        const names = query
+            .slice(7)
+            .split(",")
+            .map((n) => n.trim());
         return matchExact(ctx.toolRegistry, names, visible);
     }
     // Keyword search

package/dist/tool-system/builtin/update-automation-memory.js

@@ -47,6 +47,8 @@ export function makeUpdateAutomationMemoryTool(sink) {
             isReadOnly: false,
             isConcurrencySafe: false,
         },
+        // Host-injected automation contribution, never part of a default preset.
+        exposure: { presetTags: [] },
         execute: async (args) => {
             const raw = typeof args.summary === "string" ? args.summary : "";
             const summary = raw.trim();

package/dist/tool-system/builtin/web-fetch.js

@@ -28,8 +28,13 @@ const DEFAULT_MAX = 50_000;
 const RAW_BYTE_BUDGET_MULTIPLIER = 4;
 // Header names that must not be overridable via args.headers (SSRF / auth injection)
 const BLOCKED_REQUEST_HEADERS = new Set([
-    "host", "authorization", "cookie", "proxy-authorization",
-    "x-forwarded-for", "x-real-ip", "x-forwarded-host",
+    "host",
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "x-forwarded-for",
+    "x-real-ip",
+    "x-forwarded-host",
 ]);
 // Hostname patterns that block SSRF to internal/metadata services
 const BLOCKED_HOST_PATTERNS = [
@@ -41,15 +46,14 @@ const BLOCKED_HOST_PATTERNS = [
     /^192\.168\./,
     /^172\.(1[6-9]|2[0-9]|3[01])\./, // 172.16.0.0/12
     /^::1$/,
-    /^fc00:/i, /^fd00:/i, // IPv6 ULA
+    /^fc00:/i,
+    /^fd00:/i, // IPv6 ULA
     /^fe80:/i, // IPv6 link-local
 ];
 function isBlockedHost(hostname) {
     // `new URL("http://[::1]/").hostname` returns "[::1]" (with brackets);
     // strip them so IPv6 patterns match.
-    const stripped = hostname.startsWith("[") && hostname.endsWith("]")
-        ? hostname.slice(1, -1)
-        : hostname;
+    const stripped = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
     return BLOCKED_HOST_PATTERNS.some((re) => re.test(stripped));
 }
 // A3 hardening: per-IP block list. Used after DNS resolution to catch
@@ -119,11 +123,7 @@ const MAX_REDIRECTS = 5;
 // Headers that must be stripped when a redirect crosses origins.
 // Same policy fetch(... redirect: "follow") applies internally; we
 // re-implement it here because we drive redirects manually.
-const CROSS_ORIGIN_STRIP_HEADERS = new Set([
-    "authorization",
-    "cookie",
-    "proxy-authorization",
-]);
+const CROSS_ORIGIN_STRIP_HEADERS = new Set(["authorization", "cookie", "proxy-authorization"]);
 async function defaultDnsLookup(hostname) {
     // For literal IPs, lookup returns the IP itself (Node behavior),
     // which still flows through the block-list check above.
@@ -147,7 +147,10 @@ async function validateHopHost(u) {
         ips = await dnsLookupImpl(u.hostname);
     }
     catch (err) {
-        return { ok: false, reason: `DNS lookup failed for "${u.hostname}": ${err.message}` };
+        return {
+            ok: false,
+            reason: `DNS lookup failed for "${u.hostname}": ${err.message}`,
+        };
     }
     if (ips.length === 0) {
         return { ok: false, reason: `DNS returned no addresses for "${u.hostname}"` };
@@ -302,7 +305,8 @@ async function readAndTruncateBody(res, maxLength) {
     }
     if (rawTruncated || text.length > maxLength) {
         const shownChars = Math.min(text.length, maxLength);
-        text = text.slice(0, maxLength) + `\n\n... content truncated (showing first ${shownChars} chars)`;
+        text =
+            text.slice(0, maxLength) + `\n\n... content truncated (showing first ${shownChars} chars)`;
     }
     return text || "(page returned empty content)";
 }

package/dist/tool-system/builtin/web-search.js

@@ -153,9 +153,7 @@ export async function webSearchTool(args, ctx) {
         }
         if (results.length === 0)
             return "No results found.";
-        return results
-            .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`)
-            .join("\n\n");
+        return results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`).join("\n\n");
     }
     catch (err) {
         return `Search error: ${err.message}`;

package/dist/tool-system/capability-module.d.ts

@@ -0,0 +1,93 @@
+import type { RegisteredTool, StreamEvent } from "../types.js";
+import type { ToolContext } from "./context.js";
+import type { ToolRegistry } from "./registry.js";
+import type { BuiltinTool } from "./builtin/index.js";
+import type { RunBehaviorProfile } from "../engine/run-types.js";
+import type { PendingApprovalMetadata } from "../protocol/types.js";
+export interface ExtensionTool {
+    definition: RegisteredTool;
+    execute: (args: Record<string, unknown>, ctx?: ToolContext) => Promise<unknown>;
+}
+export type ExtensionQueryHandler = (params: Readonly<Record<string, unknown>>) => unknown | Promise<unknown>;
+/** Read-only live-session state exposed to protocol observers. */
+export interface ProtocolLiveSession {
+    sessionId: string;
+    busy: boolean;
+    queueDepth: number;
+    lastActivityAt: number;
+    kind: string;
+}
+/**
+ * Domain-agnostic protocol lifecycle observer. An extension module can attach
+ * one per AgentServer to project protocol activity (runs, stream events,
+ * approvals, session/server teardown) into its own state — without the server
+ * carrying any domain-specific logic. Observer callbacks must be cheap and
+ * must never throw (the server isolates exceptions per observer regardless).
+ */
+export interface ProtocolObserver {
+    /** A session was created/attached by agent/run (before the turn is queued). */
+    onSessionAttached?: (sessionId: string, lastActivityAt: number) => void;
+    /** Every StreamEvent forwarded to the client for a session's run. */
+    onSessionStream?: (sessionId: string, event: StreamEvent) => void;
+    /** Run lifecycle boundary: turn accepted (start), finished (end) or threw (error). */
+    onRunBoundary?: (sessionId: string, phase: "start" | "end" | "error") => void;
+    /**
+     * A pending approval was registered. May return replacement metadata (e.g.
+     * to override `surfaceable`); returning nothing keeps the input metadata.
+     */
+    onApprovalCreated?: (metadata: PendingApprovalMetadata) => PendingApprovalMetadata | void;
+    /** A pending approval left the pending state (resolved/expired/cancelled/owner-lost). */
+    onApprovalTransition?: (metadata: PendingApprovalMetadata, status: string) => void;
+    /** A session was explicitly closed (agent/closeSession). */
+    onSessionClosed?: (sessionId: string) => void;
+    /** The server is shutting down. */
+    onServerClose?: () => void;
+    /** Resolver-free pending-decision projections for host/debug snapshots. */
+    snapshotPendingDecisions?: () => readonly unknown[];
+}
+/** Capabilities the AgentServer lends to a protocol observer. */
+export interface ProtocolObserverHost {
+    /** Snapshot of live chat sessions (empty in legacy single-engine mode). */
+    getLiveSessionSnapshot: () => readonly ProtocolLiveSession[];
+    /** Host lifecycle generation attached to projection snapshots/deltas. */
+    projectionGeneration: () => number;
+    /** Persisted session kind, when the session is live and its engine knows it. */
+    getSessionKind: (sessionId: string) => string | undefined;
+    /** True once the server's transport owner disconnected. */
+    isTransportDisconnected: () => boolean;
+    /** Server → client notification. */
+    notify: (method: string, params: Record<string, unknown>) => void;
+    /** Register a protocol-method/query alias handled by this extension. */
+    registerQuery: (type: string, handler: ExtensionQueryHandler) => void;
+}
+/**
+ * Trusted, in-process product extension. Core owns the registration seam while
+ * optional packages own their tools and diagnostic/query surface.
+ */
+export interface ExtensionModule {
+    readonly id: string;
+    readonly tools?: readonly ExtensionTool[];
+    readonly queries?: Readonly<Record<string, ExtensionQueryHandler>>;
+    /** Named per-run behavior profiles contributed by this extension. */
+    readonly behaviorProfiles?: readonly RunBehaviorProfile[];
+    /** Attach a protocol lifecycle observer to an AgentServer. */
+    readonly createProtocolObserver?: (host: ProtocolObserverHost) => ProtocolObserver;
+    /** Extra agent/run params validation. Returns an error message or null. */
+    readonly validateRunParams?: (params: Record<string, unknown>) => string | null;
+    /** Session kinds this extension owns that must stay out of generic session lists. */
+    readonly hiddenSessionKinds?: readonly string[];
+    /**
+     * Full-metadata tool contributions (exposure tags, availability guards,
+     * per-turn definition rewrites, default permission rules). These join the
+     * engine's composed tool catalog exactly like builtin/capability tools do —
+     * use this instead of `tools` when the tool needs visibility metadata.
+     */
+    readonly catalogTools?: readonly BuiltinTool[];
+}
+export declare function registerExtensionModules(registry: ToolRegistry, modules: readonly ExtensionModule[]): void;
+export declare function queryExtensionModules(modules: readonly ExtensionModule[], type: string, params: Readonly<Record<string, unknown>>): Promise<{
+    handled: false;
+} | {
+    handled: true;
+    data: unknown;
+}>;

package/dist/tool-system/capability-module.js

@@ -0,0 +1,53 @@
+import { ConfigError } from "../exceptions.js";
+function validateExtensionModules(modules) {
+    const ids = new Set();
+    const queries = new Set();
+    const tools = new Set();
+    for (const module of modules) {
+        if (ids.has(module.id)) {
+            throw new ConfigError(`Duplicate capability module id: ${module.id}`, {
+                duplicateCapabilityId: module.id,
+            });
+        }
+        ids.add(module.id);
+        for (const tool of module.tools ?? []) {
+            if (tools.has(tool.definition.name)) {
+                throw new ConfigError(`Duplicate capability tool: ${tool.definition.name}`, {
+                    duplicateCapabilityTool: tool.definition.name,
+                });
+            }
+            tools.add(tool.definition.name);
+        }
+        for (const query of Object.keys(module.queries ?? {})) {
+            if (queries.has(query)) {
+                throw new ConfigError(`Duplicate capability query: ${query}`, {
+                    duplicateCapabilityQuery: query,
+                });
+            }
+            queries.add(query);
+        }
+    }
+}
+export function registerExtensionModules(registry, modules) {
+    validateExtensionModules(modules);
+    for (const module of modules) {
+        for (const tool of module.tools ?? []) {
+            if (registry.hasTool(tool.definition.name)) {
+                throw new ConfigError(`Capability tool conflicts with registered tool: ${tool.definition.name}`, {
+                    duplicateCapabilityTool: tool.definition.name,
+                    capabilityId: module.id,
+                });
+            }
+            registry.registerTool(tool.definition, tool.execute);
+        }
+    }
+}
+export async function queryExtensionModules(modules, type, params) {
+    validateExtensionModules(modules);
+    for (const module of modules) {
+        const handler = module.queries?.[type];
+        if (handler)
+            return { handled: true, data: await handler(params) };
+    }
+    return { handled: false };
+}

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.
@@ -16,11 +16,13 @@ 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
@@ -34,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;
 }
@@ -129,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
@@ -147,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 {
     /**
@@ -162,6 +164,8 @@ export interface SubAgentSpawner {
      * 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. */
@@ -186,7 +190,20 @@ export interface SubAgentSpawnResult {
 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;
@@ -197,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. */
@@ -282,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;
     /**
@@ -291,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
@@ -339,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
@@ -354,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
@@ -388,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