@cruxy/cli 1.11.2 → 1.11.3

package/dist/session/replay.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { modeFromFlags } from "../agent/mode.js";
 import { redactMessages } from "./redact.js";
-import { KNOWN_EVENT_KINDS, SessionEventSchema, SessionMetaSchema, } from "./types.js";
+import { KNOWN_EVENT_KINDS, SessionEventSchema, SessionMetaSchema, emptyCompactionTally, } from "./types.js";
 /**
  * Replay: fold an append-only event log back into the state a session needs to
  * resume (P2).
@@ -109,6 +109,10 @@ export function foldEvents(events, counts = {}) {
     let planMode = false;
     let mode = null;
     let redactions = 0;
+    let lastVerification;
+    let externalChanges = 0;
+    let plan;
+    const compactions = emptyCompactionTally();
     const resumes = [];
     const usage = { input_tokens: 0, output_tokens: 0 };
     for (const event of events) {
@@ -123,6 +127,22 @@ export function foldEvents(events, counts = {}) {
                     ...asMessages(event.summary),
                     ...messages.slice(event.replaced),
                 ];
+                // And tallied (P3): the count is the events; the sums cover only the
+                // events that carry a cost, so a pre-P3 compaction counts as one that
+                // happened and not as one that freed nothing.
+                compactions.count++;
+                if (event.estimatedBefore !== undefined &&
+                    event.estimatedAfter !== undefined) {
+                    compactions.measured++;
+                    compactions.freedTokens += Math.max(0, event.estimatedBefore - event.estimatedAfter);
+                    compactions.summaryInputTokens += event.summaryInputTokens ?? 0;
+                    compactions.summaryOutputTokens += event.summaryOutputTokens ?? 0;
+                }
+                break;
+            case "instruction-loss":
+                // Counted, not folded: the synopsis is already in the history as the
+                // model sees it. This is the fact that it may be missing something.
+                compactions.instructionLosses++;
                 break;
             case "clear":
                 messages = [];
@@ -156,6 +176,56 @@ export function foldEvents(events, counts = {}) {
                 // could be added without touching `meta` or the message array.
                 resumes.push({ at: event.at, cwd: event.cwd });
                 break;
+            case "verification":
+                // Last-writer-wins, and never folded into the messages: a run is a
+                // fact ABOUT the turn, not a turn in it. The tool_result the model saw
+                // is already in the `append` events; this is the structured claim.
+                lastVerification = {
+                    at: event.at,
+                    tool: event.tool,
+                    command: event.command,
+                    ...(event.source !== undefined ? { source: event.source } : {}),
+                    passed: event.passed,
+                    exitCode: event.exitCode,
+                    durationMs: event.durationMs,
+                    ...(event.total !== undefined ? { total: event.total } : {}),
+                    failureCount: event.failureCount,
+                    failureNames: event.failureNames,
+                    outputTruncated: event.outputTruncated,
+                    substrate: event.substrate,
+                };
+                break;
+            case "external-change":
+                // Counted, not folded: the refusal wrote nothing, so there is nothing
+                // in the history to adjust — only a fact for the resume notice.
+                externalChanges++;
+                break;
+            case "plan-approved":
+                // A new approval replaces the last: every step starts `pending`, as
+                // the executor had it, and the `plan-step` events that follow move
+                // them. Never folded into the messages — the plan's text is already
+                // there as the model's own `submit_plan` call.
+                plan = {
+                    approvedAt: event.at,
+                    decision: event.decision,
+                    steps: event.steps.map((s) => ({
+                        id: s.id,
+                        title: s.title,
+                        kind: s.kind,
+                        status: "pending",
+                    })),
+                };
+                break;
+            case "plan-step": {
+                // A transition for a step the last approval did not name is skipped,
+                // not an error: a torn `plan-approved` line, or a newer build's
+                // vocabulary. Position matters — a step left `running` is one whose
+                // outcome the log never received.
+                const step = plan?.steps.find((s) => s.id === event.stepId);
+                if (step)
+                    step.status = event.status;
+                break;
+            }
             case "meta":
                 break;
         }
@@ -172,6 +242,10 @@ export function foldEvents(events, counts = {}) {
         unknownEvents: counts.unknownEvents ?? 0,
         resumes,
         redactions,
+        ...(lastVerification ? { lastVerification } : {}),
+        externalChanges,
+        compactions,
+        ...(plan ? { plan } : {}),
     };
 }
 /** Read and parse a session file into its events, counting unusable lines. */

