phaedo-mcp 0.3.6 → 0.3.13

package/history-import.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// Phaedo — learn from your ChatGPT or Claude history, from the export file each one gives you.
+//
+//   npm run import -- ~/Downloads/chatgpt-export.zip
+//   npm run import -- ~/Downloads/claude-export.zip --all     # every conversation, not just the last year
+//   npm run import -- conversations.json --dry-run            # count what it would read, change nothing
+//
+// Get the file: ChatGPT → Settings → Data controls → Export data; Claude → Settings → Privacy →
+// Export data. Each emails a zip; its conversations.json is all this reads.
+//
+// Each conversation becomes {role, text} turns and goes through the SAME spine the Claude Code
+// hook and the Mac reader use (capture/exchanges.js → capture-core.js: the deterministic
+// detectors → per-session state → delta lift), as its own session keyed by the conversation's id,
+// so importing the same export twice replaces rather than doubles. One deposit to the phone at
+// the end when paired; a starter profile on this computer when not.
+//
+// DISCARD-RAW, as everywhere in capture: the text is read in memory, counted, and dropped.
+// Nothing derived from it but signal names and integers is kept or sent. Not in the directory
+// edition (its policy forbids reading chat history).
+
+import { execFileSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname, extname } from 'path';
+import { fileURLToPath } from 'url';
+import { isMainModule } from './lib/is-main.js';
+
+export const DEFAULT_DAYS = 365;
+export const SURFACES = Object.freeze({ chatgpt: 'chatgpt-import', claude: 'claude-import' });
+const DAY = 24 * 60 * 60 * 1000;
+
+const text = (v) => (typeof v === 'string' ? v : '');
+const iso = (t) => {
+  if (typeof t === 'number' && Number.isFinite(t)) return new Date(t < 1e12 ? t * 1000 : t).toISOString();
+  const p = Date.parse(t);
+  return Number.isFinite(p) ? new Date(p).toISOString() : null;
+};
+
+/** Which service an export came from, by shape. PURE. */
+export function detectFormat(list) {
+  const first = Array.isArray(list) ? list.find((c) => c && typeof c === 'object') : null;
+  if (!first) return null;
+  if (first.mapping && typeof first.mapping === 'object') return 'chatgpt';
+  if (Array.isArray(first.chat_messages)) return 'claude';
+  return null;
+}
+
+// ChatGPT stores each conversation as a tree (every regenerate or edit is a branch). The
+// conversation the person actually had is the path from `current_node` up to the root.
+function chatgptTurns(c) {
+  const map = c.mapping || {};
+  let id = c.current_node && map[c.current_node] ? c.current_node : null;
+  if (!id) {   // no current_node: the deepest leaf of the first branch
+    id = Object.keys(map).find((k) => !map[k]?.parent) || null;
+    while (id && Array.isArray(map[id]?.children) && map[id].children.length) id = map[id].children[0];
+  }
+  const path = [];
+  const seen = new Set();
+  while (id && map[id] && !seen.has(id)) { seen.add(id); path.push(map[id]); id = map[id].parent; }
+  path.reverse();
+  const turns = [];
+  for (const node of path) {
+    const m = node.message;
+    const role = m?.author?.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const ct = m.content?.content_type;
+    if (ct && ct !== 'text' && ct !== 'multimodal_text') continue;   // code runs, browsing, tool output
+    const body = (Array.isArray(m.content?.parts) ? m.content.parts : []).map(text).join('\n').trim();
+    if (body) turns.push({ role, text: body, id: m.id || node.id, timestamp: iso(m.create_time) });
+  }
+  return turns;
+}
+
+function claudeTurns(c) {
+  const turns = [];
+  for (const m of Array.isArray(c.chat_messages) ? c.chat_messages : []) {
+    const role = m?.sender === 'human' ? 'user' : m?.sender === 'assistant' ? 'assistant' : null;
+    if (!role) continue;
+    const parts = Array.isArray(m.content) ? m.content.filter((p) => p?.type === 'text').map((p) => text(p.text)) : [];
+    const body = (parts.length ? parts.join('\n') : text(m.text)).trim();
+    if (body) turns.push({ role, text: body, id: m.uuid, timestamp: iso(m.created_at) });
+  }
+  return turns;
+}
+
+/**
+ * The export's conversations as [{ id, at, turns }], newest first, within `days` of `now`
+ * (null = all). Never throws on a malformed entry; skips it. PURE.
+ */
+export function conversationsFrom(list, format, { now = Date.now(), days = DEFAULT_DAYS } = {}) {
+  const since = days == null ? -Infinity : now - days * DAY;
+  const out = [];
+  for (const c of Array.isArray(list) ? list : []) {
+    if (!c || typeof c !== 'object') continue;
+    const id = format === 'chatgpt' ? (c.conversation_id || c.id) : c.uuid;
+    const at = format === 'chatgpt' ? iso(c.update_time ?? c.create_time) : iso(c.updated_at ?? c.created_at);
+    if (!id || !at || Date.parse(at) < since || Date.parse(at) > now) continue;
+    const turns = format === 'chatgpt' ? chatgptTurns(c) : claudeTurns(c);
+    if (turns.some((t) => t.role === 'user') && turns.some((t) => t.role === 'assistant')) out.push({ id: String(id), at, turns });
+  }
+  return out.sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+}
+
+/** conversations.json from a .zip (system unzip, else bsdtar) or a .json path. */
+export function readExport(path) {
+  const p = resolve(path);
+  if (!existsSync(p)) throw Object.assign(new Error(`no file at ${p}`), { code: 'ENOENT' });
+  if (extname(p).toLowerCase() !== '.zip') return JSON.parse(readFileSync(p, 'utf8'));
+  const opts = { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] };
+  for (const [cmd, args] of [['unzip', ['-p', p, 'conversations.json']], ['tar', ['-xOf', p, 'conversations.json']]]) {
+    try { const raw = execFileSync(cmd, args, opts); if (raw.trim()) return JSON.parse(raw); } catch { /* try the next */ }
+  }
+  throw new Error("couldn't find conversations.json in that zip — is it the ChatGPT or Claude data export?");
+}
+
+/**
+ * Fold every conversation through the capture spine and deposit once. deps: { fold, deposit,
+ * sourceId, statePath, now } — the real ones in the CLI, fakes in tests. Returns a summary.
+ */
+export async function importConversations(convos, format, deps) {
+  const surface = SURFACES[format];
+  let signals = [];
+  let messages = 0;
+  for (const c of convos) {
+    const r = await deps.fold(c, surface);
+    messages += r.counted || 0;
+    if (Array.isArray(r.signals)) signals = r.signals;     // cumulative: the last fold holds them all
+  }
+  const deposit = signals.length && deps.deposit ? await deps.deposit(signals, surface) : null;
+  return { conversations: convos.length, messages, signals: signals.length, deposited: Boolean(deposit?.deposited), deposit };
+}
+
+const plural = (n, w) => `${n.toLocaleString('en-US')} ${w}${n === 1 ? '' : 's'}`;
+
+/** The result in plain words. PURE. */
+export function summaryText(r, { service, days, dryRun = false, paired = false }) {
+  const span = days == null ? '' : ` from the last ${days === 365 ? 'year' : `${days} days`}`;
+  if (!r.conversations) return `No ${service} conversations${span} to read in that file.`;
+  const head = `${dryRun ? 'Would read' : 'Read'} ${plural(r.conversations, 'conversation')}${span} from ${service} (${plural(r.messages, 'message')} of yours).`;
+  if (dryRun) return `${head} Nothing was changed.`;
+  const learned = r.signals
+    ? `Phaedo found ${plural(r.signals, 'pattern')} in how you work${paired ? (r.deposited ? ' and sent them to your phone' : '; they\'ll reach your phone with the next sync') : ''}.`
+    : 'Phaedo found nothing new in how you work from these.';
+  return `${head} ${learned} Only counts were kept; you can delete the export file now. To see and prune what it learned: npm run learned`;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+async function main(argv) {
+  const file = argv.find((a) => !a.startsWith('--'));
+  const say = (s) => process.stdout.write(s + '\n');
+  if (!file) {
+    say('Usage: npm run import -- <ChatGPT or Claude export .zip, or its conversations.json> [--all] [--days N] [--dry-run]');
+    return 1;
+  }
+  const opt = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : null; };
+  const days = argv.includes('--all') ? null : (Number(opt('--days')) > 0 ? Number(opt('--days')) : DEFAULT_DAYS);
+  const dryRun = argv.includes('--dry-run');
+
+  let list;
+  try { list = readExport(file); } catch (e) { say(`✗ ${e.code === 'ENOENT' ? `No file at ${file}.` : e.message}`); return 1; }
+  const format = detectFormat(list);
+  if (!format) { say("✗ That doesn't look like a ChatGPT or Claude data export (no conversations in the shape either one uses)."); return 1; }
+  const service = format === 'chatgpt' ? 'ChatGPT' : 'Claude';
+  const convos = conversationsFrom(list, format, { days });
+  list = null;                                   // the raw export is not needed past this point
+
+  if (dryRun) {
+    const messages = convos.reduce((n, c) => n + c.turns.filter((t) => t.role === 'user').length, 0);
+    say(summaryText({ conversations: convos.length, messages, signals: 0 }, { service, days, dryRun: true }));
+    return 0;
+  }
+
+  const MCP_DIR = dirname(fileURLToPath(import.meta.url));
+  const { loadCaptureModule } = await import('./lib/capture-home.js');
+  const [{ turnsToBatch }, { foldBatchToSignals }, { deriveSourceDeviceId }] = await Promise.all(
+    ['capture/exchanges.js', 'capture/capture-core.js', 'capture/source-id.js'].map(loadCaptureModule));
+  const { loadPairingRecord } = await import('./phone-source.js');
+  const { buildCaptureDelta, depositCaptureDelta } = await import('./capture-sync.js');
+  let pairing = null;
+  try { pairing = await loadPairingRecord(MCP_DIR); } catch { pairing = null; }
+  const now = new Date().toISOString();
+  const sourceId = deriveSourceDeviceId(pairing, SURFACES[format]);
+
+  const r = await importConversations(convos, format, {
+    async fold(c, surface) {
+      const batch = turnsToBatch(c.turns, { sessionId: `${surface}:${c.id}`, platform: surface });
+      // Regex detectors only: a local model over a whole history would take hours.
+      const out = await foldBatchToSignals(batch, { sourceId, surface, sessionLocalId: `${surface}:${c.id}`, now, captureModel: null });
+      return { signals: out.signals, counted: batch.user_prompts.length };
+    },
+    deposit: pairing ? async (signals, surface) => {
+      const delta = buildCaptureDelta(signals, { sourceSurface: surface, sourceDeviceId: sourceId, capturedAt: now });
+      return depositCaptureDelta(pairing, delta, { now: () => now });
+    } : null,
+  });
+  say(summaryText(r, { service, days, paired: Boolean(pairing) }));
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv.slice(2)).then((c) => process.exit(c), (e) => { process.stderr.write(`✗ ${e.message}\n`); process.exit(1); });
+}

