loopforge 3.0.0 → 3.2.1

package/dist/mcp/tools.js

@@ -1,106 +1,17 @@
 /** LoopForge MCP — Tool definitions and handlers.
  *
- * Public tools for round execution, recovery, gates, and audit.
+ * 9 tools: start, next, status, stop, pause, resume, replay,
+ *          gate_check, gate_resolve.
+ * 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 { collectSelfEvalGaps } from "../self-eval.js";
 import { isRecord } from "../token-utils.js";
-import { parseRoundReport } from "../round-report.js";
-import { getPolicy } from "../policy.js";
+import { validateLoopId } from "../policy.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // Tool schemas (MCP JSON Schema format)
 // ═══════════════════════════════════════════════════════════════════════════
-const GATE_ACTION_SCHEMA = {
-    type: "object",
-    properties: {
-        description: { type: "string" },
-        scope: { type: "array", items: { type: "string" } },
-        effects: { type: "array", items: { type: "string", enum: ["workspace_write", "production", "credentials", "data_migration", "public_api", "publish", "payment", "external_communication", "network"] } },
-        reversibility: { type: "string", enum: ["reversible", "recoverable", "irreversible", "unknown"] },
-        authorization: { type: "string", enum: ["agent_allowed", "user_required", "unknown"] },
-    },
-    required: ["description", "scope", "effects", "reversibility", "authorization"],
-};
-const ROUND_REPORT_SCHEMA = {
-    type: "object",
-    required: ["format", "outcome", "continuation", "summary", "violations"],
-    properties: {
-        format: { type: "string", const: "loopforge.round-report" },
-        outcome: { type: "string", enum: ["success", "partial", "failed", "blocked"] },
-        continuation: { type: "string", enum: ["continue", "stop"] },
-        summary: { type: "string" },
-        violations: { type: "array", items: { type: "string" } },
-        agentIntent: { type: "string" },
-        driftClarification: {
-            type: "object",
-            properties: {
-                explanation: { type: "string", minLength: 1, maxLength: 2000 },
-                anchors: { type: "array", maxItems: 8, items: { type: "string", maxLength: 240 } },
-            },
-            required: ["explanation", "anchors"],
-        },
-        evidence: {
-            type: "object",
-            properties: {
-                files: { type: "array", items: { type: "string" } },
-                checks: { type: "array", items: { type: "object", properties: {
-                            name: { type: "string" }, status: { type: "string", enum: ["passed", "failed", "not_run"] },
-                            summary: { type: "string" }, counts: { type: "object", properties: {
-                                    passed: { type: "integer", minimum: 0 }, failed: { type: "integer", minimum: 0 }, skipped: { type: "integer", minimum: 0 },
-                                } },
-                        }, required: ["name", "status"] } },
-                claims: { type: "array", items: { type: "object", properties: {
-                            id: { type: "string", pattern: "^claim-[a-f0-9]{12}$" }, targetId: { type: "string" }, evidenceRefs: { type: "array", items: { type: "string" } },
-                        }, required: ["id", "targetId", "evidenceRefs"] } },
-                provenance: {
-                    type: "object",
-                    description: "Runtime-owned evidence provenance keyed by evidence reference.",
-                    additionalProperties: {
-                        type: "object",
-                        properties: {
-                            source: { type: "string", enum: ["agent", "command", "provider", "verification"] },
-                            observedAt: { type: "string" },
-                            status: { type: "string", enum: ["verified", "claimed", "contradicted", "unavailable"] },
-                            detail: { type: "string" },
-                        },
-                        required: ["source", "observedAt", "status"],
-                    },
-                },
-                noChangeReason: { type: "string" },
-            },
-        },
-        blocker: { type: "object", properties: {
-                kind: { type: "string", enum: ["dependency", "external", "needs_human_input", "agent"] },
-                reason: { type: "string" }, references: { type: "array", items: { type: "string" } },
-                action: GATE_ACTION_SCHEMA,
-            }, required: ["kind", "reason"] },
-        discoveries: { type: "object", properties: {
-                wrongAssumptions: { type: "array", items: { type: "string" } },
-                emergedWork: { type: "array", items: { type: "string" } },
-                facts: { type: "array", items: { type: "string" } },
-                newConstraints: { type: "array", items: { type: "string" } },
-            } },
-        subGoalEvents: { type: "object", properties: {
-                completed: { type: "array", items: { type: "string" } },
-                blocked: { type: "array", items: { type: "string" } },
-                canceled: { type: "array", items: { type: "string" } },
-            } },
-        constraintEvents: { type: "object", properties: {
-                retired: { type: "array", items: { type: "string" } },
-            } },
-        criterionRevisions: { type: "array", items: { type: "object", properties: {
-                    old: { type: "string" }, new: { type: "string" },
-                }, required: ["old", "new"] } },
-        objectiveRefinement: { type: "string" },
-        phaseBoundaryProposal: { type: "object", properties: {
-                label: { type: "string" }, reason: { type: "string" },
-            }, required: ["label", "reason"] },
-        contextRequest: { type: "object", properties: {
-                emphasize: { type: "array", items: { type: "string" } },
-                expand: { type: "array", items: { type: "string" } },
-                confusion_points: { type: "array", items: { type: "string" } },
-            } },
-    },
-};
 const TOOL_BASE_SCHEMAS = [
     {
         name: "loopforge_start",
@@ -117,10 +28,9 @@ const TOOL_BASE_SCHEMAS = [
                     description: "Optional loop ID. Generated automatically if not provided.",
                 },
                 maxRounds: {
-                    type: "number",
+                    type: "integer",
                     minimum: 1,
-                    multipleOf: 1,
-                    description: "Maximum rounds before auto-stop. Default: 100 from policy.",
+                    description: "Maximum rounds before auto-stop. Default: 20 from policy.",
                 },
                 domain: {
                     type: "string",
@@ -135,122 +45,301 @@ const TOOL_BASE_SCHEMAS = [
                     items: { type: "string" },
                     description: "Hard constraints to enforce across all rounds.",
                 },
-                successCriteria: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Explicit success criteria to verify across the loop.",
-                },
             },
             required: ["task"],
         },
     },
     {
         name: "loopforge_next",
-        description: "Submit the canonical round report for the current round and advance to the next. Returns the next-round prompt, or null with a stopReason when the loop ends.",
+        description: "Submit the output from the current round and advance to the next. Returns the next-round prompt, or null with a stopReason when the loop ends. The evaluation parameter provides structured self-assessment — prefer this over embedding a ---loopforge-eval block in the output text.",
         inputSchema: {
             type: "object",
-            additionalProperties: false,
             properties: {
                 sessionId: {
                     type: "string",
                     description: "Session ID returned by loopforge_start.",
                 },
-                report: {
-                    ...ROUND_REPORT_SCHEMA,
-                    description: "Canonical round report. This is the only execution report accepted by loopforge_next.",
+                roundId: {
+                    type: "string",
+                    description: "The roundId from the most recent loopforge_start / loopforge_next / loopforge_resume / loopforge_status response. Anchors this submission to the exact round it reports on: a submission whose roundId no longer matches the current round (the round already committed) is not processed — the current held prompt is returned instead, so lost responses can be recovered without skipping or double-committing a round.",
+                },
+                output: {
+                    type: "string",
+                    description: "Optional. The agent's full output from executing the current round's prompt. May be omitted if evaluation parameter is provided.",
+                },
+                evaluation: {
+                    type: "object",
+                    description: "Structured self-evaluation for this round. Either this or an output containing a ---loopforge-eval block is required for the loop to continue. Preferred over embedding ---loopforge-eval blocks in output text.",
+                    required: ["success", "output_summary", "should_continue", "constraint_violations"],
+                    properties: {
+                        success: {
+                            type: "boolean",
+                            description: "true ONLY if all hard constraints met AND the task goal achieved.",
+                        },
+                        output_summary: {
+                            type: "string",
+                            description: "Specific, actionable summary of what was DONE this round — not what was attempted.",
+                        },
+                        should_continue: {
+                            type: "boolean",
+                            description: "false ONLY when the ENTIRE task is complete. Partial progress = true.",
+                        },
+                        constraint_violations: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Constraints the agent actually violated this round. Be honest.",
+                        },
+                        discovered_constraints: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional. New constraints discovered this round.",
+                        },
+                        objective_refinement: {
+                            type: "string",
+                            description: "Optional. If this round deepened understanding of the task objective.",
+                        },
+                        emerged_subtasks: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional. Sub-problems that surfaced during execution.",
+                        },
+                        execution_evidence: {
+                            type: "object",
+                            description: "Optional. Structured record of what actually happened this round.",
+                            properties: {
+                                files_changed: {
+                                    type: "array",
+                                    items: { type: "string" },
+                                    description: "Files modified this round.",
+                                },
+                                test_results: {
+                                    type: "object",
+                                    description: "Test results from this round.",
+                                    properties: {
+                                        passed: { type: "integer", minimum: 0, description: "Number of passing tests." },
+                                        failed: { type: "integer", minimum: 0, description: "Number of failing tests." },
+                                        skipped: { type: "integer", minimum: 0, description: "Number of skipped tests." },
+                                    },
+                                },
+                                success_criteria_met: {
+                                    type: "array",
+                                    items: { type: "string" },
+                                    description: "Success criteria satisfied this round.",
+                                },
+                                success_criteria_remaining: {
+                                    type: "array",
+                                    items: { type: "string" },
+                                    description: "Success criteria still outstanding.",
+                                },
+                                progress_estimate: {
+                                    type: "number",
+                                    minimum: 0,
+                                    maximum: 1,
+                                    description: "Estimated progress toward task completion (0.0–1.0).",
+                                },
+                            },
+                        },
+                        retracted_constraints: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional. Constraints the agent now believes are wrong.",
+                        },
+                        revised_success_criteria: {
+                            type: "array",
+                            description: "Optional. Success criteria that need reformulation.",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    old: { type: "string", description: "Original criterion." },
+                                    new: { type: "string", description: "Revised criterion." },
+                                },
+                            },
+                        },
+                        wrong_assumptions: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional. Assumptions from earlier rounds that were incorrect.",
+                        },
+                        worker_results: {
+                            type: "array",
+                            description: "Optional. Results of sub-agent / Worker delegations this round.",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    agentId: { type: "string" },
+                                    subAgentType: { type: "string" },
+                                    subTask: { type: "string" },
+                                    resultSummary: { type: "string" },
+                                    success: { type: "boolean" },
+                                    outcome: {
+                                        type: "string",
+                                        enum: ["success", "partial", "failed"],
+                                        description: "Optional. Worker outcome; derived from success when absent.",
+                                    },
+                                    discoveredConstraints: {
+                                        type: "array",
+                                        items: { type: "string" },
+                                    },
+                                },
+                                required: ["agentId", "subAgentType", "subTask", "resultSummary", "success"],
+                            },
+                        },
+                        compression_checkpoint: {
+                            type: "boolean",
+                            description: "Optional. Set true at subtask boundaries to trigger a full-state checkpoint (L2 prompt) that survives rolling-window eviction. The checkpoint label is carried into future prompts.",
+                        },
+                        checkpoint_label: {
+                            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.",
+                        },
+                        completed_subtasks: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional. Sub-tasks completed this round. Matched to previously emerged sub-tasks by description similarity.",
+                        },
+                        blocked_subtasks: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional. Sub-tasks that are now blocked. Describe what is blocking and why.",
+                        },
+                        canceled_subtasks: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Optional. Sub-tasks no longer needed. Removes them from the active sub-goal list.",
+                        },
+                        stop_reason: {
+                            type: "string",
+                            enum: ["gave_up", "blocked", "needs_human_input"],
+                            description: "Optional. Why the agent is stopping. Only meaningful when should_continue=false and success=false. 'blocked' means work cannot proceed under current constraints.",
+                        },
+                        no_change_reason: {
+                            type: "string",
+                            description: "Optional. Declared reason for claiming success with no machine-verifiable evidence (e.g. documentation-only round). Downgrades the success_without_verified_evidence check from error to info. Max 200 chars.",
+                        },
+                        outcome: {
+                            type: "string",
+                            enum: ["success", "partial", "failed", "blocked"],
+                            description: "Optional. Tri-state outcome. When absent, derived from success (true→success, false→failed). 'partial' and 'blocked' must be declared explicitly. A declared non-success outcome suppresses the success-class checks even when success=true.",
+                        },
+                        blocker: {
+                            type: "string",
+                            description: "Optional. Flat blocker description, required only when outcome=blocked. Also feeds the user/agent gate classification. Max 500 chars.",
+                        },
+                        retroactiveClaims: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    round: { type: "integer", minimum: 1 },
+                                    claim: { type: "string" },
+                                },
+                                required: ["round", "claim"],
+                                additionalProperties: false,
+                            },
+                            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.",
+                            properties: {
+                                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.",
+                                },
+                                expand: {
+                                    type: "array",
+                                    items: {
+                                        type: "string",
+                                        enum: ["milestones", "sub_goals", "constraint_lifecycle", "agent_trust", "progress", "loop_synthesis"],
+                                    },
+                                    description: "Sections to expand to full detail in the next prompt. Useful when you need full context on a specific area (e.g. full sub-goal dashboard when replanning). L1 max 1 section. L2 already expanded — redundant. L0 ignored.",
+                                },
+                                confusion_points: {
+                                    type: "array",
+                                    items: { type: "string" },
+                                    description: "Things you're confused about. Rendered at the TOP of the next prompt before the objective. Max 3 entries, each ≤ 200 chars recommended. Be specific — 'I don't understand why milestone 3 is marked complete when phase 2 appears unfinished.'",
+                                },
+                            },
+                        },
+                    },
                 },
             },
-            required: ["sessionId", "report"],
+            // v3.2.1: evaluation is optional at the schema level — the handler
+            // requires EITHER the evaluation parameter OR output containing a
+            // ---loopforge-eval block. Requiring it here made the embedded-block
+            // path dead code (input validation rejected it before the handler).
+            required: ["sessionId", "roundId"],
         },
     },
     {
         name: "loopforge_status",
-        description: "Read session, loop health, or all persisted loops through one canonical status view.",
+        description: "Inspect loop state. view=session (default): session status, round identity, success trajectory and typed projection. view=loop: loop health (goal alignment, constraints, drift). view=all: summary of every persisted loop. view=audit: read-only end-of-loop verification audit (claims, gates, verdict, sequence integrity).",
         inputSchema: {
             type: "object",
             properties: {
-                scope: { type: "string", enum: ["session", "loop", "all"] },
                 sessionId: {
                     type: "string",
-                    description: "Session ID returned by loopforge_start.",
+                    description: "Session ID returned by loopforge_start (views session/audit).",
                 },
-                loopId: { type: "string" },
-                detail: { type: "string", enum: ["summary", "full"] },
-            },
-            required: ["scope"],
-        },
-    },
-    {
-        name: "loopforge_retry",
-        description: "Submit a corrected round report for the current rejected logical round. The round ID and pre-round evidence baseline remain unchanged.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: {
+                loopId: {
                     type: "string",
-                    description: "Session ID returned by loopforge_start.",
+                    description: "Loop ID (views loop/audit).",
                 },
-                report: {
-                    ...ROUND_REPORT_SCHEMA,
-                    description: "Corrected canonical report for the rejected attempt.",
+                view: {
+                    type: "string",
+                    enum: ["session", "loop", "all", "audit"],
+                    description: "Which view to return. Defaults to session.",
                 },
             },
-            required: ["sessionId", "report"],
+            required: [],
         },
     },
     {
-        name: "loopforge_backtrack",
-        description: "Move an active session to the round after its nearest clean restore point. Returns restore instructions but never changes workspace files.",
+        name: "loopforge_stop",
+        description: "Manually stop a loop session and return its final trajectory.",
         inputSchema: {
             type: "object",
             properties: {
                 sessionId: {
                     type: "string",
-                    description: "Session ID returned by loopforge_start.",
+                    description: "Session ID to stop.",
                 },
             },
             required: ["sessionId"],
         },
     },
     {
-        name: "loopforge_history",
-        description: "Read one persisted round or a deterministic event timeline.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                loopId: { type: "string" },
-                view: { type: "string", enum: ["round", "timeline"] },
-                round: { type: "integer", minimum: 1 },
-                fromSequence: { type: "integer", minimum: 1 },
-                toSequence: { type: "integer", minimum: 1 },
-                limit: { type: "integer", minimum: 1, maximum: 200 },
-            },
-            required: ["loopId", "view"],
-        },
-    },
-    {
-        name: "loopforge_stop",
-        description: "Manually stop a loop session and return its final trajectory.",
+        name: "loopforge_pause",
+        description: "Pause a running loop session. The loop suspends at the next round boundary and its state is persisted to vault. Paused loops can be resumed with loopforge_resume. Use this to interrupt a long-running loop without losing progress.",
         inputSchema: {
             type: "object",
             properties: {
                 sessionId: {
                     type: "string",
-                    description: "Session ID to stop.",
+                    description: "Session ID to pause.",
                 },
             },
             required: ["sessionId"],
         },
     },
     {
-        name: "loopforge_pause",
-        description: "Pause a running loop session. The loop suspends at the next round boundary and its state is persisted to vault. Paused loops can be resumed with loopforge_resume. Use this to interrupt a long-running loop without losing progress.",
+        name: "loopforge_replay",
+        description: "Replay a completed or running loop session as an auditable round timeline.",
         inputSchema: {
             type: "object",
             properties: {
                 sessionId: {
                     type: "string",
-                    description: "Session ID to pause.",
+                    description: "Session ID to replay.",
                 },
             },
             required: ["sessionId"],
@@ -272,37 +361,42 @@ const TOOL_BASE_SCHEMAS = [
     },
     {
         name: "loopforge_gate_check",
-        description: "Classify whether an action is an agent-resolvable gate or requires explicit user authority. Read-only.",
+        description: "v2.12: Classify a high-risk action or blocker text as a user gate (needs human authorization) or an agent gate (resolvable with evidence). Read-only — nothing is recorded. Use the returned gate id with loopforge_gate_resolve after a human decision.",
         inputSchema: {
             type: "object",
             properties: {
-                action: GATE_ACTION_SCHEMA,
+                gateText: {
+                    type: "string",
+                    description: "The action or blocker text to classify, e.g. 'Deploy to production'.",
+                },
             },
-            required: ["action"],
+            required: ["gateText"],
         },
     },
     {
         name: "loopforge_gate_resolve",
-        description: "Record an explicit user decision for a previously classified gate.",
+        description: "v2.12: Record a human decision for a previously opened user gate. The gate id embeds the action hash — if the action text changed, the approval expires automatically. Read-only for agent gates (they are resolved by submitting evidence).",
         inputSchema: {
             type: "object",
             properties: {
-                sessionId: { type: "string" },
-                gateId: { type: "string" },
-                action: GATE_ACTION_SCHEMA,
-                approved: { type: "boolean" },
-                note: { type: "string" },
+                sessionId: {
+                    type: "string",
+                    description: "Session ID whose loop owns the gate.",
+                },
+                gateId: {
+                    type: "string",
+                    description: "Gate id returned by loopforge_gate_check or recorded from a blocked round.",
+                },
+                approved: {
+                    type: "boolean",
+                    description: "Whether the human authorizes the action.",
+                },
+                note: {
+                    type: "string",
+                    description: "Optional human note recorded with the decision.",
+                },
             },
-            required: ["sessionId", "gateId", "action", "approved", "note"],
-        },
-    },
-    {
-        name: "loopforge_audit",
-        description: "Run a read-only final audit over accepted vault events, evidence claims, checks, and gate decisions.",
-        inputSchema: {
-            type: "object",
-            properties: { loopId: { type: "string" } },
-            required: ["loopId"],
+            required: ["sessionId", "gateId", "approved"],
         },
     },
 ];
@@ -314,29 +408,34 @@ const ADVANCE_OUTPUT_SCHEMA = {
         round: { type: "number" },
         roundId: { type: ["string", "null"] },
         prompt: { type: ["string", "null"] },
-        decision: { enum: ["accepted", "rejected", "backtracked", "stopped", "terminated", "errored"] },
-        attempt: { type: "number" },
-        stopReason: { type: "string" },
-        stopDetail: { type: "string", description: "Human-readable context for why the loop stopped. Provides facts without prescribing a specific agent action." },
-        level: { type: "string" },
-        roundSuccess: { type: "boolean" },
+        stopReason: { type: ["string", "null"] },
+        stopDetail: { type: ["string", "null"], description: "Human-readable context for why the loop stopped. Provides facts without prescribing a specific agent action." },
+        level: { type: ["string", "null"] },
+        roundSuccess: { type: ["boolean", "null"] },
         enforcementAction: { enum: ["accept", "reject", "terminate", "backtrack"] },
-        enforcementReason: { type: "string" },
-        projection: { type: "object", additionalProperties: true },
-        evidenceSummary: { type: "object", additionalProperties: true },
-        stateHash: { type: "string" },
-        promptHash: { type: "string" },
+        enforcementReason: { type: ["string", "null"] },
         warnings: { type: "array", items: { type: "string" } },
+        parseGaps: {
+            type: "array",
+            items: { type: "object", additionalProperties: true },
+            description: "v2.12: Field-level format diagnostics for tolerated evaluation issues.",
+        },
+        projection: {
+            type: "object",
+            additionalProperties: true,
+            description: "v2.12: Typed cognitive state projection (focus/todo/phase/delegation/handoff).",
+        },
     },
     additionalProperties: true,
 };
-const TOOL_OUTPUT_SCHEMAS = {
+/** Declared structured-output contracts for every tool. The MCP server
+ *  validates each handler's output against these before returning it —
+ *  a mismatch is a contract bug, surfaced as a JSON-RPC error instead of
+ *  silently shipping an output that violates the declared schema. */
+export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_start: ADVANCE_OUTPUT_SCHEMA,
     loopforge_next: ADVANCE_OUTPUT_SCHEMA,
