@martinloop/mcp 0.2.5 → 0.2.7

package/dist/tools/logs.d.ts

@@ -0,0 +1,25 @@
+export interface MartinLogsInput {
+    file?: string;
+    loopId?: string;
+    runsDir?: string;
+    latest?: boolean;
+    limit?: number;
+}
+export interface MartinLogsOutput {
+    source: string;
+    sourceKind: "file" | "loop_id" | "latest" | "runs_root";
+    loopId: string;
+    logCount: number;
+    live: {
+        lifecycleState: string;
+        pauseState: "active" | "paused" | "cancellation_requested";
+        approvalState: "not_required" | "resume_requested";
+    };
+    entries: Array<{
+        timestamp?: string;
+        source: "event" | "ledger" | "control";
+        kind: string;
+        payload: Record<string, unknown>;
+    }>;
+}
+export declare function martinLogsTool(input: MartinLogsInput): Promise<MartinLogsOutput>;

package/dist/tools/logs.js

@@ -0,0 +1,49 @@
+import { readRunControlState } from "./run-controls.js";
+import { loadDetailedLoopRecord, readLedgerEvents } from "./run-store.js";
+export async function martinLogsTool(input) {
+    const detail = await loadDetailedLoopRecord(input);
+    const ledgerEvents = await readLedgerEvents(detail);
+    const controls = await readRunControlState(detail);
+    const limit = input.limit ?? 20;
+    const eventEntries = (detail.loop.events ?? []).map((event) => ({
+        timestamp: event.timestamp,
+        source: "event",
+        kind: event.type,
+        payload: event.payload ?? {}
+    }));
+    const ledgerEntries = ledgerEvents.map((event) => ({
+        timestamp: event.timestamp,
+        source: "ledger",
+        kind: event.kind,
+        payload: (event.payload ?? {})
+    }));
+    const controlEntries = controls.receipts.map((receipt) => ({
+        timestamp: receipt.requestedAt,
+        source: "control",
+        kind: `run.${receipt.action}`,
+        payload: {
+            controlId: receipt.controlId,
+            ...(receipt.reason ? { reason: receipt.reason } : {}),
+            ...(receipt.requestedBy ? { requestedBy: receipt.requestedBy } : {})
+        }
+    }));
+    const entries = [...eventEntries, ...ledgerEntries, ...controlEntries]
+        .sort((left, right) => {
+        const leftTime = left.timestamp ? new Date(left.timestamp).getTime() : 0;
+        const rightTime = right.timestamp ? new Date(right.timestamp).getTime() : 0;
+        return rightTime - leftTime;
+    })
+        .slice(0, limit);
+    return {
+        source: detail.source,
+        sourceKind: detail.sourceKind,
+        loopId: detail.loop.loopId,
+        logCount: entries.length,
+        live: {
+            lifecycleState: detail.loop.lifecycleState,
+            pauseState: controls.requestedState,
+            approvalState: controls.approvalState
+        },
+        entries
+    };
+}

package/dist/tools/plan.d.ts

@@ -0,0 +1,20 @@
+import { type MartinPlanProposal, type MartinPolicyPack } from "./workflow-governance.js";
+export interface MartinPlanInput {
+    objective: string;
+    workingDirectory?: string;
+    context?: string;
+    verificationPlan?: string[];
+    allowedPaths?: string[];
+    deniedPaths?: string[];
+    policyPack?: MartinPolicyPack;
+    maxUsd?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+    maxMinutes?: number;
+    maxFilesChanged?: number;
+    maxCommands?: number;
+}
+export interface MartinPlanOutput extends MartinPlanProposal {
+    workingDirectory: string;
+}
+export declare function martinPlanTool(input: MartinPlanInput): Promise<MartinPlanOutput>;

package/dist/tools/plan.js

@@ -0,0 +1,10 @@
+import { resolveSafeRepoRoot } from "../server-validation.js";
+import { buildPlanProposal } from "./workflow-governance.js";
+export async function martinPlanTool(input) {
+    const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
+    const proposal = buildPlanProposal(workingDirectory, input);
+    return {
+        workingDirectory,
+        ...proposal
+    };
+}

package/dist/tools/pr-tools.d.ts

