@cruxy/cli 0.14.0 → 0.17.0

package/dist/onboarding/steps.js

@@ -17,7 +17,7 @@ const c = (io) => themeForColor(io.color);
  */
 export async function acquireKeyStep(io, deps, provider) {
     const col = c(io);
-    io.write(`\nYou'll need a Cruxy API key. Create one at ${col.accent(CREATE_KEY_URL)}\n`);
+    io.write(`\nYou'll need a cruxy API key. Create one at ${col.accent(CREATE_KEY_URL)}\n`);
     for (let attempt = 1; attempt <= MAX_KEY_ATTEMPTS; attempt++) {
         io.write(col.strong("Paste your API key: "));
         const key = (await io.readSecret()).trim();

package/dist/plan/service.d.ts

@@ -4,6 +4,7 @@ import type { PromptIO } from "../approval/index.js";
 import { ToolRegistry, type ToolContext } from "../tools/index.js";
 import { type AgentResult } from "../agent/loop.js";
 import type { StreamRenderer } from "../render/index.js";
+import type { Router } from "../routing/index.js";
 import { PlanExecutionPolicy } from "./policy.js";
 /**
  * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
@@ -36,5 +37,10 @@ export interface PlanSessionArgs {
     renderer?: StreamRenderer;
     /** Revision cap (defaults to {@link MAX_PLAN_REVISIONS}). */
     maxRevisions?: number;
+    /**
+     * Multi-model routing (C.30). When set, the propose phase routes on `plan`
+     * and step execution on `main-turn`; omitted → the provider default.
+     */
+    router?: Router;
 }
 export declare function runPlanSession(args: PlanSessionArgs): Promise<AgentResult>;

package/dist/plan/service.js

@@ -75,6 +75,8 @@ export async function runPlanSession(args) {
             projectInstructions: args.projectInstructions,
             renderer: args.renderer,
             planMode: true,
+            router: args.router,
+            taskClass: "plan",
         }));
         if (!holder.plan) {
             throw planInvalid("the model ended its turn without calling submit_plan");
@@ -106,6 +108,8 @@ export async function runPlanSession(args) {
                     git: args.git,
                     projectInstructions: args.projectInstructions,
                     renderer: args.renderer,
+                    router: args.router,
+                    taskClass: "main-turn",
                 }));
             };
             await executePlan(plan, {

package/dist/render/state.js

@@ -39,9 +39,12 @@ export function describePhase(phase, glyph = UNICODE_GLYPHS) {
         case "thinking": {
             const t = phase.tokens;
             // Honest numbers only: no usage yet → no figure at all.
-            return t && t.input + t.output > 0
+            const base = t && t.input + t.output > 0
                 ? `thinking${e} ${glyph.sep} tokens ${glyph.caretUp}${formatTokens(t.input)} ${glyph.caretDown}${formatTokens(t.output)}`
                 : `thinking${e}`;
+            // The real routing tier (C.30), appended honestly when present — same
+            // ` · ` joiner as the token counts.
+            return phase.tier ? `${base} ${glyph.sep} ${phase.tier}` : base;
         }
         case "calling-tool":
             return `${phase.label}${e}`;

package/dist/render/types.d.ts

@@ -53,10 +53,16 @@ export interface TokenUsage {
  * One phase is live at a time — it is a register, not a queue.
  */
 export type RenderPhase = 
-/** Waiting on the model. `tokens` = usage accumulated so far, omitted at 0. */
+/**
+ * Waiting on the model. `tokens` = usage accumulated so far, omitted at 0.
+ * `tier` = the routing tier this turn runs on (C.30), shown only when routing
+ * is active — an honest signal of the real tier, never a fabricated one, and
+ * always a tier name (never an upstream model id, U.8).
+ */
 {
     kind: "thinking";
     tokens?: TokenUsage;
+    tier?: string;
 }
 /** A tool call is executing; `label` is the human form ("read_file src/x.ts"). */
  | {

package/dist/routing/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";

package/dist/routing/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";
+// `resolve.ts` (tier → wire model-id) is deliberately NOT re-exported: the
+// mapping is internal to routing, so it can never be reached from a user-facing
+// render path (the internal-mapping-isolation guarantee, U.8).

package/dist/routing/resolve.d.ts

@@ -0,0 +1,17 @@
+import type { Tier } from "./types.js";
+/**
+ * Tier → gateway wire model-id. This is the SINGLE place the mapping lives, and
+ * it is INTERNAL to the routing package (deliberately not re-exported from the
+ * barrel) so it can never be called from a user-facing render path.
+ *
+ * For the Cruxy gateway a tier IS the wire model id — the gateway maps the tier
+ * to a concrete upstream model SERVER-SIDE. So this returns the tier name
+ * unchanged: the output is always a tier, and no upstream model name can
+ * originate here. That property is what keeps the U.8 gag structural rather than
+ * a filter — there is no upstream id in the process to leak (see the tier-gag
+ * test, which asserts this output is always a MODEL_TIERS member).
+ *
+ * The seam exists for a future provider whose tiers map to distinct wire ids;
+ * that mapping would live here and here only.
+ */
+export declare function resolveModelId(tier: Tier): string;

package/dist/routing/resolve.js

@@ -0,0 +1,18 @@
+/**
+ * Tier → gateway wire model-id. This is the SINGLE place the mapping lives, and
+ * it is INTERNAL to the routing package (deliberately not re-exported from the
+ * barrel) so it can never be called from a user-facing render path.
+ *
+ * For the Cruxy gateway a tier IS the wire model id — the gateway maps the tier
+ * to a concrete upstream model SERVER-SIDE. So this returns the tier name
+ * unchanged: the output is always a tier, and no upstream model name can
+ * originate here. That property is what keeps the U.8 gag structural rather than
+ * a filter — there is no upstream id in the process to leak (see the tier-gag
+ * test, which asserts this output is always a MODEL_TIERS member).
+ *
+ * The seam exists for a future provider whose tiers map to distinct wire ids;
+ * that mapping would live here and here only.
+ */
+export function resolveModelId(tier) {
+    return tier;
+}

package/dist/routing/router.d.ts

@@ -0,0 +1,47 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { Router, RoutingConfig, TaskClass, Tier } from "./types.js";
+/**
+ * The tier a config resolves to when nothing else pins one down — mirrors the
+ * gateway's `auto` fallback (`AUTO_FALLBACK_TIER` in the SDK), so an unrouted
+ * cruxy session lands on exactly the tier it does today.
+ */
+export declare const DEFAULT_TIER: Tier;
+/**
+ * The config-driven {@link Router}: maps a declared task class to a tier from
+ * `{ default, map }`, and fails loud when the resolved tier is not offered. It
+ * NEVER inspects prompt content — selection is purely `map[taskClass] ?? default`.
+ */
+export declare class ConfigRouter implements Router {
+    private readonly cfg;
+    private readonly offered;
+    /**
+     * @param cfg      the resolved routing table (default tier + per-task map)
+     * @param offered  the tiers this gateway/plan actually provides; a resolved
+     *                 tier outside this set fails loud. Defaults to all tiers — the
+     *                 seam a future entitlement check narrows (never a silent
+     *                 downgrade).
+     */
+    constructor(cfg: RoutingConfig, offered?: Iterable<Tier>);
+    select(taskClass: TaskClass): Tier;
+}
+/**
+ * Build a router from resolved config, or `null` when routing should stay
+ * inert. Routing is:
+ *
+ * - a cruxy-gateway concept — tiers do not apply to BYO providers, so non-cruxy
+ *   providers get `null` (no override, their `model.model` is used unchanged);
+ * - opt-in — with no `routing.default` and an empty `routing.map`, this returns
+ *   `null` so behavior (and the wire body, and the state line) is byte-identical
+ *   to today. Multi-tier routing activates only once the user configures it.
+ */
+export declare function routerForConfig(config: CruxyConfig): Router | null;
+/**
+ * Resolve a declared task class to `{ tier, model }`: the tier for honest
+ * surfacing (the U.4 state line), the wire model id for the request. The model
+ * id comes from the internal {@link resolveModelId} — callers never touch that
+ * mapping directly, so it stays the single source of truth.
+ */
+export declare function resolveTaskModel(router: Router, taskClass: TaskClass): {
+    tier: Tier;
+    model: string;
+};

package/dist/routing/router.js

@@ -0,0 +1,84 @@
+import { MODEL_TIERS } from "../brand/voice.js";
+import { routingTierUnavailable } from "../errors/index.js";
+import { resolveModelId } from "./resolve.js";
+/**
+ * The tier a config resolves to when nothing else pins one down — mirrors the
+ * gateway's `auto` fallback (`AUTO_FALLBACK_TIER` in the SDK), so an unrouted
+ * cruxy session lands on exactly the tier it does today.
+ */
+export const DEFAULT_TIER = "vaani";
+/**
+ * The config-driven {@link Router}: maps a declared task class to a tier from
+ * `{ default, map }`, and fails loud when the resolved tier is not offered. It
+ * NEVER inspects prompt content — selection is purely `map[taskClass] ?? default`.
+ */
+export class ConfigRouter {
+    cfg;
+    offered;
+    /**
+     * @param cfg      the resolved routing table (default tier + per-task map)
+     * @param offered  the tiers this gateway/plan actually provides; a resolved
+     *                 tier outside this set fails loud. Defaults to all tiers — the
+     *                 seam a future entitlement check narrows (never a silent
+     *                 downgrade).
+     */
+    constructor(cfg, offered = MODEL_TIERS) {
+        this.cfg = cfg;
+        this.offered = new Set(offered);
+    }
+    select(taskClass) {
+        // Explicit override, else the default — an unmapped/unknown class is not an
+        // error, it just takes the default (never a crash, never the cheapest).
+        const tier = this.cfg.map[taskClass] ?? this.cfg.default;
+        // Fail loud: a configured tier the gateway does not offer is a usage error
+        // to fix, NOT a silent substitution to some other tier (a user who asked for
+        // mira reasoning must never be quietly handed kavi).
+        if (!this.offered.has(tier)) {
+            throw routingTierUnavailable(tier, taskClass, [...this.offered]);
+        }
+        return tier;
+    }
+}
+/**
+ * The base tier implied by the session's `model.model`: a real tier passes
+ * through; `auto` (and any non-tier value) falls back to {@link DEFAULT_TIER}.
+ * Used so that when a user has pinned a single tier, an opt-in routing table
+ * that omits `routing.default` still defaults to THEIR tier, not a fixed one.
+ */
+function baseTierFromModel(model) {
+    return MODEL_TIERS.includes(model)
+        ? model
+        : DEFAULT_TIER;
+}
+/**
+ * Build a router from resolved config, or `null` when routing should stay
+ * inert. Routing is:
+ *
+ * - a cruxy-gateway concept — tiers do not apply to BYO providers, so non-cruxy
+ *   providers get `null` (no override, their `model.model` is used unchanged);
+ * - opt-in — with no `routing.default` and an empty `routing.map`, this returns
+ *   `null` so behavior (and the wire body, and the state line) is byte-identical
+ *   to today. Multi-tier routing activates only once the user configures it.
+ */
+export function routerForConfig(config) {
+    if (config.model.provider !== "cruxy")
+        return null;
+    const { default: def, map } = config.routing;
+    const configured = def !== undefined || Object.keys(map).length > 0;
+    if (!configured)
+        return null;
+    return new ConfigRouter({
+        default: def ?? baseTierFromModel(config.model.model),
+        map,
+    });
+}
+/**
+ * Resolve a declared task class to `{ tier, model }`: the tier for honest
+ * surfacing (the U.4 state line), the wire model id for the request. The model
+ * id comes from the internal {@link resolveModelId} — callers never touch that
+ * mapping directly, so it stays the single source of truth.
+ */
+export function resolveTaskModel(router, taskClass) {
+    const tier = router.select(taskClass);
+    return { tier, model: resolveModelId(tier) };
+}

package/dist/routing/types.d.ts

@@ -0,0 +1,42 @@
+import { MODEL_TIERS } from "../brand/voice.js";
+/**
+ * Multi-model routing (C.30): route each unit of work to the right tier instead
+ * of running one model for everything. The caller DECLARES a {@link TaskClass}
+ * at the call site; a {@link Router} maps that class to a {@link Tier} via config
+ * — it never sniffs the prompt to guess difficulty. The tier→gateway model-id
+ * mapping is internal (see `resolve.ts`); only tier names ever appear in config,
+ * logs, errors, or the state line (the U.8 tier gag).
+ */
+/**
+ * The unit-of-work classes a caller can declare. Each is an explicit intent —
+ * NOT a difficulty the router infers. Unknown/unset resolves to the router's
+ * default tier, never a crash.
+ */
+export declare const TASK_CLASSES: readonly ["main-turn", "subagent", "plan", "commit-msg", "classify", "summarize"];
+export type TaskClass = (typeof TASK_CLASSES)[number];
+/** A routing tier — the ONLY model vocabulary the user ever sees (U.8). */
+export type Tier = (typeof MODEL_TIERS)[number];
+/**
+ * Selects a tier for a declared task class. Deliberately one method: the caller
+ * passes intent, the router returns a tier from its configured mapping. No
+ * prompt-content inspection, ever — difficulty detection is explicitly out of
+ * scope (a caller declares; the router does not guess).
+ */
+export interface Router {
+    /**
+     * Map a task class to its tier. Falls back to the configured default when the
+     * class has no explicit mapping; throws `CRUXY_E_ROUTING_TIER_UNAVAILABLE`
+     * (fail loud, never a silent substitution) when the resolved tier is not
+     * offered.
+     */
+    select(taskClass: TaskClass): Tier;
+}
+/**
+ * The declarative routing table: a `default` tier plus per-task overrides. Lives
+ * in config (`routing.default`, `routing.map`). An empty map means every class
+ * resolves to `default` — a single tier, no traffic splitting.
+ */
+export interface RoutingConfig {
+    default: Tier;
+    map: Partial<Record<TaskClass, Tier>>;
+}

package/dist/routing/types.js

@@ -0,0 +1,27 @@
+/**
+ * Multi-model routing (C.30): route each unit of work to the right tier instead
+ * of running one model for everything. The caller DECLARES a {@link TaskClass}
+ * at the call site; a {@link Router} maps that class to a {@link Tier} via config
+ * — it never sniffs the prompt to guess difficulty. The tier→gateway model-id
+ * mapping is internal (see `resolve.ts`); only tier names ever appear in config,
+ * logs, errors, or the state line (the U.8 tier gag).
+ */
+/**
+ * The unit-of-work classes a caller can declare. Each is an explicit intent —
+ * NOT a difficulty the router infers. Unknown/unset resolves to the router's
+ * default tier, never a crash.
+ */
+export const TASK_CLASSES = [
+    /** An interactive main-agent turn. */
+    "main-turn",
+    /** A spawned subagent task (C.14). */
+    "subagent",
+    /** Plan proposal / revision (C.31). */
+    "plan",
+    /** Commit / pull-request text generation. */
+    "commit-msg",
+    /** A cheap one-shot classification. */
+    "classify",
+    /** Context compaction / summarization. */
+    "summarize",
+];

package/dist/subagent/orchestrator.d.ts

@@ -2,6 +2,7 @@ import type { Provider } from "@cruxy/sdk";
 import type { ApprovalDecision } from "../approval/types.js";
 import type { CruxyConfig } from "../config/index.js";
 import type { StreamRenderer } from "../render/index.js";
+import type { Router } from "../routing/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
@@ -15,6 +16,11 @@ import type { SubagentResult, SubagentSpec } from "./types.js";
 export interface SubagentOrchestratorDeps {
     provider: Provider;
     config: CruxyConfig;
+    /**
+     * Multi-model routing (C.30). When set, child runs route on their spec's task
+     * class (default `subagent`); omitted → the provider default (unchanged).
+     */
+    router?: Router;
     /** The parent's registry — the ceiling every child scope derives from. */
     parentRegistry: ToolRegistry;
     cwd: string;

package/dist/subagent/orchestrator.js

@@ -91,6 +91,8 @@ export class SubagentOrchestrator {
                 projectInstructions: deps.projectInstructions,
                 subagent: true,
                 budget,
+                router: deps.router,
+                taskClass: spec.taskClass ?? "subagent",
             });
         }
         catch (err) {

package/dist/subagent/types.d.ts

@@ -1,4 +1,5 @@
 import type { Usage } from "@cruxy/sdk";
+import type { TaskClass } from "../routing/index.js";
 /**
  * Types for subagent orchestration (C.14): the main agent delegates a bounded
  * subtask to a child agent that runs the SAME loop with its own fresh history,
@@ -35,6 +36,11 @@ export interface SubagentSpec {
      * spawn can narrow its budget, never raise it past the configured ceilings.
      */
     budget?: Partial<BudgetLimits>;
+    /**
+     * Routing task class for this spawn (C.30); defaults to `subagent`. A
+     * declaration at the spawn call site — not something the router guesses.
+     */
+    taskClass?: TaskClass;
 }
 /**
  * What the parent gets back — compact structured data, never the transcript.

package/dist/tools/shell/exec.d.ts

@@ -0,0 +1,53 @@
+import type { ToolContext } from "../types.js";
+/**
+ * The ONE gated + sandboxed shell path (C.16 + C.19). Both `run_command` and the
+ * C.19 hook runner funnel through {@link runGatedShell}: a command reaches
+ * execution only after passing the SAME `ctx.requestApproval` gate and only
+ * through the SAME `ctx.sandbox` (or host) substrate. There is deliberately no
+ * second exec route, so a hook can never get a privileged path — proven by the
+ * fact that both callers invoke this exact function.
+ *
+ * The structured {@link ShellExecResult} carries the raw exit code (which
+ * `run_command`'s text `ToolResult` hides) so the hook runner can decide
+ * blocking pass/fail on exit 0 vs non-zero, while `run_command` maps the same
+ * result back to its byte-identical `ToolResult`.
+ */
+/** The raw outcome of executing a shell command (gate already passed). */
+export interface ShellExecResult {
+    /** The wall-clock timeout tripped and the process tree was killed. */
+    timedOut: boolean;
+    /** Numeric exit code, or null when killed / signalled / unknown. */
+    exitCode: number | null;
+    /** Terminating signal (host path only); null under the sandbox. */
+    signal: string | null;
+    /** Combined stdout+stderr, capped to `shell.maxOutputBytes`. */
+    output: string;
+    /** Output was truncated at the cap. */
+    truncated: boolean;
+    /** The host process failed to *start* (spawn error). Sandbox start failures
+     * throw a coded error instead (propagated, never returned here). */
+    spawnError?: string;
+}
+/** The result of the gate + (if allowed) execution. */
+export interface GatedShellOutcome {
+    /** The U.3 gate allowed the command. When false, nothing executed. */
+    approved: boolean;
+    /** The rejection feedback when `approved` is false. */
+    rejection?: string;
+    /** The execution result — present iff `approved`. */
+    exec?: ShellExecResult;
+}
+/**
+ * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
+ * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
+ * rejection returns `{ approved: false }` and runs nothing. A non-interactive
+ * gate throws `CRUXY_E_APPROVAL_REQUIRED` (propagated, never swallowed); a
+ * sandbox that can't run throws its coded error (fail loud, no host fallback).
+ */
+export declare function runGatedShell(command: string, ctx: ToolContext): Promise<GatedShellOutcome>;
+/**
+ * Execute an already-approved command. Substrate is chosen SOLELY by
+ * `ctx.sandbox`: present → the container (C.16), never the host; absent → the
+ * bounded host spawn. No fallback path — a sandbox that can't run throws.
+ */
+export declare function execShell(command: string, ctx: ToolContext): Promise<ShellExecResult>;

package/dist/tools/shell/exec.js

@@ -0,0 +1,128 @@
+import { spawn } from "node:child_process";
+/**
+ * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
+ * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
+ * rejection returns `{ approved: false }` and runs nothing. A non-interactive
+ * gate throws `CRUXY_E_APPROVAL_REQUIRED` (propagated, never swallowed); a
+ * sandbox that can't run throws its coded error (fail loud, no host fallback).
+ */
+export async function runGatedShell(command, ctx) {
+    const decision = await ctx.requestApproval({ kind: "shell", command });
+    if (!decision.allow) {
+        return { approved: false, rejection: decision.feedback };
+    }
+    return { approved: true, exec: await execShell(command, ctx) };
+}
+/**
+ * Execute an already-approved command. Substrate is chosen SOLELY by
+ * `ctx.sandbox`: present → the container (C.16), never the host; absent → the
+ * bounded host spawn. No fallback path — a sandbox that can't run throws.
+ */
+export function execShell(command, ctx) {
+    return ctx.sandbox ? runSandboxed(command, ctx) : runBounded(command, ctx);
+}
+/** Run in the sandbox and normalize its neutral ExecResult (start failures
+ * throw coded errors from `sandbox.exec` and propagate — never caught here). */
+async function runSandboxed(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    const result = await ctx.sandbox.exec(command, {
+        cwd: ctx.cwd,
+        timeoutMs,
+        maxOutputBytes,
+        capture: "head",
+    });
+    return {
+        timedOut: result.timedOut,
+        exitCode: result.exitCode,
+        signal: null,
+        output: result.output,
+        truncated: result.outputTruncated,
+    };
+}
+/** Spawn the command on the host, capture bounded output, enforce the timeout. */
+function runBounded(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    return new Promise((resolve) => {
+        // `detached` makes the child its own process-group leader so the whole tree
+        // (the shell plus anything it spawns) can be killed on timeout.
+        const child = spawn(command, { shell: true, cwd: ctx.cwd, detached: true });
+        const chunks = [];
+        let captured = 0;
+        let truncated = false;
+        const capture = (buf) => {
+            if (truncated)
+                return;
+            const room = maxOutputBytes - captured;
+            if (buf.length <= room) {
+                chunks.push(buf);
+                captured += buf.length;
+            }
+            else {
+                if (room > 0) {
+                    chunks.push(buf.subarray(0, room));
+                    captured += room;
+                }
+                truncated = true;
+            }
+        };
+        child.stdout?.on("data", capture);
+        child.stderr?.on("data", capture);
+        // A single guard so the timeout-kill and the natural close can't both fire.
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            killTree(child.pid);
+            resolve({
+                timedOut: true,
+                exitCode: null,
+                signal: null,
+                output: "",
+                truncated,
+            });
+        }, timeoutMs);
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                timedOut: false,
+                exitCode: null,
+                signal: null,
+                output: "",
+                truncated: false,
+                spawnError: err.message,
+            });
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                timedOut: false,
+                exitCode: code,
+                signal: signal ?? null,
+                output: Buffer.concat(chunks).toString("utf8"),
+                truncated,
+            });
+        });
+    });
+}
+/**
+ * Kill the command's entire process group. POSIX-specific (negative pid targets
+ * the group); fine on our darwin/linux targets. Swallows errors — the process
+ * may already be gone.
+ */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/tools/shell/run-command.d.ts

@@ -4,6 +4,10 @@ import type { Tool } from "../types.js";
  * Run an arbitrary shell command in the project root. The highest-risk tool we
  * ship: it is gated on `ctx.approve` (a denial runs nothing) and bounded by a
  * timeout that kills the whole process tree plus a cap on captured output.
+ *
+ * Gate + execution live in the shared {@link runGatedShell} (also used by the
+ * C.19 hook runner — the single, un-bypassable shell path); this tool only maps
+ * the structured result back onto its `ToolResult` framing.
  */
 export declare const runCommandTool: Tool<z.ZodObject<{
     command: z.ZodString;