phaedo-mcp 0.3.0 → 0.3.2

package/install.mjs

@@ -35,6 +35,18 @@ const CAPTURE_HOOK_PATH = join(BASE_DIR, 'hooks', 'session-end.mjs');
 const ENTRY_KEY = 'phaedo';
 const HOOK_MARKER = 'hooks/session-start.mjs';         // identifies our SessionStart entry
 const CAPTURE_HOOK_MARKER = 'hooks/session-end.mjs';   // identifies our SessionEnd capture entry
+// The same capture, run on Stop (end of each turn) for sessions that stay open for days
+// (the desktop app's) — throttled per session inside the hook, so most Stops cost one read.
+const STOP_CAPTURE_HOOK_PATH = join(BASE_DIR, 'hooks', 'stop-capture.mjs');
+const STOP_CAPTURE_HOOK_MARKER = 'hooks/stop-capture.mjs';
+const SHIP_HOOK_PATH = join(BASE_DIR, 'hooks', 'pre-ship.mjs');
+const SHIP_HOOK_MARKER = 'hooks/pre-ship.mjs';           // identifies our ship-consult entries
+// The ship hook (consult before a merge / deploy / phone build) runs on four Bash events:
+// before the command, when a prompt is shown (the evidence a person was asked), and after
+// it ran or failed (to record that person's yes). Its own budget is 12s; the timeout is
+// the backstop.
+export const SHIP_HOOK_EVENTS = ['PreToolUse', 'PermissionRequest', 'PostToolUse', 'PostToolUseFailure'];
+const SHIP_HOOK_ENTRY = { matcher: 'Bash', timeout: 15 };
 
 // ── Client registry ──────────────────────────────────────────────────────────
 // Every supported client stores MCP servers as a top-level `mcpServers` object,