@@ -0,0 +1,31 @@
+import { type MartinRunDossierInput } from "./run-dossier.js";
+export interface MartinPrSummaryOutput {
+    loopId: string;
+    title: string;
+    body: string;
+    grade: string;
+    score: number;
+}
+export interface MartinCreatePrInput extends MartinRunDossierInput {
+    title?: string;
+    base?: string;
+    execute?: boolean;
+}
+export interface MartinCreatePrOutput extends MartinPrSummaryOutput {
+    execute: boolean;
+    created: boolean;
+    url?: string;
+    branch?: string;
+}
+export interface MartinReviewPrInput extends MartinRunDossierInput {
+    prBody?: string;
+}
+export interface MartinReviewPrOutput {
+    loopId: string;
+    verdict: "approve_with_review" | "needs_changes" | "blocked";
+    findings: string[];
+    summary: string;
+}
+export declare function martinPrSummaryTool(input: MartinRunDossierInput): Promise<MartinPrSummaryOutput>;
+export declare function martinCreatePrTool(input: MartinCreatePrInput): Promise<MartinCreatePrOutput>;
+export declare function martinReviewPrTool(input: MartinReviewPrInput): Promise<MartinReviewPrOutput>;

package/dist/tools/pr-tools.js

@@ -0,0 +1,111 @@
+import { spawnSync } from "node:child_process";
+import { loadDetailedLoopRecord } from "./run-store.js";
+import { martinRunDossierTool } from "./run-dossier.js";
+import { martinEvalTool } from "./eval.js";
+import { detectCliAvailability } from "./tool-support.js";
+import { MartinToolError } from "./tool-errors.js";
+export async function martinPrSummaryTool(input) {
+    const dossier = await martinRunDossierTool({ ...input, format: "github-pr" });
+    const evaluation = await martinEvalTool(input);
+    const title = `martin: ${trimForTitle(dossier.loop.objective)}`;
+    const body = dossier.rendered ?? "";
+    return {
+        loopId: dossier.loop.loopId,
+        title,
+        body,
+        grade: evaluation.grade,
+        score: evaluation.score
+    };
+}
+export async function martinCreatePrTool(input) {
+    const summary = await martinPrSummaryTool(input);
+    const detail = await loadDetailedLoopRecord(input);
+    const repoRoot = detail.loop.task?.repoRoot ?? process.cwd();
+    const branch = readGitValue(repoRoot, ["branch", "--show-current"]);
+    const title = input.title?.trim() || summary.title;
+    if (!input.execute) {
+        return {
+            ...summary,
+            title,
+            execute: false,
+            created: false,
+            ...(branch ? { branch } : {})
+        };
+    }
+    const gh = detectCliAvailability("gh");
+    if (!gh.available) {
+        throw new MartinToolError("engine_unavailable", "GitHub CLI is not available on PATH.", {
+            category: "environment",
+            suggestion: "Install gh or rerun martin_create_pr with execute=false to preview the PR body.",
+            retryable: false
+        });
+    }
+    const args = ["pr", "create", "--title", title, "--body", summary.body];
+    if (input.base) {
+        args.push("--base", input.base);
+    }
+    const result = spawnSync("gh", args, {
+        cwd: repoRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (result.status !== 0) {
+        throw new MartinToolError("tool_execution_failed", "GitHub PR creation failed.", {
+            category: "transient",
+            suggestion: (result.stderr || result.stdout || "Check gh auth and branch state.").trim(),
+            retryable: false
+        });
+    }
+    const url = `${result.stdout ?? ""}`.split(/\r?\n/u).map((line) => line.trim()).find(Boolean);
+    return {
+        ...summary,
+        title,
+        execute: true,
+        created: true,
+        ...(url ? { url } : {}),
+        ...(branch ? { branch } : {})
+    };
+}
+export async function martinReviewPrTool(input) {
+    const summary = await martinPrSummaryTool(input);
+    const evaluation = await martinEvalTool(input);
+    const findings = [];
+    if (evaluation.grade === "blocked" || evaluation.grade === "insufficient_evidence") {
+        findings.push("Run evidence is not strong enough for a safe merge decision.");
+    }
+    if (evaluation.checks.verifier !== "passed") {
+        findings.push("Verifier evidence is not green.");
+    }
+    if (evaluation.checks.securityRisk !== "passed") {
+        findings.push("Risk score requires closer human review.");
+    }
+    if (input.prBody && !/MartinLoop Run Dossier/iu.test(input.prBody)) {
+        findings.push("PR body is missing the MartinLoop dossier section.");
+    }
+    const verdict = findings.length === 0
+        ? "approve_with_review"
+        : findings.some((finding) => /not strong enough|not green/iu.test(finding))
+            ? "blocked"
+            : "needs_changes";
+    return {
+        loopId: summary.loopId,
+        verdict,
+        findings,
+        summary: verdict === "approve_with_review"
+            ? "PR evidence looks reviewable."
+            : verdict === "needs_changes"
+                ? "PR needs changes before review is complete."
+                : "PR is blocked by evidence or verifier gaps."
+    };
+}
+function trimForTitle(value) {
+    return value.length > 60 ? `${value.slice(0, 57).trimEnd()}...` : value;
+}
+function readGitValue(cwd, args) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    return result.status === 0 ? result.stdout.trim() || undefined : undefined;
+}

package/dist/tools/preflight.d.ts

@@ -1,12 +1,18 @@
 import { type MartinEngine } from "./tool-support.js";
+import { buildPolicyPackDefinition, type MartinPlanProposal, type MartinPolicyPack, type MartinRiskAssessment, type MartinRunContract } from "./workflow-governance.js";
 export interface MartinPreflightInput {
     objective: string;
     workingDirectory?: string;
     engine?: MartinEngine;
     model?: string;
+    context?: string;
+    policyPack?: MartinPolicyPack;
     maxUsd?: number;
     maxIterations?: number;
     maxTokens?: number;
+    maxMinutes?: number;
+    maxFilesChanged?: number;
+    maxCommands?: number;
     verificationPlan?: string[];
     allowedPaths?: string[];
     deniedPaths?: string[];
@@ -58,5 +64,9 @@ export interface MartinPreflightOutput {
             loopRecordPathPattern: string;
         };
     };
+    policy: ReturnType<typeof buildPolicyPackDefinition>;
+    risk: MartinRiskAssessment;
+    runContract: MartinRunContract;
+    plan: MartinPlanProposal;
 }
 export declare function martinPreflightTool(input: MartinPreflightInput): Promise<MartinPreflightOutput>;

