ctxloom-pro 1.2.6 → 1.3.0

package/dist/{chunk-PVKQ5UQS.js → chunk-Q2KTZNNU.js}

@@ -4610,86 +4610,349 @@ var ToolRegistry = class {
 
 // packages/core/src/tools/search.ts
 import { z as z3 } from "zod";
+
+// packages/core/src/budget/budget.ts
+var defaultTokenEstimator = (text) => Math.ceil(text.length / 4);
+function hasBudgetArgs(args) {
+  if (!args || typeof args !== "object") return false;
+  const a = args;
+  return a.max_response_tokens !== void 0 || a.on_budget_exceeded !== void 0 || a.response_format !== void 0;
+}
+function readBudgetArgs(args) {
+  if (!args || typeof args !== "object") return {};
+  const a = args;
+  const out = {};
+  if (typeof a.max_response_tokens === "number") out.max_response_tokens = a.max_response_tokens;
+  if (a.on_budget_exceeded === "skeleton" || a.on_budget_exceeded === "truncate" || a.on_budget_exceeded === "error") {
+    out.on_budget_exceeded = a.on_budget_exceeded;
+  }
+  if (a.response_format === "full" || a.response_format === "skeleton" || a.response_format === "auto") {
+    out.response_format = a.response_format;
+  }
+  return out;
+}
+function isBudgetDisabled() {
+  return process.env.CTXLOOM_DISABLE_BUDGET === "1";
+}
+function emitTelemetry(event) {
+  if (process.env.CTXLOOM_TELEMETRY_LEVEL !== "full") return;
+  logger.info(event.event, event);
+}
+async function enforceBudget(opts) {
+  const { full, args, toolName, defaultMaxTokens, skeletonProducer } = opts;
+  const estimate = opts.estimator ?? defaultTokenEstimator;
+  const originalTokens = estimate(full);
+  if (isBudgetDisabled()) {
+    return {
+      text: full,
+      meta: {
+        format: "full",
+        original_tokens_est: originalTokens,
+        returned_tokens_est: originalTokens,
+        fallback_reason: null
+      }
+    };
+  }
+  if (args.response_format === "skeleton" && skeletonProducer) {
+    const skeleton2 = await safeSkeleton(skeletonProducer, toolName);
+    if (skeleton2 !== null) {
+      const skTokens = estimate(skeleton2);
+      return {
+        text: skeleton2,
+        meta: {
+          format: "skeleton",
+          original_tokens_est: originalTokens,
+          returned_tokens_est: skTokens,
+          fallback_reason: null
+        }
+      };
+    }
+    return {
+      text: full,
+      meta: {
+        format: "full",
+        original_tokens_est: originalTokens,
+        returned_tokens_est: originalTokens,
+        fallback_reason: "skeleton_failed"
+      }
+    };
+  }
+  const budget = args.max_response_tokens ?? defaultMaxTokens;
+  if (budget === void 0) {
+    return {
+      text: full,
+      meta: {
+        format: "full",
+        original_tokens_est: originalTokens,
+        returned_tokens_est: originalTokens,
+        fallback_reason: null
+      }
+    };
+  }
+  if (originalTokens <= budget) {
+    return {
+      text: full,
+      meta: {
+        format: "full",
+        original_tokens_est: originalTokens,
+        returned_tokens_est: originalTokens,
+        fallback_reason: null
+      }
+    };
+  }
+  emitTelemetry({
+    event: "mcp.budget.exceeded",
+    tool: toolName,
+    original_tokens: originalTokens,
+    budget,
+    ratio: originalTokens / budget
+  });
+  const mode = args.on_budget_exceeded ?? "skeleton";
+  if (mode === "error") {
+    const err = new Error(
+      `Response of ~${originalTokens} tokens exceeds max_response_tokens=${budget} for tool '${toolName}'. Re-ask with response_format: 'skeleton' or a larger budget.`
+    );
+    err.tokensOriginal = originalTokens;
+    err.budget = budget;
+    err.tool = toolName;
+    throw err;
+  }
+  if (mode === "truncate") {
+    const sliced2 = full.slice(0, budget * 4);
+    const slicedTokens = estimate(sliced2);
+    emitTelemetry({
+      event: "mcp.fallback.used",
+      tool: toolName,
+      fallback_reason: "budget_exceeded",
+      mode: "truncate"
+    });
+    return {
+      text: sliced2,
+      meta: {
+        format: "truncated",
+        original_tokens_est: originalTokens,
+        returned_tokens_est: slicedTokens,
+        fallback_reason: "budget_exceeded"
+      }
+    };
+  }
+  const skeleton = skeletonProducer ? await safeSkeleton(skeletonProducer, toolName) : null;
+  if (skeleton !== null) {
+    const skTokens = estimate(skeleton);
+    if (skTokens <= budget) {
+      emitTelemetry({
+        event: "mcp.fallback.used",
+        tool: toolName,
+        fallback_reason: "budget_exceeded",
+        mode: "skeleton"
+      });
+      return {
+        text: skeleton,
+        meta: {
+          format: "skeleton",
+          original_tokens_est: originalTokens,
+          returned_tokens_est: skTokens,
+          fallback_reason: "budget_exceeded"
+        }
+      };
+    }
+    const slicedSk = skeleton.slice(0, budget * 4);
+    emitTelemetry({
+      event: "mcp.fallback.used",
+      tool: toolName,
+      fallback_reason: "budget_exceeded",
+      mode: "skeleton+truncate"
+    });
+    return {
+      text: slicedSk,
+      meta: {
+        format: "truncated",
+        original_tokens_est: originalTokens,
+        returned_tokens_est: estimate(slicedSk),
+        fallback_reason: "budget_exceeded"
+      }
+    };
+  }
+  const sliced = full.slice(0, budget * 4);
+  emitTelemetry({
+    event: "mcp.fallback.used",
+    tool: toolName,
+    fallback_reason: "skeleton_failed",
+    mode: "truncate-fallback"
+  });
+  return {
+    text: sliced,
+    meta: {
+      format: "truncated",
+      original_tokens_est: originalTokens,
+      returned_tokens_est: estimate(sliced),
+      fallback_reason: "skeleton_failed"
+    }
+  };
+}
+async function safeSkeleton(producer, toolName) {
+  try {
+    return await producer();
+  } catch (err) {
+    logger.warn("Skeleton fallback failed", {
+      tool: toolName,
+      detail: err instanceof Error ? err.message : String(err)
+    });
+    return null;
+  }
+}
+function wrapResponse(result) {
+  const envelope = {
+    data: result.text,
+    meta: result.meta
+  };
+  return JSON.stringify(envelope);
+}
+
+// packages/core/src/tools/search.ts
+var DEFAULT_MAX_RESPONSE_TOKENS = 4e3;
 var Schema = z3.object({
   query: z3.string().describe("Search query \u2014 natural language or code fragment"),
   limit: z3.number().max(100).optional().default(10).describe("Maximum results to return"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z3.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when budget surface is opted into). Over-budget rebuilds the result list without the content snippets (paths + scores only)."),
+  on_budget_exceeded: z3.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops snippets; 'truncate' slices the raw XML; 'error' throws."),
+  response_format: z3.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the path-and-score-only view; 'full'/'auto' lets the budget decide.")
 });
 function escapeXML3(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+function renderResults(query, ranked, includeContent) {
+  const lines = [`<search_results query="${escapeXML3(query)}" count="${ranked.length}">`];
+  for (const result of ranked) {
+    lines.push(`  <result file="${escapeXML3(result.filePath)}" score="${result.score.toFixed(4)}">`);
+    if (includeContent && result.content) {
+      lines.push(`    ${result.content.slice(0, 200).replace(/&/g, "&amp;").replace(/</g, "&lt;")}`);
+    }
+    lines.push("  </result>");
+  }
+  lines.push("</search_results>");
+  return lines.join("\n");
+}
 function registerSearchTool(registry, ctx) {
   registry.register(
     "ctx_search",
     {
       name: "ctx_search",
-      description: "Hybrid semantic + graph search over the codebase. Uses vector embeddings for semantic similarity and the dependency graph for structural expansion. Returns ranked file results.",
+      description: "Hybrid semantic + graph search over the codebase. Uses vector embeddings for semantic similarity and the dependency graph for structural expansion. Returns ranked file results. When callers opt into the budget surface, over-budget responses drop the content snippets and return paths + scores only.",
       inputSchema: {
         type: "object",
         properties: {
           query: { type: "string", description: "Search query \u2014 natural language or code fragment" },
           limit: { type: "number", description: "Maximum results to return (default: 10)" },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: {
+            type: "number",
+            description: "Soft response budget in tokens. Default: 4000 (when opted into)."
+          },
+          on_budget_exceeded: {
+            type: "string",
+            enum: ["skeleton", "truncate", "error"],
+            description: "Behavior when over budget. 'skeleton' (default) drops snippets; 'truncate' slices; 'error' throws."
+          },
+          response_format: {
+            type: "string",
+            enum: ["full", "skeleton", "auto"],
+            description: "'skeleton' forces path+score-only view; 'full'/'auto' lets the budget decide."
+          }
         },
         required: ["query"]
       }
     },
     async (args) => {
-      const { query, limit, project_root } = Schema.parse(args);
-      const [store, graph] = await Promise.all([ctx.getStore(project_root), ctx.getGraph(project_root)]);
-      const queryEmbedding = await generateEmbedding(query);
-      const vectorResults = await store.search(queryEmbedding, limit);
+      const parsed = Schema.parse(args);
+      const [store, graph] = await Promise.all([ctx.getStore(parsed.project_root), ctx.getGraph(parsed.project_root)]);
+      const queryEmbedding = await generateEmbedding(parsed.query);
+      const vectorResults = await store.search(queryEmbedding, parsed.limit);
       const expandedResults = /* @__PURE__ */ new Map();
-      for (const result of vectorResults) {
-        const existingScore = expandedResults.get(result.filePath)?.score ?? Infinity;
-        if (result.score < existingScore) {
-          expandedResults.set(result.filePath, { score: result.score, content: result.content });
+      for (const result2 of vectorResults) {
+        const existingScore = expandedResults.get(result2.filePath)?.score ?? Infinity;
+        if (result2.score < existingScore) {
+          expandedResults.set(result2.filePath, { score: result2.score, content: result2.content });
         }
-        for (const related of [...graph.getImports(result.filePath), ...graph.getImporters(result.filePath)]) {
+        for (const related of [...graph.getImports(result2.filePath), ...graph.getImporters(result2.filePath)]) {
           if (!expandedResults.has(related)) {
-            expandedResults.set(related, { score: result.score + 0.1, content: "" });
+            expandedResults.set(related, { score: result2.score + 0.1, content: "" });
           }
         }
       }
-      const ranked = Array.from(expandedResults.entries()).map(([filePath, data]) => ({ filePath, score: data.score, content: data.content })).sort((a, b) => a.score - b.score).slice(0, limit);
-      const lines = [`<search_results query="${escapeXML3(query)}" count="${ranked.length}">`];
-      for (const result of ranked) {
-        lines.push(`  <result file="${escapeXML3(result.filePath)}" score="${result.score.toFixed(4)}">`);
-        if (result.content) {
-          lines.push(`    ${result.content.slice(0, 200).replace(/&/g, "&amp;").replace(/</g, "&lt;")}`);
-        }
-        lines.push("  </result>");
-      }
-      lines.push("</search_results>");
-      return lines.join("\n");
+      const ranked = Array.from(expandedResults.entries()).map(([filePath, data]) => ({ filePath, score: data.score, content: data.content })).sort((a, b) => a.score - b.score).slice(0, parsed.limit);
+      const full = renderResults(parsed.query, ranked, true);
+      if (!hasBudgetArgs(args)) return full;
+      const skeletonProducer = async () => renderResults(parsed.query, ranked, false);
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_search",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS,
+        skeletonProducer
+      });
+      return wrapResponse(result);
     }
   );
 }
 
 // packages/core/src/tools/file.ts
 import { z as z4 } from "zod";
+var DEFAULT_MAX_RESPONSE_TOKENS2 = 8e3;
 var Schema2 = z4.object({
   path: z4.string().describe("Relative path to the file"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface (all optional; back-compat preserved) ──
+  max_response_tokens: z4.number().int().positive().optional().describe("Soft response budget in tokens. Falls back to a skeleton when exceeded. Default: 8000 (when budget surface is opted into)."),
+  on_budget_exceeded: z4.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when the response would exceed max_response_tokens. 'skeleton' (default) substitutes a Skeletonizer signature view; 'truncate' slices the raw text; 'error' throws a structured error with token counts so the caller can re-ask."),
+  response_format: z4.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces a Skeletonizer view regardless of budget; 'full'/'auto' lets the budget decide.")
 });
 function registerFileTool(registry, ctx) {
   registry.register(
     "ctx_get_file",
     {
       name: "ctx_get_file",
-      description: "Read a file from the project. Path is validated to prevent traversal outside the project root. Returns the full file content.",
+      description: "Read a file from the project. Path is validated to prevent traversal outside the project root. Returns the full file content; when callers opt into the budget surface (max_response_tokens / on_budget_exceeded / response_format), the response is wrapped in a {data, meta} envelope and oversize content is auto-substituted with a Skeletonizer signature view.",
       inputSchema: {
         type: "object",
         properties: {
           path: { type: "string", description: "Relative path to the file" },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: {
+            type: "number",
+            description: "Soft response budget in tokens. Falls back to a skeleton when exceeded. Default: 8000 (when budget surface is opted into)."
+          },
+          on_budget_exceeded: {
+            type: "string",
+            enum: ["skeleton", "truncate", "error"],
+            description: "Behavior when over budget. 'skeleton' (default) substitutes a signature view; 'truncate' slices the raw text; 'error' throws."
+          },
+          response_format: {
+            type: "string",
+            enum: ["full", "skeleton", "auto"],
+            description: "'skeleton' forces a Skeletonizer view regardless of budget; 'full'/'auto' lets the budget decide."
+          }
         },
         required: ["path"]
       }
     },
     async (args) => {
-      const { path: filePath, project_root } = Schema2.parse(args);
-      return ctx.getPathValidator(project_root).readFile(filePath);
+      const parsed = Schema2.parse(args);
+      const validator = ctx.getPathValidator(parsed.project_root);
+      const full = validator.readFile(parsed.path);
+      if (!hasBudgetArgs(args)) return full;
+      const absPath = validator.validate(parsed.path);
+      const skeletonizer = await ctx.getSkeletonizer(parsed.project_root);
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_get_file",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS2,
+        skeletonProducer: () => skeletonizer.skeletonize(absPath)
+      });
+      return wrapResponse(result);
     }
   );
 }
@@ -4697,34 +4960,71 @@ function registerFileTool(registry, ctx) {
 // packages/core/src/tools/context-packet.ts
 import { z as z5 } from "zod";
 import path14 from "path";
+var DEFAULT_MAX_RESPONSE_TOKENS3 = 6e3;
 var Schema3 = z5.object({
   target_file: z5.string().describe("Relative path to the primary file"),
   mode: z5.enum(["edit", "read"]).optional().default("edit").describe("Context mode"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z5.number().int().positive().optional().describe("Soft response budget. Default: 6000 (when budget surface is opted into). Over-budget rebuilds the packet with the primary file replaced by its skeleton."),
+  on_budget_exceeded: z5.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) re-renders the packet with the primary file skeletonized; 'truncate' slices the raw envelope; 'error' throws."),
+  response_format: z5.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the skeletonized-primary packet; 'full'/'auto' lets the budget decide.")
 });
+function renderPacket(parts) {
+  return [
+    `<context_packet target="${parts.target_file}" mode="${parts.mode}">`,
+    `  <primary_context file="${parts.target_file}">`,
+    `    ${parts.primaryContent.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}`,
+    "  </primary_context>",
+    `  <dependency_skeletons count="${parts.imports.length}">`,
+    ...parts.skeletons.map((s) => `    ${s}`),
+    "  </dependency_skeletons>",
+    `  <imported_by count="${parts.importers.length}">`,
+    ...parts.importers.map((imp) => `    <importer file="${imp}" />`),
+    "  </imported_by>",
+    "</context_packet>"
+  ].join("\n");
+}
 function registerContextPacketTool(registry, ctx) {
   registry.register(
     "ctx_get_context_packet",
     {
       name: "ctx_get_context_packet",
-      description: "Returns a smart multi-file context packet: the full target file, skeletons of its imports, and the list of files that import it. Reduces token usage by ~80% vs. sending full dependencies.",
+      description: "Returns a smart multi-file context packet: the full target file, skeletons of its imports, and the list of files that import it. Reduces token usage by ~80% vs. sending full dependencies. When callers opt into the budget surface, over-budget responses re-render the packet with the primary file ALSO replaced by its Skeletonizer view.",
       inputSchema: {
         type: "object",
         properties: {
           target_file: { type: "string", description: "Relative path to the primary file" },
           mode: { type: "string", enum: ["edit", "read"], description: "Context mode (default: edit)" },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: {
+            type: "number",
+            description: "Soft response budget in tokens. Default: 6000 (when opted into)."
+          },
+          on_budget_exceeded: {
+            type: "string",
+            enum: ["skeleton", "truncate", "error"],
+            description: "Behavior when over budget. 'skeleton' (default) skeletonizes the primary; 'truncate' slices; 'error' throws."
+          },
+          response_format: {
+            type: "string",
+            enum: ["full", "skeleton", "auto"],
+            description: "'skeleton' forces the skeletonized-primary packet; 'full'/'auto' lets the budget decide."
+          }
         },
         required: ["target_file"]
       }
     },
     async (args) => {
-      const { target_file, mode, project_root } = Schema3.parse(args);
-      const [skeletonizer, graph] = await Promise.all([ctx.getSkeletonizer(project_root), ctx.getGraph(project_root)]);
-      const pathValidator = ctx.getPathValidator(project_root);
-      const primaryContent = pathValidator.readFile(target_file);
-      const imports = graph.getImports(target_file);
-      const importers = graph.getImporters(target_file);
+      const parsed = Schema3.parse(args);
+      const [skeletonizer, graph] = await Promise.all([
+        ctx.getSkeletonizer(parsed.project_root),
+        ctx.getGraph(parsed.project_root)
+      ]);
+      const pathValidator = ctx.getPathValidator(parsed.project_root);
+      const primaryContent = pathValidator.readFile(parsed.target_file);
+      const imports = graph.getImports(parsed.target_file);
+      const importers = graph.getImporters(parsed.target_file);
       const skeletons = await Promise.all(
         imports.map(async (dep) => {
           try {
@@ -4738,19 +5038,29 @@ ${sk}`;
           }
         })
       );
-      return [
-        `<context_packet target="${target_file}" mode="${mode}">`,
-        `  <primary_context file="${target_file}">`,
-        `    ${primaryContent.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}`,
-        "  </primary_context>",
-        `  <dependency_skeletons count="${imports.length}">`,
-        ...skeletons.map((s) => `    ${s}`),
-        "  </dependency_skeletons>",
-        `  <imported_by count="${importers.length}">`,
-        ...importers.map((imp) => `    <importer file="${imp}" />`),
-        "  </imported_by>",
-        "</context_packet>"
-      ].join("\n");
+      const parts = {
+        target_file: parsed.target_file,
+        mode: parsed.mode,
+        primaryContent,
+        skeletons,
+        imports,
+        importers
+      };
+      const full = renderPacket(parts);
+      if (!hasBudgetArgs(args)) return full;
+      const absPrimary = pathValidator.validate(parsed.target_file);
+      const skeletonProducer = async () => {
+        const primarySkeleton = await skeletonizer.skeletonize(absPrimary);
+        return renderPacket({ ...parts, primaryContent: primarySkeleton });
+      };
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_get_context_packet",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS3,
+        skeletonProducer
+      });
+      return wrapResponse(result);
     }
   );
 }
@@ -4845,9 +5155,14 @@ function registerCallGraphTool(registry, ctx) {
 
 // packages/core/src/tools/definition.ts
 import { z as z7 } from "zod";
+var DEFAULT_MAX_RESPONSE_TOKENS4 = 2e3;
 var Schema5 = z7.object({
   symbol: z7.string().describe("Symbol name to look up"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface (all optional; back-compat preserved) ──
+  max_response_tokens: z7.number().int().positive().optional().describe("Soft response budget in tokens. Default: 2000 (when budget surface is opted into). No skeleton fallback for this tool \u2014 the response is structural metadata; over-budget falls back to truncation."),
+  on_budget_exceeded: z7.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice the XML (no file context to skeletonize from); 'error' throws."),
+  response_format: z7.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default. 'skeleton' is accepted for consistency but produces the same output as 'full' here \u2014 the response is already a compact symbol list.")
 });
 function escapeXML5(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -4857,33 +5172,57 @@ function registerDefinitionTool(registry, ctx) {
     "ctx_get_definition",
     {
       name: "ctx_get_definition",
-      description: "Look up the definition of a symbol by name. Returns file path, type, and signature for all definitions matching the symbol name.",
+      description: "Look up the definition of a symbol by name. Returns file path, type, and signature for all definitions matching the symbol name. When callers opt into the budget surface (max_response_tokens / on_budget_exceeded / response_format), the response is wrapped in a {data, meta} envelope and over-budget responses are truncated (no skeleton fallback \u2014 the response is already structural).",
       inputSchema: {
         type: "object",
         properties: {
           symbol: { type: "string", description: "Symbol name to look up" },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: {
+            type: "number",
+            description: "Soft response budget in tokens. Default: 2000 (when budget surface is opted into)."
+          },
+          on_budget_exceeded: {
+            type: "string",
+            enum: ["skeleton", "truncate", "error"],
+            description: "Behavior when over budget. 'skeleton'/'truncate' both slice the XML; 'error' throws."
+          },
+          response_format: {
+            type: "string",
+            enum: ["full", "skeleton", "auto"],
+            description: "'full'/'auto' default; 'skeleton' produces the same output (response is already compact)."
+          }
         },
         required: ["symbol"]
       }
     },
     async (args) => {
-      const { symbol, project_root } = Schema5.parse(args);
-      const graph = await ctx.getGraph(project_root);
-      const definitions = graph.lookupSymbol(symbol);
+      const parsed = Schema5.parse(args);
+      const graph = await ctx.getGraph(parsed.project_root);
+      const definitions = graph.lookupSymbol(parsed.symbol);
+      let full;
       if (definitions.length === 0) {
-        return `<definitions symbol="${escapeXML5(symbol)}" count="0">
+        full = `<definitions symbol="${escapeXML5(parsed.symbol)}" count="0">
   <!-- Symbol not found -->
 </definitions>`;
-      }
-      const lines = [`<definitions symbol="${escapeXML5(symbol)}" count="${definitions.length}">`];
-      for (const def of definitions) {
-        lines.push(`  <definition file="${def.filePath}" type="${def.type}">`);
-        lines.push(`    ${def.signature.replace(/&/g, "&amp;").replace(/</g, "&lt;")}`);
-        lines.push("  </definition>");
-      }
-      lines.push("</definitions>");
-      return lines.join("\n");
+      } else {
+        const lines = [`<definitions symbol="${escapeXML5(parsed.symbol)}" count="${definitions.length}">`];
+        for (const def of definitions) {
+          lines.push(`  <definition file="${def.filePath}" type="${def.type}">`);
+          lines.push(`    ${def.signature.replace(/&/g, "&amp;").replace(/</g, "&lt;")}`);
+          lines.push("  </definition>");
+        }
+        lines.push("</definitions>");
+        full = lines.join("\n");
+      }
+      if (!hasBudgetArgs(args)) return full;
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_get_definition",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS4
+      });
+      return wrapResponse(result);
     }
   );
 }
@@ -5848,6 +6187,7 @@ function registerSurprisingConnectionsTool(registry, ctx) {
 // packages/core/src/tools/wiki-generate.ts
 import { z as z17 } from "zod";
 import fs14 from "fs";
+var DEFAULT_MAX_RESPONSE_TOKENS5 = 12e3;
 var Schema15 = z17.object({
   force: z17.boolean().optional().default(false).describe(
     "Regenerate all pages even if content unchanged (default: false)"
@@ -5855,7 +6195,11 @@ var Schema15 = z17.object({
   detail_level: z17.enum(["standard", "minimal"]).default("standard").describe(
     '"standard" (default) lists each written page with size. "minimal" returns counts only.'
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z17.number().int().positive().optional().describe("Soft response budget. Default: 12000 (when opted in). Over-budget re-renders at detail_level=minimal (counts only) \u2014 the wiki files themselves are unaffected."),
+  on_budget_exceeded: z17.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) downgrades to minimal output; 'truncate' slices; 'error' throws."),
+  response_format: z17.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces minimal output regardless of budget; 'full'/'auto' lets the budget decide.")
 });
 function escapeXML14(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -5885,7 +6229,10 @@ function registerWikiGenerateTool(registry, ctx) {
             enum: ["standard", "minimal"],
             description: '"standard" lists written pages with size. "minimal" returns counts only.'
           },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: { type: "number", description: "Soft response budget. Default: 12000 (when opted in)." },
+          on_budget_exceeded: { type: "string", enum: ["skeleton", "truncate", "error"], description: "Behavior over budget. 'skeleton' (default) downgrades to minimal; 'truncate' slices; 'error' throws." },
+          response_format: { type: "string", enum: ["full", "skeleton", "auto"], description: "'skeleton' forces minimal output; 'full'/'auto' lets the budget decide." }
         }
       }
     },
@@ -5894,20 +6241,30 @@ function registerWikiGenerateTool(registry, ctx) {
       const [graph, skeletonizer] = await Promise.all([ctx.getGraph(project_root), ctx.getSkeletonizer(project_root)]);
       const generator = new WikiGenerator(graph, ctx.projectRoot, skeletonizer);
       const result = await generator.generate(force);
-      if (detail_level === "minimal") {
-        return `<wiki_generate detail_level="minimal" wiki_dir="${escapeXML14(result.wikiDir)}" written="${result.written.length}" skipped="${result.skipped.length}" />`;
-      }
-      const lines = [
-        `<wiki_generate wiki_dir="${escapeXML14(result.wikiDir)}" written="${result.written.length}" skipped="${result.skipped.length}">`
-      ];
-      for (const p of result.written) {
-        const size = safeFileSize(p.filePath);
-        lines.push(
-          `  <page community="${escapeXML14(p.communityName)}" file="${escapeXML14(p.filePath)}" size="${size}" status="written" />`
-        );
-      }
-      lines.push("</wiki_generate>");
-      return lines.join("\n");
+      const renderMinimal = () => `<wiki_generate detail_level="minimal" wiki_dir="${escapeXML14(result.wikiDir)}" written="${result.written.length}" skipped="${result.skipped.length}" />`;
+      const renderStandard = () => {
+        const lines = [
+          `<wiki_generate wiki_dir="${escapeXML14(result.wikiDir)}" written="${result.written.length}" skipped="${result.skipped.length}">`
+        ];
+        for (const p of result.written) {
+          const size = safeFileSize(p.filePath);
+          lines.push(
+            `  <page community="${escapeXML14(p.communityName)}" file="${escapeXML14(p.filePath)}" size="${size}" status="written" />`
+          );
+        }
+        lines.push("</wiki_generate>");
+        return lines.join("\n");
+      };
+      const full = detail_level === "minimal" ? renderMinimal() : renderStandard();
+      if (!hasBudgetArgs(args)) return full;
+      const budgetResult = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_wiki_generate",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS5,
+        skeletonProducer: detail_level === "standard" ? async () => renderMinimal() : void 0
+      });
+      return wrapResponse(budgetResult);
     }
   );
 }
@@ -5956,6 +6313,7 @@ function registerGraphExportTool(registry, ctx) {
 import { z as z19 } from "zod";
 import { execFile } from "child_process";
 import { promisify as promisify2 } from "util";
+var DEFAULT_MAX_RESPONSE_TOKENS6 = 8e3;
 var execFileAsync = promisify2(execFile);
 var Schema17 = z19.object({
   changed_files: z19.array(z19.string()).optional().describe(
@@ -5969,7 +6327,11 @@ var Schema17 = z19.object({
   max_diff_lines: z19.number().min(10).max(2e3).optional().default(300).describe(
     "Max diff lines to include per file (default: 300)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z19.number().int().positive().optional().describe("Soft response budget. Default: 8000 (when opted in). Over-budget re-renders without <skeleton> blocks and without the transitive_importers section \u2014 keeps diffs, direct importers, and call sites."),
+  on_budget_exceeded: z19.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops skeletons + transitive importers; 'truncate' slices; 'error' throws."),
+  response_format: z19.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the lighter view; 'full'/'auto' lets the budget decide.")
 });
 function escapeXML16(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -6017,7 +6379,10 @@ function registerGitDiffReviewTool(registry, ctx) {
             description: "Include API skeletons for changed and importer files (default: true)"
           },
           max_diff_lines: { type: "number", description: "Max diff lines per file (default: 300)" },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: { type: "number", description: "Soft response budget. Default: 8000 (when opted in)." },
+          on_budget_exceeded: { type: "string", enum: ["skeleton", "truncate", "error"], description: "Behavior over budget. 'skeleton' (default) drops <skeleton> blocks + transitive importers; 'truncate' slices; 'error' throws." },
+          response_format: { type: "string", enum: ["full", "skeleton", "auto"], description: "'skeleton' forces lighter view; 'full'/'auto' lets the budget decide." }
         }
       }
     },
@@ -6037,10 +6402,21 @@ function registerGitDiffReviewTool(registry, ctx) {
           logger.warn("git diff failed \u2014 no changed files detected");
         }
       }
+      const maybeBudget = async (full2, skeletonProducer) => {
+        if (!hasBudgetArgs(args)) return full2;
+        const result = await enforceBudget({
+          full: full2,
+          args: readBudgetArgs(args),
+          toolName: "ctx_git_diff_review",
+          defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS6,
+          skeletonProducer
+        });
+        return wrapResponse(result);
+      };
       if (files.length === 0) {
-        return `<git_diff_review changed_files="0">
+        return maybeBudget(`<git_diff_review changed_files="0">
   <!-- No changed files detected -->
-</git_diff_review>`;
+</git_diff_review>`);
       }
       const graph = await ctx.getGraph(project_root);
       const blast = await computeBlastRadius({
@@ -6049,62 +6425,69 @@ function registerGitDiffReviewTool(registry, ctx) {
         projectRoot: ctx.projectRoot,
         graph
       });
-      const lines = [
-        `<git_diff_review changed_files="${files.length}" depth="${depth}">`
-      ];
-      lines.push(`  <changed_files count="${files.length}">`);
-      for (const file of files) {
-        lines.push(`    <file path="${escapeXML16(file)}">`);
+      const changedFileData = await Promise.all(files.map(async (file) => {
         const rawDiff = use_git ? await getFileDiff(ctx.projectRoot, file) : "";
         const diffLines = rawDiff ? rawDiff.split("\n") : [];
         const truncated = diffLines.length > max_diff_lines;
         const diffContent = truncated ? [...diffLines.slice(0, max_diff_lines), `... (${diffLines.length - max_diff_lines} more lines)`].join("\n") : rawDiff;
-        lines.push(`      <diff lines="${diffLines.length}" truncated="${truncated}">`);
-        if (diffContent) {
-          lines.push(escapeXML16(diffContent));
-        }
-        lines.push("      </diff>");
-        if (include_skeletons) {
-          const skeleton = await trySkeletonize(ctx, file, project_root);
-          if (skeleton) {
-            lines.push("      <skeleton>");
-            lines.push(escapeXML16(skeleton));
-            lines.push("      </skeleton>");
+        const skeleton = include_skeletons ? await trySkeletonize(ctx, file, project_root) : "";
+        return { file, diffLines, truncated, diffContent, skeleton };
+      }));
+      const skeletonLimit = 5;
+      const directImporterSkeletons = await Promise.all(
+        blast.directImporters.map(async (file, i) => ({
+          file,
+          skeleton: include_skeletons && i < skeletonLimit ? await trySkeletonize(ctx, file, project_root) : ""
+        }))
+      );
+      const render = (withSkeletons, withTransitive) => {
+        const out = [`<git_diff_review changed_files="${files.length}" depth="${depth}">`];
+        out.push(`  <changed_files count="${files.length}">`);
+        for (const cd of changedFileData) {
+          out.push(`    <file path="${escapeXML16(cd.file)}">`);
+          out.push(`      <diff lines="${cd.diffLines.length}" truncated="${cd.truncated}">`);
+          if (cd.diffContent) out.push(escapeXML16(cd.diffContent));
+          out.push("      </diff>");
+          if (withSkeletons && cd.skeleton) {
+            out.push("      <skeleton>");
+            out.push(escapeXML16(cd.skeleton));
+            out.push("      </skeleton>");
           }
+          out.push("    </file>");
+        }
+        out.push("  </changed_files>");
+        out.push(`  <direct_importers count="${blast.directImporters.length}">`);
+        for (const di of directImporterSkeletons) {
+          out.push(`    <file path="${escapeXML16(di.file)}">`);
+          if (withSkeletons && di.skeleton) {
+            out.push("      <skeleton>");
+            out.push(escapeXML16(di.skeleton));
+            out.push("      </skeleton>");
+          }
+          out.push("    </file>");
         }
-        lines.push("    </file>");
-      }
-      lines.push("  </changed_files>");
-      lines.push(`  <direct_importers count="${blast.directImporters.length}">`);
-      const skeletonLimit = 5;
-      for (let i = 0; i < blast.directImporters.length; i++) {
-        const file = blast.directImporters[i];
-        lines.push(`    <file path="${escapeXML16(file)}">`);
-        if (include_skeletons && i < skeletonLimit) {
-          const skeleton = await trySkeletonize(ctx, file, project_root);
-          if (skeleton) {
-            lines.push("      <skeleton>");
-            lines.push(escapeXML16(skeleton));
-            lines.push("      </skeleton>");
+        out.push("  </direct_importers>");
+        if (withTransitive) {
+          out.push(`  <transitive_importers count="${blast.transitiveImporters.length}">`);
+          for (const file of blast.transitiveImporters) {
+            out.push(`    <file path="${escapeXML16(file)}" />`);
           }
+          out.push("  </transitive_importers>");
+        } else {
+          out.push(`  <transitive_importers count="${blast.transitiveImporters.length}" omitted="budget"/>`);
         }
-        lines.push("    </file>");
-      }
-      lines.push("  </direct_importers>");
-      lines.push(`  <transitive_importers count="${blast.transitiveImporters.length}">`);
-      for (const file of blast.transitiveImporters) {
-        lines.push(`    <file path="${escapeXML16(file)}" />`);
-      }
-      lines.push("  </transitive_importers>");
-      lines.push(`  <call_sites count="${blast.callSites.length}">`);
-      for (const cs of blast.callSites) {
-        lines.push(
-          `    <call_site file="${escapeXML16(cs.file)}" caller="${escapeXML16(cs.callerSymbol)}" callee="${escapeXML16(cs.calleeSymbol)}" />`
-        );
-      }
-      lines.push("  </call_sites>");
-      lines.push("</git_diff_review>");
-      return lines.join("\n");
+        out.push(`  <call_sites count="${blast.callSites.length}">`);
+        for (const cs of blast.callSites) {
+          out.push(
+            `    <call_site file="${escapeXML16(cs.file)}" caller="${escapeXML16(cs.callerSymbol)}" callee="${escapeXML16(cs.calleeSymbol)}" />`
+          );
+        }
+        out.push("  </call_sites>");
+        out.push("</git_diff_review>");
+        return out.join("\n");
+      };
+      const full = render(include_skeletons, true);
+      return maybeBudget(full, async () => render(false, false));
     }
   );
 }
@@ -6113,13 +6496,18 @@ function registerGitDiffReviewTool(registry, ctx) {
 import { z as z20 } from "zod";
 import fs15 from "fs";
 import path17 from "path";
+var DEFAULT_MAX_RESPONSE_TOKENS7 = 4e3;
 var Schema18 = z20.object({
   symbol: z20.string().min(1).describe("Symbol name to rename (exact match, case-sensitive)"),
   new_name: z20.string().min(1).describe("New name for the symbol"),
   max_files: z20.number().min(1).max(200).optional().default(50).describe(
     "Maximum number of files to scan for occurrences (default: 50)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z20.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when opted in). Over-budget drops the per-change before/after lines; keeps the file+occurrence summary so callers can decide which files to drill into."),
+  on_budget_exceeded: z20.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops change details; 'truncate' slices; 'error' throws."),
+  response_format: z20.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the summary-only view; 'full'/'auto' lets the budget decide.")
 });
 function escapeXML17(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -6167,7 +6555,10 @@ function registerRefactorPreviewTool(registry, ctx) {
             type: "number",
             description: "Maximum number of candidate files to scan (default: 50)"
           },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: { type: "number", description: "Soft response budget. Default: 4000 (when opted in)." },
+          on_budget_exceeded: { type: "string", enum: ["skeleton", "truncate", "error"], description: "Behavior over budget. 'skeleton' (default) drops change details; 'truncate' slices; 'error' throws." },
+          response_format: { type: "string", enum: ["full", "skeleton", "auto"], description: "'skeleton' forces summary-only view; 'full'/'auto' lets the budget decide." }
         },
         required: ["symbol", "new_name"]
       }
@@ -6198,36 +6589,53 @@ function registerRefactorPreviewTool(registry, ctx) {
           totalOccurrences += occurrences.length;
         }
       }
-      const xmlLines = [
-        `<refactor_preview symbol="${escapeXML17(symbol)}" new_name="${escapeXML17(new_name)}" total_files="${fileChanges.length}" total_occurrences="${totalOccurrences}">`
-      ];
-      xmlLines.push(`  <definitions count="${definitions.length}">`);
-      for (const def of definitions) {
-        xmlLines.push(
-          `    <definition file="${escapeXML17(def.filePath)}" type="${escapeXML17(def.type)}" signature="${escapeXML17(def.signature)}" />`
-        );
-      }
-      xmlLines.push("  </definitions>");
-      xmlLines.push(`  <changes count="${fileChanges.length}">`);
-      for (const fc of fileChanges) {
-        xmlLines.push(`    <file path="${escapeXML17(fc.filePath)}" occurrences="${fc.occurrences.length}">`);
-        for (const occ of fc.occurrences) {
-          xmlLines.push(`      <change line="${occ.line}">`);
-          xmlLines.push(`        <before>${escapeXML17(occ.before)}</before>`);
-          xmlLines.push(`        <after>${escapeXML17(occ.after)}</after>`);
-          xmlLines.push("      </change>");
+      const render = (includeChanges) => {
+        const xmlLines = [
+          `<refactor_preview symbol="${escapeXML17(symbol)}" new_name="${escapeXML17(new_name)}" total_files="${fileChanges.length}" total_occurrences="${totalOccurrences}">`
+        ];
+        xmlLines.push(`  <definitions count="${definitions.length}">`);
+        for (const def of definitions) {
+          xmlLines.push(
+            `    <definition file="${escapeXML17(def.filePath)}" type="${escapeXML17(def.type)}" signature="${escapeXML17(def.signature)}" />`
+          );
         }
-        xmlLines.push("    </file>");
-      }
-      xmlLines.push("  </changes>");
-      xmlLines.push("</refactor_preview>");
-      return xmlLines.join("\n");
+        xmlLines.push("  </definitions>");
+        xmlLines.push(`  <changes count="${fileChanges.length}">`);
+        for (const fc of fileChanges) {
+          if (includeChanges) {
+            xmlLines.push(`    <file path="${escapeXML17(fc.filePath)}" occurrences="${fc.occurrences.length}">`);
+            for (const occ of fc.occurrences) {
+              xmlLines.push(`      <change line="${occ.line}">`);
+              xmlLines.push(`        <before>${escapeXML17(occ.before)}</before>`);
+              xmlLines.push(`        <after>${escapeXML17(occ.after)}</after>`);
+              xmlLines.push("      </change>");
+            }
+            xmlLines.push("    </file>");
+          } else {
+            xmlLines.push(`    <file path="${escapeXML17(fc.filePath)}" occurrences="${fc.occurrences.length}"/>`);
+          }
+        }
+        xmlLines.push("  </changes>");
+        xmlLines.push("</refactor_preview>");
+        return xmlLines.join("\n");
+      };
+      const full = render(true);
+      if (!hasBudgetArgs(args)) return full;
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_refactor_preview",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS7,
+        skeletonProducer: async () => render(false)
+      });
+      return wrapResponse(result);
     }
   );
 }
 
 // packages/core/src/tools/execution-flow.ts
 import { z as z21 } from "zod";
