total-recall-brain 3.41.4 → 3.41.6

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/documentation.mjs

@@ -14,6 +14,16 @@ export const DOC_SOURCES = [
   { id: 'muse', index: 'https://dev.meta.ai/docs/muse-code', prefix: 'https://dev.meta.ai/docs/muse-code' },
   { id: 'pi', repo: 'badlogic/pi-mono', branch: 'main', directories: ['packages/coding-agent/docs/'], index: 'https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/README.md' },
   { id: 'hermes', repo: 'NousResearch/hermes-agent', branch: 'main', directories: ['website/docs/'], index: 'https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/reference/cli-commands.md' },
+  { id: 'devin', index: 'https://docs.devin.ai/llms.txt', prefix: 'https://docs.devin.ai/', catalog:true },
+  { id: 'windsurf', index: 'https://docs.windsurf.com/llms.txt', prefix: 'https://docs.windsurf.com/', catalog:true },
+  { id: 'cline', index: 'https://docs.cline.bot/llms.txt', prefix: 'https://docs.cline.bot/', catalog:true },
+  { id: 'openclaw', index: 'https://docs.openclaw.ai/llms.txt', prefix: 'https://docs.openclaw.ai/', catalog:true },
+  { id: 'aider', index: 'https://aider.chat/docs/', prefix: 'https://aider.chat/docs/' },
+  { id: 'goose', index: 'https://block.github.io/goose/docs/quickstart', prefix: 'https://block.github.io/goose/docs/' },
+  { id: 'openhands', index: 'https://docs.openhands.dev/llms.txt', prefix: 'https://docs.openhands.dev/', catalog:true },
+  { id: 'replit', index: 'https://docs.replit.com/llms.txt', prefix: 'https://docs.replit.com/', catalog:true },
+  { id: 'lovable', index: 'https://docs.lovable.dev/llms.txt', prefix: 'https://docs.lovable.dev/', catalog:true },
+  { id: 'ollama', index: 'https://docs.ollama.com/llms.txt', prefix: 'https://docs.ollama.com/', catalog:true },
 ];
 const hash = value => crypto.createHash('sha256').update(value).digest('hex');
 const TTL = 24 * 60 * 60 * 1000;