package/dist/tools/preflight.js

@@ -2,9 +2,11 @@ import { DEFAULT_BUDGET } from "../vendor/contracts/index.js";
 import { resolveRunsRoot } from "../vendor/core/index.js";
 import { resolveSafeRepoRoot } from "../server-validation.js";
 import { formatUsd, getEngineAvailability, resolveExecutionMode } from "./tool-support.js";
+import { buildPlanProposal, buildRunContract, buildPolicyPackDefinition, inspectRepoSignals } from "./workflow-governance.js";
 export async function martinPreflightTool(input) {
     const executionMode = resolveExecutionMode();
     const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
+    const signals = inspectRepoSignals(workingDirectory);
     const engine = input.engine ?? "claude";
     const engineAvailability = getEngineAvailability(engine);
     const warnings = [];
@@ -32,11 +34,14 @@ export async function martinPreflightTool(input) {
     if (overlappingScopes.length > 0) {
         warnings.push(`Some path patterns appear in both allowedPaths and deniedPaths: ${overlappingScopes.join(", ")}.`);
     }
+    const plan = buildPlanProposal(workingDirectory, input);
+    const runContract = buildRunContract(workingDirectory, input);
+    const policy = buildPolicyPackDefinition(input.policyPack, signals);
     const ok = !executionMode.liveMode || engineAvailability.available;
     return {
         ok,
         summary: ok
-            ? `Preflight ready for ${engine} in ${workingDirectory} with a ${formatUsd(budget.maxUsd)} budget cap.`
+            ? `Preflight ready for ${engine} in ${workingDirectory} with a ${formatUsd(budget.maxUsd)} budget cap and ${runContract.risk.level} risk.`
             : `Preflight blocked: ${engine} is not available for live execution.`,
         warnings,
         readiness: {
@@ -76,6 +81,10 @@ export async function martinPreflightTool(input) {
                 runDirectoryPattern: "<runsRoot>/<loopId>/",
                 loopRecordPathPattern: "<runsRoot>/<loopId>/loop-record.json"
             }
-        }
+        },
+        policy,
+        risk: runContract.risk,
+        runContract,
+        plan
     };
 }

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

