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

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

@@ -0,0 +1,65 @@
+/**
+ * Single source of truth for which tools are permitted in plan mode.
+ *
+ * Two call sites consume this:
+ *   - engine.ts: filters the tool DEFINITIONS shown to the model, so the
+ *     model only sees tools it's allowed to use while planning.
+ *   - executor.ts: gates tool EXECUTION, refusing anything outside the set.
+ *
+ * These two lists used to be maintained separately and drifted (engine had
+ * the Task family + Bash but not TodoWrite; executor had TodoWrite but not the
+ * Task family), so the model could be shown a tool the executor would then
+ * block, or vice-versa. Keep them identical by importing this constant in
+ * both places.
+ *
+ * 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
+ * (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",
+    "ExitPlanMode",
+    // Read-only investigation
+    "Read",
+    "Glob",
+    "Grep",
+    "WebSearch",
+    "WebFetch",
+    // Agent / interaction / discovery
+    "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",
+    "TaskUpdate",
+    "TaskList",
+    "TaskGet",
+    // Bash: visible to the model; executor gates it to read-only commands.
+    "Bash",
+]);

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,
@@ -101,7 +110,23 @@ export class ToolRegistry {
             ]);
             clearTimeout(timerId);
             parentSignal?.removeEventListener("abort", onParentAbort);
-            return { id, toolName: name, result };
+            // executor 可返回纯字符串,或 { contentBlocks, result? }(view_image
+            // 用后者回传图片块)。归一化成 ToolResult:有 contentBlocks 就带上,
+            // result 始终保留一份文本镜像供 transcript / 摘要使用。
+            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 ?? (contentBlocks ? "(image)" : ""),
+                contentBlocks,
+                sandbox,
+            };
         }
         catch (err) {
             clearTimeout(timerId);

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",

package/dist/tool-system/validate-tool-metadata.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Registration-time guard for tool path-policy metadata.
+ *
+ * A tool's `pathPolicy[].arg` names the input field that carries a file path
+ * (or, for apply_patch, the patch text). ToolExecutor reads `args[policy.arg]`
+ * to find the targets it must run through the path-permission layer. If that
+ * arg name is a typo (e.g. `"pat"` instead of `"path"`), the lookup yields
+ * `undefined`, the executor finds zero targets, and the tool runs with NO path
+ * protection and no error — a silent security failure (assessment §4.1).
+ *
+ * This validator catches that drift at registration time by asserting every
+ * declared `pathPolicy.arg` exists in the tool's `inputSchema.properties`.
+ */
+import type { RegisteredTool, ToolDefinition } from "../types.js";
+/** A tool-shaped object carrying the fields this validator inspects. */
+type ToolLike = Pick<RegisteredTool, "name" | "inputSchema"> & Partial<Pick<RegisteredTool, "pathPolicy">>;
+export interface ToolMetadataIssue {
+    tool: string;
+    arg: string;
+    reason: string;
+}
+/**
+ * Check a single tool's path-policy metadata against its schema. Returns one
+ * issue per `pathPolicy.arg` that is not a declared input property. Tools
+ * without a pathPolicy produce no issues.
+ */
+export declare function findToolMetadataIssues(tool: ToolLike): ToolMetadataIssue[];
+/**
+ * Assert a tool's path-policy metadata is consistent with its schema. Throws on
+ * the first drift. Call at registration time so a typo fails loud instead of
+ * silently disabling path protection.
+ */
+export declare function validateToolMetadata(tool: ToolLike): void;
+/** Validate a batch; returns every issue across all tools (does not throw). */
+export declare function collectToolMetadataIssues(tools: ReadonlyArray<ToolLike | ToolDefinition>): ToolMetadataIssue[];
+export {};

package/dist/tool-system/validate-tool-metadata.js

