@pharaoh-so/mcp 0.3.45 → 0.3.49

package/.mcp.json

@@ -2,7 +2,9 @@
 	"mcpServers": {
 		"pharaoh": {
 			"command": "npx",
-			"args": ["@pharaoh-so/mcp"]
+			"args": [
+				"@pharaoh-so/mcp@0.3.49"
+			]
 		}
 	}
 }

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to `@pharaoh-so/mcp` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.49] - 2026-10-20
+
+### Changed
+- Publish from the standalone public source repository with npm provenance, after the reviewed source passes its required checks.
+- Include the test runtime needed to validate the package independently.
+
+## [0.3.48] - 2026-10-20
+
+### Added
+- Compact Trace views for supporting MCP App clients, with expandable evidence, yellow bars and green success markers. Existing text results remain available.
+- The same static Trace resource before and after sign-in. Resource reads do not start device authentication, and view data comes only from authorized tool results.
+
+## [Unreleased]
+
+Security review of 2026-10-17 (findings SC-2, SC-6, SC-7, SC-8, SC-9). See README § Security for what the installer writes.
+
+### Changed
+- The interactive setup allow-lists Pharaoh's six read-only tools and `pharaoh_account` by full name in `~/.claude/settings.json`, only when that file already exists, and says so. It replaces the blanket `mcp__pharaoh` rule earlier versions wrote on every start, which also auto-approved account deletion and `pharaoh_admin`. Proxy starts no longer touch permissions.
+- Slash command files in `~/.claude/commands/` are written only when absent or Pharaoh's own (front-matter marker `# managed-by: pharaoh-mcp`, or the header and `$ARGUMENTS` footer of an earlier install). A user's file with the same name is kept and named in the output; symlinks are never followed.
+- `~/.pharaoh` is created `0700` and set to `0700` on every start, whichever path creates it first.
+- Every registration (`claude mcp add`, OpenClaw, the shipped `.mcp.json`) runs `npx @pharaoh-so/mcp@<the installed version>`. Upgrading is `npx @pharaoh-so/mcp@latest`; the interactive setup prints a hint when the registry has a newer version.
+- `package.json` `repository` names the building repository. The release workflow requests npm provenance when the source repository is public; private-source releases publish without it.
+
 ## [0.1.5] - 2026-03-24
 
 ### Added

package/README.md

@@ -129,10 +129,10 @@ npx @pharaoh-so/mcp --logout
 
 ### Custom Server
 
-For self-hosted Pharaoh instances or development, register manually:
+For self-hosted Pharaoh instances or development, register manually, pinned to a version (`npx @pharaoh-so/mcp --version` prints the one you have):
 
 ```bash
-claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp --server https://your-pharaoh-instance.com
+claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server https://your-pharaoh-instance.com
 ```
 
 ### Environment Variables
@@ -155,6 +155,33 @@ claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp --server https://your
 - 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.
 - 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).
+
+### What the installer writes on your machine
+
+`npx @pharaoh-so/mcp` in a terminal is the interactive setup. Every later proxy start (Claude Code launching the server) repeats the plugin, skill and command steps so a new version takes effect, and nothing else.
+
+| Path | Mode | When | What |
+|------|------|------|------|
+| `~/.pharaoh/` | `0700`, set again on every start | Always | Credentials and the Claude Code plugin marketplace |
+| `~/.pharaoh/credentials.json` | `0600` | After sign-in | Access token, refresh token, expiry |
+| `~/.pharaoh/claude-marketplace/` | — | `~/.claude/` exists | The one-plugin marketplace Claude Code installs as `pharaoh@pharaoh`: the skills and the Grep routing hook. Rewritten when the package version changes |
+| `~/.claude/commands/plan.md`, `review.md`, `sessions.md` | — | `~/.claude/` exists | Slash commands. A file is written only when it is absent or is Pharaoh's: it carries the front-matter comment `# managed-by: pharaoh-mcp`, or has the exact header and `$ARGUMENTS` footer of a Pharaoh command from 0.3.46 or earlier. Any other file with that name is yours: it is kept, a symlink is never followed, and the setup output names it. Rename your file to keep both |
+| `~/.claude.json` | — | Interactive setup | Removes earlier `pharaoh` entries, then `claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version>` |
+| `~/.claude/settings.json` | — | Interactive setup, and only if the file already exists | Adds to `permissions.allow`, each by full name: `mcp__pharaoh__get_codebase_map`, `mcp__pharaoh__get_module_context`, `mcp__pharaoh__search_functions`, `mcp__pharaoh__get_blast_radius`, `mcp__pharaoh__get_unused_code`, `mcp__pharaoh__pharaoh_recon`, `mcp__pharaoh__pharaoh_account`. The setup prints a line saying what it did. The proxy never creates this file and never touches it on a start |
+| `~/.openclaw/skills/`, `~/.openclaw/openclaw.json` | — | `~/.openclaw/` exists | Skills prefixed `pharaoh-`, and an `mcpServers.pharaoh` entry running `npx @pharaoh-so/mcp@<version>`. An entry that is not an `npx @pharaoh-so/mcp` command is left alone |
+
+Versions 0.3.46 and earlier wrote one rule, `mcp__pharaoh`, on every proxy start. That prefix auto-approved every Pharaoh tool, including account deletion and `pharaoh_admin`, so a prompt injection could run them without a human prompt. The next interactive setup replaces that rule with the list above; account deletion, `pharaoh_admin` and any tool not listed prompt before they run. To take the blanket rule out by hand, delete `mcp__pharaoh` from `permissions.allow`.
+
+### Pinned version and upgrades
+
+Every registration the setup writes runs the exact version that wrote it (`npx @pharaoh-so/mcp@<version>`). A new release on npm changes nothing on your machine until you upgrade:
+
+```bash
+npx @pharaoh-so/mcp@latest
+```
+
+This signs you in again, rewrites the registration with the new version and refreshes the plugin. The interactive setup asks the npm registry for the newest version and prints a one-line hint when there is one; proxy starts never check.
 
 ### Reporting Vulnerabilities
 