+var DEFAULT_MAX_RESPONSE_TOKENS8 = 4e3;
 var Schema19 = z21.object({
   entry_point: z21.string().min(1).describe("Symbol name to start the execution flow from"),
   entry_file: z21.string().optional().describe(
@@ -6237,7 +6645,11 @@ var Schema19 = z21.object({
   max_nodes: z21.number().min(1).max(200).optional().default(50).describe(
     "Max total steps to include in output (default: 50)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z21.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when opted in). No skeleton fallback \u2014 response is already a bounded step list; over-budget falls through to truncation."),
+  on_budget_exceeded: z21.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice; 'error' throws."),
+  response_format: z21.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default; 'skeleton' same output.")
 });
 function escapeXML18(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -6299,7 +6711,10 @@ function registerExecutionFlowTool(registry, ctx) {
             type: "number",
             description: "Max total steps to return (default: 50)"
           },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: { type: "number", description: "Soft response budget. Default: 4000 (when opted in)." },
+          on_budget_exceeded: { type: "string", enum: ["skeleton", "truncate", "error"], description: "Behavior over budget." },
+          response_format: { type: "string", enum: ["full", "skeleton", "auto"], description: "'full'/'auto' default; 'skeleton' same output." }
         },
         required: ["entry_point"]
       }
@@ -6325,10 +6740,20 @@ function registerExecutionFlowTool(registry, ctx) {
           }
         }
       }
