total-recall-brain 3.41.5 → 3.41.6

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

@@ -19,6 +19,8 @@ export const DOC_SOURCES = [
   { 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 },
@@ -29,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() } = {}) {
@@ -47,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','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','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.

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;

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

@@ -0,0 +1,132 @@
+/**
+ * Cline Agent SDK & plugin hook adapter.
+ * Official doc: https://docs.cline.bot/sdk/plugins.md
+ */
+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 clineAdapter = {
+  id: 'cline',
+  level: 'enforced (unverified live)',
+  source: {
+    url: 'https://docs.cline.bot/sdk/plugins.md',
+    retrieved: '2026-11-04',
+    note: 'Cline SDK plugin beforeTool hooks; hookErrorMode default is ignore (fail-open)'
+  },
+  limits: [
+    'Cline defaults hookErrorMode to ignore (fail-open); requires explicit strict config',
+    'Returns { skip: true, reason } or { cancel: true } on denied calls'
+  ],
+
+  parse(input = {}) {
+    const event = input.event || 'beforeTool';
+    const toolName = input.toolName || input.tool || '';
+    const toolInput = input.input || input.params || input.toolInput || {};
+    const cwd = input.cwd || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'execute_command' || toolName === 'Bash' || toolName === 'shell') {
+      tool = 'shell';
+      command = toolInput.command || toolInput.cmd || '';
+    } else if (toolName === 'write_to_file' || toolName === 'replace_in_file' || toolName === 'Edit' || toolName === 'Write') {
+      tool = 'write';
+      filePath = toolInput.path || toolInput.file_path || '';
+    } else if (toolName === 'read_file' || toolName === 'list_files') {
+      tool = 'read';
+      filePath = toolInput.path || '';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  emit(decision, event, cwd = process.cwd()) {
+    if (decision?.decision === 'allow') {
+      const payload = { skip: false, cancel: false };
+      return { stdout: `${JSON.stringify(payload)}\n`, exitCode: 0 };
+    }
+
+    const reason = decision?.reason || `TR-PREFLIGHT gate: action denied. Run: ${decision?.fix || ACK_COMMAND}`;
+    const payload = {
+      skip: true,
+      cancel: true,
+      reason,
+      errorMessage: 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 } = {}) {
+    const clineDir = path.join(home, 'Documents', 'Cline', 'Hooks');
+    const hooksPath = path.join(clineDir, 'preflight-hook.json');
+    const added = [];
+
+    const hookDef = {
+      name: 'total-recall-preflight',
+      hookErrorMode: 'block',
+      command: 'total-recall preflight gate --harness cline',
+      timeout: 5
+    };
+
+    if (!dryRun) {
+      fs.mkdirSync(clineDir, { recursive: true });
+      fs.writeFileSync(hooksPath, `${JSON.stringify(hookDef, null, 2)}\n`);
+      added.push('managed Cline beforeTool hook');
+    }
+
+    return { settings: hooksPath, added };
+  },
+
+  verify({ home = os.homedir() } = {}) {
+    const hooksPath = path.join(home, 'Documents', 'Cline', 'Hooks', 'preflight-hook.json');
+    const installed = fs.existsSync(hooksPath);
+
+    const syntheticDeniedCall = {
+      event: 'beforeTool',
+      toolName: 'execute_command',
+      input: { command: 'rm -rf /tmp/foo' },
+      cwd: '/nonexistent-directory-without-receipt'
+    };
+
+    const out = this.emit(
+      { decision: 'deny', reason: 'receipt missing', fix: ACK_COMMAND },
+      'beforeTool',
+      syntheticDeniedCall.cwd
+    );
+
+    const exercised = out.exitCode === 2 && (out.stdout.includes('"skip":true') || out.stdout.includes('"cancel":true'));
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced (unverified live)',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default clineAdapter;