package/dist/session/resume.js

@@ -1,3 +1,4 @@
+import { formatTokens } from "../render/state.js";
 import { selectList } from "../components/index.js";
 import { usageError } from "../errors/index.js";
 import { listSessionRefs, listSessions, matchSessionRefs, summarizeSession, } from "./list.js";
@@ -127,8 +128,95 @@ export function loadResume(session, cwd) {
         warnings.push(`this session was redacted ${state.redactions === 1 ? "once" : `${state.redactions} times`} — ` +
             `secrets are masked in the restored history, but the original text is still in ${session.file}`);
     }
+    if (state.externalChanges > 0) {
+        // A refused write is a fact about the user's TREE, not about cruxy: while
+        // they were being asked to approve a change, something else wrote to the
+        // file. It reached the model as an error at the time; on resume it is
+        // said once more, because "was my tree written to by something else"
+        // is a question people ask after the fact.
+        warnings.push(`${state.externalChanges} write${state.externalChanges === 1 ? " was" : "s were"} refused in this session ` +
+            `because the file changed on disk while awaiting approval — nothing was written by cruxy; ` +
+            `the session log names each path`);
+    }
+    if (state.compactions.count > 0) {
+        // What compaction has cost this conversation (P3 context quality), said
+        // once on resume because it is the moment a user decides whether to
+        // continue in a history that has been summarised N times. The freed and
+        // spent figures cover only the compactions that recorded them; the clause
+        // saying so is not optional when they differ.
+        warnings.push(describeCompactions(state.compactions));
+    }
+    if (state.compactions.instructionLosses > 0) {
+        // The heuristic's finding, restated where it can still be acted on: the
+        // sentences are in the session log; the remedy is to say them again.
+        const n = state.compactions.instructionLosses;
+        warnings.push(`${n} compaction${n === 1 ? "" : "s"} in this session may have dropped an instruction you gave — ` +
+            `the session log names the sentences; restate anything that still applies`);
+    }
+    if (state.lastVerification) {
+        // Not a warning in spirit, but this is the one channel a resume has, and
+        // the sentence is the same one `/status` shows: what last ran and how it
+        // exited, dated. A resumed session's "the tests passed" is a claim about
+        // the tree as it was THEN; the age is what keeps it honest.
+        const v = state.lastVerification;
+        const exit = v.exitCode === null ? "no exit code" : `exit ${v.exitCode}`;
+        warnings.push(`last verification ${relativeAge(v.at)}: ${v.tool} \`${v.command}\` → ${exit}`);
+    }
+    if (state.plan) {
+        // The last approved plan and where it got to (plan-durability). Same
+        // channel, same reasoning as the verification line: a fact the user
+        // decides on before continuing. The sentence ends by saying the approval
+        // is not carried over, because the one thing a reader of "approved" might
+        // reasonably expect is that the consent came back with the session.
+        warnings.push(describePlan(state.plan));
+    }
     return { session, state, warnings };
 }
+/**
+ * One sentence for the last approved plan (plan-durability): when it was
+ * approved and how, how many steps finished, which failed, and — the fact a
+ * resume exists to surface — whether a step was still running when the
+ * session ended. Says in so many words that the approval is not carried over:
+ * `[g]`'s grants lived in the allowlist of the process that asked, and this
+ * process has not asked.
+ */
+export function describePlan(p, now = Date.now()) {
+    const n = p.steps.length;
+    const count = (status) => p.steps.filter((s) => s.status === status).length;
+    const done = count("done");
+    const failed = count("failed");
+    const pending = count("pending");
+    const running = p.steps.find((s) => s.status === "running");
+    const how = p.decision === "approve-grant"
+        ? "with safe steps auto-allowed"
+        : "step by step";
+    const parts = [`${done}/${n} step${n === 1 ? "" : "s"} done`];
+    if (failed > 0)
+        parts.push(`${failed} failed`);
+    if (running) {
+        parts.push(`step ${running.id} (${running.title}) was still running when the session ended`);
+    }
+    if (pending > 0)
+        parts.push(`${pending} never started`);
+    return (`last plan approved ${relativeAge(p.approvedAt, now)} ${how}: ${parts.join(", ")} — ` +
+        `that approval is not carried into this session; every action asks again`);
+}
+/**
+ * One sentence for what compaction has cost a session (P3 context quality).
+ * Shared by the resume notice and nothing else; `/context` and the one-shot
+ * summary render the same tally as lines (`render/context-view.ts`).
+ */
+export function describeCompactions(c) {
+    const times = `compacted ${c.count === 1 ? "once" : `${c.count} times`} in this session`;
+    if (c.measured === 0) {
+        return `${times} — cost not recorded (written before it was measured)`;
+    }
+    const scope = c.measured < c.count
+        ? ` (${c.count - c.measured} of them recorded no cost)`
+        : "";
+    return (`${times} — freed ~${formatTokens(c.freedTokens)} tokens; ` +
+        `the summaries cost ~${formatTokens(c.summaryInputTokens)} in / ~${formatTokens(c.summaryOutputTokens)} out${scope}`);
+}
 /**
  * VALIDATE `--resume <id>` — which session does this name? — without loading it.
  *

package/dist/session/types.js

@@ -154,6 +154,43 @@ export const CompactionEventSchema = z
     replaced: z.number().int().nonnegative(),
     /** What replaced them (the synthetic pair). */
     summary: z.array(MessageSchema),