+      const maybeBudget = async (full) => {
+        if (!hasBudgetArgs(args)) return full;
+        const result = await enforceBudget({
+          full,
+          args: readBudgetArgs(args),
+          toolName: "ctx_execution_flow",
+          defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS8
+        });
+        return wrapResponse(result);
+      };
       if (!resolvedFile) {
-        return `<execution_flow entry="${escapeXML18(entry_point)}" total_steps="0" has_cycles="false">
+        return maybeBudget(`<execution_flow entry="${escapeXML18(entry_point)}" total_steps="0" has_cycles="false">
   <!-- No call graph entries found for symbol -->
-</execution_flow>`;
+</execution_flow>`);
       }
       const { steps, hasCycles } = buildFlowSteps(
         entry_point,
@@ -6353,7 +6778,7 @@ function registerExecutionFlowTool(registry, ctx) {
         }
       }
       xmlLines.push("</execution_flow>");
-      return xmlLines.join("\n");
+      return maybeBudget(xmlLines.join("\n"));
     }
   );
 }
@@ -6362,6 +6787,7 @@ function registerExecutionFlowTool(registry, ctx) {
 import { z as z22 } from "zod";
 import fs16 from "fs";
 import path18 from "path";
+var DEFAULT_MAX_RESPONSE_TOKENS9 = 4e3;
 var ALIAS_REGEX = /^[a-z0-9-]{1,40}$/;
 var RESERVED_ALIASES = /* @__PURE__ */ new Set([
   "register",
@@ -6464,7 +6890,11 @@ var Schema20 = z22.object({
   repos: z22.array(z22.string()).optional().describe(
     "Specific repo root paths to search. Omit to search all registered repos."
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z22.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when opted in). Over-budget drops content snippets (repo + path + score only)."),
+  on_budget_exceeded: z22.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops content snippets; 'truncate' slices; 'error' throws."),
+  response_format: z22.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the path-and-score-only view; 'full'/'auto' lets the budget decide.")
 });
 function escapeXML19(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -6486,7 +6916,10 @@ function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
             items: { type: "string" },
             description: "Specific repo root paths to search. Omit to search all registered repos."
           },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: { type: "number", description: "Soft response budget. Default: 4000 (when opted in)." },
+          on_budget_exceeded: { type: "string", enum: ["skeleton", "truncate", "error"], description: "Behavior over budget. 'skeleton' (default) drops content snippets; 'truncate' slices; 'error' throws." },
+          response_format: { type: "string", enum: ["full", "skeleton", "auto"], description: "'skeleton' forces path+score-only view; 'full'/'auto' lets the budget decide." }
         },
         required: ["query"]
       }
@@ -6555,19 +6988,32 @@ function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
         );
       }
       xmlLines.push("  </repos>");