@@ -21,7 +31,11 @@ function pageFile(directory,id,file){if(!/^[a-f0-9]{64}-[a-f0-9]{64}\.txt$/.test
 function atomic(file, value) { fs.mkdirSync(path.dirname(file), { recursive: true }); const temp = `${file}.${process.pid}.tmp`; fs.writeFileSync(temp, value, { mode: 0o600 }); fs.renameSync(temp, file); }
 export function documentationDirectory() {
   const brain = process.env.TR_SECRETS_BRAIN || path.join(process.env.AGENT_DIR || path.join(os.homedir(), '.agent'), 'skills/total-recall');
-  return path.join(brain, 'memory-derived/cli-agents/docs');
+  const directory = path.join(brain, 'memory-derived/meta-harness/docs');
+  // Keep the downloaded pages when the old directory name is still on disk.
+  const legacy = path.join(brain, 'memory-derived/cli-agents/docs');
+  if (!fs.existsSync(directory) && fs.existsSync(legacy)) { fs.mkdirSync(path.dirname(directory), { recursive: true }); fs.renameSync(legacy, directory); }
+  return directory;
 }
 function metadata(directory, id) { try { return JSON.parse(fs.readFileSync(path.join(directory,id,'index.json'),'utf8')); } catch { return null; } }
 export function documentationStatus({ directory = documentationDirectory(), agent, now = Date.now() } = {}) {
@@ -39,11 +53,11 @@ export function documentationStatus({ directory = documentationDirectory(), agen
   return { ok:agents.every(row=>row.fresh), directory, agents };
 }
 async function download(url, fetchImpl) {
-  const allowed = new Set(['code.claude.com','claude.com','platform.claude.com','docs.anthropic.com','anthropic.com','developers.openai.com','openai.com','help.openai.com','learn.chatgpt.com','chatgpt.com','antigravity.google','cursor.com','docs.x.ai','dev.meta.ai','raw.githubusercontent.com','api.github.com']);
+  const allowed = new Set(['code.claude.com','claude.com','platform.claude.com','docs.anthropic.com','anthropic.com','developers.openai.com','openai.com','help.openai.com','learn.chatgpt.com','chatgpt.com','antigravity.google','cursor.com','docs.x.ai','dev.meta.ai','docs.devin.ai','docs.windsurf.com','windsurf.com','docs.cline.bot','docs.openclaw.ai','aider.chat','docs.replit.com','docs.lovable.dev','docs.ollama.com','block.github.io','docs.openhands.dev','raw.githubusercontent.com','api.github.com']);
   let target = new URL(url);
   for(let redirects=0;redirects<5;redirects++) {
     if(target.protocol!=='https:' || target.username || target.password || !allowed.has(target.hostname)) throw new Error(`Unapproved official documentation origin: ${target.hostname}`);
-    const response=await fetchImpl(target,{redirect:'manual',signal:AbortSignal.timeout(20000),headers:{'User-Agent':'Total-Recall-CLI-Agents-Docs','Accept':'*/*'}});
+    const response=await fetchImpl(target,{redirect:'manual',signal:AbortSignal.timeout(20000),headers:{'User-Agent':'Total-Recall-Meta-Harness-Docs','Accept':'*/*'}});
     if(response.status>=300 && response.status<400){target=new URL(response.headers.get('location'),target);continue;}
     // Some entries advertise Markdown exports which no longer exist while the
     // same official HTML document remains available. Fetch that representation.
@@ -63,15 +77,16 @@ function links(text,base,prefix) {
   for(const match of text.matchAll(/\]\(([^\s)]+)(?:\s+[^)]*)?\)/g)){try{values.push(new URL(match[1],base).href);}catch{}}
   for(const match of text.matchAll(/href=["']([^"']+)["']/g)) {try{values.push(new URL(match[1],base).href);}catch{}}
   return [...new Set(values.map(value=>{try{const url=new URL(value);url.hash='';url.search='';url.pathname=url.pathname.replace(/\/{2,}/g,'/').replace(/\/$/,'') || '/';return url.href;}catch{return '';}}))]
-    .filter(url=>url.startsWith(prefix) && !/\.(png|jpg|jpeg|svg|gif|css|js|woff2?|ico|pdf)$/i.test(url));
+    .filter(url=>url.startsWith(prefix) && !/%3[CE]|[<>"'`\s]/i.test(url) && !/\.(png|jpg|jpeg|svg|gif|css|js|woff2?|ico|pdf|json|ya?ml|xml|zip|gz|tgz|lock)$/i.test(url));
 }
 export async function refreshDocumentation({ directory = documentationDirectory(), agent, fetchImpl = fetch, now = () => new Date(), maxPages = 1500 } = {}) {
   const sources=agent?DOC_SOURCES.filter(source=>source.id===agent):DOC_SOURCES;
   if(!sources.length)throw new Error('Unknown documentation adapter');
   const reports=[];
   for(const source of sources) {
-    const previous=metadata(directory,source.id), pages=[], queue=[source.index], seen=new Set(), queued=new Set(queue), errors=[];
-    const enqueue=url=>{if(!queued.has(url)){queued.add(url);queue.push(url);}};
+    const previous=metadata(directory,source.id), pages=[], queue=[source.index], seen=new Set(), queued=new Set(queue), errors=[], discovered=new Set(), skipped=[];
+    // `found` marks a link taken from HTML navigation. The vendor's catalog, the index and the repository tree are authoritative; a link found by scraping is not.
+    const enqueue=(url,found=false)=>{if(!queued.has(url)){queued.add(url);queue.push(url);if(found)discovered.add(url);}};
     try {
       if(source.repo) {
         const tree=JSON.parse(await download(`https://api.github.com/repos/${source.repo}/git/trees/${source.branch}?recursive=1`,fetchImpl));
@@ -85,25 +100,33 @@ export async function refreshDocumentation({ directory = documentationDirectory(
         if(seen.size>maxPages)throw new Error('Official documentation exceeds configured page budget');
         const downloads=await Promise.allSettled(batch.map(async url=>({url,text:await download(url,fetchImpl)})));
         for(let index=0;index<downloads.length;index++) {
-          const result=downloads[index];if(result.status==='rejected'){errors.push({url:batch[index],error:result.reason.message});continue;}
+          const result=downloads[index];
+          if(result.status==='rejected'){
+            const message=result.reason.message;
+            // A scraped link that is gone (404 or 410) is a stale or illustrative link, such as a placeholder in a code sample. It is reported as skipped and does not fail the refresh. Anything else, and anything the vendor itself lists, stays a failure.
+            if(discovered.has(batch[index]) && /HTTP (404|410)\b/.test(message)){skipped.push({url:batch[index],error:message});continue;}
+            // A page that redirects off the approved origins (for example a trust-center portal) is an external link, not documentation. It is never followed, and it is reported. The index itself redirecting away still fails the refresh.
+            if(batch[index]!==source.index && /^Unapproved official documentation origin/.test(message)){skipped.push({url:batch[index],error:message});continue;}
+            errors.push({url:batch[index],error:message});continue;
+          }
           const {url,text}=result.value;
           const sha256=hash(text),file=`${hash(url)}-${sha256}.txt`;
           atomic(path.join(directory,source.id,file),text);
           pages.push({url,file,sha256,bytes:Buffer.byteLength(text)});
           // A published llms index is the authoritative documentation catalog.
           // HTML navigation also contains unrelated and obsolete marketing links.
-          if(source.prefix && (!source.catalog || url.endsWith('llms.txt')))for(const link of links(text,url,source.prefix))enqueue(link);
+          if(source.prefix && (!source.catalog || url.endsWith('llms.txt')))for(const link of links(text,url,source.prefix))enqueue(link,!url.endsWith('llms.txt'));
         }
       }
       const checkedAt=now().toISOString();
       if(errors.length){
         const error=`${errors.length} official document(s) failed: ${errors[0].error}`;
         const preserved=previous?.complete?previous:{id:source.id,complete:false,pages};
-        atomic(path.join(directory,source.id,'index.json'),JSON.stringify({...preserved,lastAttempt:checkedAt,error,failedCount:errors.length,failures:errors},null,2));
-        reports.push({id:source.id,ok:false,error,pages:preserved.pages?.length || 0,downloadedPages:pages.length,failedCount:errors.length,failures:errors});continue;
+        atomic(path.join(directory,source.id,'index.json'),JSON.stringify({...preserved,lastAttempt:checkedAt,error,failedCount:errors.length,failures:errors,...(skipped.length?{skipped}:{})},null,2));
+        reports.push({id:source.id,ok:false,error,pages:preserved.pages?.length || 0,downloadedPages:pages.length,failedCount:errors.length,failures:errors,...(skipped.length?{skippedCount:skipped.length,skipped}:{})});continue;
       }
-      atomic(path.join(directory,source.id,'index.json'),JSON.stringify({id:source.id,complete:true,checkedAt,lastAttempt:checkedAt,pages},null,2));
-      reports.push({id:source.id,ok:true,pages:pages.length});
+      atomic(path.join(directory,source.id,'index.json'),JSON.stringify({id:source.id,complete:true,checkedAt,lastAttempt:checkedAt,pages,...(skipped.length?{skipped}:{})},null,2));
+      reports.push({id:source.id,ok:true,pages:pages.length,...(skipped.length?{skippedCount:skipped.length,skipped}:{})});
     } catch(error) {
       atomic(path.join(directory,source.id,'index.json'),JSON.stringify({...previous,id:source.id,lastAttempt:now().toISOString(),error:error.message},null,2));
       reports.push({id:source.id,ok:false,error:error.message,pages:previous?.pages?.length || 0});
@@ -142,9 +165,12 @@ export function readDocumentation({agent,url,directory=documentationDirectory()}
 export function searchDocumentation({agent,query,directory=documentationDirectory()}) {
   if(typeof query!=='string' || !query.trim())throw new Error('Documentation query required');
   const sources=agent?DOC_SOURCES.filter(source=>source.id===agent):DOC_SOURCES;
-  const matches=[];
+  const matches=[],phrase=query.trim().toLowerCase(),terms=phrase.split(/\s+/).filter(Boolean);
   for(const source of sources)for(const page of metadata(directory,source.id)?.pages || []) {
-    const doc=readDocumentation({agent:source.id,url:page.url,directory});const index=doc.content.toLowerCase().indexOf(query.toLowerCase());
+    const doc=readDocumentation({agent:source.id,url:page.url,directory});const text=doc.content.toLowerCase();
+    // The exact phrase wins. Otherwise a page matches when it contains every term, in any order, so a query of two words is not limited to pages where they happen to be adjacent.
+    let index=text.indexOf(phrase);
+    if(index<0 && terms.length>1 && terms.every(term=>text.includes(term)))index=Math.min(...terms.map(term=>text.indexOf(term)));
     if(index>=0)matches.push({agent:source.id,url:page.url,excerpt:doc.content.slice(Math.max(0,index-120),index+600)});
     if(matches.length>=30)return {matches,truncated:true};
   }

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/executor.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { runWorker, runProcess, getActiveAdapters } from './worker.mjs';
+import { runWorker, runProcess, getActiveAdapters, notReady } from './worker.mjs';
 
 async function hostModule(name) {
   const selected = process.env.TR_PACKAGE_ROOT;
@@ -36,7 +36,7 @@ export async function listTargets() {
 
 export function workerProgram(request) {
   const source = fs.readFileSync(new URL('./worker.mjs', import.meta.url), 'utf8');
-  return source + '\nrunWorker(' + JSON.stringify(request) + ').then(result=>console.log(JSON.stringify(result))).catch(()=>{console.error("Selected agent worker failed");process.exitCode=1;});\n';
+  return source + '\nrunWorker(' + JSON.stringify(request) + ').then(result=>console.log(JSON.stringify(result))).catch(error=>{console.error(String(error?.message||"Selected agent worker failed"));process.exitCode=1;});\n';
 }
 
 export async function executeOnNode(node, request, { worker = runWorker, processRunner = runProcess, mesh, access } = {}) {
@@ -49,8 +49,8 @@ export async function executeOnNode(node, request, { worker = runWorker, process
   const resolved = access.resolveNodeAccess(target);
   const args = access.buildSshArgs(resolved, { command: 'export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"; exec node --input-type=module', extraOptions: ['BatchMode=yes', 'ConnectTimeout=10'] });
   if (!args) throw new Error('Selected mesh node has no verified SSH access');
-  const result = await processRunner('ssh', args, { input: workerProgram(request), timeoutMs: request.operation === 'inspect' ? 120000 : 330000 });
-  if (result.reason || result.exitCode !== 0) throw new Error('Selected mesh worker failed; verify node access, workspace and agent installation');
+  const result = await processRunner('ssh', args, { input: workerProgram(request), timeoutMs: request.operation === 'inspect' ? 120000 : (request.timeoutMs || 900000) + 30000 });
+  if (result.reason || result.exitCode !== 0) throw notReady(`Worker on ${node} failed: ${String(result.stderr || result.reason || 'verify node access, workspace and agent installation').trim().slice(0, 400)}`);
   try { return JSON.parse(result.stdout); } catch { throw new Error('Selected mesh worker returned invalid data'); }
 }
 

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/agy.mjs

@@ -0,0 +1,187 @@
+/**
+ * Google Antigravity (agy) PreToolUse & lifecycle hook adapter.
+ * Official doc: https://antigravity.google/docs/hooks?tab=cli
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const ACK_COMMAND = 'total-recall tr-preflight --ack --task "<task>" --action read,edit,test';
+
+export const agyAdapter = {
+  id: 'agy',
+  aliases: ['antigravity'],
+  level: 'enforced',
+  source: {
+    url: 'https://antigravity.google/docs/hooks?tab=cli',
+    retrieved: '2026-11-04',
+    note: 'Antigravity CLI hooks in ~/.gemini/config/hooks.json or .agents/hooks.json'
+  },
+  readablePaths: [
+    /\/\.gemini\/antigravity\/brain\/[^/]+\/\.system_generated\/tasks\/[^/]+\.log$/,
+    /\/\.gemini\/antigravity\/brain\/[^/]+\/\.system_generated\/steps\/[^/]+\/output\.txt$/
+  ],
+  limits: [
+    'Hooks receive camelCase toolCall fields: toolCall.name and toolCall.args',
+    'PreToolUse blocks execution with decision: "deny" and exit code 2'
+  ],
+
+  parse(input = {}) {
+    const event = input.event || input.hookEventName || 'PreToolUse';
+    const toolCall = input.toolCall || {};
+    const name = toolCall.name || input.toolName || input.tool_name || '';
+    const args = toolCall.args || input.toolArgs || input.tool_input || {};
+    const cwd = input.cwd || input.workspacePaths?.[0] || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (name === 'run_command' || name === 'Bash') {
+      tool = 'shell';
+      command = args.CommandLine || args.command || '';
+    } else if (name === 'read_file' || /^(Read|Glob|Grep)$/.test(name)) {
+      tool = 'read';
+      filePath = args.Path || args.file_path || args.path || '';
+    } else if (name === 'write_file' || name === 'edit_file' || /^(Edit|Write)$/.test(name)) {
+      tool = 'write';
+      filePath = args.Path || args.file_path || args.path || '';
+    } else if (name === 'search_web' || /^(WebFetch|WebSearch)$/.test(name)) {
+      tool = 'web';
+    } else if (/^(ask_question|show_message|manage_task)$/.test(name)) {
+      tool = 'meta';
+    } else if (/^(invoke_subagent|send_message|manage_subagents)$/.test(name)) {
+      tool = 'agent';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  emit(decision, event, cwd = process.cwd()) {
+    if (decision?.decision === 'allow') {
+      const payload = { decision: 'allow' };
+      return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 0 };
+    }
+
+    const reason = decision?.reason || `TR-PREFLIGHT gate: action denied. Run: ${decision?.fix || ACK_COMMAND}`;
+    const payload = {
+      decision: 'deny',
+      reason,
+      fix: decision?.fix || ACK_COMMAND
+    };
+    return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 2 };
+  },
+
+  async run({ stdin, decideWith }) {
+    const parsed = this.parse(stdin);
+    const decision = decideWith({
+      tool: parsed.tool,
+      command: parsed.command,
+      path: parsed.path,
+      cwd: parsed.cwd
+    });
+    return this.emit(decision, parsed.event, parsed.cwd);
+  },
+
+  install({ home = os.homedir(), dryRun = false, remove = false, off = false } = {}) {
+    const isRemove = remove || off;
+    const geminiDir = path.join(home, '.gemini', 'config');
+    const hooksPath = path.join(geminiDir, 'hooks.json');
+    const added = [];
+    const removed = [];
+
+    let config = { hooks: {} };
+    if (fs.existsSync(hooksPath)) {
+      try {
+        config = JSON.parse(fs.readFileSync(hooksPath, 'utf8') || '{}');
+      } catch (err) {
+        throw new Error(`${hooksPath} is not valid JSON; fix it before installing hooks: ${err.message}`);
+      }
+    }
+    config.hooks = config.hooks || {};
+    config.hooks.PreToolUse = config.hooks.PreToolUse || [];
+
+    if (isRemove) {
+      const beforeLen = config.hooks.PreToolUse.length;
+      config.hooks.PreToolUse = config.hooks.PreToolUse.filter(e =>
+        !String(e.command || '').includes('preflight')
+      );
+      if (config.hooks.PreToolUse.length < beforeLen) {
+        removed.push('managed PreToolUse gate');
+      }
+      if (!dryRun && fs.existsSync(hooksPath)) {
+        fs.writeFileSync(hooksPath, `${JSON.stringify(config, null, 2)}\n`);
+      }
+      return { settings: hooksPath, added: [], removed };
+    }
+
+    const gateCommand = 'total-recall preflight gate --harness agy';
+    const hasPreTool = config.hooks.PreToolUse.some(e =>
+      String(e.command || '').includes('preflight gate --harness agy')
+    );
+
+    if (!hasPreTool) {
+      config.hooks.PreToolUse.push({
+        matcher: '*',
+        command: gateCommand,
+        timeout: 10
+      });
+      added.push('managed PreToolUse gate');
+    }
+
+    if (!dryRun && added.length) {
+      fs.mkdirSync(geminiDir, { recursive: true });
+      if (fs.existsSync(hooksPath)) {
+        fs.copyFileSync(hooksPath, `${hooksPath}.bak-total-recall`);
+      }
+      fs.writeFileSync(hooksPath, `${JSON.stringify(config, null, 2)}\n`);
+    }
+
+    return { settings: hooksPath, added };
+  },
+
+  verify({ home = os.homedir() } = {}) {
+    const hooksPath = path.join(home, '.gemini', 'config', 'hooks.json');
+    let installed = false;
+    if (fs.existsSync(hooksPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(hooksPath, 'utf8') || '{}');
+        const preHooks = config.hooks?.PreToolUse || [];
+        installed = preHooks.some(e => String(e.command || '').includes('preflight gate --harness agy'));
+      } catch { /* unparseable */ }
+    }
+
+    const syntheticDeniedCall = {
+      event: 'PreToolUse',
+      toolCall: {
+        name: 'run_command',
+        args: { CommandLine: 'rm -rf /tmp/foo' }
+      },
+      cwd: '/nonexistent-directory-without-receipt'
+    };
+
+    const out = this.emit(
+      { decision: 'deny', reason: 'receipt missing', fix: ACK_COMMAND },
+      'PreToolUse',
+      syntheticDeniedCall.cwd
+    );
+
+    const exercised = out.exitCode === 2 && out.stdout.includes('"decision":"deny"');
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default agyAdapter;

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/claude.mjs

@@ -0,0 +1,275 @@
+/**
+ * Claude Code PreToolUse & UserPromptSubmit adapter.
+ * Official doc: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const ACK_COMMAND = 'total-recall tr-preflight --ack --task "<task>" --action read,edit,test';
+
+export const claudeAdapter = {
+  id: 'claude',
+  level: 'enforced',
+  source: {
+    url: 'https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview',
+    retrieved: '2026-11-04',
+    note: 'Claude Code hook configuration in settings.json with PreToolUse and UserPromptSubmit'
+  },
+  readablePaths: [
+    /\/\.claude\/projects\/[^/]+\/[^/]+\/tool-results\/[^/]+$/
+  ],
+  limits: [
+    'UserPromptSubmit hook is advisory-only per ENFORCE-R1 and never blocks turn',
+    'PreToolUse blocks tool executions with exit 2 or permissionDecision: "deny"'
+  ],
+
+  /**
+   * Parse Claude Code native hook JSON from stdin into normalized shape:
+   * { event, tool, command, path, cwd }
+   */
+  parse(input = {}) {
+    const event = input.hook_event_name || (input.tool_name ? 'PreToolUse' : 'UserPromptSubmit');
+    const toolName = input.tool_name || '';
+    const cwd = input.cwd || process.cwd();
+    const toolInput = input.tool_input || {};
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'Bash') {
+      tool = 'shell';
+      command = toolInput.command || '';
+    } else if (/^(Read|Glob|Grep)$/.test(toolName)) {
+      tool = 'read';
+      filePath = toolInput.file_path || toolInput.path || toolInput.pattern || '';
+    } else if (/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(toolName)) {
+      tool = 'write';
+      filePath = toolInput.file_path || toolInput.notebook_path || '';
+    } else if (/^(WebFetch|WebSearch)$/.test(toolName)) {
+      tool = 'web';
+    } else if (/^mcp__ccd_turn__/.test(toolName)) {
+      tool = 'ui';
+    } else if (/^mcp__/.test(toolName)) {
+      tool = 'mcp';
+    } else if (toolName === 'Agent') {
+      tool = 'agent';
+    } else if (/^(ToolSearch|Skill|AskUserQuestion)$/.test(toolName)) {
+      tool = 'meta';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  /**
+   * Emit Claude Code native response: { stdout, exitCode }
+   */
+  emit(decision, event, cwd = process.cwd()) {
+    if (event === 'UserPromptSubmit') {
+      // ENFORCE-R1: Prompt hooks never block
+      if (decision?.decision === 'deny') {
+        const payload = {
+          hookSpecificOutput: {
+            hookEventName: 'UserPromptSubmit',
+            additionalContext: `TR-PREFLIGHT FAILED for ${cwd}: ${decision.reason || 'check failed'}. First read the full context capsule (never truncate it), then run: ${decision.fix || ACK_COMMAND}`
+          }
+        };
+        return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 0 };
+      }
+      return { stdout: '', exitCode: 0 };
+    }
+
+    // PreToolUse
+    if (decision?.decision === 'allow') {
+      return { stdout: '', exitCode: 0 };
+    }
+
+    // Denied
+    const payload = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: decision?.reason || `TR-PREFLIGHT gate: action denied. Run: ${decision?.fix || ACK_COMMAND}`
+      }
+    };
+    return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 2 };
+  },
+
+  /**
+   * Run the gate pipeline for Claude Code
+   */
+  async run({ stdin, decideWith }) {
+    const parsed = this.parse(stdin);
+    const decision = decideWith({
+      tool: parsed.tool,
+      command: parsed.command,
+      path: parsed.path,
+      cwd: parsed.cwd
+    });
+    return this.emit(decision, parsed.event, parsed.cwd);
+  },
+
+  /**
+   * Install Claude Code managed hooks in settings.json, removing the stopgap
+   */
+  install({ home = os.homedir(), dryRun = false, remove = false, off = false } = {}) {
+    const isRemove = remove || off;
+    const claudeDir = path.join(home, '.claude');
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const stopgapPath = path.join(claudeDir, 'hooks', 'total-recall-preflight.mjs');
+    const added = [];
+    const removed = [];
+
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8') || '{}');
+      } catch (err) {
+        throw new Error(`${settingsPath} is not valid JSON; fix it before installing hooks: ${err.message}`);
+      }
+    }
+
+    const hooks = settings.hooks || (settings.hooks = {});
+
+    if (isRemove) {
+      for (const event of ['PreToolUse', 'UserPromptSubmit', 'SessionStart', 'PostToolUse']) {
+        if (Array.isArray(hooks[event])) {
+          const beforeLen = hooks[event].length;
+          hooks[event] = hooks[event].filter(entry => {
+            const subHooks = entry.hooks || [];
+            return !subHooks.some(h => String(h.command || '').includes('preflight') || String(h.command || '').includes('total-recall-preflight'));
+          });
+          if (hooks[event].length < beforeLen) {
+            removed.push(`managed ${event} hook entry`);
+          }
+        }
+      }
+      if (!dryRun && (removed.length || fs.existsSync(settingsPath))) {
+        fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+      }
+      return { settings: settingsPath, added: [], removed };
+    }
+
+    // 1. Remove stopgap references if present
+    for (const event of ['PreToolUse', 'UserPromptSubmit', 'SessionStart', 'PostToolUse']) {
+      if (Array.isArray(hooks[event])) {
+        const beforeLen = hooks[event].length;
+        hooks[event] = hooks[event].filter(entry => {
+          const subHooks = entry.hooks || [];
+          return !subHooks.some(h => String(h.command || '').includes('total-recall-preflight.mjs'));
+        });
+        if (hooks[event].length < beforeLen) {
+          removed.push(`stopgap ${event} hook entry`);
+        }
+      }
+    }
+
+    // Remove stopgap file on disk if not dryRun
+    if (!dryRun && fs.existsSync(stopgapPath)) {
+      try {
+        fs.unlinkSync(stopgapPath);
+        removed.push('total-recall-preflight.mjs file');
+      } catch { /* ignore */ }
+    }
+
+    // 2. Add managed preflight gate entries
+    const gateCommand = 'total-recall preflight gate --harness claude';
+    const remindCommand = 'total-recall preflight remind';
+
+    // PreToolUse: match all tools
+    hooks.PreToolUse = hooks.PreToolUse || [];
+    const hasPreTool = hooks.PreToolUse.some(e =>
+      (e.hooks || []).some(h => String(h.command || '').includes('preflight gate --harness claude'))
+    );
+    if (!hasPreTool) {
+      hooks.PreToolUse.push({
+        matcher: '*',
+        hooks: [{
+          type: 'command',
+          command: gateCommand,
+          timeout: 5
+        }]
+      });
+      added.push('managed PreToolUse gate');
+    }
+
+    // UserPromptSubmit: advisory reminder
+    hooks.UserPromptSubmit = hooks.UserPromptSubmit || [];
+    const hasPrompt = hooks.UserPromptSubmit.some(e =>
+      (e.hooks || []).some(h => String(h.command || '').includes('preflight remind'))
+    );
+    if (!hasPrompt) {
+      hooks.UserPromptSubmit.push({
+        hooks: [{
+          type: 'command',
+          command: remindCommand,
+          timeout: 5
+        }]
+      });
+      added.push('managed UserPromptSubmit reminder');
+    }
+
+    if (!dryRun && (added.length || removed.length)) {
+      fs.mkdirSync(claudeDir, { recursive: true });
+      if (fs.existsSync(settingsPath)) {
+        fs.copyFileSync(settingsPath, `${settingsPath}.bak-total-recall`);
+      }
+      fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    }
+
+    return { settings: settingsPath, added, removed };
+  },
+
+  /**
+   * Verify installed hook with a synthetic denied tool call
+   */
+  verify({ home = os.homedir() } = {}) {
+    const settingsPath = path.join(home, '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+      return { installed: false, exercised: false, reason: 'settings.json not found' };
+    }
+    let settings;
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8') || '{}');
+    } catch {
+      return { installed: false, exercised: false, reason: 'settings.json is unparseable' };
+    }
+    const preHooks = settings.hooks?.PreToolUse || [];
+    const installed = preHooks.some(e =>
+      (e.hooks || []).some(h => String(h.command || '').includes('preflight gate --harness claude'))
+    );
+
+    // Exercise with synthetic denied payload
+    const syntheticDeniedCall = {
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Bash',
+      tool_input: { command: 'git status' },
+      cwd: '/nonexistent-directory-without-receipt'
+    };
+
+    const out = this.emit(
+      { decision: 'deny', reason: 'receipt missing', fix: ACK_COMMAND },
+      'PreToolUse',
+      syntheticDeniedCall.cwd
+    );
+
+    const exercised = out.exitCode === 2 && out.stdout.includes('"permissionDecision":"deny"');
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default claudeAdapter;