@martinloop/mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,59 +1,199 @@
 # @martinloop/mcp
-
-Martin Loop's installable Model Context Protocol server.
-
-It exposes three MCP tools over stdio:
-
-- `martin_run`
-- `martin_inspect`
-- `martin_status`
-
-## Quickstart
-
+
+Governed MCP server for AI coding agents that need hard spend limits, verifier gates, scoped file edits, and inspectable run records.
+
+`@martinloop/mcp` exposes three stdio tools:
+
+- `martin_run`
+- `martin_inspect`
+- `martin_status`
+
+## What This Server Is For
+
+Use this MCP when a host already knows how to delegate coding work, but you want Martin Loop to bound that work with:
+
+- a hard budget ceiling (`maxUsd`)
+- an attempt ceiling (`maxIterations`)
+- a total token ceiling (`maxTokens`)
+- verifier commands (`verificationPlan`)
+- allowed and denied file globs
+- persisted run records you can inspect afterward
+
+It is a good fit for Claude Code, Codex-oriented hosts, and other MCP clients that want governed code-change execution instead of open-ended retry behavior.
+
+For host-facing integration guidance, see [MCP for AI Agents](https://github.com/Keesan12/martin-loop/blob/main/docs/oss/MCP-FOR-AI-AGENTS.md).
+
+## Quickstart
+
 Run the packaged server directly:
 
 ```sh
-npx @martinloop/mcp
+npx -y @martinloop/mcp
 ```
 
 Add it to Claude Code:
 
 ```sh
 # macOS/Linux
-claude mcp add --scope user martin-loop -- npx @martinloop/mcp
+claude mcp add --scope user martin-loop -- npx -y @martinloop/mcp
 
 # Windows PowerShell/cmd
-claude mcp add --scope user martin-loop cmd /c "npx @martinloop/mcp"
+claude mcp add --scope user martin-loop cmd /c "npx -y @martinloop/mcp"
+```
+
+Generic stdio configuration:
+
+```json
+{
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@martinloop/mcp"]
+}
+```
+
+Codex host configuration in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.martin-loop]
+command = "npx"
+args = ["-y", "@martinloop/mcp"]
+```
+
+## Requirements
+
+- Node 20+
+- For live `martin_run` usage, either the `claude` CLI or the `codex` CLI must be available on `PATH`
+- For stub or smoke flows, set `MARTIN_LIVE=false`
+
+Example stub launch:
+
+```sh
+MARTIN_LIVE=false npx -y @martinloop/mcp
+```
+
+## Tool Contract
+
+| Tool | Purpose | Required input | Important optional input | Notes |
+| --- | --- | --- | --- | --- |
+| `martin_run` | Run a governed coding loop | `objective` | `workingDirectory`, `engine`, `model`, `maxUsd`, `maxIterations`, `maxTokens`, `verificationPlan`, `allowedPaths`, `deniedPaths`, `workspaceId`, `projectId` | Unknown arguments are rejected. |
+| `martin_inspect` | Read a saved run record or run folder | none | `file`, `runsDir` | `file` may point to a `loop-record.json`, legacy `.jsonl`, or a run directory under the runs root. |
+| `martin_status` | Report budget pressure and stop conditions | exactly one of `loopJson`, `file`, `loopId`, or `latest` | `runsDir` | `latest` must be `true` when used. |
+
+## Safe-Root Path Model
+
+This MCP does not let tool callers point at arbitrary filesystem locations. The server resolves tool paths against safe roots chosen when the server starts.
+
+- `workingDirectory`
+  Defaults to `MARTIN_MCP_WORKSPACE_ROOT` or the server process current directory. If you pass a value, it must still resolve inside that workspace root. `.` and repo-relative subpaths are the safest choices.
+- `file`
+  For `martin_inspect` and `martin_status`, `file` resolves under the runs root, not the whole machine. Direct file targets must end in `.json` or `.jsonl`; run directories are also accepted where the tool supports them.
+- `runsDir`
+  Defaults to `MARTIN_RUNS_DIR` or `~/.martin/runs`. Passing `runsDir` only re-states or narrows that safe runs root; it does not grant access outside it.
+- `allowedPaths` and `deniedPaths`
+  These are relative glob patterns only. Absolute paths, drive-qualified paths, and patterns containing `..` are rejected.
+
+Absolute paths can work only when they still resolve inside the corresponding safe root. Escapes above the workspace or runs root are rejected.
+
+## Tool Examples
+
+### `martin_run`
+
+```json
+{
+  "objective": "Fix the auth regression and prove it with tests",
+  "engine": "codex",
+  "maxUsd": 3,
+  "maxIterations": 3,
+  "maxTokens": 20000,
+  "verificationPlan": ["pnpm test --filter auth"],
+  "workingDirectory": ".",
+  "allowedPaths": ["src/**", "tests/**"],
+  "deniedPaths": [".env*", "secrets/**"]
+}
+```
+
+### `martin_inspect`
+
+Inspect the default runs root:
+
+```json
+{}
+```
+
+Inspect a specific saved loop record under the runs root:
+
+```json
+{
+  "file": "loop-123/loop-record.json"
+}
+```
+
+Inspect a subdirectory under the configured runs root:
+
+```json
+{
+  "runsDir": "team-a"
+}
+```
+
+### `martin_status`
+
+Status for the latest saved run:
+
+```json
+{
+  "latest": true
+}
+```
+
+Status for a specific persisted loop:
+
+```json
+{
+  "loopId": "loop-123"
+}
+```
+
+Status from inline JSON:
+
+```json
+{
+  "loopJson": "{\"loopId\":\"loop-123\",\"status\":\"completed\",\"lifecycleState\":\"completed\",\"attempts\":[],\"budget\":{\"maxUsd\":5,\"softLimitUsd\":3,\"maxIterations\":2,\"maxTokens\":1000},\"cost\":{\"actualUsd\":1.25,\"avoidedUsd\":0,\"tokensIn\":20,\"tokensOut\":10}}"
+}
 ```
 
-For clients that want explicit command/args:
+## Registry Metadata
+
+The registry manifest artifact for this package is `server.json`. In this repository, that manifest is authored at `packages/mcp/server.json`.
+
+Current metadata:
 
-- Command: `npx`
-- Args: `@martinloop/mcp`
-
-## Official MCP Registry
-
-This package is prepared for the official MCP Registry metadata flow:
-
 - npm package: `@martinloop/mcp`
-- registry server name: `io.github.keesan12/martin-loop`
-- manifest file: `packages/mcp/server.json`
-
-The official registry publish flow is separate from npm publication. After publishing the package to npm, run the publisher from `packages/mcp`:
-
-```sh
-mcp-publisher login github
-mcp-publisher publish
-```
-
-## Local Verification
-
-From the repository root:
-
-```sh
-pnpm --filter @martinloop/mcp build
+- registry server name: `io.github.keesan12/martin-loop`
+- manifest artifact name: `server.json`
+
+Official MCP Registry publication is separate from npm publication. After publishing the package to npm, run the publisher from `packages/mcp`:
+
+```sh
+mcp-publisher login github
+mcp-publisher publish
+```
+
+## Verification
+
+From the repository root:
+
+```sh
+pnpm --filter @martinloop/mcp lint
 pnpm --filter @martinloop/mcp test
+pnpm --filter @martinloop/mcp build
 pnpm --filter @martinloop/mcp smoke:pack
-```
-
-`smoke:pack` packs the tarball, launches it through `npx`, performs the MCP handshake, lists tools, and verifies a `martin_status` call.
+pnpm --filter @martinloop/mcp smoke:published
+```
+
+- `smoke:pack` verifies the packed tarball shape and a stdio MCP launch
+- `smoke:published` verifies the npm-installed artifact through `npm install` plus live MCP tool calls
+
+## Version Notes
+
+The root `CHANGELOG.md` is repo-wide and includes non-MCP changes. For the `@martinloop/mcp` surface, prefer this README, `server.json`, and the MCP release notes under `docs/release/`.

package/dist/server-validation.d.ts

@@ -0,0 +1,10 @@
+type ToolName = "martin_run" | "martin_inspect" | "martin_status";
+export declare function validateToolInput(name: ToolName, args: unknown): unknown;
+export declare function sanitizeToolErrorMessage(error: unknown): string;
+export declare function resolveSafeRepoRoot(repoRoot?: string, workspaceRoot?: string): string;
+export declare function resolveSafeRunsJsonPath(file: string, runsRoot?: string): string;
+export declare function resolveSafeRunsPath(file: string, runsRoot?: string): string;
+export declare function resolveSafeRunsRootPath(runsRoot?: string, fallbackRunsRoot?: string): string;
+export declare function resolveSafeLoopRecordPath(loopId: string, runsRoot?: string): string;
+export declare function normalizeSafePathPatterns(value: unknown, name: string): string[] | undefined;
+export {};

package/dist/server-validation.js

@@ -0,0 +1,234 @@
+import { extname, isAbsolute, relative, resolve } from "node:path";
+import { resolveRunsRoot } from "./vendor/core/index.js";
+export function validateToolInput(name, args) {
+    switch (name) {
+        case "martin_run":
+            return validateRunInput(args);
+        case "martin_inspect":
+            return validateInspectInput(args);
+        case "martin_status":
+            return validateStatusInput(args);
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+export function sanitizeToolErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /([A-Za-z]:\\|\/|policy\.rego|policy\.wasm|\.pem|\.env)/u.test(message)
+        ? "Tool execution failed."
+        : message;
+}
+export function resolveSafeRepoRoot(repoRoot, workspaceRoot = process.env.MARTIN_MCP_WORKSPACE_ROOT ?? process.cwd()) {
+    const baseRoot = resolve(workspaceRoot);
+    const candidate = repoRoot ? resolve(baseRoot, repoRoot) : baseRoot;
+    assertPathWithinRoot(candidate, baseRoot, "workingDirectory");
+    return candidate;
+}
+export function resolveSafeRunsJsonPath(file, runsRoot = resolveRunsRoot(process.env)) {
+    const baseRoot = resolve(runsRoot);
+    const candidate = resolve(baseRoot, file);
+    assertPathWithinRoot(candidate, baseRoot, "file");
+    const extension = extname(candidate).toLowerCase();
+    if (extension !== ".json" && extension !== ".jsonl") {
+        throw new Error("Invalid file.");
+    }
+    return candidate;
+}
+export function resolveSafeRunsPath(file, runsRoot = resolveRunsRoot(process.env)) {
+    const baseRoot = resolve(runsRoot);
+    const candidate = resolve(baseRoot, file);
+    assertPathWithinRoot(candidate, baseRoot, "file");
+    const extension = extname(candidate).toLowerCase();
+    if (extension && extension !== ".json" && extension !== ".jsonl") {
+        throw new Error("Invalid file.");
+    }
+    return candidate;
+}
+export function resolveSafeRunsRootPath(runsRoot, fallbackRunsRoot = resolveRunsRoot(process.env)) {
+    const baseRoot = resolve(fallbackRunsRoot);
+    const candidate = runsRoot ? resolve(baseRoot, runsRoot) : baseRoot;
+    assertPathWithinRoot(candidate, baseRoot, "runsDir");
+    return candidate;
+}
+export function resolveSafeLoopRecordPath(loopId, runsRoot = resolveRunsRoot(process.env)) {
+    const normalizedLoopId = requireLoopId(loopId, "loopId");
+    return resolveSafeRunsJsonPath(`${normalizedLoopId}/loop-record.json`, runsRoot);
+}
+export function normalizeSafePathPatterns(value, name) {
+    const paths = optionalStringArray(value, name);
+    if (!paths) {
+        return undefined;
+    }
+    return paths.map((pattern) => {
+        const normalized = pattern.replace(/\\/gu, "/").trim();
+        if (normalized.length === 0 ||
+            normalized.startsWith("/") ||
+            /^[A-Za-z]:\//u.test(normalized) ||
+            normalized.split("/").includes("..")) {
+            throw new Error(`Invalid ${name}.`);
+        }
+        return normalized;
+    });
+}
+function validateRunInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, [
+        "objective",
+        "workingDirectory",
+        "engine",
+        "model",
+        "maxUsd",
+        "maxIterations",
+        "maxTokens",
+        "verificationPlan",
+        "allowedPaths",
+        "deniedPaths",
+        "workspaceId",
+        "projectId"
+    ]);
+    const engine = optionalEnum(record.engine, "engine", ["claude", "codex"]);
+    return {
+        objective: requireString(record.objective, "objective"),
+        ...(record.workingDirectory !== undefined
+            ? { workingDirectory: resolveSafeRepoRoot(requireString(record.workingDirectory, "workingDirectory")) }
+            : {}),
+        ...(engine ? { engine } : {}),
+        ...optionalString(record.model, "model"),
+        ...optionalPositiveNumber(record.maxUsd, "maxUsd"),
+        ...optionalPositiveInteger(record.maxIterations, "maxIterations"),
+        ...optionalPositiveInteger(record.maxTokens, "maxTokens"),
+        ...optionalStringArrayAsObject(record.verificationPlan, "verificationPlan"),
+        ...optionalPathPatternArrayAsObject(record.allowedPaths, "allowedPaths"),
+        ...optionalPathPatternArrayAsObject(record.deniedPaths, "deniedPaths"),
+        ...optionalString(record.workspaceId, "workspaceId"),
+        ...optionalString(record.projectId, "projectId")
+    };
+}
+function validateInspectInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["file", "runsDir"]);
+    return {
+        ...(record.file !== undefined
+            ? { file: resolveSafeRunsPath(requireString(record.file, "file")) }
+            : {}),
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {})
+    };
+}
+function validateStatusInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["loopJson", "file", "loopId", "runsDir", "latest"]);
+    const selectors = [
+        record.loopJson !== undefined ? "loopJson" : null,
+        record.file !== undefined ? "file" : null,
+        record.loopId !== undefined ? "loopId" : null,
+        record.latest !== undefined ? "latest" : null
+    ].filter((value) => value !== null);
+    if (selectors.length !== 1) {
+        throw new Error("Provide exactly one of loopJson, file, loopId, or latest.");
+    }
+    if (record.latest !== undefined && record.latest !== true) {
+        throw new Error("Invalid latest.");
+    }
+    return {
+        ...(record.loopJson !== undefined
+            ? { loopJson: requireString(record.loopJson, "loopJson") }
+            : {}),
+        ...(record.file !== undefined
+            ? { file: resolveSafeRunsPath(requireString(record.file, "file")) }
+            : {}),
+        ...(record.loopId !== undefined
+            ? { loopId: requireLoopId(record.loopId, "loopId") }
+            : {}),
+        ...(record.runsDir !== undefined
+            ? { runsDir: resolveSafeRunsRootPath(requireString(record.runsDir, "runsDir")) }
+            : {}),
+        ...(record.latest === true ? { latest: true } : {})
+    };
+}
+function requireObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Tool arguments must be an object.");
+    }
+    return value;
+}
+function assertAllowedKeys(record, allowed) {
+    const unknownKeys = Object.keys(record).filter((key) => !allowed.includes(key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`Unknown arguments: ${unknownKeys.join(", ")}`);
+    }
+}
+function assertPathWithinRoot(candidatePath, rootPath, name) {
+    const relativePath = relative(rootPath, candidatePath);
+    if (relativePath === "" || relativePath === ".") {
+        return;
+    }
+    if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+        throw new Error(`Invalid ${name}.`);
+    }
+}
+function requireString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Invalid ${name}.`);
+    }
+    return value.trim();
+}
+function requireLoopId(value, name) {
+    const loopId = requireString(value, name);
+    if (!/^[A-Za-z0-9._-]+$/u.test(loopId)) {
+        throw new Error(`Invalid ${name}.`);
+    }
+    return loopId;
+}
+function optionalString(value, name) {
+    if (value === undefined) {
+        return {};
+    }
+    return { [name]: requireString(value, name) };
+}
+function optionalPositiveNumber(value, name) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`Invalid ${name}.`);
+    }
+    return { [name]: value };
+}
+function optionalPositiveInteger(value, name) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`Invalid ${name}.`);
+    }
+    return { [name]: value };
+}
+function optionalStringArray(value, name) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`Invalid ${name}.`);
+    }
+    return value.map((item) => requireString(item, name));
+}
+function optionalStringArrayAsObject(value, name) {
+    const values = optionalStringArray(value, name);
+    return values ? { [name]: values } : {};
+}
+function optionalPathPatternArrayAsObject(value, name) {
+    const values = normalizeSafePathPatterns(value, name);
+    return values ? { [name]: values } : {};
+}
+function optionalEnum(value, name, allowed) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        throw new Error(`Invalid ${name}.`);
+    }
+    return value;
+}
+//# sourceMappingURL=server-validation.js.map

