pi-graphnav 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sorin Albu-Irimies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# pi-graphnav
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/pi-graphnav.svg)](https://www.npmjs.com/package/pi-graphnav)
+[![CI](https://github.com/sorinirimies/pi-graphnav/actions/workflows/ci.yml/badge.svg)](https://github.com/sorinirimies/pi-graphnav/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Audit](https://github.com/sorinirimies/pi-graphnav/actions/workflows/security.yml/badge.svg)](https://github.com/sorinirimies/pi-graphnav/actions/workflows/security.yml)
+[![Fuzz](https://github.com/sorinirimies/pi-graphnav/actions/workflows/fuzz.yml/badge.svg)](https://github.com/sorinirimies/pi-graphnav/actions/workflows/fuzz.yml)
+
+CodeGraph-first code navigation for pi: the agent understands code through
+[CodeGraph](https://github.com/colbymchenry/codegraph)'s symbol graph instead of grepping and
+reading file after file, without being told to.
+
+A [pi](https://github.com/earendil-works/pi-coding-agent) extension.
+
+## What it does
+
+* **Keeps the index current.** At session start, in the background: `codegraph init` for a git repo
+  without an index, a full `codegraph index` when the index is stale or was built by another
+  CodeGraph version, `codegraph sync` for pending changes. While pi runs, the server's file
+  watcher follows your edits.
+* **The `codegraph_*` tools** (`explore`, `search`, `node`, `callers`, `callees`, `impact`,
+  `files`, `status`) on one long-lived `codegraph serve --mcp` per project: no process start per
+  call, and the watcher stays alive.
+* **Steers symbol searches to CodeGraph.** `rg parseConfig`, `grep -rn UserService src`,
+  `git grep`, `ag`, `ack` and pi's `grep` tool with a symbol-like pattern are blocked once with
+  the CodeGraph call that answers it (`enforce`), or run with that hint appended (`nudge`).
+  Running the same command again is allowed: CodeGraph cannot answer everything. Searches for
+  phrases, string literals or in docs and config (`*.md`, `--type yaml`, …) are never touched,
+  nor symbols already looked up with CodeGraph.
+* **Hints after blind reading.** Reading several source files before any CodeGraph call adds
+  one hint to use `codegraph_explore`.
+* **Prompt guidance** that stays the same every turn, so the prompt cache survives.
+
+Needs the CodeGraph CLI: `npm i -g @colbymchenry/codegraph`. The project is the nearest
+directory with `.codegraph/`, else the git work tree; never your home directory.
+
+## Install
+
+```bash
+pi install npm:pi-graphnav
+```
+
+## Use
+
+| Command | |
+|---|---|
+| `/codegraph` or `/codegraph status` | project, index state, mode, blocked/nudged counts |
+| `/codegraph [on\|off]` | switch it all (remembered across sessions) |
+| `/codegraph mode <mode>` | symbol searches: `enforce` (default), `nudge` or `off` |
+| `/codegraph sync` | sync the index with changed files |
+| `/codegraph reindex` | rebuild the index from scratch |
+| `/codegraph init` | create the index (for a directory that is not a git repo) |
+
+Settings live in `<pi agent dir>/codegraph.json` (`PI_CODING_AGENT_DIR`, else `~/.pi/agent`):
+
+| Key | Default | |
+|---|---|---|
+| `enabled` | `true` | master switch |
+| `showStatus` | `true` | status line entry |
+| `mode` | `"enforce"` | `enforce`, `nudge` or `off` |
+| `autoInit` | `true` | init a git repo that has no index |
+| `autoSync` | `true` | sync or rebuild a stale index at session start |
+| `watch` | `true` | keep the server's file watcher running |
+| `readHintAfter` | `3` | source files read before the CodeGraph hint (`0`: never) |
+| `timeoutMs` | `30000` | per-call timeout of the CodeGraph server |
+
+Replaces `@vndv/pi-codegraph` (same tool names): uninstall that one first.
+
+## Development
+
+```bash
+bun install
+just check   # typecheck + tests (95% coverage gate) + pack check + nu script tests
+just --list  # everything else: fuzz, audit, release, remotes
+```
+
+Layout:
+
+| Path | What |
+|---|---|
+| `extensions/graphnav.ts` | wiring: hooks, tools, the command, the status line |
+| `extensions/core/gate.ts` | spotting symbol searches in shell commands; the gate decision |
+| `extensions/core/project.ts` | project root, `codegraph status -j`, what keeps the index current |
+| `extensions/core/mcp.ts` | the long-lived `codegraph serve --mcp` client |
+| `extensions/core/tools.ts` | tool definitions and prompt guidelines |
+| `extensions/core/config.ts`, `extensions/command/parse.ts` | settings, `/codegraph` parsing |
+| `tests/` | `bun test`: one file per module, `extension` (hooks), `fuzz` (randomised properties) |
+| `scripts/` | Nushell only, each with a test in `scripts/tests/` |
+| `.github/`, `.gitea/` | CI, release, nightlies on both hosts |
+
+Releases: `just release patch` bumps `package.json`, regenerates `CHANGELOG.md` with git-cliff, tags and
+pushes; the Release workflow publishes to npm (secret `NPM_TOKEN`).
+
+## License
+
+MIT

package/extensions/command/parse.ts

@@ -0,0 +1,75 @@
+/** `/codegraph ...`: parsing and argument completion. Pure: the handler in graphnav.ts acts on the result. */
+import { MODES, type Mode } from "../core/config.ts";
+
+export type Command =
+	| { kind: "status" }
+	| { kind: "on" }
+	| { kind: "off" }
+	| { kind: "mode"; mode: Mode }
+	| { kind: "sync" }
+	| { kind: "reindex" }
+	| { kind: "init" }
+	| { kind: "invalid"; message: string };
+
+export const USAGE = "Usage: /codegraph [status] · on · off · mode <enforce|nudge|off> · sync · reindex · init";
+
+export function parseCommand(args: string | undefined): Command {
+	const [cmd, ...rest] = (args ?? "").trim().split(/\s+/).filter(Boolean);
+	switch (cmd?.toLowerCase()) {
+		case undefined:
+		case "status":
+			return { kind: "status" };
+		case "on":
+		case "enable":
+			return { kind: "on" };
+		case "off":
+		case "disable":
+			return { kind: "off" };
+		case "mode": {
+			const m = rest[0]?.toLowerCase();
+			return MODES.includes(m as Mode) && rest.length === 1
+				? { kind: "mode", mode: m as Mode }
+				: { kind: "invalid", message: "Usage: /codegraph mode <enforce|nudge|off>" };
+		}
+		case "sync":
+			return { kind: "sync" };
+		case "reindex":
+		case "index":
+			return { kind: "reindex" };
+		case "init":
+			return { kind: "init" };
+		default:
+			return { kind: "invalid", message: `Unknown option "${cmd}". ${USAGE}` };
+	}
+}
+
+export interface CompletionItem {
+	value: string;
+	/** Required by pi: it calls `label.endsWith(...)` when applying a completion. */
+	label: string;
+	description?: string;
+}
+
+const TOP_LEVEL: CompletionItem[] = [
+	{ value: "status", label: "status", description: "Index state, mode and gate counts" },
+	{ value: "on", label: "on", description: "Turn CodeGraph-first on" },
+	{ value: "off", label: "off", description: "Turn CodeGraph-first off" },
+	{ value: "mode ", label: "mode", description: "Symbol searches: enforce, nudge or off" },
+	{ value: "sync", label: "sync", description: "Sync the index with changed files" },
+	{ value: "reindex", label: "reindex", description: "Rebuild the index from scratch" },
+	{ value: "init", label: "init", description: "Create the index for this project" },
+];
+
+const MODE_ITEMS: CompletionItem[] = [
+	{ value: "mode enforce", label: "enforce", description: "Block a symbol search once, pointing to CodeGraph" },
+	{ value: "mode nudge", label: "nudge", description: "Let it run, add a CodeGraph hint to the result" },
+	{ value: "mode off", label: "off", description: "Leave text searches alone" },
+];
+
+/** `prefix` is the whole argument text typed so far (pi replaces it with `value`). */
+export function completions(prefix: string): CompletionItem[] | null {
+	const text = (prefix ?? "").toLowerCase().replace(/^\s+/, "");
+	const pool = text.startsWith("mode ") ? MODE_ITEMS : TOP_LEVEL;
+	const out = pool.filter((i) => i.value.startsWith(text));
+	return out.length > 0 ? out : null;
+}

package/extensions/core/config.ts

@@ -0,0 +1,103 @@
+/**
+ * The persisted settings: <agent dir>/codegraph.json.
+ *
+ * A hand-edited file can hold anything, so `sanitizeConfig` keeps valid values and defaults the
+ * rest. A missing file is not a problem (defaults); a broken one is reported, never thrown.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Mode = "enforce" | "nudge" | "off";
+export const MODES: readonly Mode[] = ["enforce", "nudge", "off"];
+
+export interface Config {
+	/** Master switch: when false the extension adds no guidance, gates nothing and indexes nothing. */
+	enabled: boolean;
+	/** Show the status line entry. */
+	showStatus: boolean;
+	/** Symbol searches with rg/grep: block once (`enforce`), only add a hint (`nudge`) or leave alone (`off`). */
+	mode: Mode;
+	/** Create the index (`codegraph init`) for a git repo that has none. */
+	autoInit: boolean;
+	/** Sync or rebuild a stale index when the session starts. */
+	autoSync: boolean;
+	/** Keep the CodeGraph server's file watcher running, so the index follows edits. */
+	watch: boolean;
+	/** Source files read before any CodeGraph call that earn a hint (0 = never). */
+	readHintAfter: number;
+	/** Per-call timeout for the CodeGraph server, in ms. */
+	timeoutMs: number;
+}
+
+export const DEFAULT_CONFIG: Config = {
+	enabled: true,
+	showStatus: true,
+	mode: "enforce",
+	autoInit: true,
+	autoSync: true,
+	watch: true,
+	readHintAfter: 3,
+	timeoutMs: 30_000,
+};
+
+export const clampInt = (v: unknown, min: number, max: number, fallback: number): number =>
+	typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, Math.round(v))) : fallback;
+
+export function sanitizeConfig(raw: unknown): Config {
+	const r = (typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : {}) as Record<string, unknown>;
+	const d = DEFAULT_CONFIG;
+	return {
+		enabled: typeof r.enabled === "boolean" ? r.enabled : d.enabled,
+		showStatus: typeof r.showStatus === "boolean" ? r.showStatus : d.showStatus,
+		mode: MODES.includes(r.mode as Mode) ? (r.mode as Mode) : d.mode,
+		autoInit: typeof r.autoInit === "boolean" ? r.autoInit : d.autoInit,
+		autoSync: typeof r.autoSync === "boolean" ? r.autoSync : d.autoSync,
+		watch: typeof r.watch === "boolean" ? r.watch : d.watch,
+		readHintAfter: clampInt(r.readHintAfter, 0, 100, d.readHintAfter),
+		timeoutMs: clampInt(r.timeoutMs, 1000, 600_000, d.timeoutMs),
+	};
+}
+
+/** Where pi keeps its config: PI_CODING_AGENT_DIR, then $XDG_CONFIG_HOME/pi/agent, then ~/.pi/agent. */
+export function resolveAgentDir(env: Record<string, string | undefined>, home: string): string {
+	if (env.PI_CODING_AGENT_DIR) return env.PI_CODING_AGENT_DIR;
+	if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, "pi", "agent");
+	return join(home, ".pi", "agent");
+}
+
+export const configPath = (env: Record<string, string | undefined> = process.env, home = homedir()): string =>
+	join(resolveAgentDir(env, home), "codegraph.json");
+
+/** The config, plus a `problem` when the file exists but cannot be used. */
+export async function readConfig(path = configPath()): Promise<{ config: Config; problem?: string }> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (e) {
+		const code = (e as { code?: string } | null)?.code;
+		return code === "ENOENT" ? { config: sanitizeConfig({}) } : { config: sanitizeConfig({}), problem: `cannot read ${path} (${code ?? "error"})` };
+	}
+	try {
+		return { config: sanitizeConfig(JSON.parse(raw)) };
+	} catch {
+		return { config: sanitizeConfig({}), problem: `${path} is not valid JSON` };
+	}
+}
+
+export async function loadConfig(path = configPath()): Promise<Config> {
+	return (await readConfig(path)).config;
+}
+
+/** Atomic: written to a temp file and renamed, so a crash or a second pi session never leaves half a file. */
+export async function saveConfig(config: Config, path = configPath()): Promise<void> {
+	await mkdir(join(path, ".."), { recursive: true });
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+		await rename(tmp, path);
+	} catch (e) {
+		await Promise.allSettled([rm(tmp, { force: true })]); // the original error matters more
+		throw e;
+	}
+}

package/extensions/core/gate.ts

@@ -0,0 +1,317 @@
+/**
+ * The CodeGraph-first gate: spots text searches (`rg`, `grep`, `git grep`, `ag`, `ack`, pi's
+ * `grep` tool) whose pattern is really a symbol lookup, and decides whether to let them run.
+ *
+ * Pure: the extension feeds it commands and remembers what CodeGraph was already asked.
+ */
+
+/** One text search found in a command. `pattern` is undefined for a listing (`rg --files`). */
+export interface Search {
+	tool: string;
+	pattern?: string;
+	/** File and directory operands. */
+	paths: string[];
+	/** `--type`/`--glob`/`--include` filters, as written. */
+	filters: string[];
+}
+
+const OPERATORS = new Set(["|", "||", "&", "&&", ";", "(", ")", "\n", "|&"]);
+
+/**
+ * Split a shell command into simple commands (arrays of words). Handles quotes, backslash
+ * escapes and the usual operators; anything stranger (subshell syntax, heredocs) degrades to
+ * extra words, which only makes the gate more permissive.
+ */
+export function splitCommands(command: string): string[][] {
+	return splitPipeline(command).map((c) => c.words);
+}
+
+/** Like `splitCommands`, also telling which commands read a pipe (`a | b`: b is piped). */
+export function splitPipeline(command: string): { words: string[]; piped: boolean }[] {
+	const out: { words: string[]; piped: boolean }[] = [];
+	let cur: string[] = [];
+	let word = "";
+	let inWord = false;
+	let piped = false;
+	const endWord = () => {
+		if (inWord) cur.push(word);
+		word = "";
+		inWord = false;
+	};
+	const endCommand = (nextPiped: boolean) => {
+		endWord();
+		if (cur.length > 0) out.push({ words: cur, piped });
+		cur = [];
+		piped = nextPiped;
+	};
+	for (let i = 0; i < command.length; i++) {
+		const c = command[i]!;
+		if (c === "'") {
+			const end = command.indexOf("'", i + 1);
+			const stop = end === -1 ? command.length : end;
+			word += command.slice(i + 1, stop);
+			inWord = true;
+			i = stop;
+		} else if (c === '"') {
+			inWord = true;
+			for (i++; i < command.length && command[i] !== '"'; i++) {
+				if (command[i] === "\\" && i + 1 < command.length && '"\\$`'.includes(command[i + 1]!)) i++;
+				word += command[i];
+			}
+		} else if (c === "\\" && i + 1 < command.length) {
+			if (command[i + 1] !== "\n") word += command[i + 1];
+			inWord = true;
+			i++;
+		} else if (c === " " || c === "\t") {
+			endWord();
+		} else if (OPERATORS.has(c)) {
+			const double = command[i + 1] === c;
+			endCommand(c === "|" && !double);
+			if (double || (c === "|" && command[i + 1] === "&")) i++;
+		} else {
+			word += c;
+			inWord = true;
+		}
+	}
+	endCommand(false);
+	return out;
+}
+
+/** Flags that take a value, per tool. Long flags may also be written `--flag=value`. */
+const VALUE_FLAGS: Record<string, Set<string>> = {
+	rg: new Set(
+		"-A -B -C -m -M -j -d -E -g -t -T -r -f -e --after-context --before-context --context --max-count --max-columns --threads --max-depth --encoding --glob --iglob --type --type-not --type-add --type-clear --replace --file --regexp --color --colors --sort --sortr --pre --pre-glob --ignore-file --max-filesize --path-separator --field-match-separator --field-context-separator --context-separator --engine --dfa-size-limit --regex-size-limit --hostname-bin --hyperlink-format".split(" "),
+	),
+	grep: new Set("-A -B -C -m -e -f -d -D --after-context --before-context --context --max-count --regexp --file --include --exclude --exclude-dir --exclude-from --directories --devices --color --colour --label --binary-files".split(" ")),
+	ag: new Set("-A -B -C -m -G -g --after --before --context --max-count --file-search-regex --ignore --ignore-dir --depth --pager".split(" ")),
+	ack: new Set("-A -B -C -m -g --after-context --before-context --context --max-count --type --ignore-dir --ignore-file --output --match".split(" ")),
+};
+VALUE_FLAGS.egrep = VALUE_FLAGS.grep!;
+VALUE_FLAGS.fgrep = VALUE_FLAGS.grep!;
+VALUE_FLAGS["git grep"] = new Set("-A -B -C -m -e -f --after-context --before-context --context --max-count --max-depth --threads".split(" "));
+
+const PATTERN_FLAGS = new Set(["-e", "--regexp"]);
+const FILTER_FLAGS = new Set(["-g", "-t", "-T", "--glob", "--iglob", "--type", "--type-not", "--include", "-G", "--file-search-regex"]);
+const WRAPPERS = new Set(["sudo", "command", "exec", "time", "nice", "nohup", "env", "xargs", "timeout"]);
+
+/** The program of a simple command, skipping `VAR=x` assignments and wrappers like `xargs -0`. */
+function programIndex(words: string[]): number {
+	let i = 0;
+	for (;;) {
+		while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]!)) i++;
+		const w = words[i];
+		if (w === undefined || !WRAPPERS.has(baseName(w))) return i;
+		i++;
+		while (i < words.length && words[i]!.startsWith("-")) i++;
+		if (baseName(words[i - 1] ?? "") === "timeout" && /^\d/.test(words[i] ?? "")) i++;
+	}
+}
+
+const baseName = (w: string) => w.slice(w.lastIndexOf("/") + 1);
+
+/** Every text search over files in a shell command (a filter reading a pipe searches no code). */
+export function findSearches(command: string): Search[] {
+	const out: Search[] = [];
+	for (const { words, piped } of splitPipeline(command)) {
+		const at = programIndex(words);
+		const prog = baseName(words[at] ?? "");
+		let tool: string;
+		let args: string[];
+		if (prog === "git") {
+			let j = at + 1;
+			while (j < words.length && words[j]!.startsWith("-")) j += words[j] === "-C" || words[j] === "-c" ? 2 : 1;
+			if (words[j] !== "grep") continue;
+			tool = "git grep";
+			args = words.slice(j + 1);
+		} else if (prog in VALUE_FLAGS && prog !== "git grep") {
+			tool = prog;
+			args = words.slice(at + 1);
+		} else continue;
+		const search = parseArgs(tool, args);
+		// `… | rg x` filters the pipe; `… | xargs rg x` searches the files the pipe names.
+		if (piped && search.paths.length === 0 && !words.slice(0, at).some((w) => baseName(w) === "xargs")) continue;
+		out.push(search);
+	}
+	return out;
+}
+
+function parseArgs(tool: string, args: string[]): Search {
+	const valueFlags = VALUE_FLAGS[tool]!;
+	const positional: string[] = [];
+	const filters: string[] = [];
+	let pattern: string | undefined;
+	let listing = false;
+	let endOfFlags = false;
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i]!;
+		if (endOfFlags || !a.startsWith("-") || a === "-") {
+			positional.push(a);
+			continue;
+		}
+		if (a === "--") {
+			endOfFlags = true;
+			continue;
+		}
+		const eq = a.startsWith("--") ? a.indexOf("=") : -1;
+		const flag = eq === -1 ? a : a.slice(0, eq);
+		// Short flag cluster with an attached value (`-tmd`, `-e foo` as `-efoo`), or a cluster of booleans (`-rn`).
+		const short = !a.startsWith("--") && a.length > 2 ? `-${a[1]}` : undefined;
+		let value: string | undefined;
+		let name = flag;
+		if (eq !== -1) value = a.slice(eq + 1);
+		else if (valueFlags.has(flag)) value = args[++i];
+		else if (short && valueFlags.has(short)) {
+			name = short;
+			value = a.slice(2);
+		}
+		if (tool === "rg" && (name === "--files" || name === "--type-list")) listing = true;
+		if (tool === "ag" && name === "-g") listing = true;
+		if (value === undefined) continue;
+		if (PATTERN_FLAGS.has(name)) pattern = pattern === undefined ? value : `${pattern}|${value}`;
+		else if (FILTER_FLAGS.has(name) || (tool === "ack" && name === "--type")) filters.push(value);
+		else if (name === "-f" || name === "--file") listing = true; // patterns come from a file: unknowable
+	}
+	if (listing && pattern === undefined) return { tool, paths: positional, filters };
+	if (pattern === undefined) pattern = positional.shift();
+	return { tool, pattern, paths: positional, filters };
+}
+
+/** Extensions CodeGraph indexes as code. Searches limited to anything else are left alone. */
+export const CODE_EXTENSIONS = new Set(
+	"ts tsx js jsx mjs cjs mts cts kt kts java scala groovy rs go py pyi rb php cs fs swift m mm c cc cpp cxx h hh hpp hxx dart lua ex exs erl hs ml vue svelte zig nim sol".split(" "),
+);
+const CODE_TYPES = new Set(
+	"ts typescript js javascript kotlin kt java scala rust rs go py python ruby rb php cs csharp swift objc objcpp c cpp dart lua elixir erlang haskell ocaml vue svelte zig".split(" "),
+);
+
+const extOf = (p: string): string | undefined => {
+	const base = baseName(p);
+	const dot = base.lastIndexOf(".");
+	return dot > 0 ? base.slice(dot + 1).toLowerCase() : undefined;
+};
+
+/** Is the search restricted to non-code files (docs, config, logs)? */
+export function targetsOnlyNonCode(s: Search): boolean {
+	if (s.filters.length > 0) {
+		const nonCode = s.filters.every((f) => {
+			const neg = f.startsWith("!");
+			if (neg) return false;
+			const ext = /\.([A-Za-z0-9]+)\}?$/.exec(f)?.[1]?.toLowerCase() ?? (f.includes("*") || f.includes(".") ? undefined : f.toLowerCase());
+			return ext !== undefined && !CODE_EXTENSIONS.has(ext) && !CODE_TYPES.has(ext);
+		});
+		if (nonCode) return true;
+	}
+	const files = s.paths.filter((p) => extOf(p) !== undefined);
+	return s.paths.length > 0 && files.length === s.paths.length && files.every((p) => !CODE_EXTENSIONS.has(extOf(p)!));
+}
+
+const DECL_KEYWORDS =
+	"fn|pub fn|pub\\(crate\\) fn|async fn|def|class|struct|enum|trait|impl|interface|type|typealias|func|function|export function|export const|export class|export interface|export type|const|let|var|val|fun|suspend fun|object|data class|sealed class|protocol|extension|module|mod|use|import|from|new";
+const DECL = new RegExp(`^(?:${DECL_KEYWORDS})(?:\\s+|\\\\s[+*])`);
+const KEYWORDS = new Set(DECL_KEYWORDS.split("|").filter((k) => !k.includes(" ") && !k.includes("\\")));
+const QUALIFIED = /^[A-Za-z_$][\w$]*(?:(?:::|\.|#|->)[A-Za-z_$][\w$]*)*$/;
+const NOT_SYMBOLS = new Set(["todo", "fixme", "hack", "xxx", "note", "bug", "deprecated", "error", "warn", "warning", "info", "debug"]);
+
+/** Strip regex syntax that does not change what is being looked for. */
+function normalizeAlternative(raw: string): string {
+	let s = raw.trim();
+	s = s.replace(/\\[bB<>]/g, "").replace(/\[\[:<:\]\]|\[\[:>:\]\]/g, "");
+	s = s.replace(/^\^/, "").replace(/\$$/, "");
+	s = s.replace(/^\(\?:?/, "").replace(/\)$/, "");
+	s = s.replace(DECL, "");
+	s = s.replace(/(?:\\?\(|\\?<|\s*\\s\*\\?\(|\s*\\s\*)$/, "");
+	s = s.replace(/^(?:\.\*|\\s\*|\\s\+)+|(?:\.\*|\\s\*|\\s\+)+$/g, "");
+	return s.trim();
+}
+
+/**
+ * The identifiers a pattern looks for, when it is a symbol lookup (`fooBar`, `\bFoo\b`,
+ * `fn parse_args`, `Foo::new`, `foo(`, `a|b`). Undefined for a text search (a sentence, a
+ * string literal, a path, an error message, `TODO`).
+ */
+export function symbolsIn(pattern: string | undefined): string[] | undefined {
+	if (pattern === undefined || pattern.length > 200) return undefined;
+	const alternatives = pattern.split(/\\?\|/);
+	const out: string[] = [];
+	for (const alt of alternatives) {
+		const s = normalizeAlternative(alt.replace(/^\(|\)$/g, ""));
+		if (s.length < 3 || !QUALIFIED.test(s) || KEYWORDS.has(s)) return undefined;
+		const parts = s.split(/::|\.|#|->/);
+		if (parts.some((p) => NOT_SYMBOLS.has(p.toLowerCase()))) return undefined;
+		if (/^[A-Z0-9_]+$/.test(s) && s.length <= 4) return undefined;
+		out.push(s);
+	}
+	return out.length > 0 ? out : undefined;
+}
+
+/** Words a CodeGraph call looked up, for remembering what is already answered. */
+export function lookupWords(params: Record<string, unknown>): string[] {
+	const out: string[] = [];
+	for (const key of ["query", "symbol"]) {
+		const v = params[key];
+		if (typeof v === "string") for (const w of v.split(/[^\w$:.#>-]+/)) if (w.length >= 3) out.push(...w.split(/::|\.|#|->/).filter((x) => x.length >= 3), w);
+	}
+	return out.map((w) => w.toLowerCase());
+}
+
+export type Mode = "enforce" | "nudge" | "off";
+
+export type Decision =
+	| { action: "allow" }
+	| { action: "block"; reason: string }
+	| { action: "nudge"; hint: string };
+
+export interface GateMemory {
+	/** Lower-cased words already looked up with CodeGraph this session. */
+	lookedUp: Set<string>;
+	/** Commands blocked once: running the same command again is the agent's explicit override. */
+	blocked: Set<string>;
+}
+
+export const newMemory = (): GateMemory => ({ lookedUp: new Set(), blocked: new Set() });
+
+const known = (symbol: string, mem: GateMemory) => {
+	const s = symbol.toLowerCase();
+	if (mem.lookedUp.has(s)) return true;
+	const last = s.split(/::|\.|#|->/).pop()!;
+	return mem.lookedUp.has(last);
+};
+
+export function suggestion(symbols: string[]): string {
+	const q = symbols.join(" ");
+	const one = symbols[0]!;
+	return [
+		`codegraph_search({ query: "${one}" }) for the definition`,
+		`codegraph_callers({ symbol: "${one}" }) for usages`,
+		`codegraph_explore({ query: "${q}" }) for the code around it`,
+	].join(", ");
+}
+
+/**
+ * What to do with a call to a text-search tool. `key` identifies the exact call (for the
+ * re-run override); `searches` are what it searches for.
+ */
+export function decide(mode: Mode, searches: Search[], key: string, mem: GateMemory): Decision {
+	if (mode === "off") return { action: "allow" };
+	const symbols = new Set<string>();
+	for (const s of searches) {
+		if (targetsOnlyNonCode(s)) continue;
+		for (const sym of symbolsIn(s.pattern) ?? []) if (!known(sym, mem)) symbols.add(sym);
+	}
+	if (symbols.size === 0) return { action: "allow" };
+	const list = [...symbols];
+	const hint = `"${list.join('", "')}" ${list.length === 1 ? "looks like a symbol" : "look like symbols"}: CodeGraph answers this structurally. Use ${suggestion(list)}.`;
+	if (mode === "nudge") return { action: "nudge", hint: `[codegraph] ${hint}` };
+	if (mem.blocked.has(key)) return { action: "allow" };
+	mem.blocked.add(key);
+	return {
+		action: "block",
+		reason: `CodeGraph first: ${hint} If CodeGraph cannot answer it (string literals, comments, generated or non-indexed files), run the exact same command again and it will be allowed.`,
+	};
+}
+
+/** Source files: reading many of them before any CodeGraph call earns a hint. */
+export const isSourceFile = (path: string): boolean => {
+	const ext = extOf(path);
+	return ext !== undefined && CODE_EXTENSIONS.has(ext);
+};