loopforge 2.11.0 → 3.0.0

package/dist/mcp/tools.js

@@ -1,14 +1,106 @@
 /** LoopForge MCP — Tool definitions and handlers.
  *
- * 9 tools: start, next, status, stop, pause, list, replay, resume, health.
+ * Public tools for round execution, recovery, gates, and audit.
  * Each handler receives SessionManager + parsed input, returns the output object.
  */
-import { buildSelfEvaluation } from "../engine.js";
-import { getPolicyMetrics } from "../policy-metrics.js";
 import { isRecord } from "../token-utils.js";
+import { parseRoundReport } from "../round-report.js";
+import { getPolicy } 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",
@@ -26,7 +118,9 @@ const TOOL_BASE_SCHEMAS = [
                 },
                 maxRounds: {
                     type: "number",
-                    description: "Maximum rounds before auto-stop. Default: 20 from policy.",
+                    minimum: 1,
+                    multipleOf: 1,
+                    description: "Maximum rounds before auto-stop. Default: 100 from policy.",
                 },
                 domain: {
                     type: "string",
@@ -41,258 +135,122 @@ 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 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.",
+        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.",
         inputSchema: {
             type: "object",
+            additionalProperties: false,
             properties: {
                 sessionId: {
                     type: "string",
                     description: "Session ID returned by loopforge_start.",
                 },
-                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. 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" },
-                                    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.",
-                        },
-                        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.'",
-                                },
-                            },
-                        },
-                    },
+                report: {
+                    ...ROUND_REPORT_SCHEMA,
+                    description: "Canonical round report. This is the only execution report accepted by loopforge_next.",
                 },
             },
-            required: ["sessionId", "evaluation"],
+            required: ["sessionId", "report"],
         },
     },
     {
         name: "loopforge_status",
-        description: "Get the current status of a loop session, including round identity and success trajectory.",
+        description: "Read session, loop health, or all persisted loops through one canonical status view.",
         inputSchema: {
             type: "object",
             properties: {
+                scope: { type: "string", enum: ["session", "loop", "all"] },
                 sessionId: {
                     type: "string",
                     description: "Session ID returned by loopforge_start.",
                 },
+                loopId: { type: "string" },
+                detail: { type: "string", enum: ["summary", "full"] },
             },
-            required: ["sessionId"],
+            required: ["scope"],
         },
     },
     {
-        name: "loopforge_stop",
-        description: "Manually stop a loop session and return its final trajectory.",
+        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: {
                     type: "string",
-                    description: "Session ID to stop.",
+                    description: "Session ID returned by loopforge_start.",
+                },
+                report: {
+                    ...ROUND_REPORT_SCHEMA,
+                    description: "Corrected canonical report for the rejected attempt.",
                 },
             },
-            required: ["sessionId"],
+            required: ["sessionId", "report"],
         },
     },
     {
-        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_backtrack",
+        description: "Move an active session to the round after its nearest clean restore point. Returns restore instructions but never changes workspace files.",
         inputSchema: {
             type: "object",
             properties: {
                 sessionId: {
                     type: "string",
-                    description: "Session ID to pause.",
+                    description: "Session ID returned by loopforge_start.",
                 },
             },
             required: ["sessionId"],
         },
     },
     {
-        name: "loopforge_list",
-        description: "List all active loop sessions managed by this MCP server.",
+        name: "loopforge_history",
+        description: "Read one persisted round or a deterministic event timeline.",
         inputSchema: {
             type: "object",
-            properties: {},
-            required: [],
+            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_replay",
-        description: "Replay a completed or running loop session as an auditable round timeline.",
+        name: "loopforge_stop",
+        description: "Manually stop a loop session and return its final trajectory.",
         inputSchema: {
             type: "object",
             properties: {
                 sessionId: {
                     type: "string",
-                    description: "Session ID to replay.",
+                    description: "Session ID to stop.",
+                },
+            },
+            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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: {
+                    type: "string",
+                    description: "Session ID to pause.",
                 },
             },
             required: ["sessionId"],
@@ -313,16 +271,37 @@ const TOOL_BASE_SCHEMAS = [
         },
     },
     {
-        name: "loopforge_health",
-        description: "Check the health of a loop: goal alignment, constraint integrity, drift detection, strategy stability, and task continuity. Works for both active in-memory sessions and vault-persisted loops.",
+        name: "loopforge_gate_check",
+        description: "Classify whether an action is an agent-resolvable gate or requires explicit user authority. Read-only.",
         inputSchema: {
             type: "object",
             properties: {
-                loopId: {
-                    type: "string",
-                    description: "Loop ID to check health for.",
-                },
+                action: GATE_ACTION_SCHEMA,
+            },
+            required: ["action"],
+        },
+    },
+    {
+        name: "loopforge_gate_resolve",
+        description: "Record an explicit user decision for a previously classified gate.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                gateId: { type: "string" },
+                action: GATE_ACTION_SCHEMA,
+                approved: { type: "boolean" },
+                note: { type: "string" },
             },
+            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"],
         },
     },
@@ -335,12 +314,18 @@ 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" },
         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" },
         warnings: { type: "array", items: { type: "string" } },
     },
     additionalProperties: true,