package/commands/review.md

@@ -33,12 +33,13 @@ Before merging any branch. Before opening any PR. When reviewing changes that to
    [ -n "$TARGET" ] || for b in origin/main origin/master main master; do
      git rev-parse -q --verify "$b" >/dev/null && TARGET=$b && break
    done
-   git merge-base HEAD "$TARGET"                                                       # prints the base commit: $BASE below
+   BASE=$(git merge-base HEAD "$TARGET") && echo "base: $BASE"
    ```
-   If no base comes out, stop and ask which branch this merges into. An empty base makes every diff below come out empty, and the review would report no changes.
+   If no base comes out, stop and ask which branch this merges into. An empty base makes every diff below come out empty, and the review would report no changes. If your shell doesn't keep variables between commands, set `BASE` to the printed commit at the start of each one.
 
 3. Collect the full changeset from the base:
    ```bash
+   : "${BASE:?no base: ask which branch this merges into}"   # stops here rather than diff HEAD against itself
    git diff --name-only "$BASE"...HEAD   # all changed files
    git diff --stat "$BASE"...HEAD        # summary stats
    git log --oneline "$BASE"..HEAD       # all commits on this branch
@@ -256,7 +257,7 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
 ### Auto-block triggers (any of these = BLOCK)
 
 - Any CRITICAL security finding (injection, broken access control, tenant isolation violation, secret exposure)
-- Unreachable exports in an application (new public code that nothing calls). In a library, exports are the public API: check each new one is documented or tested instead. Without reachability data (no Pharaoh, no PR Guard), raise it under SHIP WITH CHANGES, not BLOCK
+- Unreachable exports in an application (new public code that nothing calls). In a library, exports are the public API: check each new one is documented or tested instead. Without graph reachability data, a search can't prove nothing calls it: raise it under SHIP WITH CHANGES, not BLOCK
 - New circular dependencies between modules
 - HIGH regression risk without corresponding test coverage
 - **A MUST-bullet in `docs/VISION.md` is violated by this change** (without VISION.md being updated in the same PR with user approval)
@@ -275,7 +276,7 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
 ### SHIP triggers
 
 - No CRITICAL or confirmed IMPORTANT findings
-- All new exports are reachable (applications) or documented and tested (libraries)
+- All new exports are reachable (applications) or documented or tested (libraries)
 - Regression risk is LOW or MEDIUM with adequate test coverage
 - Spec alignment is clean or intentionally divergent with documentation
 

package/dist/backend.d.ts

