@cleocode/core 2026.6.12 → 2026.6.13

package/dist/tools/dispatch.js

@@ -0,0 +1,505 @@
+/**
+ * Agent tool-call dispatch engine (T1740 · epic T11456 · SG-TOOLS).
+ *
+ * The SINGLE chokepoint that turns a model-emitted tool-call `{ name, args }`
+ * into an executed, LLM-safe result. It is the SDK-side dispatch path the T1738
+ * architecture (D11141) names: **core DISPATCHES, cleo-os DRIVES**. Given a tool
+ * call from the agent loop, it:
+ *
+ *  1. **Looks up** the tool in the injected {@link AgentToolRegistry} (the
+ *     name→descriptor catalog). An unknown name is a typed
+ *     `tool-not-found` result — never a throw.
+ *  2. **Validates** the model-supplied arguments against the tool's Zod schema
+ *     (defense in depth: the wire layer advertised the JSON-schema, but the
+ *     model's emitted args are re-validated here before any side effect). A
+ *     schema failure is a typed `invalid-args` result carrying the FLATTENED
+ *     issue list — not the raw Zod error (no internals leak).
+ *  3. **Checks availability** for the current {@link ToolAvailabilityContext}
+ *     (network egress, binaries on PATH, capability flags). An unavailable tool
+ *     is a typed `guard-denied` result — the model is told the tool is not
+ *     offered right now, with no precondition internals.
+ *  4. **Charges the budget** ({@link ToolCallBudget}) — per-call count / wall-time
+ *     ceilings. An exhausted budget short-circuits with a typed `guard-denied`
+ *     result BEFORE the tool runs; a per-call timeout races the execution and
+ *     yields a typed `timeout` result.
+ *  5. **Executes** the bound {@link AgentToolExecutable} over the injected
+ *     {@link GuardedToolSurface} — the deny-first chokepoint
+ *     ({@link ./guard.js}). Every fs/shell side effect therefore still funnels
+ *     through the guard's path allowlist + command denylist + env scrub; there
+ *     is NO raw-primitive bypass.
+ *  6. **Formats** the outcome for LLM consumption ({@link formatToolResultForLlm})
+ *     — a `tool_result`-shaped payload the Pi loop feeds back to the model. On
+ *     ANY error the message is a redacted, classified summary; a raw secret,
+ *     stack trace, or guard internal NEVER reaches the model-facing string.
+ *
+ * ## Sync + async handlers (AC2)
+ *
+ * A registered {@link AgentToolExecutable} returns a `Promise<unknown>`, but a
+ * synchronous handler that returns a plain value is equally supported: the
+ * engine `await`s the call so a non-thenable return is normalized to a resolved
+ * value, and a synchronous throw is caught the same as a rejected promise.
+ *
+ * ## Why it lives in `core/src/tools` (Gate-11)
+ *
+ * The dispatch engine is a CORE-SDK concern, built entirely against the frozen
+ * {@link AgentToolRegistry} + {@link GuardedToolSurface} contracts. It defines
+ * NO new atomic tool primitive (Gate-11 Tools-vs-Skills boundary) and makes NO
+ * LLM call (Gate-13): result-formatting is pure serialization. The harness
+ * (`cleo-os`) and the in-process Pi adapter merely SUPPLY the registry, the
+ * guard, and the workspace context, then read the {@link ToolDispatchResult}.
+ *
+ * @task T1740
+ * @epic T11456
+ * @see ./agent-registry.js — the name→descriptor catalog + availability checks
+ * @see ./guard.js — the deny-first surface every executable routes side effects through
+ * @see ../llm/pi/pi-tool-bridge.js — the AC6 consumer wiring this into the Pi loop
+ */
+import { getLogger } from '../logger.js';
+import { ALWAYS_AVAILABLE } from './agent-registry.js';
+const log = getLogger('tool-dispatch');
+/**
+ * Stable machine-readable error codes, one per {@link ToolDispatchErrorKind}.
+ * Surfaced on the failure envelope so a programmatic caller never string-matches
+ * the human message.
+ */
+export const TOOL_DISPATCH_ERROR_CODE = {
+    'tool-not-found': 'E_TOOL_NOT_FOUND',
+    'invalid-args': 'E_TOOL_INVALID_ARGS',
+    'guard-denied': 'E_TOOL_GUARD_DENIED',
+    'execution-error': 'E_TOOL_EXECUTION_ERROR',
+    timeout: 'E_TOOL_TIMEOUT',
+};
+/**
+ * Per-run tool-call budget (AC5). Tracks call count + cumulative wall-time
+ * against the configured {@link ToolBudgetLimits}. The engine consults
+ * {@link admit} BEFORE running a tool (rejecting once a ceiling is hit) and
+ * {@link charge}s the elapsed time AFTER. A single budget instance is threaded
+ * across all calls of one run, so the count/time caps are run-scoped.
+ */
+export class ToolCallBudget {
+    #limits;
+    #callsUsed = 0;
+    #timeUsedMs = 0;
+    /**
+     * @param limits - The ceilings this budget enforces (each optional → uncapped).
+     */
+    constructor(limits = {}) {
+        this.#limits = limits;
+    }
+    /** The per-call timeout ceiling in ms, or `undefined` when uncapped. */
+    get perCallTimeoutMs() {
+        return this.#limits.perCallTimeoutMs;
+    }
+    /**
+     * Whether another call is admitted right now. Returns a typed denial reason
+     * (or `null` when admitted) so the engine can map it onto the precise
+     * `guard-denied` message WITHOUT exposing the limit internals to the model.
+     *
+     * @returns `null` when a call is admitted; otherwise the human-readable reason.
+     */
+    admit() {
+        if (this.#limits.maxCalls !== undefined && this.#callsUsed >= this.#limits.maxCalls) {
+            return `tool-call budget exhausted (max ${this.#limits.maxCalls} calls)`;
+        }
+        if (this.#limits.totalTimeBudgetMs !== undefined &&
+            this.#timeUsedMs >= this.#limits.totalTimeBudgetMs) {
+            return `tool-call time budget exhausted (max ${this.#limits.totalTimeBudgetMs}ms)`;
+        }
+        return null;
+    }
+    /**
+     * Charge one completed call against the budget.
+     *
+     * @param elapsedMs - The call's measured wall-time in milliseconds.
+     */
+    charge(elapsedMs) {
+        this.#callsUsed += 1;
+        this.#timeUsedMs += Math.max(0, elapsedMs);
+    }
+    /** A read-only snapshot of current consumption (AC5). */
+    snapshot() {
+        const callsRemaining = this.#limits.maxCalls === undefined
+            ? Number.POSITIVE_INFINITY
+            : Math.max(0, this.#limits.maxCalls - this.#callsUsed);
+        const timeRemainingMs = this.#limits.totalTimeBudgetMs === undefined
+            ? Number.POSITIVE_INFINITY
+            : Math.max(0, this.#limits.totalTimeBudgetMs - this.#timeUsedMs);
+        return {
+            callsUsed: this.#callsUsed,
+            callsRemaining,
+            timeUsedMs: this.#timeUsedMs,
+            timeRemainingMs,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Engine
+// ---------------------------------------------------------------------------
+/** Maximum length of a formatted `tool_result` body before truncation (AC4). */
+export const MAX_TOOL_RESULT_CHARS = 16_000;
+/**
+ * The agent tool-call dispatch engine (AC1).
+ *
+ * One instance per agent run: it holds the frozen registry, the guarded surface,
+ * the availability context, and the run-scoped budget, and dispatches each
+ * model-emitted {@link ToolCall} to a classified {@link ToolDispatchResult}.
+ * {@link dispatch} NEVER throws — every failure mode is encoded as a typed
+ * {@link ToolDispatchFailure} (AC3), so the agent loop can always feed a
+ * `tool_result` back and continue.
+ *
+ * @example
+ * ```ts
+ * const registry = await createAgentToolRegistry();
+ * const tools = createToolGuard({ allowedRoots: [root], mode: 'enforce' });
+ * const engine = new ToolDispatchEngine({
+ *   registry,
+ *   tools,
+ *   budget: new ToolCallBudget({ maxCalls: 50, perCallTimeoutMs: 30_000 }),
+ * });
+ * const result = await engine.dispatch({ id: 'c1', name: 'read_file_paged', arguments: { path } });
+ * // result.ok ? feed result.display : feed the classified result.message
+ * ```
+ */
+export class ToolDispatchEngine {
+    #registry;
+    #tools;
+    #availability;
+    #budget;
+    /**
+     * @param deps - The registry, guarded surface, availability context, and
+     *   optional run-scoped budget.
+     */
+    constructor(deps) {
+        this.#registry = deps.registry;
+        this.#tools = deps.tools;
+        this.#availability = deps.availability ?? {};
+        this.#budget = deps.budget ?? new ToolCallBudget();
+    }
+    /** A read-only snapshot of the run's budget consumption (AC5). */
+    budgetSnapshot() {
+        return this.#budget.snapshot();
+    }
+    /**
+     * Dispatch a single model-emitted tool call to a classified result (AC1–AC5).
+     *
+     * The full pipeline — lookup → validate → availability → budget admit →
+     * (timed) execute → charge → format — runs here. It NEVER throws: a thrown
+     * executable (incl. a deny-first `GuardDeniedError` during the side effect)
+     * becomes an `execution-error`, a slow executable a `timeout`, a cancelled call
+     * an `execution-error`, an unknown name a `tool-not-found`, bad args an
+     * `invalid-args`, and an unavailable tool / exhausted budget a `guard-denied`.
+     *
+     * ## Abort handling (honest contract)
+     *
+     * A `signal` (when supplied) is honoured REGARDLESS of whether a per-call
+     * timeout is configured — including the default no-budget production path: an
+     * already-aborted signal short-circuits before the executable is awaited, and
+     * an abort RACED in flight rejects with an `execution-error`. BUT this is
+     * abandon-the-promise cancellation, NOT preemptive kill: the frozen
+     * {@link AgentToolExecutable}/{@link GuardedToolSurface} contracts expose no
+     * signal channel, so a tool that already spawned an OS process keeps that
+     * process running until the tool's own internal bound fires. The engine
+     * returns promptly; the side effect may still be settling. See
+     * {@link ToolDispatchEngine.#runWithTimeout} for the full rationale.
+     *
+     * @param call - The model-emitted tool call (`{ id, name, arguments }`).
+     * @param signal - Optional abort signal honoured on every path (timeout or
+     *   not); aborting yields an `execution-error` but cannot preemptively kill an
+     *   in-flight OS process (frozen-contract limitation).
+     * @returns The terminal {@link ToolDispatchResult}.
+     */
+    async dispatch(call, signal) {
+        // 1. Lookup (AC1).
+        const descriptor = this.#registry.get(call.name);
+        if (!descriptor) {
+            return this.#fail(call.name, 'tool-not-found', `unknown tool "${call.name}"`);
+        }
+        // 2. Validate arguments against the tool's Zod schema (AC3 — defense in depth).
+        const parsed = descriptor.parameters.safeParse(call.arguments);
+        if (!parsed.success) {
+            const issues = flattenZodIssues(parsed.error);
+            return this.#fail(call.name, 'invalid-args', `arguments for "${call.name}" failed validation`, issues);
+        }
+        // 3. Availability check (AC5 — registry availability predicates).
+        const available = (descriptor.available ?? ALWAYS_AVAILABLE)(this.#availability);
+        if (!available) {
+            return this.#fail(call.name, 'guard-denied', `tool "${call.name}" is not available in the current context`);
+        }
+        // 4. Budget admit (AC5 — count/time ceilings BEFORE running).
+        const denial = this.#budget.admit();
+        if (denial !== null) {
+            return this.#fail(call.name, 'guard-denied', denial);
+        }
+        // 5. Timed execution through the guarded surface (AC2 sync/async + AC5 timeout).
+        // `parsed.data` is the schema-validated argument object; a tool's `parameters`
+        // is always a Zod object schema, so the validated value is a record. Coerce to
+        // the executable's input shape (the generic `z.ZodType` infers `unknown`).
+        const validatedArgs = isRecord(parsed.data)
+            ? parsed.data
+            : {};
+        const startedAt = Date.now();
+        try {
+            const value = await this.#runWithTimeout(descriptor, validatedArgs, signal);
+            this.#budget.charge(Date.now() - startedAt);
+            // 6. Format the success for LLM consumption (AC4).
+            return { ok: true, name: call.name, value, display: formatToolValueForLlm(value) };
+        }
+        catch (err) {
+            // Charge the elapsed time even on failure so a long-running failed call
+            // still counts against the time budget (AC5).
+            this.#budget.charge(Date.now() - startedAt);
+            if (err instanceof ToolTimeoutError) {
+                return this.#fail(call.name, 'timeout', err.message);
+            }
+            if (err instanceof ToolAbortError) {
+                // Cancellation is an execution-error (the call did not complete). The
+                // engine-authored abort message carries no secret, so it is safe verbatim.
+                log.debug({ tool: call.name, kind: 'execution-error' }, 'tool dispatch aborted');
+                return this.#fail(call.name, 'execution-error', err.message);
+            }
+            // Any thrown executable error (incl. a deny-first GuardDeniedError raised
+            // DURING the side effect) is an execution-error. The message is REDACTED
+            // (AC3) — no raw secret/stack reaches the model-facing result.
+            const redacted = redactErrorMessage(err);
+            log.debug({ tool: call.name, kind: 'execution-error' }, 'tool dispatch execution failed');
+            return this.#fail(call.name, 'execution-error', redacted);
+        }
+    }
+    /**
+     * Run the executable, racing it against the per-call timeout AND the abort
+     * signal whenever EITHER is present.
+     *
+     * Both a synchronous return value and a `Promise` are handled: `await`ing a
+     * non-thenable normalizes it to a resolved value, and a synchronous throw is
+     * caught by {@link dispatch}'s surrounding `try` exactly like a rejection
+     * (AC2). The timeout rejects with a {@link ToolTimeoutError} the caller maps
+     * to a `timeout` result; an abort rejects with a {@link ToolAbortError} the
+     * caller maps to an `execution-error` (the call was cancelled, not slow).
+     *
+     * ## Fast path
+     *
+     * When NO timeout is configured AND no `signal` is supplied there is nothing
+     * to race, so the executable promise is returned directly — the engine adds no
+     * overhead to the common bounded-by-the-loop case.
+     *
+     * ## Cancellation is cooperative-or-abandon, NOT preemptive
+     *
+     * Winning the race (timeout or abort) only ABANDONS the executable promise —
+     * it does NOT cancel the running tool. The frozen {@link AgentToolExecutable}
+     * signature (`(args, tools) => Promise<unknown>`) and the frozen
+     * {@link GuardedToolSurface} (whose `executeShell`/`executePty`/`runGit` carry
+     * no `AbortSignal` parameter) expose NO cancellation channel, so a tool that
+     * spawned a real OS process keeps that process running in the background until
+     * the tool's OWN internal bound (its per-call `timeoutMs`, when the model
+     * supplied one) fires. The engine therefore returns a `timeout`/`execution-error`
+     * result to the model PROMPTLY while the underlying side effect may still be
+     * settling. This is the honest contract: the dispatch-level cap bounds how long
+     * the LOOP waits, not how long the OS process lives. Wiring a real signal
+     * through to the surface requires evolving the frozen registry +
+     * `GuardedToolSurface` contracts (out of T1740's scope — tracked for the
+     * contract owner of #1013).
+     */
+    async #runWithTimeout(descriptor, args, signal) {
+        const timeoutMs = this.#budget.perCallTimeoutMs;
+        // `Promise.resolve(...)` normalizes a synchronous (non-thenable) return into
+        // a resolved promise; a synchronous throw inside `execute` rejects it.
+        const run = Promise.resolve(descriptor.execute(args, this.#tools));
+        // Fast path: nothing to race against → return the executable directly.
+        if (timeoutMs === undefined && signal === undefined)
+            return run;
+        // A pre-aborted signal short-circuits BEFORE awaiting the run — the abort was
+        // already requested, so the engine must not wait for (nor charge a full
+        // timeout for) the in-flight call. This is the default-production path the
+        // no-budget config exercises: the signal is honoured even with no timeout.
+        if (signal?.aborted) {
+            throw new ToolAbortError(`tool "${descriptor.name}" call aborted`);
+        }
+        let timer;
+        let onAbort;
+        const interrupt = new Promise((_resolve, reject) => {
+            // Wire the per-call timeout only when one is configured.
+            if (timeoutMs !== undefined) {
+                timer = setTimeout(() => reject(new ToolTimeoutError(`tool "${descriptor.name}" exceeded the per-call timeout of ${timeoutMs}ms`)), timeoutMs);
+            }
+            // Wire the abort listener whenever a (not-yet-aborted) signal is present —
+            // independent of whether a timeout is set, so the default no-budget path
+            // still honours containment-managed cancellation.
+            if (signal) {
+                onAbort = () => reject(new ToolAbortError(`tool "${descriptor.name}" call aborted`));
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+        });
+        try {
+            return await Promise.race([run, interrupt]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (signal && onAbort)
+                signal.removeEventListener('abort', onAbort);
+        }
+    }
+    /** Build a classified {@link ToolDispatchFailure}. */
+    #fail(name, kind, message, issues) {
+        return {
+            ok: false,
+            name,
+            kind,
+            code: TOOL_DISPATCH_ERROR_CODE[kind],
+            message,
+            ...(issues !== undefined ? { issues } : {}),
+        };
+    }
+}
+/** Thrown internally when a tool call exceeds its per-call timeout (AC5). */
+export class ToolTimeoutError extends Error {
+    /** Machine-readable code. */
+    code = 'E_TOOL_TIMEOUT';
+    constructor(message) {
+        super(message);
+        this.name = 'ToolTimeoutError';
+    }
+}
+/**
+ * Thrown internally when a tool call is cancelled via its {@link AbortSignal}
+ * (containment-managed run cancel / OOM-guard / budget kill). Distinct from
+ * {@link ToolTimeoutError}: a timeout means "the call was too slow", an abort
+ * means "the run was cancelled out from under the call". The engine maps it to a
+ * typed `execution-error` result (the call did not complete).
+ *
+ * @remarks Winning the abort race only ABANDONS the executable promise — it does
+ *   NOT preemptively kill a tool that already spawned an OS process, because the
+ *   frozen {@link AgentToolExecutable}/{@link GuardedToolSurface} contracts carry
+ *   no signal channel (see {@link ToolDispatchEngine.dispatch}).
+ */
+export class ToolAbortError extends Error {
+    /** Machine-readable code. */
+    code = 'E_TOOL_ABORTED';
+    constructor(message) {
+        super(message);
+        this.name = 'ToolAbortError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Result formatting (AC4)
+// ---------------------------------------------------------------------------
+/**
+ * Render a tool's raw return value into the LLM-facing `tool_result` body (AC4).
+ *
+ * A string passes through; everything else is JSON-serialized (pretty, stable).
+ * A circular / non-serializable value degrades to its `String(...)` form rather
+ * than throwing. The result is hard-capped at {@link MAX_TOOL_RESULT_CHARS} with
+ * a truncation marker so one tool call cannot blow the model's context window.
+ *
+ * @param value - The raw tool return.
+ * @returns The model-safe `tool_result` string.
+ */
+export function formatToolValueForLlm(value) {
+    let rendered;
+    if (typeof value === 'string') {
+        rendered = value;
+    }
+    else if (value === undefined) {
+        rendered = '';
+    }
+    else {
+        try {
+            rendered = JSON.stringify(value, null, 2) ?? String(value);
+        }
+        catch {
+            // Circular / BigInt / non-serializable — degrade rather than throw.
+            rendered = String(value);
+        }
+    }
+    return truncateForLlm(rendered);
+}
+/**
+ * Project a terminal {@link ToolDispatchResult} onto the `tool_result` message
+ * shape the agent loop feeds back to the model (AC4).
+ *
+ * The `content` is `result.display` on success or the redacted, classified
+ * `result.message` on failure (with the flattened arg issues appended when
+ * present). `isError` lets the loop / transport mark the turn so the model knows
+ * the call did not succeed.
+ *
+ * @param result - The dispatch outcome.
+ * @returns A `{ toolCallId, toolName, content, isError }` envelope.
+ */
+export function formatToolResultForLlm(call, result) {
+    if (result.ok) {
+        return { toolCallId: call.id, toolName: result.name, content: result.display, isError: false };
+    }
+    const issuesText = result.issues && result.issues.length > 0
+        ? `\n${result.issues.map((i) => `- ${i.path ? `${i.path}: ` : ''}${i.message}`).join('\n')}`
+        : '';
+    return {
+        toolCallId: call.id,
+        toolName: result.name,
+        content: `[${result.code}] ${result.message}${issuesText}`,
+        isError: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// Redaction + helpers
+// ---------------------------------------------------------------------------
+/** Truncate a rendered result to {@link MAX_TOOL_RESULT_CHARS} with a marker. */
+function truncateForLlm(text) {
+    if (text.length <= MAX_TOOL_RESULT_CHARS)
+        return text;
+    const head = text.slice(0, MAX_TOOL_RESULT_CHARS);
+    const omitted = text.length - MAX_TOOL_RESULT_CHARS;
+    return `${head}\n…[truncated ${omitted} chars]`;
+}
+/**
+ * Produce a REDACTED, model-safe message from a thrown executable error (AC3).
+ *
+ * Only the error's single-line `message` is kept — never the stack trace (which
+ * can leak absolute paths / internal module structure) and never an attached
+ * `cause`. The message itself is scrubbed for obvious secret-looking tokens so a
+ * tool that interpolates a credential into its error string cannot leak it to
+ * the model. A non-`Error` throw degrades to a fixed, generic summary.
+ *
+ * @param err - The thrown value.
+ * @returns A single-line, secret-scrubbed message safe for the model.
+ */
+export function redactErrorMessage(err) {
+    const raw = err instanceof Error ? err.message : typeof err === 'string' ? err : 'tool execution failed';
+    // Keep a single line (drop any embedded newlines/stack-like content) and cap
+    // the length so a runaway message cannot dominate the context window.
+    const firstLine = raw.split('\n', 1)[0] ?? 'tool execution failed';
+    return scrubSecrets(firstLine).slice(0, 500);
+}
+/**
+ * Best-effort secret scrub for a model-facing string. Masks the high-signal
+ * secret shapes (provider key prefixes, bearer tokens, long base64-ish blobs)
+ * so a leaked credential cannot reach the LLM-facing result. This is a
+ * defense-in-depth net on TOP of the architecture's rule that no plaintext key
+ * is ever in scope here — not a substitute for it.
+ *
+ * @param text - The candidate message.
+ * @returns The message with secret-looking tokens masked.
+ */
+function scrubSecrets(text) {
+    return text
+        .replace(/\b(sk|pk|rk|ghp|gho|ghs|xoxb|xoxp|AKIA)[-_a-zA-Z0-9]{12,}\b/g, '[redacted]')
+        .replace(/\bBearer\s+[A-Za-z0-9._-]{12,}\b/gi, 'Bearer [redacted]')
+        .replace(/\beyJ[A-Za-z0-9._-]{20,}\b/g, '[redacted-jwt]');
+}
+/**
+ * Flatten a {@link z.ZodError} into the minimal, model-safe
+ * {@link ToolArgIssue}[] — path + reason only, no raw Zod internals.
+ *
+ * @param error - The Zod validation error.
+ * @returns The flattened issues.
+ */
+export function flattenZodIssues(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.map(String).join('.'),
+        message: issue.message,
+    }));
+}
+/** Narrow an unknown to a plain (non-array) record. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/tools/dispatch.js.map

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

package/dist/tools/env-scrub.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare const TRUSTED_PATH: string;
+/** Options for {@link scrubSubprocessEnv}. */
+export interface ScrubEnvOptions {
+    /**
+     * The parent environment to copy the benign {@link PASSTHROUGH_KEYS} from.
+     * Defaults to `process.env`. Injectable for tests so a clean env can be
+     * asserted without mutating the real process environment.
+     */
+    readonly parentEnv?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Extra variables to set on the scrubbed env (e.g. a caller-supplied `env`
+     * merged ON TOP of the minimal base). These are themselves SCRUBBED — any
+     * dangerous key (loader hooks, `PATH`, secrets) is dropped, so an untrusted
+     * caller (Pi) cannot reintroduce an escape through this channel.
+     */
+    readonly extra?: Readonly<Record<string, string | undefined>>;
+    /**
+     * The trusted `PATH` to pin. Defaults to {@link TRUSTED_PATH}. Callers MUST
+     * pass an absolute, trusted value — never the inbound/Pi-controlled `PATH`.
+     */
+    readonly path?: string;
+}
+/**
+ * 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 declare function isForbiddenEnvName(name: string): boolean;
+/**
+ * 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 declare function scrubSubprocessEnv(options?: ScrubEnvOptions): Record<string, string>;
+//# sourceMappingURL=env-scrub.d.ts.map

package/dist/tools/env-scrub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-scrub.d.ts","sourceRoot":"","sources":["../../src/tools/env-scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAOR,CAAC;AAsBlB,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAClE;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC9D;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAiDD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMxD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,eAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BxF"}