@jerryan/pi-subagent-tools 0.3.0 → 0.4.0

package/sandbox-bash.ts

@@ -1,148 +1,312 @@
-/**
- * Sandboxed read-only bash for review/explore child sessions.
- *
- * One tool replaces the former read/grep/find/ls allowlist plus the git
- * tool's policy table: a just-bash interpreter over a composed filesystem
- * (see createSandboxFs), with just-git providing git inside the sandbox.
- * Read-only is enforced at the capability layer — see DESIGN.md.
- *
- * The `disabled` git list below is UX only (clean "not available" errors
- * for pure mutators); enforcement is the read-only filesystem. Dual-purpose
- * verbs (branch, tag, stash, config, remote, worktree) stay enabled so
- * their read modes work; their write modes fail at the filesystem.
- *
- * Each call runs in a freshly constructed interpreter: per-call
- * construction is the statelessness guarantee, and it avoids any
- * shared-state questions between parallel children.
- */
-
-import * as path from "node:path";
-import { Type } from "@sinclair/typebox";
-import { defineTool } from "@earendil-works/pi-coding-agent";
-import { Bash, InMemoryFs, MountableFs, OverlayFs, type ExecResult } from "just-bash";
-import { createGit, type GitCommandName } from "just-git";
-
-/** Pure-mutator git verbs, disabled for clean UX errors. FS enforces the rest. */
-const DISABLED_GIT: GitCommandName[] = [
-  "init",
-  "add",
-  "commit",
-  "checkout",
-  "switch",
-  "restore",
-  "reset",
-  "merge",
-  "cherry-pick",
-  "revert",
-  "rebase",
-  "mv",
-  "rm",
-  "clean",
-  "bisect",
-  "gc",
-  "repack",
-];
-
-/** Mount point of the project root inside the sandbox. */
-const MOUNT_POINT = "/repo";
-
-/**
- * Compose the sandbox filesystem: the project root mounted read-only at
- * /repo over a writable in-memory base. The base provides working /dev/null
- * (stderr silencing is a core shell idiom; on a real read-only mount the
- * device still works) and per-call in-memory scratch (/tmp, ...) that
- * evaporates with the interpreter. Note MountableFs strips the mount
- * prefix before delegating, so the inner OverlayFs mounts at "/".
- */
-function createSandboxFs(projectRoot: string): MountableFs {
-  const fs = new MountableFs({ base: new InMemoryFs() });
-  fs.mount(
-    MOUNT_POINT,
-    new OverlayFs({ root: projectRoot, mountPoint: "/", readOnly: true }),
-  );
-  return fs;
-}
-
-const MAX_OUTPUT_CHARS = 50_000;
-const MAX_OUTPUT_LINES = 2_000;
-
-/**
- * Filesystem-style error codes the sandbox can raise. just-bash reports
- * command-level failures (touch, rm) as exit codes, but interpreter-level
- * failures — output redirections write through the interpreter's own FS
- * path — REJECT the exec promise with these. Both shapes mean the same
- * thing to the caller: the command failed. Anything outside this taxonomy
- * is a genuine interpreter bug and is rethrown, loudly.
- */
-const FS_ERROR_PATTERN =
-  /^(EROFS|EACCES|EPERM|ENOENT|EFBIG|ENOSPC|EISDIR|ENOTDIR|ELOOP|ENOTEMPTY|EEXIST|EINVAL|EBUSY|EXDEV|EIO)\b/;
-
-function truncateOutput(output: string): string {
-  const lines = output.split("\n");
-  if (lines.length <= MAX_OUTPUT_LINES && output.length <= MAX_OUTPUT_CHARS) {
-    return output;
-  }
-  const kept = lines.slice(0, MAX_OUTPUT_LINES).join("\n").slice(0, MAX_OUTPUT_CHARS);
-  const keptLines = kept.split("\n").length;
-  return `${kept}\n\n[output truncated: showing ${keptLines} lines, ${kept.length} chars]`;
-}
-
-export const sandboxBashTool = defineTool({
-  name: "bash",
-  label: "bash (read-only)",
-  description:
-    "Run a command in a sandboxed, read-only bash environment. " +
-    "The working directory is the project root (mounted at /repo); use relative paths with forward slashes. " +
-    "Standard utilities are available (grep, find, sed, awk, head, tail, sort, uniq, wc, cat, ls, ...) " +
-    "plus git for repository inspection (log, diff, show, blame, grep, ls-files, branch/tag listing; " +
-    "note: git status is slow in large repos — prefer the targeted commands). " +
-    "The environment has no network access and the project directory is read-only by design: all writes to it fail. " +
-    "Paths outside /repo (like /tmp) are in-memory scratch, discarded after each call. " +
-    "Each call runs in a fresh shell — cd and environment variables do not persist between calls; " +
-    "use compound commands (cd dir && command) for multi-step work.",
-  promptSnippet: "Run a command in the read-only sandboxed shell",
-  promptGuidelines: [
-    "Use bash for searching, file inspection, and git history — never attempt to modify files; all writes fail by design.",
-  ],
-  parameters: Type.Object({
-    command: Type.String({
-      description:
-        "The command line to execute (e.g. 'grep -rn \"pattern\" src/', 'git log --oneline -10', 'find . -name \"*.ts\" | head').",
-    }),
-  }),
-  async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-    const bash = new Bash({
-      fs: createSandboxFs(path.resolve(ctx.cwd)),
-      cwd: MOUNT_POINT,
-      customCommands: [createGit({ network: false, disabled: DISABLED_GIT })],
-    });
-    const result = await execSafely(bash, params.command, signal);
-    const stdout = result.stdout;
-    const stderr = result.stderr;
-    const combined =
-      stdout && stderr ? `${stdout}\n${stderr}` : stdout || stderr || "(no output)";
-    const text =
-      result.exitCode === 0
-        ? truncateOutput(combined)
-        : `Exit code ${result.exitCode}\n${truncateOutput(combined)}`;
-    return {
-      content: [{ type: "text" as const, text }],
-      details: { exitCode: result.exitCode },
-    };
-  },
-});
-
-async function execSafely(
-  bash: Bash,
-  command: string,
-  signal?: AbortSignal,
-): Promise<ExecResult> {
-  try {
-    return await bash.exec(command, { signal });
-  } catch (err: any) {
-    if (FS_ERROR_PATTERN.test(err?.message ?? "")) {
-      return { stdout: "", stderr: err.message, exitCode: 1 };
-    }
-    throw err;
-  }
-}
+/**
+ * Sandboxed read-only bash for review/explore child sessions.
+ *
+ * One tool replaces the former read/grep/find/ls allowlist plus the git
+ * tool's policy table: a just-bash interpreter over a composed filesystem
+ * (see computeTopology), with just-git providing git inside the sandbox.
+ * Read-only is enforced at the capability layer — see DESIGN.md.
+ *
+ * Mounts are REAL-LAYOUT: on posix, $HOME at its own path (plus the
+ * project root when the cwd is outside home — read-only agents may read
+ * other projects); on win32, every existing drive at MSYS form
+ * ("C:\" -> "/c"). Sandbox paths therefore match host paths one-to-one,
+ * so a path printed by bash works verbatim with the read tool and vice
+ * versa. Everything outside the mounts is per-call in-memory scratch
+ * (/dev/null, /tmp) that evaporates with the interpreter.
+ *
+ * The `disabled` git list below is UX only (clean "not available" errors
+ * for pure mutators); enforcement is the read-only filesystem. Dual-purpose
+ * verbs (branch, tag, stash, config, remote, worktree) stay enabled so
+ * their read modes work; their write modes fail at the filesystem.
+ *
+ * Each call runs in a freshly constructed interpreter: per-call
+ * construction is the statelessness guarantee, and it avoids any
+ * shared-state questions between parallel children.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Type } from "@sinclair/typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Bash, InMemoryFs, MountableFs, OverlayFs, type ExecResult } from "@jerryan/just-bash";
+import { createGit, type GitCommandName } from "just-git";
+
+/** Pure-mutator git verbs, disabled for clean UX errors. FS enforces the rest. */
+const DISABLED_GIT: GitCommandName[] = [
+  "init",
+  "add",
+  "commit",
+  "checkout",
+  "switch",
+  "restore",
+  "reset",
+  "merge",
+  "cherry-pick",
+  "revert",
+  "rebase",
+  "mv",
+  "rm",
+  "clean",
+  "bisect",
+  "gc",
+  "repack",
+];
+
+// ---------------------------------------------------------------------------
+// Real-layout mount topology
+// ---------------------------------------------------------------------------
+
+type Platform = "win32" | "posix";
+const PLATFORM: Platform = process.platform === "win32" ? "win32" : "posix";
+
+function toSlashes(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+/** Canonical on-disk spelling (symlinks, casing); falls back to the input. */
+function canonicalize(p: string): string {
+  try {
+    const real = realpathSync.native(p);
+    // Strip Windows extended-length prefixes so paths stay comparable.
+    if (real.startsWith("\\\\?\\UNC\\")) return `\\${real.slice(8)}`;
+    if (real.startsWith("\\\\?\\")) return real.slice(4);
+    return real;
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Virtual mount point for a host root: posix roots map to themselves;
+ * win32 roots map to MSYS form ("C:\Users\jerry" -> "/c/Users/jerry").
+ * One path form is therefore understood by both the sandbox and pi's
+ * native tools (pi's native shell on Windows is an MSYS-family bash).
+ */
+export function virtualMountPointFor(hostRoot: string, platform: Platform): string {
+  const normalized = toSlashes(hostRoot);
+  if (platform !== "win32") return normalized;
+  const drive = /^([A-Za-z]):\/(.*)$/.exec(normalized);
+  if (!drive) return normalized; // UNC
+  const rest = drive[2]!.replace(/\/+$/, "");
+  return `/${drive[1]!.toLowerCase()}${rest ? `/${rest}` : ""}`;
+}
+
+/** Boundary-aware prefix check; slash-normalized, case-insensitive on win32. */
+function isWithin(root: string, child: string, platform: Platform): boolean {
+  const form = (p: string) => {
+    let out = toSlashes(p);
+    while (out.length > 1 && out.endsWith("/")) out = out.slice(0, -1);
+    return platform === "win32" ? out.toLowerCase() : out;
+  };
+  const r = form(root);
+  const c = form(child);
+  return c === r || c.startsWith(`${r}/`);
+}
+
+/**
+ * Resolve candidate host roots to a minimal, non-overlapping mount set
+ * (overlapping mounts are rejected by MountableFs). "home" and "cwd" are
+ * just candidates — neither is special. For each candidate, in order:
+ *  (1) "/" is dropped (a read-only overlay at the fs root would shadow
+ *      the scratch /dev/null and /tmp; MountableFs rejects it anyway),
+ *  (2) a candidate within an already-kept root is dropped,
+ *  (3) a candidate that CONTAINS kept roots replaces them.
+ */
+export function resolveMountRoots(candidates: string[], platform: Platform = PLATFORM): string[] {
+  const roots: string[] = [];
+  for (const candidate of candidates) {
+    if (toSlashes(candidate) === "/") continue; // (1)
+    if (roots.some((root) => isWithin(root, candidate, platform))) continue; // (2)
+    for (let i = roots.length - 1; i >= 0; i--) {
+      if (isWithin(candidate, roots[i]!, platform)) roots.splice(i, 1); // (3)
+    }
+    roots.push(candidate);
+  }
+  return roots;
+}
+
+/** Existing drive roots ("C:\", "D:\", ...); A/B skipped (floppy probes hang). */
+function probeWindowsDrives(): string[] {
+  const drives: string[] = [];
+  for (let code = 67; code <= 90; code++) {
+    const root = `${String.fromCharCode(code)}:\\`;
+    if (existsSync(root)) drives.push(root);
+  }
+  return drives;
+}
+
+// Probing drives touches every letter (a disconnected mapped drive can stall
+// for seconds), so it happens once per process, not per tool call. Node has
+// no drive-list API; the npm "list-drives" alternatives all spawn
+// wmic/powershell, which is worse per call than this probe.
+let cachedWindowsDrives: string[] | undefined;
+function windowsDrives(): string[] {
+  return (cachedWindowsDrives ??= probeWindowsDrives());
+}
+
+export interface SandboxTopology {
+  mounts: { at: string; root: string }[];
+  virtualCwd: string;
+  virtualHome: string;
+  /** Host absolute path -> virtual vfs path, or null when under no mount. */
+  hostToVirtual(hostPath: string): string | null;
+}
+
+export function computeTopology(
+  cwdInput: string,
+  homeInput: string,
+  options?: { platform?: Platform; drives?: string[]; canonicalize?: (p: string) => string },
+): SandboxTopology {
+  const platform = options?.platform ?? PLATFORM;
+  const canon = options?.canonicalize ?? canonicalize;
+  const cwd = canon(cwdInput);
+  const home = canon(homeInput);
+  // win32: home is of course on one of the drives, so only cwd is worth
+  // adding — and only matters for a UNC working directory, which no drive
+  // letter covers.
+  const spelled =
+    platform === "win32" ? [...(options?.drives ?? windowsDrives()), cwdInput] : [homeInput, cwdInput];
+  // Mounts are string-matched, so a symlinked path must be mounted under
+  // BOTH its spelled and canonical forms (macOS /var -> /private/var
+  // firmlinks) — otherwise a path typed in the spelled form misses the
+  // mount while pi's read tool (host-resolved) sees the file fine.
+  const candidates = [...spelled, ...spelled.map(canon)];
+  const mounts = resolveMountRoots(candidates, platform).map((root) => ({
+    at: virtualMountPointFor(root, platform),
+    root,
+  }));
+  const hostToVirtual = (hostPath: string): string | null => {
+    const canonical = canon(hostPath);
+    let best: { at: string; root: string } | null = null;
+    for (const mount of mounts) {
+      if (isWithin(mount.root, canonical, platform) && (!best || mount.root.length > best.root.length)) {
+        best = mount;
+      }
+    }
+    if (!best) return null;
+    const rel = toSlashes(
+      (platform === "win32" ? path.win32 : path.posix).relative(best.root, canonical),
+    );
+    return rel ? path.posix.join(best.at, rel) : best.at;
+  };
+  return {
+    mounts,
+    virtualCwd: hostToVirtual(cwd) ?? "/",
+    virtualHome: hostToVirtual(home) ?? "/",
+    hostToVirtual,
+  };
+}
+
+/**
+ * Compose the sandbox filesystem: real-layout read-only overlays over a
+ * writable in-memory base. The base provides working /dev/null (stderr
+ * silencing is a core shell idiom; on a real read-only mount the device
+ * still works) and per-call in-memory scratch (/tmp, ...) that evaporates
+ * with the interpreter. Note MountableFs strips the mount prefix before
+ * delegating, so the inner OverlayFs mounts at "/".
+ *
+ * allowSymlinks: with the default (false) any real-FS path traversing a
+ * symlink is rejected — fine for a project-only mount, but home is full
+ * of intentional symlinks (stow/chezmoi dotfiles, ~/.config, pnpm
+ * node_modules). Read-only enforcement is unaffected (writes fail with
+ * EROFS either way) and there is no confidentiality boundary to protect:
+ * the read tool is unrestricted.
+ */
+export function createSandboxFs(mounts: { at: string; root: string }[]): MountableFs {
+  const fs = new MountableFs({ base: new InMemoryFs() });
+  for (const mount of mounts) {
+    try {
+      fs.mount(
+        mount.at,
+        new OverlayFs({ root: mount.root, mountPoint: "/", readOnly: true, allowSymlinks: true }),
+      );
+    } catch {
+      // A cached drive that vanished since the probe (USB pulled, mapped
+      // drive dropped) must not brick every call for the process lifetime.
+    }
+  }
+  return fs;
+}
+
+const MAX_OUTPUT_CHARS = 50_000;
+const MAX_OUTPUT_LINES = 2_000;
+
+/**
+ * Filesystem-style error codes the sandbox can raise. just-bash reports
+ * command-level failures (touch, rm) as exit codes, but interpreter-level
+ * failures — output redirections write through the interpreter's own FS
+ * path — REJECT the exec promise with these. Both shapes mean the same
+ * thing to the caller: the command failed. Anything outside this taxonomy
+ * is a genuine interpreter bug and is rethrown, loudly.
+ */
+const FS_ERROR_PATTERN =
+  /^(EROFS|EACCES|EPERM|ENOENT|EFBIG|ENOSPC|EISDIR|ENOTDIR|ELOOP|ENOTEMPTY|EEXIST|EINVAL|EBUSY|EXDEV|EIO|ENAMETOOLONG|EMFILE|ENFILE|EPIPE)\b/;
+
+export function truncateOutput(output: string): string {
+  const lines = output.split("\n");
+  if (lines.length <= MAX_OUTPUT_LINES && output.length <= MAX_OUTPUT_CHARS) {
+    return output;
+  }
+  const kept = lines.slice(0, MAX_OUTPUT_LINES).join("\n").slice(0, MAX_OUTPUT_CHARS);
+  const keptLines = kept.split("\n").length;
+  return `${kept}\n\n[output truncated: showing ${keptLines} lines, ${kept.length} chars]`;
+}
+
+export const sandboxBashTool = defineTool({
+  name: "bash",
+  label: "bash (read-only)",
+  description:
+    "Execute a bash command in a sandboxed, read-only filesystem (standard utilities plus git; no network; writes to real paths fail by design; absolute host paths work verbatim). " +
+    "Returns stdout and stderr. Output is truncated to 2000 lines or 50KB (whichever is hit first). " +
+    "Each call runs in a fresh shell — cd and environment variables do not persist between calls.",
+  promptSnippet: "Run a command in the read-only sandboxed shell",
+  promptGuidelines: ["Use bash for searching, file inspection, and git history."],
+  parameters: Type.Object({
+    command: Type.String({
+      description:
+        "The command line to execute (e.g. 'grep -rn \"pattern\" src/', 'git log --oneline -10', 'find . -name \"*.ts\" | head').",
+    }),
+  }),
+  async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    const topology = computeTopology(path.resolve(ctx.cwd), os.homedir());
+    const bash = new Bash({
+      fs: createSandboxFs(topology.mounts),
+      cwd: topology.virtualCwd,
+      env: { HOME: topology.virtualHome },
+      // Deliberately NO python here: a bare `python3` on PATH implies the
+      // native interpreter (project env, pip). Sandboxed stdlib-only CPython
+      // is a separate tool with that contract made explicit — see
+      // sandbox-python.ts.
+      customCommands: [createGit({ network: false, disabled: DISABLED_GIT })],
+    });
+    const result = await execSafely(bash, params.command, signal);
+    const stdout = result.stdout;
+    const stderr = result.stderr;
+    const combined =
+      stdout && stderr ? `${stdout}\n${stderr}` : stdout || stderr || "(no output)";
+    const text =
+      result.exitCode === 0
+        ? truncateOutput(combined)
+        : `Exit code ${result.exitCode}\n${truncateOutput(combined)}`;
+    return {
+      content: [{ type: "text" as const, text }],
+      details: { exitCode: result.exitCode },
+    };
+  },
+});
+
+export async function execSafely(
+  bash: Bash,
+  command: string,
+  signal?: AbortSignal,
+): Promise<ExecResult> {
+  try {
+    return await bash.exec(command, { signal });
+  } catch (err: any) {
+    if (FS_ERROR_PATTERN.test(err?.message ?? "")) {
+      return { stdout: "", stderr: err.message, exitCode: 1 };
+    }
+    throw err;
+  }
+}

package/sandbox-python.ts

@@ -0,0 +1,169 @@
+/**
+ * Sandboxed "python" tool for review/explore child sessions: stdlib-only
+ * CPython (just-bash's WASM build) for dependency-free scripting and data
+ * processing, over the same read-only real-layout filesystem as the
+ * sandboxed bash (see sandbox-bash.ts).
+ *
+ * This is a SEPARATE tool on purpose, mirroring pi-overlayfs's design: a
+ * bare `python3` on PATH inside bash implies the native interpreter
+ * (project environment, pip, third-party packages) and the WASM CPython
+ * is none of that — exposing it as a shell command sells a capability
+ * that isn't there. The dedicated tool makes the stdlib-only contract
+ * explicit in its description. The bash sandbox therefore has no
+ * `python3`; scripts that need the real environment cannot run in a
+ * read-only child at all (fail-closed, same as everything else).
+ *
+ * Per call a fresh interpreter and filesystem are constructed — the same
+ * statelessness guarantee as the sandboxed bash. Inline code is staged to
+ * a /tmp scratch file (in-memory, gone with the call).
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import { Type } from "@sinclair/typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Bash, type ExecResult } from "@jerryan/just-bash";
+import {
+  computeTopology,
+  createSandboxFs,
+  execSafely,
+  truncateOutput,
+} from "./sandbox-bash.ts";
+
+const DEFAULT_TIMEOUT_SECONDS = 300;
+
+/** Scratch path inline code is staged at (per-call fs — no collision risk). */
+const STAGED_SCRIPT = "/tmp/.pi-py-script.py";
+
+const WINDOWS_ABSOLUTE = /^[a-zA-Z]:[\\/]/;
+const UNC_PATH = /^[\\/]{2}/;
+
+/** Single-quote escape for embedding an argument in a shell command line. */
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Resolve a model-typed path to a virtual vfs path. Real-layout mounts
+ * make host and virtual forms coincide, so: relative paths join the
+ * project root; absolute paths map through the mounts when covered and
+ * pass through unchanged otherwise (scratch like /tmp, or simply
+ * invisible to the sandbox).
+ */
+function toVirtual(
+  input: string,
+  virtualCwd: string,
+  hostToVirtual: (hostPath: string) => string | null,
+): string {
+  const trimmed = input.trim();
+  if (trimmed.startsWith("/") || WINDOWS_ABSOLUTE.test(trimmed) || UNC_PATH.test(trimmed)) {
+    return hostToVirtual(trimmed) ?? trimmed.replace(/\\/g, "/");
+  }
+  return path.posix.normalize(path.posix.join(virtualCwd, trimmed));
+}
+
+export const sandboxPythonTool = defineTool({
+  name: "python",
+  label: "python (stdlib, read-only)",
+  description:
+    "Run Python 3 (standard library only) for scripting and data processing, in the same read-only sandbox as bash. " +
+    "Provide exactly one of code (inline source) or path (a script). " +
+    "This is not the project's Python environment: third-party packages and pip are unavailable. " +
+    "Output is truncated to 2000 lines or 50KB (whichever is hit first).",
+  promptSnippet: "Run Python 3 scripts (standard library only)",
+  promptGuidelines: ["Use python for dependency-free scripting and data analysis."],
+  parameters: Type.Object({
+    code: Type.Optional(Type.String({ description: "Inline Python 3 source to execute" })),
+    path: Type.Optional(Type.String({ description: "Path to a Python script (absolute or relative to the project)" })),
+    args: Type.Optional(Type.Array(Type.String(), { description: "Arguments passed to the script" })),
+    timeout: Type.Optional(
+      Type.Number({ description: `Timeout in seconds (optional, defaults to ${DEFAULT_TIMEOUT_SECONDS})` }),
+    ),
+  }),
+  async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    const hasCode = typeof params.code === "string" && params.code.length > 0;
+    const hasPath = typeof params.path === "string" && params.path.trim().length > 0;
+    if (hasCode === hasPath) {
+      throw new Error("python: exactly one of 'code' or 'path' is required");
+    }
+    const requested = params.timeout;
+    // Clamp to [1, 3600]: NaN/0/negative would misbehave in setTimeout.
+    const timeoutSeconds =
+      typeof requested === "number" && Number.isFinite(requested)
+        ? Math.min(Math.max(Math.floor(requested), 1), 3600)
+        : DEFAULT_TIMEOUT_SECONDS;
+
+    const topology = computeTopology(path.resolve(ctx.cwd), os.homedir());
+    const fs = createSandboxFs(topology.mounts);
+    const bash = new Bash({
+      fs,
+      cwd: topology.virtualCwd,
+      env: { HOME: topology.virtualHome },
+      python: true,
+      // The interpreter's own caps (maxPythonTimeoutMs defaults to 30s,
+      // maxExecutionTimeMs to 1h) must sit ABOVE this tool's timer so a
+      // timeout surfaces as this tool's `timeout:N` error (via the abort
+      // below) rather than a raw exit-124 the agent can't distinguish from
+      // a script failure.
+      executionLimits: {
+        maxPythonTimeoutMs: timeoutSeconds * 1000 + 10_000,
+        maxExecutionTimeMs: timeoutSeconds * 1000 + 15_000,
+      },
+    });
+
+    // The CPython worker expects /tmp to exist in the vfs.
+    await fs.mkdir("/tmp", { recursive: true });
+
+    let scriptPath: string;
+    if (hasCode) {
+      scriptPath = STAGED_SCRIPT;
+      await fs.writeFile(scriptPath, params.code as string, { encoding: "utf8" });
+    } else {
+      scriptPath = toVirtual(params.path as string, topology.virtualCwd, topology.hostToVirtual);
+      if (!(await fs.exists(scriptPath))) {
+        throw new Error(`python: script not found: ${params.path}`);
+      }
+    }
+
+    const args = (params.args ?? []).map(shellQuote);
+    const command = [`python3 ${shellQuote(scriptPath)}`, ...args].join(" ");
+
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    // A listener on an already-aborted signal never fires — check first.
+    if (signal?.aborted) controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutSeconds * 1000);
+
+    let result: ExecResult;
+    try {
+      result = await execSafely(bash, command, controller.signal);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+    if (timedOut) {
+      let detail = "";
+      if (result!.stdout) detail += `\n${truncateOutput(result!.stdout)}`;
+      if (result!.stderr) detail += `\n--- stderr ---\n${truncateOutput(result!.stderr)}`;
+      throw new Error(`timeout:${timeoutSeconds}${detail}`);
+    }
+
+    const stdout = result!.stdout;
+    const stderr = result!.stderr;
+    const combined =
+      stdout && stderr ? `${stdout}\n${stderr}` : stdout || stderr || "(no output)";
+    const text =
+      result!.exitCode === 0
+        ? truncateOutput(combined)
+        : `Exit code ${result!.exitCode}\n${truncateOutput(combined)}`;
+    return {
+      content: [{ type: "text" as const, text }],
+      details: { exitCode: result!.exitCode },
+    };
+  },
+});