@martinloop/mcp 0.5.0 → 0.5.3

package/README.md

@@ -6,11 +6,31 @@ But did it actually work? Did it pass your tests? How much did it spend? What fi
 
 You don't know. And that's the problem.
 
+## One system around the coding agent
+
+MartinLoop is the execution-control system around coding agents. The coding agent still performs the software work. MartinLoop connects the run from Definition of Done through preflight, control, verification, recovery evidence, receipts, and post-run analysis.
+
+```text
+DEFINE -> PREFLIGHT -> CONTROL -> VERIFY -> RECOVER -> PROVE -> ANALYZE
+```
+
+The product-level flow is **Definition of Done -> Controlled Run -> Verified Handoff**.
+
+Through MCP, compatible hosts can use the same MartinLoop lifecycle without giving up the host's own model selection. MartinLoop does not inject a hidden fallback model.
+
+For agent-readable product context see [`../../llms.txt`](../../llms.txt), [`../../llms-full.txt`](../../llms-full.txt), and [`../../docs/for-agents.md`](../../docs/for-agents.md).
+
 ## What This Does
 
-MartinLoop is a governed loop for AI coding agents. You tell it what to do, set a budget, and point it at your test suite. It runs the agent, checks your tests after every attempt, and stops when either the tests pass or the money runs out.
+MartinLoop governs AI coding-agent execution. You define what the run needs to accomplish, set execution boundaries such as budget and verifier checks, and let the configured coding agent do the work inside that contract.
+
+When it's done, you get a receipt — not a vague summary, but a structured record: dollars spent when available, attempts made, verification results, files changed, recovery state, and what the available evidence established.
+
+The final governed outcome is one of:
 
-When it's done, you get a receipt — not a vague summary, but a structured record: dollars spent, attempts made, verification results, files changed, and whether you got what you asked for.
+- `VERIFIED` when the configured evidence supports the Definition of Done
+- `STOPPED` when a configured hard boundary ends the run
+- `NEEDS REVIEW` when completion cannot be established from the available evidence
 
 **One line to connect it:**
 
@@ -18,7 +38,7 @@ When it's done, you get a receipt — not a vague summary, but a structured reco
 claude mcp add martin-loop -- npx -y @martinloop/mcp
 ```
 
-That's it. Your agent now runs governed.
+That's it. Your host can now use MartinLoop's governed run and evidence surfaces.
 
 ## Real Numbers From Real Runs
 
@@ -37,27 +57,27 @@ These aren't hypotheticals. The $28 overshoot happened in production testing. We
 
 ### Claude Code
 ```sh
-claude mcp add martin-loop -- npx -y @martinloop/mcp
+claude mcp add martin-loop -- npx -y @martinloop/mcp@0.5.3
 ```
 
 Windows:
 ```sh
-claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
+claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp@0.5.3
 ```
 
 ### Codex
 ```sh
-codex mcp add martin-loop -- npx -y @martinloop/mcp
+codex mcp add martin-loop -- npx -y @martinloop/mcp@0.5.3
 ```
 
 ### Gemini CLI
 ```sh
-gemini mcp add martin-loop -- npx -y @martinloop/mcp
+gemini mcp add martin-loop -- npx -y @martinloop/mcp@0.5.3
 ```
 
 ### Any MCP Host
 ```sh
-npx -y @martinloop/mcp
+npx -y @martinloop/mcp@0.5.3
 ```
 
 ## How a Governed Run Works
@@ -69,14 +89,16 @@ You: "Fix the auth bug. Budget $3. Verify: npm test"
   martin_plan       →  scopes the task, sets constraints
   martin_preflight  →  validates before any spend
   martin_run        →  agent works inside budget + verifier gates
-  martin_dossier    →  receipt: $1.40 spent, 2 attempts, tests pass
+  martin_dossier    →  receipt: spend, attempts, verifier evidence, final outcome
 ```
 
