@flyingrobots/graft 0.5.0 → 0.6.1

package/src/mcp/stdio-server.ts

@@ -2,10 +2,24 @@ import * as path from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createGraftServer } from "./server.js";
 
+export interface StartStdioServerOptions {
+  readonly runtime: "stdio" | "daemon";
+  readonly socketPath?: string;
+}
+
+function resolveProjectRoot(cwd: string): string {
+  const fromEnv = process.env["GRAFT_PROJECT_ROOT"]?.trim();
+  if (fromEnv !== undefined && fromEnv.length > 0) {
+    return path.resolve(fromEnv);
+  }
+  return cwd;
+}
+
 export async function startStdioServer(cwd = process.cwd()): Promise<void> {
+  const projectRoot = resolveProjectRoot(cwd);
   const graft = createGraftServer({
-    projectRoot: cwd,
-    graftDir: path.join(cwd, ".graft"),
+    projectRoot,
+    graftDir: path.join(projectRoot, ".graft"),
   });
   const transport = new StdioServerTransport();
   await graft.getMcpServer().connect(transport);

package/src/mcp/tool-registry.ts

@@ -0,0 +1,80 @@
+import type { ToolDefinition } from "./context.js";
+
+import { safeReadTool } from "./tools/safe-read.js";
+import { fileOutlineTool } from "./tools/file-outline.js";
+import { readRangeTool } from "./tools/read-range.js";
+import { changedSinceTool } from "./tools/changed-since.js";
+import { graftDiffTool } from "./tools/graft-diff.js";
+import { runCaptureTool } from "./tools/run-capture.js";
+import { stateSaveTool, stateLoadTool } from "./tools/state.js";
+import { doctorTool } from "./tools/doctor.js";
+import { statsTool } from "./tools/stats.js";
+import { explainTool } from "./tools/explain.js";
+import { setBudgetTool } from "./tools/budget.js";
+import { sinceTool } from "./tools/since.js";
+import { mapTool } from "./tools/map.js";
+import { codeShowTool } from "./tools/code-show.js";
+import { codeFindTool } from "./tools/code-find.js";
+import { codeRefsTool } from "./tools/code-refs.js";
+import { daemonMonitorsTool } from "./tools/daemon-monitors.js";
+import { daemonReposTool } from "./tools/daemon-repos.js";
+import { daemonSessionsTool } from "./tools/daemon-sessions.js";
+import { daemonStatusTool } from "./tools/daemon-status.js";
+import { monitorPauseTool } from "./tools/monitor-pause.js";
+import { monitorResumeTool } from "./tools/monitor-resume.js";
+import { monitorStartTool } from "./tools/monitor-start.js";
+import { monitorStopTool } from "./tools/monitor-stop.js";
+import { activityViewTool } from "./tools/activity-view.js";
+import { causalStatusTool } from "./tools/causal-status.js";
+import { causalAttachTool } from "./tools/causal-attach.js";
+import { workspaceAuthorizeTool } from "./tools/workspace-authorize.js";
+import { workspaceAuthorizationsTool } from "./tools/workspace-authorizations.js";
+import { workspaceBindTool } from "./tools/workspace-bind.js";
+import { workspaceRevokeTool } from "./tools/workspace-revoke.js";
+import { workspaceStatusTool } from "./tools/workspace-status.js";
+import { workspaceRebindTool } from "./tools/workspace-rebind.js";
+
+export const TOOL_REGISTRY: readonly ToolDefinition[] = [
+  safeReadTool,
+  fileOutlineTool,
+  readRangeTool,
+  changedSinceTool,
+  graftDiffTool,
+  runCaptureTool,
+  stateSaveTool,
+  stateLoadTool,
+  doctorTool,
+  activityViewTool,
+  causalStatusTool,
+  causalAttachTool,
+  statsTool,
+  explainTool,
+  setBudgetTool,
+  sinceTool,
+  mapTool,
+  codeShowTool,
+  codeFindTool,
+  codeRefsTool,
+];
+
+export const DAEMON_TOOL_REGISTRY: readonly ToolDefinition[] = [
+  daemonReposTool,
+  daemonStatusTool,
+  daemonSessionsTool,
+  daemonMonitorsTool,
+  monitorStartTool,
+  monitorPauseTool,
+  monitorResumeTool,
+  monitorStopTool,
+  workspaceAuthorizeTool,
+  workspaceAuthorizationsTool,
+  workspaceRevokeTool,
+  workspaceBindTool,
+  workspaceStatusTool,
+  workspaceRebindTool,
+];
+
+export const ALL_TOOL_REGISTRY: readonly ToolDefinition[] = [
+  ...TOOL_REGISTRY,
+  ...DAEMON_TOOL_REGISTRY,
+];

package/src/mcp/tools/activity-view.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { buildRuntimeStagedTarget } from "../runtime-staged-target.js";
 import { deriveCausalSurfaceNextAction } from "../semantic-transition-guidance.js";
 import type { PersistedLocalActivityItem } from "../persisted-local-history.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 const limitSchema = z.number().int().positive().max(50).optional();
 
@@ -206,8 +206,8 @@ export const activityViewTool: ToolDefinition = {
   schema: {
     limit: limitSchema,
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const limit = limitSchema.parse(args["limit"]) ?? 20;
       const workspaceStatus = ctx.getWorkspaceStatus();
 

package/src/mcp/tools/budget.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+import type { SetBudgetResponse } from "./diagnostic-models.js";
 
 export const setBudgetTool: ToolDefinition = {
   name: "set_budget",
@@ -8,13 +10,14 @@ export const setBudgetTool: ToolDefinition = {
     "read thresholds as the budget drains — no single read may consume " +
     "more than 5% of remaining budget. Call once at session start.",
   schema: { bytes: z.number() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
+  createHandler(): ToolHandler {
+    return (args, ctx) => {
       const bytes = args["bytes"] as number;
-      ctx.session.setBudget(bytes);
-      return ctx.respond("set_budget", {
-        budget: ctx.session.getBudget(),
-      });
+      ctx.governor.setBudget(bytes);
+      const response: SetBudgetResponse = {
+        budget: ctx.governor.getBudget(),
+      };
+      return ctx.respond("set_budget", toJsonObject(response));
     };
   },
 };

package/src/mcp/tools/causal-attach.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { buildRuntimeStagedTarget } from "../runtime-staged-target.js";
 import { deriveCausalSurfaceNextAction } from "../semantic-transition-guidance.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 const actorKindSchema = z.enum(["human", "agent"]);
 
@@ -15,8 +15,8 @@ export const causalAttachTool: ToolDefinition = {
     from_actor_id: z.string().min(1).optional(),
     note: z.string().min(1).optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const result = await ctx.declareCausalAttach({
         actorKind: actorKindSchema.parse(args["actor_kind"]),
         actorId: typeof args["actor_id"] === "string" ? args["actor_id"] : undefined,

package/src/mcp/tools/causal-status.ts

@@ -1,13 +1,13 @@
 import { buildRuntimeStagedTarget } from "../runtime-staged-target.js";
 import { deriveCausalSurfaceNextAction } from "../semantic-transition-guidance.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const causalStatusTool: ToolDefinition = {
   name: "causal_status",
   description:
     "Inspect the active causal workspace and persisted local-history posture.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
       const workspaceStatus = ctx.getWorkspaceStatus();
       const persistedLocalHistory = await ctx.getPersistedLocalHistorySummary();
       if (workspaceStatus.bindState === "unbound") {

package/src/mcp/tools/changed-since.ts

@@ -3,7 +3,7 @@ import { RefusedResult } from "../../policy/types.js";
 import { extractOutlineForFile } from "../../parser/outline.js";
 import { diffOutlines } from "../../parser/diff.js";
 import { hashContent } from "../cache.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 import { evaluateMcpPolicy } from "../policy.js";
 
 export const changedSinceTool: ToolDefinition = {
@@ -13,9 +13,10 @@ export const changedSinceTool: ToolDefinition = {
     "diff (added/removed/changed symbols) or 'unchanged'. Peek mode by " +
     "default; pass consume: true to update the observation cache.",
   schema: { path: z.string(), consume: z.boolean().optional() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const filePath = ctx.resolvePath(args["path"] as string);
+      ctx.recordFootprint({ paths: [filePath] });
       const consume = (args["consume"] as boolean | undefined) === true;
 
       // Policy check: refuse banned files even via changed_since.

package/src/mcp/tools/code-find.ts

@@ -136,6 +136,11 @@ export async function runCodeFind(
     });
   }
 
+  ctx.recordFootprint({
+    paths: [...new Set(visibleMatches.map((m) => m.path))],
+    symbols: visibleMatches.map((m) => m.name),
+  });
+
   return ctx.respond("code_find", {
     query: request.query,
     kind: request.kind ?? null,
@@ -158,7 +163,7 @@ export const codeFindTool: ToolDefinition = {
     path: z.string().optional(),
   },
   policyCheck: true,
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => runCodeFind(ctx, args, { allowWarp: true });
+  createHandler(): ToolHandler {
+    return (args, ctx) => runCodeFind(ctx, args, { allowWarp: true });
   },
 };

package/src/mcp/tools/code-refs.ts

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 import type { ProcessRunner } from "../../ports/process-runner.js";
 import { GitFileQuery, listGitFiles } from "./git-files.js";
 import {
@@ -385,8 +385,8 @@ export const codeRefsTool: ToolDefinition = {
     mode: z.enum(CODE_REFS_MODES).optional(),
     path: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const request = new CodeRefsRequest(args, ctx.projectRoot);
       const pattern = buildCodeRefsPattern(request);
       const repoState = ctx.getRepoState();
@@ -446,6 +446,10 @@ export const codeRefsTool: ToolDefinition = {
         });
       }
 
+      ctx.recordFootprint({
+        paths: [...new Set(visibleMatches.map((m) => m.path))],
+      });
+
       return ctx.respond("code_refs", {
         query: request.query,
         mode: request.mode,

package/src/mcp/tools/code-show.ts

@@ -182,6 +182,10 @@ export async function runCodeShow(
   }
 
   if (visibleLocations.length > 1) {
+    ctx.recordFootprint({
+      paths: [...new Set(visibleLocations.map((m) => m.path))],
+      symbols: visibleLocations.map((m) => m.name),
+    });
     return ctx.respond("code_show", {
       symbol: symbolName,
       ambiguous: true,
@@ -219,6 +223,12 @@ export async function runCodeShow(
     ? readRangeFromContent(loc.path, content, loc.startLine, loc.endLine)
     : await readRange(ctx.resolvePath(loc.path), loc.startLine, loc.endLine, { fs: ctx.fs });
 
+  ctx.recordFootprint({
+    paths: [loc.path],
+    symbols: [loc.name],
+    regions: [{ path: loc.path, startLine: loc.startLine, endLine: loc.endLine }],
+  });
+
   return ctx.respond("code_show", {
     symbol: loc.name,
     kind: loc.kind,
@@ -246,7 +256,7 @@ export const codeShowTool: ToolDefinition = {
     path: z.string().optional(),
     ref: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => runCodeShow(ctx, args, { allowWarp: true });
+  createHandler(): ToolHandler {
+    return (args, ctx) => runCodeShow(ctx, args, { allowWarp: true });
   },
 };

package/src/mcp/tools/daemon-monitors.ts

@@ -1,11 +1,11 @@
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const daemonMonitorsTool: ToolDefinition = {
   name: "daemon_monitors",
   description:
     "List daemon-managed persistent repo monitors with lifecycle, backlog, and recent failure state.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
       return ctx.respond("daemon_monitors", {
         monitors: await ctx.listDaemonMonitors(),
       });

package/src/mcp/tools/daemon-repos.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const daemonReposTool: ToolDefinition = {
   name: "daemon_repos",
@@ -9,8 +9,8 @@ export const daemonReposTool: ToolDefinition = {
     repoId: z.string().optional(),
     cwd: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       return ctx.respond("daemon_repos", {
         ...await ctx.listDaemonRepos({
           repoId: args["repoId"] as string | undefined,

package/src/mcp/tools/daemon-sessions.ts

@@ -1,11 +1,11 @@
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const daemonSessionsTool: ToolDefinition = {
   name: "daemon_sessions",
   description:
     "List active daemon sessions with bind state, workspace identity, and capability posture, without exposing session-local receipts or shell output.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
       return ctx.respond("daemon_sessions", {
         sessions: await ctx.listDaemonSessions(),
       });

package/src/mcp/tools/daemon-status.ts

@@ -1,11 +1,11 @@
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const daemonStatusTool: ToolDefinition = {
   name: "daemon_status",
   description:
     "Return daemon-wide health, authorization counts, and default capability posture for the local control plane.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
       return ctx.respond("daemon_status", { ...await ctx.getDaemonStatus() });
     };
   },

package/src/mcp/tools/diagnostic-models.ts

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// Diagnostic tool response models — explicit types for diagnostic tool outputs
+// ---------------------------------------------------------------------------
+
+import type { BurdenByKind, BurdenKind } from "../burden.js";
+import type { RuntimeObservabilityState } from "../runtime-observability.js";
+import type { RuntimeCausalContext } from "../runtime-causal-context.js";
+import type { GovernorDepth } from "../../session/types.js";
+import type {
+  PersistedLocalHistorySummary,
+  RepoConcurrencySummary,
+} from "../persisted-local-history.js";
+import type { RuntimeWorkspaceOverlayFooting } from "../runtime-workspace-overlay.js";
+import type { CausalSurfaceNextAction } from "../../contracts/causal-surface-next-action.js";
+
+export interface SetBudgetResponse {
+  readonly budget: {
+    readonly total: number;
+    readonly consumed: number;
+    readonly remaining: number;
+    readonly fraction: number;
+  } | null;
+}
+
+export interface StatsResponse {
+  readonly totalReads: number;
+  readonly totalOutlines: number;
+  readonly totalRefusals: number;
+  readonly totalCacheHits: number;
+  readonly totalBytesReturned: number;
+  readonly totalBytesAvoidedByCache: number;
+  readonly totalNonReadBytesReturned: number;
+  readonly burdenByKind: Readonly<BurdenByKind>;
+}
+
+export interface ExplainResponse {
+  readonly code: string;
+  readonly meaning?: string | undefined;
+  readonly action?: string | undefined;
+  readonly error?: string | undefined;
+  readonly knownCodes?: string | undefined;
+}
+
+export interface DoctorBurdenSummary {
+  readonly totalBytesReturned: number;
+  readonly totalNonReadBytesReturned: number;
+  readonly topKind: BurdenKind | null;
+  readonly topBytesReturned: number;
+  readonly topCalls: number;
+}
+
+export interface DoctorResponse {
+  readonly projectRoot: string;
+  readonly parserHealthy: boolean;
+  readonly thresholds: { readonly lines: number; readonly bytes: number };
+  readonly sessionDepth: GovernorDepth;
+  readonly totalMessages: number;
+  readonly burdenSummary: DoctorBurdenSummary;
+  readonly runtimeObservability: RuntimeObservabilityState;
+  readonly causalContext: RuntimeCausalContext;
+  readonly latestReadEvent: PersistedLocalHistorySummary["latestReadEvent"];
+  readonly latestStageEvent: PersistedLocalHistorySummary["latestStageEvent"];
+  readonly latestTransitionEvent: PersistedLocalHistorySummary["latestTransitionEvent"];
+  readonly repoConcurrency: RepoConcurrencySummary | null;
+  readonly checkoutEpoch: unknown;
+  readonly lastTransition: unknown;
+  readonly semanticTransition: unknown;
+  readonly workspaceOverlayId: unknown;
+  readonly workspaceOverlay: unknown;
+  readonly workspaceOverlayFooting: RuntimeWorkspaceOverlayFooting | null;
+  readonly stagedTarget: unknown;
+  readonly attribution: PersistedLocalHistorySummary["attribution"];
+  readonly persistedLocalHistory: PersistedLocalHistorySummary;
+  readonly recommendedNextAction: CausalSurfaceNextAction;
+}
+
+export interface RunCapturePolicyBoundary {
+  readonly kind: "shell_escape_hatch";
+  readonly boundedReadContract: false;
+  readonly policyEnforced: false;
+}
+
+export interface RunCaptureResponse {
+  readonly output: string;
+  readonly totalLines: number;
+  readonly tailedLines: number;
+  readonly logPath: string | null;
+  readonly logRedactions: number;
+  readonly logPersistenceEnabled: boolean;
+  readonly truncated: boolean;
+  readonly policyBoundary: RunCapturePolicyBoundary;
+  readonly disabled?: boolean | undefined;
+  readonly error?: string | undefined;
+  readonly stderr?: string | undefined;
+}

package/src/mcp/tools/doctor.ts

@@ -2,15 +2,17 @@ import { STATIC_THRESHOLDS } from "../../policy/evaluate.js";
 import { topBurdenKind, totalNonReadBytesReturned } from "../burden.js";
 import { buildRuntimeStagedTarget } from "../runtime-staged-target.js";
 import { deriveCausalSurfaceNextAction } from "../semantic-transition-guidance.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { toJsonObject } from "../../operations/result-dto.js";
+import type { DoctorResponse } from "./diagnostic-models.js";
 
 export const doctorTool: ToolDefinition = {
   name: "doctor",
   description:
     "Runtime health check. Shows project root, parser status, active " +
     "thresholds, session depth, message count, and burden summary.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
       const repoState = ctx.getRepoState();
       const causalContext = ctx.getCausalContext();
       const workspaceOverlayFooting = await ctx.getWorkspaceOverlayFooting();
@@ -23,12 +25,12 @@ export const doctorTool: ToolDefinition = {
         repoState.semanticTransition,
         repoConcurrency,
       );
-      return ctx.respond("doctor", {
+      const response: DoctorResponse = {
         projectRoot: ctx.projectRoot,
         parserHealthy: true,
         thresholds: { lines: STATIC_THRESHOLDS.lines, bytes: STATIC_THRESHOLDS.bytes },
-        sessionDepth: ctx.session.getSessionDepth(),
-        totalMessages: ctx.session.getMessageCount(),
+        sessionDepth: ctx.governor.getGovernorDepth(),
+        totalMessages: ctx.governor.getMessageCount(),
         burdenSummary: {
           totalBytesReturned: metrics.bytesReturned,
           totalNonReadBytesReturned: totalNonReadBytesReturned(metrics.burdenByKind),
@@ -57,7 +59,8 @@ export const doctorTool: ToolDefinition = {
         attribution: persistedLocalHistory.attribution,
         persistedLocalHistory,
         recommendedNextAction,
-      });
+      };
+      return ctx.respond("doctor", toJsonObject(response));
     };
   },
 };

package/src/mcp/tools/explain.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 const EXPLANATIONS: Readonly<Record<string, { meaning: string; action: string }>> = {
   CONTENT: {
@@ -62,8 +62,8 @@ export const explainTool: ToolDefinition = {
     "Explain a graft reason code. Returns human-readable meaning and " +
     "recommended next action for any reason code returned by graft tools.",
   schema: { code: z.string() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return (args) => {
+  createHandler(): ToolHandler {
+    return (args, ctx) => {
       const code = (args["code"] as string).toUpperCase();
       const entry = EXPLANATIONS[code];
       if (entry === undefined) {

package/src/mcp/tools/file-outline.ts

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { fileOutline } from "../../operations/file-outline.js";
 import { detectStructuredFormat } from "../../parser/lang.js";
 import { hashContent } from "../cache.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { toJsonObject } from "../../operations/result-dto.js";
 
 export const fileOutlineTool: ToolDefinition = {
   name: "file_outline",
@@ -12,9 +13,10 @@ export const fileOutlineTool: ToolDefinition = {
     "for targeted read_range follow-ups.",
   schema: { path: z.string() },
   policyCheck: true,
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const filePath = ctx.resolvePath(args["path"] as string);
+      ctx.recordFootprint({ paths: [filePath] });
 
       // Check cache
       let rawContent: string | null = null;
@@ -31,6 +33,9 @@ export const fileOutlineTool: ToolDefinition = {
         if (cacheResult.hit) {
           cacheResult.obs.touch();
           ctx.metrics.recordCacheHit(cacheResult.obs.actual.bytes);
+          ctx.recordFootprint({
+            symbols: cacheResult.obs.outline.map((e) => e.name),
+          });
           return ctx.respond("file_outline", {
             path: filePath,
             outline: cacheResult.obs.outline,
@@ -43,6 +48,7 @@ export const fileOutlineTool: ToolDefinition = {
 
       const result = await fileOutline(filePath, { fs: ctx.fs });
       ctx.metrics.recordOutline();
+      ctx.recordFootprint({ symbols: result.outline.map((e) => e.name) });
 
       // Record observation
       if (rawContent !== null && outlineSupported && result.reason !== "UNSUPPORTED_LANGUAGE") {
@@ -55,7 +61,7 @@ export const fileOutlineTool: ToolDefinition = {
         );
       }
 
-      return ctx.respond("file_outline", result);
+      return ctx.respond("file_outline", toJsonObject(result));
     };
   },
 };

package/src/mcp/tools/graft-diff.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { graftDiff } from "../../operations/graft-diff.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 import { evaluateMcpRefusal } from "../policy.js";
 
 export const graftDiffTool: ToolDefinition = {
@@ -10,8 +10,8 @@ export const graftDiffTool: ToolDefinition = {
     "changed symbols per file \u2014 not line hunks. Defaults to working " +
     "tree vs HEAD.",
   schema: { base: z.string().optional(), head: z.string().optional(), path: z.string().optional() },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const head = args["head"] as string | undefined;
       const result = await graftDiff({
         cwd: ctx.projectRoot,
@@ -23,6 +23,9 @@ export const graftDiffTool: ToolDefinition = {
         path: args["path"] as string | undefined,
         refusalCheck: (filePath, actual) => evaluateMcpRefusal(ctx, filePath, actual),
       });
+      ctx.recordFootprint({
+        paths: (result.files as readonly { path: string }[]).map((f) => f.path),
+      });
       return ctx.respond("graft_diff", {
         ...result,
         layer: head === undefined ? "workspace_overlay" : "ref_view",