@cleocode/core 2026.6.12 → 2026.6.14

package/dist/tools/env-scrub.js

@@ -0,0 +1,176 @@
+/**
+ * Subprocess environment scrubbing (T11897 · S1 · security hardening).
+ *
+ * Building the environment a child process inherits is a SECURITY boundary, not
+ * a convenience. Two distinct threats are closed here:
+ *
+ * 1. **Sandbox escape via Pi-controlled env** — a model-driven loop that can
+ *    set `LD_PRELOAD`, `NODE_OPTIONS`, `GIT_SSH_COMMAND`, `DYLD_*`, or a custom
+ *    `PATH` gains arbitrary native code execution outside any command allowlist
+ *    (the OS loader / Node honour them) and can satisfy a basename denylist with
+ *    a workspace-resident impostor on a hijacked `PATH`. The scrubber NEVER
+ *    forwards any of these dangerous variables and PINS `PATH` to a trusted
+ *    absolute value.
+ * 2. **Daemon-secret exfiltration** — the daemon's own `process.env` carries
+ *    resolved provider credentials (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …),
+ *    OAuth headers, and vault material (`CLEO_VAULT_*`). Inheriting the full
+ *    parent env into a Pi-spawned child means a single `env`/`printenv`/log line
+ *    exfiltrates them. The scrubber builds a MINIMAL, explicitly-constructed env
+ *    instead of inheriting `process.env`.
+ *
+ * The doctrine is **allowlist, not denylist**: the scrubbed env starts EMPTY and
+ * only a small set of benign, named variables are copied through from the parent
+ * (locale, terminal, home/user, tmp). Everything else — including every secret,
+ * every loader hook, and `PATH` itself — is reconstructed from trusted inputs.
+ *
+ * Pure function of input — no global/session coupling, import-time side-effect
+ * free (S1).
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11897
+ * @saga T11387
+ */
+import { delimiter } from 'node:path';
+/**
+ * The trusted, absolute `PATH` a scrubbed subprocess runs under. A fixed list of
+ * standard system binary directories — NEVER the caller's (possibly Pi-poisoned)
+ * `PATH`. Pinning this defeats the "workspace-resident impostor on a hijacked
+ * PATH satisfies an allowed basename" escape: the workspace is not on it.
+ */
+export const TRUSTED_PATH = [
+    '/usr/local/sbin',
+    '/usr/local/bin',
+    '/usr/sbin',
+    '/usr/bin',
+    '/sbin',
+    '/bin',
+].join(delimiter);
+/**
+ * Benign environment variables copied through from the parent when present.
+ * These carry NO secrets and NO code-execution surface — locale, terminal type,
+ * timezone, home/user identity, and the tmp dir. `PATH` is deliberately ABSENT
+ * (it is pinned to {@link TRUSTED_PATH}); every `*_API_KEY`, `*_TOKEN`,
+ * `LD_*`, `DYLD_*`, `NODE_OPTIONS`, and `GIT_SSH_COMMAND` is deliberately ABSENT.
+ */
+const PASSTHROUGH_KEYS = [
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'TERM',
+    'TMPDIR',
+    'SHELL',
+];
+/**
+ * Variable-name prefixes that are NEVER forwarded into a scrubbed subprocess.
+ * These either grant arbitrary code execution to the child (loader/runtime
+ * hooks) or carry credentials. Matched case-INsensitively as a prefix so e.g.
+ * `LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD_INSERT_LIBRARIES`, `ANTHROPIC_API_KEY`,
+ * `OPENAI_API_KEY`, `CLEO_VAULT_SECRET`, and `AWS_SECRET_ACCESS_KEY` are all
+ * caught. Used to filter the caller-supplied `extra` map.
+ */
+const FORBIDDEN_PREFIXES = [
+    'LD_',
+    'DYLD_',
+    'NODE_OPTIONS',
+    'NODE_REPL_EXTERNAL_MODULE',
+    'GIT_SSH',
+    'GIT_PROXY',
+    'BASH_ENV',
+    'ENV',
+    'CDPATH',
+];
+/**
+ * Exact variable names that are NEVER forwarded (in addition to
+ * {@link FORBIDDEN_PREFIXES}). `PATH` is pinned separately, so a caller cannot
+ * override it via `extra`.
+ */
+const FORBIDDEN_EXACT = new Set(['PATH', 'IFS']);
+/**
+ * Substrings whose presence in a variable NAME marks it as a credential that is
+ * NEVER forwarded. Matched case-INsensitively. Catches `*_API_KEY`, `*_TOKEN`,
+ * `*_SECRET`, `*PASSWORD*`, OAuth material, and the vault namespace.
+ */
+const SECRET_NAME_SUBSTRINGS = [
+    'API_KEY',
+    'APIKEY',
+    'SECRET',
+    'TOKEN',
+    'PASSWORD',
+    'PASSWD',
+    'CREDENTIAL',
+    'PRIVATE_KEY',
+    'ACCESS_KEY',
+    'AUTH',
+    'VAULT',
+    'SESSION_KEY',
+];
+/**
+ * Whether a variable NAME is forbidden in a scrubbed subprocess env (a loader
+ * hook, `PATH`, or a credential).
+ *
+ * @param name - The environment variable name.
+ * @returns `true` when the variable must NOT be forwarded.
+ */
+export function isForbiddenEnvName(name) {
+    const upper = name.toUpperCase();
+    if (FORBIDDEN_EXACT.has(upper))
+        return true;
+    if (FORBIDDEN_PREFIXES.some((p) => upper.startsWith(p)))
+        return true;
+    if (SECRET_NAME_SUBSTRINGS.some((s) => upper.includes(s)))
+        return true;
+    return false;
+}
+/**
+ * Build a MINIMAL, explicitly-constructed subprocess environment.
+ *
+ * The result starts EMPTY; only the benign {@link PASSTHROUGH_KEYS} present in
+ * `parentEnv` are copied, `PATH` is pinned to a trusted absolute value, and any
+ * caller-supplied `extra` is merged ON TOP after being filtered through
+ * {@link isForbiddenEnvName}. The daemon's secrets and any loader hooks in the
+ * parent environment are therefore NEVER visible to the child, and an untrusted
+ * caller cannot reintroduce an escape via `extra`.
+ *
+ * @param options - {@link ScrubEnvOptions}.
+ * @returns A fresh `Record<string, string>` safe to hand to `spawn(..., { env })`.
+ *
+ * @example
+ * ```ts
+ * // A Pi-supplied env that tries to inject a loader hook + hijack PATH:
+ * const env = scrubSubprocessEnv({
+ *   extra: { LD_PRELOAD: '/tmp/evil.so', PATH: '/workspace', SAFE: '1' },
+ * });
+ * // env has no LD_PRELOAD, PATH is the pinned TRUSTED_PATH, only SAFE survives.
+ * ```
+ */
+export function scrubSubprocessEnv(options = {}) {
+    const parentEnv = options.parentEnv ?? process.env;
+    const scrubbed = {};
+    for (const key of PASSTHROUGH_KEYS) {
+        const value = parentEnv[key];
+        if (typeof value === 'string' && value.length > 0 && !isForbiddenEnvName(key)) {
+            scrubbed[key] = value;
+        }
+    }
+    // Pin PATH to a trusted absolute value — never the inbound/parent PATH.
+    scrubbed.PATH = options.path ?? TRUSTED_PATH;
+    // Merge caller-supplied extras ON TOP, but drop any dangerous key so an
+    // untrusted caller (Pi) cannot reintroduce a loader hook, secret, or PATH
+    // override through this channel.
+    if (options.extra) {
+        for (const [key, value] of Object.entries(options.extra)) {
+            if (typeof value !== 'string')
+                continue;
+            if (isForbiddenEnvName(key))
+                continue;
+            scrubbed[key] = value;
+        }
+    }
+    return scrubbed;
+}
+//# sourceMappingURL=env-scrub.js.map

