@pharaoh-so/mcp 0.3.59 → 0.3.60

package/.mcp.json

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

package/CHANGELOG.md

@@ -26,6 +26,11 @@ 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.60] - 2026-11-05
+
+### Added
+- When it connects, the proxy tells Pharaoh what your agent's instruction files say about it: whether `~/.claude/CLAUDE.md` holds the line setup suggests, mentions Pharaoh another way, doesn't, or is missing, and whether setup's block is still there. In Claude Code started at a git repo's root, the same for the project's `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md` or `AGENTS.md`. Only those values are sent, never file text. A file over 64 KB, or one that isn't a regular file or can't be read, counts as unknown. Pharaoh uses this to learn whether the line leads agents to use it (privacy policy § 9, connection records).
+
 ## [0.3.59] - 2026-11-04
 
 ### Changed

package/README.md

@@ -152,10 +152,11 @@ claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server ht
 - Credentials are stored with restrictive file permissions (`0600` — owner-read/write only)
 - Authentication uses the [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628) device authorization flow — no secrets are embedded in the package
 - All communication with the Pharaoh server uses HTTPS/TLS
-- The proxy never reads or sends your local files. Pharaoh reads your code from GitHub through its GitHub App, maps it into a knowledge graph of structural metadata (function names, file paths, dependency relationships), and deletes the clone when mapping ends.
+- The proxy never sends your code or the text of any file. Pharaoh reads your code from GitHub through its GitHub App, maps it into a knowledge graph of structural metadata (function names, file paths, dependency relationships), and deletes the clone when mapping ends.
+- From 0.3.60, when it connects, the proxy also tells Pharaoh whether your `~/.claude/CLAUDE.md` holds the line setup suggests, mentions Pharaoh another way, doesn't, or is missing, and whether setup's block is still in it. In Claude Code started at a git repo's root, it does the same for that project's `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md` and `AGENTS.md`. Only these values are sent, never the files' text.
 - Tokens expire after 7 days and are refreshed automatically
 - Only use trusted server URLs — the proxy sends your auth token to the configured server
-- No telemetry. The proxy's only network calls are the device flow, token refresh, the MCP connection, and one registry lookup during interactive setup (below).
+- The proxy's only network calls are the device flow, token refresh, the MCP connection, and one registry lookup during interactive setup (below). Over the MCP connection it tells Pharaoh which client it serves (the name and version that client reports) and whether Pharaoh's Claude Code plugin is enabled, which it reads from `~/.claude/settings.json`. Nothing else about your machine is sent.
 
 ### What the installer writes on your machine
 

package/dist/backend.d.ts

