@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.1

package/dist/tool-system/builtin/worktree.d.ts

@@ -2,9 +2,10 @@
  * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 import { type WorktreeSession } from "../../git/worktree.js";
 export declare function getActiveWorktree(): WorktreeSession | undefined;
 export declare const enterWorktreeToolDef: ToolDefinition;
-export declare function enterWorktreeTool(args: Record<string, unknown>): Promise<string>;
+export declare function enterWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const exitWorktreeToolDef: ToolDefinition;
 export declare function exitWorktreeTool(args: Record<string, unknown>): Promise<string>;

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

@@ -1,7 +1,7 @@
 /**
  * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
  */
-import { createWorktree, removeWorktree, validateWorktreeSlug, } from "../../git/worktree.js";
+import { createWorktree, removeWorktree, validateWorktreeSlug, selectPlatformScript, runWorktreeSetup, } from "../../git/worktree.js";
 // Global worktree state
 let _activeWorktree;
 export function getActiveWorktree() {
@@ -25,7 +25,7 @@ export const enterWorktreeToolDef = {
         required: ["slug"],
     },
 };
-export async function enterWorktreeTool(args) {
+export async function enterWorktreeTool(args, ctx) {
     const slug = args.slug;
     if (!slug)
         return "Error: slug is required";
@@ -41,18 +41,45 @@ export async function enterWorktreeTool(args) {
     try {
         // Use a placeholder session ID (the agent should set this properly)
         const sessionId = args.__sessionId ?? `wt-${Date.now()}`;
-        const cwd = args.__cwd ?? process.cwd();
+        const cwd = args.__cwd ?? ctx?.cwd ?? process.cwd();
         _activeWorktree = createWorktree(cwd, slug, sessionId);
+        // Run the project's localEnvironment.setupScripts once in the new
+        // worktree root (Beta decision 2026-06-08: setup belongs to the worktree
+        // lifecycle, not the conversation). Failure warns-but-continues — a broken
+        // setup script must not strand the agent outside a worktree it just made.
+        let setupNote = "";
+        const setupScripts = ctx?.engine?.readWorktreeSetupScripts(cwd);
+        const script = selectPlatformScript(setupScripts);
+        if (script) {
+            const setup = await runWorktreeSetup(_activeWorktree.worktreePath, script, {
+                sandbox: ctx?.sandbox,
+                shellEnv: ctx?.shellEnv,
+                signal: ctx?.signal,
+            });
+            if (setup.ok) {
+                setupNote = `\n\nRan setup script (exit 0).${setup.output ? `\n${truncate(setup.output)}` : ""}`;
+            }
+            else {
+                setupNote =
+                    `\n\n⚠️ Setup script failed (exit ${setup.exitCode ?? "?"}) — continuing anyway. ` +
+                        `You may need to run setup manually.${setup.output ? `\n${truncate(setup.output)}` : ""}`;
+            }
+        }
         return (`Worktree created:\n` +
             `  Path:   ${_activeWorktree.worktreePath}\n` +
             `  Branch: ${_activeWorktree.worktreeBranch}\n` +
             `  From:   ${_activeWorktree.originalBranch ?? "HEAD"}\n\n` +
-            `You are now working in an isolated copy. Changes here won't affect the main repo.`);
+            `You are now working in an isolated copy. Changes here won't affect the main repo.` +
+            setupNote);
     }
     catch (err) {
         return `Error creating worktree: ${err.message}`;
     }
 }
+/** Keep setup output from bloating the tool result — head+tail-ish trim. */
+function truncate(s, max = 2000) {
+    return s.length <= max ? s : `${s.slice(0, max)}\n…(${s.length - max} more chars)`;
+}
 export const exitWorktreeToolDef = {
     name: "ExitWorktree",
     description: "Exit the current worktree and return to the main working directory. " +

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

@@ -4,7 +4,6 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { fileCache } from "./file-cache.js";
-import { enforcePathPolicy } from "../path-policy.js";
 export const writeToolDef = {
     name: "Write",
     description: "Write content to a file. Creates the file if it doesn't exist, " +
@@ -25,11 +24,6 @@ export async function writeTool(args, ctx) {
         return "Error: file_path is required";
     if (content === undefined)
         return "Error: content is required";
-    // Path policy gate: deny writes to sensitive paths, refuse writes outside
-    // workspace until approved. See tool-system/path-policy.ts.
-    const blocked = enforcePathPolicy(filePath, "write", ctx?.cwd);
-    if (blocked)
-        return blocked;
     try {
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, content, "utf-8");

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

@@ -18,11 +18,39 @@ import type { ToolRegistry } from "./registry.js";
 import type { AgentPresetName } from "../preset/index.js";
 import type { SandboxBackend } from "./sandbox/index.js";
 import type { HookRegistry } from "../hooks/registry.js";
-import type { Engine } from "../engine/engine.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
+ * concrete `Engine` type so tool-system does NOT depend on the top-level
+ * engine module — that import created a tool-system ↔ engine cycle. The Engine
+ * class satisfies this structurally (no `implements` needed); this interface
+ * lists exactly the members tools use today (see plan.ts / worktree.ts).
+ */
+export interface ToolRuntimeHost {
+    /** Whether the owning Engine is currently in plan mode. */
+    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;
+}
 /** One choice in a multiple-choice AskUserQuestion. */
 export interface AskUserChoice {
     label: string;
     description: string;
+    /**
+     * Optional semantic hint for how the UI colors this choice and its resolved
+     * echo — `ok` (affirmative / allow → green ✓), `danger` (negative / deny →
+     * red ✕), `neutral` (no coloring). Only set by trusted first-party callers
+     * with fixed option sets (e.g. the credential-use gate); the LLM-facing
+     * AskUserQuestion tool strips it so model-authored prompts stay neutral.
+     */
+    tone?: "ok" | "danger" | "neutral";
 }
 /**
  * Optional rendering hints / multiple-choice options carried alongside the
@@ -35,6 +63,14 @@ export interface AskUserOptions {
     options?: AskUserChoice[];
     /** Allow the user to pick more than one option. Defaults to false. */
     multiSelect?: boolean;
+    /**
+     * When true, the UI must offer ONLY the given `options` — no "其它…"
+     * free-text escape hatch. Used by closed-set decisions (e.g. a path-permission
+     * 允许本次/拒绝 prompt) where the answer is interpreted by an exact label
+     * match, so a free-typed answer like "允许" would never match and silently
+     * deny. Ignored unless `options` is non-empty.
+     */
+    optionsOnly?: boolean;
 }
 /**
  * Function the host UI / server uses to ask the user a question.
@@ -76,6 +112,12 @@ export interface SubAgentSpawnRequest {
      * Undefined → child inherits the parent's full tool set (current behavior).
      */
     toolAllowlist?: string[];
+    /**
+     * Optional skill-name allowlist for the child (hard isolation). When set,
+     * the child only sees/invokes these skills in its system prompt and Skill
+     * tool. Undefined → child inherits the parent's full skill pool.
+     */
+    skillAllowlist?: string[];
     /**
      * Optional per-call system prompt appended to the child Engine's prompt
      * (the role definition's Markdown body). Undefined → child inherits only
@@ -84,10 +126,34 @@ export interface SubAgentSpawnRequest {
     appendSystemPrompt?: string;
     /** True for read-only reviewer/researcher children; tunes investigation guard reminders. */
     readOnlySession?: boolean;
+    /**
+     * Resume an existing child session instead of cold-starting a new one.
+     * When set, the child Engine runs with `sessionId: resumeSessionId`, which
+     * loads that session's full transcript (all prior tool calls + results) and
+     * appends this turn's prompt — i.e. transcript replay, the CC model. When
+     * omitted, the child cold-starts under its own `agentId` as the session id
+     * (so `agentId === childSid`, enabling later resume with no extra mapping).
+     * See AgentSendInput in builtin/agent.ts.
+     */
+    resumeSessionId?: string;
 }
 export interface SubAgentSpawner {
-    /** Run a sub-agent synchronously and return its text output. */
-    spawn(req: SubAgentSpawnRequest): Promise<string>;
+    /**
+     * Run a sub-agent synchronously. Returns its text output and the child's
+     * session id. The session id equals the request's `agentId` on a cold start
+     * (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;
+    }>;
+    /**
+     * 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;
     /** 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. */
@@ -156,9 +222,18 @@ export interface ToolContext {
     /** Whether the owning Engine is currently in plan mode. Replaces the
      *  removed module-level `isInPlanMode()` singleton. */
     planMode: boolean;
-    /** The Engine that built this context. Lets tools call back into the engine
-     *  (e.g. ctx.engine.setPlanMode(true/false)) without a module-level singleton. */
-    engine: Engine;
+    /**
+     * The owning Engine's permission mode. Path policy reads this so that
+     * `bypassPermissions` (the user's "完全访问") skips the path-approval prompt
+     * entirely — matching the tool-permission backend and CC, where bypass
+     * skips ALL checks including path validation. Undefined → treat as
+     * "default" (always enforce). */
+    permissionMode?: string;
+    /** The Engine that built this context, as the narrow {@link ToolRuntimeHost}
+     *  view. Lets tools call back into the engine (e.g. ctx.engine.setPlanMode)
+     *  without a module-level singleton — and without tool-system depending on
+     *  the concrete Engine type (which would re-introduce the import cycle). */
+    engine: ToolRuntimeHost;
     /**
      * sessionId of the Engine.run() turn this context was built for. Tools
      * that emit session-scoped side effects (today: background-agent
@@ -183,6 +258,28 @@ export interface ToolContext {
      * `settings.disabledPlugins` by Engine.run().
      */
     disabledPlugins?: string[];
+    /**
+     * Sub-agent skill allowlist (hard isolation). When set, this sub-agent may
+     * only see/invoke skills in this list — applied on top of the disabled
+     * lists. Undefined → inherit the parent's full pool (current behavior).
+     * Comes from the agent role definition's `skills:` frontmatter, threaded
+     * through SubAgentSpawnRequest.skillAllowlist into the child Engine.
+     */
+    skillAllowlist?: string[];
+    /**
+     * Background-shell manager (Bash run_in_background + BashOutput / KillShell
+     * / ListShells). Undefined → the tools fall back to the process-local
+     * `backgroundShellManager` singleton. Threaded explicitly so tests (and
+     * any future per-engine isolation) can inject their own instance.
+     */
+    backgroundShells?: import("../runtime/background-shell.js").BackgroundShellManager;
+    /**
+     * False in unattended automation/cron runs — `Bash(run_in_background=true)`
+     * is rejected and the three background-shell tools are stripped (design
+     * §5.5): no one is watching to reap a long-lived dev server. Defaults to
+     * true (interactive sessions allow it).
+     */
+    allowBackgroundShells?: boolean;
     /**
      * Builtin tool names the project's capabilityOverrides marked `off` for
      * this cwd. Engine.run() already HIDES these from the LLM-visible tool
@@ -193,7 +290,58 @@ export interface ToolContext {
      * sub-agents and no-cwd contexts (same as readBuiltinOverride).
      */
     disabledBuiltins?: Set<string>;
+    /**
+     * MCP servers THIS session's merged config enables (keys of
+     * config.mcpServers, enabled!==false). The pool + registry are
+     * worker-shared (B1), so tools registered by another project's session live
+     * in the same registry — the engine hides them from this session's tool
+     * list and the executor rejects calls to them via this set. Undefined =
+     * no gating (sub-agents / tests whose registries carry no MCP tools).
+     */
+    allowedMcpServers?: Set<string>;
+    /**
+     * 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
+     * the host user's ~/.code-shell. "full" = host app (user + project); "project"
+     * / "isolated" = must not surface host user credentials or autoApprove.
+     * Undefined = legacy/no-cwd → treated as "full" by consumers for compat.
+     */
+    settingsScope?: import("../settings/manager.js").SettingsScope;
+    /**
+     * Project-scoped extra environment variables (the user's
+     * `localEnvironment.env` KEY=VALUE pairs for this cwd). Layered on top of
+     * the shell env that the Bash tool and background shells build, so a project
+     * can inject e.g. `DATABASE_URL` / `NODE_ENV` into every command it runs.
+     * Unlike the sandbox allowlist, these bypass the deny regex — the user put
+     * them in project settings deliberately. Undefined for sub-agents and
+     * no-cwd contexts (populated from settings by Engine.buildToolContext()).
+     */
+    shellEnv?: Record<string, string>;
+    /**
+     * Browser automation bridge (browser_snapshot / click / type / navigate /
+     * scroll). The renderer implements it on top of the webview's CDP
+     * (Accessibility.getFullAXTree + Input.dispatchMouseEvent). Undefined →
+     * headless / no browser panel → the browser tools degrade with a clear error.
+     * See tool-system/browser-bridge.ts and the MVP spec
+     * docs/superpowers/specs/2026-06-16-browser-automation-mvp.md.
+     */
+    browser?: import("./browser-bridge.js").BrowserBridge;
+    /**
+     * 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
+     * (desktop main) implements it on top of `restoreCookiesToBrowser`. Undefined
+     * → headless / no browser → the InjectCredential tool degrades with a clear
+     * error. Mirrors the askUser cross-process callback shape. The credentialId
+     * names a `type:"cookie"` credential; result counts cookies written.
+     */
+    injectCredentialToBrowser?: InjectCredentialFn;
 }
+/** Inject a cookie credential into the built-in browser (host-implemented). */
+export type InjectCredentialFn = (credentialId: string) => Promise<{
+    ok: boolean;
+    count?: number;
+    error?: string;
+}>;
 /**
  * Per-Engine container that produces a fresh ToolContext on demand.
  * Engine creates one of these in run() and passes it to ToolExecutor.

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

@@ -39,7 +39,9 @@ export declare class ToolExecutor {
     /** Check if a tool is safe for concurrent execution (read-only). */
     isConcurrencySafe(toolName: string): boolean;
     executeSingle(callIn: ToolCall): Promise<ToolResult>;
-    private isReadOnlyBashCommand;
+    private resolvePolicyOperation;
+    private enforceDeclaredPathPolicy;
+    private resolvePathPolicyTargets;
     /**
      * Convert tool results into Message entries for the transcript.
      */

package/dist/tool-system/executor.js

@@ -2,10 +2,15 @@
  * Tool executor — orchestrates permission checks, hooks, and execution.
  */
 import { setMaxListeners } from "node:events";
+import { resolve as resolvePath, isAbsolute as isAbsolutePath } from "node:path";
+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";
 // A1 hardening: hooks must never promote a non-`allow` classifier
 // decision to `allow`. They may otherwise adjust the decision freely
 // (e.g. tighten `allow` to `deny`/`ask`, or relax `deny` to `ask` to
@@ -114,22 +119,77 @@ export class ToolExecutor {
                 isError: true,
             };
         }
-        // 0. Plan mode: only allow read-only tools — no file writes at all
-        if (this.toolCtx?.planMode) {
-            // Shared with engine.ts's tool-visibility filter so the set the model
-            // SEES and the set the executor RUNS can't drift (they had).
-            if (!PLAN_MODE_ALLOWED_TOOLS.has(call.toolName)) {
-                if (call.toolName === "Bash" && this.isReadOnlyBashCommand(call.args)) {
-                    // Read-only bash is fine
+        // Same gate for MCP tools: the registry is worker-shared, so it can hold
+        // tools from servers OTHER sessions enabled. Visibility filtering hides
+        // them from this session's tool list; this rejects a direct call anyway.
+        if (this.toolCtx?.allowedMcpServers) {
+            const allowed = this.toolCtx.allowedMcpServers;
+            const reg = this.registry.getTool(call.toolName);
+            if (reg?.source === "mcp" && !allowed.has(reg.serverName ?? "")) {
+                return {
+                    id: call.id,
+                    toolName: call.toolName,
+                    error: `Tool ${call.toolName} belongs to an MCP server that is not enabled for this project. 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
+            // or read a resource on a server only ANOTHER session enabled. Gate on the
+            // server arg. ListMcpResources has an optional server filter and would
+            // otherwise enumerate every connected server's resources, so we inject the
+            // allowlist for it to filter by (see mcp-tools.ts).
+            if (call.toolName === "MCPTool" || call.toolName === "ReadMcpResource") {
+                const server = String(call.args.server ?? "");
+                if (!allowed.has(server)) {
+                    return {
+                        id: call.id,
+                        toolName: call.toolName,
+                        error: `MCP server "${server}" is not enabled for this project. Do NOT retry this tool call.`,
+                        isError: true,
+                    };
                 }
-                else {
+            }
+            else if (call.toolName === "ListMcpResources") {
+                const server = String(call.args.server ?? "");
+                if (server && !allowed.has(server)) {
                     return {
                         id: call.id,
                         toolName: call.toolName,
-                        error: `Plan mode: ${call.toolName} is blocked. Only read-only tools (Read, Glob, Grep, WebSearch, WebFetch, Bash read-only) are allowed. You MUST output your plan as text in the conversation instead. Do NOT retry this tool call.`,
+                        error: `MCP server "${server}" is not enabled for this project. Do NOT retry this tool call.`,
                         isError: true,
                     };
                 }
+                call.args.__allowedMcpServers = allowed;
+            }
+        }
+        // 0. Plan mode: only allow read-only tools — no file writes at all
+        if (this.toolCtx?.planMode) {
+            // Shared with engine.ts's tool-visibility filter so the set the model
+            // SEES and the set the executor RUNS can't drift (they had).
+            // Bash is in the allow-list so the model can SEE it for read-only probing,
+            // but membership alone must NOT grant write access: a Bash command that
+            // modifies files (echo >, sed -i, mv, ...) has to be blocked here too, or it
+            // would slip past plan mode into the normal permission flow (where the user
+            // could approve it) AND leave no diff, since it never touches Write/Edit.
+            const allowed = PLAN_MODE_ALLOWED_TOOLS.has(call.toolName);
+            // Defer to the canonical shell classifier (the same one the permission
+            // flow uses) instead of a second hand-rolled allowlist that drifted and
+            // let find -delete / awk system() / process substitution / git difftool
+            // through. Plan mode is strictly read-only, so ONLY "safe-read" passes —
+            // safe-write (mkdir/touch/cp), unsafe, and dangerous are all blocked.
+            const bashWrite = call.toolName === "Bash" &&
+                classifyBashCommand(String(call.args.command ?? "")) !== "safe-read";
+            if (!allowed || bashWrite) {
+                return {
+                    id: call.id,
+                    toolName: call.toolName,
+                    error: allowed && bashWrite
+                        ? `Plan mode is read-only: this Bash command writes or modifies files, which is not allowed while planning. To carry it out, first call ExitPlanMode (after the user approves your plan), then run it. Do NOT retry this command in plan mode.`
+                        : `Plan mode: ${call.toolName} is blocked. Only read-only tools (Read, Glob, Grep, WebSearch, WebFetch, Bash read-only) are allowed. You MUST output your plan as text in the conversation instead. Do NOT retry this tool call.`,
+                    isError: true,
+                };
             }
         }
         // 0.5. Validate tool args
@@ -182,6 +242,19 @@ export class ToolExecutor {
                 toolCallId: call.id,
             });
         }
+        // 0.65. Centralized file path policy. Tool handlers declare their file
+        // 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.
+        const pathPolicyError = await this.enforceDeclaredPathPolicy(toolDef, call.args);
+        if (pathPolicyError) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: pathPolicyError,
+                isError: true,
+            };
+        }
         // A1 hardening: pre_tool_use can no longer pre-approve a tool via
         // `decision === "allow"`. Hooks may relax `allow` and may force
         // `ask`/`deny`, but they cannot promote a `deny`/`ask` decision to
@@ -321,6 +394,18 @@ export class ToolExecutor {
                 durationMs: Date.now() - toolStartedAt,
                 error: err instanceof Error ? err.stack ?? err.message : String(err),
             });
+            // A model calling a tool that isn't in the registry (hallucinated name,
+            // or a builtin missing from the active preset's whitelist) must not kill
+            // the turn. Feed it back as a normal tool error so the model can retry
+            // or pick a different tool — same path as permission denials above.
+            if (err instanceof ToolNotFoundError) {
+                return {
+                    id: call.id,
+                    toolName: call.toolName,
+                    error: `Tool not found: ${call.toolName}. It is not available in this session — do not call it again; use a different tool.`,
+                    isError: true,
+                };
+            }
             throw err;
         }
         result.id = call.id;
@@ -386,86 +471,85 @@ export class ToolExecutor {
         }
         return result;
     }
-    isReadOnlyBashCommand(args) {
-        const cmd = String(args.command ?? "").trim();
-        // Reject shell metacharacters that could chain a write command after a
-        // read-only prefix: ; && || ` $(...) redirections. A single pipe (|) is
-        // still allowed — the per-part whitelist further down validates it.
-        const DANGEROUS = /;|&&|\|\||`|\$\(|>/;
-        if (DANGEROUS.test(cmd))
-            return false;
-        // Extract the base command (first word, ignoring env vars like VAR=val)
-        const baseCmd = cmd.replace(/^(\w+=\S+\s+)*/, "").split(/\s/)[0];
-        const readOnlyCommands = new Set([
-            "ls",
-            "find",
-            "cat",
-            "head",
-            "tail",
-            "wc",
-            "file",
-            "stat",
-            "tree",
-            "du",
-            "df",
-            "pwd",
-            "echo",
-            "which",
-            "type",
-            "env",
-            "printenv",
-            "grep",
-            "rg",
-            "ag",
-            "awk",
-            "less",
-            "more",
-            "sort",
-            "uniq",
-            "diff",
-            "readlink",
-            "realpath",
-            "basename",
-            "dirname",
-            "date",
-            "whoami",
-            "uname",
-            "hostname",
-            "id",
-            "groups",
-            "locale",
-            "uptime",
-        ]);
-        // Whitelisted read-only git/tool subcommands.
-        // Deliberately exclude `node -e`, `python -c`, `sed -n`, etc. — those can
-        // execute arbitrary code even though they "look read-only".
-        const readOnlyPrefixes = [
-            "git log",
-            "git status",
-            "git diff",
-            "git branch",
-            "git show",
-            "git blame",
-            "git remote",
-            "git tag",
-            "git stash list",
-            "git rev-parse",
-            "npx tsc --noEmit",
-        ];
-        if (readOnlyCommands.has(baseCmd))
-            return true;
-        if (readOnlyPrefixes.some((p) => cmd.startsWith(p)))
-            return true;
-        // Allow piped commands if all parts are read-only. Redirections were
-        // already rejected above, so a bare `|` here is a real pipeline.
-        if (cmd.includes("|")) {
-            const parts = cmd.split("|").map((p) => p.trim());
-            return parts.every((part) => {
-                const partBase = part.replace(/^(\w+=\S+\s+)*/, "").split(/\s/)[0];
-                return readOnlyCommands.has(partBase);
-            });
+    resolvePolicyOperation(op, args) {
+        if (op === "read" || op === "write")
+            return op;
+        const raw = args[op.fromArg];
+        const value = typeof raw === "string" ? raw : String(raw ?? "");
+        if (op.readValues?.includes(value))
+            return "read";
+        if (op.writeValues?.includes(value))
+            return "write";
+        return op.default;
+    }
+    async enforceDeclaredPathPolicy(tool, args) {
+        const policies = tool?.pathPolicy;
+        if (!policies?.length)
+            return null;
+        for (const policy of policies) {
+            const targets = this.resolvePathPolicyTargets(policy, args);
+            if (typeof targets === "string")
+                return targets;
+            const operation = this.resolvePolicyOperation(policy.operation, args);
+            for (const target of targets) {
+                const blocked = await enforcePathPolicyWithApproval(target, operation, this.toolCtx);
+                if (blocked)
+                    return blocked;
+            }
+        }
+        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 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;
+        }
+        catch (err) {
+            return `Error: ${err.message}`;
         }
-        return false;
     }
     /**
      * Convert tool results into Message entries for the transcript.

package/dist/tool-system/investigation-guard.js

@@ -16,7 +16,7 @@
  *
  * Everything decays naturally on any write/Bash/AskUser tool (state reset).
  */
-const READ_ONLY_TOOLS = new Set(["Read", "Grep", "Glob", "WebFetch", "WebSearch", "ToolSearch"]);
+import { READ_ONLY_TOOLS } from "./plan-mode-allowlist.js";
 const READ_BUDGET = 3;
 const SILENT_TURN_BUDGET = 3;
 const DEDUPE_OFFSET_BUCKET = 50;