@flyingrobots/graft 0.4.0 → 0.5.0

package/src/mcp/tools/precision.ts

@@ -0,0 +1,312 @@
+import * as path from "node:path";
+import type WarpApp from "@git-stunts/git-warp";
+import { getFileAtRef, GitError } from "../../git/diff.js";
+import { detectLang } from "../../parser/lang.js";
+import { extractOutline } from "../../parser/outline.js";
+import type { JumpEntry, OutlineEntry } from "../../parser/types.js";
+import { allSymbolsLens, fileSymbolsLens, symbolByNameLens } from "../../warp/observers.js";
+import type { GitClient } from "../../ports/git.js";
+import type { ToolContext } from "../context.js";
+import { evaluateMcpRefusal, type McpPolicyRefusal } from "../policy.js";
+import { PrecisionSearchRequest, type RankedPrecisionSymbolMatch } from "./precision-query.js";
+import { PrecisionSymbolMatch } from "./precision-match.js";
+
+const MAX_RANGE_LINES = 250;
+
+export { PrecisionSearchRequest } from "./precision-query.js";
+export { PrecisionSymbolMatch } from "./precision-match.js";
+export type PrecisionPolicyRefusal = McpPolicyRefusal;
+
+async function git(gitClient: GitClient, args: readonly string[], cwd: string): Promise<string> {
+  const result = await gitClient.run({ args, cwd });
+  if (result.error !== undefined || result.status !== 0) {
+    throw result.error ?? new Error(result.stderr.trim() || `git exited with status ${String(result.status)}`);
+  }
+  return result.stdout;
+}
+
+function buildJumpLookup(
+  jumpTable: readonly JumpEntry[],
+): Map<string, { start: number; end: number }[]> {
+  const lookup = new Map<string, { start: number; end: number }[]>();
+  for (const entry of jumpTable) {
+    const existing = lookup.get(entry.symbol) ?? [];
+    existing.push({ start: entry.start, end: entry.end });
+    lookup.set(entry.symbol, existing);
+  }
+  return lookup;
+}
+
+function decodeSymbolPath(nodeId: string): string | null {
+  if (!nodeId.startsWith("sym:")) return null;
+  const lastColon = nodeId.lastIndexOf(":");
+  if (lastColon <= "sym:".length) return null;
+  return nodeId.slice("sym:".length, lastColon);
+}
+
+function toMatch(
+  nodeId: string,
+  props: Record<string, unknown>,
+): PrecisionSymbolMatch | null {
+  const name = props["name"];
+  const kind = props["kind"];
+  const path = decodeSymbolPath(nodeId);
+  if (typeof name !== "string" || typeof kind !== "string" || path === null) {
+    return null;
+  }
+
+  return new PrecisionSymbolMatch({
+    name,
+    kind,
+    path,
+    ...(typeof props["signature"] === "string" ? { signature: props["signature"] } : {}),
+    exported: props["exported"] === true,
+    ...(typeof props["startLine"] === "number" ? { startLine: props["startLine"] } : {}),
+    ...(typeof props["endLine"] === "number" ? { endLine: props["endLine"] } : {}),
+  });
+}
+
+
+export function normalizeRepoPath(projectRoot: string, input: string): string {
+  if (!path.isAbsolute(input)) return input;
+  const rel = path.relative(projectRoot, input);
+  if (rel === "") return ".";
+  return rel.startsWith("..") ? input : rel;
+}
+
+export function requireRepoPath(projectRoot: string, input: string): string {
+  const normalized = normalizeRepoPath(projectRoot, input);
+  if (path.isAbsolute(normalized)) {
+    throw new Error(`Path must be inside the repository for git-ref queries: ${input}`);
+  }
+  return normalized;
+}
+
+export async function resolveGitRef(ref: string, gitClient: GitClient, cwd: string): Promise<string> {
+  try {
+    return (await git(gitClient, ["rev-parse", "--verify", ref], cwd)).trim();
+  } catch {
+    throw new GitError(`ref does not exist: ${ref}`);
+  }
+}
+
+export async function listTrackedFilesAtRef(
+  dirPath: string,
+  gitClient: GitClient,
+  cwd: string,
+  ref: string,
+): Promise<string[]> {
+  try {
+    const args = dirPath.length > 0
+      ? ["ls-tree", "-r", "--name-only", ref, "--", dirPath]
+      : ["ls-tree", "-r", "--name-only", ref];
+    const output = (await git(gitClient, args, cwd)).trim();
+    return output.length === 0 ? [] : output.split("\n");
+  } catch {
+    return [];
+  }
+}
+
+export async function isWorkingTreeDirty(gitClient: GitClient, cwd: string): Promise<boolean> {
+  try {
+    return (await git(gitClient, ["status", "--porcelain"], cwd)).trim().length > 0;
+  } catch {
+    return true;
+  }
+}
+
+export async function getIndexedCommitCeilings(warp: WarpApp): Promise<ReadonlyMap<string, number>> {
+  const { receipts } = await warp.core().materialize({ receipts: true });
+  const ceilings = new Map<string, number>();
+
+  for (const receipt of receipts) {
+    const commitAdd = receipt.ops.find((op) =>
+      op.op === "NodeAdd" &&
+      op.result === "applied" &&
+      op.target.startsWith("commit:")
+    );
+    if (commitAdd !== undefined) {
+      ceilings.set(commitAdd.target.slice("commit:".length), receipt.lamport);
+    }
+  }
+
+  return ceilings;
+}
+
+export function collectSymbols(
+  entries: readonly OutlineEntry[],
+  filePath: string,
+  jumpTable: readonly JumpEntry[],
+  jumpCursor: Map<string, number> = new Map<string, number>(),
+): PrecisionSymbolMatch[] {
+  const jumpLookup = buildJumpLookup(jumpTable);
+  const results: PrecisionSymbolMatch[] = [];
+
+  for (const entry of entries) {
+    const candidates = jumpLookup.get(entry.name) ?? [];
+    const jumpIndex = jumpCursor.get(entry.name) ?? 0;
+    const jump = candidates[jumpIndex];
+    if (jump !== undefined) {
+      jumpCursor.set(entry.name, jumpIndex + 1);
+    }
+    results.push(new PrecisionSymbolMatch({
+      name: entry.name,
+      kind: entry.kind,
+      path: filePath,
+      exported: entry.exported,
+      ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
+      ...(jump?.start !== undefined ? { startLine: jump.start } : {}),
+      ...(jump?.end !== undefined ? { endLine: jump.end } : {}),
+    }));
+
+    if (entry.children !== undefined && entry.children.length > 0) {
+      results.push(...collectSymbols(entry.children, filePath, jumpTable, jumpCursor));
+    }
+  }
+
+  return results;
+}
+
+export async function loadFileContent(
+  ctx: ToolContext,
+  filePath: string,
+  ref?: string,
+): Promise<string | null> {
+  if (ref !== undefined) {
+    return getFileAtRef(ref, filePath, { cwd: ctx.projectRoot, git: ctx.git });
+  }
+
+  try {
+    return await ctx.fs.readFile(ctx.resolvePath(filePath), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function evaluatePrecisionPolicy(
+  ctx: ToolContext,
+  filePath: string,
+  content: string,
+): PrecisionPolicyRefusal | null {
+  const actual = {
+    lines: content.split("\n").length,
+    bytes: Buffer.byteLength(content),
+  };
+  return evaluateMcpRefusal(ctx, filePath, actual);
+}
+
+export async function searchWarpSymbols(
+  warp: WarpApp,
+  request: PrecisionSearchRequest,
+): Promise<PrecisionSymbolMatch[]> {
+  const lensMode = request.selectLens();
+  if (lensMode === "file" && request.filePath === undefined) {
+    throw new Error("PrecisionSearchRequest selected file lens without filePath");
+  }
+  if (lensMode === "exact" && request.exactName === undefined) {
+    throw new Error("PrecisionSearchRequest selected exact lens without exactName");
+  }
+  let lens;
+  if (lensMode === "file") {
+    const filePath = request.filePath;
+    if (filePath === undefined) {
+      throw new Error("PrecisionSearchRequest selected file lens without filePath");
+    }
+    lens = fileSymbolsLens(filePath);
+  } else if (lensMode === "exact") {
+    const exactName = request.exactName;
+    if (exactName === undefined) {
+      throw new Error("PrecisionSearchRequest selected exact lens without exactName");
+    }
+    lens = symbolByNameLens(exactName);
+  } else {
+    lens = allSymbolsLens();
+  }
+  const observer = await warp.observer(
+    lens,
+    request.ceiling !== undefined ? { source: { kind: "live", ceiling: request.ceiling } } : undefined,
+  );
+  const nodeIds = await observer.getNodes();
+
+  const matches = await Promise.all(nodeIds.map(async (nodeId) => {
+    const props = await observer.getNodeProps(nodeId);
+    if (props === null) return null;
+    const match = toMatch(nodeId, props);
+    if (match === null) return null;
+    return request.rank(match);
+  }));
+
+  const visibleMatches = matches.filter((match): match is RankedPrecisionSymbolMatch => match !== null);
+  return request.sort(visibleMatches);
+}
+
+export async function searchLiveSymbols(
+  ctx: ToolContext,
+  filePaths: readonly string[],
+  request: PrecisionSearchRequest,
+  ref?: string,
+): Promise<PrecisionSymbolMatch[]> {
+  const matches: RankedPrecisionSymbolMatch[] = [];
+
+  for (const filePath of filePaths) {
+    const lang = detectLang(filePath);
+    if (lang === null) continue;
+
+    const content = await loadFileContent(ctx, filePath, ref);
+    if (content === null) continue;
+
+    const result = extractOutline(content, lang);
+    const symbols = collectSymbols(result.entries, filePath, result.jumpTable ?? []);
+
+    for (const symbol of symbols) {
+      const ranked = request.rank(symbol);
+      if (ranked !== null) matches.push(ranked);
+    }
+  }
+
+  return request.sort(matches);
+}
+
+export function readRangeFromContent(
+  filePath: string,
+  content: string,
+  start: number,
+  end: number,
+): {
+  path: string;
+  content?: string | undefined;
+  startLine?: number | undefined;
+  endLine?: number | undefined;
+  truncated?: boolean | undefined;
+  clipped?: boolean | undefined;
+  reason?: string | undefined;
+} {
+  if (start > end) {
+    return { path: filePath, reason: "INVALID_RANGE" };
+  }
+
+  const allLines = content.split("\n");
+  const totalLines = allLines.length;
+  let effectiveEnd = end;
+  let truncated = false;
+  let clipped = false;
+
+  if (effectiveEnd - start + 1 > MAX_RANGE_LINES) {
+    effectiveEnd = start + MAX_RANGE_LINES - 1;
+    truncated = true;
+  }
+
+  if (effectiveEnd > totalLines) {
+    effectiveEnd = totalLines;
+    clipped = true;
+  }
+
+  return {
+    path: filePath,
+    content: allLines.slice(start - 1, effectiveEnd).join("\n"),
+    startLine: start,
+    endLine: effectiveEnd,
+    ...(truncated ? { truncated: true, reason: "RANGE_EXCEEDED" } : {}),
+    ...(clipped ? { clipped: true } : {}),
+  };
+}

package/src/mcp/tools/run-capture.ts

@@ -1,66 +1,148 @@
 import * as path from "node:path";
-import { execFileSync } from "node:child_process";
 import { z } from "zod";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
 
+const RUN_CAPTURE_POLICY_BOUNDARY = {
+  kind: "shell_escape_hatch",
+  boundedReadContract: false,
+  policyEnforced: false,
+} as const;
+
+const PRIVATE_KEY_BLOCK_RE = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+const SECRET_ASSIGNMENT_RE = /(\b(?:api[_-]?key|access[_-]?token|auth(?:orization)?|bearer|token|secret|password|passwd|private[_-]?key|client[_-]?secret|session[_-]?key)\b\s*[:=]\s*)([^\r\n]+)/gi;
+const BEARER_TOKEN_RE = /(\bbearer\s+)([A-Za-z0-9._~+/=-]{8,})/gi;
+
+function tailOutput(output: string, tail: number): {
+  readonly tailed: string;
+  readonly totalLines: number;
+} {
+  const lines = output.split("\n");
+  return {
+    tailed: lines.slice(-tail).join("\n"),
+    totalLines: lines.length,
+  };
+}
+
+function renderCaptureError(result: {
+  readonly status: number | null;
+  readonly stderr: string;
+  readonly error?: Error;
+}): string {
+  if (result.error !== undefined) {
+    return result.error.message;
+  }
+  const stderr = result.stderr.trim();
+  if (stderr.length > 0) {
+    return stderr;
+  }
+  return `Command exited with status ${String(result.status)}`;
+}
+
+function redactForLog(output: string): {
+  readonly value: string;
+  readonly redactions: number;
+} {
+  let redactions = 0;
+  let value = output.replace(PRIVATE_KEY_BLOCK_RE, () => {
+    redactions++;
+    return "[REDACTED PRIVATE KEY BLOCK]";
+  });
+  value = value.replace(SECRET_ASSIGNMENT_RE, (_match, prefix: string) => {
+    redactions++;
+    return `${prefix}[REDACTED]`;
+  });
+  value = value.replace(BEARER_TOKEN_RE, (_match, prefix: string) => {
+    redactions++;
+    return `${prefix}[REDACTED]`;
+  });
+  return { value, redactions };
+}
+
+async function persistCaptureLog(ctx: ToolContext, output: string): Promise<{
+  readonly logPath: string | null;
+  readonly logRedactions: number;
+}> {
+  if (!ctx.runCapture.persistLogs) {
+    return { logPath: null, logRedactions: 0 };
+  }
+
+  const logPath = path.join(ctx.graftDir, "logs", "capture.log");
+  const persisted = ctx.runCapture.redactLogs ? redactForLog(output) : { value: output, redactions: 0 };
+
+  try {
+    await ctx.fs.mkdir(path.dirname(logPath), { recursive: true });
+    await ctx.fs.writeFile(logPath, persisted.value, "utf-8");
+    return {
+      logPath,
+      logRedactions: persisted.redactions,
+    };
+  } catch {
+    return { logPath: null, logRedactions: 0 };
+  }
+}
+
 export const runCaptureTool: ToolDefinition = {
   name: "run_capture",
   description:
     "Execute a shell command and return the last N lines of output " +
-    "(default 60). Full output saved to .graft/logs/capture.log for " +
-    "follow-up read_range calls.",
+    "(default 60). Responses include an explicit policy boundary. " +
+    "Persisted logs can be disabled and obvious secrets are redacted " +
+    "before writing to .graft/logs/capture.log.",
   schema: { command: z.string(), tail: z.number().optional() },
   createHandler(ctx: ToolContext): ToolHandler {
     return async (args) => {
       const command = args["command"] as string;
       const tail = Math.max(1, Math.floor((args["tail"] as number | undefined) ?? 60));
-      // execFileSync is intentional: MCP tool calls are sequential per-session,
-      // and synchronous execution simplifies stdout/stderr capture with timeout.
-      let output: string;
-      try {
-        output = execFileSync("sh", ["-c", command], {
-          cwd: ctx.projectRoot,
-          encoding: "utf-8",
-          timeout: 30000,
-          stdio: ["pipe", "pipe", "pipe"],
-          maxBuffer: 10 * 1024 * 1024,
-        });
-      } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        const stdout = (err as { stdout?: string }).stdout ?? "";
-        const stderr = (err as { stderr?: string }).stderr ?? "";
-        // Return whatever stdout was captured before failure
-        const tailed = typeof stdout === "string"
-          ? stdout.split("\n").slice(-tail).join("\n")
-          : "";
-        const totalLines = typeof stdout === "string" ? stdout.split("\n").length : 0;
+      if (!ctx.runCapture.enabled) {
         return ctx.respond("run_capture", {
-          error: msg,
-          output: tailed,
-          totalLines,
-          tailedLines: Math.min(tail, totalLines),
-          truncated: totalLines > tail,
-          stderr: typeof stderr === "string" ? stderr.slice(0, 2000) : "",
+          output: "",
+          totalLines: 0,
+          tailedLines: 0,
+          logPath: null,
+          logRedactions: 0,
+          logPersistenceEnabled: false,
+          truncated: false,
+          disabled: true,
+          error: "run_capture is disabled by configuration",
+          policyBoundary: RUN_CAPTURE_POLICY_BOUNDARY,
         });
       }
+      const result = ctx.process.run({
+        command: "sh",
+        args: ["-c", command],
+        cwd: ctx.projectRoot,
+        timeoutMs: 30000,
+        maxBufferBytes: 10 * 1024 * 1024,
+      });
 
-      const lines = output.split("\n");
-      const tailed = lines.slice(-tail).join("\n");
-      const logPath = path.join(ctx.graftDir, "logs", "capture.log");
-      let logWriteSucceeded = true;
-      try {
-        await ctx.fs.mkdir(path.dirname(logPath), { recursive: true });
-        await ctx.fs.writeFile(logPath, output, "utf-8");
-      } catch {
-        // Log persistence failure must not mask a successful command
-        logWriteSucceeded = false;
+      if (result.error !== undefined || result.status !== 0) {
+        const tailedOutput = tailOutput(result.stdout, tail);
+        return ctx.respond("run_capture", {
+          error: renderCaptureError(result),
+          output: tailedOutput.tailed,
+          totalLines: tailedOutput.totalLines,
+          tailedLines: Math.min(tail, tailedOutput.totalLines),
+          logPath: null,
+          logRedactions: 0,
+          logPersistenceEnabled: ctx.runCapture.persistLogs,
+          truncated: tailedOutput.totalLines > tail,
+          stderr: result.stderr.slice(0, 2000),
+          policyBoundary: RUN_CAPTURE_POLICY_BOUNDARY,
+        });
       }
+
+      const output = result.stdout;
+      const tailedOutput = tailOutput(output, tail);
+      const persisted = await persistCaptureLog(ctx, output);
       return ctx.respond("run_capture", {
-        output: tailed,
-        totalLines: lines.length,
-        tailedLines: Math.min(tail, lines.length),
-        logPath: logWriteSucceeded ? logPath : null,
-        truncated: lines.length > tail,
+        output: tailedOutput.tailed,
+        totalLines: tailedOutput.totalLines,
+        tailedLines: Math.min(tail, tailedOutput.totalLines),
+        logPath: persisted.logPath,
+        logRedactions: persisted.logRedactions,
+        logPersistenceEnabled: ctx.runCapture.persistLogs,
+        truncated: tailedOutput.totalLines > tail,
+        policyBoundary: RUN_CAPTURE_POLICY_BOUNDARY,
       });
     };
   },

package/src/mcp/tools/safe-read.ts

@@ -1,11 +1,11 @@
 import { z } from "zod";
 import { safeRead } from "../../operations/safe-read.js";
 import type { SafeReadResult } from "../../operations/safe-read.js";
-import { evaluatePolicy } from "../../policy/evaluate.js";
 import { RefusedResult } from "../../policy/types.js";
 import { diffOutlines } from "../../parser/diff.js";
 import { CachedFile } from "../cached-file.js";
 import type { Metrics } from "../metrics.js";
+import { evaluateMcpPolicy, toPolicyPath } from "../policy.js";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
 
 const PROJECTION_METRICS: Readonly<Record<string, ((m: Metrics) => void) | undefined>> = {
@@ -32,21 +32,18 @@ export const safeReadTool: ToolDefinition = {
       // eliminating TOCTOU races where the file changes between reads.
       let cf: CachedFile | null = null;
       try {
-        const rawContent = ctx.fs.readFileSync(filePath, "utf-8");
+        const rawContent = await ctx.fs.readFile(filePath, "utf-8");
         cf = new CachedFile(filePath, rawContent);
       } catch {
         // File doesn't exist or can't be read — proceed to safeRead for error handling
       }
 
       // Check cache if we could read the file
-      if (cf !== null) {
+      if (cf?.supportsOutline === true) {
         const cacheResult = ctx.cache.check(filePath, cf.rawContent);
         if (cacheResult.hit) {
           // Defense: re-check policy before returning cached data.
-          const policy = evaluatePolicy(
-            { path: filePath, lines: cf.actual.lines, bytes: cf.actual.bytes },
-            { sessionDepth: ctx.session.getSessionDepth(), budgetRemaining: ctx.session.getBudget()?.remaining },
-          );
+          const policy = evaluateMcpPolicy(ctx, filePath, cf.actual);
           if (policy instanceof RefusedResult) {
             ctx.metrics.recordRefusal();
             return ctx.respond("safe_read", {
@@ -77,10 +74,7 @@ export const safeReadTool: ToolDefinition = {
         // File changed since last observation — compute structural diff
         if (cacheResult.stale !== null) {
           // Defense: re-check policy before returning structural data.
-          const policy = evaluatePolicy(
-            { path: filePath, lines: cf.actual.lines, bytes: cf.actual.bytes },
-            { sessionDepth: ctx.session.getSessionDepth(), budgetRemaining: ctx.session.getBudget()?.remaining },
-          );
+          const policy = evaluateMcpPolicy(ctx, filePath, cf.actual);
           if (policy instanceof RefusedResult) {
             ctx.metrics.recordRefusal();
             return ctx.respond("safe_read", {
@@ -117,6 +111,8 @@ export const safeReadTool: ToolDefinition = {
         codec: ctx.codec,
         content: cf?.rawContent,
         intent: args["intent"] as string | undefined,
+        policyPath: toPolicyPath(ctx.projectRoot, filePath),
+        graftignorePatterns: [...ctx.graftignorePatterns],
         sessionDepth: ctx.session.getSessionDepth(),
         budgetRemaining: ctx.session.getBudget()?.remaining,
       });
@@ -125,7 +121,13 @@ export const safeReadTool: ToolDefinition = {
 
       // Record observation for cacheable projections — uses CachedFile
       // outline (no re-read) to eliminate the snapshot race.
-      if (cf !== null && result.actual !== undefined && CACHEABLE_PROJECTIONS.has(result.projection)) {
+      if (
+        cf !== null &&
+        cf.supportsOutline &&
+        result.actual !== undefined &&
+        CACHEABLE_PROJECTIONS.has(result.projection) &&
+        result.reason !== "UNSUPPORTED_LANGUAGE"
+      ) {
         ctx.cache.record(filePath, cf.hash, cf.outline, cf.jumpTable, result.actual);
       }
 

package/src/mcp/tools/since.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { graftDiff } from "../../operations/graft-diff.js";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { evaluateMcpRefusal } from "../policy.js";
 
 export const sinceTool: ToolDefinition = {
   name: "graft_since",
@@ -13,15 +14,18 @@ export const sinceTool: ToolDefinition = {
     head: z.string().optional(),
   },
   createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
+    return async (args) => {
       const base = args["base"] as string;
       const head = (args["head"] as string | undefined) ?? "HEAD";
 
-      const result = graftDiff({
+      const result = await graftDiff({
         cwd: ctx.projectRoot,
         fs: ctx.fs,
+        git: ctx.git,
+        resolveWorkingTreePath: (filePath) => ctx.resolvePath(filePath),
         base,
         head,
+        refusalCheck: (filePath, actual) => evaluateMcpRefusal(ctx, filePath, actual),
       });
 
       // Aggregate symbol-level changes across all files
@@ -38,6 +42,7 @@ export const sinceTool: ToolDefinition = {
       return ctx.respond("graft_since", {
         ...result,
         summary: `+${String(totalAdded)} added, -${String(totalRemoved)} removed, ~${String(totalChanged)} changed across ${String(result.files.length)} files`,
+        layer: "ref_view",
       });
     };
   },

package/src/mcp/tools/state.ts

@@ -1,5 +1,6 @@
+import * as path from "node:path";
 import { z } from "zod";
-import { stateSave, stateLoad } from "../../operations/state.js";
+import { STATE_FILENAME, stateSave, stateLoad } from "../../operations/state.js";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
 
 export const stateSaveTool: ToolDefinition = {
@@ -10,7 +11,11 @@ export const stateSaveTool: ToolDefinition = {
   schema: { content: z.string() },
   createHandler(ctx: ToolContext): ToolHandler {
     return async (args) => {
-      const result = await stateSave(args["content"] as string, { graftDir: ctx.graftDir, fs: ctx.fs });
+      const result = await stateSave(args["content"] as string, {
+        stateDir: ctx.graftDir,
+        statePath: path.join(ctx.graftDir, STATE_FILENAME),
+        fs: ctx.fs,
+      });
       return ctx.respond("state_save", result as Record<string, unknown>);
     };
   },
@@ -23,7 +28,10 @@ export const stateLoadTool: ToolDefinition = {
     "been saved.",
   createHandler(ctx: ToolContext): ToolHandler {
     return async () => {
-      const result = await stateLoad({ graftDir: ctx.graftDir, fs: ctx.fs });
+      const result = await stateLoad({
+        statePath: path.join(ctx.graftDir, STATE_FILENAME),
+        fs: ctx.fs,
+      });
       return ctx.respond("state_load", result as Record<string, unknown>);
     };
   },

package/src/mcp/tools/stats.ts

@@ -1,10 +1,11 @@
+import { totalNonReadBytesReturned } from "../burden.js";
 import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
 
 export const statsTool: ToolDefinition = {
   name: "stats",
   description:
     "Decision metrics for the current session. Total reads, outlines, " +
-    "refusals, cache hits, and bytes avoided.",
+    "refusals, cache hits, bytes avoided, and burden by tool kind.",
   createHandler(ctx: ToolContext): ToolHandler {
     return () => {
       const snap = ctx.metrics.snapshot();
@@ -13,7 +14,10 @@ export const statsTool: ToolDefinition = {
         totalOutlines: snap.outlines,
         totalRefusals: snap.refusals,
         totalCacheHits: snap.cacheHits,
+        totalBytesReturned: snap.bytesReturned,
         totalBytesAvoidedByCache: snap.bytesAvoided,
+        totalNonReadBytesReturned: totalNonReadBytesReturned(snap.burdenByKind),
+        burdenByKind: snap.burdenByKind,
       });
     };
   },

package/src/mcp/tools/workspace-authorizations.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const workspaceAuthorizationsTool: ToolDefinition = {
+  name: "workspace_authorizations",
+  description:
+    "List daemon-authorized workspaces, their capability posture, and active bound-session counts.",
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async () => {
+      return ctx.respond("workspace_authorizations", {
+        workspaces: await ctx.listWorkspaceAuthorizations(),
+      });
+    };
+  },
+};