-Every attempt runs your verifier. Every dollar is tracked. If the agent drifts off-task, the scope contract catches it. If it blows the budget, the circuit breaker kills the subprocess mid-stream — not after the bill arrives.
+Every attempt can be checked by your configured verifier. Budget and policy controls stay attached to the run. If the agent drifts off-task, the scope contract can block the change. If a hard spend boundary is reached, the run stops according to policy instead of silently retrying forever.
 
 ## What Your Agent Gets
 
-### 21 Tools
+### MCP Tools
+
+The exact tool set is discoverable from the running MCP server with `tools/list`; do not rely on a hard-coded count in documentation.
 
 **Run the loop:**
 `martin_doctor` `martin_plan` `martin_preflight` `martin_run` `martin_pause` `martin_continue` `martin_cancel`
@@ -87,7 +109,9 @@ Every attempt runs your verifier. Every dollar is tracked. If the agent drifts o
 **Ship the work:**
 `martin_pr_summary` `martin_create_pr` `martin_review_pr`
 
-### 11 Read-Only Resources
+### Read-Only Resources
+
+The exact resource set is discoverable from the running MCP server; this documentation names the primary public resources without treating a count as a release invariant.
 
 Your agent can pull context without side effects:
 
@@ -106,20 +130,33 @@ npx martin-loop mcp print-config --host claude --profile github-review  # + PR w
 
 ## What Happens When Things Go Wrong
 
-MartinLoop doesn't just report failures — it tries to fix them:
+MartinLoop does not round failure into success. It preserves the evidence and follows the configured recovery path while budget and policy still allow useful work.
 
 | Failure | Old behavior | Now |
 |---|---|---|
 | CLI not on PATH | Error message, dead stop | Searches npm global, homebrew, nvm, scoop — uses what it finds |
-| Verifier says "command not found" | Generic "verification failed" | Tells the next attempt: "bun is missing, install with `npm i -g bun`" |
+| Verifier says "command not found" | Generic "verification failed" | Carries specific failure context into the next allowed attempt |
 | `git restore` fails mid-rollback | Throws, leaves dirty state | Retries once, falls back to `git checkout`, cleans up |
 | Invalid `--profile` flag | Crashes | Warns, falls back to `minimal`, keeps running |
 
+## Codex compatibility in 0.5.3
+
+MartinLoop no longer assumes one Codex host or one fixed Codex flag set. The CLI resolves the exact Codex executable, reads its advertised capabilities, negotiates a supported write strategy, proves that strategy before reporting launch readiness, and reuses the same contract for the governed run.
+
+That means MCP hosts can point MartinLoop at different Codex installations without requiring a documentation-specific approval or sandbox flag to exist everywhere.
+
+## Presentation and evidence
+
+MCP responses are Markdown-first for humans while retaining structured content for agents and automation. The presentation layer does not rewrite governed truth.
+
+MartinLoop Arcade is a terminal-only experience. It does not run inside MCP and cannot influence MCP evidence, budgets, verification, or final outcomes.
+
 ## Who Uses This
 
 - **Engineers running overnight agent loops** — you need a kill switch that actually works, and a receipt in the morning
 - **Teams with shared API budgets** — you need per-task spend caps, not org-wide prayer
 - **Anyone reviewing agent-generated PRs** — the dossier shows what the agent tried, what passed, and what didn't
+- **Teams tired of stitching together point tools** — you want one execution-control lifecycle around coding-agent work from preflight through post-run analysis
 
 ## Requirements
 