+    /**
+     * What the compaction COST (P3 context quality) — the four facts in hand
+     * at the write site and, until P3, thrown away there. All optional: a log
+     * written before P3 carries none, and absence means "not measured", never
+     * zero. Freed tokens is `estimatedBefore - estimatedAfter` and is NOT
+     * stored — one derivation, in the fold, rather than a fifth field that
+     * could disagree with the other two.
+     *
+     * The estimates are `estimateTokens` over the history — the same chars/4
+     * heuristic the trigger uses — WITHOUT the fixed reserve, which is a
+     * setting and would cancel out of the difference anyway.
+     */
+    estimatedBefore: z.number().int().nonnegative().optional(),
+    estimatedAfter: z.number().int().nonnegative().optional(),
+    /**
+     * The summarize call's own usage, as the provider reported it. Absent
+     * when the provider reported nothing — the same honesty rule as the usage
+     * record: unknown is not zero.
+     */
+    summaryInputTokens: z.number().int().nonnegative().optional(),
+    summaryOutputTokens: z.number().int().nonnegative().optional(),
+})
+    .passthrough();
+/**
+ * A compaction after which the user's instructions could not all be found in
+ * the synopsis (P3 context quality). Written by the heuristic in
+ * `agent/instruction-loss.ts`, which can be wrong both ways and says so; the
+ * event is what makes a suspected loss auditable after the fact instead of a
+ * warning that scrolled away. `sentences` are the user's own words, bounded
+ * and truncated — enough to recognise what may need restating.
+ */
+export const InstructionLossEventSchema = z
+    .object({
+    kind: z.literal("instruction-loss"),
+    at: z.string(),
+    runId: z.string().optional(),
+    sentences: z.array(z.string()),
 })
     .passthrough();
 /** `/clear`: history dropped, session kept. Replay resets to an empty array. */
@@ -283,6 +320,111 @@ export const ResumedEventSchema = z
     cliVersion: z.string().optional(),
 })
     .passthrough();