@@ -0,0 +1,63 @@
+/**
+ * Registration-time guard for tool path-policy metadata.
+ *
+ * A tool's `pathPolicy[].arg` names the input field that carries a file path
+ * (or, for apply_patch, the patch text). ToolExecutor reads `args[policy.arg]`
+ * to find the targets it must run through the path-permission layer. If that
+ * arg name is a typo (e.g. `"pat"` instead of `"path"`), the lookup yields
+ * `undefined`, the executor finds zero targets, and the tool runs with NO path
+ * protection and no error — a silent security failure (assessment §4.1).
+ *
+ * This validator catches that drift at registration time by asserting every
+ * declared `pathPolicy.arg` exists in the tool's `inputSchema.properties`.
+ */
+/**
+ * Return the set of property names declared in a JSON-schema-ish object's
+ * `properties`. Tolerant of missing/malformed schema (returns empty set), so a
+ * tool with no declared properties is treated as "declares nothing" rather
+ * than throwing — the caller decides how to react.
+ */
+function schemaPropertyNames(inputSchema) {
+    const props = inputSchema?.properties;
+    if (!props || typeof props !== "object")
+        return new Set();
+    return new Set(Object.keys(props));
+}
+/**
+ * Check a single tool's path-policy metadata against its schema. Returns one
+ * issue per `pathPolicy.arg` that is not a declared input property. Tools
+ * without a pathPolicy produce no issues.
+ */
+export function findToolMetadataIssues(tool) {
+    const policies = tool.pathPolicy;
+    if (!policies || policies.length === 0)
+        return [];
+    const declared = schemaPropertyNames(tool.inputSchema);
+    const issues = [];
+    for (const policy of policies) {
+        if (!declared.has(policy.arg)) {
+            issues.push({
+                tool: tool.name,
+                arg: policy.arg,
+                reason: `pathPolicy.arg "${policy.arg}" is not a property of inputSchema (path-permission enforcement would silently no-op)`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Assert a tool's path-policy metadata is consistent with its schema. Throws on
+ * the first drift. Call at registration time so a typo fails loud instead of
+ * silently disabling path protection.
+ */
+export function validateToolMetadata(tool) {
+    const issues = findToolMetadataIssues(tool);
+    if (issues.length > 0) {
+        const first = issues[0];
+        throw new Error(`Invalid tool metadata for "${first.tool}": ${first.reason}`);
+    }
+}
+/** Validate a batch; returns every issue across all tools (does not throw). */
+export function collectToolMetadataIssues(tools) {
+    return tools.flatMap((t) => findToolMetadataIssues(t));
+}

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

@@ -1,3 +1,13 @@
+/**
+ * Lightweight tool input validation against a JSON Schema.
+ *
+ * NOT a full JSON-Schema validator: it only checks `required` presence and
+ * top-level primitive types (string/number/boolean). Arrays, objects, enums,
+ * nested shapes, and formats are intentionally NOT validated — this is a
+ * cheap pre-flight guard, not a substitute for the provider's own schema
+ * enforcement. (Was previously labelled "Zod-based" and imported `z`, but
+ * never used zod — corrected to avoid misleading readers.)
+ */
 /**
  * Validate tool args against the tool's inputSchema.
  * Returns null if valid, error string if invalid.

package/dist/tool-system/validation.js

@@ -1,3 +1,13 @@
+/**
+ * Lightweight tool input validation against a JSON Schema.
+ *
+ * NOT a full JSON-Schema validator: it only checks `required` presence and
+ * top-level primitive types (string/number/boolean). Arrays, objects, enums,
+ * nested shapes, and formats are intentionally NOT validated — this is a
+ * cheap pre-flight guard, not a substitute for the provider's own schema
+ * enforcement. (Was previously labelled "Zod-based" and imported `z`, but
+ * never used zod — corrected to avoid misleading readers.)
+ */
 /**
  * Validate tool args against the tool's inputSchema.
  * Returns null if valid, error string if invalid.
@@ -6,14 +16,17 @@ export function validateToolArgs(toolName, args, schema) {
     try {
         const properties = schema.properties;
         const required = schema.required ?? [];
-        if (!properties)
-            return null;
-        // Check required fields
+        // Required-field presence does not depend on `properties` existing — a
+        // schema may declare `required` with no `properties` block (e.g. a
+        // malformed external MCP tool schema). Check it before the properties
+        // guard so missing params are still caught.
         for (const field of required) {
             if (args[field] === undefined || args[field] === null) {
                 return `Missing required parameter: ${field}`;
             }
         }
+        if (!properties)
+            return null; // No property shapes to type-check.
         // Type check each provided field
         for (const [key, value] of Object.entries(args)) {
             const propSchema = properties[key];