-      xmlLines.push(`  <results count="${topResults.length}">`);
-      for (const r of topResults) {
-        xmlLines.push(
-          `    <result repo="${escapeXML19(r.repoName)}" file="${escapeXML19(r.filePath)}" score="${r.score.toFixed(4)}">`
-        );
-        if (r.content) {
-          xmlLines.push(`      ${escapeXML19(r.content.slice(0, 200))}`);
+      const render = (includeContent) => {
+        const out = [...xmlLines];
+        out.push(`  <results count="${topResults.length}">`);
+        for (const r of topResults) {
+          if (includeContent && r.content) {
+            out.push(`    <result repo="${escapeXML19(r.repoName)}" file="${escapeXML19(r.filePath)}" score="${r.score.toFixed(4)}">`);
+            out.push(`      ${escapeXML19(r.content.slice(0, 200))}`);
+            out.push("    </result>");
+          } else {
+            out.push(`    <result repo="${escapeXML19(r.repoName)}" file="${escapeXML19(r.filePath)}" score="${r.score.toFixed(4)}"/>`);
+          }
         }
-        xmlLines.push("    </result>");
-      }
-      xmlLines.push("  </results>");
-      xmlLines.push("</cross_repo_search>");
-      return xmlLines.join("\n");
+        out.push("  </results>");
+        out.push("</cross_repo_search>");
+        return out.join("\n");
+      };
+      const full = render(true);
+      if (!hasBudgetArgs(args)) return full;
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_cross_repo_search",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS9,
+        skeletonProducer: async () => render(false)
+      });
+      return wrapResponse(result);
     }
   );
 }