package/dist/tools/env-scrub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-scrub.js","sourceRoot":"","sources":["../../src/tools/env-scrub.ts"],"names":[],"mappings":"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"}

package/dist/tools/exec-code-agent-tool.d.ts

@@ -0,0 +1,179 @@
+/**
+ * `execute_code` agent tool — guarded code execution via a {@link PiExecutionEnv}
+ * (T11946 · M7 · epic T11456 · SG-TOOLS).
+ *
+ * The first M7 catalog increment: the ONE capability the existing ~18-tool set
+ * lacks — running a supplied code snippet. It adds NO new execution mechanism of
+ * its own; it routes EVERY run through the EXISTING per-run execution-env selector
+ * {@link import('../llm/pi/resolve-execution-env.js').resolveExecutionEnv}, which
+ * prefers the Gondolin micro-VM (`backend: 'gondolin'`) when the optional
+ * `@earendil-works/gondolin` package + `/dev/kvm` + QEMU are present, and SILENTLY
+ * DEGRADES to the always-available in-process deny-first
+ * {@link import('../llm/pi/pi-execution-env.js').GuardedExecutionEnv} otherwise.
+ * The snippet runs via `env.exec(...)` — NEVER a raw `child_process`.
+ *
+ * ## Why the selector, not a new primitive (Gate-11 + D11142)
+ *
+ * `resolveExecutionEnv` already owns the backend choice + the optional-dep
+ * degradation. Reusing it means:
+ *   - **Optional-dep safety (D11142):** this module has NO `import type` from
+ *     `@earendil-works/gondolin`; the selector loads that package lazily and ONLY
+ *     when the VM is chosen. `core` builds + runs + tests with gondolin ABSENT —
+ *     the in-process env runs. This module is import-time side-effect-free.
+ *   - **Gate-11 (Tools-vs-Skills):** the tool is DEFINED here under
+ *     `packages/core/src/tools`; it constructs NO new atomic primitive — it
+ *     consumes the existing `ExecutionEnv` seam + the existing `ToolGuard`.
+ *   - **Gate-13 (LLM chokepoint):** `execute_code` runs CODE, not an LLM call. It
+ *     constructs NO transport / client and reads no API key — there is no
+ *     chokepoint concern.
+ *
+ * ## Availability (mirrors `browser_*`)
+ *
+ * The tool is ALWAYS registered but its {@link AvailabilityCheck} returns `false`
+ * unless the run context advertises `capabilities.codeExec === true`. This mirrors
+ * the Playwright-gated `browser_*` family: registered-but-hidden until the host
+ * opts code execution in, so a loop that never enables it cannot invoke arbitrary
+ * code. (The in-process env is itself ALWAYS constructible — Gondolin is the
+ * preferred-but-optional upgrade — so the gate is a host POLICY switch, not an
+ * infra probe.)
+ *
+ * ## Egress denylist (AC2)
+ *
+ * Before a command reaches `env.exec`, the tool rejects a real-egress verb
+ * ({@link import('../llm/pi/pi-gondolin-env.js').DENIED_EXEC_PREFIXES} — `gh` /
+ * `git push` / `git remote` / `npm publish` / `cleo`) via the shared
+ * {@link import('../llm/pi/pi-gondolin-env.js').deniedEgressVerb} predicate. The
+ * Gondolin backend enforces this denylist itself; applying it HERE gives the
+ * in-process fallback the SAME egress posture (the guarded env's command denylist
+ * is policy-configured and may not include these verbs).
+ *
+ * @epic T11456
+ * @task T11946
+ * @see ../llm/pi/resolve-execution-env.js — the backend selector this tool reuses
+ * @see ../llm/pi/pi-execution-env.js — the in-process guarded `ExecutionEnv` fallback
+ * @see ./web-agent-tools.js — the `browser_*` optional-dep + capability-gated pattern mirrored here
+ */
+import type { PiExecutionEnv } from '../llm/pi/pi-execution-env.js';
+import { type ExecutionEnvBackend, type ResolveExecutionEnvOptions, type ResolveExecutionEnvSeams } from '../llm/pi/resolve-execution-env.js';
+import { type ToolGuard } from '../tools/guard.js';
+import type { AgentToolRegistry, AvailabilityCheck } from './agent-registry.js';
+/** The languages `execute_code` knows how to invoke (AC2). */
+export declare const EXEC_CODE_LANGUAGES: readonly ["python", "node", "bash", "sh"];
+/** One supported {@link EXEC_CODE_LANGUAGES} value. */
+export type ExecCodeLanguage = (typeof EXEC_CODE_LANGUAGES)[number];
+/**
+ * Available ONLY when the run context opts code execution in
+ * (`capabilities.codeExec === true`). Mirrors the `browser_*` family's
+ * `playwright`-gated predicate: the tool is ALWAYS registered (so the catalog is
+ * stable) but hidden by `available()` until the host advertises the capability, so
+ * a loop that never enables it cannot run arbitrary code.
+ */
+export declare const codeExecAvailable: AvailabilityCheck;
+/**
+ * Result of an {@link registerExecCodeAgentTool | execute_code} run — the captured
+ * process output plus the resolved language and backend, for the LLM and for
+ * structured logging. `exitCode` is `null` when the process was killed by a
+ * signal/timeout (the {@link PiExecResult} contract).
+ */
+export interface ExecCodeResult {
+    /** The language the snippet was run as. */
+    readonly language: ExecCodeLanguage;
+    /** Captured standard output. */
+    readonly stdout: string;
+    /** Captured standard error. */
+    readonly stderr: string;
+    /** Process exit code, or `null` when killed by signal/timeout. */
+    readonly exitCode: number | null;
+    /** The confinement backend that ran the snippet (`gondolin` or `in-process`). */
+    readonly backend: ExecutionEnvBackend;
+    /** Whether the run completed without a denial/transport error (`exec` returned ok). */
+    readonly ok: boolean;
+    /**
+     * Present only when `ok === false`: a stable code + message for why the run did
+     * not produce a process result (e.g. a denied egress verb, or the selected
+     * env's `exec` returned `Result.err`). NEVER carries a raw secret.
+     */
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/**
+ * The selector seam {@link registerExecCodeAgentTool} resolves a
+ * {@link PiExecutionEnv} through. Defaults to the real
+ * {@link import('../llm/pi/resolve-execution-env.js').resolveExecutionEnv}.
+ *
+ * EXPORTED so the unit test can inject a fake selector that returns a fake
+ * `PiExecutionEnv` — asserting the selector IS called and its `exec` output is
+ * captured, WITHOUT a real Gondolin VM, QEMU, or subprocess. In production the
+ * default is the real selector (Gondolin when available, in-process guarded env
+ * otherwise — gondolin ABSENT in CI).
+ */
+export type ExecutionEnvResolver = (opts: ResolveExecutionEnvOptions, seams?: ResolveExecutionEnvSeams) => Promise<PiExecutionEnv>;
+/** Options for {@link registerExecCodeAgentTool} — all injectable for testing. */
+export interface ExecCodeAgentToolOptions {
+    /**
+     * The env selector. Defaults to the real
+     * {@link import('../llm/pi/resolve-execution-env.js').resolveExecutionEnv}. The
+     * test injects a fake that returns a fake `PiExecutionEnv` (no real VM/subprocess).
+     */
+    readonly resolveEnv?: ExecutionEnvResolver;
+    /**
+     * The confinement backend to PREFER. `'gondolin'` boots the micro-VM when the
+     * optional package + `/dev/kvm` + QEMU are present and DEGRADES to the in-process
+     * env otherwise (the CI / most-developer-machines path); `'in-process'` always
+     * resolves to the guarded env without probing the host. Defaults to `'gondolin'`
+     * — prefer the strongest available confinement, degrade silently.
+     */
+    readonly backend?: ExecutionEnvBackend;
+    /**
+     * The enforce-mode {@link ToolGuard} backing the in-process fallback. Defaults to
+     * a fresh `createToolGuard({ mode: 'enforce' })` per run. Injectable so a host
+     * can supply a guard with a project path allowlist + command denylist.
+     */
+    readonly guard?: ToolGuard;
+    /**
+     * The absolute workspace root the in-process fallback confines fs paths under.
+     * Defaults to the resolved project root (`resolveOrCwd(undefined)`, T9584 — never
+     * a bare `process.cwd()`). The VM backend confines to its own `/workspace`.
+     */
+    readonly workspaceRoot?: string;
+    /**
+     * The disposable seeded-copy host dir mounted RW at the VM's `/workspace`.
+     * REQUIRED only when a real Gondolin VM actually boots (`backend: 'gondolin'` AND
+     * available) — MUST be a `VACUUM INTO` snapshot dir, NEVER the live `.cleo` DBs.
+     * Ignored by the in-process fallback (the CI path).
+     */
+    readonly seededCopyDir?: string;
+}
+/**
+ * Build the command line for a `language` + `code` pair. Each interpreter runs the
+ * snippet from its inline-code flag (`python -c`, `node -e`, `bash -c`, `sh -c`)
+ * with the code passed as ONE single-quoted argument — no further shell expansion
+ * of the model's code into the command shape.
+ *
+ * @param language - The interpreter to run.
+ * @param code - The model-supplied snippet.
+ * @returns The command string handed to `env.exec`.
+ */
+export declare function buildExecCommand(language: ExecCodeLanguage, code: string): string;
+/**
+ * Register the `execute_code` tool into `registry`. Pure registration — no env is
+ * resolved, no VM is booted, no code runs here; all of that happens later inside
+ * the tool's `execute` through the injected (or default) selector. Import-time
+ * side-effect-free + optional-dep-safe (D11142).
+ *
+ * @param registry - The registry to populate.
+ * @param options - Injectable selector / backend / guard / workspace (for testing).
+ */
+export declare function registerExecCodeAgentTool(registry: AgentToolRegistry, options?: ExecCodeAgentToolOptions): void;
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. Aliases
+ * {@link registerExecCodeAgentTool} so a future scan-dir discovery (or the
+ * built-in aggregator) can call it uniformly with the other agent-tool modules.
+ *
+ * @param registry - The registry to populate.
+ */
+export declare function registerAgentTools(registry: AgentToolRegistry): void;
+//# sourceMappingURL=exec-code-agent-tool.d.ts.map

package/dist/tools/exec-code-agent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-code-agent-tool.d.ts","sourceRoot":"","sources":["../../src/tools/exec-code-agent-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAE9B,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAIhF,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,2CAA4C,CAAC;AAE7E,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAgE,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,IAAI,EAAE,0BAA0B,EAChC,KAAK,CAAC,EAAE,wBAAwB,KAC7B,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B,kFAAkF;AAClF,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAeD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAYjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,wBAA6B,GACrC,IAAI,CAkHN;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAEpE"}

package/dist/tools/exec-code-agent-tool.js

@@ -0,0 +1,239 @@
+/**
+ * `execute_code` agent tool — guarded code execution via a {@link PiExecutionEnv}
+ * (T11946 · M7 · epic T11456 · SG-TOOLS).
+ *
+ * The first M7 catalog increment: the ONE capability the existing ~18-tool set
+ * lacks — running a supplied code snippet. It adds NO new execution mechanism of
+ * its own; it routes EVERY run through the EXISTING per-run execution-env selector
+ * {@link import('../llm/pi/resolve-execution-env.js').resolveExecutionEnv}, which
+ * prefers the Gondolin micro-VM (`backend: 'gondolin'`) when the optional
+ * `@earendil-works/gondolin` package + `/dev/kvm` + QEMU are present, and SILENTLY
+ * DEGRADES to the always-available in-process deny-first
+ * {@link import('../llm/pi/pi-execution-env.js').GuardedExecutionEnv} otherwise.
+ * The snippet runs via `env.exec(...)` — NEVER a raw `child_process`.
+ *
+ * ## Why the selector, not a new primitive (Gate-11 + D11142)
+ *
+ * `resolveExecutionEnv` already owns the backend choice + the optional-dep
+ * degradation. Reusing it means:
+ *   - **Optional-dep safety (D11142):** this module has NO `import type` from
+ *     `@earendil-works/gondolin`; the selector loads that package lazily and ONLY
+ *     when the VM is chosen. `core` builds + runs + tests with gondolin ABSENT —
+ *     the in-process env runs. This module is import-time side-effect-free.
+ *   - **Gate-11 (Tools-vs-Skills):** the tool is DEFINED here under
+ *     `packages/core/src/tools`; it constructs NO new atomic primitive — it
+ *     consumes the existing `ExecutionEnv` seam + the existing `ToolGuard`.
+ *   - **Gate-13 (LLM chokepoint):** `execute_code` runs CODE, not an LLM call. It
+ *     constructs NO transport / client and reads no API key — there is no
+ *     chokepoint concern.
+ *
+ * ## Availability (mirrors `browser_*`)
+ *
+ * The tool is ALWAYS registered but its {@link AvailabilityCheck} returns `false`
+ * unless the run context advertises `capabilities.codeExec === true`. This mirrors
+ * the Playwright-gated `browser_*` family: registered-but-hidden until the host
+ * opts code execution in, so a loop that never enables it cannot invoke arbitrary
+ * code. (The in-process env is itself ALWAYS constructible — Gondolin is the
+ * preferred-but-optional upgrade — so the gate is a host POLICY switch, not an
+ * infra probe.)
+ *
+ * ## Egress denylist (AC2)
+ *
+ * Before a command reaches `env.exec`, the tool rejects a real-egress verb
+ * ({@link import('../llm/pi/pi-gondolin-env.js').DENIED_EXEC_PREFIXES} — `gh` /
+ * `git push` / `git remote` / `npm publish` / `cleo`) via the shared
+ * {@link import('../llm/pi/pi-gondolin-env.js').deniedEgressVerb} predicate. The
+ * Gondolin backend enforces this denylist itself; applying it HERE gives the
+ * in-process fallback the SAME egress posture (the guarded env's command denylist
+ * is policy-configured and may not include these verbs).
+ *
+ * @epic T11456
+ * @task T11946
+ * @see ../llm/pi/resolve-execution-env.js — the backend selector this tool reuses
+ * @see ../llm/pi/pi-execution-env.js — the in-process guarded `ExecutionEnv` fallback
+ * @see ./web-agent-tools.js — the `browser_*` optional-dep + capability-gated pattern mirrored here
+ */
+import { z } from 'zod';
+import { DENIED_EXEC_PREFIXES, deniedEgressVerb } from '../llm/pi/pi-gondolin-env.js';
+import { resolveExecutionEnv as realResolveExecutionEnv, } from '../llm/pi/resolve-execution-env.js';
+import { getLogger } from '../logger.js';
+import { resolveOrCwd } from '../paths.js';
+import { createToolGuard } from '../tools/guard.js';
+const log = getLogger('tool-exec-code');
+/** The languages `execute_code` knows how to invoke (AC2). */
+export const EXEC_CODE_LANGUAGES = ['python', 'node', 'bash', 'sh'];
+/**
+ * Available ONLY when the run context opts code execution in
+ * (`capabilities.codeExec === true`). Mirrors the `browser_*` family's
+ * `playwright`-gated predicate: the tool is ALWAYS registered (so the catalog is
+ * stable) but hidden by `available()` until the host advertises the capability, so
+ * a loop that never enables it cannot run arbitrary code.
+ */
+export const codeExecAvailable = (ctx) => ctx.capabilities?.codeExec === true;
+/**
+ * Shell-quote a single argument for a POSIX `sh -c` / interpreter `-c`/`-e`
+ * invocation: wrap in single quotes and escape embedded single quotes. The code
+ * is UNTRUSTED model input, so it is passed as ONE quoted argument to the
+ * interpreter's `-c`/`-e` flag rather than interpolated into the command shape.
+ *
+ * @param value - The raw argument (the model-supplied code).
+ * @returns The single-quoted, shell-safe token.
+ */
+function singleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build the command line for a `language` + `code` pair. Each interpreter runs the
+ * snippet from its inline-code flag (`python -c`, `node -e`, `bash -c`, `sh -c`)
+ * with the code passed as ONE single-quoted argument — no further shell expansion
+ * of the model's code into the command shape.
+ *
+ * @param language - The interpreter to run.
+ * @param code - The model-supplied snippet.
+ * @returns The command string handed to `env.exec`.
+ */
+export function buildExecCommand(language, code) {
+    const quoted = singleQuote(code);
+    switch (language) {
+        case 'python':
+            return `python -c ${quoted}`;
+        case 'node':
+            return `node -e ${quoted}`;
+        case 'bash':
+            return `bash -c ${quoted}`;
+        case 'sh':
+            return `sh -c ${quoted}`;
+    }
+}
+/**
+ * Register the `execute_code` tool into `registry`. Pure registration — no env is
+ * resolved, no VM is booted, no code runs here; all of that happens later inside
+ * the tool's `execute` through the injected (or default) selector. Import-time
+ * side-effect-free + optional-dep-safe (D11142).
+ *
+ * @param registry - The registry to populate.
+ * @param options - Injectable selector / backend / guard / workspace (for testing).
+ */
+export function registerExecCodeAgentTool(registry, options = {}) {
+    const resolveEnv = options.resolveEnv ?? realResolveExecutionEnv;
+    const backend = options.backend ?? 'gondolin';
+    registry.register({
+        name: 'execute_code',
+        // 'shell' — the run is a process invocation (its strongest side-effect surface).
+        class: 'shell',
+        description: 'Execute a code snippet in a guarded execution environment (Gondolin micro-VM ' +
+            'when available, in-process guarded sandbox otherwise) and capture its ' +
+            'stdout / stderr / exit code. Real-egress verbs (gh, git push, npm publish, ' +
+            'cleo) are denied. Available only when the run enables code execution.',
+        toolset: 'agent',
+        stateless: true,
+        available: codeExecAvailable,
+        parameters: z.object({
+            language: z
+                .enum(EXEC_CODE_LANGUAGES)
+                .describe('Interpreter to run the snippet with: python, node, bash, or sh.'),
+            code: z.string().describe('The source code / script to execute.'),
+            timeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Hard wall-time ceiling for the run, in milliseconds.'),
+        }),
+        execute: async (rawArgs) => {
+            // `rawArgs` is the schema-validated argument object (the dispatch engine
+            // re-validates against `parameters` before calling). Narrow defensively.
+            const language = rawArgs.language;
+            const code = String(rawArgs.code);
+            const timeoutMs = typeof rawArgs.timeoutMs === 'number' ? rawArgs.timeoutMs : undefined;
+            // AC2: deny a real-egress verb BEFORE the env runs it — same posture on the
+            // in-process fallback as on the Gondolin backend (whose own denylist is the
+            // shared DENIED_EXEC_PREFIXES list). The check runs against the SNIPPET
+            // itself (the leading verb the user wants to run), NOT the wrapped
+            // `bash -c '<snippet>'` command — whose argv-0 is always a benign
+            // interpreter (`bash`/`sh`/`python`/`node`). For a shell snippet (`bash`/`sh`)
+            // the code IS the command line, so `gh …`/`git push …`/`npm publish …` is
+            // caught; for `python`/`node` the same scan is a harmless extra net.
+            const denied = deniedEgressVerb(code);
+            if (denied !== null) {
+                return {
+                    language,
+                    stdout: '',
+                    stderr: '',
+                    exitCode: null,
+                    backend,
+                    ok: false,
+                    error: {
+                        code: 'E_EXEC_CODE_EGRESS_DENIED',
+                        message: `egress verb "${denied}" is denied (one of: ${DENIED_EXEC_PREFIXES.join(', ')})`,
+                    },
+                };
+            }
+            // Shape the interpreter command line (the snippet passed as ONE quoted
+            // argument to the interpreter's inline-code flag — no shell expansion of the
+            // model's code into the command shape).
+            const command = buildExecCommand(language, code);
+            // Resolve the per-run env through the SELECTOR (Gondolin if present, else the
+            // in-process guarded env). The selector owns the optional-dep degradation —
+            // this call works with gondolin ABSENT.
+            const guard = options.guard ?? createToolGuard({ mode: 'enforce' });
+            // `resolveOrCwd` resolves to the supplied root, else the project root (T9584
+            // — never a bare `process.cwd()` in core).
+            const workspaceRoot = resolveOrCwd(options.workspaceRoot);
+            const env = await resolveEnv({
+                backend,
+                guard,
+                workspaceRoot,
+                ...(options.seededCopyDir !== undefined ? { seededCopyDir: options.seededCopyDir } : {}),
+            });
+            try {
+                const result = await env.exec(command, {
+                    ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}),
+                });
+                if (!result.ok) {
+                    // `exec` never throws — a denial / failure is a typed Result.err. Surface
+                    // it as a non-ok run rather than a thrown executable error.
+                    return {
+                        language,
+                        stdout: '',
+                        stderr: '',
+                        exitCode: null,
+                        backend,
+                        ok: false,
+                        error: { code: result.error.code, message: result.error.message },
+                    };
+                }
+                return {
+                    language,
+                    stdout: result.value.stdout,
+                    stderr: result.value.stderr,
+                    exitCode: result.value.exitCode,
+                    backend,
+                    ok: true,
+                };
+            }
+            finally {
+                // Best-effort teardown — the env (VM or guarded) may own resources; cleanup
+                // never throws (the PiExecutionEnv contract).
+                try {
+                    await env.cleanup();
+                }
+                catch (err) {
+                    log.debug({ err }, 'execute_code: env cleanup failed (ignored)');
+                }
+            }
+        },
+    });
+}
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. Aliases
+ * {@link registerExecCodeAgentTool} so a future scan-dir discovery (or the
+ * built-in aggregator) can call it uniformly with the other agent-tool modules.
+ *
+ * @param registry - The registry to populate.
+ */
+export function registerAgentTools(registry) {
+    registerExecCodeAgentTool(registry);
+}
+//# sourceMappingURL=exec-code-agent-tool.js.map