@@ -74,7 +86,13 @@ export function serverEntry({ nodePath = process.execPath, serverPath = SERVER_P
   return entry;
 }
 
-// ── Consult model judge config (on by default) ────────────────────────────────
+// ── Consult model judge config (OFF by default — opt in) ──────────────────────
+// Was on by default. Measured 2026-10-18 on the dev Mac against the same cached profile:
+// llama3.1:8b answered a $12k IRREVERSIBLE payment `clarify 0.9` on one run and
+// `proceed_with_note 0.9` on the next — flipping between runs, toward proceeding, with
+// high confidence both times — where the rule engine says `clarify` every time. A judge
+// that can talk itself into a payment does not get to be the default. Opt in with
+// --model-judge (auto-detect) or --consult-model <id> (pin).
 // The MCP server runs the consult model judge when PHAEDO_CONSULT_MODEL is set;
 // it falls back to the local rule engine if the model/Ollama isn't there, so
 // defaulting it ON is safe. We write a LOCAL endpoint only (privacy-clean); a
@@ -88,15 +106,21 @@ export function buildConsultEnv({ model = DEFAULT_CONSULT_MODEL, url = DEFAULT_C
 }
 
 // Probe local Ollama so "on by default" works with whatever model the user has.
-// Picks the first installed general-purpose model (skips the phaedo extraction
-// fine-tune). Falls back to the default string + reachable:false on any failure.
+// Prefers the default when it is installed, else the first installed CHAT model —
+// skipping the phaedo extraction fine-tunes and embedding models. An embedding model
+// cannot answer a chat prompt: `nomic-embed-text` was picked on the dev Mac (it sorts
+// before llama3.1:8b), every judge call failed in ~15 ms and fell back to the rules,
+// and the installer kept printing "model judge ON" for a judge that had never run.
+// Falls back to the default string + reachable:false on any failure.
+const NOT_A_JUDGE = /phaedo|extract|embed|nomic|bge|minilm|mxbai|arctic|e5-|gte-|rerank/i;
 export async function detectConsultModel({ url = DEFAULT_CONSULT_URL, fallback = DEFAULT_CONSULT_MODEL, fetchImpl = globalThis.fetch } = {}) {
   try {
     const res = await fetchImpl(`${url.replace(/\/$/, '')}/api/tags`, { signal: AbortSignal.timeout(1500) });
     if (!res.ok) return { model: fallback, reachable: false, hadModels: false };
     const data = await res.json();
     const names = (data.models || []).map((m) => m.name || m.model).filter(Boolean);
-    const general = names.find((n) => !/phaedo|extract/i.test(n));
+    const bare = (n) => String(n).replace(/:latest$/, '');
+    const general = names.find((n) => bare(n) === bare(fallback)) || names.find((n) => !NOT_A_JUDGE.test(n));
     return { model: general || fallback, reachable: true, hadModels: names.length > 0, picked: !!general };
   } catch {
     return { model: fallback, reachable: false, hadModels: false };
@@ -161,14 +185,18 @@ const isPhaedoHookEntryFor = (marker) => (e) =>
 
 // Generic per-event merge/remove — the SessionStart (injection) and SessionEnd
 // (capture) entries use the same shape, distinguished by their script-path marker.
-export function mergeHookEntry(settings, event, command, marker) {
+// `matcher` / `timeout` (optional) are for tool events: the ship hook filters to Bash.
+export function mergeHookEntry(settings, event, command, marker, { matcher, timeout } = {}) {
   const isOurs = isPhaedoHookEntryFor(marker);
   const next = { ...settings, hooks: { ...(settings.hooks || {}) } };
   const prior = Array.isArray(next.hooks[event]) ? next.hooks[event] : [];
   const others = prior.filter((e) => !isOurs(e)); // drop a stale phaedo entry (path refresh)
   const existing = prior.find(isOurs);
-  const already = !!existing && existing.hooks.some((h) => h.command === command);
-  next.hooks[event] = [...others, { hooks: [{ type: 'command', command }] }];
+  const handler = { type: 'command', command, ...(timeout ? { timeout } : {}) };
+  const entry = { ...(matcher ? { matcher } : {}), hooks: [handler] };
+  const already = !!existing && existing.matcher === entry.matcher &&
+    existing.hooks.some((h) => h.command === command && h.timeout === handler.timeout);
+  next.hooks[event] = [...others, entry];
   return { settings: next, changed: !already };
 }
 
@@ -208,11 +236,18 @@ export function applyCodeHook({ action, dryRun = false, home = homedir() } = {})
     if (!read.existed) return { name, status: 'absent', detail: 'no settings.json' };
     const start = removeSessionStartHook(read.config);
     const both = removeHookEntry(start.settings, 'SessionEnd', CAPTURE_HOOK_MARKER);
-    if (!start.changed && !both.changed) return { name, status: 'absent', detail: 'no phaedo hook to remove' };
-    if (!dryRun) { backup(path); writeConfig(path, both.settings); }
+    const stop = removeHookEntry(both.settings, 'Stop', STOP_CAPTURE_HOOK_MARKER);
+    let s = stop.settings;
+    let shipChanged = false;
+    for (const ev of SHIP_HOOK_EVENTS) {
+      const r = removeHookEntry(s, ev, SHIP_HOOK_MARKER);
+      s = r.settings; shipChanged = shipChanged || r.changed;
+    }
+    if (!start.changed && !both.changed && !stop.changed && !shipChanged) return { name, status: 'absent', detail: 'no phaedo hook to remove' };
+    if (!dryRun) { backup(path); writeConfig(path, s); }
     return { name, status: dryRun ? 'would-remove' : 'removed', detail: path };
   }
-  // Always install SessionStart injection. Only install the SessionEnd CAPTURE hook
+  // Always install SessionStart injection. Only install the SessionEnd + Stop CAPTURE hooks
   // when its dependencies actually resolve from THIS install location: the hook loads
   // capture/* and extraction/delta-lift.js via lib/capture-home.js — repo root in a
   // clone, mcp/vendor/ in the published tarball (build-package.mjs vendors the
@@ -225,17 +260,27 @@ export function applyCodeHook({ action, dryRun = false, home = homedir() } = {})
   let captureNote = '';
   if (captureHookAvailable()) {
     const both = mergeHookEntry(settings, 'SessionEnd', hookCommand({ hookPath: CAPTURE_HOOK_PATH }), CAPTURE_HOOK_MARKER);
-    settings = both.settings; captureChanged = both.changed;
+    const stop = mergeHookEntry(both.settings, 'Stop', hookCommand({ hookPath: STOP_CAPTURE_HOOK_PATH }), STOP_CAPTURE_HOOK_MARKER);
+    settings = stop.settings; captureChanged = both.changed || stop.changed;
   } else {
     // Never leave a broken capture hook wired if we can't run it here.
     const rm = removeHookEntry(settings, 'SessionEnd', CAPTURE_HOOK_MARKER);
-    settings = rm.settings; captureChanged = rm.changed;
+    const rmStop = removeHookEntry(rm.settings, 'Stop', STOP_CAPTURE_HOOK_MARKER);
+    settings = rmStop.settings; captureChanged = rm.changed || rmStop.changed;
     captureNote = ' (capture hook skipped — not available in this install; injection only)';
   }
-  const changed = start.changed || captureChanged;
+  // Ship hook: consult before a merge / deploy / phone build. Its imports are all inside
+  // mcp/, so it runs wherever the server does — no availability gate needed.
+  let shipChanged = false;
+  for (const ev of SHIP_HOOK_EVENTS) {
+    const r = mergeHookEntry(settings, ev, hookCommand({ hookPath: SHIP_HOOK_PATH }), SHIP_HOOK_MARKER, SHIP_HOOK_ENTRY);
+    settings = r.settings; shipChanged = shipChanged || r.changed;
+  }
+  const changed = start.changed || captureChanged || shipChanged;
   if (!changed) return { name, status: 'unchanged', detail: `already configured${captureNote}` };
   if (!dryRun) { if (read.existed) backup(path); writeConfig(path, settings); }
-  return { name, status: dryRun ? 'would-write' : 'configured', detail: path + captureNote };
+  return { name, status: dryRun ? 'would-write' : 'configured', detail: path + captureNote,
+    restartHint: 'Start a new Claude Code session — hooks load when a session starts.' };
 }
 
 // The SessionEnd capture hook can only run where its imported modules resolve —
@@ -370,6 +415,7 @@ function parseArgs(argv) {
     else if (a === '--consult-model') opts.consultModel = argv[++i];
     else if (a === '--consult-url') opts.consultUrl = argv[++i];
     else if (a === '--no-model-judge') opts.noModelJudge = true;
+    else if (a === '--model-judge') opts.modelJudge = true;
     else if (a === '--capture-model') opts.captureModel = argv[++i];
     else if (a === '--capture-url') opts.captureUrl = argv[++i];
     else if (a === '--help' || a === '-h') opts.help = true;
@@ -396,10 +442,11 @@ const HELP = `Phaedo MCP installer
   node install.mjs --dry-run       preview changes, write nothing
   node install.mjs --only <id>     one client only: claude-desktop | cursor | claude-code
 
-  Consult model judge (ON by default, local Ollama, falls back to the rule engine):
-  node install.mjs --consult-model <id>   pin the model (e.g. llama3.1:8b)
+  Consult model judge (OFF by default — the rule engine answers; opt in below):
+  node install.mjs --model-judge          turn it on, auto-detecting a local Ollama chat model
+  node install.mjs --consult-model <id>   turn it on with a pinned model (e.g. llama3.1:8b)
   node install.mjs --consult-url <url>    endpoint (default http://localhost:11434)
-  node install.mjs --no-model-judge       rule engine only (no model env)
+  node install.mjs --no-model-judge       rule engine only (the default; kept for scripts)
 `;
 
 function runPairing() {
@@ -427,12 +474,12 @@ async function main(argv) {
 
   const action = opts.uninstall ? 'uninstall' : 'install';
 
-  // Consult model judge: ON by default. Pin it if --consult-model is given,
-  // otherwise probe local Ollama and pick an installed general model. Off with
-  // --no-model-judge. Always falls back to the rule engine at runtime, so a
-  // missing model never breaks consultation.
+  // Consult model judge: OFF unless asked for (see the measurement above buildConsultEnv).
+  // --consult-model pins one; --model-judge probes local Ollama for an installed chat model.
+  // Always falls back to the rule engine at runtime, so a missing model never breaks
+  // consultation. A plain install REMOVES a judge env an earlier default-on install wrote.
   let env = {}, consultNote = '';
-  if (action === 'install' && !opts.noModelJudge) {
+  if (action === 'install' && !opts.noModelJudge && (opts.consultModel || opts.modelJudge)) {
     const url = opts.consultUrl || DEFAULT_CONSULT_URL;
     if (opts.consultModel) {
       env = buildConsultEnv({ model: opts.consultModel, url });
@@ -445,7 +492,7 @@ async function main(argv) {
         : `model judge ON → ${d.model} @ ${url} (Ollama not detected — falls back to the rule engine until it's running)`;
     }
   } else if (action === 'install') {
-    consultNote = 'model judge OFF (rule engine only)';
+    consultNote = 'model judge OFF — the rule engine answers (opt in: --model-judge)';
   }
   const entry = serverEntry({ env });
   console.log(`Phaedo MCP — ${action}${opts.dryRun ? ' (dry run)' : ''}`);
@@ -490,7 +537,7 @@ async function main(argv) {
       console.log('\nNext:');
       console.log('  1. Pair with your phone:  npm run pair   (or re-run with --pair)');
       console.log('  2. Restart any client that was already open:');
-      for (const r of touched) console.log(`       • ${r.name}: ${r.restartHint}`);
+      for (const r of touched) if (r.restartHint) console.log(`       • ${r.name}: ${r.restartHint}`);
       console.log('  3. Inject your fingerprint at session start:');
       console.log('       • any client: run the `/phaedo` prompt (one click), or call');
       console.log('         the `phaedo_request_injection` tool.');

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
-  "description": "Phaedo MCP server \u2014 inject your cognitive fingerprint into any MCP client, and consult your decision pattern at agent decision points (docs/protocol/mcp-binding.md).",
+  "description": "Lets Claude, Cursor and other MCP apps answer in your style, check with you before acting, send decisions to your phone to approve, and ask you to sign purchase approvals with Face ID. Needs the Phaedo phone app; set PHAEDO_FINGERPRINT=sample to try it.",
   "mcpName": "io.github.phaedo-labs/phaedo-mcp",
   "homepage": "https://phaedo.so",
   "repository": {
@@ -14,11 +14,20 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
+    "claude",
+    "claude-code",
+    "cursor",
     "personalization",
-    "fingerprint",
-    "consultation",
-    "agent"
+    "human-in-the-loop",
+    "approval",
+    "guardrails",
+    "agent",
+    "ai-agents",
+    "ap2",
+    "agent-payments",
+    "anamnesis"
   ],
   "bin": {
     "phaedo-mcp": "server.js"
@@ -32,6 +41,9 @@
     "consult.js",
     "consult-core.js",
     "consult-policy.js",
+    "consult-runtime.js",
+    "ship-actions.js",
+    "ship-readout.js",
     "action-binding.js",
     "autonomy-promotion.js",
     "ap2.js",
@@ -80,9 +92,10 @@
     "unsetup": "node install.mjs --uninstall",
     "pair": "node pair.js",
     "pull": "node pull.js",
-    "test": "node test-smoke.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs",
+    "test": "node test-smoke.mjs && node test-no-profile.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs",
     "receipts": "node receipts.js list",
     "agreement": "node agreement.js",
+    "ship-readout": "node ship-readout.js",
     "calibration": "node calibration.js",
     "health": "node health.js",
     "validate": "node ../spec/validate-fingerprint.mjs sample-fingerprint.json",

package/phone-source.js

@@ -163,7 +163,12 @@ async function getSession(rec, deps) {
 // (consult-policy loadPolicies / context-block renderContextBlock); absent —
 // pre-part-3 phone — consumers fall back to the fingerprint A-home unchanged.
 export function toVaultPayload(inner) {
-  const m = inner.metrics || {};
+  // Prefer every paired browser's counters combined (`metrics_combined`, 2026-10-01): the subject
+  // is one person across browsers, and `metrics` is only the browser that posted last. A phone
+  // that predates the sibling sends only `metrics`, which still serves.
+  const m = (inner.metrics_combined && typeof inner.metrics_combined === 'object' && !Array.isArray(inner.metrics_combined))
+    ? inner.metrics_combined
+    : (inner.metrics || {});
   return {
     phaedo_fingerprint: inner.data,
     ...(inner.user_configuration && typeof inner.user_configuration === 'object'

package/receipts.js

@@ -261,7 +261,7 @@ if (process.argv[1] && process.argv[1].endsWith('receipts.js')) {
       for (const r of rs.slice(-50)) {
         const ad = r.request.action_descriptor;
         console.log(
-          `${r.receipt_id.slice(0, 8)}  ${r.created_at}  ${r.via === 'phaedo_check_authorization' ? '[pre-flight]' : '[consult]  '}` +
+          `${r.receipt_id.slice(0, 8)}  ${r.created_at}  ${r.via === 'phaedo_check_authorization' ? '[pre-flight]' : r.agent_id === 'claude-code/ship-hook' ? '[ship-hook] ' : '[consult]  '}` +
           ` ${r.request.consultation_type}  ${ad.domain || '-'}` +
           `  → ${r.response.signal} (conf ${r.response.confidence}, def ${r.response.deference_level})` +
           `  user_action: ${r.user_action ?? '—'}`

package/server.js

@@ -16,8 +16,8 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-import { loadFingerprint, loadFingerprintPreferCache, sourceOf } from './fingerprint-source.js';
-import { hasPairingRecord, loadPairingRecord, readServingClientId } from './phone-source.js';
+import { loadFingerprint, sourceOf } from './fingerprint-source.js';
+import { hasPairingRecord, loadPairingRecord } from './phone-source.js';
 import { depositDelegationSuggestions } from './delegation-sync.js';
 import { depositReceiptsDigest, drainAndApplyMarks } from './receipts-sync.js';
 import { buildDelegationPromotions } from './consult-core.js';
@@ -27,8 +27,9 @@ import { buildIntentMandatePayload } from './ap2.js';
 import { depositSignRequest, pollSignOnce } from './signing-request.js';
 import { buildSigningAuditRecord, appendSigningAudit } from './signing-audit.js';
 import { buildInjectionResponse, errorResponse, PhaedoError } from './projection.js';
-import { resolveConsultation, checkAuthorization, consultOptsFromEnv, CONSULTATION_TYPES, consultDrivers, deriveDelegationSignals, withDelegationSignals, authoredDelegationSignals } from './consult.js';
+import { resolveConsultation, checkAuthorization, CONSULTATION_TYPES, consultDrivers, withRevision } from './consult.js';
 import { defaultStateDir } from './cache.js';
+import { buildConsultOpts, loadConsultVd } from './consult-runtime.js';
 import { buildReceipt, appendReceipt, receiptsCapFromEnv, readReceipts, markOutcome, USER_ACTIONS } from './receipts.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -88,28 +89,6 @@ function withStaleAuthorityGuard(response, vd) {
   return out;
 }
 
-// Load the fingerprint for a consult and fold in the act-as-me channel: delegation
-// signals derived from this subject's own override history (§10.6 receipts). The
-// origin-aware resolver then lets a `delegation` correction outrank a `self` signal on
-// the same dimension. Best-effort — if receipts are unreadable, the consult still
-// answers from the plain fingerprint (delegation learning never breaks a consultation).
-async function loadConsultVd(baseDir, { preferCache = false } = {}) {
-  // preferCache (escalation): read the at-rest cache instead of a live phone pull, so the
-  // escalation doesn't add a fingerprint-read AUTHORIZE prompt on top of its decision card.
-  const vd = preferCache ? await loadFingerprintPreferCache(baseDir) : await loadFingerprint(baseDir);
-  try {
-    // Two delegation sources, both origin-aware: live override history (every override)
-    // + the subject's ENDORSED, portable delegation rules (authored_delegation). The
-    // authored rule thus shapes consult too, not only the §9 injection it already renders in.
-    const signals = deriveDelegationSignals(await readReceipts(defaultStateDir()))
-      .concat(authoredDelegationSignals(vd && vd.phaedo_fingerprint));
-    return withDelegationSignals(vd, signals);
-  } catch (e) {
-    process.stderr.write(`[phaedo-mcp] delegation derive skipped (consult unaffected): ${e.message}\n`);
-    return vd;
-  }
-}
-
 // Act-as-me PROMOTION (delegation-sync.js): when the override history shows an
 // ESTABLISHED pattern that isn't already authored/staged, deposit a delegation
 // SUGGESTION across the sync boundary (relay agent_to_ext) for the subject to review +
@@ -184,7 +163,9 @@ async function maybeDepositDelegationPromotions(vd) {
   }
 }
 
-const CONSULT_OPTS = consultOptsFromEnv(process.env);
+// Env config + the subject's deference policies + this install's paired-client id —
+// built in consult-runtime.js, the one copy the Claude Code ship hook shares.
+const CONSULT_OPTS = buildConsultOpts(BASE_DIR, process.env);
 // Real-time escalation window (docs/roadmap/escalation-and-push.md §crux): how long a
 // blocking decision waits for the subject before the agent applies the safe-default
 // (hold). Configurable; bounded by the relay's own MAX_WINDOW_MS.
@@ -192,20 +173,6 @@ const ESCALATION_WINDOW_MS = (() => {
   const n = Number(process.env.PHAEDO_ESCALATION_WINDOW_MS);
   return Number.isFinite(n) && n > 0 ? n : 3 * 60 * 1000;
 })();
-// Deference policies: PHAEDO_CONSULT_POLICIES if set, else the default file beside
-// the server (mcp/consult-policies.json — what policy-editor.html produces). Zero
-// config: drop the file in and restart the client. (Portable vault policies in
-// phaedo_consult_policies always apply too, regardless of this file.)
-const POLICIES_PATH = process.env.PHAEDO_CONSULT_POLICIES || join(BASE_DIR, 'consult-policies.json');
-if (existsSync(POLICIES_PATH)) {
-  try { CONSULT_OPTS.policies = JSON.parse(readFileSync(POLICIES_PATH, 'utf8')); }
-  catch (e) { process.stderr.write(`[phaedo-mcp] ignoring malformed consult policies (${POLICIES_PATH}): ${e.message}\n`); }
-}
-// §10.5 `agents`: this process's OWN paired-client identity, resolved once at startup.
-// One server serves one paired client, so it never asks a caller who is calling — it
-// reads who it IS. Null (unpaired / unreadable) makes `agents`-scoped RELAXING rules
-// inert, which is the fail-safe direction; the server still answers everything else.
-CONSULT_OPTS.clientId = readServingClientId(BASE_DIR);
 
 // Escalation PUSH policy (which signals wake the subject): the subject-configurable knob
 // over the stakes-gated default. Local file (PHAEDO_ESCALATION_POLICY, else
@@ -223,7 +190,18 @@ if (existsSync(ESCALATION_POLICY_PATH)) {
 // been the package's for two months. One source of truth; test-package-closure.mjs
 // asserts the two agree.
 const PKG_VERSION = JSON.parse(readFileSync(join(BASE_DIR, 'package.json'), 'utf8')).version;
-const server = new McpServer({ name: 'phaedo', version: PKG_VERSION });
+// The one place a client is told how the tools fit together. Without it an app saw eight
+// tool descriptions and nothing saying "load the profile first" or "consult before you ship" —
+// so whether Phaedo was used at all depended on the model guessing. Short on purpose: clients
+// put this in the model's context on every turn.
+const SERVER_INSTRUCTIONS = [
+  'Phaedo holds the user\'s profile: how they like answers written, and how they want decisions handled when an AI acts for them.',
+  '- At the start of a session, call phaedo_request_injection once and treat the returned projection as background on the user\'s style.',
+  '- Before a consequential action for the user (merging, deploying, publishing, sending a message, spending money, deleting, changing an account or setting), call phaedo_consult and follow its signal. If you are acting on your own and the decision should be the user\'s, use phaedo_escalate and do not proceed until it resolves.',
+  '- When the user reacts to an action you consulted on, call phaedo_record_outcome with its receipt_id: record what they chose, never what you inferred.',
+  '- If a tool says no Phaedo profile is set up, tell the user once, plainly, and carry on normally. Do not retry.',
+].join('\n');
+const server = new McpServer({ name: 'phaedo', version: PKG_VERSION }, { instructions: SERVER_INSTRUCTIONS });
 
 // ── Tool: phaedo_request_injection (binding §3.1) ─────────────────────────────
 server.registerTool(
@@ -285,8 +263,8 @@ const ACTION_BINDING_SCHEMA = z
   .optional()
   .describe(
     'Binds this consultation to the concrete call it describes. The action_descriptor is your ACCOUNT of the action; ' +
-    'this is the action. Recorded on the audit receipt so a later mismatch is provable, shown to the subject when an ' +
-    'escalation reaches their phone, and REQUIRED by any standing rule the subject marked require_binding before it ' +
+    'this is the action. Recorded on the audit receipt so a later mismatch is provable, shown to the user when an ' +
+    'escalation reaches their phone, and REQUIRED by any standing rule the user marked require_binding before it ' +
     'will auto-proceed.',
   );
 
@@ -299,9 +277,18 @@ server.registerTool(
   {
     title: 'Consult the Phaedo fingerprint at a decision point',
     description:
-      "Ask how the user's cognitive pattern bears on a decision — without ingesting the fingerprint. " +
-      'Returns a signal (proceed | proceed_with_note | clarify | escalate | decline), a confidence, a ' +
-      'short rationale_hint, and a deference_level (how strongly to weight it). Use at agent decision points.',
+      // Names the MOMENTS. "Use at agent decision points" told no agent when it was at one: not
+      // one consultation was written between 2026-07-28 and 2026-10-18. And it closes the loop —
+      // the receipt_id is the only handle that attributes the user's reaction to THIS action.
+      'Ask how the user would want an action handled, before you take it on their behalf — without ' +
+      'reading their profile. Call it BEFORE any consequential action you are about to take for the ' +
+      'user: merging or deploying, publishing or posting, sending a message, paying or committing money, ' +
+      'deleting, or changing an account or setting. Describe the action in action_descriptor (domain, ' +
+      'reversible, magnitude, a short summary; amount when money moves) and bind it to the exact call ' +
+      'with action_binding. Returns a signal (proceed | proceed_with_note | clarify | escalate | decline | ' +
+      'insufficient_signal), a confidence, a short rationale_hint, a deference_level (how strongly to ' +
+      'weight it) and a receipt_id. Keep the receipt_id: when the user reacts to what you did — confirms ' +
+      'it, overrides it, or wants it done differently — record that with phaedo_record_outcome.',
     inputSchema: {
       consultation_type: z.enum(CONSULTATION_TYPES),
       agent_id: z.string().optional(),
@@ -334,12 +321,12 @@ server.registerTool(
       // the two tools an autonomous agent actually uses answered from a possibly-revoked cached
       // profile with no downgrade and no provenance. That is the 2026-07-25 device defect (a
       // revoked $500 grant honoured from a 22h cache) still live on the paths that matter most.
-      const response = withStaleAuthorityGuard(
-        await resolveConsultation(vd, args || {}, CONSULT_OPTS), vd);
+      const raw = await resolveConsultation(vd, args || {}, CONSULT_OPTS);
+      const response = withStaleAuthorityGuard(raw, vd);
       // Provenance for the local audit receipt only — the cues that drove this
       // (never in `response`; §10.4). Best-effort: a failure must not block the answer.
       let drivers = [];
-      try { drivers = consultDrivers(vd, args || {}); } catch { /* provenance is non-critical */ }
+      try { drivers = withRevision(consultDrivers(vd, args || {}, CONSULT_OPTS), raw); } catch { /* provenance is non-critical */ }
       const receiptId = await emitReceipt('phaedo_consult', args, response, drivers); // every resolution, abstains included
       if (receiptId) response.receipt_id = receiptId;   // the handle for phaedo_record_outcome
       await maybeDepositDelegationPromotions(vd);                    // act-as-me promotion (best-effort)
@@ -372,7 +359,7 @@ server.registerTool(
     title: 'Check standing authorizations for an action',
     description:
       "Deterministic pre-flight: check whether one of the user's standing authorizations " +
-      '(§10.5) already decides this action — escalate, decline, or pre-approve — without running ' +
+      'already decides this action — escalate, decline, or pre-approve — without running ' +
       'the full consultation. Returns authorization_matched plus the authorized signal and the ' +
       'rule that fired. If no rule matches, fall back to phaedo_consult or your own default.',
     inputSchema: {
@@ -450,10 +437,13 @@ server.registerTool(
   {
     title: 'Record what the subject decided about a consulted action',
     description:
-      'After you consulted Phaedo and the USER decided what to do, record their outcome on the receipt: ' +
-      'approved | rejected | modified | unknown. Record what the USER chose, NOT whether you proceeded. ' +
-      'A rejected/modified outcome teaches Phaedo how the user wants delegated work handled (the act-as-me ' +
-      'channel). Defaults to the most recent receipt; pass receipt_id to mark a specific one.',
+      'Record what the USER decided about an action you consulted Phaedo on: approved | rejected | ' +
+      'modified | unknown. Call it when the user reacts to that action — they confirm it (approved), ' +
+      'refuse or undo it (rejected), or want it done differently (modified). Always pass the receipt_id ' +
+      'that phaedo_consult (or a Phaedo hook) gave you; without it the most recent receipt is marked, ' +
+      'which may be a different action. Record what the user chose, never whether you proceeded: ' +
+      'silence is not approval, and an approval you inferred teaches nothing. A rejected/modified ' +
+      'outcome teaches Phaedo how the user wants delegated work handled (the act-as-me channel).',
     inputSchema: {
       outcome: z.enum(USER_ACTIONS),
       receipt_id: z.string().optional(),
@@ -547,10 +537,10 @@ server.registerTool(
       // UNCONDITIONALLY, so without the guard it always reasoned from a possibly-stale profile
       // and then told the agent the signal was not blocking — i.e. "just proceed", and never
       // wake the subject, on authority that may have been revoked hours earlier.
-      const response = withStaleAuthorityGuard(
-        await resolveConsultation(vd, req, CONSULT_OPTS), vd);
+      const raw = await resolveConsultation(vd, req, CONSULT_OPTS);
+      const response = withStaleAuthorityGuard(raw, vd);
       let drivers = [];
-      try { drivers = consultDrivers(vd, req); } catch { /* non-critical */ }
+      try { drivers = withRevision(consultDrivers(vd, req, CONSULT_OPTS), raw); } catch { /* non-critical */ }
       const escReceiptId = await emitReceipt('phaedo_escalate', req, response, drivers);   // the decision being escalated
       await maybeDepositReceiptsDigest();                              // G1+G2 audit channel
 
@@ -687,10 +677,10 @@ server.registerTool(
   {
     title: 'Ask the subject to sign a payment authorization (AP2 Intent Mandate)',
     description:
-      'Request the subject\'s cryptographic signature on an AP2 Intent Mandate built from their ' +
+      'Request the user\'s cryptographic signature on an AP2 Intent Mandate built from their ' +
       'standing authorizations — a credential a merchant or payments network can verify. Returns a ' +
       'request_id and the unsigned mandate immediately; then poll phaedo_sign_status with BOTH, and ' +
-      'DO NOT treat the mandate as authorized until it returns signed. The subject signs on their ' +
+      'DO NOT treat the mandate as authorized until it returns signed. The user signs on their ' +
       'phone (Face ID, key in the Secure Enclave); they may also decline. Use only when you need a ' +
       'verifiable payment credential — not for ordinary consultations.',
     inputSchema: {
@@ -740,7 +730,7 @@ server.registerTool(
             mandate,
             message: 'Sent to the subject to sign. Poll phaedo_sign_status with this request_id AND this ' +
                      'mandate; do not treat it as authorized until it returns signed. If it expires or the ' +
-                     'subject declines, the mandate stays an unsigned proposal.',
+                     'user declines, the mandate stays an unsigned proposal.',
           }
         : {
             request_type: 'sign_mandate', status: 'unreachable', reason: dep.reason,
@@ -766,9 +756,9 @@ server.registerTool(
     title: 'Check whether the subject has signed the mandate',
     description:
       'Poll a request from phaedo_sign_mandate. Pass the request_id AND the mandate that call returned. ' +
-      'Returns signed + the mandate carrying the verified signature once the subject signs, refused if ' +
+      'Returns signed + the mandate carrying the verified signature once the user signs, refused if ' +
       'they declined, pending while you should keep waiting, or expired once the window lapsed. A signed ' +
-      'result is verified against the subject\'s published signing key before it is returned.',
+      'result is verified against the user\'s published signing key before it is returned.',
     inputSchema: {
       request_id: z.string(),
       mandate: z.record(z.any()),

package/server.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.phaedo-labs/phaedo-mcp",
-  "description": "Carry your Phaedo cognitive fingerprint into any MCP client: injection, consults, escalation, mandate signing.",
-  "version": "0.3.0",
+  "description": "Make AI apps answer your way, check with you before acting, and get approvals on your phone.",
+  "version": "0.3.2",
   "repository": {
     "url": "https://github.com/phaedo-labs/phaedo-mcp",
     "source": "github",
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "phaedo-mcp",
-      "version": "0.3.0",
+      "version": "0.3.2",
       "transport": {
         "type": "stdio"
       }