@@ -6576,6 +7022,7 @@ function registerCrossRepoSearchTool(registry, _ctx, registryFilePath) {
 import { z as z23 } from "zod";
 import fs17 from "fs";
 import path19 from "path";
+var DEFAULT_MAX_RESPONSE_TOKENS10 = 2e3;
 var Schema21 = z23.object({
   symbol: z23.string().min(1).describe("Symbol name to rename (exact, case-sensitive)"),
   new_name: z23.string().min(1).describe("New name for the symbol"),
@@ -6585,7 +7032,11 @@ var Schema21 = z23.object({
   max_files: z23.number().min(1).max(200).optional().default(50).describe(
     "Maximum candidate files to process (default: 50)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z23.number().int().positive().optional().describe("Soft response budget. Default: 2000 (when opted in). No skeleton fallback \u2014 response is already compact; over-budget falls through to truncation."),
+  on_budget_exceeded: z23.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice the XML; 'error' throws."),
+  response_format: z23.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default; 'skeleton' produces the same output.")
 });
 function escapeXML20(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -6619,7 +7070,10 @@ function registerApplyRefactorTool(registry, ctx) {
           new_name: { type: "string", description: "New name" },
           dry_run: { type: "boolean", description: "Preview only, no writes (default: false)" },
           max_files: { type: "number", description: "Max candidate files (default: 50)" },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: { type: "number", description: "Soft response budget. Default: 2000 (when opted in)." },
+          on_budget_exceeded: { type: "string", enum: ["skeleton", "truncate", "error"], description: "Behavior over budget." },
+          response_format: { type: "string", enum: ["full", "skeleton", "auto"], description: "'full'/'auto' default; 'skeleton' same output." }
         },
         required: ["symbol", "new_name"]
       }
@@ -6659,7 +7113,15 @@ function registerApplyRefactorTool(registry, ctx) {
         );
       }
       xml.push("</apply_refactor>");
-      return xml.join("\n");
+      const full = xml.join("\n");
+      if (!hasBudgetArgs(args)) return full;
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_apply_refactor",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS10
+      });
+      return wrapResponse(result);
     }
   );
 }