@@ -17,6 +17,7 @@
  */
 import type { CallToolResult, ClientCapabilities, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { DeviceFlowGateway } from "./gateway.js";
+import type { InstructionState, ManagedBlockState } from "./install-skills.js";
 /**
  * Notification that tells Pharaoh which client the proxy serves. Pharaoh sees
  * the proxy itself as `pharaoh-proxy`; this lands on the session's row.
@@ -32,6 +33,12 @@ export type DownstreamClient = {
     };
     /** Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. */
     plugin: "enabled" | "disabled" | "absent";
+    /** What the client's instruction files say about Pharaoh (install-skills.ts instructionStates); never their text. */
+    instructions?: {
+        user: InstructionState;
+        managed: ManagedBlockState;
+        project: InstructionState;
+    };
 };
 /** The contract ProxyServer uses to delegate tool handling. */
 export interface Backend {

package/dist/install-skills.d.ts

@@ -87,6 +87,19 @@ export declare function allowReadTools(home?: string): AllowReadToolsResult;
 export declare function describeAllowReadTools(result: AllowReadToolsResult): string;
 /** What the interactive setup asks before writing the line. */
 export declare const CLAUDE_MD_QUESTION = "Pharaoh: add one line to ~/.claude/CLAUDE.md so Claude checks Pharaoh before searching your code?\n  \"In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists.\"\n[Y/n] ";
+/** What an instruction file says about Pharaoh: the suggested line, another mention, none, no file, or unreadable. */
+export type InstructionState = "exact" | "mention" | "none" | "missing" | "unknown";
+/** Whether the block setup wrote into ~/.claude/CLAUDE.md is there and holds the current line. */
+export type ManagedBlockState = "current" | "stale" | "absent" | "unknown";
+/**
+ * The instruction state the proxy reports for its client. Project files only
+ * for clients known to start the proxy in the project folder. Never throws.
+ */
+export declare function instructionStates(clientName: string | undefined, cwd?: string, home?: string): {
+    user: InstructionState;
+    managed: ManagedBlockState;
+    project: InstructionState;
+};
 /** What `offerClaudeMdLine` did; `describeClaudeMdOutcome` words it. */
 export type ClaudeMdOutcome = "added" | "updated" | "declined" | "kept" | "failed" | "current" | "answered" | "cancelled" | "no-terminal" | "no-claude";
 /**

package/dist/install-skills.js

@@ -6,9 +6,9 @@
  * and OpenClaw skills in ~/.openclaw/skills/. Also merges the Pharaoh MCP
  * server config into OpenClaw.
  */
-import { closeSync, constants, cpSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { closeSync, constants, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensurePharaohHome } from "./credentials.js";
 import { CLAUDE_CLI_SETUP_URL, claudeCliFor } from "./setup.js";
@@ -765,6 +765,111 @@ function readClaudeMd(home) {
     const current = text.slice(block.body, block.to) === `${PHARAOH_CLAUDE_MD_LINE}\n`;
     return { state: current ? "current" : "stale", path, text, block };
 }
+/** A CLAUDE.md is a few KB; anything bigger reads as "unknown" instead of slowing initialize. */
+const INSTRUCTION_READ_CAP = 64 * 1024;
+/**
+ * A project's instruction files, read only for clients confirmed to start the
+ * proxy in the project folder (Claude Code 2.1.310 does: probed 2026-11-04).
+ */
+const PROJECT_INSTRUCTION_FILES = [
+    "CLAUDE.md",
+    "CLAUDE.local.md",
+    join(".claude", "CLAUDE.md"),
+    "AGENTS.md",
+];
+const PROJECT_CWD_CLIENTS = new Set(["claude-code"]);
+/**
+ * Up to `cap` bytes of a regular file, read from the descriptor that was
+ * checked, so a FIFO or device swapped in can't block `initialize`. A symlink
+ * is followed: only a state is derived from what it points at.
+ *
+ * @returns The file's text, wrapped so no content can read as a state;
+ *   "missing" when there's no file; "unknown" when it's over the cap, not a
+ *   regular file, or unreadable
+ */
+function readBoundedText(path, cap = INSTRUCTION_READ_CAP) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "unknown";
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return "unknown";
+        const buf = Buffer.alloc(cap + 1);
+        let length = 0;
+        while (length <= cap) {
+            const n = readSync(fd, buf, length, cap + 1 - length, null);
+            if (n === 0)
+                break;
+            length += n;
+        }
+        return length > cap ? "unknown" : { text: buf.toString("utf-8", 0, length) };
+    }
+    catch {
+        return "unknown";
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Whether `text` holds the suggested line, otherwise mentions Pharaoh, or neither. */
+function classifyInstructionText(text) {
+    if (text.includes(PHARAOH_CLAUDE_MD_LINE))
+        return "exact";
+    return /\bpharaoh\b/i.test(text) ? "mention" : "none";
+}
+/** What ~/.claude/CLAUDE.md says about Pharaoh, and whether setup's block is there and current. */
+function userInstructionState(home = homedir()) {
+    const file = readBoundedText(join(home, ".claude", "CLAUDE.md"));
+    if (file === "missing")
+        return { user: "missing", managed: "absent" };
+    if (file === "unknown")
+        return { user: "unknown", managed: "unknown" };
+    const { text } = file;
+    const block = findClaudeMdBlock(text);
+    const managed = block === null
+        ? "absent"
+        : block === "broken"
+            ? "unknown"
+            : text.slice(block.body, block.to) === `${PHARAOH_CLAUDE_MD_LINE}\n`
+                ? "current"
+                : "stale";
+    return { user: classifyInstructionText(text), managed };
+}
+/**
+ * The strongest state across a project's instruction files: any exact line,
+ * then any mention, then any unreadable file, then a file without a mention.
+ * "unknown" outside a git repository's root or in the home folder.
+ */
+function projectInstructionState(cwd, home = homedir()) {
+    if (resolve(cwd) === resolve(home) || !existsSync(join(cwd, ".git")))
+        return "unknown";
+    const states = PROJECT_INSTRUCTION_FILES.map((file) => {
+        const read = readBoundedText(join(cwd, file));
+        return typeof read === "string" ? read : classifyInstructionText(read.text);
+    });
+    return (["exact", "mention", "unknown", "none"].find((s) => states.includes(s)) ?? "missing");
+}
+/**
+ * The instruction state the proxy reports for its client. Project files only
+ * for clients known to start the proxy in the project folder. Never throws.
+ */
+export function instructionStates(clientName, cwd, home = homedir()) {
+    try {
+        // process.cwd() throws when the folder was deleted: inside the try, so it reads as unknown.
+        const project = clientName && PROJECT_CWD_CLIENTS.has(clientName)
+            ? projectInstructionState(cwd ?? process.cwd(), home)
+            : "unknown";
+        return { ...userInstructionState(home), project };
+    }
+    catch {
+        return { user: "unknown", managed: "unknown", project: "unknown" };
+    }
+}
 /**
  * Offer the Pharaoh-first line in ~/.claude/CLAUDE.md. Interactive setup only,
  * never a proxy start. Asks only when the block is absent and the user hasn't

package/dist/proxy-server.js

@@ -27,7 +27,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { AuthRequiredBackend, createSseBackend, } from "./backend.js";
 import { loadBundledCatalog } from "./catalog.js";
 import { createGateway } from "./gateway.js";
-import { claudePluginState } from "./install-skills.js";
+import { claudePluginState, instructionStates } from "./install-skills.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { registerTraceResource } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
@@ -70,6 +70,7 @@ export class ProxyServer {
             const downstream = {
                 client: { name: info?.name, version: info?.version },
                 plugin: claudePluginState(),
+                instructions: instructionStates(info?.name),
             };
             this.downstream = downstream;
             this.clientCapabilities = this.server.getClientCapabilities() ?? {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.59",
+	"version": "0.3.60",
 	"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",