package/dist/tools/exec-code-agent-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-code-agent-tool.js","sourceRoot":"","sources":["../../src/tools/exec-code-agent-tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/fs.d.ts

@@ -19,6 +19,36 @@
  * @saga T11387
  */
 import type { PathExistsInput, PathExistsResult, ReadFileInput, ReadFileResult, WriteFileInput, WriteFileResult } from '@cleocode/contracts/tools/atomic';
+/**
+ * Symlink-resolving canonicalization of a (possibly not-yet-existing) path.
+ *
+ * A purely LEXICAL path check (`resolve` + `relative`) is symlink-BLIND: a
+ * symlink planted inside an allowed root can point anywhere on the host, so the
+ * lexical path stays "inside" while the real target is outside. This is the
+ * classic symlink/TOCTOU escape. {@link canonicalizePath} resolves the REAL
+ * filesystem location so a containment check can be made against it:
+ *
+ * - If the path EXISTS, its own realpath is returned (every symlink component,
+ *   including the final one, is followed to its real target).
+ * - If the path does NOT exist (a fresh write target), the nearest existing
+ *   ANCESTOR directory is realpath'd and the not-yet-existing tail segments are
+ *   re-appended. This prevents a symlinked PARENT directory from redirecting a
+ *   write outside the boundary while still allowing legitimate new files.
+ *
+ * The returned path is always absolute. Containment MUST be re-checked against
+ * THIS value, not the lexical one.
+ *
+ * @param path - The path to canonicalize (absolute or relative to `process.cwd()`).
+ * @returns The symlink-resolved absolute path.
+ *
+ * @example
+ * ```ts
+ * // root/innocent.txt -> /tmp/secret  ⇒  canonicalizePath('root/innocent.txt')
+ * // returns '/tmp/secret', revealing the escape to the containment check.
+ * const real = await canonicalizePath(join(root, 'innocent.txt'));
+ * ```
+ */
+export declare function canonicalizePath(path: string): Promise<string>;
 /**
  * Read a file as text.
  *

package/dist/tools/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAGhF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAG1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAUrF;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQlF"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBpE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAGhF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAG1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAUrF;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQlF"}