@@ -6780,13 +7242,18 @@ function registerDetectChangesTool(registry, ctx) {
 import { z as z25 } from "zod";
 import fs18 from "fs";
 import path20 from "path";
+var DEFAULT_MAX_RESPONSE_TOKENS11 = 4e3;
 var Schema23 = z25.object({
   query: z25.string().min(1).describe("Search term \u2014 literal or /regex/"),
   mode: z25.enum(["hybrid", "keyword", "semantic"]).optional().default("hybrid"),
   case_sensitive: z25.boolean().optional().default(false),
   limit: z25.number().min(1).max(100).optional().default(20),
   context_lines: z25.number().min(0).max(5).optional().default(1),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z25.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when budget surface is opted into). Over-budget rebuilds the result list without match snippets (paths + match counts only)."),
+  on_budget_exceeded: z25.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops snippets; 'truncate' slices the raw XML; 'error' throws."),
+  response_format: z25.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the path-and-count-only view; 'full'/'auto' lets the budget decide.")
 });
 function escapeXML22(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -6841,27 +7308,53 @@ function registerFullTextSearchTool(registry, ctx) {
           case_sensitive: { type: "boolean", description: "Case-sensitive match (default: false)" },
           limit: { type: "number", description: "Max results (default: 20)" },
           context_lines: { type: "number", description: "Context lines around each match (default: 1)" },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: {
+            type: "number",
+            description: "Soft response budget in tokens. Default: 4000 (when opted into)."
+          },
+          on_budget_exceeded: {
+            type: "string",
+            enum: ["skeleton", "truncate", "error"],
+            description: "Behavior when over budget. 'skeleton' (default) drops match snippets; 'truncate' slices; 'error' throws."
+          },
+          response_format: {
+            type: "string",
+            enum: ["full", "skeleton", "auto"],
+            description: "'skeleton' forces path+count-only view; 'full'/'auto' lets the budget decide."
+          }
         },
         required: ["query"]
       }
     },
     async (args) => {
-      const { query, mode, case_sensitive, limit, context_lines, project_root } = Schema23.parse(args);
+      const parsed = Schema23.parse(args);
+      const { query, mode, case_sensitive, limit, context_lines, project_root } = parsed;
+      const maybeBudget = async (full, skeletonProducer) => {
+        if (!hasBudgetArgs(args)) return full;
+        const result = await enforceBudget({
+          full,
+          args: readBudgetArgs(args),
+          toolName: "ctx_full_text_search",
+          defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS11,
+          skeletonProducer
+        });
+        return wrapResponse(result);
+      };
       if (mode === "semantic") {
         try {
           const { generateEmbedding: generateEmbedding2 } = await import("./embedder-R4KCXSGO.js");
           const store = await ctx.getStore(project_root);
           const embedding = await generateEmbedding2(query);
           const results = await store.search(embedding, limit);
-          const xml2 = [`<full_text_search query="${escapeXML22(query)}" mode="semantic" count="${results.length}">`];
+          const xml = [`<full_text_search query="${escapeXML22(query)}" mode="semantic" count="${results.length}">`];
           for (const r of results) {
-            xml2.push(`  <result file="${escapeXML22(r.filePath)}" matches="0"/>`);
+            xml.push(`  <result file="${escapeXML22(r.filePath)}" matches="0"/>`);
           }
-          xml2.push("</full_text_search>");
-          return xml2.join("\n");
+          xml.push("</full_text_search>");
+          return maybeBudget(xml.join("\n"));
         } catch {
-          return `<full_text_search query="${escapeXML22(query)}" mode="semantic" count="0"/>`;
+          return maybeBudget(`<full_text_search query="${escapeXML22(query)}" mode="semantic" count="0"/>`);
         }
       }
       const pattern = buildPattern(query, case_sensitive);
@@ -6903,18 +7396,28 @@ function registerFullTextSearchTool(registry, ctx) {
         } catch {
         }
       }
