@pharaoh-so/mcp 0.3.60 → 0.3.61

package/.mcp.json

@@ -3,7 +3,7 @@
 		"pharaoh": {
 			"command": "npx",
 			"args": [
-				"@pharaoh-so/mcp@0.3.60"
+				"@pharaoh-so/mcp@0.3.61"
 			]
 		}
 	}

package/CHANGELOG.md

@@ -26,6 +26,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The `pharaoh` skill's connection URL is `https://mcp.pharaoh.so/mcp` instead of `/sse`. The skill also carries the guidance that was only in the server instructions: one Pharaoh call answers what grep and file reads take many turns to piece together, load Pharaoh's tools before the first code search when your client defers them, summarize a block marked "Trace view available" instead of reproducing it, and check related repos when a change touches shared interfaces.
 - The server instructions state facts: what Pharaoh maps, which tool answers which question, what the graph leaves to grep, how repos are mapped and what each account tool does. Asking Pharaoh first, not re-checking its answers with grep, surfacing and crediting its ★ blocks and the rest of that guidance now live in the `pharaoh` skill. Claude Code and OpenClaw list the skill in every session and load its body only when they use it. The Grep hook and the optional `~/.claude/CLAUDE.md` line are unchanged and apply from the start of a session.
 
+## [0.3.61] - 2026-11-05
+
+### Changed
+- Eligible project memory pilot setup recommends quiet reminders and remembers declines through upgrades. The normal authenticated MCP connection provides memory when hooks are disabled or unavailable.
+
+### Added
+- Optional pilot worktree cues suggest graph tools for structural Bash searches and flag local edits that differ from a previously consulted codebase map revision.
+
 ## [0.3.60] - 2026-11-05
 
 ### Added

package/dist/helpers.d.ts

