loopforge 3.7.1 → 3.8.2

package/dist/mcp/tools.js

@@ -5,10 +5,10 @@
  * status is the unified inspection tool (view=session|loop|all|audit).
  * Each handler receives SessionManager + parsed input, returns the output object.
  */
-import { buildSelfEvaluation } from "../engine.js";
-import { parseSubGoalUpdates, validateCoreSelfEvaluation, validateSubGoalUpdatesShape, } from "../self-eval.js";
+import { validateCoreSelfEvaluation } from "../self-eval.js";
 import { isRecord } from "../token-utils.js";
 import { getPolicy, validateLoopId } from "../policy.js";
+import { deriveEvidenceCapability } from "../evidence-provider.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // Tool schemas (MCP JSON Schema format)
 // ═══════════════════════════════════════════════════════════════════════════
@@ -104,7 +104,7 @@ const TOOL_BASE_SCHEMAS = [
                             description: "Optional. Sub-problems that surfaced during execution. The only " +
                                 "sub-goal creation channel — sg-XXXXXXXX ID literals are rejected here.",
                         },
-                        execution_evidence: {
+                        execution_report: {
                             type: "object",
                             description: "Optional. Structured record of what actually happened this round.",
                             properties: {
@@ -113,7 +113,7 @@ const TOOL_BASE_SCHEMAS = [
                                     items: { type: "string" },
                                     description: "Files modified this round.",
                                 },
-                                test_results: {
+                                tests_reported: {
                                     type: "object",
                                     description: "Test results from this round.",
                                     properties: {
@@ -122,15 +122,31 @@ const TOOL_BASE_SCHEMAS = [
                                         skipped: { type: "integer", minimum: 0, description: "Number of skipped tests." },
                                     },
                                 },
-                                success_criteria_met: {
+                                criterion_claims: {
                                     type: "array",
-                                    items: { type: "string" },
-                                    description: "Success criteria satisfied this round.",
+                                    description: "v3.8: advisory claims about objective criteria. LENIENT — unknown or malformed ids are dropped with a warning, never a rejection.",
+                                    items: {
+                                        type: "object",
+                                        properties: {
+                                            criterion_id: { type: "string", description: "cr-XXXXXXXX criterion id (free text allowed)." },
+                                            outcome: { type: "string", enum: ["met", "remaining"] },
+                                        },
+                                        required: ["criterion_id", "outcome"],
+                                        additionalProperties: false,
+                                    },
                                 },
-                                success_criteria_remaining: {
+                                contract_item_claims: {
                                     type: "array",
-                                    items: { type: "string" },
-                                    description: "Success criteria still outstanding.",
+                                    description: "Claims about items of the ACTIVE contract, cited by the rci-XXXXXXXX id the prompt rendered. LENIENT at declaration: an unknown/malformed id is reported as contract_invalid so you can correct the payload and resubmit the same roundId. A claim never verifies anything by itself — the runtime only marks an item verified when its bound commands are observed passing.",
+                                    items: {
+                                        type: "object",
+                                        properties: {
+                                            item_id: { type: "string", description: "rci-XXXXXXXX id of an item of the ACTIVE contract." },
+                                            outcome: { type: "string", enum: ["met", "remaining"], description: "Your claim for that item this round." },
+                                        },
+                                        required: ["item_id", "outcome"],
+                                        additionalProperties: false,
+                                    },
                                 },
                                 progress_estimate: {
                                     type: "number",
@@ -194,10 +210,6 @@ const TOOL_BASE_SCHEMAS = [
                             type: "string",
                             description: "Optional. Human-readable label for this checkpoint (e.g. 'core-functions-complete'). Only meaningful when compression_checkpoint is true.",
                         },
-                        next_action: {
-                            type: "string",
-                            description: "Optional. What the agent plans to do in the next round. Helps LoopForge detect task drift early by comparing declared intent with actual work.",
-                        },
                         subgoal_updates: {
                             type: "array",
                             maxItems: 20,
@@ -265,10 +277,6 @@ const TOOL_BASE_SCHEMAS = [
                             },
                             description: "Optional. Claims that a PRIOR round satisfied a criterion. The runtime verifies them against the prior round's git evidence. Max 20 entries.",
                         },
-                        drift_clarification: {
-                            type: "string",
-                            description: "Optional. Explain why this round's actions diverged from your previous round's next_action. Only required when the previous round was flagged for intent_drift or subgoal_drift. Mention concrete anchors: sub-goal IDs (sg-XXXXXXXX), constraint IDs (c-XXXXXXXX), criterion IDs (cr-XXXXXXXX), or file paths.",
-                        },
                         prompt_requests: {
                             type: "object",
                             description: "Optional. Information needs for the next round's prompt. Use when you know what context you'll need to succeed in the next round.",
@@ -276,7 +284,7 @@ const TOOL_BASE_SCHEMAS = [
                                 emphasize: {
                                     type: "array",
                                     items: { type: "string" },
-                                    description: "Constraints, discoveries, or decisions that need emphasis in the next prompt. Matched by meaning — not exact text. Matched items appear in a 'Critical Context' section. Max 5 entries. Pure reordering — no token overhead.",
+                                    description: "Constraints, discoveries, or decisions that need emphasis in the next prompt. Each entry is matched against active state items by STABLE ID (c-/cr-/sg-XXXXXXXX) or by exact text after normalization — a paraphrase matches nothing and renders nothing. Matched items appear in a 'Critical Context' section. Max 5 entries. Pure reordering — no token overhead.",
                                 },
                                 confusion_points: {
                                     type: "array",
@@ -287,29 +295,49 @@ const TOOL_BASE_SCHEMAS = [
                         },
                         round_contract: {
                             type: "object",
-                            description: "Optional. Proposal for the NEXT round's contract (v3.4). Declared here, it becomes the ACTIVE contract (rendered as the Current Task) only after this round commits, and stays active until a later round lists every done_when item in success_criteria_met or reports outcome=blocked. While it is active, restate it unchanged here; on completion or block, declare the next contract instead (or omit the field — the Current Task reverts to the original task). Checks: round_underspecified / round_unverifiable target this proposal; round_scope_drift and premature_boundary target the ACTIVE contract.",
+                            description: "Optional. Proposal for the NEXT round's contract (v3.8 item model). Declared here, it becomes the ACTIVE contract (rendered as the Current Task) only after this round commits. It closes when EVERY item is machine-verified (its bound commands observed passing, untampered, with the declared config), or when a round reports outcome=blocked. While it is open, restate it unchanged here — a different proposal is ignored. DECLARATION IS STRICT: an item with no bound command, one naming an unknown/disabled/non-after-capable command, a scope entry leaving the workspace, a malformed reference, or a count over the declared limits returns contract_invalid and the round may be retried with the same roundId.",
                             properties: {
                                 work_item: {
                                     type: "string",
                                     description: "Optional. Round focus, one line. Rendered as the active contract's Current Task first line. Max 200 chars.",
                                 },
-                                done_when: {
-                                    type: "array",
-                                    items: { type: "string" },
-                                    description: "Completion conditions: cr-XXXXXXXX criterion IDs or free text. Satisfied = list in success_criteria_met; still open = list in success_criteria_remaining. Max 20 items.",
-                                },
-                                verification_plan: {
+                                items: {
                                     type: "array",
-                                    items: { type: "string" },
-                                    description: "Names of configured, enabled evidence.commands (see loop_policy.json evidence.commands) that verify the done_when claims. Max 20 items.",
+                                    description: "Required, at least one (max 20). Each item is a verification unit bound to evidence commands. The runtime derives a stable rci-XXXXXXXX id per item and renders it in the prompt — cite that id in execution_report.contract_item_claims.",
+                                    items: {
+                                        type: "object",
+                                        properties: {
+                                            description: {
+                                                type: "string",
+                                                description: "What must be true for this item. Max 200 chars.",
+                                            },
+                                            criterion_refs: {
+                                                type: "array",
+                                                items: { type: "string" },
+                                                description: "Optional. cr-XXXXXXXX criterion ids this item is evidence for (free text allowed). Max 20.",
+                                            },
+                                            subgoal_refs: {
+                                                type: "array",
+                                                items: { type: "string" },
+                                                description: "Optional. sg-XXXXXXXX sub-goals THIS ITEM is evidence for. Must name sub-goals that exist (or that this same submission creates via emerged_subtasks). Max 20 ids. A machine-verified item produces the derived verified-subgoal fact for exactly the ids it names here.",
+                                            },
+                                            verify_with: {
+                                                type: "array",
+                                                items: { type: "string" },
+                                                description: "Required, at least one. Names of configured, enabled, after-capable evidence.commands (loop_policy.json) that verify this item. Unknown or disabled names are rejected.",
+                                            },
+                                        },
+                                        required: ["description", "verify_with"],
+                                        additionalProperties: false,
+                                    },
                                 },
                                 scope: {
                                     type: "array",
                                     items: { type: "string" },
-                                    description: "Files/directories this round may touch (workspace-relative; './' and trailing slashes accepted). Out-of-scope git changes trigger round_scope_drift. Max 50 items.",
+                                    description: "Files/directories this round may touch (workspace-relative; './' and trailing slashes accepted; must stay inside the workspace). Out-of-scope git changes trigger round_scope_drift, which is a machine fact and is not waivable by explanation. Max 50 items.",
                                 },
                             },
-                            required: ["done_when", "verification_plan", "scope"],
+                            required: ["items", "scope"],
                         },
                     },
                 },
@@ -333,8 +361,12 @@ const TOOL_BASE_SCHEMAS = [
                 },
                 view: {
                     type: "string",
-                    enum: ["session", "loop", "all", "audit"],
-                    description: "Which view to return. Defaults to session.",
+                    enum: ["session", "loop", "all", "audit", "explain"],
+                    description: "Which view to return. Defaults to session. explain (v3.8) is the read-only per-round \"why\" view over committed facts.",
+                },
+                round: {
+                    type: "number",
+                    description: "view=explain only: return that single round's \"why\" view. Omit for the whole timeline.",
                 },
             },
             required: [],
@@ -493,7 +525,8 @@ const TOOL_BASE_SCHEMAS = [
 const ADVANCE_OUTPUT_SCHEMA = {
     type: "object",
     properties: {
-        error: { type: "string" },
+        ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
+        error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
         details: { type: "object", additionalProperties: true },
         sessionId: { type: "string" },
         round: { type: "number" },
@@ -525,7 +558,8 @@ export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_status: {
         type: "object",
         properties: {
-            error: { type: "string" },
+            ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
             sessionId: { type: "string" },
             loopId: { type: "string" },
             round: { type: "number" },
@@ -545,7 +579,8 @@ export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_stop: {
         type: "object",
         properties: {
-            error: { type: "string" },
+            ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
             success: { type: "boolean" },
             roundsCompleted: { type: "number" },
             successTrajectory: { type: "array", items: { type: "boolean" } },
@@ -555,7 +590,8 @@ export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_pause: {
         type: "object",
         properties: {
-            error: { type: "string" },
+            ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
             sessionId: { type: "string" },
             round: { type: "number" },
             status: { type: "string" },
@@ -565,7 +601,8 @@ export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_replay: {
         type: "object",
         properties: {
-            error: { type: "string" },
+            ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
             sessionId: { type: "string" },
             loopId: { type: "string" },
             timeline: { type: "array", items: { type: "object", additionalProperties: true } },
@@ -575,7 +612,8 @@ export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_gate_check: {
         type: "object",
         properties: {
-            error: { type: "string" },
+            ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
             sessionId: { type: "string" },
             gateId: { type: "string" },
             risk: { type: "string", enum: ["low", "high", "unknown"] },
@@ -591,7 +629,8 @@ export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_gate_resolve: {
         type: "object",
         properties: {
-            error: { type: "string" },
+            ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
             sessionId: { type: "string" },
             loopId: { type: "string" },
             gateId: { type: "string" },
@@ -772,6 +811,16 @@ export function validateToolOutput(name, output) {
         return;
     validateSchema(output, schema, `output.${name}`);
 }
+/** v3.8: capability warnings for the current policy, merged with the compile's
+ *  own warnings. Derived through the SAME function `RoundDriver.prepare()`
+ *  uses, so the start/resume banner and the prepared round cannot tell two
+ *  different stories about what the runtime can observe. Never persisted. */
+function capabilityWarningList(existing) {
+    return [...new Set([
+            ...(existing ?? []),
+            ...deriveEvidenceCapability(getPolicy()).warnings,
+        ])];
+}
 export const TOOL_HANDLERS = {
     async loopforge_start(mgr, input) {
         const startInput = {
@@ -785,7 +834,10 @@ export const TOOL_HANDLERS = {
                 : undefined,
         };
         if (!startInput.task.trim()) {
-            return { error: "task is required and must be non-empty" };
+            return {
+                error: "invalid_argument",
+                errorMessage: "task is required and must be non-empty",
+            };
         }
         // v2.14: entry-point validation — a bad maxRounds previously passed
         // through and stopped the loop on the first round; an invalid loopId
@@ -793,92 +845,86 @@ export const TOOL_HANDLERS = {
         // argument error.
         if (startInput.maxRounds !== undefined &&
             (!Number.isInteger(startInput.maxRounds) || startInput.maxRounds < 1)) {
-            return { error: "maxRounds must be a positive integer" };
+            return {
+                error: "invalid_argument",
+                errorMessage: "maxRounds must be a positive integer",
+            };
         }
         if (startInput.loopId !== undefined) {
             try {
                 validateLoopId(startInput.loopId);
             }
             catch (error) {
-                return { error: `invalid loopId: ${error.message}` };
+                return {
+                    error: "invalid_argument",
+                    errorMessage: `invalid loopId: ${error.message}`,
+                };
             }
         }
-        const result = await mgr.create(startInput);
+        // A malformed loop_policy.json is a configuration defect, not a bad
+        // argument — it must not escape as an opaque JSON-RPC internal error.
+        let result;
+        try {
+            result = await mgr.create(startInput);
+        }
+        catch (error) {
+            return {
+                error: "policy_invalid",
+                errorMessage: `the runtime policy could not be loaded: ${error.message}`,
+            };
+        }
         // v2.14: a same-process duplicate loopId surfaces as a clean argument
         // error instead of a prompt-less "success" the client cannot act on.
         if (typeof result.stopReason === "string" &&
             result.stopReason.startsWith("loop_already_running:")) {
-            return { error: result.stopDetail ?? "loop already running" };
+            return {
+                error: "loop_already_running",
+                errorMessage: result.stopDetail ?? "loop already running",
+            };
         }
-        return { ...result };
+        // v3.8: the static capability warning — a loop with no provider or no
+        // enabled command can still run; its success claims are recorded as
+        // insufficient instead of verified, and the agent is told so up front.
+        const capabilityWarnings = capabilityWarningList(result.warnings);
+        return capabilityWarnings.length > 0
+            ? { ...result, warnings: capabilityWarnings }
+            : { ...result };
     },
     async loopforge_next(mgr, input) {
         const sessionId = String(input.sessionId ?? "");
         const output = String(input.output ?? "");
         const rawEval = input.evaluation;
         const roundId = input.roundId === undefined ? undefined : String(input.roundId);
-        if (!sessionId)
-            return { error: "sessionId is required" };
+        if (!sessionId) {
+            return { error: "invalid_argument", errorMessage: "sessionId is required" };
+        }
         // v3.0.1: every submission is anchored to the round it reports on. A
         // missing roundId would silently re-process a stale submission against a
         // later round — reject it here so the contract is enforced even when the
         // handler is invoked directly (bypassing schema validation).
         if (!roundId || !roundId.trim()) {
-            return { error: "roundId is required — pass the roundId from the most recent loopforge_start / loopforge_next / loopforge_resume / loopforge_status response" };
-        }
-        if (!rawEval || typeof rawEval !== "object" || Array.isArray(rawEval)) {
             return {
-                error: "evaluation_invalid",
-                details: {
-                    missing: ["evaluation"],
-                    invalid: [{ field: "evaluation", expected: "object" }],
-                },
-                sessionId,
-                roundId,
+                error: "round_id_required",
+                errorMessage: "roundId is required — pass the roundId from the most recent " +
+                    "loopforge_start / loopforge_next / loopforge_resume / loopforge_status response",
             };
         }
-        const validation = validateCoreSelfEvaluation(rawEval);
-        if (validation.missing.length > 0 || validation.invalid.length > 0) {
+        // v3.8.1: the submission boundary belongs to the RUNTIME, not to this
+        // transport. `mgr.advance` applies all of it — object shape, core fields,
+        // subgoal_updates structure and references, and the strict Round Contract
+        // declaration/claims boundary — before touching any state, and reports a
+        // refusal through `submissionError`. This handler only maps that onto the
+        // tool envelope, so a non-MCP caller gets exactly the same strictness.
+        const result = await mgr.advance(sessionId, output, rawEval, roundId);
+        if (result.submissionError) {
             return {
-                error: "evaluation_invalid",
-                details: validation,
+                error: result.submissionError.code,
+                errorMessage: result.stopDetail ?? "the submission was rejected",
+                details: result.submissionError.details,
                 sessionId,
                 roundId,
             };
         }
-        // v3.7.1: subgoal_updates is a strict structural boundary. Shape errors
-        // (bad entries, sg- literals in the creation channel) and referential
-        // errors (unknown / terminal / illegal transitions, checked against the
-        // compiled sub-goal set) return evaluation_invalid BEFORE advance — no
-        // state change, no gates, no rejection counters; retry same roundId.
-        const subgoalErrors = validateSubGoalUpdatesShape(rawEval);
-        if (subgoalErrors.length > 0) {
-            return {
-                error: "evaluation_invalid",
-                details: { missing: [], invalid: [], subgoal_errors: subgoalErrors },
-                sessionId,
-                roundId,
-            };
-        }
-        const updates = parseSubGoalUpdates(rawEval.subgoal_updates);
-        if (updates.length > 0) {
-            const emerged = Array.isArray(rawEval.emerged_subtasks)
-                ? rawEval.emerged_subtasks
-                    .filter((v) => typeof v === "string")
-                    .map((s) => s.slice(0, 500))
-                : [];
-            const referentialErrors = mgr.preflightSubGoalUpdates(sessionId, roundId, updates, emerged);
-            if (referentialErrors.length > 0) {
-                return {
-                    error: "evaluation_invalid",
-                    details: { missing: [], invalid: [], subgoal_errors: referentialErrors },
-                    sessionId,
-                    roundId,
-                };
-            }
-        }
-        const preExtractedEval = buildSelfEvaluation(rawEval);
-        const result = await mgr.advance(sessionId, output, preExtractedEval, roundId);
         // v2.12: Typed projection — runtime facts for the main agent, attached
         // on every accepted/continued round (not on errors).
         let projection = null;
@@ -889,7 +935,8 @@ export const TOOL_HANDLERS = {
         return projection ? { ...result, projection } : { ...result };
     },
     async loopforge_status(mgr, input) {
-        const view = input.view === "loop" || input.view === "all" || input.view === "audit"
+        const view = input.view === "loop" || input.view === "all" ||
+            input.view === "audit" || input.view === "explain"
             ? input.view
             : "session";
         const sessionId = String(input.sessionId ?? "");
@@ -900,25 +947,55 @@ export const TOOL_HANDLERS = {
         }
         // v2.12: view=audit — read-only verification audit.
         if (view === "audit") {
-            if (!loopId)
-                return { error: "loopId is required for view=audit" };
+            if (!loopId) {
+                return { error: "invalid_argument", errorMessage: "loopId is required for view=audit" };
+            }
             const audit = mgr.getAudit(loopId);
-            if (!audit)
-                return { error: `no audit data found for loop "${loopId}"` };
+            if (!audit) {
+                return {
+                    error: "state_unavailable",
+                    errorMessage: `no audit data found for loop "${loopId}"`,
+                    sessionId,
+                };
+            }
             return audit;
         }
+        // v3.8: view=explain — the read-only per-round "why" view.
+        if (view === "explain") {
+            if (!loopId) {
+                return { error: "invalid_argument", errorMessage: "loopId is required for view=explain" };
+            }
+            const roundValue = input.round;
+            const round = typeof roundValue === "number" && Number.isInteger(roundValue) && roundValue >= 1
+                ? roundValue
+                : undefined;
+            return mgr.getExplain(loopId, round);
+        }
         // v2.12: view=loop — loop health (formerly loopforge_health).
         if (view === "loop") {
-            if (!loopId)
-                return { error: "loopId is required for view=loop" };
+            if (!loopId) {
+                return { error: "invalid_argument", errorMessage: "loopId is required for view=loop" };
+            }
             const health = mgr.getHealth(loopId);
-            return health ?? { error: `no health data for loop "${loopId}"` };
+            return health ?? {
+                error: "state_unavailable",
+                errorMessage: `no health data for loop "${loopId}"`,
+            };
+        }
+        if (!sessionId) {
+            return {
+                error: "invalid_argument",
+                errorMessage: "sessionId is required for view=session",
+            };
         }
-        if (!sessionId)
-            return { error: "sessionId is required for view=session" };
         const session = mgr.get(sessionId);
-        if (!session)
-            return { error: `session not found: ${sessionId}` };
+        if (!session) {
+            return {
+                error: "session_not_found",
+                errorMessage: `session not found: ${sessionId} (process restarted?) — pass loopId for view=audit/loop, or loopforge_resume`,
+                sessionId,
+            };
+        }
         const metrics = session.engine.getMetrics();
         return {
             sessionId: session.sessionId,
@@ -933,6 +1010,11 @@ export const TOOL_HANDLERS = {
             // verification gates derive the same value from the same committed
             // evals via the shared round-contract walker).
             activeContract: mgr.getActiveContract(sessionId),
+            // v3.8: the ONE capability fact — the static half the compile hashes
+            // (what verification is possible) plus the live half rendered from the
+            // last baseline. `available` is provider-registry state: reported here
+            // and by `doctor`, never hashed.
+            capability: deriveEvidenceCapability(getPolicy(), session.evidenceBaseline ?? []),
             projection: mgr.getProjection(sessionId),
             metrics: {
                 vaultWriteErrors: metrics.vaultWriteErrors,
@@ -947,11 +1029,17 @@ export const TOOL_HANDLERS = {
     },
     async loopforge_stop(mgr, input) {
         const sessionId = String(input.sessionId ?? "");
-        if (!sessionId)
-            return { error: "sessionId is required" };
+        if (!sessionId) {
+            return { error: "invalid_argument", errorMessage: "sessionId is required" };
+        }
         const session = mgr.get(sessionId);
-        if (!session)
-            return { error: `session not found: ${sessionId}` };
+        if (!session) {
+            return {
+                error: "session_not_found",
+                errorMessage: `session not found: ${sessionId}`,
+                sessionId,
+            };
+        }
         const roundsCompleted = session.currentRound;
         const successTrajectory = [...session.successTrajectory];
         mgr.delete(sessionId);
@@ -959,8 +1047,9 @@ export const TOOL_HANDLERS = {
     },
     async loopforge_pause(mgr, input) {
         const sessionId = String(input.sessionId ?? "");
-        if (!sessionId)
-            return { error: "sessionId is required" };
+        if (!sessionId) {
+            return { error: "invalid_argument", errorMessage: "sessionId is required" };
+        }
         const result = mgr.pause(sessionId);
         return { ...result };
     },
@@ -968,7 +1057,11 @@ export const TOOL_HANDLERS = {
         const sessionId = String(input.sessionId ?? "");
         const loopId = String(input.loopId ?? "");
         if (!sessionId && !loopId) {
-            return { error: "sessionId or loopId is required — pass loopId to replay a loop after a restart (no live session)" };
+            return {
+                error: "invalid_argument",
+                errorMessage: "sessionId or loopId is required — pass loopId to replay a loop " +
+                    "after a restart (no live session)",
+            };
         }
         // Live session first: it disambiguates re-used loopIds and the session
         // registry is the cheapest lookup.
@@ -981,27 +1074,39 @@ export const TOOL_HANDLERS = {
             // v3.3.1: session not in memory (restart). Fall through to the vault
             // path when a loopId was also provided; otherwise say so plainly.
             if (!loopId) {
-                return { error: `session not found: ${sessionId} (process restarted?) — pass loopId to replay from the vault` };
+                return {
+                    error: "session_not_found",
+                    errorMessage: `session not found: ${sessionId} (process restarted?) — ` +
+                        "pass loopId to replay from the vault",
+                    sessionId,
+                };
             }
         }
         // Vault-direct replay — the timeline lives in the committed round
         // documents, not in the session registry.
         const timeline = mgr.replayByLoop(loopId);
         if (!timeline) {
-            return { error: `no committed rounds found for loop "${loopId}"` };
+            return {
+                error: "state_unavailable",
+                errorMessage: `no committed rounds found for loop "${loopId}"`,
+            };
         }
         // sessionId omitted on the vault path (its output schema is string-only).
         return { ...(sessionId ? { sessionId } : {}), loopId, timeline };
     },
     async loopforge_resume(mgr, input) {
         const loopId = String(input.loopId ?? "");
-        if (!loopId)
-            return { error: "loopId is required" };
+        if (!loopId) {
+            return { error: "invalid_argument", errorMessage: "loopId is required" };
+        }
         try {
             validateLoopId(loopId);
         }
         catch (error) {
-            return { error: `invalid loopId: ${error.message}` };
+            return {
+                error: "invalid_argument",
+                errorMessage: `invalid loopId: ${error.message}`,
+            };
         }
         // Paused recovery must run first so the persisted status is atomically
         // changed back to running before a prompt is returned.
@@ -1009,8 +1114,12 @@ export const TOOL_HANDLERS = {
         if (!result) {
             result = await mgr.resume(loopId);
         }
-        if (!result)
-            return { error: `no saved session found for loop "${loopId}"` };
+        if (!result) {
+            return {
+                error: "state_unavailable",
+                errorMessage: `no saved session found for loop "${loopId}"`,
+            };
+        }
         return { ...result };
     },
     async loopforge_gate_check(mgr, input) {
@@ -1020,12 +1129,19 @@ export const TOOL_HANDLERS = {
         const sessionId = String(input.sessionId ?? "");
         const roundId = String(input.roundId ?? "");
         const action = input.action;
-        if (!sessionId)
-            return { error: "sessionId is required" };
-        if (!roundId)
-            return { error: "roundId is required — pass the roundId from the latest response" };
-        if (!action || !isRecord(action))
-            return { error: "action is required" };
+        if (!sessionId) {
+            return { error: "invalid_argument", errorMessage: "sessionId is required" };
+        }
+        if (!roundId) {
+            return {
+                error: "round_id_required",
+                errorMessage: "roundId is required — pass the roundId from the latest response",
+                sessionId,
+            };
+        }
+        if (!action || !isRecord(action)) {
+            return { error: "invalid_argument", errorMessage: "action is required", sessionId, roundId };
+        }
         const descriptor = {
             description: String(action.description ?? ""),
             scope: Array.isArray(action.scope)
@@ -1033,7 +1149,7 @@ export const TOOL_HANDLERS = {
                 : [],
             effects: Array.isArray(action.effects)
                 ? action.effects.filter((v) => typeof v === "string")
-                    .filter((v) => true)
+                    .filter((_v) => true)
                 : [],
             reversibility: (["reversible", "recoverable", "irreversible", "unknown"]
                 .includes(String(action.reversibility))
@@ -1045,7 +1161,12 @@ export const TOOL_HANDLERS = {
                 : "unknown"),
         };
         if (!descriptor.description.trim()) {
-            return { error: "action.description is required" };
+            return {
+                error: "invalid_argument",
+                errorMessage: "action.description is required",
+                sessionId,
+                roundId,
+            };
         }
         return mgr.checkGate(sessionId, roundId, descriptor);
     },