@@ -348,7 +333,10 @@ const ADVANCE_OUTPUT_SCHEMA = {
 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: {
@@ -385,43 +373,17 @@ const TOOL_OUTPUT_SCHEMAS = {
         },
         additionalProperties: true,
     },
-    loopforge_list: {
-        type: "object",
-        properties: {
-            sessions: { type: "array", items: { type: "object", additionalProperties: true } },
-        },
-        required: ["sessions"],
-        additionalProperties: false,
-    },
-    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_health: {
-        type: "object",
-        properties: {
-            error: { type: "string" },
-            loopId: { type: "string" },
-            goal_alignment: { type: "object", additionalProperties: true },
-            constraint_integrity: { type: "object", additionalProperties: true },
-            drift_detected: { type: "boolean" },
-            strategy_stability: { type: "object", additionalProperties: true },
-            task_continuity: { type: "object", additionalProperties: true },
-            policy_metrics: { type: "object", additionalProperties: true },
-        },
-        additionalProperties: true,
-    },
+    loopforge_gate_check: { type: "object", additionalProperties: true },
+    loopforge_gate_resolve: { type: "object", additionalProperties: true },
+    loopforge_audit: { type: "object", additionalProperties: true },
 };
 function closeObjectSchemas(schema) {
     const result = { ...schema };
     if (result.type === "object") {
-        result.additionalProperties = false;
+        // Preserve explicitly open maps such as EvidenceEnvelope.provenance.
+        // Fixed-shape objects remain closed by default.
+        if (!("additionalProperties" in result))
+            result.additionalProperties = false;
         if (isRecord(result.properties)) {
             result.properties = Object.fromEntries(Object.entries(result.properties).map(([key, value]) => [
                 key,
@@ -490,6 +452,13 @@ function validateSchema(value, schema, path) {
     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`);
     }
@@ -513,6 +482,55 @@ 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);
+}
 export const TOOL_HANDLERS = {
     async loopforge_start(mgr, input) {
         const startInput = {
@@ -524,37 +542,92 @@ 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" };
+            return { error: "task is required and must be non-empty", decision: "errored" };
+        }
+        const policyMaxRounds = getPolicy().engine.max_rounds;
+        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" };
         }
         const result = await mgr.create(startInput);
-        return { ...result };
+        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,
+        };
     },
     async loopforge_next(mgr, input) {
         const sessionId = String(input.sessionId ?? "");
-        const output = String(input.output ?? "");
-        const rawEval = input.evaluation;
         if (!sessionId)
-            return { error: "sessionId is required" };
-        // 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);
-        return { ...result };
+            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) });
     },
     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() };
+        }
+        if (scope === "loop") {
+            if (hasSessionId)
+                return { error: "scope=loop does not accept sessionId" };
+            const loopId = String(input.loopId ?? "").trim();
+            if (!loopId)
+                return { error: "loopId is required for loop scope" };
+            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 };
+        }
+        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" };
         const session = mgr.get(sessionId);
         if (!session)
             return { error: `session not found: ${sessionId}` };
-        const metrics = session.engine.getMetrics();
-        return {
+        const metrics = session.runtime.getMetrics();
+        const state = mgr.cognitiveProjection(sessionId);
+        const artifact = session.roundSnapshot?.promptArtifact;
+        const audit = mgr.audit(session.loopId);
+        const summary = {
             sessionId: session.sessionId,
             loopId: session.loopId,
             round: session.currentRound,
@@ -563,9 +636,40 @@ 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 ?? [],
+            },
             metrics: {
                 vaultWriteErrors: metrics.vaultWriteErrors,
-                policy: getPolicyMetrics(session.loopId),
+                policy: mgr.getLoopPolicyMetrics(session.loopId),
             },
         };
     },
@@ -579,7 +683,17 @@ export const TOOL_HANDLERS = {
         const roundsCompleted = session.currentRound;
         const successTrajectory = [...session.successTrajectory];
         mgr.delete(sessionId);
-        return { success: true, roundsCompleted, successTrajectory };
+        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,
+        };
     },
     async loopforge_pause(mgr, input) {
         const sessionId = String(input.sessionId ?? "");
@@ -588,42 +702,53 @@ export const TOOL_HANDLERS = {
         const result = mgr.pause(sessionId);
         return { ...result };
     },
-    async loopforge_list(mgr, _input) {
-        const sessions = mgr.list();
-        return { sessions };
-    },
-    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_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_resume(mgr, input) {
         const loopId = String(input.loopId ?? "");
         if (!loopId)
-            return { error: "loopId is required" };
+            return { error: "loopId is required", decision: "errored" };
         // 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 = mgr.resume(loopId);
+            result = await mgr.resume(loopId);
         }
         if (!result)
-            return { error: `no saved session found for loop "${loopId}"` };
-        return { ...result };
+            return { error: `no saved session found for loop "${loopId}"`, decision: "errored" };
+        return finalizeAdvanceOutput(mgr, { ...result });
     },
-    async loopforge_health(mgr, input) {
-        const loopId = String(input.loopId ?? "");
+    async loopforge_gate_check(mgr, input) {
+        if (!isRecord(input.action))
+            return { error: "action descriptor is required" };
+        return mgr.checkGate(input.action);
+    },
+    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" };
-        const health = mgr.getHealth(loopId);
-        if (!health)
-            return { error: `no data found for loop "${loopId}"` };
-        return health;
+        return mgr.audit(loopId);
     },
 };
 //# sourceMappingURL=tools.js.map