package/hooks/agent-hook.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// Phaedo — the merge check for agents other than Claude Code.
+//
+//   node hooks/agent-hook.mjs <cursor|copilot|codex|gemini>
+//
+// Each agent's pre-action hook sends its own JSON on stdin. This turns it into the shape the
+// Claude Code ship hook (pre-ship.mjs) already handles, runs the SAME classification, consult
+// and receipt path, and answers in the agent's own format. Same rule as pre-ship: it only ever
+// adds friction — it never returns "allow" — and it stays silent for anything that isn't a
+// merge, deploy, publish, message, payment, delete or the like.
+//
+//   agent     hook                                         can it show a prompt?
+//   Cursor    ~/.cursor/hooks.json beforeShellExecution,   yes — permission "ask"
+//             beforeMCPExecution
+//   Copilot   ~/.copilot/hooks/phaedo.json preToolUse      yes — permissionDecision "ask"
+//   Codex     ~/.codex/hooks.json PreToolUse               no  — "ask" is unsupported
+//   Gemini    ~/.gemini/settings.json BeforeTool           no  — allow / deny only
+//
+// Where the agent can't prompt, Phaedo pauses the action once with the reason, so the agent
+// stops and asks in the chat; the same call again within RETRY_WINDOW_MS goes through (the
+// subject has answered) and is not consulted twice. A pause, never a wall — and never a loop.
+//
+// FAIL-SAFE: any error, and anything past BUDGET_MS, exits 0 with no output. That matters most
+// for Copilot, where a hook that crashes DENIES the tool call.
+
+import { join } from 'path';
+import { classifyToolCall } from '../ship-actions.js';
+import { runShipHook, callHash, readState, writeState, BUDGET_MS } from './pre-ship.mjs';
+import { isMainModule } from '../lib/is-main.js';
+
+export const AGENTS = Object.freeze({
+  cursor:  { id: 'cursor/ship-hook', canAsk: true },
+  copilot: { id: 'copilot-cli/ship-hook', canAsk: true },
+  codex:   { id: 'codex/ship-hook', canAsk: false },
+  gemini:  { id: 'gemini-cli/ship-hook', canAsk: false },
+});
+export const RETRY_WINDOW_MS = 15 * 60 * 1000;
+
+const parseMaybe = (v) => {
+  if (typeof v !== 'string') return v && typeof v === 'object' ? v : {};
+  try { const o = JSON.parse(v); return o && typeof o === 'object' ? o : {}; } catch { return {}; }
+};
+const shell = (command, cwd) => (typeof command === 'string' && command.trim()
+  ? { tool_name: 'Bash', tool_input: { command }, cwd, hook_event_name: 'PreToolUse' } : null);
+const mcp = (server, tool, args, cwd) => (server && tool
+  ? { tool_name: `mcp__${server}__${tool}`, tool_input: parseMaybe(args), cwd, hook_event_name: 'PreToolUse' } : null);
+
+/** The agent's hook input as the Claude Code PreToolUse shape, or null when it isn't a tool call. PURE. */
+export function normalize(agent, raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  const cwd = r.cwd || (Array.isArray(r.workspace_roots) ? r.workspace_roots[0] : undefined);
+  switch (agent) {
+    case 'cursor':
+      if (typeof r.mcp_server_name === 'string') return mcp(r.mcp_server_name, r.tool_name, r.tool_input, cwd);
+      return shell(r.command, cwd);
+    case 'copilot': {
+      // camelCase `preToolUse` (toolName/toolArgs), or the PascalCase variant (tool_name/tool_input).
+      const name = String(r.toolName ?? r.tool_name ?? '');
+      const args = parseMaybe(r.toolArgs ?? r.tool_input);
+      if (/^(bash|shell|powershell)$/i.test(name)) return shell(args.command, cwd);
+      if (name.startsWith('mcp__')) return { tool_name: name, tool_input: args, cwd, hook_event_name: 'PreToolUse' };
+      return null;
+    }
+    case 'codex':
+      // Codex's PreToolUse is already Claude-shaped: Bash + tool_input.command, mcp__server__tool.
+      if (r.tool_name === 'Bash') return shell(r.tool_input?.command, cwd);
+      if (typeof r.tool_name === 'string' && r.tool_name.startsWith('mcp__')) return { tool_name: r.tool_name, tool_input: parseMaybe(r.tool_input), cwd, hook_event_name: 'PreToolUse' };
+      return null;
+    case 'gemini': {
+      const name = String(r.tool_name || '');
+      if (name === 'run_shell_command') return shell(r.tool_input?.command, cwd);
+      const ctx = r.mcp_context && typeof r.mcp_context === 'object' ? r.mcp_context : {};
+      const server = ctx.server_name;
+      if (server && name.startsWith(`mcp_${server}_`)) return mcp(server, name.slice(`mcp_${server}_`.length), r.tool_input, cwd);
+      const m = /^mcp_([^_]+)_(.+)$/.exec(name);
+      return m ? mcp(m[1], m[2], r.tool_input, cwd) : null;
+    }
+    default: return null;
+  }
+}
+
+const PAUSE = " This agent can't show a confirmation prompt, so Phaedo paused it: ask the user, and run the same command again only if they say yes.";
+
+/**
+ * The ship hook's answer in the agent's own format, or null for no output. PURE.
+ * Never "allow": a quiet answer is no output, so the agent's own permission flow applies.
+ */
+export function render(agent, out) {
+  const h = out?.hookSpecificOutput || {};
+  const asked = h.permissionDecision === 'ask';
+  const reason = h.permissionDecisionReason || '';
+  const context = h.additionalContext || '';
+  switch (agent) {
+    case 'cursor':
+      return asked ? { permission: 'ask', user_message: reason, agent_message: context } : null;
+    case 'copilot':
+      return asked ? { permissionDecision: 'ask', permissionDecisionReason: reason } : null;
+    case 'codex':
+      if (asked) return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason + PAUSE } };
+      return context ? { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: context } } : null;
+    case 'gemini':
+      return asked ? { decision: 'deny', reason: reason + PAUSE, systemMessage: reason } : null;
+    default: return null;
+  }
+}
+
+/**
+ * One invocation. deps: the pre-ship deps (consult, writeReceipt, statePath, now…) plus
+ * `pausePath` for the agents that can't prompt. Returns what to print, or null.
+ */
+export async function runAgentHook(agent, raw, deps) {
+  const spec = AGENTS[agent];
+  if (!spec) return null;
+  const input = normalize(agent, raw);
+  if (!input || !classifyToolCall(input.tool_name, input.tool_input)) return null;
+  const now = deps.now ?? Date.now();
+  const hash = callHash(input);
+
+  if (!spec.canAsk) {
+    const paused = readState(deps.pausePath);
+    paused.pending ||= {};
+    for (const [k, v] of Object.entries(paused.pending)) if (!(now - Date.parse(v?.at) < RETRY_WINDOW_MS)) delete paused.pending[k];
+    const key = `${agent}:${hash}`;
+    if (paused.pending[key]) {
+      // The retry after a pause: the subject answered in the chat. Let it through, once.
+      delete paused.pending[key];
+      writeState(deps.pausePath, paused, now);
+      return null;
+    }
+    const out = await runShipHook(input, { ...deps, agentId: spec.id });
+    if (out?.hookSpecificOutput?.permissionDecision === 'ask') {
+      paused.pending[key] = { at: new Date(now).toISOString() };
+      writeState(deps.pausePath, paused, now);
+    }
+    return render(agent, out);
+  }
+  return render(agent, await runShipHook(input, { ...deps, agentId: spec.id }));
+}
+
+async function main(agent) {
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return; }
+  // Cheap exit before importing the vault stack: most tool calls are not ship actions.
+  const input = normalize(agent, parsed);
+  if (!input || !classifyToolCall(input.tool_name, input.tool_input)) return;
+  const { realDeps } = await import('./pre-ship.mjs');
+  const { defaultStateDir } = await import('../cache.js');
+  const deps = await realDeps({ agentId: AGENTS[agent]?.id });
+  const out = await runAgentHook(agent, parsed, { ...deps, pausePath: join(defaultStateDir(), 'agent-hook-paused.json') });
+  if (out) process.stdout.write(JSON.stringify(out));
+}
+
+if (isMainModule(import.meta.url)) {
+  const timeout = new Promise((res) => setTimeout(res, BUDGET_MS));
+  Promise.race([main(process.argv[2]).catch(() => {}), timeout])
+    .then(() => process.exit(0))
+    .catch(() => process.exit(0)); // never break, and never deny by crashing (Copilot fails closed)
+}