package/dist/server.js

@@ -17,13 +17,17 @@
  * Manual start:
  *   node dist/server.js
  */
+import { createRequire } from "node:module";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { getStatusTool } from "./tools/get-status.js";
 import { inspectLoopTool } from "./tools/inspect-loop.js";
 import { runLoopTool } from "./tools/run-loop.js";
-const server = new Server({ name: "martin-loop", version: "0.1.1" }, { capabilities: { tools: {} } });
+import { sanitizeToolErrorMessage, validateToolInput } from "./server-validation.js";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+const server = new Server({ name: "martin-loop", version: packageJson.version }, { capabilities: { tools: {} } });
 // ---------------------------------------------------------------------------
 // Tool manifest
 // ---------------------------------------------------------------------------
@@ -34,6 +38,7 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
             description: "Execute a full Martin Loop on a coding task. Martin spawns the selected agent CLI (claude or codex), runs the task, classifies failures, and retries within the specified budget. Returns the loop outcome including lifecycle state, attempt count, and spend.",
             inputSchema: {
                 type: "object",
+                additionalProperties: false,
                 properties: {
                     objective: {
                         type: "string",
@@ -41,7 +46,7 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                     },
                     workingDirectory: {
                         type: "string",
-                        description: "Absolute path to the project root. Defaults to the current working directory."
+                        description: "Optional repo-root override resolved under the MCP workspace root (or current working directory). Must stay within that safe root."
                     },
                     engine: {
                         type: "string",
@@ -54,14 +59,17 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                     },
                     maxUsd: {
                         type: "number",
+                        exclusiveMinimum: 0,
                         description: "Hard budget ceiling in USD. Defaults to 25."
                     },
                     maxIterations: {
-                        type: "number",
+                        type: "integer",
+                        exclusiveMinimum: 0,
                         description: "Maximum number of loop attempts. Defaults to 8."
                     },
                     maxTokens: {
-                        type: "number",
+                        type: "integer",
+                        exclusiveMinimum: 0,
                         description: "Maximum total tokens across all attempts. Defaults to 80000."
                     },
                     verificationPlan: {
@@ -69,6 +77,16 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
                         items: { type: "string" },
                         description: "Shell commands that must all exit 0 for the task to be considered complete (e.g. ['pnpm test', 'pnpm build'])."
                     },
+                    allowedPaths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Repo-relative path globs Martin may modify, such as ['src/**', 'tests/**']. Absolute paths and '..' traversal are rejected."
+                    },
+                    deniedPaths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Repo-relative path globs Martin must never modify, such as ['.env', 'docs/security/**']. Absolute paths and '..' traversal are rejected."
+                    },
                     workspaceId: {
                         type: "string",
                         description: "Workspace identifier for telemetry. Defaults to 'ws_mcp'."
@@ -83,30 +101,56 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
         },
         {
             name: "martin_inspect",
-            description: "Summarise a saved Martin loop record file. Reads a JSON file containing one or more LoopRecords and returns portfolio-level statistics: total spend, avoided spend, token counts, and loop counts.",
+            description: "Summarise Martin Loop run records from a saved loop file or run-store directory. Supports canonical loop-record.json files, legacy JSONL files, and full runs directories.",
             inputSchema: {
                 type: "object",
+                additionalProperties: false,
                 properties: {
                     file: {
                         type: "string",
-                        description: "Absolute or relative path to a LoopRecord JSON file."
+                        description: "Optional path resolved under the Martin runs root to a loop-record.json file, a legacy .jsonl file, or a run-store directory."
+                    },
+                    runsDir: {
+                        type: "string",
+                        description: "Optional runs-root override resolved under the default Martin runs root. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs."
                     }
-                },
-                required: ["file"]
+                }
             }
         },
         {
             name: "martin_status",
-            description: "Return the current budget and cost state of a Martin loop record. Useful for monitoring in-progress or completed loops.",
+            description: "Return the current budget and cost state of a Martin loop record. Accepts inline JSON, a saved loop file, a loopId under the run store, or the latest run in the store.",
             inputSchema: {
                 type: "object",
+                additionalProperties: false,
                 properties: {
                     loopJson: {
                         type: "string",
                         description: "JSON-serialized LoopRecord."
+                    },
+                    file: {
+                        type: "string",
+                        description: "Optional path resolved under the Martin runs root to a loop-record.json file, a legacy .jsonl file, or a run-store directory."
+                    },
+                    loopId: {
+                        type: "string",
+                        description: "Optional Martin loop ID. Loads <runsDir>/<loopId>/loop-record.json."
+                    },
+                    runsDir: {
+                        type: "string",
+                        description: "Optional runs-root override resolved under the default Martin runs root. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs."
+                    },
+                    latest: {
+                        const: true,
+                        description: "When true, loads the most recently updated loop record in the runs directory."
                     }
                 },
-                required: ["loopJson"]
+                oneOf: [
+                    { required: ["loopJson"] },
+                    { required: ["file"] },
+                    { required: ["loopId"] },
+                    { required: ["latest"] }
+                ]
             }
         }
     ]