@@ -0,0 +1,36 @@
+import { type DetailedLoopSource } from "./run-store.js";
+export type MartinControlAction = "pause" | "cancel" | "continue";
+export interface MartinRunControlRequestInput {
+    file?: string;
+    loopId?: string;
+    runsDir?: string;
+    latest?: boolean;
+    reason?: string;
+    requestedBy?: string;
+}
+export interface MartinRunControlReceipt {
+    controlId: string;
+    loopId: string;
+    action: MartinControlAction;
+    requestedAt: string;
+    reason?: string;
+    requestedBy?: string;
+}
+export interface MartinRunControlState {
+    requestedState: "active" | "paused" | "cancellation_requested";
+    latestReceipt?: MartinRunControlReceipt;
+    approvalState: "not_required" | "resume_requested";
+    receipts: MartinRunControlReceipt[];
+    receiptPath?: string;
+}
+export interface MartinRunControlOutput {
+    ok: boolean;
+    summary: string;
+    loopId: string;
+    requestedAction: MartinControlAction;
+    state: MartinRunControlState;
+}
+export declare function createRunControlReceipt(action: MartinControlAction, input: MartinRunControlRequestInput): Promise<MartinRunControlOutput>;
+export declare function readRunControlState(detailOrInput: DetailedLoopSource | MartinRunControlRequestInput): Promise<MartinRunControlState>;
+export declare function readControlReceipts(receiptPath: string): Promise<MartinRunControlReceipt[]>;
+export declare function validateControlReason(value?: string): string | undefined;

package/dist/tools/run-controls.js