@@ -129,6 +166,7 @@ MartinLoop doesn't just report failures — it tries to fix them:
 ## Links
 
 - [martin-loop](https://www.npmjs.com/package/martin-loop) — the standalone CLI
+- [MartinLoop for AI Agents](../../docs/for-agents.md)
 - [GitHub](https://github.com/Keesan12/martin-loop) — source and issues
 - [martinloop.com](https://martinloop.com)
 

package/dist/resources.js

@@ -37,6 +37,16 @@ export const MARTIN_STATIC_RESOURCE_URIS = {
     modeStatus: "martin://agent/mode-status",
     memorySummary: "martin://agent/memory-summary"
 };
+function formatRecordedCost(usd, provenance) {
+    if (provenance === "unavailable")
+        return "unavailable";
+    if (provenance === "actual")
+        return `$${usd.toFixed(2)} provider-settled actual`;
+    if (provenance === "calculated") {
+        return `$${usd.toFixed(2)} calculated from observed usage`;
+    }
+    return `$${usd.toFixed(2)} estimated`;
+}
 export const MARTIN_RESOURCE_TEMPLATES = [
     {
         name: "martin_run_record",
@@ -376,7 +386,7 @@ async function loadLatestRunForCompactResource(runsRoot) {
                 empty: true,
                 warnings: [
                     "No Martin run records were found yet.",
-                    "Run `npx martin-loop demo`, then run `npx martin-loop run ... --proof --verify <command>` for a no-spend local proof pass."
+                    "Run `npx martin-loop demo`, then use `--proof --verify <command>` for explicitly non-governed verification-only evidence."
                 ]
             };
         }
@@ -404,6 +414,7 @@ async function buildLatestSummaryResource(runsRoot) {
         budget: loop.budget,
         cost: {
             actualUsd: loop.cost.actualUsd,
+            provenance: loop.cost.provenance ?? "unavailable",
             avoidedUsdEstimate: loop.cost.avoidedUsd ?? 0,
             tokensIn: loop.cost.tokensIn,
             tokensOut: loop.cost.tokensOut,
@@ -439,6 +450,7 @@ async function buildLatestBudgetStatusResource(runsRoot) {
         budget: loop.budget,
         cost: {
             actualUsd: loop.cost.actualUsd,
+            provenance: loop.cost.provenance ?? "unavailable",
             avoidedUsdEstimate: loop.cost.avoidedUsd ?? 0,
             tokensIn: loop.cost.tokensIn,
             tokensOut: loop.cost.tokensOut,
@@ -575,7 +587,7 @@ async function buildLatestProofCardResource(runsRoot) {
         `Run: \`${loop.loopId}\``,
         `Status: ${loop.status} / ${loop.lifecycleState}`,
         `Attempts: ${loop.attempts.length}`,
-        `Spend: $${loop.cost.actualUsd.toFixed(2)} actual, $${(loop.cost.avoidedUsd ?? 0).toFixed(2)} avoided estimate`,
+        `Spend: ${formatRecordedCost(loop.cost.actualUsd, loop.cost.provenance ?? "unavailable")}, $${(loop.cost.avoidedUsd ?? 0).toFixed(2)} avoided estimate`,
         `Tokens: ${loop.cost.tokensIn} in / ${loop.cost.tokensOut} out`,
         `Verifier: ${verifierStatus}`,
         "",
@@ -599,7 +611,7 @@ function compactEmptyState(kind, runsRoot, warnings) {
         status: "empty",
         runsRoot,
         summary: "No Martin run records are available yet.",
-        nextStep: "Run `npx martin-loop doctor`, create the demo workspace with `npx martin-loop demo`, then run `npx martin-loop run ... --proof --verify <command>`.",
+        nextStep: "Run `npx martin-loop doctor`, create the demo workspace, then use `--proof --verify <command>` only for non-governed verification evidence.",
         warnings
     };
 }

package/dist/server.js

@@ -55,6 +55,15 @@ const stringArraySchema = {
     type: "array",
     items: { type: "string" }
 };
+function describeCostProvenance(provenance) {
+    if (provenance === "actual")
+        return "provider-settled actual";
+    if (provenance === "calculated")
+        return "calculated from observed usage";
+    if (provenance === "estimated")
+        return "estimated";
+    return "unavailable";
+}
 const loopPreviewSchema = {
     type: "object",
     additionalProperties: true,
@@ -68,6 +77,10 @@ const loopPreviewSchema = {
         updatedAt: { type: "string" },
         attempts: { type: "integer" },
         costUsd: { type: "number" },
+        costProvenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        },
         avoidedUsd: { type: "number" },
         pressure: { type: "string" },
         shouldStop: { type: "boolean" },
@@ -87,6 +100,7 @@ const loopPreviewSchema = {
         "lifecycleState",
         "attempts",
         "costUsd",
+        "costProvenance",
         "avoidedUsd",
         "pressure",
         "shouldStop",
@@ -113,9 +127,13 @@ const costSchema = {
         actualUsd: { type: "number" },
         avoidedUsd: { type: "number" },
         tokensIn: { type: "integer" },
-        tokensOut: { type: "integer" }
+        tokensOut: { type: "integer" },
+        provenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        }
     },
-    required: ["actualUsd", "avoidedUsd", "tokensIn", "tokensOut"]
+    required: ["actualUsd", "avoidedUsd", "tokensIn", "tokensOut", "provenance"]
 };
 const verificationSchema = {
     type: "object",
@@ -248,6 +266,10 @@ const runOutputSchema = {
         reason: { type: "string" },
         attempts: { type: "integer" },
         costUsd: { type: "number" },
+        costProvenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        },
         verificationPassed: { type: "boolean" },
         loopId: { type: "string" },
         pressure: { type: "string" },
@@ -279,6 +301,7 @@ const runOutputSchema = {
         "reason",
         "attempts",
         "costUsd",
+        "costProvenance",
         "verificationPassed",
         "loopId",
         "pressure",
@@ -346,6 +369,10 @@ const statusOutputSchema = {
         lifecycleState: { type: "string" },
         attempts: { type: "integer" },
         costUsd: { type: "number" },
+        costProvenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        },
         avoidedUsd: { type: "number" },
         pressure: { type: "string" },
         shouldStop: { type: "boolean" },
@@ -369,6 +396,7 @@ const statusOutputSchema = {
         "lifecycleState",
         "attempts",
         "costUsd",
+        "costProvenance",
         "avoidedUsd",
         "pressure",
         "shouldStop",
@@ -1503,17 +1531,22 @@ export function createMartinMcpServer(serverInfo) {
                     });
                 }
                 const output = await runLoopTool(input);
-                return createToolSuccessResult(output, `Run ${output.loopId} is ${output.status}/${output.lifecycleState} after ${output.attempts} attempt(s); spend ${output.costUsd.toFixed(2)} USD.`);
+                return createToolSuccessResult(output, [
+                    `Run ${output.loopId} is ${output.status}/${output.lifecycleState}`,
+                    `after ${output.attempts} attempt(s); recorded cost ${output.costUsd.toFixed(2)} USD (${describeCostProvenance(output.costProvenance)}).`,
+                    `Execution mode: ${output.executionMode}; governance claim eligible:`,
+                    `${output.governanceClaimEligible ? "yes" : "no"}.`
+                ].join(" "));
             }
             if (name === "martin_inspect") {
                 const input = validateToolInput("martin_inspect", args);
                 const output = await inspectLoopTool(input);
-                return createToolSuccessResult(output, `Inspected ${output.loopCount} run(s) from ${output.source}; total actual spend ${output.portfolio.totalActualUsd.toFixed(2)} USD.`);
+                return createToolSuccessResult(output, `Inspected ${output.loopCount} run(s) from ${output.source}; total recorded cost ${output.portfolio.totalActualUsd.toFixed(2)} USD.`);
             }
             if (name === "martin_status") {
                 const input = validateToolInput("martin_status", args);
                 const output = await getStatusTool(input);
-                return createToolSuccessResult(output, `Loop ${output.loopId} is ${output.status}/${output.lifecycleState}; pressure is ${output.pressure} with ${output.remainingBudgetUsd.toFixed(2)} USD remaining.`);
+                return createToolSuccessResult(output, `Loop ${output.loopId} is ${output.status}/${output.lifecycleState}; recorded cost is ${output.costUsd.toFixed(2)} USD (${describeCostProvenance(output.costProvenance)}), and pressure is ${output.pressure} with ${output.remainingBudgetUsd.toFixed(2)} USD remaining.`);
             }
             if (name === "martin_doctor") {
                 const input = validateToolInput("martin_doctor", args);
@@ -1671,8 +1704,7 @@ export function createMartinMcpServer(serverInfo) {
                     compressed: route.compressed,
                     ...(route.compressionSummary ? { compressionSummary: route.compressionSummary } : {}),
                     recommendedBudgetUsd,
-                    recommendedModelTier: route.recommendedModelTier,
-                    estimatedSavingVsSonnetUsd: route.estimatedSavingVsSonnetUsd
+                    modelAuthority: "agent_or_provider_default"
                 };
                 await recordMcpWorkflowStep({
                     runsRoot,
@@ -1687,7 +1719,7 @@ export function createMartinMcpServer(serverInfo) {
                         runsRoot
                     }
                 }).catch(() => { });
-                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route (${route.recommendedModelTier}), ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
+                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route, ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Model authority remains with the agent/provider. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
             }
             return createToolErrorResult(toToolFailure(new Error(`Unknown tool: ${name}`)));
         }

package/dist/tools/doctor.js

@@ -115,10 +115,11 @@ export async function martinDoctorTool(input) {
                 ...(gemini.resolvedPath ? { resolvedPath: gemini.resolvedPath } : {})
             },
             openai: {
-                available: Boolean(process.env.MARTIN_OPENAI_API_KEY),
-                detail: process.env.MARTIN_OPENAI_API_KEY
-                    ? `OpenAI-compatible endpoint configured (model: ${process.env.MARTIN_OPENAI_MODEL ?? "gpt-4.1-mini"})`
-                    : "Set MARTIN_OPENAI_API_KEY and optionally MARTIN_OPENAI_BASE_URL + MARTIN_OPENAI_MODEL to enable."
+                available: Boolean(process.env.MARTIN_OPENAI_MODEL &&
+                    (process.env.MARTIN_OPENAI_API_KEY || process.env.MARTIN_OPENAI_BASE_URL)),
+                detail: process.env.MARTIN_OPENAI_MODEL
+                    ? `OpenAI-compatible model configured: ${process.env.MARTIN_OPENAI_MODEL}.`
+                    : "MODEL_CONFIGURATION_REQUIRED: set MARTIN_OPENAI_MODEL and the endpoint/auth required by your provider."
             }
         },
         ...(input.engine ? { requestedEngine: input.engine } : {}),

package/dist/tools/get-status.d.ts

@@ -1,3 +1,4 @@
+import type { CostProvenance } from "../vendor/contracts/index.js";
 import { type LoopPreview } from "./tool-support.js";
 export interface GetStatusInput {
     /** JSON-serialized LoopRecord. */
@@ -18,6 +19,7 @@ export interface GetStatusOutput {
     lifecycleState: string;
     attempts: number;
     costUsd: number;
+    costProvenance: CostProvenance;
     avoidedUsd: number;
     pressure: string;
     shouldStop: boolean;

package/dist/tools/get-status.js

@@ -31,6 +31,7 @@ export async function getStatusTool(input) {
         lifecycleState: loop.lifecycleState,
         attempts: loop.attempts.length,
         costUsd: loop.cost.actualUsd,
+        costProvenance: loop.cost.provenance ?? "unavailable",
         avoidedUsd: loop.cost.avoidedUsd ?? 0,
         pressure: costState.pressure,
         shouldStop: costState.shouldStop,

package/dist/tools/preflight.js

@@ -36,7 +36,7 @@ export async function martinPreflightTool(input) {
         maxTokens: input.maxTokens
     });
     if (!executionMode.liveMode) {
-        warnings.push("Proof mode is active; preflight only proves configuration shape, not live CLI readiness.");
+        warnings.push("Verification-only mode is active; it cannot emit governed VERIFIED or prove live CLI readiness.");
     }
     else if (!engineAvailability.available) {
         warnings.push(`Requested engine '${engine}' is not available on PATH.`);

package/dist/tools/run-loop.d.ts

@@ -1,5 +1,6 @@
+import { type SpawnLike } from "../vendor/adapters/index.js";
 import { type RunStore } from "../vendor/core/index.js";
-import type { LoopBudget, ReceiptScope } from "../vendor/contracts/index.js";
+import type { CostProvenance, ExecutionMode, LoopBudget, ReceiptScope } from "../vendor/contracts/index.js";
 import { buildArtifactSummary, buildVerificationSummary, buildLoopPreview, type MartinEngine } from "./tool-support.js";
 export interface RunLoopInput {
     objective: string;
@@ -22,7 +23,10 @@ export interface RunLoopOutput {
     reason: string;
     attempts: number;
     costUsd: number;
+    costProvenance: CostProvenance;
     verificationPassed: boolean;
+    executionMode: ExecutionMode;
+    governanceClaimEligible: boolean;
     loopId: string;
     pressure: string;
     shouldStop: boolean;
@@ -43,5 +47,6 @@ export interface RunLoopOutput {
         artifacts: ReturnType<typeof buildArtifactSummary>;
     };
 }
+export declare function __setProofModeVerifierSpawnImplForTests(spawnImpl?: SpawnLike): void;
 export declare function __setRunStoreOverrideForTests(store?: RunStore): void;
 export declare function runLoopTool(input: RunLoopInput): Promise<RunLoopOutput>;

package/dist/tools/run-loop.js

@@ -1,10 +1,14 @@
-import { createClaudeCliAdapter, createCodexCliAdapter, createGeminiCliAdapter, createStubDirectProviderAdapter, probeCodexLaunch, resolveCliCommandAvailability } from "../vendor/adapters/index.js";
+import { createClaudeCliAdapter, createCodexCliAdapter, createGeminiCliAdapter, createVerifierOnlyAdapter, probeCodexLaunch, resolveCliCommandAvailability } from "../vendor/adapters/index.js";
 import { createFileRunStore, evaluateCostGovernor, resolveRunsRoot, runMartin } from "../vendor/core/index.js";
 import { normalizeSafePathPatterns, resolveSafeRepoRoot } from "../server-validation.js";
 import { MartinToolError } from "./tool-errors.js";
 import { buildArtifactSummary, buildVerificationSummary, buildLoopPreview, buildRunRecordPaths, getEngineAvailability, resolveExecutionMode } from "./tool-support.js";
 import { normalizeLoopBudget } from "./workflow-governance.js";
+let proofModeVerifierSpawnImpl;
 let runStoreOverrideForTests;
+export function __setProofModeVerifierSpawnImplForTests(spawnImpl) {
+    proofModeVerifierSpawnImpl = spawnImpl;
+}
 export function __setRunStoreOverrideForTests(store) {
     runStoreOverrideForTests = store;
 }
@@ -15,6 +19,9 @@ export async function runLoopTool(input) {
     const allowedPaths = normalizeSafePathPatterns(input.allowedPaths, "allowedPaths");
     const deniedPaths = normalizeSafePathPatterns(input.deniedPaths, "deniedPaths");
     const executionMode = resolveExecutionMode();
+    const evidenceExecutionMode = executionMode.liveMode
+        ? "governed"
+        : "verification_only";
     const workspaceRoot = resolveSafeRepoRoot();
     const runsRoot = resolveRunsRoot(process.env);
     const receiptScope = {
@@ -30,7 +37,7 @@ export async function runLoopTool(input) {
             if (!engineAvailability.available) {
                 throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
                     category: "environment",
-                    suggestion: "Install the requested CLI or set MARTIN_LIVE=false for a no-spend proof run.",
+                    suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
                     retryable: false
                 });
             }
@@ -52,17 +59,18 @@ export async function runLoopTool(input) {
             if (!engineAvailability.available) {
                 throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
                     category: "environment",
-                    suggestion: "Install the requested CLI or set MARTIN_LIVE=false for a no-spend proof run.",
+                    suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
                     retryable: false
                 });
             }
         }
     }
     const adapter = !executionMode.liveMode
-        ? createStubDirectProviderAdapter({
-            label: "Proof mode stub adapter (MARTIN_LIVE=false)",
-            providerId: "stub",
-            model: "stub"
+        ? createVerifierOnlyAdapter({
+            workingDirectory,
+            label: "Verification-only adapter (MARTIN_LIVE=false)",
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+            ...(proofModeVerifierSpawnImpl ? { spawnImpl: proofModeVerifierSpawnImpl } : {})
         })
         : engine === "codex"
             ? createCodexCliAdapter({
@@ -110,6 +118,10 @@ export async function runLoopTool(input) {
             ...(deniedPaths ? { deniedPaths } : {})
         },
         budget,
+        metadata: {
+            executionMode: evidenceExecutionMode,
+            governanceClaimEligible: evidenceExecutionMode === "governed" ? "true" : "false"
+        },
         adapter
     });
     const lastAttempt = result.loop.attempts.at(-1);
@@ -133,7 +145,10 @@ export async function runLoopTool(input) {
         reason: result.decision.reason,
         attempts: result.loop.attempts.length,
         costUsd: result.loop.cost.actualUsd,
+        costProvenance: result.loop.cost.provenance ?? "unavailable",
         verificationPassed,
+        executionMode: evidenceExecutionMode,
+        governanceClaimEligible: evidenceExecutionMode === "governed",
         loopId: result.loop.loopId,
         pressure: costState.pressure,
         shouldStop: costState.shouldStop,

package/dist/tools/tool-errors.js

@@ -92,7 +92,7 @@ export function toToolFailure(error) {
             code: "engine_unavailable",
             category: "environment",
             message,
-            suggestion: "Install the requested CLI or set MARTIN_LIVE=false for a no-spend proof run.",
+            suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
             retryable: false
         };
     }

package/dist/tools/tool-response.js

@@ -4,13 +4,20 @@ function createJsonBlock(output) {
         text: JSON.stringify(output, null, 2)
     };
 }
+function resolveHumanArtifact(output, summary) {
+    const rendered = "rendered" in output ? output.rendered : undefined;
+    return typeof rendered === "string" && rendered.trim().length > 0 ? rendered : summary;
+}
 export function createToolSuccessResult(output, summary) {
     return {
-        content: [createJsonBlock(output), { type: "text", text: summary }],
+        content: [
+            { type: "text", text: resolveHumanArtifact(output, summary) },
+            createJsonBlock(output)
+        ],
         structuredContent: output,
         _meta: {
             "martinloop/summary": summary,
-            "martinloop/contentVersion": "2026-05-15"
+            "martinloop/contentVersion": "2026-08-18"
         }
     };
 }

package/dist/tools/tool-support.d.ts

@@ -1,4 +1,4 @@
-import type { LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope, TerminationEnvelopeV1 } from "../vendor/contracts/index.js";
+import type { CostProvenance, LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope, TerminationEnvelopeV1 } from "../vendor/contracts/index.js";
 import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord } from "../vendor/core/index.js";
 export declare const MARTIN_ENGINE_VALUES: readonly ["claude", "codex", "gemini", "openai"];
 export type MartinEngine = (typeof MARTIN_ENGINE_VALUES)[number];
@@ -27,6 +27,7 @@ export interface LoopPreview {
     updatedAt?: string;
     attempts: number;
     costUsd: number;
+    costProvenance: CostProvenance;
     avoidedUsd: number;
     pressure: string;
     shouldStop: boolean;
@@ -128,7 +129,7 @@ export declare function inspectRunsRoot(runsRoot?: string): Promise<RunStoreInsp
 export declare function buildRunRecordPaths(runsRoot: string, loopId: string): CanonicalRunPaths;
 export declare function buildAttemptArtifactDirectory(runsRoot: string, loopId: string, attemptIndex: number): string;
 export declare function buildAttemptArtifactsReference(runsRoot: string, loopId: string, attemptIndex: number): Promise<AttemptArtifactFiles>;
-export declare function buildCostSnapshot(cost: Pick<LoopCost, "actualUsd" | "tokensIn" | "tokensOut"> & {
+export declare function buildCostSnapshot(cost: Pick<LoopCost, "actualUsd" | "tokensIn" | "tokensOut" | "provenance"> & {
     avoidedUsd?: number;
 }): LoopCost;
 export declare function buildBudgetSnapshot(budget: LoopBudget): LoopBudget;

package/dist/tools/tool-support.js

@@ -15,7 +15,7 @@ export function resolveExecutionMode() {
         mode: liveMode ? "live" : "proof",
         detail: liveMode
             ? "Live CLI execution is enabled."
-            : "Proof mode is active because MARTIN_LIVE=false."
+            : "Verification-only mode is active because MARTIN_LIVE=false; governed VERIFIED is unavailable."
     };
 }
 export function detectCliAvailability(command) {
@@ -175,7 +175,7 @@ function suggestInstallCommand(command) {
 export function getEngineAvailability(engine) {
     return detectCliAvailability(engine);
 }
-export function createSkippedCliAvailability(command, detail = "Proof mode skipped live CLI availability detection.") {
+export function createSkippedCliAvailability(command, detail = "Verification-only mode skipped live CLI availability detection; governed VERIFIED is unavailable.") {
     return {
         command,
         available: false,
@@ -208,6 +208,7 @@ export function buildLoopPreview(loop) {
         ...(loop.updatedAt ? { updatedAt: loop.updatedAt } : {}),
         attempts: loop.attempts.length,
         costUsd: loop.cost.actualUsd,
+        costProvenance: loop.cost.provenance ?? "unavailable",
         avoidedUsd: loop.cost.avoidedUsd ?? 0,
         pressure: costState.pressure,
         shouldStop: costState.shouldStop,
@@ -411,7 +412,8 @@ export function buildCostSnapshot(cost) {
         actualUsd: cost.actualUsd,
         avoidedUsd: cost.avoidedUsd ?? 0,
         tokensIn: cost.tokensIn,
-        tokensOut: cost.tokensOut
+        tokensOut: cost.tokensOut,
+        provenance: cost.provenance ?? "unavailable"
     };
 }
 export function buildBudgetSnapshot(budget) {

package/dist/vendor/adapters/claude-cli.d.ts

@@ -96,7 +96,7 @@ export interface GeminiCliAdapterOptions {
     timeoutMs?: number;
     verifyTimeoutMs?: number;
     label?: string;
-    /** Override the model passed via --model flag. Defaults to the Gemini `flash` alias. */
+    /** Explicit model override passed via --model. Omitted to preserve Gemini Auto. */
     model?: string;
     /** Approval mode for headless Gemini runs. Defaults to yolo for autonomous execution. */
     approvalMode?: "default" | "auto_edit" | "yolo" | "plan";
@@ -135,7 +135,7 @@ export declare function createClaudeCliAdapter(options?: ClaudeCliAdapterOptions
  */
 export declare function createCodexCliAdapter(options?: CodexCliAdapterOptions): MartinAdapter;
 /**
- * Spawns `gemini --model <model> --prompt "" --approval-mode <mode> --output-format json [...]`.
+ * Spawns `gemini [--model <explicit-model>] --prompt "" --approval-mode <mode> --output-format json [...]`.
  *
  * The prompt is delivered via stdin while forcing headless mode with `--prompt ""`,
  * which keeps large MartinLoop prompts off the command line on Windows.