ctxloom-pro 1.2.5 → 1.2.7

package/dist/{chunk-6S3ZF2YS.js → chunk-RY3JAC2Q.js}

@@ -4,7 +4,7 @@ import {
 import {
   collectFiles,
   generateEmbedding
-} from "./chunk-NMXQC5CG.js";
+} from "./chunk-UVR65QBJ.js";
 import {
   logger
 } from "./chunk-TYDMSHV7.js";
@@ -165,7 +165,7 @@ var GrammarLoader = class {
     const url = entry.downloadUrl?.trim() ? entry.downloadUrl : `${this.cdn}/${entry.npmPackage}@${entry.version}/${entry.wasmFile}`;
     const dest = path.join(this.cacheDir, entry.wasmFile);
     logger.info("Downloading grammar", { language, url, source: entry.downloadUrl?.trim() ? "custom" : "cdn" });
-    fs.mkdirSync(this.cacheDir, { recursive: true });
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
     await this.download(url, dest);
     if (entry.sha256 && !this.skipVerify) {
       await this.verifyHash(dest, entry.sha256, language);
@@ -179,6 +179,12 @@ var GrammarLoader = class {
     return new Promise((resolve, reject) => {
       const tmp = dest + ".tmp";
       const file = fs.createWriteStream(tmp);
+      const onFileError = (err) => {
+        file.destroy();
+        fs.rmSync(tmp, { force: true });
+        reject(err);
+      };
+      file.on("error", onFileError);
       const request = https.get(url, (response) => {
         if (response.statusCode === 301 || response.statusCode === 302) {
           const location = response.headers.location;
@@ -208,11 +214,6 @@ var GrammarLoader = class {
           fs.rmSync(tmp, { force: true });
           reject(err);
         });
-        file.on("error", (err) => {
-          file.destroy();
-          fs.rmSync(tmp, { force: true });
-          reject(err);
-        });
         file.on("finish", () => {
           fs.renameSync(tmp, dest);
           resolve();
@@ -843,15 +844,14 @@ var ASTParser = class {
           return;
         }
         case "import_declaration": {
+          const specs = [];
           const walkImport = (n) => {
             if (n.type === "import_spec") {
               const pathNode = n.childForFieldName?.("path");
               if (pathNode) {
                 const spec = pathNode.text.replace(/^"|"$/g, "");
-                nodes.push({
-                  type: "import",
+                specs.push({
                   name: spec,
-                  source: spec,
                   startLine: n.startPosition.row + 1,
                   endLine: n.endPosition.row + 1
                 });
@@ -862,6 +862,25 @@ var ASTParser = class {
             }
           };
           walkImport(node);
+          if (specs.length > 0) {
+            const firstSpec = specs[0];
+            nodes.push({
+              type: "import",
+              name: firstSpec.name,
+              source: firstSpec.name,
+              startLine: node.startPosition.row + 1,
+              endLine: node.endPosition.row + 1
+            });
+          }
+          for (const spec of specs) {
+            nodes.push({
+              type: "import",
+              name: spec.name,
+              source: spec.name,
+              startLine: spec.startLine,
+              endLine: spec.endLine
+            });
+          }
           return;
         }
       }
@@ -1183,6 +1202,24 @@ var ASTParser = class {
     const lines = source.split("\n");
     const walk = (node) => {
       switch (node.type) {
+        case "call": {
+          const methodNode = node.childForFieldName?.("method") ?? node.children.find((c) => c?.type === "identifier");
+          const name = methodNode?.text ?? "";
+          if (name === "require" || name === "require_relative" || name === "load" || name === "autoload") {
+            const argsNode = node.childForFieldName?.("arguments") ?? node.children.find((c) => c?.type === "argument_list");
+            const firstStringArg = argsNode?.children.find((c) => c?.type === "string" || c?.type === "simple_symbol");
+            const spec = firstStringArg?.text.replace(/^['":]+|['"]+$/g, "") ?? "";
+            nodes.push({
+              type: "import",
+              name: spec,
+              source: spec,
+              startLine: node.startPosition.row + 1,
+              endLine: node.endPosition.row + 1
+            });
+            return;
+          }
+          break;
+        }
         case "method":
         case "singleton_method": {
           const nameNode = node.childForFieldName?.("name") ?? node.children.find((c) => c?.type === "identifier");
@@ -1470,9 +1507,18 @@ var ASTParser = class {
     const walk = (node) => {
       switch (node.type) {
         case "import_or_export": {
-          const uriNode = node.children.find((c) => c?.type === "uri");
+          const findUri = (n) => {
+            if (n.type === "uri") return n;
+            for (const c of n.children) {
+              if (!c) continue;
+              const hit = findUri(c);
+              if (hit) return hit;
+            }
+            return void 0;
+          };
+          const uriNode = findUri(node);
           const uri = uriNode?.text?.replace(/['"]/g, "") ?? "";
-          if (uri.startsWith(".")) {
+          if (uri) {
             nodes.push({
               type: "import",
               name: uri,
@@ -3411,8 +3457,8 @@ var CoChangeIndex = class _CoChangeIndex {
     if (event.isBulk || event.isMerge) return;
     const paths = event.files.map((f) => f.path);
     if (paths.length === 0) return;
-    for (const path35 of paths) {
-      this.nodeCounts.set(path35, (this.nodeCounts.get(path35) ?? 0) + 1);
+    for (const path36 of paths) {
+      this.nodeCounts.set(path36, (this.nodeCounts.get(path36) ?? 0) + 1);
     }
     for (let i = 0; i < paths.length; i++) {
       for (let j = i + 1; j < paths.length; j++) {
@@ -3559,8 +3605,8 @@ var ChurnIndex = class _ChurnIndex {
    */
   snapshot() {
     const nodes = {};
-    for (const [path35, raw] of this.nodes) {
-      nodes[path35] = {
+    for (const [path36, raw] of this.nodes) {
+      nodes[path36] = {
         commits: raw.commits,
         churnLines: raw.churnLines,
         bugCommits: raw.bugCommits,
@@ -3575,8 +3621,8 @@ var ChurnIndex = class _ChurnIndex {
    */
   static load(s) {
     const idx = new _ChurnIndex();
-    for (const [path35, raw] of Object.entries(s.nodes)) {
-      idx.nodes.set(path35, {
+    for (const [path36, raw] of Object.entries(s.nodes)) {
+      idx.nodes.set(path36, {
         commits: raw.commits,
         churnLines: raw.churnLines,
         bugCommits: raw.bugCommits,
@@ -3589,8 +3635,8 @@ var ChurnIndex = class _ChurnIndex {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  getOrCreate(path35) {
-    const existing = this.nodes.get(path35);
+  getOrCreate(path36) {
+    const existing = this.nodes.get(path36);
     if (existing !== void 0) return existing;
     const fresh = {
       commits: 0,
@@ -3599,7 +3645,7 @@ var ChurnIndex = class _ChurnIndex {
       authorCounts: {},
       lastTouch: 0
     };
-    this.nodes.set(path35, fresh);
+    this.nodes.set(path36, fresh);
     return fresh;
   }
 };
@@ -3680,12 +3726,12 @@ var OwnershipIndex = class _OwnershipIndex {
    */
   snapshot() {
     const nodes = {};
-    for (const [path35, raw] of this.nodes) {
+    for (const [path36, raw] of this.nodes) {
       const authorWeights = {};
       for (const [email, entry] of Object.entries(raw.authorWeights)) {
         authorWeights[email] = { ...entry };
       }
-      nodes[path35] = { authorWeights, lastTouch: raw.lastTouch };
+      nodes[path36] = { authorWeights, lastTouch: raw.lastTouch };
     }
     return { version: 1, nodes };
   }
@@ -3694,23 +3740,23 @@ var OwnershipIndex = class _OwnershipIndex {
    */
   static load(s) {
     const idx = new _OwnershipIndex();
-    for (const [path35, raw] of Object.entries(s.nodes)) {
+    for (const [path36, raw] of Object.entries(s.nodes)) {
       const authorWeights = {};
       for (const [email, entry] of Object.entries(raw.authorWeights)) {
         authorWeights[email] = { ...entry };
       }
-      idx.nodes.set(path35, { authorWeights, lastTouch: raw.lastTouch });
+      idx.nodes.set(path36, { authorWeights, lastTouch: raw.lastTouch });
     }
     return idx;
   }
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
-  getOrCreate(path35) {
-    const existing = this.nodes.get(path35);
+  getOrCreate(path36) {
+    const existing = this.nodes.get(path36);
     if (existing !== void 0) return existing;
     const fresh = { authorWeights: {}, lastTouch: 0 };
-    this.nodes.set(path35, fresh);
+    this.nodes.set(path36, fresh);
     return fresh;
   }
 };
@@ -4564,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);
     }
   );
 }
@@ -4651,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 {
@@ -4692,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);
     }
   );
 }
@@ -4799,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;");
@@ -4811,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);
     }
   );
 }
@@ -5802,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)"
@@ -5809,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;");
@@ -5839,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." }
         }
       }
     },
@@ -5848,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);
     }
   );
 }
@@ -5910,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(
@@ -5923,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;");
@@ -5971,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." }
         }
       }
     },
@@ -5991,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({
@@ -6003,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));
     }
   );
 }
@@ -6067,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;");
@@ -6121,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"]
       }
@@ -6152,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(
@@ -6191,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;");
@@ -6253,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"]
       }
@@ -6279,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,
@@ -6307,7 +6778,7 @@ function registerExecutionFlowTool(registry, ctx) {
         }
       }
       xmlLines.push("</execution_flow>");
-      return xmlLines.join("\n");
+      return maybeBudget(xmlLines.join("\n"));
     }
   );
 }
@@ -6316,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",
@@ -6418,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;");
@@ -6440,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"]
       }
@@ -6509,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);
     }
   );
 }
@@ -6530,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"),
@@ -6539,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;");
@@ -6573,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"]
       }
@@ -6613,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);
     }
   );
 }
@@ -6734,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;");
@@ -6795,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-5LMEYY4M.js");
+          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);
@@ -6841,7 +7380,7 @@ function registerFullTextSearchTool(registry, ctx) {
       let merged = keywordResults.slice(0, limit);
       if (mode === "hybrid") {
         try {
-          const { generateEmbedding: generateEmbedding2 } = await import("./embedder-5LMEYY4M.js");
+          const { generateEmbedding: generateEmbedding2 } = await import("./embedder-R4KCXSGO.js");
           const store = await ctx.getStore(project_root);
           const embedding = await generateEmbedding2(query);
           const vectorResults = await store.search(embedding, Math.ceil(limit / 2));
@@ -6857,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)
+      );
     }
   );
 }
@@ -7255,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."
@@ -7265,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 = [];
@@ -7315,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)." }
         }
       }
     },
@@ -7323,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);
     }
   );
 }
@@ -8717,113 +9284,15 @@ function maybePrintExpiryWarning(expiresAt) {
 }
 
 // packages/core/src/license/index.ts
-import os3 from "os";
-var REVALIDATION_DAYS = 7;
-var GRACE_HOURS = 72;
-function defaultHome() {
-  return os3.homedir();
-}
-async function isActive(opts = {}) {
-  const home = opts.home ?? defaultHome();
-  const store = new LicenseStore(home);
-  const license = await store.read();
-  if (!license) return false;
-  if (new Date(license.expiresAt).getTime() <= Date.now()) return false;
-  const lastValidated = new Date(license.lastValidatedAt).getTime();
-  const msSinceValidation = Date.now() - lastValidated;
-  const revalidationMs = REVALIDATION_DAYS * 24 * 60 * 60 * 1e3;
-  if (msSinceValidation <= revalidationMs) {
-    maybePrintExpiryWarning(license.expiresAt);
-    return true;
-  }
-  const client = new ApiClient(opts.apiBase);
-  try {
-    const result = await client.validate(license.key, license.instanceId);
-    if (result.status === "revoked" || result.status === "expired") return false;
-    const refreshed = {
-      ...license,
-      lastValidatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      expiresAt: result.expiresAt || license.expiresAt
-    };
-    await store.write(refreshed);
-    maybePrintExpiryWarning(refreshed.expiresAt);
-    return true;
-  } catch (err) {
-    if (err instanceof LicenseRevokedError) return false;
-    if (err instanceof NetworkError || err instanceof TypeError) {
-      const graceMs = GRACE_HOURS * 60 * 60 * 1e3;
-      if (msSinceValidation <= revalidationMs + graceMs) {
-        process.stderr.write(
-          `\u26A0 ctxloom is running offline. License will be reverified when network is available.
-
-`
-        );
-        maybePrintExpiryWarning(license.expiresAt);
-        return true;
-      }
-      return false;
-    }
-    return false;
-  }
-}
-async function requireActive(opts = {}) {
-  const active = await isActive(opts);
-  if (!active) throw new LicenseRequiredError();
-}
-async function getLicenseInfo(opts = {}) {
-  const home = opts.home ?? defaultHome();
-  const store = new LicenseStore(home);
-  return store.read();
-}
-async function activateLicense(key, opts = {}) {
-  const home = opts.home ?? defaultHome();
-  const fingerprint = await Fingerprint.compute();
-  const hostname = os3.hostname();
-  const platform = `${os3.platform()}-${os3.arch()}`;
-  const client = new ApiClient(opts.apiBase);
-  const result = await client.activate(key, fingerprint, hostname, platform);
-  const license = {
-    schemaVersion: 1,
-    key,
-    tier: result.tier,
-    status: "active",
-    fingerprint,
-    seats: result.seatsTotal,
-    issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    expiresAt: result.expiresAt,
-    lastValidatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    licenseId: result.licenseId,
-    instanceId: result.instanceId
-  };
-  const store = new LicenseStore(home);
-  await store.write(license);
-  return license;
-}
-async function deactivateLicense(opts = {}) {
-  const home = opts.home ?? defaultHome();
-  const store = new LicenseStore(home);
-  const license = await store.read();
-  if (!license) return;
-  const client = new ApiClient(opts.apiBase);
-  await client.deactivate(license.key, license.instanceId);
-  await store.clear();
-}
-async function startTrial(email, opts = {}) {
-  const home = opts.home ?? defaultHome();
-  const fingerprint = await Fingerprint.compute();
-  const client = new ApiClient(opts.apiBase);
-  const result = await client.startTrial(email, fingerprint);
-  void home;
-  return result;
-}
+import os5 from "os";
 
 // packages/core/src/license/DistinctIdStore.ts
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
 import path30 from "path";
-import os4 from "os";
+import os3 from "os";
 var UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function distinctIdPath(home) {
-  return path30.join(home ?? os4.homedir(), ".ctxloom", "distinct_id");
+  return path30.join(home ?? os3.homedir(), ".ctxloom", "distinct_id");
 }
 function isValidV4(id) {
   return typeof id === "string" && UUID_V4_REGEX.test(id);
@@ -8842,7 +9311,7 @@ function getOrCreateDistinctId(home) {
   }
   const record = {
     id: crypto.randomUUID(),
-    alias_pending: os4.hostname()
+    alias_pending: os3.hostname()
   };
   mkdirSync2(path30.dirname(filePath), { recursive: true });
   writeFileSync2(filePath, JSON.stringify(record), { mode: 384 });
@@ -8873,7 +9342,7 @@ var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
 function getTelemetryLevel() {
   return TELEMETRY_LEVEL;
 }
-var CTXLOOM_VERSION = "1.2.5".length > 0 ? "1.2.5" : "dev";
+var CTXLOOM_VERSION = "1.2.7".length > 0 ? "1.2.7" : "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" : "");
@@ -9004,32 +9473,169 @@ function parseStack(stack) {
   }).filter((f) => f !== null).slice(0, 20);
 }
 