package/hooks/pre-ship.mjs

@@ -41,7 +41,7 @@ import { dirname, resolve, join } from 'path';
 import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
 import { createHash } from 'crypto';
 import { execFile } from 'child_process';
-import { classifyShipCommand } from '../ship-actions.js';
+import { classifyShipCommand, classifyToolCall } from '../ship-actions.js';
 import { isMainModule } from '../lib/is-main.js';
 
 const MCP_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -55,7 +55,11 @@ export const BUDGET_MS = 12000;
 export const ASKING_SIGNALS = new Set(['escalate', 'clarify', 'decline']);
 
 // Permission modes in which a PermissionRequest is not evidence that a PERSON answered:
-// auto mode's classifier and dontAsk decide without one.
+// auto mode's classifier and dontAsk decide without one. With ONE exception, in auto mode: when
+// this hook itself returned `ask`, Claude Code shows the subject a real prompt ("a hook's `ask`
+// also forces a permission prompt in auto mode: the classifier can still deny the tool call,
+// but it can't approve the call silently" — hooks reference). That prompt is the personal
+// reviewer's whole point, so a yes on it is the subject's and is recorded.
 const NO_HUMAN_MODES = new Set(['auto', 'dontAsk']);
 
 // The profile is read from the at-rest cache, which only a live read refreshes. Past this
