total-recall-brain 3.41.4 → 3.41.6

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;

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

@@ -0,0 +1,187 @@
+/**
+ * OpenAI Codex PreToolUse hook adapter.
+ * Official doc: https://learn.chatgpt.com/docs/hooks
+ */
+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 codexAdapter = {
+  id: 'codex',
+  level: 'enforced',
+  source: {
+    url: 'https://learn.chatgpt.com/docs/hooks',
+    retrieved: '2026-11-04',
+    note: 'Codex CLI hooks in ~/.codex/hooks.json or inline in config.toml'
+  },
+  limits: [
+    'Non-managed hooks require trust in config.toml [hooks.state]',
+    'Blocks with exit 2 and decision: "block" / permissionDecision: "deny"'
+  ],
+
+  parse(input = {}) {
+    const event = input.hook_event_name || input.event || 'PreToolUse';
+    const toolName = input.tool_name || input.toolName || '';
+    const toolInput = input.tool_input || input.toolInput || {};
+    const cwd = input.cwd || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'exec_command' || toolName === 'Bash' || toolName === 'shell') {
+      tool = 'shell';
+      command = toolInput.cmd || toolInput.command || '';
+    } else if (toolName === 'apply_patch' || toolName === 'Edit' || toolName === 'Write') {
+      tool = 'write';
+      filePath = toolInput.path || toolInput.file_path || '';
+    } else if (toolName === 'read_file' || toolName === 'Read' || /^(Glob|Grep)$/.test(toolName)) {
+      tool = 'read';
+      filePath = toolInput.path || toolInput.file_path || '';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  emit(decision, event, cwd = process.cwd()) {
+    if (decision?.decision === 'allow') {
+      return { stdout: '', exitCode: 0 };
+    }
+
+    const reason = decision?.reason || `TR-PREFLIGHT gate: action denied. Run: ${decision?.fix || ACK_COMMAND}`;
+    const payload = {
+      decision: 'block',
+      hookSpecificOutput: {
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason
+      },
+      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 codexDir = path.join(home, '.codex');
+    const hooksPath = path.join(codexDir, 'hooks.json');
+    const legacyGate = path.join(codexDir, 'hooks', 'total-recall-gate.mjs');
+    const added = [];
+    const removed = [];
+
+    let hooksConfig = { hooks: {} };
+    if (fs.existsSync(hooksPath)) {
+      try {
+        hooksConfig = JSON.parse(fs.readFileSync(hooksPath, 'utf8') || '{}');
+      } catch (err) {
+        throw new Error(`${hooksPath} is not valid JSON; fix it before installing hooks: ${err.message}`);
+      }
+    }
+    hooksConfig.hooks = hooksConfig.hooks || {};
+    hooksConfig.hooks.PreToolUse = hooksConfig.hooks.PreToolUse || [];
+
+    if (isRemove) {
+      const beforeLen = hooksConfig.hooks.PreToolUse.length;
+      hooksConfig.hooks.PreToolUse = hooksConfig.hooks.PreToolUse.filter(e =>
+        !String(e.command || '').includes('preflight') && !String(e.command || '').includes('total-recall-gate')
+      );
+      if (hooksConfig.hooks.PreToolUse.length < beforeLen) {
+        removed.push('managed PreToolUse gate');
+      }
+      if (!dryRun && fs.existsSync(hooksPath)) {
+        fs.writeFileSync(hooksPath, `${JSON.stringify(hooksConfig, null, 2)}\n`);
+      }
+      return { settings: hooksPath, added: [], removed };
+    }
+
+    // Remove legacy unmanaged gate entries (F-011)
+    const beforeLen = hooksConfig.hooks.PreToolUse.length;
+    hooksConfig.hooks.PreToolUse = hooksConfig.hooks.PreToolUse.filter(e => {
+      const cmd = String(e.command || '');
+      return !cmd.includes('total-recall-gate.mjs');
+    });
+    if (hooksConfig.hooks.PreToolUse.length < beforeLen) {
+      removed.push('legacy hand-made gate hook');
+    }
+
+    const gateCommand = 'total-recall preflight gate --harness codex';
+    const hasPreTool = hooksConfig.hooks.PreToolUse.some(e =>
+      String(e.command || '').includes('preflight gate --harness codex')
+    );
+
+    if (!hasPreTool) {
+      hooksConfig.hooks.PreToolUse.push({
+        matcher: '*',
+        command: gateCommand,
+        timeout: 10
+      });
+      added.push('managed PreToolUse gate');
+    }
+
+    if (!dryRun && (added.length || removed.length)) {
+      fs.mkdirSync(codexDir, { recursive: true });
+      if (fs.existsSync(hooksPath)) {
+        fs.copyFileSync(hooksPath, `${hooksPath}.bak-total-recall`);
+      }
+      fs.writeFileSync(hooksPath, `${JSON.stringify(hooksConfig, null, 2)}\n`);
+    }
+
+    return { settings: hooksPath, added, removed };
+  },
+
+  verify({ home = os.homedir() } = {}) {
+    const hooksPath = path.join(home, '.codex', '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 codex'));
+      } catch { /* unparseable */ }
+    }
+
+    const syntheticDeniedCall = {
+      hook_event_name: 'PreToolUse',
+      tool_name: 'exec_command',
+      tool_input: { cmd: '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":"block"') || out.stdout.includes('"permissionDecision":"deny"'));
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default codexAdapter;

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

@@ -0,0 +1,158 @@
+/**
+ * Cursor IDE & agent hook adapter.
+ * Official doc: https://cursor.com/docs/hooks
+ */
+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 cursorAdapter = {
+  id: 'cursor',
+  level: 'enforced (unverified live)',
+  source: {
+    url: 'https://cursor.com/docs/hooks',
+    retrieved: '2026-11-04',
+    note: 'Cursor hooks in ~/.cursor/hooks.json and .cursor/hooks.json'
+  },
+  limits: [
+    'Cursor defaults to fail-open unless failClosed: true is set',
+    'User-level hooks apply across workspaces; requires failClosed flag'
+  ],
+
+  parse(input = {}) {
+    const event = input.event || input.hookEventName || 'preToolUse';
+    const toolName = input.toolName || input.tool || '';
+    const toolInput = input.toolInput || input.input || {};
+    const cwd = input.cwd || input.workspaceRoot || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (event === 'beforeShellExecution' || toolName === 'execute' || toolName === 'terminal' || toolName === 'Bash') {
+      tool = 'shell';
+      command = input.command || toolInput.command || toolInput.cmd || '';
+    } else if (event === 'beforeReadFile' || toolName === 'readFile' || toolName === 'Read') {
+      tool = 'read';
+      filePath = input.file || input.path || toolInput.file || toolInput.path || '';
+    } else if (toolName === 'edit' || toolName === 'Write' || toolName === 'Edit') {
+      tool = 'write';
+      filePath = input.file || input.path || toolInput.file || toolInput.path || '';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  emit(decision, event, cwd = process.cwd()) {
+    if (decision?.decision === 'allow') {
+      const payload = { permission: '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 = {
+      permission: '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 } = {}) {
+    const cursorDir = path.join(home, '.cursor');
+    const hooksPath = path.join(cursorDir, 'hooks.json');
+    const added = [];
+
+    let config = { hooks: {}, failClosed: true };
+    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.failClosed = true;
+    config.hooks = config.hooks || {};
+    config.hooks.preToolUse = config.hooks.preToolUse || [];
+
+    const gateCommand = 'total-recall preflight gate --harness cursor';
+    const hasHook = config.hooks.preToolUse.some(e =>
+      String(e.command || '').includes('preflight gate --harness cursor')
+    );
+
+    if (!hasHook) {
+      config.hooks.preToolUse.push({
+        matcher: '*',
+        command: gateCommand,
+        timeout: 10
+      });
+      added.push('managed preToolUse gate (failClosed: true)');
+    }
+
+    if (!dryRun && added.length) {
+      fs.mkdirSync(cursorDir, { 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, '.cursor', '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 cursor'));
+      } catch { /* unparseable */ }
+    }
+
+    const syntheticDeniedCall = {
+      event: 'preToolUse',
+      toolName: 'execute',
+      toolInput: { command: '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('"permission":"deny"');
+
+    return {
+      installed,
+      exercised,
+      level: installed ? 'enforced (unverified live)' : 'enforced (unverified live)',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default cursorAdapter;

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

@@ -0,0 +1,157 @@
+/**
+ * Devin CLI & Windsurf Cascade hook adapter.
+ * Official doc: https://docs.devin.ai/cli/extensibility/hooks/lifecycle-hooks
+ */
+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 devinAdapter = {
+  id: 'devin',
+  aliases: ['windsurf'],
+  level: 'enforced (unverified live)',
+  source: {
+    url: 'https://docs.devin.ai/cli/extensibility/hooks/lifecycle-hooks',
+    retrieved: '2026-11-04',
+    note: 'Devin/Windsurf hooks in ~/.config/devin/config.json or .devin/hooks.v1.json'
+  },
+  limits: [
+    'Hooks do not run when Devin operates in Restricted Mode',
+    'Exit 2 blocks tool execution in PreToolUse'
+  ],
+
+  parse(input = {}) {
+    const event = input.event || input.hookEventName || 'PreToolUse';
+    const toolName = input.tool || input.toolName || input.tool_name || '';
+    const toolInput = input.toolInput || input.input || {};
+    const cwd = input.cwd || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'exec' || toolName === 'Bash' || toolName === 'shell') {
+      tool = 'shell';
+      command = toolInput.cmd || toolInput.command || '';
+    } else if (toolName === 'edit' || toolName === 'write') {
+      tool = 'write';
+      filePath = toolInput.path || toolInput.file || '';
+    } else if (toolName === 'read') {
+      tool = 'read';
+      filePath = toolInput.path || toolInput.file || '';
+    }
+
+    return {
+      event,
+      tool,
+      command,
+      path: filePath,
+      cwd,
+      raw: input
+    };
+  },
+
+  emit(decision, event, cwd = process.cwd()) {
+    if (decision?.decision === 'allow') {
+      return { stdout: '', 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 } = {}) {
+    const devinDir = path.join(home, '.config', 'devin');
+    const hooksPath = path.join(devinDir, 'hooks.json');
+    const added = [];
+
+    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 || [];
+
+    const gateCommand = 'total-recall preflight gate --harness devin';
+    const hasHook = config.hooks.PreToolUse.some(e =>
+      String(e.command || '').includes('preflight gate --harness devin')
+    );
+
+    if (!hasHook) {
+      config.hooks.PreToolUse.push({
+        matcher: '*',
+        command: gateCommand,
+        timeout: 10
+      });
+      added.push('managed PreToolUse gate');
+    }
+
+    if (!dryRun && added.length) {
+      fs.mkdirSync(devinDir, { 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, '.config', 'devin', '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 devin'));
+      } catch { /* unparseable */ }
+    }
+
+    const syntheticDeniedCall = {
+      event: 'PreToolUse',
+      tool: 'exec',
+      toolInput: { cmd: '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 (unverified live)',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default devinAdapter;