-// packages/core/src/license/TelemetryNotice.ts
+// packages/core/src/license/FunnelMilestones.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
 import path31 from "path";
-import os5 from "os";
+import os4 from "os";
+var INSTALL_MARKER = "installed_at";
+var FIRST_REVIEW_MARKER = "first_review_at";
+function writeMarker(filePath) {
+  mkdirSync3(path31.dirname(filePath), { recursive: true });
+  writeFileSync3(filePath, (/* @__PURE__ */ new Date()).toISOString(), { mode: 384 });
+}
+function shouldEmitInstallCompleted(home) {
+  const root = home ?? os4.homedir();
+  const marker = path31.join(root, ".ctxloom", INSTALL_MARKER);
+  if (existsSync3(marker)) return false;
+  try {
+    writeMarker(marker);
+  } catch {
+  }
+  return true;
+}
+function shouldEmitFirstReviewRun(projectRoot) {
+  const marker = path31.join(projectRoot, ".ctxloom", FIRST_REVIEW_MARKER);
+  if (existsSync3(marker)) return false;
+  try {
+    writeMarker(marker);
+  } catch {
+  }
+  return true;
+}
+
+// packages/core/src/license/index.ts
+var REVALIDATION_DAYS = 7;
+var GRACE_HOURS = 72;
+function defaultHome() {
+  return os5.homedir();
+}
+async function isActive(opts = {}) {
+  const home = opts.home ?? defaultHome();
+  const store = new LicenseStore(home);
+  const license = await store.read();
+  if (!license) return false;
+  if (new Date(license.expiresAt).getTime() <= Date.now()) return false;
+  const lastValidated = new Date(license.lastValidatedAt).getTime();
+  const msSinceValidation = Date.now() - lastValidated;
+  const revalidationMs = REVALIDATION_DAYS * 24 * 60 * 60 * 1e3;
+  if (msSinceValidation <= revalidationMs) {
+    maybePrintExpiryWarning(license.expiresAt);
+    return true;
+  }
+  const client = new ApiClient(opts.apiBase);
+  try {
+    const result = await client.validate(license.key, license.instanceId);
+    if (result.status === "revoked" || result.status === "expired") return false;
+    const refreshed = {
+      ...license,
+      lastValidatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      expiresAt: result.expiresAt || license.expiresAt
+    };
+    await store.write(refreshed);
+    if (result.expiresAt && result.expiresAt !== license.expiresAt) {
+      track("renewal", {
+        tier: license.tier,
+        previousExpiresAt: license.expiresAt,
+        newExpiresAt: result.expiresAt
+      });
+    }
+    maybePrintExpiryWarning(refreshed.expiresAt);
+    return true;
+  } catch (err) {
+    if (err instanceof LicenseRevokedError) return false;
+    if (err instanceof NetworkError || err instanceof TypeError) {
+      const graceMs = GRACE_HOURS * 60 * 60 * 1e3;
+      if (msSinceValidation <= revalidationMs + graceMs) {
+        process.stderr.write(
+          `\u26A0 ctxloom is running offline. License will be reverified when network is available.
+
+`
+        );
+        maybePrintExpiryWarning(license.expiresAt);
+        return true;
+      }
+      return false;
+    }
+    return false;
+  }
+}
+async function requireActive(opts = {}) {
+  const active = await isActive(opts);
+  if (!active) throw new LicenseRequiredError();
+}
+async function getLicenseInfo(opts = {}) {
+  const home = opts.home ?? defaultHome();
+  const store = new LicenseStore(home);
+  return store.read();
+}
+async function activateLicense(key, opts = {}) {
+  const home = opts.home ?? defaultHome();
+  const fingerprint = await Fingerprint.compute();
+  const hostname = os5.hostname();
+  const platform = `${os5.platform()}-${os5.arch()}`;
+  const client = new ApiClient(opts.apiBase);
+  const result = await client.activate(key, fingerprint, hostname, platform);
+  const license = {
+    schemaVersion: 1,
+    key,
+    tier: result.tier,
+    status: "active",
+    fingerprint,
+    seats: result.seatsTotal,
+    issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    expiresAt: result.expiresAt,
+    lastValidatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    licenseId: result.licenseId,
+    instanceId: result.instanceId
+  };
+  const store = new LicenseStore(home);
+  await store.write(license);
+  return license;
+}
+async function deactivateLicense(opts = {}) {
+  const home = opts.home ?? defaultHome();
+  const store = new LicenseStore(home);
+  const license = await store.read();
+  if (!license) return;
+  const client = new ApiClient(opts.apiBase);
+  await client.deactivate(license.key, license.instanceId);
+  await store.clear();
+}
+async function startTrial(email, opts = {}) {
+  const home = opts.home ?? defaultHome();
+  const fingerprint = await Fingerprint.compute();
+  const client = new ApiClient(opts.apiBase);
+  const result = await client.startTrial(email, fingerprint);
+  void home;
+  return result;
+}
+
+// packages/core/src/license/TelemetryNotice.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import path32 from "path";
+import os6 from "os";
 function noticePath(home) {
-  return path31.join(home ?? os5.homedir(), ".ctxloom", "telemetry_notice_shown");
+  return path32.join(home ?? os6.homedir(), ".ctxloom", "telemetry_notice_shown");
 }
 function shouldShowTelemetryNotice(home) {
   const filePath = noticePath(home);
-  if (existsSync3(filePath)) return false;
+  if (existsSync4(filePath)) return false;
   try {
-    mkdirSync3(path31.dirname(filePath), { recursive: true });
-    writeFileSync3(filePath, (/* @__PURE__ */ new Date()).toISOString(), { mode: 384 });
+    mkdirSync4(path32.dirname(filePath), { recursive: true });
+    writeFileSync4(filePath, (/* @__PURE__ */ new Date()).toISOString(), { mode: 384 });
   } catch {
   }
   return true;
 }
 
 // packages/core/src/server/ProjectState.ts
