total-recall-brain 3.41.4 → 3.41.6

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

@@ -0,0 +1,183 @@
+/**
+ * DeepSeek Harness (DSH) PreToolUse hook adapter.
+ * Migrates legacy tr-first.sh / tr-wrapper.sh into managed preflight gate.
+ */
+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 dshAdapter = {
+  id: 'dsh',
+  level: 'enforced',
+  source: {
+    note: 'DeepSeek Harness hook configuration in ~/.dsh/hooks/hooks.json',
+    retrieved: '2026-11-04'
+  },
+  limits: [
+    'Claude-compatible PreToolUse contract: exit code 2 blocks execution',
+    'Repository sweep checks enforce Total Recall consult requirement'
+  ],
+
+  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 === 'Bash' || toolName === 'shell') {
+      tool = 'shell';
+      command = toolInput.command || toolInput.cmd || '';
+    } else if (toolName === 'Edit' || toolName === 'Write') {
+      tool = 'write';
+      filePath = toolInput.file_path || toolInput.path || '';
+    } else if (toolName === 'Read' || /^(Glob|Grep)$/.test(toolName)) {
+      tool = 'read';
+      filePath = toolInput.file_path || toolInput.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: 'deny',
+      permissionDecision: '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 dshDir = path.join(home, '.dsh', 'hooks');
+    const hooksPath = path.join(dshDir, 'hooks.json');
+    const legacyTrFirst = path.join(dshDir, 'tr-first.sh');
+    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('tr-first')
+      );
+      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 tr-first.sh scripts if present (F-011)
+    const beforeLen = hooksConfig.hooks.PreToolUse.length;
+    hooksConfig.hooks.PreToolUse = hooksConfig.hooks.PreToolUse.filter(e => {
+      const cmd = String(e.command || '');
+      return !cmd.includes('tr-first.sh') && !cmd.includes('tr-wrapper.sh');
+    });
+    if (hooksConfig.hooks.PreToolUse.length < beforeLen) {
+      removed.push('legacy tr-first.sh hook entry');
+    }
+
+    const gateCommand = 'total-recall preflight gate --harness dsh';
+    const hasPreTool = hooksConfig.hooks.PreToolUse.some(e =>
+      String(e.command || '').includes('preflight gate --harness dsh')
+    );
+
+    if (!hasPreTool) {
+      hooksConfig.hooks.PreToolUse.push({
+        matcher: '*',
+        command: gateCommand,
+        timeout: 10
+      });
+      added.push('managed PreToolUse gate');
+    }
+
+    if (!dryRun && (added.length || removed.length)) {
+      fs.mkdirSync(dshDir, { 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, '.dsh', 'hooks', '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 dsh'));
+      } catch { /* unparseable */ }
+    }
+
+    const syntheticDeniedCall = {
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Bash',
+      tool_input: { 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('"decision":"deny"');
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default dshAdapter;

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

@@ -0,0 +1,132 @@
+/**
+ * xAI Grok Build CLI hook adapter.
+ * Official doc: https://docs.x.ai/build/features/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 grokAdapter = {
+  id: 'grok',
+  level: 'enforced (unverified live)',
+  source: {
+    url: 'https://docs.x.ai/build/features/hooks',
+    retrieved: '2026-11-04',
+    note: 'Grok Build hooks in ~/.grok/hooks/ or .grok/hooks/'
+  },
+  limits: [
+    'Timeouts, crashes and malformed outputs fail open in Grok Build',
+    'Project-level hooks require trust in ~/.grok/trusted_folders.toml'
+  ],
+
+  parse(input = {}) {
+    const event = input.hookEventName || input.event || 'PreToolUse';
+    const toolName = input.toolName || input.tool_name || input.tool || '';
+    const toolInput = input.toolInput || input.tool_input || input.input || {};
+    const cwd = input.cwd || input.workspaceRoot || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'Bash' || toolName === 'exec' || toolName === 'shell') {
+      tool = 'shell';
+      command = toolInput.command || toolInput.cmd || '';
+    } else if (/^(Edit|Write)$/.test(toolName)) {
+      tool = 'write';
+      filePath = toolInput.file_path || toolInput.path || '';
+    } else if (/^(Read|Glob|Grep)$/.test(toolName)) {
+      tool = 'read';
+      filePath = toolInput.file_path || toolInput.path || '';
+    }
+
+    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 } = {}) {
+    const grokDir = path.join(home, '.grok', 'hooks');
+    const hooksPath = path.join(grokDir, 'total-recall-preflight.json');
+    const added = [];
+
+    const hookDef = {
+      name: 'total-recall-preflight',
+      description: 'Fail-closed preflight gate for Total Recall',
+      events: ['PreToolUse'],
+      matcher: '*',
+      command: 'total-recall preflight gate --harness grok',
+      timeout: 5
+    };
+
+    if (!dryRun) {
+      fs.mkdirSync(grokDir, { recursive: true });
+      fs.writeFileSync(hooksPath, `${JSON.stringify(hookDef, null, 2)}\n`);
+      added.push('managed Grok PreToolUse hook');
+    }
+
+    return { settings: hooksPath, added };
+  },
+
+  verify({ home = os.homedir() } = {}) {
+    const hooksPath = path.join(home, '.grok', 'hooks', 'total-recall-preflight.json');
+    const installed = fs.existsSync(hooksPath);
+
+    const syntheticDeniedCall = {
+      hookEventName: 'PreToolUse',
+      toolName: 'Bash',
+      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('"decision":"deny"');
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced (unverified live)',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default grokAdapter;

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

@@ -0,0 +1,173 @@
+/**
+ * Hermes Agent Runtime hook adapter.
+ * Official doc: https://hermes-agent.nousresearch.com/docs/user-guide/features/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 hermesAdapter = {
+  id: 'hermes',
+  level: 'enforced',
+  source: {
+    url: 'https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks',
+    retrieved: '2026-11-04',
+    note: 'Hermes shell & plugin hooks in ~/.hermes/config.yaml'
+  },
+  limits: [
+    'Hermes plugin callbacks fail closed on timeout',
+    'Pre-tool hook returns {"action":"block","message":...} with exit 2'
+  ],
+
+  parse(input = {}) {
+    const event = input.event || input.hook_event_name || 'pre_tool_call';
+    const toolName = input.tool_name || input.tool || '';
+    const toolInput = input.tool_input || input.params || input.args || {};
+    const cwd = input.cwd || process.cwd();
+
+    let tool = 'other';
+    let command;
+    let filePath;
+
+    if (toolName === 'terminal' || toolName === 'Bash' || toolName === 'shell' || toolName === 'exec') {
+      tool = 'shell';
+      command = toolInput.command || toolInput.cmd || '';
+    } else if (toolName === 'write_file' || toolName === 'Edit' || toolName === 'Write') {
+      tool = 'write';
+      filePath = toolInput.path || toolInput.file_path || '';
+    } else if (toolName === 'read_file' || toolName === 'Read') {
+      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') {
+      const payload = { action: '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 = {
+      action: 'block',
+      message: 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 hermesDir = path.join(home, '.hermes');
+    const hooksPath = path.join(hermesDir, 'hooks.json');
+    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.pre_tool_call = hooksConfig.hooks.pre_tool_call || [];
+
+    if (isRemove) {
+      const beforeLen = hooksConfig.hooks.pre_tool_call.length;
+      hooksConfig.hooks.pre_tool_call = hooksConfig.hooks.pre_tool_call.filter(e =>
+        !String(e.command || '').includes('preflight')
+      );
+      if (hooksConfig.hooks.pre_tool_call.length < beforeLen) {
+        removed.push('managed pre_tool_call gate');
+      }
+      if (!dryRun && fs.existsSync(hooksPath)) {
+        fs.writeFileSync(hooksPath, `${JSON.stringify(hooksConfig, null, 2)}\n`);
+      }
+      return { settings: hooksPath, added: [], removed };
+    }
+
+    const gateCommand = 'total-recall preflight gate --harness hermes';
+    const hasPreTool = hooksConfig.hooks.pre_tool_call.some(e =>
+      String(e.command || '').includes('preflight gate --harness hermes')
+    );
+
+    if (!hasPreTool) {
+      hooksConfig.hooks.pre_tool_call.push({
+        matcher: '*',
+        command: gateCommand,
+        timeout: 10
+      });
+      added.push('managed pre_tool_call gate');
+    }
+
+    if (!dryRun && added.length) {
+      fs.mkdirSync(hermesDir, { 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 };
+  },
+
+  verify({ home = os.homedir() } = {}) {
+    const hooksPath = path.join(home, '.hermes', 'hooks.json');
+    let installed = false;
+    if (fs.existsSync(hooksPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(hooksPath, 'utf8') || '{}');
+        const preHooks = config.hooks?.pre_tool_call || [];
+        installed = preHooks.some(e => String(e.command || '').includes('preflight gate --harness hermes'));
+      } catch { /* unparseable */ }
+    }
+
+    const syntheticDeniedCall = {
+      event: 'pre_tool_call',
+      tool_name: 'terminal',
+      tool_input: { command: 'rm -rf /tmp/foo' },
+      cwd: '/nonexistent-directory-without-receipt'
+    };
+
+    const out = this.emit(
+      { decision: 'deny', reason: 'receipt missing', fix: ACK_COMMAND },
+      'pre_tool_call',
+      syntheticDeniedCall.cwd
+    );
+
+    const exercised = out.exitCode === 2 && out.stdout.includes('"action":"block"');
+
+    return {
+      installed,
+      exercised,
+      level: 'enforced',
+      native: out.stdout.trim()
+    };
+  }
+};
+
+export default hermesAdapter;

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