@@ -118,18 +162,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
         if (name === "martin_run") {
-            const input = args;
+            const input = validateToolInput("martin_run", args);
             const output = await runLoopTool(input);
             return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
         }
         if (name === "martin_inspect") {
-            const input = args;
+            const input = validateToolInput("martin_inspect", args);
             const output = await inspectLoopTool(input);
             return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
         }
         if (name === "martin_status") {
-            const input = args;
-            const output = getStatusTool(input);
+            const input = validateToolInput("martin_status", args);
+            const output = await getStatusTool(input);
             return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
         }
         return {
@@ -138,7 +182,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = sanitizeToolErrorMessage(error);
         return {
             content: [{ type: "text", text: `Tool error: ${message}` }],
             isError: true

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

@@ -1,6 +1,14 @@
 export interface GetStatusInput {
     /** JSON-serialized LoopRecord. */
-    loopJson: string;
+    loopJson?: string;
+    /** Optional path to a JSON, JSONL, or run-store directory under the Martin runs root. */
+    file?: string;
+    /** Optional loop identifier under the Martin runs root. */
+    loopId?: string;
+    /** Optional Martin runs directory. Defaults to MARTIN_RUNS_DIR or ~/.martin/runs. */
+    runsDir?: string;
+    /** Load the newest loop record from the runs directory. */
+    latest?: boolean;
 }
 export interface GetStatusOutput {
     loopId: string;
@@ -15,4 +23,4 @@ export interface GetStatusOutput {
     remainingIterations: number;
     remainingTokens: number;
 }
-export declare function getStatusTool(input: GetStatusInput): GetStatusOutput;
+export declare function getStatusTool(input: GetStatusInput): Promise<GetStatusOutput>;