@swarmvaultai/engine 3.16.1 → 3.18.0

package/dist/hooks/claude.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+// src/hooks/claude.ts
+import { spawn } from "child_process";
+
 // src/hooks/marker-state.ts
 import crypto from "crypto";
 import fs from "fs/promises";
@@ -13,6 +16,23 @@ function markerState(cwd, agentKey) {
     markerPath: path.join(dir, "report-read")
   };
 }
+function flagPath(cwd, agentKey, name) {
+  const safeName = name.replaceAll(/[^a-z0-9-]/gi, "-");
+  return path.join(markerState(cwd, agentKey).dir, safeName);
+}
+async function markFlag(cwd, agentKey, name) {
+  const target = flagPath(cwd, agentKey, name);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, "seen\n", "utf8");
+}
+async function hasFlag(cwd, agentKey, name) {
+  try {
+    await fs.access(flagPath(cwd, agentKey, name));
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isReportPath(value, cwd) {
   if (typeof value !== "string" || value.length === 0) {
     return false;
@@ -57,6 +77,10 @@ function resolveToolName(input) {
   const shaped = input ?? {};
   return String(shaped.toolName ?? shaped.tool_name ?? shaped.tool?.name ?? shaped.name ?? "");
 }
+function resolveToolInput(input) {
+  const shaped = input ?? {};
+  return shaped.toolInput ?? shaped.tool_input ?? {};
+}
 async function hasReport(cwd) {
   try {
     await fs.access(reportPath(cwd));
@@ -116,13 +140,18 @@ function collectCommandCandidates(node, acc = []) {
   return acc;
 }
 function commandLooksLikeBroadSearch(command) {
-  const tokens = command.replace(/[;&|()]/g, " ").split(/\s+/).map((token) => path.basename(token.replace(/^['"]|['"]$/g, ""))).filter(Boolean);
-  for (let index = 0; index < tokens.length; index += 1) {
-    const token = tokens[index];
-    if (["rg", "grep", "find", "fd", "ag", "ack"].includes(token)) {
+  const statements = command.split(/;|&&|\|\|/);
+  for (const statement of statements) {
+    const firstStage = statement.split("|")[0] ?? "";
+    const tokens = firstStage.replace(/[()]/g, " ").split(/\s+/).map((token) => path.basename(token.replace(/^['"]|['"]$/g, ""))).filter(Boolean);
+    const leading = tokens.find((token) => !token.includes("=") && !token.startsWith("-"));
+    if (!leading) {
+      continue;
+    }
+    if (["rg", "grep", "find", "fd", "ag", "ack"].includes(leading)) {
       return true;
     }
-    if (token === "git" && tokens[index + 1] === "grep") {
+    if (leading === "git" && tokens[tokens.indexOf(leading) + 1] === "grep") {
       return true;
     }
   }
@@ -135,6 +164,100 @@ function isBroadSearchInput(input) {
   }
   return collectCommandCandidates(input).some(commandLooksLikeBroadSearch);
 }
+var VAULT_ARTIFACT_SEGMENTS = ["wiki", "raw", "state", "agent", "inbox"];
+function isVaultArtifactSearch(input, cwd) {
+  const artifactRoot = artifactRootDir(cwd);
+  const candidates = [...collectCandidatePaths(input), ...collectCommandCandidates(input)];
+  return candidates.some((candidate) => {
+    if (typeof candidate !== "string" || candidate.length === 0) {
+      return false;
+    }
+    const normalized = candidate.replaceAll("\\", "/");
+    if (VAULT_ARTIFACT_SEGMENTS.some(
+      (segment) => normalized.includes(`${segment}/`) && normalized.match(new RegExp(`(^|[\\s'"=/])${segment}/`))
+    )) {
+      return true;
+    }
+    const resolved = path.resolve(cwd, candidate);
+    return VAULT_ARTIFACT_SEGMENTS.some(
+      (segment) => resolved.startsWith(path.join(artifactRoot, segment) + path.sep) || resolved === path.join(artifactRoot, segment)
+    );
+  });
+}
+async function isNarrowSearch(input) {
+  const toolInput = resolveToolInput(input);
+  const candidate = toolInput?.path;
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    return false;
+  }
+  try {
+    const stats = await fs.stat(candidate);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+async function resolveGraphFirstMode(cwd) {
+  const fromEnv = process.env.SWARMVAULT_GRAPH_FIRST?.trim().toLowerCase();
+  if (fromEnv === "deny" || fromEnv === "context" || fromEnv === "off") {
+    return fromEnv;
+  }
+  try {
+    const raw = await fs.readFile(path.join(cwd, "swarmvault.config.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    const fromConfig = typeof parsed?.hooks?.graphFirst === "string" ? parsed.hooks.graphFirst.toLowerCase() : "";
+    if (fromConfig === "deny" || fromConfig === "context" || fromConfig === "off") {
+      return fromConfig;
+    }
+  } catch {
+  }
+  return "context";
+}
+async function readWatchStaleness(cwd) {
+  const watchDir = path.join(artifactRootDir(cwd), "state", "watch");
+  let lastRunAt;
+  let lastRunSuccess;
+  let pendingCount = 0;
+  let found = false;
+  try {
+    const raw = await fs.readFile(path.join(watchDir, "status.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    lastRunAt = typeof parsed?.lastRun?.finishedAt === "string" ? parsed.lastRun.finishedAt : void 0;
+    lastRunSuccess = typeof parsed?.lastRun?.success === "boolean" ? parsed.lastRun.success : void 0;
+    found = true;
+  } catch {
+  }
+  try {
+    const raw = await fs.readFile(path.join(watchDir, "pending-semantic-refresh.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      pendingCount = parsed.length;
+      found = true;
+    }
+  } catch {
+  }
+  if (!found) {
+    return null;
+  }
+  return { lastRunAt, lastRunSuccess, pendingSemanticRefreshCount: pendingCount };
+}
+function collectEditedFilePaths(input, cwd) {
+  const toolInput = resolveToolInput(input);
+  const candidates = [];
+  for (const key of ["file_path", "filePath", "path", "notebook_path", "notebookPath"]) {
+    const value = toolInput?.[key];
+    if (typeof value === "string" && value.length > 0) {
+      candidates.push(value);
+    }
+  }
+  const artifactRoot = artifactRootDir(cwd);
+  const resolved = candidates.map((candidate) => path.resolve(cwd, candidate)).filter(
+    (absolutePath) => !VAULT_ARTIFACT_SEGMENTS.some(
+      (segment) => absolutePath === path.join(artifactRoot, segment) || absolutePath.startsWith(path.join(artifactRoot, segment) + path.sep)
+    )
+  );
+  return [...new Set(resolved)];
+}
 async function readHookInput() {
   let body = "";
   for await (const chunk of process.stdin) {
@@ -149,7 +272,52 @@ async function readHookInput() {
     return {};
   }
 }
-var REPORT_NOTE = "SwarmVault graph report exists at wiki/graph/report.md, or at $SWARMVAULT_OUT/wiki/graph/report.md when SWARMVAULT_OUT is set. Read it before broad grep/glob searching.";
+var GRAPH_FIRST_COMMANDS = [
+  '- `swarmvault graph query "<seed>"` \u2014 top matches with page paths plus an inline excerpt of the best page; usually answers where-is/what-calls in one command',
+  '- `swarmvault graph explain "<node>"` \u2014 compact node summary with neighbors and its wiki page',
+  "- `swarmvault graph blast <target>` \u2014 reverse-import impact analysis for change-impact questions",
+  "- `wiki/graph/report.md` \u2014 orientation report (architecture, communities, key nodes)",
+  "Do not add `--json` to these \u2014 the plain output is far smaller and already structured.",
+  "Trust the graph/wiki answer for orientation questions; verify in source only when you are about to edit or the evidence conflicts. Answer directly in chat \u2014 do not write answer files unless asked for a durable artifact."
+];
+function buildGraphFirstNote(staleness) {
+  const lines = [
+    "This repo has a SwarmVault code graph. To save tokens, answer code-understanding questions (where is X, what calls Y, how is Z structured, impact of changing W) from the graph instead of reading or grepping source files:",
+    ...GRAPH_FIRST_COMMANDS,
+    "Read source files directly only when you are about to edit them, or when the graph lacks the detail you need.",
+    "After your edits the SwarmVault hook refreshes the graph automatically."
+  ];
+  if (staleness?.pendingSemanticRefreshCount) {
+    lines.push(
+      `Note: ${staleness.pendingSemanticRefreshCount} non-code change(s) await semantic refresh \u2014 run \`swarmvault compile\` when convenient.`
+    );
+  }
+  if (staleness?.lastRunSuccess === false) {
+    lines.push(
+      "Note: the last graph refresh failed \u2014 run `swarmvault graph status` then `swarmvault graph update` before relying on the graph."
+    );
+  }
+  return lines.join("\n");
+}
+function extractSearchTerm(input) {
+  const toolInput = resolveToolInput(input);
+  for (const key of ["pattern", "query", "regex"]) {
+    const value = toolInput?.[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return "<your term>";
+}
+function buildDenyReason(toolName, input) {
+  const term = extractSearchTerm(input).slice(0, 120);
+  return [
+    `SwarmVault graph-first: this repo has a compiled code graph that answers structure questions in far fewer tokens than ${toolName || "broad search"}.`,
+    `Run: swarmvault graph query "${term}" \u2014 it prints the top matches with page paths plus an inline excerpt of the best page, which usually answers the question without reading source. Add --context calls for caller/impact questions. Do not add --json (much larger output).`,
+    "Trust that answer for orientation questions instead of re-verifying in source files.",
+    "If the graph does not answer, repeat this exact search \u2014 it will be allowed for the rest of the session."
+  ].join(" ");
+}
 
 // src/hooks/claude.ts
 var AGENT_KEY = "claude";
@@ -157,38 +325,92 @@ function emit(value) {
   process.stdout.write(`${JSON.stringify(value)}
 `);
 }
-async function main() {
-  const mode = process.argv[2] ?? "";
-  const input = await readHookInput();
-  const cwd = resolveInputCwd(input);
-  if (!await hasReport(cwd)) {
+function denyFlagName(toolName) {
+  return `deny-search-${(toolName || "unknown").toLowerCase()}`;
+}
+async function handleSessionStart(cwd) {
+  await resetSession(cwd, AGENT_KEY);
+  const staleness = await readWatchStaleness(cwd);
+  emit({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: buildGraphFirstNote(staleness)
+    }
+  });
+}
+async function handlePostEdit(cwd, input) {
+  const editedPaths = collectEditedFilePaths(input, cwd);
+  if (editedPaths.length > 0) {
+    try {
+      const child = spawn("swarmvault", ["graph", "update", ...editedPaths.flatMap((p) => ["--file", p]), "--json"], {
+        cwd,
+        detached: true,
+        stdio: "ignore"
+      });
+      child.unref();
+    } catch {
+    }
+  }
+  emit({});
+}
+async function handlePreToolUse(cwd, input) {
+  if (collectCandidatePaths(input).some((value) => isReportPath(value, cwd))) {
+    await markReportRead(cwd, AGENT_KEY);
     emit({});
-    process.exit(0);
+    return;
   }
-  if (mode === "session-start") {
-    await resetSession(cwd, AGENT_KEY);
+  const mode = await resolveGraphFirstMode(cwd);
+  if (mode === "off" || !isBroadSearchInput(input)) {
+    emit({});
+    return;
+  }
+  if (isVaultArtifactSearch(input, cwd) || await isNarrowSearch(input)) {
+    emit({});
+    return;
+  }
+  const toolName = resolveToolName(input);
+  const flag = denyFlagName(toolName);
+  if (mode === "deny" && !await hasFlag(cwd, AGENT_KEY, flag)) {
+    await markFlag(cwd, AGENT_KEY, flag);
     emit({
       hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext: REPORT_NOTE
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: buildDenyReason(toolName, input)
       }
     });
-    process.exit(0);
+    return;
   }
-  if (collectCandidatePaths(input).some((value) => isReportPath(value, cwd))) {
+  if (!await hasSeenReport(cwd, AGENT_KEY)) {
     await markReportRead(cwd, AGENT_KEY);
-    emit({});
-    process.exit(0);
-  }
-  if (isBroadSearchInput(input) && !await hasSeenReport(cwd, AGENT_KEY)) {
     emit({
       hookSpecificOutput: {
         hookEventName: "PreToolUse",
-        additionalContext: REPORT_NOTE
+        permissionDecision: "allow",
+        additionalContext: buildDenyReason(toolName, input)
       }
     });
-    process.exit(0);
+    return;
   }
   emit({});
 }
+async function main() {
+  const mode = process.argv[2] ?? "";
+  const input = await readHookInput();
+  const cwd = resolveInputCwd(input);
+  if (!await hasReport(cwd) || await resolveGraphFirstMode(cwd) === "off") {
+    emit({});
+    process.exit(0);
+  }
+  if (mode === "session-start") {
+    await handleSessionStart(cwd);
+    process.exit(0);
+  }
+  if (mode === "post-edit") {
+    await handlePostEdit(cwd, input);
+    process.exit(0);
+  }
+  await handlePreToolUse(cwd, input);
+  process.exit(0);
+}
 await main();

package/dist/hooks/codex.js

@@ -57,6 +57,10 @@ function resolveToolName(input) {
   const shaped = input ?? {};
   return String(shaped.toolName ?? shaped.tool_name ?? shaped.tool?.name ?? shaped.name ?? "");
 }
+function resolveToolInput(input) {
+  const shaped = input ?? {};
+  return shaped.toolInput ?? shaped.tool_input ?? {};
+}
 async function hasReport(cwd) {
   try {
     await fs.access(reportPath(cwd));
@@ -116,13 +120,18 @@ function collectCommandCandidates(node, acc = []) {
   return acc;
 }
 function commandLooksLikeBroadSearch(command) {
-  const tokens = command.replace(/[;&|()]/g, " ").split(/\s+/).map((token) => path.basename(token.replace(/^['"]|['"]$/g, ""))).filter(Boolean);
-  for (let index = 0; index < tokens.length; index += 1) {
-    const token = tokens[index];
-    if (["rg", "grep", "find", "fd", "ag", "ack"].includes(token)) {
+  const statements = command.split(/;|&&|\|\|/);
+  for (const statement of statements) {
+    const firstStage = statement.split("|")[0] ?? "";
+    const tokens = firstStage.replace(/[()]/g, " ").split(/\s+/).map((token) => path.basename(token.replace(/^['"]|['"]$/g, ""))).filter(Boolean);
+    const leading = tokens.find((token) => !token.includes("=") && !token.startsWith("-"));
+    if (!leading) {
+      continue;
+    }
+    if (["rg", "grep", "find", "fd", "ag", "ack"].includes(leading)) {
       return true;
     }
-    if (token === "git" && tokens[index + 1] === "grep") {
+    if (leading === "git" && tokens[tokens.indexOf(leading) + 1] === "grep") {
       return true;
     }
   }
@@ -135,6 +144,83 @@ function isBroadSearchInput(input) {
   }
   return collectCommandCandidates(input).some(commandLooksLikeBroadSearch);
 }
+var VAULT_ARTIFACT_SEGMENTS = ["wiki", "raw", "state", "agent", "inbox"];
+function isVaultArtifactSearch(input, cwd) {
+  const artifactRoot = artifactRootDir(cwd);
+  const candidates = [...collectCandidatePaths(input), ...collectCommandCandidates(input)];
+  return candidates.some((candidate) => {
+    if (typeof candidate !== "string" || candidate.length === 0) {
+      return false;
+    }
+    const normalized = candidate.replaceAll("\\", "/");
+    if (VAULT_ARTIFACT_SEGMENTS.some(
+      (segment) => normalized.includes(`${segment}/`) && normalized.match(new RegExp(`(^|[\\s'"=/])${segment}/`))
+    )) {
+      return true;
+    }
+    const resolved = path.resolve(cwd, candidate);
+    return VAULT_ARTIFACT_SEGMENTS.some(
+      (segment) => resolved.startsWith(path.join(artifactRoot, segment) + path.sep) || resolved === path.join(artifactRoot, segment)
+    );
+  });
+}
+async function isNarrowSearch(input) {
+  const toolInput = resolveToolInput(input);
+  const candidate = toolInput?.path;
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    return false;
+  }
+  try {
+    const stats = await fs.stat(candidate);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+async function resolveGraphFirstMode(cwd) {
+  const fromEnv = process.env.SWARMVAULT_GRAPH_FIRST?.trim().toLowerCase();
+  if (fromEnv === "deny" || fromEnv === "context" || fromEnv === "off") {
+    return fromEnv;
+  }
+  try {
+    const raw = await fs.readFile(path.join(cwd, "swarmvault.config.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    const fromConfig = typeof parsed?.hooks?.graphFirst === "string" ? parsed.hooks.graphFirst.toLowerCase() : "";
+    if (fromConfig === "deny" || fromConfig === "context" || fromConfig === "off") {
+      return fromConfig;
+    }
+  } catch {
+  }
+  return "context";
+}
+async function readWatchStaleness(cwd) {
+  const watchDir = path.join(artifactRootDir(cwd), "state", "watch");
+  let lastRunAt;
+  let lastRunSuccess;
+  let pendingCount = 0;
+  let found = false;
+  try {
+    const raw = await fs.readFile(path.join(watchDir, "status.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    lastRunAt = typeof parsed?.lastRun?.finishedAt === "string" ? parsed.lastRun.finishedAt : void 0;
+    lastRunSuccess = typeof parsed?.lastRun?.success === "boolean" ? parsed.lastRun.success : void 0;
+    found = true;
+  } catch {
+  }
+  try {
+    const raw = await fs.readFile(path.join(watchDir, "pending-semantic-refresh.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      pendingCount = parsed.length;
+      found = true;
+    }
+  } catch {
+  }
+  if (!found) {
+    return null;
+  }
+  return { lastRunAt, lastRunSuccess, pendingSemanticRefreshCount: pendingCount };
+}
 async function readHookInput() {
   let body = "";
   for await (const chunk of process.stdin) {
@@ -149,7 +235,52 @@ async function readHookInput() {
     return {};
   }
 }
-var REPORT_NOTE = "SwarmVault graph report exists at wiki/graph/report.md, or at $SWARMVAULT_OUT/wiki/graph/report.md when SWARMVAULT_OUT is set. Read it before broad grep/glob searching.";
+var GRAPH_FIRST_COMMANDS = [
+  '- `swarmvault graph query "<seed>"` \u2014 top matches with page paths plus an inline excerpt of the best page; usually answers where-is/what-calls in one command',
+  '- `swarmvault graph explain "<node>"` \u2014 compact node summary with neighbors and its wiki page',
+  "- `swarmvault graph blast <target>` \u2014 reverse-import impact analysis for change-impact questions",
+  "- `wiki/graph/report.md` \u2014 orientation report (architecture, communities, key nodes)",
+  "Do not add `--json` to these \u2014 the plain output is far smaller and already structured.",
+  "Trust the graph/wiki answer for orientation questions; verify in source only when you are about to edit or the evidence conflicts. Answer directly in chat \u2014 do not write answer files unless asked for a durable artifact."
+];
+function buildGraphFirstNote(staleness) {
+  const lines = [
+    "This repo has a SwarmVault code graph. To save tokens, answer code-understanding questions (where is X, what calls Y, how is Z structured, impact of changing W) from the graph instead of reading or grepping source files:",
+    ...GRAPH_FIRST_COMMANDS,
+    "Read source files directly only when you are about to edit them, or when the graph lacks the detail you need.",
+    "After your edits the SwarmVault hook refreshes the graph automatically."
+  ];
+  if (staleness?.pendingSemanticRefreshCount) {
+    lines.push(
+      `Note: ${staleness.pendingSemanticRefreshCount} non-code change(s) await semantic refresh \u2014 run \`swarmvault compile\` when convenient.`
+    );
+  }
+  if (staleness?.lastRunSuccess === false) {
+    lines.push(
+      "Note: the last graph refresh failed \u2014 run `swarmvault graph status` then `swarmvault graph update` before relying on the graph."
+    );
+  }
+  return lines.join("\n");
+}
+function extractSearchTerm(input) {
+  const toolInput = resolveToolInput(input);
+  for (const key of ["pattern", "query", "regex"]) {
+    const value = toolInput?.[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return "<your term>";
+}
+function buildDenyReason(toolName, input) {
+  const term = extractSearchTerm(input).slice(0, 120);
+  return [
+    `SwarmVault graph-first: this repo has a compiled code graph that answers structure questions in far fewer tokens than ${toolName || "broad search"}.`,
+    `Run: swarmvault graph query "${term}" \u2014 it prints the top matches with page paths plus an inline excerpt of the best page, which usually answers the question without reading source. Add --context calls for caller/impact questions. Do not add --json (much larger output).`,
+    "Trust that answer for orientation questions instead of re-verifying in source files.",
+    "If the graph does not answer, repeat this exact search \u2014 it will be allowed for the rest of the session."
+  ].join(" ");
+}
 
 // src/hooks/codex.ts
 var AGENT_KEY = "codex";
@@ -157,10 +288,10 @@ function emit(value) {
   process.stdout.write(`${JSON.stringify(value)}
 `);
 }
-function note() {
+function note(message) {
   return {
     priority: "IMPORTANT",
-    message: REPORT_NOTE
+    message
   };
 }
 async function main() {
@@ -173,7 +304,7 @@ async function main() {
   }
   if (mode === "session-start") {
     await resetSession(cwd, AGENT_KEY);
-    emit(note());
+    emit(note(buildGraphFirstNote(await readWatchStaleness(cwd))));
     process.exit(0);
   }
   if (collectCandidatePaths(input).some((value) => isReportPath(value, cwd))) {
@@ -181,8 +312,10 @@ async function main() {
     emit({});
     process.exit(0);
   }
-  if (isBroadSearchInput(input) && !await hasSeenReport(cwd, AGENT_KEY)) {
-    emit(note());
+  const graphFirstMode = await resolveGraphFirstMode(cwd);
+  if (graphFirstMode !== "off" && isBroadSearchInput(input) && !isVaultArtifactSearch(input, cwd) && !await isNarrowSearch(input) && !await hasSeenReport(cwd, AGENT_KEY)) {
+    await markReportRead(cwd, AGENT_KEY);
+    emit(note(buildDenyReason(resolveToolName(input), input)));
     process.exit(0);
   }
   emit({});

package/dist/hooks/copilot.js

@@ -57,6 +57,10 @@ function resolveToolName(input) {
   const shaped = input ?? {};
   return String(shaped.toolName ?? shaped.tool_name ?? shaped.tool?.name ?? shaped.name ?? "");
 }
+function resolveToolInput(input) {
+  const shaped = input ?? {};
+  return shaped.toolInput ?? shaped.tool_input ?? {};
+}
 async function hasReport(cwd) {
   try {
     await fs.access(reportPath(cwd));
@@ -96,6 +100,74 @@ async function resetSession(cwd, agentKey) {
 function isBroadSearchTool(toolName) {
   return /grep|glob|search|find/i.test(toolName);
 }
+function collectCommandCandidates(node, acc = []) {
+  if (!node || typeof node !== "object") {
+    return acc;
+  }
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectCommandCandidates(item, acc);
+    }
+    return acc;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (["command", "cmd", "script", "bash", "shell"].includes(key) && typeof value === "string") {
+      acc.push(value);
+      continue;
+    }
+    collectCommandCandidates(value, acc);
+  }
+  return acc;
+}
+var VAULT_ARTIFACT_SEGMENTS = ["wiki", "raw", "state", "agent", "inbox"];
+function isVaultArtifactSearch(input, cwd) {
+  const artifactRoot = artifactRootDir(cwd);
+  const candidates = [...collectCandidatePaths(input), ...collectCommandCandidates(input)];
+  return candidates.some((candidate) => {
+    if (typeof candidate !== "string" || candidate.length === 0) {
+      return false;
+    }
+    const normalized = candidate.replaceAll("\\", "/");
+    if (VAULT_ARTIFACT_SEGMENTS.some(
+      (segment) => normalized.includes(`${segment}/`) && normalized.match(new RegExp(`(^|[\\s'"=/])${segment}/`))
+    )) {
+      return true;
+    }
+    const resolved = path.resolve(cwd, candidate);
+    return VAULT_ARTIFACT_SEGMENTS.some(
+      (segment) => resolved.startsWith(path.join(artifactRoot, segment) + path.sep) || resolved === path.join(artifactRoot, segment)
+    );
+  });
+}
+async function isNarrowSearch(input) {
+  const toolInput = resolveToolInput(input);
+  const candidate = toolInput?.path;
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    return false;
+  }
+  try {
+    const stats = await fs.stat(candidate);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+async function resolveGraphFirstMode(cwd) {
+  const fromEnv = process.env.SWARMVAULT_GRAPH_FIRST?.trim().toLowerCase();
+  if (fromEnv === "deny" || fromEnv === "context" || fromEnv === "off") {
+    return fromEnv;
+  }
+  try {
+    const raw = await fs.readFile(path.join(cwd, "swarmvault.config.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    const fromConfig = typeof parsed?.hooks?.graphFirst === "string" ? parsed.hooks.graphFirst.toLowerCase() : "";
+    if (fromConfig === "deny" || fromConfig === "context" || fromConfig === "off") {
+      return fromConfig;
+    }
+  } catch {
+  }
+  return "context";
+}
 async function readHookInput() {
   let body = "";
   for await (const chunk of process.stdin) {
@@ -110,7 +182,25 @@ async function readHookInput() {
     return {};
   }
 }
-var REPORT_NOTE = "SwarmVault graph report exists at wiki/graph/report.md, or at $SWARMVAULT_OUT/wiki/graph/report.md when SWARMVAULT_OUT is set. Read it before broad grep/glob searching.";
+function extractSearchTerm(input) {
+  const toolInput = resolveToolInput(input);
+  for (const key of ["pattern", "query", "regex"]) {
+    const value = toolInput?.[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return "<your term>";
+}
+function buildDenyReason(toolName, input) {
+  const term = extractSearchTerm(input).slice(0, 120);
+  return [
+    `SwarmVault graph-first: this repo has a compiled code graph that answers structure questions in far fewer tokens than ${toolName || "broad search"}.`,
+    `Run: swarmvault graph query "${term}" \u2014 it prints the top matches with page paths plus an inline excerpt of the best page, which usually answers the question without reading source. Add --context calls for caller/impact questions. Do not add --json (much larger output).`,
+    "Trust that answer for orientation questions instead of re-verifying in source files.",
+    "If the graph does not answer, repeat this exact search \u2014 it will be allowed for the rest of the session."
+  ].join(" ");
+}
 
 // src/hooks/copilot.ts
 var AGENT_KEY = "copilot";
@@ -139,10 +229,12 @@ async function main() {
     emit({});
     process.exit(0);
   }
-  if (isBroadSearchTool(toolName) && !await hasSeenReport(cwd, AGENT_KEY)) {
+  const graphFirstMode = await resolveGraphFirstMode(cwd);
+  if (graphFirstMode === "deny" && isBroadSearchTool(toolName) && !isVaultArtifactSearch(input, cwd) && !await isNarrowSearch(input) && !await hasSeenReport(cwd, AGENT_KEY)) {
+    await markReportRead(cwd, AGENT_KEY);
     emit({
       permissionDecision: "deny",
-      permissionDecisionReason: REPORT_NOTE
+      permissionDecisionReason: buildDenyReason(toolName, input)
     });
     process.exit(0);
   }