@@ -0,0 +1,88 @@
+import { appendFile, readFile } from "node:fs/promises";
+import path from "node:path";
+import { invalidArgumentsError, unsupportedOperationError } from "./tool-errors.js";
+import { loadDetailedLoopRecord } from "./run-store.js";
+export async function createRunControlReceipt(action, input) {
+    const detail = await loadDetailedLoopRecord(input);
+    if (!detail.canonicalRunDirectory) {
+        throw unsupportedOperationError("Run control receipts require a canonical run directory.", "Use a canonical loopId-backed Martin run before writing control receipts.");
+    }
+    const receipt = {
+        controlId: `ctl_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+        loopId: detail.loop.loopId,
+        action,
+        requestedAt: new Date().toISOString(),
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.requestedBy ? { requestedBy: input.requestedBy } : {})
+    };
+    const receiptPath = path.join(detail.canonicalRunDirectory, "controls.jsonl");
+    await appendFile(receiptPath, `${JSON.stringify(receipt)}\n`, "utf8");
+    const state = await readRunControlState(detail);
+    return {
+        ok: true,
+        summary: action === "cancel"
+            ? `Cancellation request recorded for ${detail.loop.loopId}.`
+            : action === "pause"
+                ? `Pause request recorded for ${detail.loop.loopId}.`
+                : `Continue request recorded for ${detail.loop.loopId}.`,
+        loopId: detail.loop.loopId,
+        requestedAction: action,
+        state
+    };
+}
+export async function readRunControlState(detailOrInput) {
+    const detail = isDetailedLoopSource(detailOrInput)
+        ? detailOrInput
+        : await loadDetailedLoopRecord(detailOrInput);
+    const receiptPath = detail.canonicalRunDirectory
+        ? path.join(detail.canonicalRunDirectory, "controls.jsonl")
+        : undefined;
+    const receipts = receiptPath ? await readControlReceipts(receiptPath) : [];
+    const latestReceipt = receipts.at(-1);
+    return {
+        requestedState: latestReceipt?.action === "pause"
+            ? "paused"
+            : latestReceipt?.action === "cancel"
+                ? "cancellation_requested"
+                : "active",
+        ...(latestReceipt ? { latestReceipt } : {}),
+        approvalState: latestReceipt?.action === "pause" ? "resume_requested" : "not_required",
+        receipts,
+        ...(receiptPath ? { receiptPath } : {})
+    };
+}
+export async function readControlReceipts(receiptPath) {
+    try {
+        const contents = await readFile(receiptPath, "utf8");
+        return contents
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line))
+            .filter(isRunControlReceipt);
+    }
+    catch {
+        return [];
+    }
+}
+function isDetailedLoopSource(value) {
+    return typeof value === "object" && value !== null && "loop" in value && "runsRoot" in value;
+}
+function isRunControlReceipt(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.controlId === "string" &&
+        typeof value.loopId === "string" &&
+        typeof value.action === "string" &&
+        typeof value.requestedAt === "string");
+}
+export function validateControlReason(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw invalidArgumentsError("Invalid reason.");
+    }
+    return trimmed;
+}

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

@@ -1,9 +1,13 @@
 import { buildArtifactSummary, buildBudgetSnapshot, buildCostSnapshot, buildEventSummaries, buildLoopPreview, buildVerificationSummary } from "./tool-support.js";
+import { readRunControlState } from "./run-controls.js";
+import { martinEvalTool } from "./eval.js";
+import { assessRunRisk } from "./workflow-governance.js";
 export interface MartinRunDossierInput {
     file?: string;
     loopId?: string;
     runsDir?: string;
     latest?: boolean;
+    format?: "json" | "md" | "github-pr";
 }
 export interface MartinRunDossierOutput {
     source: string;
@@ -30,6 +34,16 @@ export interface MartinRunDossierOutput {
         resources: string[];
         prompts: string[];
     };
+    review: {
+        diffSummary: string;
+        risk: ReturnType<typeof assessRunRisk>;
+        outcome: "passed" | "failed" | "needs_review";
+        nextAction: string;
+    };
+    evaluation: Awaited<ReturnType<typeof martinEvalTool>>;
+    control: Awaited<ReturnType<typeof readRunControlState>>;
+    format: "json" | "md" | "github-pr";
+    rendered?: string;
     inspection: {
         runsRoot: string;
         canonicalRunDirectory?: string;

package/dist/tools/run-dossier.js

@@ -1,9 +1,22 @@
 import { buildArtifactSummary, buildBudgetSnapshot, buildCostSnapshot, buildEventSummaries, buildLoopPreview, buildSuggestedPromptNames, buildSuggestedResourceUris, buildVerificationSummary } from "./tool-support.js";
 import { loadDetailedLoopRecord, readAttemptArtifactFiles, readLedgerEvents } from "./run-store.js";
+import { readRunControlState } from "./run-controls.js";
+import { martinEvalTool } from "./eval.js";
+import { assessRunRisk, inspectRepoSignals } from "./workflow-governance.js";
 export async function martinRunDossierTool(input) {
     const detail = await loadDetailedLoopRecord(input);
     const ledgerEvents = await readLedgerEvents(detail);
     const verification = buildVerificationSummary(detail.loop, ledgerEvents);
+    const control = await readRunControlState(detail);
+    const evaluation = await martinEvalTool(input);
+    const repoRoot = detail.loop.task?.repoRoot ?? process.cwd();
+    const risk = assessRunRisk({
+        objective: detail.loop.task?.objective ?? detail.loop.loopId,
+        allowedPaths: detail.loop.task?.allowedPaths ?? [],
+        blockedPaths: detail.loop.task?.deniedPaths ?? [],
+        verifiers: detail.loop.task?.verificationPlan ?? [],
+        signals: inspectRepoSignals(repoRoot)
+    });
     const attempts = await Promise.all(detail.loop.attempts.map(async (attempt) => ({
         index: attempt.index,
         ...(attempt.attemptId ? { attemptId: attempt.attemptId } : {}),
@@ -16,7 +29,23 @@ export async function martinRunDossierTool(input) {
         ...(attempt.summary ? { summary: attempt.summary } : {}),
         artifactFiles: await readAttemptArtifactFiles(detail, attempt.index)
     })));
-    return {
+    const review = {
+        diffSummary: attempts.length > 0
+            ? `Run touched ${attempts.length} attempt(s); latest summary: ${attempts.at(-1)?.summary ?? "No attempt summary recorded."}`
+            : "No attempts were recorded for this run.",
+        risk,
+        outcome: verification.status === "passed"
+            ? "passed"
+            : verification.status === "failed"
+                ? "failed"
+                : "needs_review",
+        nextAction: verification.status === "passed"
+            ? "Review the dossier and evaluation, then decide whether to merge or promote."
+            : verification.status === "failed"
+                ? "Investigate the latest verifier failure before retrying or promoting."
+                : "Collect more evidence before claiming completion."
+    };
+    const output = {
         source: detail.source,
         sourceKind: detail.sourceKind,
         loop: buildLoopPreview(detail.loop),
@@ -30,6 +59,10 @@ export async function martinRunDossierTool(input) {
             resources: buildSuggestedResourceUris(detail.loop.loopId),
             prompts: buildSuggestedPromptNames()
         },
+        review,
+        evaluation,
+        control,
+        format: input.format ?? "json",
         inspection: {
             runsRoot: detail.runsRoot,
             ...(detail.canonicalRunDirectory ? { canonicalRunDirectory: detail.canonicalRunDirectory } : {}),
@@ -38,4 +71,31 @@ export async function martinRunDossierTool(input) {
         },
         warnings: [...detail.warnings, ...verification.warnings]
     };
+    if (output.format !== "json") {
+        output.rendered = renderDossier(output);
+    }
+    return output;
+}
+function renderDossier(output) {
+    const lines = [
+        output.format === "github-pr" ? "## MartinLoop Run Dossier" : "# MartinLoop Run Dossier",
+        "",
+        `Objective: ${output.loop.objective}`,
+        `Run: ${output.loop.loopId}`,
+        `Status: ${output.loop.status} / ${output.loop.lifecycleState}`,
+        `Attempts: ${output.attempts.length}`,
+        `Verifiers: ${output.verification.status}`,
+        `Risk: ${output.review.risk.level} (${output.review.risk.score})`,
+        `Allowed paths: ${output.review.risk.reasons.length > 0 ? output.review.risk.reasons.join("; ") : "No major risk reasons recorded."}`,
+        "",
+        "Review Summary:",
+        output.review.diffSummary,
+        "",
+        "Next Action:",
+        output.review.nextAction
+    ];
+    if (output.format === "github-pr") {
+        lines.push("", `Evaluation: ${output.evaluation.grade} (${output.evaluation.score})`);
+    }
+    return lines.join("\n");
 }

package/dist/tools/run-loop.js

@@ -2,6 +2,7 @@ import { createClaudeCliAdapter, createCodexCliAdapter, createStubDirectProvider
 import { createFileRunStore, evaluateCostGovernor, resolveRunsRoot, runMartin } from "../vendor/core/index.js";
 import { DEFAULT_BUDGET } from "../vendor/contracts/index.js";
 import { normalizeSafePathPatterns, resolveSafeRepoRoot } from "../server-validation.js";
+import { evaluateMcpRunGate } from "../workflow-state.js";
 import { MartinToolError } from "./tool-errors.js";
 import { buildArtifactSummary, buildVerificationSummary, buildLoopPreview, buildRunRecordPaths, getEngineAvailability, resolveExecutionMode } from "./tool-support.js";
 export async function runLoopTool(input) {
@@ -12,6 +13,25 @@ export async function runLoopTool(input) {
     const deniedPaths = normalizeSafePathPatterns(input.deniedPaths, "deniedPaths");
     const executionMode = resolveExecutionMode();
     const engineAvailability = getEngineAvailability(engine);
+    const runsRoot = resolveRunsRoot(process.env);
+    const gate = await evaluateMcpRunGate({
+        runsRoot,
+        workingDirectory,
+        objective: input.objective,
+        engine,
+        verificationPlan: input.verificationPlan
+    });
+    if (!gate.allowed) {
+        throw new MartinToolError("policy_blocked", gate.summary, {
+            category: "policy_blocked",
+            suggestion: gate.nextAction,
+            retryable: false,
+            details: {
+                missingSteps: gate.missingSteps,
+                nextAction: gate.nextAction
+            }
+        });
+    }
     if (executionMode.liveMode && !engineAvailability.available) {
         throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
             category: "environment",
@@ -41,7 +61,7 @@ export async function runLoopTool(input) {
     const result = await runMartin({
         workspaceId: input.workspaceId ?? "ws_mcp",
         projectId: input.projectId ?? "proj_mcp",
-        store: createFileRunStore({ runsRoot: resolveRunsRoot(process.env) }),
+        store: createFileRunStore({ runsRoot }),
         task: {
             title: input.objective.slice(0, 100),
             objective: input.objective,
@@ -65,7 +85,6 @@ export async function runLoopTool(input) {
         },
         attemptsUsed: result.loop.attempts.length
     });
-    const runsRoot = resolveRunsRoot(process.env);
     const recordPaths = buildRunRecordPaths(runsRoot, result.loop.loopId);
     const verification = buildVerificationSummary(result.loop);
     const artifacts = buildArtifactSummary(result.loop);

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

@@ -1,5 +1,5 @@
 import type { MartinErrorCategory } from "../vendor/contracts/index.js";
-export type ToolFailureCode = "attempt_not_found" | "engine_unavailable" | "invalid_arguments" | "invalid_json" | "invalid_path" | "invalid_selector" | "no_loop_records" | "store_unreadable" | "tool_execution_failed" | "unknown_tool" | "unsupported_operation";
+export type ToolFailureCode = "attempt_not_found" | "engine_unavailable" | "invalid_arguments" | "invalid_json" | "invalid_path" | "invalid_selector" | "no_loop_records" | "policy_blocked" | "store_unreadable" | "tool_execution_failed" | "unknown_tool" | "unsupported_operation";
 export type ToolFailureCategory = MartinErrorCategory;
 export interface ToolFailure {
     code: ToolFailureCode;