@@ -70,6 +74,10 @@ const PENDING_TTL_MS = DAY_MS;
 export const AGENT_ID = 'claude-code/ship-hook';
 
 export const commandHash = (cmd) => createHash('sha256').update(String(cmd ?? '')).digest('hex');
+// The call's identity across its hook events: the command for Bash, the input for a tool.
+export const callHash = (input) => commandHash(input?.tool_name === 'Bash' ? input?.tool_input?.command : `${input?.tool_name}:${JSON.stringify(input?.tool_input ?? null)}`);
+// The calls this hook reviews: shell commands, and connected tools (MCP).
+const reviewable = (input) => input?.tool_name === 'Bash' || String(input?.tool_name || '').startsWith('mcp__');
 
 // ── CI state for a merge (precedent track Phase 1b, B6) ───────────────────────────────
 // Merging a PR whose checks are failing, or have not finished, is a bigger act than merging a
@@ -217,9 +225,22 @@ export function writeState(path, state, now) {
   renameSync(tmp, path);
 }
 
+// THE PERSONAL PART OF THE PROMPT. Auto mode's reviewer judges an action by its type; this says
+// why THIS person would want to see it — their own rule when one decided it, else what is at
+// stake. Built only from the agent's descriptor and the consult answer (never vault content).
+export function personalWhy(descriptor = {}, response = {}) {
+  const rule = /^Per your standing rule: (.+?)\.?$/.exec(String(response?.rationale_hint || '').trim());
+  if (rule) return `your rule: ${rule[1]}`;
+  const w = [];
+  if (descriptor.reversible === false) w.push("it can't be undone");
+  if (typeof descriptor.amount === 'number' && descriptor.amount > 0) w.push(`it spends $${descriptor.amount.toLocaleString('en-US', { maximumFractionDigits: 2 })}`);
+  return w.join(' and ');
+}
+
 // What the subject reads on the prompt. Plain words, no numbers, no protocol terms.