-import path33 from "path";
+import path34 from "path";
 
 // packages/core/src/server/projectId.ts
 import crypto5 from "crypto";
-import path32 from "path";
+import path33 from "path";
 function hashProjectRoot(absPath) {
-  const canonical = path32.resolve(absPath);
+  const canonical = path33.resolve(absPath);
   return crypto5.createHash("sha256").update(canonical).digest("hex").slice(0, 16);
 }
 
@@ -9037,7 +9643,7 @@ function hashProjectRoot(absPath) {
 function createProjectState(projectRoot, opts = {}) {
   return {
     projectRoot,
-    dbPath: path33.join(projectRoot, ".ctxloom", "vectors.lancedb"),
+    dbPath: path34.join(projectRoot, ".ctxloom", "vectors.lancedb"),
     pinned: opts.pinned ?? false,
     lastTouchedAt: Date.now(),
     vectorsInitialized: false,
@@ -9190,7 +9796,7 @@ var ProjectStateManager = class {
 
 // packages/core/src/server/resolveProjectRoot.ts
 import fs27 from "fs";
-import path34 from "path";
+import path35 from "path";
 var PATH_SEPARATOR_PATTERN = /[/\\~]|^[A-Za-z]:/;
 function looksLikePath(value) {
   return PATH_SEPARATOR_PATTERN.test(value);
@@ -9215,9 +9821,9 @@ function resolvePathSafely(p, cwd) {
   let expanded = p;
   if (p === "~" || p.startsWith("~/")) {
     const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-    expanded = p === "~" ? home : path34.join(home, p.slice(2));
+    expanded = p === "~" ? home : path35.join(home, p.slice(2));
   }
-  return path34.isAbsolute(expanded) ? path34.resolve(expanded) : path34.resolve(cwd, expanded);
+  return path35.isAbsolute(expanded) ? path35.resolve(expanded) : path35.resolve(cwd, expanded);
 }
 function realpathOrSame(p) {
   try {
@@ -9289,7 +9895,7 @@ function validateDefaultRoot(candidate) {
   } catch {
     return false;
   }
-  return PROJECT_MARKERS.some((m) => fs27.existsSync(path34.join(candidate, m)));
+  return PROJECT_MARKERS.some((m) => fs27.existsSync(path35.join(candidate, m)));
 }
 
 // packages/core/src/server/structuredErrors.ts
@@ -9436,17 +10042,19 @@ export {
   ApiClient,
   Fingerprint,
   maybePrintExpiryWarning,
+  getOrCreateDistinctId,
+  markAliasSent,
+  getTelemetryLevel,
+  track,
+  captureError,
+  shouldEmitInstallCompleted,
+  shouldEmitFirstReviewRun,
   isActive,
   requireActive,
   getLicenseInfo,
   activateLicense,
   deactivateLicense,
   startTrial,
-  getOrCreateDistinctId,
-  markAliasSent,
-  getTelemetryLevel,
-  track,
-  captureError,
   shouldShowTelemetryNotice,
   hashProjectRoot,
   createProjectState,
@@ -9464,4 +10072,4 @@ export {
   FirstTouchTracker,
   EmittedOnceTracker
 };
-//# sourceMappingURL=chunk-6S3ZF2YS.js.map
+//# sourceMappingURL=chunk-RY3JAC2Q.js.map