-      const xml = [
-        `<full_text_search query="${escapeXML22(query)}" mode="${mode}" case_sensitive="${case_sensitive}" count="${merged.length}">`
-      ];
-      for (const r of merged) {
-        xml.push(`  <result file="${escapeXML22(r.filePath)}" matches="${r.matchCount}">`);
-        for (const snippet of r.snippets) {
-          xml.push(`    <match><![CDATA[${snippet}]]></match>`);
+      const render = (includeSnippets) => {
+        const xml = [
+          `<full_text_search query="${escapeXML22(query)}" mode="${mode}" case_sensitive="${case_sensitive}" count="${merged.length}">`
+        ];
+        for (const r of merged) {
+          if (includeSnippets && r.snippets.length > 0) {
+            xml.push(`  <result file="${escapeXML22(r.filePath)}" matches="${r.matchCount}">`);
+            for (const snippet of r.snippets) {
+              xml.push(`    <match><![CDATA[${snippet}]]></match>`);
+            }
+            xml.push("  </result>");
+          } else {
+            xml.push(`  <result file="${escapeXML22(r.filePath)}" matches="${r.matchCount}"/>`);
+          }
         }
-        xml.push("  </result>");
-      }
-      xml.push("</full_text_search>");
-      return xml.join("\n");
+        xml.push("</full_text_search>");
+        return xml.join("\n");
+      };
+      return maybeBudget(
+        render(true),
+        async () => render(false)
+      );
     }
   );
 }