-    loopforge_retry: ADVANCE_OUTPUT_SCHEMA,
-    loopforge_backtrack: ADVANCE_OUTPUT_SCHEMA,
     loopforge_resume: ADVANCE_OUTPUT_SCHEMA,
-    loopforge_history: { type: "object", additionalProperties: true },
     loopforge_status: {
         type: "object",
         properties: {
@@ -373,17 +472,47 @@ const TOOL_OUTPUT_SCHEMAS = {
         },
         additionalProperties: true,
     },
-    loopforge_gate_check: { type: "object", additionalProperties: true },
-    loopforge_gate_resolve: { type: "object", additionalProperties: true },
-    loopforge_audit: { type: "object", additionalProperties: true },
+    loopforge_replay: {
+        type: "object",
+        properties: {
+            error: { type: "string" },
+            sessionId: { type: "string" },
+            loopId: { type: "string" },
+            timeline: { type: "array", items: { type: "object", additionalProperties: true } },
+        },
+        additionalProperties: true,
+    },
+    loopforge_gate_check: {
+        type: "object",
+        properties: {
+            error: { type: "string" },
+            id: { type: "string" },
+            kind: { type: "string" },
+            question: { type: "string" },
+            blockedScope: { type: "array", items: { type: "string" } },
+            allowedWork: { type: "array", items: { type: "string" } },
+            problem: { type: "string" },
+            requiredEvidence: { type: "array", items: { type: "string" } },
+            suggestedResolution: { type: "string" },
+        },
+        additionalProperties: true,
+    },
+    loopforge_gate_resolve: {
+        type: "object",
+        properties: {
+            error: { type: "string" },
+            sessionId: { type: "string" },
+            loopId: { type: "string" },
+            gateId: { type: "string" },
+            approved: { type: "boolean" },
+        },
+        additionalProperties: true,
+    },
 };
 function closeObjectSchemas(schema) {
     const result = { ...schema };
     if (result.type === "object") {
-        // Preserve explicitly open maps such as EvidenceEnvelope.provenance.
-        // Fixed-shape objects remain closed by default.
-        if (!("additionalProperties" in result))
-            result.additionalProperties = false;
+        result.additionalProperties = false;
         if (isRecord(result.properties)) {
             result.properties = Object.fromEntries(Object.entries(result.properties).map(([key, value]) => [
                 key,
@@ -411,12 +540,28 @@ export class ToolInputValidationError extends Error {
         this.name = "ToolInputValidationError";
     }
 }
+function typeMatches(value, type) {
+    switch (type) {
+        case "object": return isRecord(value);
+        case "array": return Array.isArray(value);
+        case "string": return typeof value === "string";
+        case "boolean": return typeof value === "boolean";
+        case "number": return typeof value === "number" && Number.isFinite(value);
+        case "integer": return typeof value === "number" && Number.isInteger(value);
+        case "null": return value === null;
+        default: return true; // undeclared type — no constraint
+    }
+}
 function validateSchema(value, schema, path) {
-    const type = schema.type;
-    if (type === "object") {
-        if (!isRecord(value)) {
-            throw new ToolInputValidationError(`${path} must be an object`);
-        }
+    // v2.14: an explicitly-undefined optional field is the same as absent —
+    // output objects carry `key: undefined` after spreads of optional fields.
+    if (value === undefined)
+        return;
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((type) => typeMatches(value, type))) {
+        throw new ToolInputValidationError(`${path} must be ${types.join(" or ")}`);
+    }
+    if (types.some((type) => type === "object") && isRecord(value)) {
         const properties = isRecord(schema.properties) ? schema.properties : {};
         const required = Array.isArray(schema.required)
             ? schema.required.filter((item) => typeof item === "string")
@@ -440,34 +585,23 @@ function validateSchema(value, schema, path) {
         }
         return;
     }
-    if (type === "array") {
-        if (!Array.isArray(value)) {
-            throw new ToolInputValidationError(`${path} must be an array`);
-        }
+    if (types.some((type) => type === "array") && Array.isArray(value)) {
         if (isRecord(schema.items)) {
             value.forEach((item, index) => validateSchema(item, schema.items, `${path}[${index}]`));
         }
         return;
     }
-    if (type === "string" && typeof value !== "string") {
-        throw new ToolInputValidationError(`${path} must be a string`);
-    }
-    if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => candidate === value)) {
-        throw new ToolInputValidationError(`${path} must be one of ${schema.enum.join(", ")}`);
-    }
-    if (type === "string" && typeof value === "string" &&
-        typeof schema.pattern === "string" && !new RegExp(schema.pattern).test(value)) {
-        throw new ToolInputValidationError(`${path} must match ${schema.pattern}`);
-    }
-    if (type === "boolean" && typeof value !== "boolean") {
-        throw new ToolInputValidationError(`${path} must be a boolean`);
-    }
-    if (type === "number" || type === "integer") {
-        if (typeof value !== "number" ||
-            !Number.isFinite(value) ||
-            (type === "integer" && !Number.isInteger(value))) {
-            throw new ToolInputValidationError(`${path} must be ${type === "integer" ? "an integer" : "a number"}`);
+    if (types.some((type) => type === "string") && typeof value === "string") {
+        // Enforce declared enums — the schemas advertise them, so validation
+        // must too (v2.12: view/gateText enums were previously unchecked).
+        if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+            throw new ToolInputValidationError(`${path} must be one of: ${schema.enum.join(", ")}`);
         }
+        return;
+    }
+    if ((types.some((type) => type === "number") ||
+        types.some((type) => type === "integer")) &&
+        typeof value === "number") {
         if (typeof schema.minimum === "number" && value < schema.minimum) {
             throw new ToolInputValidationError(`${path} must be >= ${schema.minimum}`);
         }
@@ -482,54 +616,15 @@ export function validateToolInput(name, input) {
         throw new ToolInputValidationError(`Unknown tool: ${name}`);
     validateSchema(input, contract.inputSchema, "arguments");
 }
-function enrichAdvanceResult(mgr, result) {
-    const sessionId = typeof result.sessionId === "string" ? result.sessionId : "";
-    const session = sessionId ? mgr.get(sessionId) : undefined;
-    const projection = sessionId ? mgr.cognitiveProjection(sessionId) : null;
-    const audit = session ? mgr.audit(session.loopId) : null;
-    const enforcement = String(result.enforcementAction ?? "");
-    const stopReason = String(result.stopReason ?? "");
-    const decision = enforcement === "reject" ? "rejected"
-        : enforcement === "backtrack" ? "backtracked"
-            : enforcement === "terminate" ? "terminated"
-                : stopReason ? "stopped" : "accepted";
-    const artifact = session?.roundSnapshot?.promptArtifact;
-    const criteria = isRecord(audit?.criteria) ? audit.criteria : {};
-    const checks = isRecord(audit?.checks) ? audit.checks : {};
-    return {
-        ...result,
-        decision,
-        attempt: session?.roundSnapshot?.attempt ?? result.attempt,
-        projection: projection ? {
-            phase: Array.isArray(projection.phaseHistory)
-                ? projection.phaseHistory.at(-1)?.label ?? ""
-                : "",
-            focus: projection.currentFocus ?? "",
-            todo: projection.todoProjection ?? null,
-            gate: projection.activeGate ?? null,
-        } : undefined,
-        evidenceSummary: {
-            verified: Array.isArray(criteria.evidenced) ? criteria.evidenced : [],
-            contradicted: Array.isArray(checks.failed) ? checks.failed : [],
-            unavailable: Array.isArray(checks.unavailable) ? checks.unavailable : [],
-        },
-        stateHash: artifact?.stateHash,
-        promptHash: artifact?.promptHash,
-    };
-}
-/** Uniform decision enrichment for advance-family tools.
- *
- *  Handler-level `{error}` responses and session-level lease conflicts are
- *  not loop decisions — without this guard the enforcement-only derivation
- *  above would label them "stopped" (any stopReason) or even "accepted"
- *  (a bare error with no enforcement fields). */
-function finalizeAdvanceOutput(mgr, result) {
-    const stopReason = String(result.stopReason ?? "");
-    if ((result.error !== undefined && result.error !== null) ||
-        stopReason.startsWith("session_owned_elsewhere")) {
-        return { ...result, decision: "errored" };
-    }
-    return enrichAdvanceResult(mgr, result);
+/** Validate a handler's output against the tool's declared output schema.
+ *  v2.14: the schemas were advertised in tools/list but never enforced —
+ *  a mismatched output silently violated the declared contract. Throws
+ *  ToolInputValidationError on mismatch. */
+export function validateToolOutput(name, output) {
+    const schema = TOOL_OUTPUT_SCHEMAS[name];
+    if (!schema)
+        return;
+    validateSchema(output, schema, `output.${name}`);
 }
 export const TOOL_HANDLERS = {
     async loopforge_start(mgr, input) {
@@ -542,92 +637,112 @@ export const TOOL_HANDLERS = {
             constraints: Array.isArray(input.constraints)
                 ? input.constraints
                 : undefined,
-            successCriteria: Array.isArray(input.successCriteria)
-                ? input.successCriteria
-                : undefined,
         };
         if (!startInput.task.trim()) {
-            return { error: "task is required and must be non-empty", decision: "errored" };
+            return { error: "task is required and must be non-empty" };
         }
-        const policyMaxRounds = getPolicy().engine.max_rounds;
+        // v2.14: entry-point validation — a bad maxRounds previously passed
+        // through and stopped the loop on the first round; an invalid loopId
+        // exploded later as an internal storage error instead of a clean
+        // argument error.
         if (startInput.maxRounds !== undefined &&
-            (!Number.isInteger(startInput.maxRounds) || startInput.maxRounds < 1 || startInput.maxRounds > policyMaxRounds)) {
-            return { error: `maxRounds must be an integer between 1 and ${policyMaxRounds}`, decision: "errored" };
+            (!Number.isInteger(startInput.maxRounds) || startInput.maxRounds < 1)) {
+            return { error: "maxRounds must be a positive integer" };
+        }
+        if (startInput.loopId !== undefined) {
+            try {
+                validateLoopId(startInput.loopId);
+            }
+            catch (error) {
+                return { error: `invalid loopId: ${error.message}` };
+            }
         }
         const result = await mgr.create(startInput);
-        const enriched = finalizeAdvanceOutput(mgr, { ...result });
-        const session = typeof result.sessionId === "string" ? mgr.get(result.sessionId) : undefined;
-        return {
-            ...enriched,
-            loopId: session?.loopId,
-            goalId: session?.runtime.state?.task_id ?? session?.loopId,
-        };
+        // 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 { ...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", decision: "errored" };
-        const report = parseRoundReport(input.report);
-        if (!report)
-            return { error: "report is not a valid RoundReport", decision: "errored" };
-        const result = await mgr.advance(sessionId, report);
-        return finalizeAdvanceOutput(mgr, { ...result });
-    },
-    async loopforge_retry(mgr, input) {
-        const sessionId = String(input.sessionId ?? "");
-        if (!sessionId)
-            return { error: "sessionId is required", decision: "errored" };
-        const report = parseRoundReport(input.report);
-        if (!report)
-            return { error: "report is not a valid RoundReport", decision: "errored" };
-        return finalizeAdvanceOutput(mgr, { ...await mgr.retry(sessionId, report) });
-    },
-    async loopforge_backtrack(mgr, input) {
-        const sessionId = String(input.sessionId ?? "");
-        if (!sessionId)
-            return { error: "sessionId is required", decision: "errored" };
-        // Backtrack is an enforcement action: enrich it like the other advance
-        // tools so the output honors the shared advance contract.
-        return finalizeAdvanceOutput(mgr, { ...await mgr.backtrack(sessionId) });
+            return { error: "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" };
+        }
+        // Build SelfEvaluation from structured evaluation parameter
+        const preExtractedEval = rawEval ? buildSelfEvaluation(rawEval) : undefined;
+        // Require at least one of: evaluation parameter or output with embedded eval block
+        if (!preExtractedEval && !output.trim()) {
+            return { error: "Either evaluation parameter or output with ---loopforge-eval block is required" };
+        }
+        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;
+        if (result.enforcementAction !== "reject" && result.enforcementAction !== "terminate" &&
+            result.stopReason !== "session_not_found" && result.stopReason !== "stalled") {
+            projection = mgr.getProjection(sessionId);
+        }
+        // v2.12: Field-level diagnostics for tolerated format issues. The
+        // lenient parser still accepts the evaluation — the gaps are surfaced
+        // as structured warnings so the agent can correct its template.
+        if (rawEval) {
+            const gaps = collectSelfEvalGaps(rawEval);
+            if (gaps.length > 0) {
+                return {
+                    ...result,
+                    projection,
+                    warnings: [...(result.warnings ?? []), ...gaps.map((g) => `[${g.field}] ${g.issue}`)],
+                    parseGaps: gaps,
+                };
+            }
+        }
+        return projection ? { ...result, projection } : { ...result };
     },
     async loopforge_status(mgr, input) {
-        const scope = String(input.scope ?? "");
-        const hasSessionId = typeof input.sessionId === "string" && input.sessionId.trim().length > 0;
-        const hasLoopId = typeof input.loopId === "string" && input.loopId.trim().length > 0;
-        if (scope === "all") {
-            if (hasSessionId || hasLoopId)
-                return { error: "scope=all does not accept sessionId or loopId" };
-            return { scope, sessions: mgr.list() };
+        const view = input.view === "loop" || input.view === "all" || input.view === "audit"
+            ? input.view
+            : "session";
+        const sessionId = String(input.sessionId ?? "");
+        const loopId = String(input.loopId ?? "");
+        // v2.12: view=all — every persisted loop (formerly loopforge_list).
+        if (view === "all") {
+            return { sessions: mgr.list() };
         }
-        if (scope === "loop") {
-            if (hasSessionId)
-                return { error: "scope=loop does not accept sessionId" };
-            const loopId = String(input.loopId ?? "").trim();
+        // v2.12: view=audit — read-only verification audit.
+        if (view === "audit") {
             if (!loopId)
-                return { error: "loopId is required for loop scope" };
+                return { error: "loopId is required for view=audit" };
+            const audit = mgr.getAudit(loopId);
+            if (!audit)
+                return { error: `no audit data found for loop "${loopId}"` };
+            return audit;
+        }
+        // v2.12: view=loop — loop health (formerly loopforge_health).
+        if (view === "loop") {
+            if (!loopId)
+                return { error: "loopId is required for view=loop" };
             const health = mgr.getHealth(loopId);
-            if (!health)
-                return { error: `no data found for loop "${loopId}"` };
-            const audit = mgr.audit(loopId);
-            return input.detail === "full"
-                ? { scope, loopId, health, audit }
-                : { scope, loopId, health };
+            return health ?? { error: `no health data for loop "${loopId}"` };
         }
-        if (scope !== "session")
-            return { error: "scope must be session, loop, or all" };
-        if (hasLoopId)
-            return { error: "scope=session does not accept loopId" };
-        const sessionId = String(input.sessionId ?? "");
         if (!sessionId)
-            return { error: "sessionId is required" };
+            return { error: "sessionId is required for view=session" };
         const session = mgr.get(sessionId);
         if (!session)
             return { error: `session not found: ${sessionId}` };
-        const metrics = session.runtime.getMetrics();
-        const state = mgr.cognitiveProjection(sessionId);
-        const artifact = session.roundSnapshot?.promptArtifact;
-        const audit = mgr.audit(session.loopId);
-        const summary = {
+        const metrics = session.engine.getMetrics();
+        return {
             sessionId: session.sessionId,
             loopId: session.loopId,
             round: session.currentRound,
@@ -636,40 +751,10 @@ export const TOOL_HANDLERS = {
             status: session.status,
             successTrajectory: session.successTrajectory,
             lease: mgr.getLeaseStatus(session.loopId),
-        };
-        if (input.detail !== "full")
-            return summary;
-        return {
-            ...summary,
-            cognition: state ? {
-                phaseHistory: state.phaseHistory ?? [],
-                currentFocus: state.currentFocus ?? "",
-                todoProjection: state.todoProjection ?? null,
-                suggestedNextAction: state.suggestedNextAction ?? "",
-                activeGate: state.activeGate ?? null,
-                handoff: state.handoff ?? null,
-                stateFreshness: state.stateFreshness ?? "missing",
-                regressionObligations: state.regressionObligations ?? [],
-            } : null,
-            promptDiagnostics: artifact ? {
-                level: artifact.level,
-                reasons: artifact.levelReasons,
-                includedSections: artifact.includedSections,
-                omittedSections: artifact.omittedSections,
-                stateHash: artifact.stateHash,
-                promptHash: artifact.promptHash,
-                lastL2Round: artifact.lastL2Round,
-                lastMeaningfulProgressRound: artifact.lastMeaningfulProgressRound,
-                stateAgeRounds: artifact.stateAgeRounds,
-            } : null,
-            audit: {
-                verdict: audit.verdict,
-                missingCriteria: isRecord(audit.criteria) ? audit.criteria.missing : [],
-                unresolvedUserGates: audit.unresolvedUserGates ?? [],
-            },
+            projection: mgr.getProjection(sessionId),
             metrics: {
                 vaultWriteErrors: metrics.vaultWriteErrors,
-                policy: mgr.getLoopPolicyMetrics(session.loopId),
+                policy: mgr.getPolicyMetrics(session.loopId),
             },
         };
     },
@@ -683,17 +768,7 @@ export const TOOL_HANDLERS = {
         const roundsCompleted = session.currentRound;
         const successTrajectory = [...session.successTrajectory];
         mgr.delete(sessionId);
-        const audit = mgr.audit(session.loopId);
-        return {
-            success: true,
-            sessionId,
-            loopId: session.loopId,
-            stopReason: "cancelled",
-            stopDetail: "The loop was manually stopped. Vault state was retained for audit and inspection.",
-            roundsCompleted,
-            successTrajectory,
-            audit,
-        };
+        return { success: true, roundsCompleted, successTrajectory };
     },
     async loopforge_pause(mgr, input) {
         const sessionId = String(input.sessionId ?? "");
@@ -702,53 +777,44 @@ export const TOOL_HANDLERS = {
         const result = mgr.pause(sessionId);
         return { ...result };
     },
-    async loopforge_history(mgr, input) {
-        const loopId = String(input.loopId ?? "").trim();
-        const view = String(input.view ?? "");
-        if (!loopId)
-            return { error: "loopId is required" };
-        if (view !== "round" && view !== "timeline")
-            return { error: "view must be round or timeline" };
-        if (view === "round") {
-            const round = Number(input.round);
-            if (!Number.isInteger(round) || round < 1)
-                return { error: "round must be a positive integer" };
-            const inspected = mgr.inspect(loopId, round);
-            return inspected ?? { error: `round not found: ${loopId}#${round}` };
-        }
-        const fromSequence = typeof input.fromSequence === "number" ? input.fromSequence : undefined;
-        const toSequence = typeof input.toSequence === "number" ? input.toSequence : undefined;
-        const limit = typeof input.limit === "number" ? input.limit : 50;
-        const result = mgr.replayTimelineByLoop(loopId, fromSequence, toSequence, limit);
-        return { loopId, view, timeline: result.timeline, nextSequence: result.nextSequence };
+    async loopforge_replay(mgr, input) {
+        const sessionId = String(input.sessionId ?? "");
+        if (!sessionId)
+            return { error: "sessionId is required" };
+        const session = mgr.get(sessionId);
+        if (!session)
+            return { error: `session not found: ${sessionId}` };
+        const timeline = mgr.replayTimeline(sessionId) ?? [];
+        return { sessionId, loopId: session.loopId, timeline };
     },
     async loopforge_resume(mgr, input) {
         const loopId = String(input.loopId ?? "");
         if (!loopId)
-            return { error: "loopId is required", decision: "errored" };
+            return { error: "loopId is required" };
+        try {
+            validateLoopId(loopId);
+        }
+        catch (error) {
+            return { error: `invalid loopId: ${error.message}` };
+        }
         // Paused recovery must run first so the persisted status is atomically
         // changed back to running before a prompt is returned.
         let result = await mgr.unpause(loopId);
         if (!result) {
-            result = await mgr.resume(loopId);
+            result = mgr.resume(loopId);
         }
         if (!result)
-            return { error: `no saved session found for loop "${loopId}"`, decision: "errored" };
-        return finalizeAdvanceOutput(mgr, { ...result });
+            return { error: `no saved session found for loop "${loopId}"` };
+        return { ...result };
     },
     async loopforge_gate_check(mgr, input) {
-        if (!isRecord(input.action))
-            return { error: "action descriptor is required" };
-        return mgr.checkGate(input.action);
+        const gateText = String(input.gateText ?? "");
+        if (!gateText.trim())
+            return { error: "gateText is required" };
+        return mgr.checkGate(gateText);
     },
     async loopforge_gate_resolve(mgr, input) {
-        return mgr.resolveGate(String(input.sessionId ?? ""), String(input.gateId ?? ""), isRecord(input.action) ? input.action : {}, input.approved === true, String(input.note ?? ""));
-    },
-    async loopforge_audit(mgr, input) {
-        const loopId = String(input.loopId ?? "").trim();
-        if (!loopId)
-            return { error: "loopId is required" };
-        return mgr.audit(loopId);
+        return mgr.resolveGate(String(input.sessionId ?? ""), String(input.gateId ?? ""), input.approved === true, input.note === undefined ? undefined : String(input.note));
     },
 };
 //# sourceMappingURL=tools.js.map