@@ -5,7 +5,7 @@ export declare const NPX_COMMAND = "npx @pharaoh-so/mcp";
 /** Write one or more lines to stderr. */
 export declare function printLines(...lines: string[]): void;
 /**
- * Ask a yes/no question that defaults to yes: Enter, `y` or `yes` is yes; `n`
+ * Ask a yes/no question. Enter uses the default; `y` or `yes` is yes; `n`
  * or `no` is no; anything else asks again. Ctrl-C exits (130). On a terminal,
  * keys pressed before the question showed (an Enter while sign-in waited) are
  * dropped, so only a key pressed after reading it answers.
@@ -13,11 +13,12 @@ export declare function printLines(...lines: string[]): void;
  * @param question - The prompt, ending in something like `[Y/n] `.
  * @param input - Where the answer is read (defaults to stdin).
  * @param output - Where the prompt is written (defaults to stderr, like every other line).
+ * @param defaultAnswer - The answer for Enter (defaults to yes).
  * @returns The answer, or null when input ended before one.
  */
 export declare function askYesNo(question: string, input?: NodeJS.ReadableStream & {
     isTTY?: boolean;
-}, output?: NodeJS.WritableStream): Promise<boolean | null>;
+}, output?: NodeJS.WritableStream, defaultAnswer?: boolean): Promise<boolean | null>;
 /** Parse CLI arguments. */
 export declare function parseArgs(argv?: string[]): {
     server: string;

package/dist/helpers.js

@@ -15,7 +15,7 @@ export function printLines(...lines) {
 /** How long to read and drop input that was typed before a question showed. */
 const TYPE_AHEAD_MS = 50;
 /**
- * Ask a yes/no question that defaults to yes: Enter, `y` or `yes` is yes; `n`
+ * Ask a yes/no question. Enter uses the default; `y` or `yes` is yes; `n`
  * or `no` is no; anything else asks again. Ctrl-C exits (130). On a terminal,
  * keys pressed before the question showed (an Enter while sign-in waited) are
  * dropped, so only a key pressed after reading it answers.
@@ -23,9 +23,10 @@ const TYPE_AHEAD_MS = 50;
  * @param question - The prompt, ending in something like `[Y/n] `.
  * @param input - Where the answer is read (defaults to stdin).
  * @param output - Where the prompt is written (defaults to stderr, like every other line).
+ * @param defaultAnswer - The answer for Enter (defaults to yes).
  * @returns The answer, or null when input ended before one.
  */
-export async function askYesNo(question, input = process.stdin, output = process.stderr) {
+export async function askYesNo(question, input = process.stdin, output = process.stderr, defaultAnswer = true) {
     if (input.isTTY)
         await dropTypedAhead(input);
     const rl = createInterface({ input, output });
@@ -39,7 +40,9 @@ export async function askYesNo(question, input = process.stdin, output = process
         // The iterator ends on EOF; rl.question never settles then.
         for await (const reply of rl) {
             const answer = reply.trim().toLowerCase();
-            if (answer === "" || answer === "y" || answer === "yes")
+            if (answer === "")
+                return defaultAnswer;
+            if (answer === "y" || answer === "yes")
                 return true;
             if (answer === "n" || answer === "no")
                 return false;
@@ -96,7 +99,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
     return { server, logout };
 }
 export function printUsage() {
-    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config, the Claude Code plugin and the CLAUDE.md line, then exit", "  --clean           Remove Pharaoh setup, including managed local project memory hooks", "  --memory-hooks    Install optional project memory reminders during interactive setup", "  --disable-memory-hooks  Remove Pharaoh's local project memory hooks", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config, the Claude Code plugin and the CLAUDE.md line, then exit", "  --clean           Remove Pharaoh setup, including managed local project memory hooks", "  --memory-hooks    Accept project memory hooks during eligible interactive setup", "  --disable-memory-hooks  Remove Pharaoh's memory hooks and remember the choice", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.

package/dist/index.js

@@ -12,7 +12,8 @@
  *                      mode until device flow completes, then swap to SSE in
  *                      place — the stdio session never disconnects.
  */
-import { syncMemoryHooks } from "../project-memory/setup.mjs";
+import { resetHookPreferences } from "../project-memory/preferences.mjs";
+import { applyMemoryHookChoices, chooseMemoryHooks, syncMemoryHooks, } from "../project-memory/setup.mjs";
 import { pollForToken, printActivationPrompt, printAuthSuccess, requestDeviceCode, } from "./auth.js";
 import { AuthRequiredBackend, createSseBackend } from "./backend.js";
 import { deleteCredentials, readCredentials, writeCredentials, } from "./credentials.js";
@@ -44,6 +45,34 @@ function reportMemorySetup(options) {
         return false;
     }
 }
+function clearMemoryHookChoices(disable) {
+    try {
+        resetHookPreferences(disable);
+        return true;
+    }
+    catch {
+        printLines("Pharaoh: could not update local project memory choices.");
+        return false;
+    }
+}
+async function setupMemoryHooks(credentials, clients, requested) {
+    try {
+        const decision = await chooseMemoryHooks({
+            credentials,
+            clients,
+            requested,
+            ask: (question, defaultAnswer) => process.stderr.isTTY
+                ? askYesNo(question, process.stdin, process.stderr, defaultAnswer)
+                : Promise.resolve(null),
+        });
+        const notices = applyMemoryHookChoices(decision, { credentials });
+        if (notices.length)
+            printLines(...notices);
+    }
+    catch {
+        printLines("Pharaoh: could not finish local project memory setup. MCP remains available.");
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes("--help") || args.includes("-h")) {
@@ -68,7 +97,8 @@ async function main() {
         return;
     }
     if (args.includes("--disable-memory-hooks")) {
-        if (!reportMemorySetup())
+        const saved = clearMemoryHookChoices(true);
+        if (!reportMemorySetup() || !saved)
             process.exitCode = 1;
         return;
     }
@@ -77,10 +107,11 @@ async function main() {
     if (args.includes("--clean")) {
         const { cleanCodexSetup, cleanSlate } = await import("./setup.js");
         const { uninstallClaudePlugin } = await import("./install-skills.js");
+        clearMemoryHookChoices(false);
+        reportMemorySetup();
         cleanSlate();
         uninstallClaudePlugin();
         cleanCodexSetup();
-        reportMemorySetup();
         printLines("Pharaoh: local setup cleanup finished.");
         process.exit(0);
     }
@@ -90,10 +121,11 @@ async function main() {
         const { uninstallClaudePlugin } = await import("./install-skills.js");
         // Credentials first: a cleanup step that fails must never leave the tokens behind.
         deleteCredentials();
+        clearMemoryHookChoices(false);
+        reportMemorySetup();
         cleanSlate();
         uninstallClaudePlugin();
         cleanCodexSetup();
-        reportMemorySetup();
         printLines("Pharaoh: credentials cleared and local setup cleanup finished.");
         process.exit(0);
     }
@@ -130,8 +162,10 @@ async function main() {
             if (runCodexSetup())
                 clients.push("codex");
         }
-        if (!clients.length)
+        if (!clients.length) {
+            await setupMemoryHooks(newCreds, clients, args.includes("--memory-hooks"));
             process.exit(1);
+        }
         if (clients.includes("claude-code")) {
             process.stderr.write("  Setting up...");
             const { keptCommands } = runInstallSkills(undefined, { silent: true });
@@ -144,7 +178,7 @@ async function main() {
             if (claudeMd)
                 printLines(claudeMd);
         }
-        reportMemorySetup({ credentials: newCreds, clients, enable: args.includes("--memory-hooks") });
+        await setupMemoryHooks(newCreds, clients, args.includes("--memory-hooks"));
         // The registration is pinned to this version; upgrading is a deliberate
         // re-run. Interactive only, and quiet when the registry can't be reached.
         const latest = await fetchLatestVersion();

package/hooks/route-grep.mjs

@@ -103,6 +103,69 @@ export function routeGrep(input, signedIn, redirected) {
 	].join(" ");
 }
 
+/**
+ * Match one plain Bash rg invocation with an explicit declaration or call pattern.
+ * @param {unknown} command
+ * @returns {{ symbol: string, tool: "search_functions" | "get_blast_radius" } | undefined}
+ */
+export function classifyBashGrep(command) {
+	if (typeof command !== "string" || command.length > 1024 || /[\r\n]/.test(command)) return;
+	const source = command.trim();
+	// Only the quoting and flags needed by a simple rg search. Unrecognized
+	// shell syntax falls through, including expansions, redirects and pipelines.
+	const word = /(?:'([^']*)'|"([^"$`\\]*)"|([A-Za-z0-9_./:-]+))(?:[ \t]+|$)/gy;
+	const args = [];
+	while (word.lastIndex < source.length) {
+		const match = word.exec(source);
+		if (!match) return;
+		args.push(match[1] ?? match[2] ?? match[3]);
+	}
+	if (args.shift() !== "rg") return;
+
+	const scope = {};
+	while (args[0]?.startsWith("-")) {
+		const option = args.shift();
+		if (option === "--") break;
+		if (["-n", "--line-number", "--no-heading", "-S", "--smart-case"].includes(option ?? ""))
+			continue;
+		const value = args.shift();
+		if (!value) return;
+		if ((option === "-g" || option === "--glob") && scope.glob === undefined) scope.glob = value;
+		else if ((option === "-t" || option === "--type") && scope.type === undefined)
+			scope.type = value;
+		else return;
+	}
+	const [pattern, path] = args;
+	const globExtensions = scope.glob?.match(/^\*\.(?:\{([a-z]+(?:,[a-z]+)*)\}|([a-z]+))$/i);
+	if (
+		!pattern ||
+		args.length > 2 ||
+		(path &&
+			(!/^[A-Za-z0-9_./][A-Za-z0-9_./-]*$/.test(path) ||
+				path.startsWith("/") ||
+				path.split("/").includes(".."))) ||
+		[scope.glob, path].some((value) =>
+			/(?:^|[/.\-_])(?:config|settings|env|docs|documentation|fixtures|snapshots)(?:[/.\-_]|$)/i.test(
+				value ?? "",
+			),
+		) ||
+		(scope.glob &&
+			(!globExtensions ||
+				!(globExtensions[1] ?? globExtensions[2])
+					.toLowerCase()
+					.split(",")
+					.every((extension) => MAPPED_EXTENSIONS.has(extension)))) ||
+		!searchesMappedCode({ type: scope.type }) ||
+		!searchesMappedCode({ path })
+	)
+		return;
+	const symbol = symbolSearched(pattern);
+	if (!symbol || symbol.length > 80) return;
+	if (/\\?\($/.test(pattern)) return { symbol, tool: "get_blast_radius" };
+	if (/^(?:(?:export|default|async) +)*(?:function|class|def|interface|type|enum)\b/.test(pattern))
+		return { symbol, tool: "search_functions" };
+}
+
 /** Hook entry point: read the payload from stdin, reply with a PreToolUse deny or nothing. */
 function main() {
 	try {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.60",
+	"version": "0.3.61",
 	"description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for coding agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
 	"type": "module",
 	"main": "dist/index.js",

package/project-memory/bundle.mjs

@@ -12,7 +12,7 @@ import {
 import { dirname, join, relative } from "node:path";
 
 const LIMIT = 256 * 1024;
-export const MEMORY_RUNTIME_FILES = [
+export const LEGACY_MEMORY_RUNTIME_FILES = [
 	"execute-turn.mjs",
 	"hook-config.mjs",
 	"hook-events.mjs",
@@ -25,6 +25,13 @@ export const MEMORY_RUNTIME_FILES = [
 	"runtime/package.json",
 	"runtime/refresh.js",
 ];
+export const MEMORY_RUNTIME_FILES = [
+	...LEGACY_MEMORY_RUNTIME_FILES,
+	"bundle.mjs",
+	"graph-cues.mjs",
+	"preferences.mjs",
+	"route-grep.mjs",
+];
 
 function digest(files) {
 	return createHash("sha256").update(JSON.stringify(files)).digest("hex");
@@ -51,7 +58,7 @@ export function packagedMemoryBundle(packageRoot = new URL("../", import.meta.ur
 		} else {
 			const location = name.startsWith("runtime/")
 				? new URL(`dist/${name.slice(8)}`, packageRoot)
-				: new URL(`project-memory/${name}`, packageRoot);
+				: new URL(`${name === "route-grep.mjs" ? "hooks" : "project-memory"}/${name}`, packageRoot);
 			try {
 				bytes = readFileSync(location);
 			} catch {

package/project-memory/graph-cues.mjs

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { gitBefore, sessionKey, updateWorktreeCueState } from "./local.mjs";
+
+const MAP_TOOL = "mcp__pharaoh__get_codebase_map";
+const SHA = /^(?!0{40}$)[a-f0-9]{40}$/i;
+const DIGEST = /^[a-f0-9]{64}$/;
+const MAPPED_FILE = /\.(?:[cm]?[jt]s|[jt]sx|py)$/i;
+const STATE_TTL = 12 * 60 * 60 * 1000;
+const MAX_SCOPES = 8;
+const MAX_SEARCHES = 2;
+const MAX_WARNED = 8;
+const MAX_EDIT_PATHS = 20;
+const MAX_SOURCE_BYTES = 512 * 1024;
+
+function digest(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function responseText(value) {
+	if (typeof value === "string") {
+		if (/^\s*[[{]/.test(value)) {
+			try {
+				return responseText(JSON.parse(value));
+			} catch {
+				return [];
+			}
+		}
+		return [value];
+	}
+	if (value?.isError || value?.is_error) return [];
+	const content = Array.isArray(value) ? value : value?.content;
+	return Array.isArray(content)
+		? content.flatMap((block) =>
+				block?.type === "text" && typeof block.text === "string" ? [block.text] : [],
+			)
+		: [];
+}
+
+function mappedRevision(input, target, repos) {
+	const requested = input.tool_input?.repo;
+	if (typeof requested !== "string") return;
+	const full = target.repo.toLowerCase();
+	const short = full.split("/")[1];
+	if (requested.toLowerCase() !== full) {
+		if (requested.toLowerCase() !== short) return;
+		const matches = new Set(
+			repos
+				.filter((repo) => typeof repo === "string")
+				.map((repo) => repo.toLowerCase())
+				.filter((repo) => repo.split("/").at(-1) === short),
+		);
+		if (matches.size !== 1 || !matches.has(full)) return;
+	}
+	const maps = responseText(input.tool_response).filter((text) =>
+		text
+			.split(/\r?\n/)
+			.some((line) =>
+				[`# ${short} codebase map`, `# ${full} codebase map`].includes(line.toLowerCase()),
+			),
+	);
+	if (maps.length !== 1) return;
+	const revisions = [...maps[0].matchAll(/^Indexed commit: ([^\r\n]+)\r?$/gm)];
+	const revision = revisions.length === 1 && revisions[0][1];
+	if (revision && SHA.test(revision)) return revision.toLowerCase();
+}
+
+function editedPaths(input, client, root) {
+	let paths;
+	if (client === "codex") {
+		if (input.tool_name !== "apply_patch") return [];
+		const patch = input.tool_input?.command;
+		const succeeded = responseText(input.tool_response).some((text) =>
+			/^Success\. Updated the following files:/m.test(text),
+		);
+		if (!succeeded || typeof patch !== "string" || !patch.startsWith("*** Begin Patch\n"))
+			return [];
+		paths = [
+			...patch.matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/gm),
+		].map((match) => match[1]);
+	} else {
+		if (!["Edit", "Write", "MultiEdit"].includes(input.tool_name)) return [];
+		paths = [input.tool_input?.file_path];
+	}
+	if (paths.length > MAX_EDIT_PATHS) return [];
+	const inCheckout = paths.flatMap((path) => {
+		if (typeof path !== "string" || path.length > 512 || !MAPPED_FILE.test(path)) return [];
+		const absolute = resolve(input.cwd ?? root, path);
+		let parent;
+		try {
+			parent = realpathSync(dirname(absolute));
+		} catch {
+			return [];
+		}
+		const local = relative(root, join(parent, basename(absolute)));
+		if (!local || local === ".." || local.startsWith(`..${sep}`) || isAbsolute(local)) return [];
+		return [local];
+	});
+	return [...new Set(inCheckout)];
+}
+
+function worktreeBlob(path, remaining) {
+	let fd;
+	try {
+		fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	} catch (error) {
+		return error.code === "ENOENT" ? null : undefined;
+	}
+	try {
+		const before = fstatSync(fd);
+		if (!before.isFile() || before.size > remaining) return;
+		const bytes = Buffer.alloc(before.size);
+		if (readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length) return;
+		const after = fstatSync(fd);
+		if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) return;
+		return {
+			size: bytes.length,
+			oid: createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex"),
+		};
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function changedPaths(root, revision, paths, deadline, git) {
+	const comparisonDeadline = Math.min(deadline, performance.now() + 700);
+	const run = (...args) =>
+		git(
+			root,
+			Math.min(comparisonDeadline, performance.now() + 300),
+			"--literal-pathspecs",
+			...args,
+		);
+	try {
+		// Git reads tree and index metadata only. Hash raw regular-file bytes
+		// locally so checkout attributes cannot invoke an executable filter.
+		const tree = run("ls-tree", "-rz", revision, "--", ...paths);
+		const indexed = new Map(
+			tree
+				.split("\0")
+				.filter(Boolean)
+				.map((entry) => {
+					const tab = entry.indexOf("\t");
+					const [mode, type, oid] = entry.slice(0, tab).split(" ");
+					return [
+						entry.slice(tab + 1),
+						/^100(?:644|755)$/.test(mode) && type === "blob" && SHA.test(oid) ? oid : null,
+					];
+				}),
+		);
+		const added = paths.filter((path) => !indexed.has(path));
+		const visible = added.length
+			? new Set(
+					run("ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...added).split(
+						"\0",
+					),
+				)
+			: new Set();
+		let remaining = MAX_SOURCE_BYTES;
+		const changed = [];
+		for (const path of paths) {
+			if (performance.now() >= comparisonDeadline) return [];
+			const previous = indexed.get(path);
+			if (!previous && !visible.has(path)) continue;
+			const local = worktreeBlob(join(root, path), remaining);
+			if (local === undefined) continue;
+			remaining -= local?.size ?? 0;
+			if ((local?.oid ?? undefined) !== previous) changed.push(digest(path));
+		}
+		if (performance.now() >= comparisonDeadline) return [];
+		return changed;
+	} catch {
+		// A missing revision or failed comparison leaves the cue available for a later edit.
+		return [];
+	}
+}
+
+function validEntry(entry, now) {
+	return (
+		DIGEST.test(entry?.key ?? "") &&
+		Number.isFinite(entry.expires) &&
+		entry.expires > now &&
+		entry.expires <= now + STATE_TTL &&
+		(entry.revision === undefined || SHA.test(entry.revision)) &&
+		Array.isArray(entry.searches) &&
+		entry.searches.length <= MAX_SEARCHES &&
+		entry.searches.every((item) => typeof item === "string" && DIGEST.test(item)) &&
+		Array.isArray(entry.warned) &&
+		entry.warned.length <= MAX_WARNED &&
+		entry.warned.every((item) => typeof item === "string" && DIGEST.test(item))
+	);
+}
+
+/** Process local hook evidence without dispatching tools or retaining their payloads. */
+export function worktreeCue(
+	input,
+	{
+		client,
+		target,
+		binding,
+		repos = [],
+		stateDirectory,
+		structuralSearch,
+		deadline = Infinity,
+		git = gitBefore,
+		now = Date.now(),
+	},
+) {
+	const session = sessionKey(client, input.session_id);
+	if (!session || !binding || performance.now() >= deadline) return;
+	const event = input.hook_event_name;
+	const search = event === "PreToolUse" && structuralSearch;
+	const revision =
+		event === "PostToolUse" && input.tool_name === MAP_TOOL && mappedRevision(input, target, repos);
+	const paths = event === "PostToolUse" ? editedPaths(input, client, target.root) : [];
+	if (!search && !revision && !paths.length) return;
+	const key = digest(`${binding}\0${session}\0${target.root}\0${target.repo.toLowerCase()}`);
+
+	const context = updateWorktreeCueState(
+		stateDirectory,
+		(state) => {
+			if (state !== undefined && (state?.version !== 1 || !Array.isArray(state.entries))) return;
+			const entries = (state?.entries ?? [])
+				.filter((entry) => validEntry(entry, now))
+				.slice(0, MAX_SCOPES);
+			const existing = entries.find((entry) => entry.key === key);
+			const current = existing ? { ...existing } : { key, searches: [], warned: [] };
+			let notice;
+			if (revision) {
+				if (current.revision === revision) return;
+				current.revision = revision;
+				current.warned = [];
+			} else if (search) {
+				if (current.revision || current.searches.length >= MAX_SEARCHES) return;
+				const head = git(
+					target.root,
+					Math.min(deadline, performance.now() + 300),
+					"rev-parse",
+					"HEAD",
+				);
+				if (!SHA.test(head)) return;
+				const requested = digest(`${head}\0${search.tool}\0${search.symbol}`);
+				if (current.searches.includes(requested)) return;
+				current.searches = [...current.searches, requested];
+				notice = `For structural evidence on ${search.symbol}, try Pharaoh's ${search.tool}. The graph covers the indexed default branch. Use the current worktree for local changes.`;
+			} else {
+				if (!current.revision || current.warned.length >= MAX_WARNED) return;
+				const changed = changedPaths(target.root, current.revision, paths, deadline, git);
+				const unseen = changed.filter((path) => !current.warned.includes(path));
+				if (!unseen.length) return;
+				current.warned = [...current.warned, ...unseen].slice(0, MAX_WARNED);
+				notice = `The Pharaoh evidence consulted earlier reflects the indexed default branch at ${current.revision.slice(0, 12)}. This edited scope differs from that revision. Check the local diff or source before relying on that evidence.`;
+			}
+			if (performance.now() >= deadline) return;
+			current.expires = now + STATE_TTL;
+			return {
+				state: {
+					version: 1,
+					entries: [current, ...entries.filter((entry) => entry.key !== key)].slice(0, MAX_SCOPES),
+				},
+				context: notice,
+			};
+		},
+		now,
+	);
+	if (context) return { hookSpecificOutput: { hookEventName: event, additionalContext: context } };
+}

package/project-memory/hook-config.mjs

@@ -7,6 +7,7 @@ const EVENTS = {
 };
 const GLOBAL_MARKER = "# pharaoh-project-memory:user-v1";
 const LEGACY_MARKER = / # pharaoh-project-memory:[a-f0-9]{64}$/;
+const TOOL_EVENTS = ["PreToolUse", "PostToolUse"];
 
 function isObject(value) {
 	return value && typeof value === "object" && !Array.isArray(value);
@@ -33,14 +34,14 @@ function matchesUserHook(value) {
 }
 
 /** Keep unrelated handlers even when they share an event group with ours. */
-function replaceHooks(config, client, matches, command, installEvents = EVENTS[client]) {
+function replaceHooks(config, events, matches, additions) {
 	if (!isObject(config) || (config.hooks !== undefined && !isObject(config.hooks))) {
 		throw new Error("The existing hooks configuration is not a JSON object.");
 	}
 	const hooks = { ...config.hooks };
-	for (const event of EVENTS[client]) {
+	for (const event of events) {
 		const current = hooks[event];
-		const install = command && installEvents.includes(event);
+		const install = additions[event];
 		if (!install && (current === undefined || (Array.isArray(current) && !current.length)))
 			continue;
 		if (
@@ -54,7 +55,7 @@ function replaceHooks(config, client, matches, command, installEvents = EVENTS[c
 			if (rest.length === group.hooks.length) return [group];
 			return rest.length ? [{ ...group, hooks: rest }] : [];
 		});
-		if (install) kept.push({ hooks: [{ type: "command", command, timeout: 3 }] });
+		if (install) kept.push(install);
 		if (kept.length) hooks[event] = kept;
 		else delete hooks[event];
 	}
@@ -63,24 +64,50 @@ function replaceHooks(config, client, matches, command, installEvents = EVENTS[c
 		: { ...config, hooks };
 }
 
+function group(command, matcher) {
+	return { ...(matcher && { matcher }), hooks: [{ type: "command", command, timeout: 3 }] };
+}
+
 export function updateHooks(config, client, target, remove, hookPath, node = process.execPath) {
 	const marker = legacyMarker(client, target.root);
 	if (!remove && !hookPath) throw new Error("A pinned project memory hook is required.");
 	const command = remove
 		? null
 		: `${[node, hookPath, client, target.root, target.repo].map(shellWord).join(" ")} ${marker}`;
-	return replaceHooks(config, client, matchesLegacyHook(client, target.root), command);
+	const events = EVENTS[client];
+	const additions = command
+		? Object.fromEntries(events.map((event) => [event, group(command)]))
+		: {};
+	return replaceHooks(config, events, matchesLegacyHook(client, target.root), additions);
 }
 
-export function updateUserHooks(config, client, hookPath, node = process.execPath) {
-	const command = hookPath
-		? `${[node, hookPath, client, "--user"].map(shellWord).join(" ")} ${GLOBAL_MARKER}`
-		: null;
-	return replaceHooks(config, client, matchesUserHook, command, ["UserPromptSubmit"]);
+export function updateUserHooks(
+	config,
+	client,
+	hookPath,
+	node = process.execPath,
+	graphCues = false,
+) {
+	const additions = {};
+	if (hookPath) {
+		const command = (mode) =>
+			`${[node, hookPath, client, mode].map(shellWord).join(" ")} ${GLOBAL_MARKER}`;
+		additions.UserPromptSubmit = group(command("--user"));
+		if (graphCues) {
+			const graph = command("--graph");
+			const edit = client === "codex" ? "apply_patch" : "Edit|Write|MultiEdit";
+			additions.PreToolUse = group(graph, "^Bash$");
+			additions.PostToolUse = group(graph, `^(?:${edit}|mcp__pharaoh__get_codebase_map)$`);
+		}
+	}
+	const toolEvents = TOOL_EVENTS.filter(
+		(event) => additions[event] || hasHooks(config, [event], matchesUserHook),
+	);
+	return replaceHooks(config, [...EVENTS[client], ...toolEvents], matchesUserHook, additions);
 }
 
-function hasHooks(config, client, matches) {
-	return EVENTS[client].some((event) => {
+function hasHooks(config, events, matches) {
+	return events.some((event) => {
 		const groups = config?.hooks?.[event];
 		return (
 			Array.isArray(groups) &&
@@ -93,9 +120,9 @@ function hasHooks(config, client, matches) {
 }
 
 export function hasLegacyHooks(config, client, root) {
-	return hasHooks(config, client, matchesLegacyHook(client, root));
+	return hasHooks(config, EVENTS[client], matchesLegacyHook(client, root));
 }
 
 export function hasUserHooks(config, client) {
-	return hasHooks(config, client, matchesUserHook);
+	return hasHooks(config, [...EVENTS[client], ...TOOL_EVENTS], matchesUserHook);
 }

package/project-memory/hook-events.mjs

@@ -52,7 +52,7 @@ export function memoryReminder(repo) {
 	return {
 		hookSpecificOutput: {
 			hookEventName: "UserPromptSubmit",
-			additionalContext: `For work in ${repo}, use pharaoh_memory_recall if prior decisions may matter. Use pharaoh_memory_expand if you need the full record, and pharaoh_memory_capture for one supported candidate when the task permits. Mention memory only when it changes a decision.`,
+			additionalContext: `For work in ${repo}, call pharaoh_memory_recall before source inspection when prior decisions could matter. Use specific, non-sensitive terms. Use pharaoh_memory_expand only for needed evidence and pharaoh_memory_capture for one supported candidate when the user permits a write. Mention memory only if it changes a decision.`,
 		},
 	};
 }

package/project-memory/local.mjs

@@ -252,6 +252,35 @@ function recoverLock(path, now) {
 	return true;
 }
 
+function acquireLocalLock(directory, path, now) {
+	return (
+		acquireLock(directory, path, now) ??
+		(recoverLock(path, now) ? acquireLock(directory, path, now) : undefined)
+	);
+}
+
+/** Update only the bounded worktree cue metadata. Concurrent events can skip. */
+export function updateWorktreeCueState(directory, update, now = Date.now()) {
+	makePrivateDirectory(directory);
+	const release = acquireLocalLock(directory, join(directory, "worktree-cues.lock"), now);
+	if (!release) return;
+	try {
+		const path = join(directory, "worktree-cues.json");
+		const file = lstatSync(path, { throwIfNoEntry: false });
+		if (file && file.uid !== process.getuid?.()) return;
+		const before = file ? readJson(path) : undefined;
+		if (file && before === undefined) return;
+		const change = update(before);
+		if (!change) return;
+		const data = JSON.stringify(change.state);
+		if (Buffer.byteLength(data) > 8192) return;
+		atomicWrite(path, data);
+		return change.context;
+	} finally {
+		release();
+	}
+}
+
 /** Serialize local state transitions only; network operations never hold this lock. */
 export function turnStore(home = homedir(), now = Date.now) {
 	const directory = join(home, ".pharaoh", "project-memory-turns-v2");
@@ -276,9 +305,7 @@ export function turnStore(home = homedir(), now = Date.now) {
 		if (!TOKEN.test(key)) return;
 		const path = join(directory, `${key}.lock`);
 		const time = now();
-		const release =
-			acquireLock(directory, path, time) ??
-			(recoverLock(path, time) ? acquireLock(directory, path, time) : undefined);
+		const release = acquireLocalLock(directory, path, time);
 		if (!release) return onBusy?.();
 		try {
 			const stored = readJson(overlapPath(key));

package/project-memory/pharaoh-memory-hook.mjs

@@ -4,6 +4,8 @@ import { handleEvent, memoryReminder, skipMemoryPrompt } from "./hook-events.mjs
 import { readStdin } from "./local.mjs";
 import {
 	activeMemoryRuntime,
+	memoryClientRoot,
+	projectMemorySession,
 	readMemoryCredentials,
 	resolveMemoryHookTarget,
 } from "./user-target.mjs";
@@ -16,19 +18,49 @@ try {
 	const [client, root, repo] = process.argv.slice(2);
 	const input = await readStdin(1024 * 1024);
 	let result;
-	if (root === "--user") {
+	if (root === "--user" || root === "--graph") {
+		const reminder = root === "--user";
+		const event = input?.hook_event_name;
+		if (
+			reminder
+				? event !== "UserPromptSubmit" || skipMemoryPrompt(input.prompt)
+				: event !== "PreToolUse" && event !== "PostToolUse"
+		)
+			process.exit(0);
+		let structuralSearch;
+		if (event === "PreToolUse") {
+			if (input.tool_name !== "Bash") process.exit(0);
+			const { classifyBashGrep } = await import("./route-grep.mjs");
+			structuralSearch = classifyBashGrep(input.tool_input?.command);
+			if (!structuralSearch) process.exit(0);
+		}
 		const runtime = dirname(fileURLToPath(import.meta.url));
 		if (!activeMemoryRuntime(client, runtime)) process.exit(0);
-		if (input?.hook_event_name !== "UserPromptSubmit" || skipMemoryPrompt(input.prompt))
-			process.exit(0);
+		const { readHookPreferences } = await import("./preferences.mjs");
+		const choice = readHookPreferences()[client];
+		if (choice?.memory === false || (!reminder && choice?.graph === false)) process.exit(0);
+		const credentials = await readMemoryCredentials();
 		const eligible = await resolveMemoryHookTarget(
 			client,
 			input?.cwd,
-			await readMemoryCredentials(),
-			true,
+			credentials,
+			reminder,
 			deadline,
 		);
-		if (eligible && performance.now() < deadline) result = memoryReminder(eligible.repo);
+		if (!eligible || performance.now() >= deadline) process.exit(0);
+		if (reminder) result = memoryReminder(eligible.repo);
+		else {
+			const { worktreeCue } = await import("./graph-cues.mjs");
+			result = worktreeCue(input, {
+				client,
+				target: eligible,
+				binding: projectMemorySession(credentials),
+				repos: credentials?.repos,
+				stateDirectory: memoryClientRoot(),
+				structuralSearch,
+				deadline,
+			});
+		}
 	} else {
 		result = handleEvent(input, {
 			client,
@@ -38,7 +70,7 @@ try {
 			deadline,
 		});
 	}
-	if (result) process.stdout.write(JSON.stringify(result));
+	if (result && performance.now() < deadline) process.stdout.write(JSON.stringify(result));
 } catch {
 	// Project memory never blocks ordinary work or opens a continuation.
 } finally {

package/project-memory/preferences.d.mts

@@ -0,0 +1,12 @@
+export type MemoryHookClient = "claude-code" | "codex";
+export type HookPreferences = Partial<
+	Record<MemoryHookClient, { memory?: boolean; graph?: boolean }>
+>;
+export const MEMORY_HOOK_CLIENTS: readonly MemoryHookClient[];
+export function readHookPreferences(home?: string): HookPreferences;
+export function writeHookPreferences(
+	clients: HookPreferences,
+	home?: string,
+	expected?: HookPreferences,
+): void;
+export function resetHookPreferences(disable: boolean, home?: string): void;

package/project-memory/preferences.mjs

@@ -0,0 +1,70 @@
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { privateMemoryPath } from "./bundle.mjs";
+import { atomicWrite } from "./local.mjs";
+import { memoryClientRoot } from "./user-target.mjs";
+
+export const MEMORY_HOOK_CLIENTS = ["claude-code", "codex"];
+const FILE = "hook-preferences-v1.json";
+
+export function readHookPreferences(home = homedir()) {
+	const root = memoryClientRoot(home);
+	const path = join(root, FILE);
+	try {
+		privateMemoryPath(root, true);
+		if (privateMemoryPath(path, false).size > 1024)
+			throw new Error("Project memory preferences are too large.");
+		const { version, clients } = JSON.parse(readFileSync(path, "utf8"));
+		if (version !== 1 || !clients || typeof clients !== "object" || Array.isArray(clients))
+			throw new Error("Project memory preferences have an unknown format.");
+		for (const client of MEMORY_HOOK_CLIENTS) {
+			if (!Object.hasOwn(clients, client)) continue;
+			const choice = clients[client];
+			if (
+				!choice ||
+				typeof choice !== "object" ||
+				Array.isArray(choice) ||
+				["memory", "graph"].some(
+					(key) => Object.hasOwn(choice, key) && typeof choice[key] !== "boolean",
+				)
+			)
+				throw new Error("Project memory preferences contain an invalid choice.");
+		}
+		return clients;
+	} catch (error) {
+		if (error.code === "ENOENT") return {};
+		throw error;
+	}
+}
+
+export function writeHookPreferences(clients, home = homedir(), expected) {
+	const previous = readHookPreferences(home);
+	if (expected && JSON.stringify(expected) !== JSON.stringify(previous))
+		throw new Error("Project memory preferences changed while setup was asking.");
+	if (JSON.stringify(clients) === JSON.stringify(previous)) return;
+	const root = memoryClientRoot(home);
+	const path = join(root, FILE);
+	if (Object.keys(clients).length === 0) {
+		rmSync(path, { force: true });
+		return;
+	}
+	mkdirSync(root, { recursive: true, mode: 0o700 });
+	privateMemoryPath(root, true);
+	atomicWrite(path, `${JSON.stringify({ version: 1, clients })}\n`);
+}
+
+export function resetHookPreferences(disable, home = homedir()) {
+	if (typeof process.getuid !== "function") return;
+	const choices = readHookPreferences(home);
+	for (const client of MEMORY_HOOK_CLIENTS) {
+		const choice = choices[client];
+		if (disable) choices[client] = { memory: false, graph: false };
+		else if (choice) {
+			if (choice.memory === true) delete choice.memory;
+			if (choice.graph === true) delete choice.graph;
+			if (Object.keys(choice).length === 0) delete choices[client];
+		}
+	}
+	writeHookPreferences(choices, home);
+}

package/project-memory/setup.d.mts

@@ -1,14 +1,40 @@
-export function syncMemoryHooks(options?: {
-	credentials?: {
-		sse_url: string;
-		project_memory?: Array<{ repo: string; revision: string | null }>;
-		project_memory_status?: "unavailable";
-	};
-	clients?: string[];
-	enable?: boolean;
+type MemoryCredentials = {
+	sse_url: string;
+	project_memory?: Array<{ repo: string; revision: string | null }>;
+	project_memory_status?: "unavailable";
+};
+
+type MemoryHookChoices = {
+	accepted: string[];
+	declined: string[];
+	graphClients: string[];
+	notices: string[];
+	removeUnentitled?: boolean;
+};
+
+type MemoryHookSetup = {
+	credentials?: MemoryCredentials;
 	home?: string;
 	env?: NodeJS.ProcessEnv;
 	cwd?: string;
 	node?: string;
 	packageRoot?: URL;
-}): string[];
+};
+
+export function chooseMemoryHooks(options: {
+	credentials?: MemoryCredentials;
+	clients: string[];
+	requested?: boolean;
+	ask: (question: string, defaultAnswer: boolean) => Promise<boolean | null>;
+	home?: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<MemoryHookChoices>;
+
+export function applyMemoryHookChoices(
+	decision: MemoryHookChoices,
+	options?: MemoryHookSetup,
+): string[];
+
+export function syncMemoryHooks(
+	options?: MemoryHookSetup & { clients?: string[]; graphClients?: string[]; enable?: boolean },
+): string[];

package/project-memory/setup.mjs

@@ -4,6 +4,7 @@ import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { bundledHook, installMemoryBundle, packagedMemoryBundle } from "./bundle.mjs";
 import { hasLegacyHooks, hasUserHooks, updateHooks, updateUserHooks } from "./hook-config.mjs";
 import { atomicWrite, checkout, git, hasMemoryGit } from "./local.mjs";
+import { MEMORY_HOOK_CLIENTS, readHookPreferences, writeHookPreferences } from "./preferences.mjs";
 import {
 	legacySettingsPath,
 	matchingMemoryHint,
@@ -13,8 +14,6 @@ import {
 	readHookSettings,
 } from "./user-target.mjs";
 
-const CLIENTS = ["claude-code", "codex"];
-
 function userSettings(client, home, env) {
 	const codex = client === "codex";
 	const directory =
@@ -82,7 +81,7 @@ function migrateCheckout(client, target, notices) {
 	}
 }
 
-function syncUserHooks(client, home, env, target, hookPath, node, alreadyActive) {
+function syncUserHooks(client, home, env, target, hookPath, node, alreadyActive, graphCues) {
 	let known = Boolean(alreadyActive);
 	try {
 		const settings = inspectSettings(userSettings(client, home, env));
@@ -95,7 +94,7 @@ function syncUserHooks(client, home, env, target, hookPath, node, alreadyActive)
 				hasLegacyHooks(settings.config, client, target.root);
 			writeSettings(
 				settings,
-				updateUserHooks(settings.config, client, hookPath, node),
+				updateUserHooks(settings.config, client, hookPath, node, graphCues),
 				target,
 				checkoutHook,
 			);
@@ -110,10 +109,118 @@ function writeActivation(path, active) {
 	else rmSync(path, { force: true });
 }
 
+/** Resolve explicit choices only after a supported client's MCP registration. */
+export async function chooseMemoryHooks({
+	credentials,
+	clients,
+	requested = false,
+	ask,
+	home = homedir(),
+	env = process.env,
+}) {
+	const choices = { accepted: [], declined: [], graphClients: [], notices: [] };
+	if (typeof process.getuid !== "function") {
+		if (requested)
+			choices.notices.push("Pharaoh: project memory hooks need a POSIX client with system Git.");
+		return choices;
+	}
+	if (credentials?.project_memory_status === "unavailable") {
+		if (requested)
+			choices.notices.push(
+				"Pharaoh: project memory eligibility could not be checked. Retry setup to enable hooks.",
+			);
+		return choices;
+	}
+	if (!projectMemoryHint(credentials).length) {
+		if (requested) choices.notices.push("Pharaoh: this session has no project memory hook grant.");
+		return credentials ? { ...choices, removeUnentitled: true } : choices;
+	}
+	if (!clients.length || !hasMemoryGit) {
+		if (requested && !hasMemoryGit)
+			choices.notices.push("Pharaoh: project memory hooks need a POSIX client with system Git.");
+		return choices;
+	}
+	const previous = readHookPreferences(home);
+	const active = readActiveMemoryClients(home);
+	const next = { ...previous };
+	for (const client of MEMORY_HOOK_CLIENTS) {
+		if (!clients.includes(client)) continue;
+		const label = client === "codex" ? "Codex" : "Claude Code";
+		let config;
+		try {
+			config = inspectSettings(userSettings(client, home, env)).config;
+		} catch {
+			// An unreadable settings file cannot establish a previous installation.
+		}
+		if (client === "claude-code" && config?.disableAllHooks === true) continue;
+		const choice = { ...previous[client] };
+		const memoryHook =
+			active[client] &&
+			hasUserHooks({ hooks: { UserPromptSubmit: config?.hooks?.UserPromptSubmit } }, client);
+		if (requested) choice.memory = true;
+		else if (choice.memory !== false && (choice.memory !== true || !memoryHook)) {
+			const answer = await ask(
+				`Enable Pharaoh project memory hooks in ${label} (recommended)? [Y/n] `,
+				true,
+			);
+			if (answer === null) continue;
+			choice.memory = answer;
+			if (!answer && choice.graph === true) delete choice.graph;
+		}
+		if (choice.memory === true) {
+			let graphEnabled =
+				choice.graph === true &&
+				["PreToolUse", "PostToolUse"].every((event) =>
+					hasUserHooks({ hooks: { [event]: config?.hooks?.[event] } }, client),
+				);
+			if (requested || choice.graph === undefined || (choice.graph === true && !graphEnabled)) {
+				const answer = await ask(
+					`Enable advisory Pharaoh worktree cues in ${label}? [y/N] `,
+					false,
+				);
+				if (answer !== null) {
+					choice.graph = answer;
+					graphEnabled = answer;
+				}
+			}
+			choices.accepted.push(client);
+			if (graphEnabled) choices.graphClients.push(client);
+		} else {
+			choices.declined.push(client);
+		}
+		next[client] = choice;
+	}
+	writeHookPreferences(next, home, previous);
+	return choices;
+}
+
+/** Apply the outcome against the saved choices, which can change after the prompt. */
+export function applyMemoryHookChoices(decision, options = {}) {
+	const { accepted, declined, graphClients, removeUnentitled } = decision;
+	const notices = [...decision.notices];
+	if (removeUnentitled)
+		return [...notices, ...syncMemoryHooks({ ...options, clients: MEMORY_HOOK_CLIENTS })];
+
+	if (declined.length) {
+		const saved = readHookPreferences(options.home);
+		const clients = declined.filter((client) => saved[client]?.memory === false);
+		if (clients.length) notices.push(...syncMemoryHooks({ ...options, clients }));
+	}
+	if (accepted.length) {
+		const saved = readHookPreferences(options.home);
+		const clients = accepted.filter((client) => saved[client]?.memory === true);
+		const cues = graphClients.filter((client) => saved[client]?.graph === true);
+		if (clients.length)
+			notices.push(...syncMemoryHooks({ ...options, clients, graphClients: cues, enable: true }));
+	}
+	return notices;
+}
+
 /** Run only during setup or explicit cleanup of the local memory hooks. */
 export function syncMemoryHooks({
 	credentials,
-	clients = [],
+	clients = MEMORY_HOOK_CLIENTS,
+	graphClients = [],
 	enable = false,
 	home = homedir(),
 	env = process.env,
@@ -150,8 +257,8 @@ export function syncMemoryHooks({
 		}
 	}
 
-	for (const client of CLIENTS) {
-		if (enable && !clients.includes(client)) continue;
+	for (const client of MEMORY_HOOK_CLIENTS) {
+		if (!clients.includes(client)) continue;
 		const next = { ...active, [client]: digest };
 		try {
 			// Enable the replacement before swapping any settings, so failed
@@ -159,7 +266,16 @@ export function syncMemoryHooks({
 			const replacing = enable && active[client] !== digest;
 			if (replacing) writeActivation(activePath, next);
 			try {
-				syncUserHooks(client, home, env, target, installed, node, active[client]);
+				syncUserHooks(
+					client,
+					home,
+					env,
+					target,
+					installed,
+					node,
+					active[client],
+					graphClients.includes(client),
+				);
 			} catch (error) {
 				if (replacing) writeActivation(activePath, active);
 				throw error;
@@ -176,8 +292,16 @@ export function syncMemoryHooks({
 	}
 
 	// Deactivate loaded user hooks even if known settings could not be edited.
-	if (!enable && Object.keys(active).length) writeActivation(activePath, {});
-	for (const client of enable ? configured : CLIENTS) migrateCheckout(client, target, notices);
+	if (!enable) {
+		const remaining = Object.fromEntries(
+			Object.entries(active).filter(([client]) => !clients.includes(client)),
+		);
+		if (Object.keys(remaining).length !== Object.keys(active).length)
+			writeActivation(activePath, remaining);
+	}
+	for (const client of enable ? configured : clients) {
+		if (MEMORY_HOOK_CLIENTS.includes(client)) migrateCheckout(client, target, notices);
+	}
 	if (configured.length) {
 		notices.push(
 			"Pharaoh project memory reminders are set up for your eligible repositories. Start a new local conversation.",