@@ -7301,6 +7804,7 @@ function registerGraphDiffTool(registry, ctx) {
 
 // packages/core/src/tools/find-large-functions.ts
 import { z as z30 } from "zod";
+var DEFAULT_MAX_RESPONSE_TOKENS12 = 2e3;
 var schema3 = z30.object({
   threshold: z30.number().int().min(1).default(50).describe(
     "Minimum line count to include (default: 50). Functions/classes shorter than this are excluded."
@@ -7311,7 +7815,11 @@ var schema3 = z30.object({
   limit: z30.number().int().min(1).max(200).default(30).describe(
     "Maximum results to return (default: 30)."
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: z30.number().int().positive().optional().describe("Soft response budget. Default: 2000 (when opted in). No skeleton fallback \u2014 response is already structural; over-budget falls through to truncation."),
+  on_budget_exceeded: z30.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice the XML; 'error' throws."),
+  response_format: z30.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default; 'skeleton' produces the same output (response is already compact).")
 });
 function findLargeFunctions(graph, threshold, fileFilter) {
   const results = [];
@@ -7361,7 +7869,10 @@ function registerFindLargeFunctionsTool(registry, ctx) {
             type: "number",
             description: "Maximum results to return (default: 30, max: 200)."
           },
-          project_root: PROJECT_ROOT_JSON_SCHEMA
+          project_root: PROJECT_ROOT_JSON_SCHEMA,
+          max_response_tokens: { type: "number", description: "Soft response budget. Default: 2000 (when opted in)." },
+          on_budget_exceeded: { type: "string", enum: ["skeleton", "truncate", "error"], description: "Behavior over budget. 'skeleton'/'truncate' slice; 'error' throws." },
+          response_format: { type: "string", enum: ["full", "skeleton", "auto"], description: "'full'/'auto' default; 'skeleton' same output (already compact)." }
         }
       }
     },
@@ -7369,19 +7880,29 @@ function registerFindLargeFunctionsTool(registry, ctx) {
       const { threshold, file_filter, limit, project_root } = schema3.parse(args);
       const graph = await ctx.getGraph(project_root);
       const results = findLargeFunctions(graph, threshold, file_filter).slice(0, limit);
+      let full;
       if (results.length === 0) {
-        return `<ctx_find_large_functions threshold="${threshold}" count="0">
+        full = `<ctx_find_large_functions threshold="${threshold}" count="0">
   <message>No functions or classes exceed ${threshold} lines.</message>
 </ctx_find_large_functions>`;
-      }
-      const lines = [
-        `<ctx_find_large_functions threshold="${threshold}" count="${results.length}">`,
-        ...results.map(
-          (r) => `  <symbol name="${escapeXML24(r.name)}" type="${r.type}" file="${escapeXML24(r.filePath)}" start="${r.startLine}" end="${r.endLine}" lines="${r.lineCount}" />`
-        ),
-        `</ctx_find_large_functions>`
-      ];
-      return lines.join("\n");
+      } else {
+        const lines = [
+          `<ctx_find_large_functions threshold="${threshold}" count="${results.length}">`,
+          ...results.map(
+            (r) => `  <symbol name="${escapeXML24(r.name)}" type="${r.type}" file="${escapeXML24(r.filePath)}" start="${r.startLine}" end="${r.endLine}" lines="${r.lineCount}" />`
+          ),
+          `</ctx_find_large_functions>`
+        ];
+        full = lines.join("\n");
+      }
+      if (!hasBudgetArgs(args)) return full;
+      const result = await enforceBudget({
+        full,
+        args: readBudgetArgs(args),
+        toolName: "ctx_find_large_functions",
+        defaultMaxTokens: DEFAULT_MAX_RESPONSE_TOKENS12
+      });
+      return wrapResponse(result);
     }
   );
 }
@@ -8821,7 +9342,7 @@ var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
 function getTelemetryLevel() {
   return TELEMETRY_LEVEL;
 }
-var CTXLOOM_VERSION = "1.2.6".length > 0 ? "1.2.6" : "dev";
+var CTXLOOM_VERSION = "1.3.0".length > 0 ? "1.3.0" : "dev";
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_KEY = process.env["POSTHOG_API_KEY"] ?? (true ? "phc_CiDkmFLcZ2K6uCpcoSUQLmFrnnUvsyXGhSxopX5TVKE6" : "");
 var SENTRY_DSN = process.env["SENTRY_DSN"] ?? (true ? "https://81c94a0f04a8e242dee493ac1e17f733@o4508531702497280.ingest.de.sentry.io/4511256875368528" : "");
@@ -9551,4 +10072,4 @@ export {
   FirstTouchTracker,
   EmittedOnceTracker
 };
-//# sourceMappingURL=chunk-PVKQ5UQS.js.map
+//# sourceMappingURL=chunk-Q2KTZNNU.js.map