+/**
+ * One run that ACTUALLY EXECUTED (P2 verification): `run_tests`, or a
+ * `run_command` the model chose. An index over what happened, keyed to the
+ * turn it happened in — NOT a copy of the run's output. The `append` event
+ * already holds the tool_result the model saw, as the string built for the
+ * model; this is the structured claim beside it, written from the same
+ * object the tool built rather than re-parsed from that string (the same
+ * reasoning as the `run_tests` renderer side channel, P3).
+ *
+ * `passed` is the exit code and nothing else. `tool` and `source` are plain
+ * strings so a newer build's tool or provenance parses here instead of
+ * poisoning the line. A refused attempt, a denied approval or a spawn failure
+ * ran nothing, so no event is written for it — writing one would be a
+ * fabrication.
+ *
+ * Evidence, not enforcement: nothing reads this to decide whether a turn may
+ * end. See `verification/types.ts` for why that decision stands.
+ */
+export const VerificationEventSchema = z
+    .object({
+    kind: z.literal("verification"),
+    at: z.string(),
+    runId: z.string().optional(),
+    tool: z.string(),
+    command: z.string(),
+    source: z.string().optional(),
+    passed: z.boolean(),
+    exitCode: z.number().int().nullable(),
+    durationMs: z.number().nonnegative(),
+    total: z.number().int().nonnegative().optional(),
+    failureCount: z.number().int().nonnegative().default(0),
+    failureNames: z.array(z.string()).default([]),
+    outputTruncated: z.boolean().default(false),
+    substrate: z.string(),
+})
+    .passthrough();
+/**
+ * A write refused because its target moved during the approval wait (P1).
+ *
+ * The refusal itself is an error string handed to the model; before this
+ * event the user learned of it only by opening a rollback preview later.
+ * Something else wrote to a file in their tree while they were being asked to
+ * approve a change to it, and that is recorded here as a fact about the
+ * session — separate from `verification` so the fold never mistakes one for
+ * the other. No content is recorded: the path and what moved are the whole
+ * fact.
+ */
+export const ExternalChangeEventSchema = z
+    .object({
+    kind: z.literal("external-change"),
+    at: z.string(),
+    runId: z.string().optional(),
+    path: z.string(),
+    what: z.string(),
+})
+    .passthrough();
+/**
+ * The user approved a plan (plan-durability).
+ *
+ * Recorded as a FACT — the decision kind and the steps as approved, dated —
+ * because it is stronger than the mode toggle, which was already journaled,
+ * and it used to evaporate with the process: the plan lived in a local holder
+ * inside one `runPlanSession` call and nowhere else. The plan's text was
+ * already on disk as the model's own `submit_plan` tool_use; this is the
+ * typed record beside it, the one a reader can fold without parsing a tool
+ * call.
+ *
+ * IT IS NEVER RE-ARMED ON RESUME. `decision: "approve-grant"` says the user
+ * chose `[g]`, which wrote grants into the session allowlist — RAM, in the
+ * process that asked. A resumed session reading this event and restoring
+ * those grants would pre-authorize writes the user consented to in a
+ * different process, against a tree that has since changed. The fold hands
+ * back a description; nothing on the consent side reads it.
+ *
+ * `decision` and `kind` are plain strings so a log written by a newer build
+ * parses here rather than poisoning the line.
+ */
+export const PlanApprovedEventSchema = z
+    .object({
+    kind: z.literal("plan-approved"),
+    at: z.string(),
+    runId: z.string().optional(),
+    /** `approve` or `approve-grant`, as the user chose. */
+    decision: z.string(),
+    steps: z.array(z
+        .object({ id: z.string(), title: z.string(), kind: z.string() })
+        .passthrough()),
+})
+    .passthrough();
+/**
+ * One step of the last approved plan changed status (plan-durability):
+ * `running` when its turn began, `done` or `failed` when it ended. A step
+ * whose last event is `running` is the signature of an interrupted plan —
+ * the process died before the step could report either outcome — and that
+ * is exactly the fact the resume notice needs.
+ */
+export const PlanStepEventSchema = z
+    .object({
+    kind: z.literal("plan-step"),
+    at: z.string(),
+    runId: z.string().optional(),
+    stepId: z.string(),
+    status: z.string(),
+})
+    .passthrough();
 /** Every event, discriminated on `kind`. */
 export const SessionEventSchema = z.discriminatedUnion("kind", [
     SessionMetaSchema,
@@ -294,6 +436,11 @@ export const SessionEventSchema = z.discriminatedUnion("kind", [
     UsageEventSchema,
     RedactEventSchema,
     ResumedEventSchema,
+    VerificationEventSchema,
+    ExternalChangeEventSchema,
+    InstructionLossEventSchema,
+    PlanApprovedEventSchema,
+    PlanStepEventSchema,
 ]);
 /**
  * Every `kind` this build understands, derived from the union itself so the two
@@ -304,3 +451,14 @@ export const SessionEventSchema = z.discriminatedUnion("kind", [
  * they used to be counted as one.
  */
 export const KNOWN_EVENT_KINDS = new Set(SessionEventSchema.options.map((option) => option.shape.kind.value));
+/** A tally with nothing in it — a fresh session, or a log with no compaction. */
+export function emptyCompactionTally() {
+    return {
+        count: 0,
+        measured: 0,
+        freedTokens: 0,
+        summaryInputTokens: 0,
+        summaryOutputTokens: 0,
+        instructionLosses: 0,
+    };
+}

package/dist/testing/run-tests-tool.js

@@ -147,7 +147,9 @@ export function makeRunTestsTool(deps = {}) {
             // The structured result goes to the renderer here, from the same object
             // the payload below is built from — never from re-reading that payload.
             try {
-                deps.onResult?.(result, resolved);
+                deps.onResult?.(result, resolved, {
+                    substrate: ctx.sandbox ? "sandbox" : "host",
+                });
             }
             catch {
                 // A renderer problem is not a test-run problem.

package/dist/tools/create-pull-request.js

@@ -25,7 +25,8 @@ const parameters = z.object({
     body: z
         .string()
         .optional()
-        .describe("PR body in markdown (what changed · why · verification). Omit to auto-generate."),
+        .describe("PR body in markdown (what changed · why). Omit to auto-generate. " +
+        "Do not write a Verification section: it is added from the record of what actually ran this session, and one you write is replaced by it."),
     base: z
         .string()
         .optional()
@@ -58,6 +59,12 @@ export const createPullRequestTool = {
                     ...i,
                     scopes: guidance.scopes,
                     skillBody: guidance.skillBody,
+                    // The PR body's Verification section is the record's (P2): the
+                    // runs this session actually executed, with their exit codes —
+                    // or no such section at all. The model's own body keeps its
+                    // prose; a Verification section it wrote is replaced by this.
+                    // Never a manufactured "ran typecheck + lint + test".
+                    verification: { runs: ctx.verification?.sessionRuns() ?? [] },
                 }),
             });
             const outcome = await service.openPullRequest({

package/dist/tools/file/apply-patch.js

@@ -172,8 +172,12 @@ export const applyPatchTool = {
         const drifted = [];
         for (const p of planned) {
             const moved = await changedSince(p.abs, p.approved, p.rel);
-            if (moved)
-                drifted.push(moved);
+            if (moved) {
+                drifted.push(moved.message);
+                // One record per path that moved (P2 verification): the user learns
+                // which files something else wrote to, not just that the patch failed.
+                ctx.verification?.record({ kind: "external-change", ...moved });
+            }
         }
         if (drifted.length > 0)
             return { ok: false, error: drifted.join("\n") };

package/dist/tools/file/edit-file.js

@@ -76,8 +76,12 @@ export const editFileTool = {
         // changed the file during the wait makes `updated` a splice of stale
         // content — refuse rather than overwrite what is there now (P1).
         const moved = await changedSince(abs, approvedState, input.path);
-        if (moved)
-            return { ok: false, error: moved };
+        if (moved) {
+            // Told to the model as the error, and recorded for the user (P2
+            // verification) — see write-file.ts.
+            ctx.verification?.record({ kind: "external-change", ...moved });
+            return { ok: false, error: moved.message };
+        }
         try {
             await fs.writeFile(abs, updated, "utf8");
             return { ok: true, output: `edited ${input.path}` };

package/dist/tools/file/snapshot.js

@@ -28,8 +28,9 @@ export async function snapshotFile(abs) {
 /**
  * Re-read `abs` and compare it with the state the approval was granted
  * against. Returns `null` when the file is exactly as it was, otherwise the
- * refusal to hand back as the tool's error — one sentence on what moved, and
- * the same next step every time: read it again and retry.
+ * refusal — its `message` is the tool's error (one sentence on what moved,
+ * and the same next step every time: read it again and retry), and its
+ * `path`/`what` are what the tool records so the user learns of it too.
  *
  * Call this AFTER approval and IMMEDIATELY before the write, with nothing
  * awaited in between — the point is to make the gap as small as the platform
@@ -58,6 +59,10 @@ export async function changedSince(abs, approved, rel) {
 }
 /** The one refusal shape: what moved, that nothing was written, what to do. */
 function refusal(rel, what) {
-    return (`${ErrorCode.FileChangedSinceRead}: ${rel} ${what}, so the approval no longer ` +
-        `covers this write; nothing was written — read the file again and retry`);
+    return {
+        path: rel,
+        what,
+        message: `${ErrorCode.FileChangedSinceRead}: ${rel} ${what}, so the approval no longer ` +
+            `covers this write; nothing was written — read the file again and retry`,
+    };
 }

package/dist/tools/file/write-file.js

@@ -65,8 +65,13 @@ export const writeFileTool = {
         // appeared during the wait; an overwrite approved against one version must
         // not land on another (P1).
         const moved = await changedSince(abs, approvedState, input.path);
-        if (moved)
-            return { ok: false, error: moved };
+        if (moved) {
+            // Told to the model as the error, and recorded for the user (P2
+            // verification): a file in their tree was written to by something else
+            // while they were being asked to approve a change to it.
+            ctx.verification?.record({ kind: "external-change", ...moved });
+            return { ok: false, error: moved.message };
+        }
         try {
             await fs.mkdir(path.dirname(abs), { recursive: true });
             await fs.writeFile(abs, input.content, "utf8");

package/dist/tools/registry.js

@@ -2,7 +2,7 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 import { listFilesTool } from "./list-files.js";
 import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
-import { runCommandTool } from "./shell/index.js";
+import { makeRunCommandTool, runCommandTool, } from "./shell/index.js";
 import { makeRunTestsTool, } from "../testing/run-tests-tool.js";
 import { searchCodebaseTool } from "./search-codebase.js";
 import { listSkillsTool } from "./list-skills.js";
@@ -54,20 +54,51 @@ function toInputSchema(schema) {
     delete json.$ref;
     return json;
 }
-/** Build the default registry with every built-in tool registered. */
+/**
+ * Build the default registry with every always-on built-in registered.
+ *
+ * `tools` is the config block of the same name (P4). Its two keys —
+ * `fileEdit` and `shell` — were declared in the C.0 scaffold and, until P4,
+ * consumed by NOTHING: a user could set `tools.shell: false`, `cruxy config
+ * list` would show it, and `run_command` would register regardless. Deleting
+ * them was the other option and is ruled out by `initConfig`, which writes the
+ * full defaults into every generated config: the schema is `.strict()`, so a
+ * removed key would stop every `cruxy init`-generated config from loading on
+ * upgrade — a compat break for everyone, not the #296 kind that bites only
+ * whoever wrote the key. So the keys now mean what their names say:
+ *
+ *  - `fileEdit: false` withholds the three tools that write files through the
+ *    U.3 gate — `write_file`, `edit_file`, `apply_patch`. Reads stay.
+ *  - `shell: false` withholds the two that execute commands — `run_command`
+ *    and `run_tests` (the test runner is a shell command with a parser on it,
+ *    and "no shell" that still ran `pnpm test` would be a setting that lies).
+ *    `create_pull_request` runs git through its own approval and is not a
+ *    shell for the model; it stays.
+ *
+ * Both default to `true`, so a config that never mentions them — every config
+ * today — gets the same registry it always did. Omitted → both on.
+ */
 export function buildDefaultRegistry(opts = {}) {
+    const fileEdit = opts.tools?.fileEdit ?? true;
+    const shell = opts.tools?.shell ?? true;
     const registry = new ToolRegistry();
     registry.register(listFilesTool);
     registry.register(readFileTool);
-    registry.register(writeFileTool);
-    registry.register(editFileTool);
-    registry.register(applyPatchTool);
+    if (fileEdit) {
+        registry.register(writeFileTool);
+        registry.register(editFileTool);
+        registry.register(applyPatchTool);
+    }
     registry.register(globTool);
     registry.register(grepFilesTool);
     registry.register(gitStatusTool);
-    registry.register(runCommandTool);
-    // A fresh tool per registry — its iteration budget (C.13) is session-scoped.
-    registry.register(makeRunTestsTool(opts.onTestResult ? { onResult: opts.onTestResult } : {}));
+    if (shell) {
+        registry.register(opts.onCommandResult
+            ? makeRunCommandTool({ onResult: opts.onCommandResult })
+            : runCommandTool);
+        // A fresh tool per registry — its iteration budget (C.13) is session-scoped.
+        registry.register(makeRunTestsTool(opts.onTestResult ? { onResult: opts.onTestResult } : {}));
+    }
     registry.register(searchCodebaseTool);
     registry.register(listSkillsTool);
     registry.register(loadSkillTool);

package/dist/tools/schema-depth.js

@@ -1,10 +1,17 @@
 /**
- * The provider's tool-schema depth bound, and the counter that measures against
- * it. ONE home for both, because there are two consumers that must agree: the
- * CI gate on our own built-ins (`schema-depth.test.ts`) and the runtime bound on
- * third-party MCP schemas (`../mcp/bounds.ts`). A counter that disagreed with
- * the bound, or two copies of either drifting apart, would mean a schema that
- * passes here and dies on the wire.
+ * The gateway's three tool-schema bounds — depth, bytes, nodes — and the
+ * counters that measure against them. ONE home for all of it, because there
+ * are two consumers that must agree: the CI gate on our own built-ins
+ * (`schema-depth.test.ts`) and the runtime bound on third-party MCP schemas
+ * (`../mcp/bounds.ts`). A counter that disagreed with its bound, or two copies
+ * of either drifting apart, would mean a schema that passes here and dies on
+ * the wire.
+ *
+ * Until P4 only depth was mirrored. The gateway has always applied all three
+ * to every tool's `parameters` (cruxy-ai/api `internal/httpx/chat_tools.go`,
+ * `validateToolParameters`), from the same constants its structured-output
+ * validator uses, and a rejection names which one (`bound`: `bytes` | `depth`
+ * | `nodes`). Two of the three were caught by nothing here.
  */
 /**
  * Nesting depth of the JSON Schema we put on the wire, counted the way the
@@ -83,3 +90,69 @@ export function schemaDepth(node) {
  * `depth >= MAX_SCHEMA_DEPTH`.
  */
 export const MAX_SCHEMA_DEPTH = 8;
+/**
+ * The gateway's byte bound on ONE tool's `parameters`, as serialized on the
+ * wire. Mirrors `maxSchemaBytes` (128 KiB) in cruxy-ai/api
+ * `internal/httpx/structured.go`, applied per tool by `validateToolParameters`
+ * as `len(raw) > maxSchemaBytes` — so, unlike {@link MAX_SCHEMA_DEPTH}, this
+ * bound is INCLUSIVE: a schema is safe AT the limit and dies one byte past it.
+ *
+ * NOT OURS TO CHOOSE, same as depth: raising it here moves the failure from CI
+ * to every user's terminal, and a rejection carrying `bound: "bytes"` with a
+ * `limit` that disagrees with this number means THIS number is stale. If a
+ * schema cannot fit, the schema changes. Every built-in is two orders of
+ * magnitude under it today (the largest, `spawn_subagents`, is ~1.2 KB); the
+ * bound is here so that stays a fact CI checks rather than one someone
+ * remembers.
+ *
+ * The MCP path is covered twice over: `mcp.maxSchemaBytes` has a config
+ * ceiling of 64 KiB (`config/schema.ts`, #237), half this limit, and a test
+ * pins that the ceiling stays under the mirror — so no MCP schema that loads
+ * from config can reach the gateway's byte bound at all.
+ */
+export const MAX_SCHEMA_BYTES = 128 * 1024;
+/**
+ * The gateway's node bound on ONE tool's `parameters`: the number of
+ * containers (objects and arrays) in the schema. Mirrors `maxSchemaNodes`
+ * (400) in cruxy-ai/api `internal/httpx/structured.go`, applied per tool by
+ * `boundJSON` as `nodes > maxSchemaNodes` — INCLUSIVE, like bytes: safe at
+ * 400, dead at 401. {@link schemaNodes} counts exactly what `boundJSON`
+ * counts. Same provenance rule: a sanity ceiling that mirrors the gateway,
+ * never raised to make a schema fit. Flatten instead.
+ *
+ * Small and wide is the shape this catches that neither of the others does:
+ * a flat object with 400 string properties is 3 levels deep and a few KB, and
+ * the gateway refuses it.
+ */
+export const MAX_SCHEMA_NODES = 400;
+/**
+ * Container count of a JSON tree, counted the way the gateway's `boundJSON`
+ * counts it: every object and every array is one node, scalars are not. So
+ * `{}` is 1, `{a: {}}` is 2, `{a: [{}, {}]}` is 4. Iterative for the same
+ * reason {@link schemaDepth} is — the MCP path can hand this a hostile input.
+ */
+export function schemaNodes(node) {
+    const isContainer = (n) => Array.isArray(n) || (typeof n === "object" && n !== null);
+    if (!isContainer(node))
+        return 0;
+    let count = 0;
+    const pending = [node];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        count++;
+        const children = Array.isArray(current)
+            ? current
+            : Object.values(current);
+        for (const child of children)
+            if (isContainer(child))
+                pending.push(child);
+    }
+    return count;
+}
+/**
+ * Bytes of a schema as it goes on the wire: compact `JSON.stringify`, UTF-8 —
+ * which is what the SDK serializes and the gateway measures with `len(raw)`.
+ */
+export function schemaBytes(node) {
+    return Buffer.byteLength(JSON.stringify(node) ?? "", "utf8");
+}