-export function promptReason(signal, summary, why) {
-  const what = why ? `${summary} — ${why}` : summary;
+export function promptReason(signal, summary, why, personal = '') {
+  const reasons = [why, personal].filter(Boolean).join('; ');
+  const what = reasons ? `${summary} — ${reasons}` : summary;
   if (signal === 'decline') return `Phaedo thinks you'd say no to this one: ${what}. Go ahead anyway?`;
   if (signal === 'clarify') return `Phaedo isn't sure how you'd want this handled: ${what}. Go ahead?`;
   return `Phaedo thinks you'd want to OK this yourself: ${what}.`;
@@ -228,7 +249,7 @@ export function promptReason(signal, summary, why) {
 // What the agent reads before the command. It carries the receipt id — the one handle
 // that attributes an outcome to THIS decision rather than whatever receipt is newest.
 export function preContext({ summary, signal, receiptId, asked, hint }) {
-  const head = `Phaedo was consulted before this command (${summary}) and answered "${signal}"` +
+  const head = `Phaedo was consulted before this action (${summary}) and answered "${signal}"` +
     (hint ? ` — ${hint}` : '') + `. receipt_id: ${receiptId}.`;
   if (asked) {
     return `${head} Phaedo flagged it for the user, so they may be asked to confirm. If they decline, ` +
@@ -243,7 +264,7 @@ export function preContext({ summary, signal, receiptId, asked, hint }) {
 
 // After the command, when Phaedo had flagged it and no prompt was shown.
 export function unpromptedContext(receiptId) {
-  return `No confirmation prompt was shown for this command (receipt_id: ${receiptId}), though Phaedo ` +
+  return `No confirmation prompt was shown for this action (receipt_id: ${receiptId}), though Phaedo ` +
     `had flagged it for the user. Tell them in one line that it ran and Phaedo had flagged it, and ` +
     `record their reaction with phaedo_record_outcome and this receipt_id if they give one. Silence ` +
     `is not approval.`;
@@ -264,12 +285,12 @@ export function staleContext(days, mcpDir) {
  * Returns the JSON object to print, or null for no output.
  */
 export async function runShipHook(input, deps) {
-  if (!input || input.tool_name !== 'Bash') return null;
+  if (!reviewable(input)) return null;
   const now = deps.now ?? Date.now();
   const ev = input.hook_event_name;
 
   if (ev === 'PreToolUse') {
-    const ship = classifyShipCommand(input.tool_input?.command);
+    const ship = classifyToolCall(input.tool_name, input.tool_input);
     if (!ship) return null;
     // B6 + B3: one GitHub lookup per merge — check state, size, paths. Each can only raise.
     let ci = null, stakes = null;
@@ -281,7 +302,7 @@ export async function runShipHook(input, deps) {
     const raised = why !== '';
     const request = {
       consultation_type: 'action_approval',
-      agent_id: AGENT_ID,
+      agent_id: deps.agentId || AGENT_ID,
       action_descriptor: raised ? { ...ship.action_descriptor, magnitude: 'high' } : ship.action_descriptor,
       action_binding: ship.action_binding,
     };
@@ -299,7 +320,7 @@ export async function runShipHook(input, deps) {
     const state = readState(deps.statePath);
     if (input.tool_use_id) {
       state.pending[input.tool_use_id] = {
-        receipt_id: receiptId, cmd_hash: commandHash(input.tool_input?.command),
+        receipt_id: receiptId, cmd_hash: callHash(input),
         asked, prompt_shown: false, at: new Date(now).toISOString(),
       };
     }
@@ -317,7 +338,7 @@ export async function runShipHook(input, deps) {
     return {
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',
-        ...(asked ? { permissionDecision: 'ask', permissionDecisionReason: promptReason(signal, ship.summary, why) } : {}),
+        ...(asked ? { permissionDecision: 'ask', permissionDecisionReason: promptReason(signal, ship.summary, why, personalWhy(request.action_descriptor, response)) } : {}),
         additionalContext: context,
       },
     };
@@ -326,13 +347,15 @@ export async function runShipHook(input, deps) {
   if (ev === 'PermissionRequest') {
     // Evidence that a prompt is about to be shown for this command. PermissionRequest has
     // no tool_use_id (documented), so match the newest pending consult on the same command.
-    if (NO_HUMAN_MODES.has(input.permission_mode)) return null;
-    const h = commandHash(input.tool_input?.command);
+    if (input.permission_mode === 'dontAsk') return null;
+    const h = callHash(input);
     const state = readState(deps.statePath);
     const hit = Object.values(state.pending)
       .filter((e) => e.cmd_hash === h && !e.prompt_shown)
       .sort((a, b) => Date.parse(b.at) - Date.parse(a.at))[0];
     if (!hit) return null;
+    // Auto mode: only the prompt Phaedo forced is a person's; anything else is the classifier.
+    if (NO_HUMAN_MODES.has(input.permission_mode) && !hit.asked) return null;
     hit.prompt_shown = true;
     writeState(deps.statePath, state, now);
     return null;                     // never decide here — the subject answers the prompt
@@ -361,7 +384,8 @@ export async function runShipHook(input, deps) {
 }
 
 // ── Real deps: the same consult path as the MCP server (consult-runtime.js). ──────────
-async function realDeps() {
+// `agentId` names the agent on the receipt; other agents' hooks (agent-hook.mjs) pass their own.
+export async function realDeps({ agentId = AGENT_ID, statePath } = {}) {
   const { loadConsultVd, buildConsultOpts } = await import('../consult-runtime.js');
   const { resolveConsultation, consultDrivers, withRevision } = await import('../consult.js');
   const { buildReceipt, appendReceipt, receiptsCapFromEnv, markOutcome } = await import('../receipts.js');
@@ -371,7 +395,8 @@ async function realDeps() {
   const quiet = () => {};
   const opts = buildConsultOpts(MCP_DIR, process.env, { warn: quiet });
   return {
-    statePath: join(stateDir, 'ship-hook.json'),
+    statePath: statePath || join(stateDir, 'ship-hook.json'),
+    agentId,
     mcpDir: MCP_DIR,
     prFacts: (ship, cwd) => lookupPrFacts(ship, cwd),
     async consult(request) {
@@ -382,7 +407,7 @@ async function realDeps() {
       return { response, drivers, source: sourceOf(vd) };
     },
     async writeReceipt({ request, response, drivers }) {
-      const r = buildReceipt({ via: 'phaedo_consult', agentId: AGENT_ID, clientId: opts.clientId, request, response, drivers });
+      const r = buildReceipt({ via: 'phaedo_consult', agentId, clientId: opts.clientId, request, response, drivers });
       await appendReceipt(stateDir, r, { cap: receiptsCapFromEnv(process.env) });
       return r.receipt_id;
     },
@@ -395,8 +420,8 @@ async function main() {
   for await (const chunk of process.stdin) raw += chunk;
   const input = JSON.parse(raw);
   // Cheap exit before importing the vault stack: most Bash calls are not ship actions.
-  if (input?.tool_name !== 'Bash') return;
-  if (input.hook_event_name === 'PreToolUse' && !classifyShipCommand(input.tool_input?.command)) return;
+  if (!reviewable(input)) return;
+  if (input.hook_event_name === 'PreToolUse' && !classifyToolCall(input.tool_name, input.tool_input)) return;
   const out = await runShipHook(input, await realDeps());
   if (out) process.stdout.write(JSON.stringify(out));
 }

package/hooks/session-start.mjs

@@ -16,12 +16,15 @@
 //
 // FAIL-SAFE: any error (no pairing, phone unreachable + no cache, render failure)
 // exits 0 with NO output, so a missing fingerprint never blocks or slows your
-// session beyond a short timeout. It never writes anything.
+// session beyond a short timeout. The one thing it writes: other agents' instruction files
+// that already carry Phaedo's block (rules-files.js) get the same profile, refreshed — never
+// a file the subject didn't opt in with `npm run rules`.
 
 import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 import { loadFingerprintPreferCache } from '../fingerprint-source.js';
 import { buildInjectionResponse } from '../projection.js';
+import { refreshExisting } from '../rules-files.js';
 
 // hooks/ lives one level under mcp/ — the sources resolve against mcp/.
 const MCP_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -46,7 +49,10 @@ async function run() {
   // Same pattern that #76 applied to escalation (cache-preferred fingerprint read).
   const vd = await loadFingerprintPreferCache(MCP_DIR);
   const response = buildInjectionResponse(vd, { requested_layers: ['all'], mode: 'standard' });
-  if (response && response.projection) emitContext(response.projection);
+  if (response && response.projection) {
+    emitContext(response.projection);
+    await refreshExisting(response.projection).catch(() => {});
+  }
 }
 
 const timeout = new Promise((res) => setTimeout(res, BUDGET_MS));

package/install.mjs

@@ -27,6 +27,9 @@ import { dirname, join, resolve } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { MCP_HOOK_MATCHER } from './ship-actions.js';
+import { targets as rulesTargets, removeFromFile } from './rules-files.js';
+import { applyAgentHooks } from './agent-hooks.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
 const SERVER_PATH = join(BASE_DIR, 'server.js');
@@ -46,7 +49,10 @@ const SHIP_HOOK_MARKER = 'hooks/pre-ship.mjs';           // identifies our ship-
 // 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 };
+// Shell commands, plus connected-tool calls whose name says they send, pay, delete or merge
+// (ship-actions.js MCP_HOOK_MATCHER) — the personal reviewer covers both.
+export const SHIP_HOOK_MATCHER = `Bash|${MCP_HOOK_MATCHER}`;
+const SHIP_HOOK_ENTRY = { matcher: SHIP_HOOK_MATCHER, timeout: 15 };
 
 // ── Client registry ──────────────────────────────────────────────────────────
 // Every supported client stores MCP servers as a top-level `mcpServers` object,
@@ -412,6 +418,7 @@ function parseArgs(argv) {
     else if (a === '--dry-run') opts.dryRun = true;
     else if (a === '--only') opts.only = argv[++i];
     else if (a === '--code-hook') opts.codeHook = true;
+    else if (a === '--agent-hooks') opts.agentHooks = true;
     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;
@@ -430,6 +437,8 @@ const HELP = `Phaedo MCP installer
   node install.mjs --pair          configure, then run the one-time pairing
   node install.mjs --code-hook     also add the Claude Code SessionStart hook
                                    (true auto-injection; ~/.claude/settings.json)
+  node install.mjs --agent-hooks   also add Phaedo's merge check to Cursor, Copilot CLI,
+                                   Codex and Gemini CLI (each one found on this computer)
   node install.mjs --capture-model <name|off>   turn the capture hook's local
                                    model detector on (e.g. llama3.1:8b) or off.
                                    Writes <state dir>/capture-model.json, which
@@ -507,6 +516,19 @@ async function main(argv) {
   if (opts.codeHook || action === 'uninstall') {
     results.push(applyCodeHook({ action, dryRun: opts.dryRun }));
   }
+  // The merge check in other agents (agent-hooks.js): opt-in on install, always cleaned up.
+  if (opts.agentHooks || action === 'uninstall') {
+    results.push(...applyAgentHooks({ action, dryRun: opts.dryRun }));
+  }
+  // Other agents' instruction files (rules-files.js): with the hook gone nothing would keep
+  // them current, so an uninstall always takes Phaedo's block back out.
+  if (action === 'uninstall') {
+    for (const t of Object.values(rulesTargets())) {
+      const r = await removeFromFile(t.file, { dryRun: opts.dryRun }).catch((e) => ({ status: 'error', error: e.message }));
+      if (r.status === 'removed') results.push({ name: t.label, status: opts.dryRun ? 'would-remove' : 'removed', detail: `took Phaedo's section out of ${t.file}` });
+      else if (r.status === 'error') results.push({ name: t.label, status: 'error', detail: `${r.error} (${t.file})` });
+    }
+  }
   // Capture-model on-switch (state-dir config file; see applyCaptureModelConfig).
   if (action === 'install' && opts.captureModel !== undefined) {
     const r = await applyCaptureModelConfig(opts.captureModel, { url: opts.captureUrl, dryRun: opts.dryRun });