@martinloop/mcp 0.3.6 → 0.3.8

package/dist/resources.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { homedir } from "node:os";
 import { buildMartinDiscoveryMetadata } from "./discovery-metadata.js";
 import { MARTIN_MCP_PACKAGE_VERSION } from "./package-version.js";
 import { inspectLoopTool } from "./tools/inspect-loop.js";
@@ -19,6 +19,7 @@ export const MARTIN_STATIC_RESOURCE_URIS = {
     triage: "martin://runs/triage",
     latestRun: "martin://runs/latest",
     latestSummary: "martin://runs/latest/summary",
+    latestReceipt: "martin://runs/latest/receipt",
     latestProofCard: "martin://runs/latest/proof-card",
     latestBudgetStatus: "martin://runs/latest/budget-status",
     latestVerifierEvidence: "martin://runs/latest/verifier-evidence",
@@ -34,8 +35,8 @@ export const MARTIN_STATIC_RESOURCE_URIS = {
     operatingRulesGuide: "martin://guides/operating-rules",
     publishReadinessGuide: "martin://guides/publish-readiness",
     governanceStatus: "martin://agent/governance-status",
-    modeStatus: "martin://agent/mode-status",
-    memorySummary: "martin://agent/memory-summary"
+    memorySummary: "martin://agent/memory-summary",
+    modeStatus: "martin://agent/mode-status"
 };
 export const MARTIN_RESOURCE_TEMPLATES = [
     {
@@ -99,11 +100,18 @@ export const MARTIN_STATIC_RESOURCES = [
         description: "Compact latest-run summary for context-constrained agents.",
         mimeType: "application/json"
     },
+    {
+        uri: MARTIN_STATIC_RESOURCE_URIS.latestReceipt,
+        name: "martin_latest_receipt",
+        title: "Martin Latest Receipt",
+        description: "Canonical structured receipt for the latest run; use this before optional proof-card views.",
+        mimeType: "application/json"
+    },
     {
         uri: MARTIN_STATIC_RESOURCE_URIS.latestProofCard,
         name: "martin_latest_proof_card",
         title: "Martin Latest Proof Card",
-        description: "Small Markdown receipt showing what happened, what Martin prevented, and the next safe action.",
+        description: "Optional Markdown proof view derived from the latest receipt.",
         mimeType: "text/markdown"
     },
     {
@@ -204,19 +212,19 @@ export const MARTIN_STATIC_RESOURCES = [
         description: "Proactive governance status: whether work is governed, budget remaining, unreceipted runs, and recommended next action. Read this before starting agent work.",
         mimeType: "application/json"
     },
-    {
-        uri: MARTIN_STATIC_RESOURCE_URIS.modeStatus,
-        name: "martin_mode_status",
-        title: "Martin Mode Status",
-        description: "Current MartinLoop working mode, whether it is inherited or explicitly configured, and how to switch it.",
-        mimeType: "application/json"
-    },
     {
         uri: MARTIN_STATIC_RESOURCE_URIS.memorySummary,
         name: "martin_memory_summary",
         title: "Martin Memory Summary",
         description: "MartinLoop persistent memory: user preferences, consent signals, budget patterns, and behavioral observations aggregated over time. Read at session start to personalize recommendations.",
         mimeType: "application/json"
+    },
+    {
+        uri: MARTIN_STATIC_RESOURCE_URIS.modeStatus,
+        name: "martin_mode_status",
+        title: "Martin Mode Status",
+        description: "Current Martin working mode (auto, plan, or edits) and consent state. Read before starting agent work to confirm whether the user expects autonomous execution, plan approval, or per-edit review.",
+        mimeType: "application/json"
     }
 ];
 export function listMartinResources() {
@@ -252,6 +260,8 @@ export async function readMartinResource(input) {
             return jsonResource(input.uri, withDiscoveryMetadata(await martinRunDossierTool({ latest: true, runsDir: context.runsRoot }), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.latestSummary:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildLatestSummaryResource(context.runsRoot), context.runsRoot));
+        case MARTIN_STATIC_RESOURCE_URIS.latestReceipt:
+            return jsonResource(input.uri, withDiscoveryMetadata(await buildLatestReceiptResource(context.runsRoot), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.latestProofCard:
             return textResource(input.uri, "text/markdown", await buildLatestProofCardResource(context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus:
@@ -274,7 +284,7 @@ export async function readMartinResource(input) {
         case MARTIN_STATIC_RESOURCE_URIS.governanceStatus:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildGovernanceStatusResource(context.runsRoot, context.workingDirectory), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.modeStatus:
-            return jsonResource(input.uri, withDiscoveryMetadata(await buildModeStatusResource(context.workingDirectory), context.runsRoot));
+            return jsonResource(input.uri, withDiscoveryMetadata(await buildModeStatusResource(), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.agentNextStep:
             return jsonResource(input.uri, withDiscoveryMetadata(await buildAgentNextStepResource(context.runsRoot), context.runsRoot));
         case MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide:
@@ -423,6 +433,44 @@ async function buildLatestSummaryResource(runsRoot) {
         warnings: [...latest.detail.warnings, ...verification.warnings]
     };
 }
+async function buildLatestReceiptResource(runsRoot) {
+    const latest = await loadLatestRunForCompactResource(runsRoot);
+    if (latest.empty || !latest.detail) {
+        return compactEmptyState("latest-receipt", runsRoot, latest.warnings);
+    }
+    const ledgerEvents = await readLedgerEvents(latest.detail);
+    const loop = latest.detail.loop;
+    const verification = buildVerificationHistorySnapshot(loop, ledgerEvents);
+    const preview = buildPersistedLoopPreview(loop);
+    return {
+        kind: "latest-receipt",
+        loop: preview,
+        task: {
+            title: loop.task?.title,
+            objective: loop.task?.objective,
+            verificationPlan: loop.task?.verificationPlan ?? []
+        },
+        receiptIntegrity: latest.detail.loop.receiptIntegrity,
+        verification: {
+            status: verification.latestVerification?.passed === true
+                ? "passed"
+                : verification.latestVerification?.passed === false
+                    ? "failed"
+                    : "unavailable",
+            summary: verification.latestVerification?.summary,
+            latest: verification.latestVerification,
+            count: verification.verificationCount
+        },
+        whatHappened: loop.attempts.at(-1)?.summary ?? verification.latestVerification?.summary ?? loop.task?.objective,
+        whatMartinPrevented: describePrevention(loop),
+        nextSafeAction: inferAgentNextStep(loop, verification),
+        proofCard: {
+            artifactGuaranteed: false,
+            resource: MARTIN_STATIC_RESOURCE_URIS.latestProofCard
+        },
+        warnings: [...latest.detail.warnings, ...verification.warnings]
+    };
+}
 async function buildLatestBudgetStatusResource(runsRoot) {
     const latest = await loadLatestRunForCompactResource(runsRoot);
     if (latest.empty || !latest.detail) {
@@ -553,7 +601,7 @@ async function buildLatestProofCardResource(runsRoot) {
             "",
             "What happened: Martin has not found a local run record in this runs root.",
             "What Martin prevented: unknown until a governed run executes.",
-            "Next safe action: call `martin_doctor`, run `npx martin-loop demo`, then inspect `martin://runs/latest/summary`.",
+            "Next safe action: call `martin_doctor`, run `npx martin-loop demo`, then inspect `martin://runs/latest/receipt` or `martin://runs/latest/summary`.",
             "",
             "Estimate note: no cost or token savings are claimed without run evidence.",
             ""
@@ -607,9 +655,10 @@ async function buildGovernanceStatusResource(runsRoot, workingDirectory) {
     const state = await readWorkflowState(runsRoot);
     const mcpState = state.mcp ?? {};
     const hasDoctor = Boolean(mcpState.doctor);
+    const hasEstimate = Boolean(mcpState.estimate);
     const hasPlan = Boolean(mcpState.plan);
     const hasPreflight = Boolean(mcpState.preflight);
-    const governed = hasDoctor && hasPlan && hasPreflight;
+    const governed = hasDoctor && hasEstimate && hasPlan && hasPreflight;
     const latest = await loadLatestRunForCompactResource(runsRoot);
     const budgetRemaining = (!latest.empty && latest.detail)
         ? buildPersistedLoopPreview(latest.detail.loop).remainingBudgetUsd
@@ -627,22 +676,27 @@ async function buildGovernanceStatusResource(runsRoot, workingDirectory) {
     const missingSteps = [];
     if (!hasDoctor)
         missingSteps.push("martin_doctor");
+    if (!hasEstimate)
+        missingSteps.push("martin_estimate");
     if (!hasPlan)
         missingSteps.push("martin_plan");
     if (!hasPreflight)
         missingSteps.push("martin_preflight");
     const recommendedAction = !hasDoctor
         ? "Run martin_doctor to confirm environment before any work."
-        : !hasPlan
-            ? "Run martin_plan with your objective to scope the task."
-            : !hasPreflight
-                ? "Run martin_preflight to validate the run contract before execution."
-                : "Governance complete. You may proceed with martin_run.";
+        : !hasEstimate
+            ? "Run martin_estimate to preview cost and route before spending."
+            : !hasPlan
+                ? "Run martin_plan with your objective to scope the task."
+                : !hasPreflight
+                    ? "Run martin_preflight to validate the run contract before execution."
+                    : "Governance complete. You may proceed with martin_run.";
     return {
         kind: "governance-status",
         governed,
         workflowReceipts: {
             doctor: hasDoctor ? { recordedAt: mcpState.doctor.recordedAt } : null,
+            estimate: hasEstimate ? { recordedAt: mcpState.estimate.recordedAt } : null,
             plan: hasPlan ? { recordedAt: mcpState.plan.recordedAt } : null,
             preflight: hasPreflight ? { recordedAt: mcpState.preflight.recordedAt } : null
         },
@@ -650,37 +704,10 @@ async function buildGovernanceStatusResource(runsRoot, workingDirectory) {
         budgetRemaining,
         unreceiptedRuns,
         recommendedAction,
-        requiredSequence: ["martin_doctor", "martin_plan", "martin_preflight", "martin_run", "martin_dossier"],
+        requiredSequence: ["martin_doctor", "martin_estimate", "martin_plan", "martin_preflight", "martin_run", "martin_dossier"],
         warning: governed ? undefined : "This session is NOT governed. Complete the required sequence before making changes."
     };
 }
-async function buildModeStatusResource(workingDirectory) {
-    const configPath = join(homedir(), ".martin", "config.json");
-    let config = {};
-    try {
-        config = JSON.parse(await readFile(configPath, "utf8"));
-    }
-    catch {
-        // Fresh config means the implicit auto default is in effect.
-    }
-    const projectMode = config.projectOverrides?.[workingDirectory];
-    const defaultMode = config.defaultMode ?? "auto";
-    const effectiveMode = projectMode ?? defaultMode;
-    return {
-        kind: "mode-status",
-        effectiveMode,
-        defaultMode,
-        scope: projectMode ? "project" : config.defaultMode ? "global" : "implicit_default",
-        configured: Boolean(projectMode || config.defaultMode),
-        projectOverride: projectMode ?? null,
-        workingDirectory,
-        switchCommands: {
-            auto: "martin mode auto",
-            plan: "martin mode plan",
-            edits: "martin mode edits"
-        }
-    };
-}
 function buildCurrentPoliciesResource(workingDirectory) {
     const signals = inspectRepoSignals(workingDirectory);
     const recommended = buildPolicyPackDefinition(undefined, signals);
@@ -724,14 +751,14 @@ function inferAgentNextStep(loop, verification) {
         return {
             action: "triage_before_retry",
             toolOrResource: "martin_triage_runs",
-            instruction: "Call `martin_triage_runs` and inspect the proof card before spending another attempt."
+            instruction: "Call `martin_triage_runs` and inspect the latest receipt before spending another attempt."
         };
     }
     if (loop.status === "completed" && verification.latestVerification?.passed === true) {
         return {
             action: "prove_and_share",
-            toolOrResource: MARTIN_STATIC_RESOURCE_URIS.latestProofCard,
-            instruction: "Read the proof card and full dossier before sharing or promoting the result."
+            toolOrResource: MARTIN_STATIC_RESOURCE_URIS.latestReceipt,
+            instruction: "Read the latest receipt and full dossier before sharing or promoting the result; generate a proof card only when a visual artifact is explicitly needed."
         };
     }
     return {
@@ -742,175 +769,202 @@ function inferAgentNextStep(loop, verification) {
 }
 function buildMcpUsageGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Loop MCP Usage
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Martin Loop exposes governed coding workflows over MCP. Use the server health and run-store views to decide when to preflight, execute, inspect, or escalate.
-
-## Recommended Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` or call \`martin_doctor\` to confirm the environment and run-store visibility.
-2. Use the \`martin_governed_coding_kickoff\` prompt to frame a governed coding request.
-3. Call \`martin_preflight\` before \`martin_run\` when the task or safety envelope is non-trivial.
-4. After execution, inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`martin://runs/{loopId}\`, and \`martin://runs/{loopId}/verification\`.
-5. For low-context agents, read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, or \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` before asking for full JSON.
-6. Read \`${MARTIN_STATIC_RESOURCE_URIS.triage}\` or call \`martin_triage_runs\` to prioritize which run needs attention first.
-7. Use \`martin_debug_failed_run\` when a loop exits failed, budget-bound, or escalated.
-
-## Current Martin MCP Surface
-
-- Tools: \`martin_run\`, \`martin_inspect\`, \`martin_status\`, \`martin_doctor\`, \`martin_preflight\`, \`martin_list_runs\`, \`martin_triage_runs\`, \`martin_get_run\`, \`martin_get_attempt\`, \`martin_get_verification_results\`, \`martin_run_dossier\`
-- Static resources: \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\`, \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`${MARTIN_STATIC_RESOURCE_URIS.triage}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestVerifierEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestRollbackEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.governanceStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.modeStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.memorySummary}\`, \`${MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.publishReadinessGuide}\`
-- Resource templates: \`martin://runs/{loopId}\`, \`martin://runs/{loopId}/attempts/{attemptIndex}\`, \`martin://runs/{loopId}/verification\`
-- Prompts: \`martin_start\`, \`martin_preflight\`, \`martin_triage\`, \`martin_resume\`, \`martin_prove\`, \`martin_release_check\`, \`martin_governed_coding_kickoff\`, \`martin_debug_failed_run\`, \`martin_publish_readiness_review\`, \`martin_triage_run_store\`
-
-## Notes
-
-- Discovery helpers read the existing Martin run-store; they do not create new schema.
-- Verification history is derived from persisted \`verification.completed\` evidence in loop records and ledgers.
-- Attempt inspection stays aligned with the same loop selectors used by \`martin_status\` and \`martin_inspect\`.
+    return `# Martin Loop MCP Usage
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Martin Loop exposes governed coding workflows over MCP. Use the server health and run-store views to decide when to preflight, execute, inspect, or escalate.
+
+## Recommended Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` or call \`martin_doctor\` to confirm the environment and run-store visibility.
+2. Use the \`martin_governed_coding_kickoff\` prompt to frame a governed coding request.
+3. Call \`martin_preflight\` before \`martin_run\` when the task or safety envelope is non-trivial.
+4. After execution, inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`martin://runs/{loopId}\`, and \`martin://runs/{loopId}/verification\`.
+5. For low-context agents, read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, or \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\` before asking for full JSON. Treat \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` as an optional derived view.
+6. Read \`${MARTIN_STATIC_RESOURCE_URIS.triage}\` or call \`martin_triage_runs\` to prioritize which run needs attention first.
+7. Use \`martin_debug_failed_run\` when a loop exits failed, budget-bound, or escalated.
+
+## Current Martin MCP Surface
+
+- Tools: \`martin_run\`, \`martin_inspect\`, \`martin_status\`, \`martin_doctor\`, \`martin_preflight\`, \`martin_list_runs\`, \`martin_triage_runs\`, \`martin_get_run\`, \`martin_get_attempt\`, \`martin_get_verification_results\`, \`martin_run_dossier\`
+- Static resources: \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\`, \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\`, \`${MARTIN_STATIC_RESOURCE_URIS.triage}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestBudgetStatus}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestVerifierEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.latestRollbackEvidence}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`, \`${MARTIN_STATIC_RESOURCE_URIS.mcpUsageGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`, \`${MARTIN_STATIC_RESOURCE_URIS.publishReadinessGuide}\`
+- Resource templates: \`martin://runs/{loopId}\`, \`martin://runs/{loopId}/attempts/{attemptIndex}\`, \`martin://runs/{loopId}/verification\`
+- Prompts: \`martin_start\`, \`martin_preflight\`, \`martin_triage\`, \`martin_resume\`, \`martin_prove\`, \`martin_release_check\`, \`martin_governed_coding_kickoff\`, \`martin_debug_failed_run\`, \`martin_publish_readiness_review\`, \`martin_triage_run_store\`
+
+## Notes
+
+- Discovery helpers read the existing Martin run-store; they do not create new schema.
+- Verification history is derived from persisted \`verification.completed\` evidence in loop records and ledgers.
+- Attempt inspection stays aligned with the same loop selectors used by \`martin_status\` and \`martin_inspect\`.
 `;
 }
 function buildAgentStartGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Agent Start Here
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use Martin Loop as the local governor before you spend agent tokens or retry a failed coding loop.
-
-## Cheap Default Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\` first. It is the smallest "what should I do now?" payload.
-2. If no runs exist, call \`martin_doctor\`, then \`martin_preflight\`.
-3. If a run exists, read \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\` before reading full run JSON.
-4. If the verifier failed, use prompt \`martin_debug_failed_run\` or \`martin_triage\`.
-5. If you need a shareable receipt, read \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`.
-
-## Install Profiles
-
-- \`minimal\` (default): doctor, preflight, list, triage, dossier. Good for low tool bloat.
-- \`diagnostic\`: read-only inspection tools for debugging without execution.
-- \`full-local\`: all local tools, including \`martin_run\`.
-- \`github-review\`: review-oriented local profile for PR drafting and reviewer evidence.
-- \`starter\` and \`full\`: compatibility aliases.
-
-## Copy-Paste Agent Rule
-
-Before running or retrying an autonomous coding task, call Martin. Prefer compact resources first, then full dossiers only when the compact receipt says more evidence is needed. Never claim success unless Martin shows verifier-backed completion or a clear blocked reason.
+    return `# Agent Start Here
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use Martin Loop as the local governor before you spend agent tokens or retry a failed coding loop.
+
+## Cheap Default Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\` first. It is the smallest "what should I do now?" payload.
+2. If no runs exist, call \`martin_doctor\`, then \`martin_preflight\`.
+3. If a run exists, read \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\` before reading full run JSON.
+4. If the verifier failed, use prompt \`martin_debug_failed_run\` or \`martin_triage\`.
+5. If you need a shareable receipt, read \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\` first. Generate or inspect \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\` only when a visual artifact is explicitly required.
+
+## Install Profiles
+
+- \`minimal\` (default): doctor, preflight, list, triage, dossier. Good for low tool bloat.
+- \`diagnostic\`: read-only inspection tools for debugging without execution.
+- \`full-local\`: all local tools, including \`martin_run\`.
+- \`github-review\`: review-oriented local profile for PR drafting and reviewer evidence.
+- \`starter\` and \`full\`: compatibility aliases.
+
+## Copy-Paste Agent Rule
+
+Before running or retrying an autonomous coding task, call Martin. Prefer compact resources first, then full dossiers only when the compact receipt says more evidence is needed. Never claim success unless Martin shows verifier-backed completion or a clear blocked reason.
 `;
 }
 function buildCommandMapGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Command Map
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide when an IDE or agent needs to know which Martin surface to call next.
-
-## Default Governed Sequence
-
-1. \`martin_doctor\` — confirm environment and visibility.
-2. \`martin_plan\` — propose the bounded approach without spending a run.
-3. \`martin_preflight\` — turn the plan into an explicit contract.
-4. \`martin_run\` — execute only after the contract is safe.
-5. \`martin_dossier\` — inspect what happened and what Martin prevented.
-6. \`martin_eval\` — convert the result into review posture when needed.
-
-## When To Use Which Surface
-
-- Need the smallest next action: \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`
-- Need a quick receipt: \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`
-- Need a shareable proof object: \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`
-- Need a full run review: \`martin_dossier\`
-- Need to decide whether to retry: \`martin_triage_runs\`
-- Need IDE setup guidance: \`${MARTIN_STATIC_RESOURCE_URIS.ideOnboardingGuide}\`
+    return `# Martin Command Map
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide when an IDE or agent needs to know which Martin surface to call next.
+
+## Default Governed Sequence
+
+1. \`martin_doctor\` — confirm environment and visibility.
+2. \`martin_plan\` — propose the bounded approach without spending a run.
+3. \`martin_preflight\` — turn the plan into an explicit contract.
+4. \`martin_run\` — execute only after the contract is safe.
+5. \`martin_dossier\` — inspect what happened and what Martin prevented.
+6. \`martin_eval\` — convert the result into review posture when needed.
+
+## When To Use Which Surface
+
+- Need the smallest next action: \`${MARTIN_STATIC_RESOURCE_URIS.agentNextStep}\`
+- Need a quick receipt: \`${MARTIN_STATIC_RESOURCE_URIS.latestSummary}\`
+- Need the structured receipt source of truth: \`${MARTIN_STATIC_RESOURCE_URIS.latestReceipt}\`
+- Need an optional visual proof object: \`${MARTIN_STATIC_RESOURCE_URIS.latestProofCard}\`
+- Need a full run review: \`martin_dossier\`
+- Need to decide whether to retry: \`martin_triage_runs\`
+- Need IDE setup guidance: \`${MARTIN_STATIC_RESOURCE_URIS.ideOnboardingGuide}\`
 `;
 }
 function buildIdeOnboardingGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin IDE Onboarding
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide after the MCP server is installed so the host naturally uses MartinLoop during real work.
-
-## IDE Default Flow
-
-1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`
-2. Read \`${MARTIN_STATIC_RESOURCE_URIS.operatingRulesGuide}\`
-3. Use prompt \`martin_start\` or \`martin_governed_coding_kickoff\`
-4. Call \`martin_doctor\`
-5. Call \`martin_plan\`
-6. Call \`martin_preflight\`
-7. Only then call \`martin_run\`
-
-## Goal
-
-MartinLoop should become the normal path for coding work in the host, not a manual extra step the human has to remember.
+    return `# Martin IDE Onboarding
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide after the MCP server is installed so the host naturally uses MartinLoop during real work.
+
+## IDE Default Flow
+
+1. Read \`${MARTIN_STATIC_RESOURCE_URIS.agentStartGuide}\`
+2. Read \`${MARTIN_STATIC_RESOURCE_URIS.operatingRulesGuide}\`
+3. Use prompt \`martin_start\` or \`martin_governed_coding_kickoff\`
+4. Call \`martin_doctor\`
+5. Call \`martin_plan\`
+6. Call \`martin_preflight\`
+7. Only then call \`martin_run\`
+
+## Goal
+
+MartinLoop should become the normal path for coding work in the host, not a manual extra step the human has to remember.
 `;
 }
 function buildOperatingRulesGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin Operating Rules
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use these rules inside the IDE or MCP host as the default MartinLoop operating posture.
-
-## Required Sequence Before Real Work
-
-1. \`martin_doctor\`
-2. \`martin_plan\`
-3. \`martin_preflight\`
-4. \`martin_run\`
-5. \`martin_dossier\`
-
-## Enforcement Rule
-
-Do not execute real coding work through MartinLoop until doctor and preflight have both been used for the current task.
-
-## Completion Rule
-
-Do not claim success until MartinLoop shows verifier-backed completion or an explicit blocked reason backed by evidence.
+    return `# Martin Operating Rules
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use these rules inside the IDE or MCP host as the default MartinLoop operating posture.
+
+## Required Sequence Before Real Work
+
+1. \`martin_doctor\`
+2. \`martin_plan\`
+3. \`martin_preflight\`
+4. \`martin_run\`
+5. \`martin_dossier\`
+
+## Enforcement Rule
+
+Do not execute real coding work through MartinLoop until doctor and preflight have both been used for the current task.
+
+## Completion Rule
+
+Do not claim success until MartinLoop shows verifier-backed completion or an explicit blocked reason backed by evidence.
 `;
 }
 function buildPublishReadinessGuide(runsRoot) {
     const metadata = buildMartinDiscoveryMetadata(MARTIN_MCP_PACKAGE_VERSION);
-    return `# Martin MCP Publish Readiness
-
-Discovery revision: \`${metadata.discoveryRevision}\`
-Server version: \`${metadata.serverVersion}\`
-Runs root: \`${runsRoot}\`
-
-Use this guide when reviewing whether the public MCP package is ready to publish, promote, or hand off for registry submission.
-
-## Review Areas
-
-1. Environment health: confirm \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` shows a sane working directory, runs root, and engine availability for the target mode.
-2. Discovery surface: verify tools, prompts, static resources, and resource templates are all discoverable and named consistently.
-3. Run evidence: inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\` and, when relevant, \`martin://runs/{loopId}/verification\` to confirm verification outcomes are explainable from persisted data.
-4. Packaging lane: run the MCP package test, build, and smoke-pack commands before calling the package publish-ready.
-5. Findings-first reporting: call out missing schema, integration gaps, triage-critical runs, and verification blockers before summarizing strengths.
-
-## Evidence Expectations
-
-- Prefer concrete run IDs, attempt indices, and verification summaries over vague statements.
-- Distinguish local package validation from live registry readiness.
-- If a discovery helper exists but is not yet wired into the server, report that as an integration gap instead of treating the capability as fully shipped.
+    return `# Martin MCP Publish Readiness
+
+Discovery revision: \`${metadata.discoveryRevision}\`
+Server version: \`${metadata.serverVersion}\`
+Runs root: \`${runsRoot}\`
+
+Use this guide when reviewing whether the public MCP package is ready to publish, promote, or hand off for registry submission.
+
+## Review Areas
+
+1. Environment health: confirm \`${MARTIN_STATIC_RESOURCE_URIS.serverHealth}\` shows a sane working directory, runs root, and engine availability for the target mode.
+2. Discovery surface: verify tools, prompts, static resources, and resource templates are all discoverable and named consistently.
+3. Run evidence: inspect \`${MARTIN_STATIC_RESOURCE_URIS.recentRuns}\` and, when relevant, \`martin://runs/{loopId}/verification\` to confirm verification outcomes are explainable from persisted data.
+4. Packaging lane: run the MCP package test, build, and smoke-pack commands before calling the package publish-ready.
+5. Findings-first reporting: call out missing schema, integration gaps, triage-critical runs, and verification blockers before summarizing strengths.
+
+## Evidence Expectations
+
+- Prefer concrete run IDs, attempt indices, and verification summaries over vague statements.
+- Distinguish local package validation from live registry readiness.
+- If a discovery helper exists but is not yet wired into the server, report that as an integration gap instead of treating the capability as fully shipped.
 `;
 }
+async function buildModeStatusResource() {
+    let currentMode = "auto";
+    let modeConfigured = false;
+    try {
+        const config = JSON.parse(await readFile(join(homedir(), ".martin", "config.json"), "utf8"));
+        if (config.defaultMode) {
+            currentMode = config.defaultMode;
+            modeConfigured = true;
+        }
+    }
+    catch { /* fresh install — default to auto */ }
+    return {
+        kind: "mode-status",
+        currentMode,
+        modeConfigured,
+        modes: {
+            auto: "MartinLoop governs autonomously — estimate, preflight, run, receipt without per-step approval.",
+            plan: "MartinLoop shows the proposed plan before executing. Agent waits for user approval.",
+            edits: "MartinLoop shows each file change before writing. Maximum human control."
+        },
+        agentGuidance: modeConfigured
+            ? `User has explicitly set mode to "${currentMode}". Respect this preference during the session.`
+            : "Mode not explicitly configured. Defaulting to auto. Suggest running `martin mode auto|plan|edits` to set a preference.",
+        changeCommand: "martin mode auto | plan | edits"
+    };
+}
 function withDiscoveryMetadata(value, runsRoot) {
     return {
         metadata: {

package/dist/server-validation.d.ts

@@ -1,4 +1,4 @@
-type ToolName = "martin_run" | "martin_inspect" | "martin_status" | "martin_doctor" | "martin_plan" | "martin_preflight" | "martin_estimate" | "martin_logs" | "martin_cancel" | "martin_pause" | "martin_continue" | "martin_list_runs" | "martin_triage_runs" | "martin_get_run" | "martin_get_attempt" | "martin_get_verification_results" | "martin_run_dossier" | "martin_dossier" | "martin_eval" | "martin_pr_summary" | "martin_create_pr" | "martin_review_pr";
+type ToolName = "martin_run" | "martin_inspect" | "martin_status" | "martin_doctor" | "martin_estimate" | "martin_plan" | "martin_preflight" | "martin_logs" | "martin_cancel" | "martin_pause" | "martin_continue" | "martin_list_runs" | "martin_triage_runs" | "martin_get_run" | "martin_get_attempt" | "martin_get_verification_results" | "martin_run_dossier" | "martin_dossier" | "martin_eval" | "martin_pr_summary" | "martin_create_pr" | "martin_review_pr";
 export { sanitizeToolErrorMessage } from "./tools/tool-errors.js";
 export declare function validateToolInput(name: ToolName, args: unknown): unknown;
 export declare function resolveSafeRepoRoot(repoRoot?: string, workspaceRoot?: string): string;