@@ -15,7 +15,7 @@
  * resolves each tool call's handler at request-arrival time, so in-flight
  * calls complete against whichever backend started them.
  */
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, ClientCapabilities, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { DeviceFlowGateway } from "./gateway.js";
 /** The contract ProxyServer uses to delegate tool handling. */
 export interface Backend {
@@ -32,6 +32,8 @@ export interface Backend {
      * act on. Backends without a supervisor loop (AuthRequiredBackend) omit this.
      */
     waitForExit?(): Promise<void>;
+    /** Return an unstarted replacement only if the negotiated UI support changed. */
+    withClientCapabilities?(capabilities: ClientCapabilities): Backend;
 }
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
@@ -75,7 +77,9 @@ export declare class SseProxyBackend implements Backend {
     private transport;
     private stopped;
     private reconnectPromise;
-    constructor(sseUrl: string, token: string);
+    private readonly clientCapabilities;
+    constructor(sseUrl: string, token: string, capabilities?: ClientCapabilities);
+    withClientCapabilities(capabilities: ClientCapabilities): Backend;
     start(): Promise<void>;
     /**
      * Expose the long-running reconnect loop so a supervisor can await it.

package/dist/backend.js

@@ -19,6 +19,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { loadBundledCatalog } from "./catalog.js";
 import { classifySSEError, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { TRACE_MIME_TYPE } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
@@ -143,9 +144,23 @@ export class SseProxyBackend {
     transport = null;
     stopped = false;
     reconnectPromise = null;
-    constructor(sseUrl, token) {
+    clientCapabilities;
+    constructor(sseUrl, token, capabilities = {}) {
         this.sseUrl = sseUrl;
         this.token = token;
+        // The proxy can deliver only this static UI extension. Advertising other
+        // capabilities (sampling, elicitation, etc.) would promise unsupported RPCs.
+        const ui = capabilities.extensions?.["io.modelcontextprotocol/ui"];
+        this.clientCapabilities =
+            Array.isArray(ui?.mimeTypes) && ui.mimeTypes.includes(TRACE_MIME_TYPE)
+                ? { extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [TRACE_MIME_TYPE] } } }
+                : {};
+    }
+    withClientCapabilities(capabilities) {
+        const next = new SseProxyBackend(this.sseUrl, this.token, capabilities);
+        return JSON.stringify(next.clientCapabilities) === JSON.stringify(this.clientCapabilities)
+            ? this
+            : next;
     }
     async start() {
         if (this.client)
@@ -169,9 +184,29 @@ export class SseProxyBackend {
         return this.reconnectPromise ?? Promise.resolve();
     }
     async connectOnce() {
-        this.transport = createSSETransport(this.sseUrl, this.token);
-        this.client = new Client({ name: "pharaoh-proxy", version: getPackageVersion() }, { capabilities: {} });
-        await this.client.connect(this.transport);
+        const transport = createSSETransport(this.sseUrl, this.token);
+        const client = new Client({ name: "pharaoh-proxy", version: getPackageVersion() }, { capabilities: this.clientCapabilities });
+        this.transport = transport;
+        this.client = client;
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            // A failed warm capability handshake must not leave EventSource's
+            // automatic retries alive beside the previous backend.
+            await client.close().catch(() => {
+                process.stderr.write("Pharaoh: failed SSE connection cleanup\n");
+            });
+            if (this.transport === transport)
+                this.transport = null;
+            if (this.client === client)
+                this.client = null;
+            // Initial and negotiated connects need the same typed auth recovery
+            // as reconnects. Generic failures still surface to the caller.
+            if (error instanceof Error)
+                classifySSEError(error);
+            throw error;
+        }
     }
     /** Wait for the current transport to close, then decide what to do. */
     waitForClose() {
@@ -204,6 +239,8 @@ export class SseProxyBackend {
         const delay = BACKOFF_MS[attempt - 1];
         process.stderr.write(`Pharaoh: reconnecting in ${delay / 1000}s (attempt ${attempt}/${BACKOFF_MS.length})...\n`);
         await sleep(delay);
+        if (this.stopped)
+            return;
         await this.connectOnce();
         process.stderr.write("Pharaoh: reconnected\n");
     }
@@ -213,6 +250,8 @@ export class SseProxyBackend {
         while (!this.stopped) {
             try {
                 await this.waitForClose();
+                if (this.stopped)
+                    return;
                 attempt++;
                 if (attempt > BACKOFF_MS.length) {
                     process.stderr.write("Pharaoh: max reconnect attempts reached — exiting\n");

package/dist/credentials.d.ts

@@ -46,6 +46,15 @@ export declare function writeCredentials(creds: Credentials, path?: string): voi
  * @throws If the lock stays held for LOCK_WAIT_MS, or a stale lock can't be removed.
  */
 export declare function acquireCredentialsLock(path?: string): Promise<() => void>;
+/**
+ * Create `~/.pharaoh` with mode 0700 and set that mode again if it already
+ * exists. The one place the directory is created, whichever path gets there
+ * first (credentials or the Claude Code plugin marketplace), so it is never
+ * left world-readable (security review SC-8).
+ *
+ * @param dir - The directory (defaults to `~/.pharaoh`).
+ */
+export declare function ensurePharaohHome(dir?: string): void;
 /** Delete the credential file. No-op if it doesn't exist. */
 export declare function deleteCredentials(path?: string): void;
 /**

package/dist/credentials.js

@@ -6,7 +6,7 @@
  * refreshes take a lock (acquireCredentialsLock) and writes are atomic.
  */
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -147,12 +147,21 @@ function lockAgeMs(lockPath) {
         return 0; // released between our create attempt and this stat — retry immediately
     }
 }
-/** Create the credentials directory (0700) if it doesn't exist. */
+/**
+ * Create `~/.pharaoh` with mode 0700 and set that mode again if it already
+ * exists. The one place the directory is created, whichever path gets there
+ * first (credentials or the Claude Code plugin marketplace), so it is never
+ * left world-readable (security review SC-8).
+ *
+ * @param dir - The directory (defaults to `~/.pharaoh`).
+ */
+export function ensurePharaohHome(dir = join(homedir(), ".pharaoh")) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+}
+/** Create the directory holding a credentials file (0700). */
 function ensureDir(path) {
-    const dir = dirname(path);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-    }
+    ensurePharaohHome(dirname(path));
 }
 /** Delete the credential file. No-op if it doesn't exist. */
 export function deleteCredentials(path = CREDENTIALS_PATH) {

package/dist/index.js

@@ -17,11 +17,12 @@ import { AuthRequiredBackend, createSseBackend } from "./backend.js";
 import { deleteCredentials, readCredentials, writeCredentials, } from "./credentials.js";
 import { createGateway } from "./gateway.js";
 import { formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
-import { runInstallSkills } from "./install-skills.js";
+import { allowReadTools, describeAllowReadTools, formatKeptCommands, runInstallSkills, } from "./install-skills.js";
 import { handleRefreshFailure, tryMidSessionRefresh } from "./lifecycle.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { startInAuthRequiredMode, startInSseMode } from "./proxy-server.js";
 import { loadAndRefresh } from "./refresh.js";
+import { fetchLatestVersion, getPackageVersion, isNewerVersion, UPGRADE_COMMAND, } from "./version.js";
 const BANNER = [
     "",
     "  ___  _  _   _   ___    _    ___  _  _ ",
@@ -90,8 +91,22 @@ async function main() {
         process.stderr.write("  Setting up...");
         const { runSetup } = await import("./setup.js");
         runSetup({ silent: true });
-        runInstallSkills(undefined, { silent: true });
+        const { keptCommands } = runInstallSkills(undefined, { silent: true });
         process.stderr.write(" done.\n");
+        // Two things the user must hear about: their settings.json (the only
+        // place this setup edits permissions, never a silent start) and any
+        // command file of theirs that was left alone.
+        printLines(describeAllowReadTools(allowReadTools()));
+        const kept = formatKeptCommands(keptCommands);
+        if (kept)
+            printLines(kept);
+        // 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();
+        const running = getPackageVersion();
+        if (latest && isNewerVersion(latest, running)) {
+            printLines(`Pharaoh: ${latest} is available (this is ${running}). Upgrade: ${UPGRADE_COMMAND}`);
+        }
         printLines("", "Pharaoh is ready. Try these in a new Claude Code conversation:", "", '  "What modules does this codebase have?"', '  "Search for functions related to authentication"', '  "What breaks if I change this file?"', "");
         process.exit(0);
     }

package/dist/inspect.js

@@ -11,6 +11,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { loadBundledCatalog } from "./catalog.js";
+import { registerTraceResource } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
 const INSPECT_MSG = "This is Pharaoh's inspection server for directory listings. " +
     "Connect to https://mcp.pharaoh.so for actual usage.";
@@ -29,5 +30,6 @@ export async function runInspect() {
     server.setRequestHandler(CallToolRequestSchema, async () => ({
         content: [{ type: "text", text: INSPECT_MSG }],
     }));
+    registerTraceResource(server);
     await server.connect(new StdioServerTransport());
 }

package/dist/install-skills.d.ts

@@ -1,3 +1,4 @@
+import { type ClaudeCli } from "./setup.js";
 /**
  * Detect whether OpenClaw is installed by checking for ~/.openclaw/.
  *
@@ -5,8 +6,6 @@
  * @returns True if ~/.openclaw/ exists.
  */
 export declare function detectOpenClaw(home?: string): boolean;
-/** Runs one `claude` CLI command; true on success. */
-type ClaudeCli = (args: string[]) => boolean;
 /**
  * Uninstall Pharaoh's Claude Code plugin: through the CLI, then the local
  * marketplace directory and any pre-marketplace install.
@@ -15,6 +14,22 @@ type ClaudeCli = (args: string[]) => boolean;
  * @param claude - `claude` CLI runner (defaults to the real CLI for `home`).
  */
 export declare function uninstallClaudePlugin(home?: string, claude?: ClaudeCli): void;
+/**
+ * Marker the installer writes into the front-matter of every command file it
+ * installs, as a YAML comment Claude Code ignores. A file in
+ * `~/.claude/commands/` is rewritten only when it is Pharaoh's: it carries
+ * this marker, or the exact header and `$ARGUMENTS` footer every installer
+ * before the marker shipped. Any other file with the same name is the user's
+ * and is left alone (security review SC-7).
+ */
+export declare const PHARAOH_COMMAND_MARKER = "# managed-by: pharaoh-mcp";
+/**
+ * The one-line notice for command files the installer left alone, or null
+ * when there were none.
+ *
+ * @param kept - File names from `runInstallSkills().keptCommands`.
+ */
+export declare function formatKeptCommands(kept: readonly string[]): string | null;
 /**
  * Install bundled skills to `~/.openclaw/skills/` with the same `pharaoh-`
  * prefix that Claude Code installs use. Keeps naming consistent across both
@@ -28,26 +43,64 @@ export declare function uninstallClaudePlugin(home?: string, claude?: ClaudeCli)
  */
 export declare function installSkills(home?: string): number;
 /**
- * Read ~/.openclaw/openclaw.json, add the Pharaoh MCP server under `mcpServers`,
- * and write it back. Creates the file if it does not exist. Does NOT overwrite
- * an existing `pharaoh` entry — skips if already present.
+ * Read ~/.openclaw/openclaw.json, set the Pharaoh MCP server under `mcpServers`
+ * to `npx @pharaoh-so/mcp@<this version>`, and write it back. Creates the file
+ * if it does not exist. An existing `pharaoh` entry is re-pinned when it is an
+ * `npx @pharaoh-so/mcp` command (extra arguments kept) and left alone when it
+ * is anything else.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns True if the config was written/updated, false if pharaoh was already present.
+ * @returns True if the config was written, false if it was already current or is not ours.
  */
 export declare function mergeOpenClawConfig(home?: string): boolean;
 /**
- * Main entry point for --install-skills.
+ * Rules the interactive setup adds to `permissions.allow` in
+ * ~/.claude/settings.json: the six read-only tools and `pharaoh_account`,
+ * each by full name. Never a prefix rule — `mcp__pharaoh` also auto-approves
+ * account deletion and `pharaoh_admin`, so a prompt injection could run them
+ * with no human in the loop (security review SC-6). Those tools keep prompting.
+ */
+export declare const PHARAOH_ALLOW_RULES: readonly string[];
+/** What `allowReadTools` did to ~/.claude/settings.json. */
+export type AllowReadToolsResult = "added" | "migrated" | "current" | "no-settings" | "error";
+/**
+ * Add `PHARAOH_ALLOW_RULES` to `permissions.allow` in ~/.claude/settings.json,
+ * replacing the blanket `mcp__pharaoh` rule an earlier version wrote. Runs
+ * only from the interactive setup, which prints what happened; never on a
+ * proxy start. Never creates the file: with no settings.json the tools
+ * simply prompt on first use.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @returns "added" or "migrated" when the file was written, "current" when
+ *   nothing was missing, "no-settings" when there is no file, "error" when
+ *   the file is not valid JSON (left untouched).
+ */
+export declare function allowReadTools(home?: string): AllowReadToolsResult;
+/**
+ * The line the interactive setup prints for an `allowReadTools` result, so
+ * the user always learns what was done to their settings.
+ *
+ * @param result - What `allowReadTools` returned.
+ */
+export declare function describeAllowReadTools(result: AllowReadToolsResult): string;
+/** What `runInstallSkills` wants the caller to tell the user. */
+export interface InstallResult {
+    /** Files in ~/.claude/commands/ left as they were because they are not Pharaoh's. */
+    keptCommands: string[];
+}
+/**
+ * Main entry point for --install-skills, also run on every proxy start.
  *
  * Detection priority: Claude Code > OpenClaw > manual instructions.
- * Installs to all detected platforms (a user may use both).
+ * Installs to all detected platforms (a user may use both). Never touches
+ * Claude Code permissions: that is `allowReadTools`, interactive setup only.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @param options.silent - Print nothing (the interactive setup prints its own summary).
  * @param options.claude - `claude` CLI runner (defaults to the real CLI for `home`).
+ * @returns What was kept, for the caller's own summary.
  */
 export declare function runInstallSkills(home?: string, options?: {
     silent?: boolean;
     claude?: ClaudeCli;
-}): void;
-export {};
+}): InstallResult;