@@ -0,0 +1,87 @@
+/**
+ * Gate Adapters registry for Meta Harness (tr-plugin-cli-agents).
+ * Provides harness-specific parsing, emission, installation and verification.
+ */
+import { claudeAdapter } from './claude.mjs';
+import { agyAdapter } from './agy.mjs';
+import { codexAdapter } from './codex.mjs';
+import { dshAdapter } from './dsh.mjs';
+import { hermesAdapter } from './hermes.mjs';
+import { openclawAdapter } from './openclaw.mjs';
+import { cursorAdapter } from './cursor.mjs';
+import { devinAdapter } from './devin.mjs';
+import { grokAdapter } from './grok.mjs';
+import { clineAdapter } from './cline.mjs';
+import { piAdapter } from './pi.mjs';
+
+const ADAPTERS = new Map([
+  ['claude', claudeAdapter],
+  ['claude-code', claudeAdapter],
+  ['agy', agyAdapter],
+  ['antigravity', agyAdapter],
+  ['codex', codexAdapter],
+  ['dsh', dshAdapter],
+  ['hermes', hermesAdapter],
+  ['openclaw', openclawAdapter],
+  ['cursor', cursorAdapter],
+  ['devin', devinAdapter],
+  ['windsurf', devinAdapter],
+  ['grok', grokAdapter],
+  ['cline', clineAdapter],
+  ['pi', piAdapter]
+]);
+
+export function get(harnessId) {
+  if (!harnessId) return null;
+  return ADAPTERS.get(String(harnessId).toLowerCase()) || null;
+}
+
+export function list() {
+  const seen = new Set();
+  const result = [];
+  for (const adapter of ADAPTERS.values()) {
+    if (!seen.has(adapter.id)) {
+      seen.add(adapter.id);
+      result.push(adapter);
+    }
+  }
+  return result;
+}
+
+export function install(harnessId, opts = {}) {
+  const adapter = get(harnessId);
+  if (!adapter) throw new Error(`Unknown harness adapter: ${harnessId}`);
+  if (typeof adapter.install !== 'function') {
+    throw new Error(`Harness adapter ${harnessId} does not support installation`);
+  }
+  return adapter.install(opts);
+}
+
+export function verify(harnessId, opts = {}) {
+  const adapter = get(harnessId);
+  if (!adapter) throw new Error(`Unknown harness adapter: ${harnessId}`);
+  if (typeof adapter.verify !== 'function') {
+    throw new Error(`Harness adapter ${harnessId} does not support verification`);
+  }
+  return adapter.verify(opts);
+}
+
+export default {
+  get,
+  list,
+  install,
+  verify,
+  adapters: {
+    claude: claudeAdapter,
+    agy: agyAdapter,
+    codex: codexAdapter,
+    dsh: dshAdapter,
+    hermes: hermesAdapter,
+    openclaw: openclawAdapter,
+    cursor: cursorAdapter,
+    devin: devinAdapter,
+    grok: grokAdapter,
+    cline: clineAdapter,
+    pi: piAdapter
+  }
+};