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

package/dist/tool-system/permission.js

@@ -1,7 +1,11 @@
 /**
  * Permission system — classifier + approval backend.
  */
+import { resolve as resolvePath, dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { logger as rootPermLogger } from "../logging/logger.js";
+import { READ_ONLY_TOOLS } from "./plan-mode-allowlist.js";
 export class HeadlessApprovalBackend {
     mode;
     constructor(mode) {
@@ -14,8 +18,7 @@ export class HeadlessApprovalBackend {
             case "deny-all":
                 return { approved: false, reason: "headless deny-all mode" };
             case "approve-read-only": {
-                const readOnlyTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch", "ToolSearch"];
-                if (readOnlyTools.includes(req.toolName)) {
+                if (READ_ONLY_TOOLS.has(req.toolName)) {
                     return { approved: true };
                 }
                 return { approved: false, reason: "read-only mode: write operations denied" };
@@ -103,7 +106,13 @@ export class AutoApprovalBackend {
  * the next time the user opens the project.
  */
 export class InteractiveApprovalBackend {
-    sessionRules = new Map();
+    // Session-scoped grants, keyed on the OPERATION (tool + narrowed argsPattern
+    // via buildProjectRule), NOT just the tool name. Approving `git status` for
+    // the session must not auto-allow `rm -rf /` (both are "Bash"). Allow and
+    // deny are tracked separately so a one-off deny of `curl evil` never blocks
+    // an unrelated `git status`. (TODO 5.1 会话级权限缓存.)
+    sessionAllowRules = [];
+    sessionDenyRules = [];
     promptFn = null;
     cwd = null;
     // Project rules saved during this session. Kept in-memory (not re-read from
@@ -113,6 +122,13 @@ export class InteractiveApprovalBackend {
     // the same session. We accumulate here and hand the full list to the callback.
     savedProjectRules = [];
     onProjectRules = null;
+    // Serialize prompts so a burst of parallel tool calls doesn't queue N
+    // identical cards: while one ask is outstanding, later requests wait here
+    // and RE-CHECK the session rules when their turn comes — the first
+    // "本会话一直允许" answer then silently absorbs the queued duplicates.
+    // (All callers were already serialized at the UI anyway — the renderer
+    // shows one approval card at a time.)
+    promptTurn = Promise.resolve();
     setPromptFn(fn) {
         this.promptFn = fn;
     }
@@ -140,25 +156,75 @@ export class InteractiveApprovalBackend {
         this.onProjectRules = fn;
     }
     async requestApproval(req) {
-        // Check session rules first
-        const toolRule = this.sessionRules.get(req.toolName);
-        if (toolRule === "allow")
-            return { approved: true };
-        if (toolRule === "deny")
+        // Fast path: the operation may already be covered by a session rule.
+        const cached = this.checkSessionRules(req);
+        if (cached)
+            return cached;
+        if (!this.promptFn) {
+            return { approved: false, reason: "interactive approval backend has no prompt function" };
+        }
+        // Serialize prompts and re-check rules when our turn comes (see promptTurn
+        // field doc): a burst of parallel tool calls all passes the fast path
+        // before the first decision lands; without the re-check the user had to
+        // answer one card per duplicate.
+        const prevTurn = this.promptTurn;
+        let release;
+        this.promptTurn = new Promise((r) => (release = r));
+        try {
+            await prevTurn;
+            const nowCached = this.checkSessionRules(req);
+            if (nowCached)
+                return nowCached;
+            return await this.promptAndRecord(req);
+        }
+        finally {
+            release();
+        }
+    }
+    /** Session-rule lookup — operation-scoped (see sessionAllowRules doc). Deny
+     *  wins over allow if both somehow match (conservative). Null = no rule. */
+    checkSessionRules(req) {
+        if (this.sessionDenyRules.some((r) => ruleMatches(r, req.toolName, req.args))) {
             return { approved: false };
+        }
+        if (this.sessionAllowRules.some((r) => ruleMatches(r, req.toolName, req.args))) {
+            return { approved: true };
+        }
+        return null;
+    }
+    /** The actual interactive ask + rule recording (runs inside the prompt turn). */
+    async promptAndRecord(req) {
         if (!this.promptFn) {
             return { approved: false, reason: "interactive approval backend has no prompt function" };
         }
         const result = await this.promptFn(req);
         const scope = result.scope ?? (result.always ? "session" : "once");
+        // Path narrowing only rides on an APPROVE: a path-scoped deny is confusing
+        // (deny stays tool-wide). pathScope is ignored by buildProjectRule for
+        // non-file tools / when absent.
+        const ruleOpts = result.approved
+            ? { pathScope: result.pathScope, cwd: this.cwd ?? undefined }
+            : undefined;
         if (scope === "session" && result.always) {
-            this.sessionRules.set(req.toolName, result.approved ? "allow" : "deny");
+            // Narrow to the operation (Bash → head command, file tools → path scope)
+            // so the session grant is scoped, not tool-wide. A rule with no
+            // argsPattern keeps the prior tool-granularity behavior.
+            const rule = buildProjectRule(req.toolName, req.args, ruleOpts);
+            if (rule) {
+                const target = result.approved ? this.sessionAllowRules : this.sessionDenyRules;
+                const dup = target.some((r) => r.tool === rule.tool &&
+                    JSON.stringify(r.argsPattern) === JSON.stringify(rule.argsPattern));
+                if (!dup) {
+                    // buildProjectRule always returns decision:"allow"; flip for deny.
+                    target.push(result.approved ? rule : { ...rule, decision: "deny" });
+                }
+            }
         }
         else if (scope === "project" && result.approved) {
             // Project-scope: persist a PermissionRule to settings.local.json.
             // We only persist allow rules — denies stay session-only because a
             // persisted deny is harder to recover from than a session deny.
-            const rule = buildProjectRule(req.toolName, req.args);
+            const rule = buildProjectRule(req.toolName, req.args, ruleOpts);
             if (rule && this.cwd) {
                 try {
                     persistProjectRule(this.cwd, rule);
@@ -189,20 +255,54 @@ export class InteractiveApprovalBackend {
                     console.error("Failed to persist project permission rule:", err.message);
                 }
             }
-            // Also seed session map so the rest of this REPL session benefits
-            // even if the classifier path doesn't pick the rule up immediately.
-            this.sessionRules.set(req.toolName, "allow");
+            // Also seed the session allow list (operation-scoped) so the rest of
+            // this REPL session benefits even if the classifier path doesn't pick
+            // the rule up immediately.
+            if (rule) {
+                const dup = this.sessionAllowRules.some((r) => r.tool === rule.tool &&
+                    JSON.stringify(r.argsPattern) === JSON.stringify(rule.argsPattern));
+                if (!dup)
+                    this.sessionAllowRules.push(rule);
+            }
         }
         return result;
     }
 }
+/** File tools whose approvals can be narrowed to a path prefix. */
+const PATH_SCOPED_TOOLS = new Set(["Write", "Edit"]);
+/**
+ * Build the `file_path` argsPattern that narrows a remembered file-tool grant
+ * to a path scope. Pure: takes an ALREADY-RESOLVED absolute path (the caller
+ * normalizes against cwd so `../` can't slip past the prefix) and the scope.
+ *
+ *   "file" → `^<esc(abs)>$`         only this exact file
+ *   "dir"  → `^<esc(dir(abs))>/`    this file's directory + subdirectories
+ *   "tool" → null                   no narrowing (tool-wide; legacy behavior)
+ *
+ * The dir form keeps a trailing slash so `/repo/src/` can't match a sibling
+ * like `/repo/src-secret/x.ts`. Regex metacharacters in the path are escaped.
+ */
+export function pathRuleArgsPattern(absPath, scope) {
+    if (scope === "tool")
+        return null;
+    if (scope === "file")
+        return { file_path: `^${escapeRegex(absPath)}$` };
+    // dir: strip the basename, ensure a single trailing slash, anchor as prefix.
+    const slash = absPath.lastIndexOf("/");
+    const dir = slash > 0 ? absPath.slice(0, slash) : absPath;
+    return { file_path: `^${escapeRegex(dir + "/")}` };
+}
 /**
  * Build a PermissionRule from a single approval. Bash narrows to the head
  * command (first whitespace token) so "git status" → allow all `git ...`.
- * Other tools currently allow at tool granularity — file-level whitelists
- * could be added later by extending argsPattern.
+ *
+ * File tools (Write/Edit) narrow to a PATH scope when `opts.pathScope` is
+ * "file"/"dir": "allow Write src/foo.ts for this session" then means exactly
+ * that file (or its directory), NOT every path. Without a pathScope (or
+ * "tool"), they keep the legacy tool-wide grant. Paths are resolved against
+ * `opts.cwd` first so `../` can't widen the prefix. Other tools stay tool-wide.
  */
-function buildProjectRule(toolName, args) {
+function buildProjectRule(toolName, args, opts) {
     if (toolName === "Bash") {
         const cmd = String(args.command ?? "").trim();
         const head = cmd.split(/\s+/)[0];
@@ -215,6 +315,23 @@ function buildProjectRule(toolName, args) {
             reason: `Allowed via permission prompt: ${head}`,
         };
     }
+    if (PATH_SCOPED_TOOLS.has(toolName) && opts?.pathScope && opts.pathScope !== "tool") {
+        const raw = String(args.file_path ?? "");
+        if (raw) {
+            // Resolve against cwd so a relative or `../`-laden path becomes the real
+            // absolute path the prefix anchors to.
+            const abs = resolvePath(opts.cwd ?? process.cwd(), raw);
+            const argsPattern = pathRuleArgsPattern(abs, opts.pathScope);
+            if (argsPattern) {
+                return {
+                    tool: toolName,
+                    argsPattern,
+                    decision: "allow",
+                    reason: `Allowed via permission prompt: ${toolName} ${opts.pathScope === "dir" ? dirname(abs) + "/" : abs}`,
+                };
+            }
+        }
+    }
     return {
         tool: toolName,
         decision: "allow",
@@ -224,6 +341,66 @@ function buildProjectRule(toolName, args) {
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/**
+ * Does `rule` match this tool call? Shared by the {@link PermissionClassifier}
+ * (project/user rules) and {@link InteractiveApprovalBackend}'s session cache
+ * so the two never diverge on what "the same operation" means. Handles the
+ * JSON round-trip where a persisted RegExp comes back as a string.
+ */
+export function ruleMatches(rule, toolName, args) {
+    if (rule.tool !== toolName && rule.tool !== "*")
+        return false;
+    if (!rule.argsPattern)
+        return true;
+    // A Bash allow-rule is narrowed to a HEAD command (e.g. `^git(\s|$)`), but a
+    // raw regex test would let a chained command smuggle a dangerous tail past a
+    // grant for its head: `git status && rm -rf /` starts with `git `, so the
+    // grant for `git status` would otherwise auto-allow the whole thing. A
+    // head-narrowed grant must only cover a SINGLE, non-dangerous command — if the
+    // candidate chains (`&&`/`||`/`;`), pipes (`| sh`), or uses substitution/
+    // redirection, refuse the match so it re-prompts. (We only gate narrowed Bash
+    // grants; a tool-wide `*`/no-pattern rule, or an explicit user `argsPattern`,
+    // is the user's own choice and untouched.)
+    if (toolName === "Bash" && rule.tool === "Bash" && rule.argsPattern.command) {
+        const cmd = String(args.command ?? "");
+        const scan = scanShellCommand(cmd);
+        // scanShellCommand flags `;`/`&&`/`||`/substitution/redirection (multi-segment
+        // or dangerous), but a single pipe stays IN-segment (it's per-segment data
+        // flow, not a statement boundary) — so `git log | sh` is one non-dangerous
+        // segment. A head grant must not cover a pipe either: reject any segment
+        // carrying an (unquoted-enough) pipe so pipe-to-shell can't ride the grant.
+        if (scan.dangerous || scan.segments.length > 1 || scan.segments.some((s) => s.includes("|"))) {
+            return false;
+        }
+    }
+    for (const [key, pattern] of Object.entries(rule.argsPattern)) {
+        const argVal = String(args[key] ?? "");
+        if (pattern instanceof RegExp) {
+            if (!pattern.test(argVal))
+                return false;
+        }
+        else if (typeof pattern === "string") {
+            const looksLikeRegex = /[\\^$.*+?()[\]|{}]/.test(pattern);
+            if (looksLikeRegex) {
+                let re;
+                try {
+                    re = new RegExp(pattern);
+                }
+                catch {
+                    if (!argVal.includes(pattern))
+                        return false;
+                    continue;
+                }
+                if (!re.test(argVal))
+                    return false;
+            }
+            else if (!argVal.includes(pattern)) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
 /**
  * Append a rule to <cwd>/.code-shell/settings.local.json. Local file because
  * permission grants are per-developer and shouldn't be checked into git.
@@ -232,16 +409,17 @@ function escapeRegex(s) {
 function persistProjectRule(cwd, rule) {
     const dir = `${cwd}/.code-shell`;
     const file = `${dir}/settings.local.json`;
-    // Lazy node imports — keep permission.ts free of fs at module load time
-    // so it can be used in non-Node contexts (tests, browsers via shim).
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const fs = require("node:fs");
-    if (!fs.existsSync(dir))
-        fs.mkdirSync(dir, { recursive: true });
+    // Don't resurrect a deleted project root: a recursive mkdir of
+    // <cwd>/.code-shell recreates `cwd` itself as an empty shell when cwd is gone.
+    // Persistence here is best-effort, so skip when the root is missing.
+    if (!existsSync(cwd))
+        return;
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
     let settings = {};
-    if (fs.existsSync(file)) {
+    if (existsSync(file)) {
         try {
-            settings = JSON.parse(fs.readFileSync(file, "utf-8"));
+            settings = JSON.parse(readFileSync(file, "utf-8"));
         }
         catch {
             /* start fresh on parse error */
@@ -260,9 +438,11 @@ function persistProjectRule(cwd, rule) {
     settings.permissions.rules.push(rule);
     // Atomic write: stage to .tmp, then rename, so a crash mid-write can't
     // truncate settings.local.json and lose every saved permission grant.
-    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", "utf-8");
-    fs.renameSync(tmp, file);
+    // randomUUID() (not pid+Date.now()) guards against temp-name collisions when
+    // two writers fire within the same millisecond.
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    renameSync(tmp, file);
 }
 // Singleton interactive backend for use by the UI
 let _interactiveBackend = null;
@@ -300,9 +480,16 @@ const DANGEROUS_PATTERNS = [
 ];
 const SAFE_READ_PATTERNS = [
     /^(cat|head|tail|less|more|wc|file|stat|du|df)\s/,
-    /^(ls|tree|find|locate|which|whereis|type)\s/,
+    /^(ls|tree|locate|which|whereis|type)\s/,
+    // `find` is read-only ONLY without an action that executes or mutates:
+    // -delete, -exec/-execdir/-ok/-okdir run commands; -fprint/-fprintf/-fls
+    // write files. Reject those so `find . -delete` / `find . -exec rm {} +`
+    // are NOT classified safe-read. Plain predicates (-name, -type, -print) stay.
+    /^find\s(?!.*\s-(delete|exec(dir)?|ok(dir)?|fprintf?|fls)\b)/,
     /^(grep|rg|ag|ack|fgrep|egrep)\s/,
-    /^(git\s+(status|log|diff|branch|show|blame|remote|tag|stash\s+list|rev-parse|describe))/,
+    // Word-boundary the git read subcommands so `git difftool -x <cmd>` (which
+    // runs an arbitrary external command) does NOT match on the `diff` branch.
+    /^(git\s+(status|log|diff|branch|show|blame|remote|tag|stash\s+list|rev-parse|describe))\b/,
     /^(node|python|ruby|go|rustc|java|javac)\s+--version/,
     /^(npm|pnpm|yarn|cargo|pip|gem|brew)\s+(list|ls|info|show|view|outdated|audit)/,
     /^pwd$/,
@@ -313,6 +500,46 @@ const SAFE_READ_PATTERNS = [
     /^env$/,
     /^printenv/,
 ];
+// ─── Sensitive safe-read downgrade ────────────────────────────────
+//
+// `Read ~/.ssh/id_rsa` routes through path-policy (asks); the equivalent
+// `cat ~/.ssh/id_rsa` was YOLO-classified safe-read and auto-allowed with the
+// desktop's default sandbox=off — a zero-approval credential exfil channel.
+// A segment that would otherwise be safe-read is downgraded to `unsafe` (→
+// ask) when it dumps the process env or its arguments touch a sensitive path.
+// Conservative-and-narrow: only known credential/secret shapes trip it, so
+// ordinary reads (README.md, src/*.ts) stay safe-read.
+// Whole-command env dumps that leak Credential.exposeAsEnv / top-level `env`
+// API keys. `env FOO=bar cmd` (env used as a launcher) is intentionally NOT
+// matched — only a bare dump.
+const ENV_DUMP_RE = /^(env|printenv)(\s+[A-Za-z_][A-Za-z0-9_]*)*\s*$/;
+const SENSITIVE_PATH_PATTERNS = [
+    /\.ssh\//, // ~/.ssh/id_rsa, authorized_keys, known_hosts
+    /(^|\/)id_(rsa|dsa|ecdsa|ed25519)\b/,
+    /(^|\/|\s)\.env(\.[A-Za-z0-9]|\b)/, // .env, .env.local, .env.production
+    /\.aws\/credentials\b/,
+    /\.code-shell\/credentials\b/,
+    /credentials\.json\b/,
+    /\.npmrc\b/,
+    /\.netrc\b/,
+    /\.pgpass\b/,
+    /\.docker\/config\.json\b/,
+    /\.kube\/config\b/,
+    /\.config\/gh\/hosts\b/,
+    /\.gnupg\//,
+    /(^|\/)\.git-credentials\b/,
+];
+/**
+ * True when an otherwise-safe-read shell segment must be downgraded to `unsafe`
+ * because it dumps the environment or reads a sensitive credential/secret path.
+ * Exported for direct unit testing of the predicate.
+ */
+export function segmentIsSensitiveRead(segment) {
+    const s = segment.trim();
+    if (ENV_DUMP_RE.test(s))
+        return true;
+    return SENSITIVE_PATH_PATTERNS.some((re) => re.test(s));
+}
 const SAFE_WRITE_PATTERNS = [
     /^(git\s+(add|commit|stash\s+(save|push)))/,
     /^mkdir\s/,
@@ -433,6 +660,12 @@ function scanShellCommand(input) {
         i++;
     }
     flush();
+    // An unclosed quote means we stopped recognizing separators/metacharacters
+    // partway through (pipes, `;`, redirection inside the dangling quote were
+    // swallowed). Treat malformed shell syntax as dangerous rather than risk
+    // misclassifying it as safe.
+    if (quote !== null)
+        dangerous = true;
     return { segments, dangerous };
 }
 function classifySegment(segment) {
@@ -454,12 +687,17 @@ function classifySegment(segment) {
         const parts = segment.split("|").map((p) => p.trim());
         const partIsSafeRead = (p) => SAFE_READ_PATTERNS.some((re) => re.test(p) || re.test(`${p} `));
         if (parts.every(partIsSafeRead)) {
+            // A sensitive read anywhere in the pipe (`cat ~/.ssh/id_rsa | base64`,
+            // `env | grep KEY`) downgrades the whole pipe.
+            if (parts.some(segmentIsSensitiveRead))
+                return "unsafe";
             return "safe-read";
         }
         return "unsafe";
     }
-    if (SAFE_READ_PATTERNS.some((p) => p.test(segment)))
-        return "safe-read";
+    if (SAFE_READ_PATTERNS.some((p) => p.test(segment))) {
+        return segmentIsSensitiveRead(segment) ? "unsafe" : "safe-read";
+    }
     if (SAFE_WRITE_PATTERNS.some((p) => p.test(segment)))
         return "safe-write";
     return "unsafe";
@@ -696,43 +934,10 @@ export class PermissionClassifier {
         return undefined;
     }
     matchesRule(rule, toolName, args) {
-        if (rule.tool !== toolName && rule.tool !== "*")
-            return false;
-        if (rule.argsPattern) {
-            for (const [key, pattern] of Object.entries(rule.argsPattern)) {
-                const argVal = String(args[key] ?? "");
-                if (pattern instanceof RegExp) {
-                    if (!pattern.test(argVal))
-                        return false;
-                }
-                else if (typeof pattern === "string") {
-                    // Rules persisted in settings.local.json lose their RegExp type
-                    // through JSON round-trip — they come back as strings. buildProjectRule
-                    // produces regex sources like `^cd(\\s|$)`; treat any string with
-                    // regex metacharacters as a pattern and only fall back to substring
-                    // match for plain literals (kept for backward compat with hand-edited
-                    // settings files that used plain substrings).
-                    const looksLikeRegex = /[\\^$.*+?()[\]|{}]/.test(pattern);
-                    if (looksLikeRegex) {
-                        let re;
-                        try {
-                            re = new RegExp(pattern);
-                        }
-                        catch {
-                            if (!argVal.includes(pattern))
-                                return false;
-                            continue;
-                        }
-                        if (!re.test(argVal))
-                            return false;
-                    }
-                    else if (!argVal.includes(pattern)) {
-                        return false;
-                    }
-                }
-            }
-        }
-        return true;
+        // Delegate to the shared matcher so the classifier and the session cache
+        // agree on rule semantics (the JSON-string-vs-RegExp handling, the head-
+        // command narrowing for Bash, etc.).
+        return ruleMatches(rule, toolName, args);
     }
     isDangerousCommand(args) {
         const command = String(args.command ?? "");
@@ -745,7 +950,14 @@ export class PermissionClassifier {
             return "medium";
         if (toolName === "Bash")
             return "medium";
-        return "low";
+        // Only genuinely read-only built-ins are "low" (the sole tier
+        // AutoApprovalBackend approves with no delegate). Everything else —
+        // crucially every MCP tool, which can delete records, send messages, or
+        // deploy — defaults to "medium" so auto mode delegates it (UI prompt) or
+        // fails closed, instead of blind-approving an unknown side-effecting tool.
+        if (READ_ONLY_TOOLS.has(toolName))
+            return "low";
+        return "medium";
     }
     /**
      * Short, human-friendly subtitle. The UI shows this under the tool title;

package/dist/tool-system/plan-mode-allowlist.d.ts

@@ -15,7 +15,18 @@
  * Membership policy: read-only tools, planning/agent tools, and
  * non-destructive task-tracking tools. Bash is included so the model sees it;
  * the executor additionally gates Bash to read-only commands at call time
- * (see executor.isReadOnlyBashCommand). Write/Edit/ApplyPatch/NotebookEdit and
- * other mutating tools are intentionally excluded.
+ * (executor defers to classifyBashCommand, admitting only "safe-read").
+ * Write/Edit/ApplyPatch/NotebookEdit and other mutating tools are
+ * intentionally excluded.
  */
+/**
+ * The built-in tools that only READ — no file writes, no side effects, no
+ * network mutations. Single source of truth shared by:
+ *   - investigation-guard.ts (which tools count as "just looking")
+ *   - permission.ts HeadlessApprovalBackend (approve-read-only mode)
+ *   - permission.ts assessRisk (these are genuinely low-risk; everything else,
+ *     including MCP tools, is at least medium so it isn't auto-approved blind)
+ * These three lists were independent byte-for-byte copies that could drift.
+ */
+export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
 export declare const PLAN_MODE_ALLOWED_TOOLS: ReadonlySet<string>;

package/dist/tool-system/plan-mode-allowlist.js

@@ -15,9 +15,27 @@
  * Membership policy: read-only tools, planning/agent tools, and
  * non-destructive task-tracking tools. Bash is included so the model sees it;
  * the executor additionally gates Bash to read-only commands at call time
- * (see executor.isReadOnlyBashCommand). Write/Edit/ApplyPatch/NotebookEdit and
- * other mutating tools are intentionally excluded.
+ * (executor defers to classifyBashCommand, admitting only "safe-read").
+ * Write/Edit/ApplyPatch/NotebookEdit and other mutating tools are
+ * intentionally excluded.
  */
+/**
+ * The built-in tools that only READ — no file writes, no side effects, no
+ * network mutations. Single source of truth shared by:
+ *   - investigation-guard.ts (which tools count as "just looking")
+ *   - permission.ts HeadlessApprovalBackend (approve-read-only mode)
+ *   - permission.ts assessRisk (these are genuinely low-risk; everything else,
+ *     including MCP tools, is at least medium so it isn't auto-approved blind)
+ * These three lists were independent byte-for-byte copies that could drift.
+ */
+export const READ_ONLY_TOOLS = new Set([
+    "Read",
+    "Glob",
+    "Grep",
+    "WebSearch",
+    "WebFetch",
+    "ToolSearch",
+]);
 export const PLAN_MODE_ALLOWED_TOOLS = new Set([
     // Plan lifecycle
     "EnterPlanMode",
@@ -32,6 +50,10 @@ export const PLAN_MODE_ALLOWED_TOOLS = new Set([
     "AskUserQuestion",
     "Agent",
     "ToolSearch",
+    // Skill: loads a skill's guidance text into context — read-only, no file
+    // writes. Planning is exactly when methodology skills (brainstorming,
+    // writing-plans, …) are most useful, so it belongs in the allow-list.
+    "Skill",
     // Task tracking (non-destructive) — both the TodoWrite and the Task* family
     "TodoWrite",
     "TaskCreate",

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

@@ -19,6 +19,7 @@ export declare class ToolRegistry {
     constructor(options?: ToolRegistryOptions);
     private registerBuiltins;
     registerTool(tool: RegisteredTool, executor?: BuiltinToolFn): void;
+    unregisterTool(name: string): void;
     getToolDefinitions(): ToolDefinition[];
     getTool(name: string): RegisteredTool | undefined;
     hasTool(name: string): boolean;

package/dist/tool-system/registry.js

@@ -3,6 +3,7 @@
  */
 import { ConfigError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError } from "../exceptions.js";
 import { BUILTIN_TOOLS } from "./builtin/index.js";
+import { validateToolMetadata } from "./validate-tool-metadata.js";
 /**
  * Default execution timeout for any tool that does not declare its own
  * timeoutMs at registration time. Tools that need to run longer (Agent,
@@ -28,16 +29,24 @@ export class ToolRegistry {
             if (selectedNames && !selectedNames.has(tool.definition.name)) {
                 continue;
             }
+            // Fail loud on pathPolicy.arg drift rather than silently disabling path
+            // protection (assessment §4.1).
+            validateToolMetadata(tool.definition);
             this.tools.set(tool.definition.name, tool.definition);
             this.builtinExecutors.set(tool.definition.name, tool.execute);
         }
     }
     registerTool(tool, executor) {
+        validateToolMetadata(tool);
         this.tools.set(tool.name, tool);
         if (executor) {
             this.builtinExecutors.set(tool.name, executor);
         }
     }
+    unregisterTool(name) {
+        this.tools.delete(name);
+        this.builtinExecutors.delete(name);
+    }
     getToolDefinitions() {
         return [...this.tools.values()].map((t) => ({
             name: t.name,
@@ -107,11 +116,16 @@ export class ToolRegistry {
             if (typeof result === "string") {
                 return { id, toolName: name, result };
             }
+            // 结构化返回:图片块(view_image)或沙箱标记(Bash 等)。两者互斥,
+            // 各取所有,缺的字段为 undefined。
+            const contentBlocks = "contentBlocks" in result ? result.contentBlocks : undefined;
+            const sandbox = "sandbox" in result ? result.sandbox : undefined;
             return {
                 id,
                 toolName: name,
-                result: result.result ?? "(image)",
-                contentBlocks: result.contentBlocks,
+                result: result.result ?? (contentBlocks ? "(image)" : ""),
+                contentBlocks,
+                sandbox,
             };
         }
         catch (err) {

package/dist/tool-system/sandbox/index.d.ts

@@ -27,6 +27,14 @@ export interface SandboxConfig {
 export interface SandboxBackend {
     /** Resolved backend name — "off" means no sandboxing. */
     name: "off" | "seatbelt" | "bwrap";
+    /**
+     * Network policy that applied for this run. Not part of the backend's
+     * isolation mechanism — the Engine stamps it onto the resolved backend
+     * (it owns the resolved SandboxConfig) so tools can surface "网络 deny"
+     * on their result without threading the whole config through ToolContext.
+     * Absent on "off" (no policy enforced).
+     */
+    network?: SandboxNetworkPolicy;
     /**
      * Decide the binary + argv that should actually be spawned to run `command`
      * under this sandbox. The shell still interprets `command`; we only swap

package/dist/tool-system/sandbox/index.js

@@ -17,7 +17,7 @@
  * when no sandbox is available.
  */
 import { accessSync, constants, realpathSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { SandboxUnavailableError } from "../../exceptions.js";
 /**
  * Detect which sandbox mechanisms are available on the current host. Used by
@@ -111,9 +111,14 @@ function warnAutoDowngrade() {
         `Set sandbox.mode=off in settings.json to silence, or CODE_SHELL_SANDBOX_QUIET=1.\n`);
 }
 export function defaultSandboxConfig(mode = "auto") {
+    // Temp roots are writable so tool-result spillover / scratch files land
+    // somewhere. POSIX: the canonical /tmp family. Windows has no OS sandbox
+    // backend (auto → off), so writableRoots is effectively unused there, but
+    // keep it host-correct by using the platform temp dir instead of /tmp.
+    const tmpRoots = process.platform === "win32" ? [tmpdir()] : ["/tmp", "/private/tmp", "/var/tmp"];
     return {
         mode,
-        writableRoots: ["${workspace}", "/tmp", "/private/tmp", "/var/tmp"],
+        writableRoots: ["${workspace}", ...tmpRoots],
         deniedReads: [
             "~/.ssh",
             "~/.aws",