claude-bulkhead 0.2.2 → 0.3.0

package/src/agent-hook.js

@@ -0,0 +1,162 @@
+'use strict'
+const path = require('path')
+const { option } = require('./cli-util')
+
+// `bulkhead hook --agent <name>`: the Bash guards for coding agents other than Claude Code. The
+// agent pipes its pre-tool payload on stdin; the adapter maps it to the shape the guards read
+// ({ tool_name, tool_input: { command }, cwd, session_id }), runs the same guards as the Claude
+// Code PreToolUse hook, and answers in the agent's own block format. Anything unexpected lets
+// the command through, and Copilot and Cursor treat a crash or bad output as a denial, so those
+// two always get an explicit allow.
+
+const str = v => (typeof v === 'string' && v ? v : null)
+const obj = v => (v && typeof v === 'object' && !Array.isArray(v) ? v : null)
+const json = v => JSON.stringify(v)
+
+function asObject(v) {
+  if (typeof v !== 'string') return obj(v)
+  try { return obj(JSON.parse(v)) } catch { return null }
+}
+
+const sh = (command, cwd, session, extra = {}) =>
+  command ? { tool_name: 'Bash', tool_input: { command, ...extra }, cwd: cwd || undefined, session_id: session || undefined } : null
+
+const powershell = input => (input ? { ...input, tool_name: 'PowerShell' } : null)
+
+// Cline's run_commands takes a string, a list, { commands }, { command, args } or { cmd }.
+function clineCommands(input) {
+  const quote = a => (/^[\w@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)
+  const one = c => (typeof c === 'string' ? c : obj(c) && str(c.command) ? [c.command, ...(Array.isArray(c.args) ? c.args.map(String) : [])].map(quote).join(' ') : null)
+  let list = []
+  if (typeof input === 'string') list = [input]
+  else if (Array.isArray(input)) list = input
+  else if (obj(input)) {
+    if ('commands' in input) list = Array.isArray(input.commands) ? input.commands : [input.commands]
+    else if ('command' in input) list = [input]
+    else if ('cmd' in input) list = [input.cmd]
+  }
+  return list.map(one).filter(Boolean).join('\n')
+}
+
+const resolveDir = (cwd, dir) => (str(dir) ? path.resolve(cwd || process.cwd(), dir) : cwd)
+
+// How each agent's payload maps and how it wants a block (and, where silence is unsafe, an allow)
+// answered. read() returns null for anything that is not a shell command.
+const ADAPTERS = {
+  // https://developers.openai.com/codex/hooks: PreToolUse, tool_name "Bash", tool_input.command
+  codex: {
+    read: p => (p.tool_name === 'Bash' ? sh(str(obj(p.tool_input) && p.tool_input.command), p.cwd, p.session_id) : null),
+    block: msg => ({ out: json({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: msg } }) }),
+  },
+  // https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md: BeforeTool, run_shell_command
+  gemini: {
+    read: p => {
+      const ti = obj(p.tool_input)
+      if (p.tool_name !== 'run_shell_command' || !ti) return null
+      return sh(str(ti.command), resolveDir(p.cwd, ti.dir_path), p.session_id, ti.is_background ? { run_in_background: true } : {})
+    },
+    block: msg => ({ out: json({ decision: 'deny', reason: msg }) }),
+  },
+  // https://docs.github.com/en/copilot/reference/hooks-configuration: preToolUse, camelCase or
+  // (PreToolUse) snake_case payload; toolArgs may be a JSON string
+  copilot: {
+    read: p => {
+      const name = String(p.toolName || p.tool_name || '').toLowerCase()
+      if (name !== 'bash' && name !== 'powershell') return null
+      const args = asObject(p.toolArgs !== undefined ? p.toolArgs : p.tool_input)
+      const input = sh(str(args && args.command), p.cwd, p.sessionId || p.session_id)
+      return name === 'powershell' ? powershell(input) : input
+    },
+    block: msg => ({ out: json({ permissionDecision: 'deny', permissionDecisionReason: msg }) }),
+    allow: '',
+  },
+  // https://cursor.com/docs/hooks: beforeShellExecution { command, cwd }, answer { permission }
+  cursor: {
+    read: p => sh(str(p.command), str(p.cwd) || (Array.isArray(p.workspace_roots) && str(p.workspace_roots[0])), p.conversation_id),
+    block: msg => ({ out: json({ permission: 'deny', user_message: msg.split('\n')[0], agent_message: msg }) }),
+    allow: json({ permission: 'allow' }),
+  },
+  // Windsurf (Cascade) pre_run_command { tool_info: { command_line, cwd } }; exit 2 blocks
+  windsurf: {
+    read: p => {
+      const ti = obj(p.tool_info)
+      return ti ? sh(str(ti.command_line), ti.cwd, p.trajectory_id) : null
+    },
+    block: msg => ({ err: msg, code: 2 }),
+  },
+  // https://docs.factory.ai/reference/hooks-reference: PreToolUse, tool_name "Execute"
+  droid: {
+    read: p => (p.tool_name === 'Execute' ? sh(str(obj(p.tool_input) && p.tool_input.command), p.cwd, p.session_id) : null),
+    block: msg => ({ out: json({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: msg } }) }),
+  },
+  // https://docs.devin.ai/cli/extensibility/hooks/overview.md: PreToolUse, tool_name "exec"; exit 2 blocks
+  devin: {
+    read: p => (/^(?:exec|execute|bash|shell)$/i.test(String(p.tool_name)) ? sh(str(obj(p.tool_input) && p.tool_input.command), p.cwd, p.session_id) : null),
+    block: msg => ({ err: msg, code: 2 }),
+  },
+  // https://github.com/cline/cline/blob/main/sdk/examples/hooks/README.md: PreToolUse file hook, run_commands
+  cline: {
+    read: p => {
+      const call = obj(p.tool_call)
+      if (!call || call.name !== 'run_commands') return null
+      return sh(clineCommands(call.input), Array.isArray(p.workspaceRoots) ? p.workspaceRoots[0] : null, p.taskId)
+    },
+    block: msg => ({ out: json({ cancel: true, errorMessage: msg }) }),
+    allow: '{}',
+  },
+  // The opencode and Amp plugins that `bulkhead setup` writes pipe { command, cwd, session_id }
+  // and turn exit code 2 into a rejected tool call.
+  opencode: { read: p => sh(str(p.command), p.cwd, p.session_id), block: msg => ({ err: msg, code: 2 }) },
+  amp: { read: p => sh(str(p.command), p.cwd, p.session_id), block: msg => ({ err: msg, code: 2 }) },
+}
+
+const AGENT_NAMES = Object.keys(ADAPTERS)
+
+// The same guards, in the same order, as the Claude Code hook (bash-guards.js): the first block wins.
+async function judge(input) {
+  const r = await require('./bash-guards').judge(input, { rewrite: false })
+  return r && r.block ? r.block : null
+}
+
+// raw: the payload text. Returns { out, err, code } to write and exit with; never throws.
+async function run(agent, raw) {
+  const adapter = ADAPTERS[agent]
+  const allow = { out: adapter.allow || '', code: 0 }
+  try {
+    const input = adapter.read(JSON.parse(raw || '{}'))
+    if (!input) return allow
+    process.env.BULKHEAD_AGENT = agent
+    const message = await judge(input)
+    if (!message) return allow
+    const answer = adapter.block(message.endsWith('\n') ? message.slice(0, -1) : message)
+    return { out: '', err: '', code: 0, ...answer }
+  } catch {
+    return allow
+  }
+}
+
+function readStdin(stream) {
+  return new Promise(resolve => {
+    if (stream.isTTY) return resolve('')
+    let raw = ''
+    stream.setEncoding('utf8')
+    stream.on('data', d => (raw += d))
+    stream.on('end', () => resolve(raw))
+    stream.on('error', () => resolve(''))
+  })
+}
+
+async function main(args, { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, exit = process.exit } = {}) {
+  const agent = option(args, 'agent')
+  if (typeof agent !== 'string' || !ADAPTERS[agent]) {
+    stderr.write(`usage: bulkhead hook --agent <${AGENT_NAMES.join('|')}>   (reads the agent's pre-tool payload on stdin)\n`)
+    return exit(1)
+  }
+  const { out, err, code } = await run(agent, await readStdin(stdin))
+  if (err) stderr.write(err.endsWith('\n') ? err : err + '\n')
+  // exit only once the pipe has taken the answer
+  if (out) stdout.write(out, () => exit(code))
+  else exit(code)
+}
+
+module.exports = { main, run, judge, ADAPTERS, AGENT_NAMES, clineCommands }

package/src/agent-setup.js

@@ -0,0 +1,256 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { rejectArgs } = require('./cli-util')
+
+// `bulkhead setup <agent> [--print|--write]`: the config that makes an agent call
+// `bulkhead hook --agent <name>` before each shell command. --print (the default) shows it,
+// --write merges it into the agent's config file after copying the original aside. Running it
+// again changes nothing.
+
+const SCRIPT = path.join(__dirname, '..', 'bin', 'bulkhead')
+const MARK = 'bulkhead-managed'
+
+const quote = s => (/[\s"]/.test(s) ? `"${s}"` : s)
+// The node that runs this now, by absolute path: agents started from a desktop launcher often
+// have no node on their PATH, and Copilot turns a hook that cannot start into a denial.
+const launcher = (node = process.execPath, script = SCRIPT) => [node, script]
+const commandLine = (agent, argv = launcher()) => [...argv.map(quote), 'hook', '--agent', agent].join(' ')
+const isOurs = (text, agent) => new RegExp(`bulkhead\\\\?["']?\\s+hook\\s+--agent[ =]${agent}\\b`).test(text)
+const pretty = v => JSON.stringify(v, null, 2) + '\n'
+
+// The `command`/`bash` strings of every hook in a list of matcher groups.
+const commandsIn = groups => JSON.stringify(groups || [])
+
+// Adds `group` to doc[...path][event] unless one of our hooks is already there. Returns the doc.
+function addGroup(doc, pathKeys, event, group, agent) {
+  let node = doc
+  for (const k of pathKeys) {
+    if (node[k] === undefined) node[k] = {}
+    if (!node[k] || typeof node[k] !== 'object' || Array.isArray(node[k])) throw new Error(`"${k}" is not an object`)
+    node = node[k]
+  }
+  if (node[event] === undefined) node[event] = []
+  if (!Array.isArray(node[event])) throw new Error(`"${event}" is not a list`)
+  if (!isOurs(commandsIn(node[event]), agent)) node[event].push(group)
+  return doc
+}
+
+function jsonPlan(file, existing, build) {
+  const fragment = build({})
+  const snippet = pretty(fragment)
+  if (existing === null || !existing.trim()) return { file, snippet, next: snippet }
+  let doc
+  try {
+    doc = JSON.parse(existing)
+  } catch (e) {
+    return { file, snippet, error: `${file} is not plain JSON (${e.message}); add the snippet by hand` }
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return { file, snippet, error: `${file} does not hold a JSON object; add the snippet by hand` }
+  const before = pretty(doc)
+  let next
+  try {
+    next = pretty(build(doc))
+  } catch (e) {
+    return { file, snippet, error: `${file}: ${e.message}; add the snippet by hand` }
+  }
+  return { file, snippet, next: next === before ? null : next }
+}
+
+// A file bulkhead owns outright (a script, a plugin): install it, update ours, never replace another's.
+function ownedPlan(file, existing, content, agent) {
+  if (existing !== null && !existing.includes(MARK) && !isOurs(existing, agent)) {
+    return { file, snippet: content, error: `${file} already exists and is not from bulkhead; put the call to \`bulkhead hook --agent ${agent}\` in it by hand` }
+  }
+  return { file, snippet: content, next: existing === content ? null : content, mode: 0o755 }
+}
+
+const pluginSource = (agent, argv) => ({
+  opencode: `// ${MARK}: written by \`bulkhead setup opencode\`, safe to delete
+import { spawnSync } from 'node:child_process'
+
+const HOOK = ${JSON.stringify([...argv, 'hook', '--agent', 'opencode'])}
+
+export const BulkheadPlugin = async ({ directory }) => ({
+  'tool.execute.before': async (input, output) => {
+    if (input.tool !== 'bash') return
+    const command = output.args && output.args.command
+    if (typeof command !== 'string' || !command) return
+    const cwd = (output.args && output.args.workdir) || directory
+    const r = spawnSync(HOOK[0], HOOK.slice(1), {
+      input: JSON.stringify({ command, cwd, session_id: input.sessionID }), encoding: 'utf8', timeout: 25000, windowsHide: true,
+    })
+    if (r.status === 2) throw new Error((r.stderr || 'blocked by bulkhead').trim())
+  },
+})
+`,
+  amp: `// ${MARK}: written by \`bulkhead setup amp\`, safe to delete
+import { spawnSync } from 'node:child_process'
+import type { PluginAPI } from '@ampcode/plugin'
+
+const HOOK = ${JSON.stringify([...argv, 'hook', '--agent', 'amp'])}
+
+export default function (amp: PluginAPI) {
+  amp.on('tool.call', async event => {
+    const shell = amp.helpers.shellCommandFromToolCall(event)
+    if (!shell || !shell.command) return { action: 'allow' }
+    const r = spawnSync(HOOK[0], HOOK.slice(1), {
+      input: JSON.stringify({ command: shell.command, cwd: shell.dir || process.cwd(), session_id: event.thread.id }),
+      encoding: 'utf8', timeout: 25000, windowsHide: true,
+    })
+    if (r.status === 2) return { action: 'reject-and-continue', message: (r.stderr || 'blocked by bulkhead').trim() }
+    return { action: 'allow' }
+  })
+}
+`,
+})[agent]
+
+const clineScript = (argv, platform) => platform === 'win32'
+  ? `# ${MARK}: written by \`bulkhead setup cline\`\r\n$input | & ${argv.map(a => `"${a}"`).join(' ')} hook --agent cline\r\n`
+  : `#!/usr/bin/env bash\n# ${MARK}: written by \`bulkhead setup cline\`\nexec ${argv.map(a => `'${a.replace(/'/g, `'\\''`)}'`).join(' ')} hook --agent cline\n`
+
+// agent: { where(home, env, platform) -> file, plan(file, existing, ctx) -> plan, note }
+const SETUP = {
+  codex: {
+    where: (home, env) => path.join(env.CODEX_HOME || path.join(home, '.codex'), 'hooks.json'),
+    plan: (file, existing, { argv }) => jsonPlan(file, existing, doc => addGroup(doc, ['hooks'], 'PreToolUse',
+      { matcher: '^Bash$', hooks: [{ type: 'command', command: commandLine('codex', argv), timeout: 30, statusMessage: 'bulkhead guards' }] }, 'codex')),
+    note: 'Codex asks you to review a new hook once: open /hooks in Codex and trust it.',
+  },
+  gemini: {
+    where: home => path.join(home, '.gemini', 'settings.json'),
+    plan: (file, existing, { argv }) => jsonPlan(file, existing, doc => addGroup(doc, ['hooks'], 'BeforeTool',
+      { matcher: 'run_shell_command', hooks: [{ name: 'bulkhead', type: 'command', command: commandLine('gemini', argv), timeout: 30000 }] }, 'gemini')),
+  },
+  copilot: {
+    where: (home, env) => path.join(env.COPILOT_HOME || path.join(home, '.copilot'), 'hooks', 'bulkhead.json'),
+    plan: (file, existing, { argv }) => {
+      const command = commandLine('copilot', argv)
+      return ownedPlan(file, existing, pretty({ version: 1, hooks: { preToolUse: [{ type: 'command', bash: command, powershell: command, timeoutSec: 30 }] } }), 'copilot')
+    },
+    note: 'Copilot CLI treats a hook that fails to start as a denial. If you move or remove this node, run the setup again.',
+  },
+  cursor: {
+    where: home => path.join(home, '.cursor', 'hooks.json'),
+    plan: (file, existing, { argv }) => jsonPlan(file, existing, doc => {
+      doc.version = doc.version || 1
+      const list = (doc.hooks = doc.hooks || {}).beforeShellExecution = (doc.hooks.beforeShellExecution || [])
+      if (!isOurs(commandsIn(list), 'cursor')) list.push({ command: commandLine('cursor', argv), timeout: 30 })
+      return doc
+    }),
+  },
+  windsurf: {
+    where: home => path.join(home, '.codeium', 'windsurf', 'hooks.json'),
+    plan: (file, existing, { argv }) => jsonPlan(file, existing, doc => {
+      const list = (doc.hooks = doc.hooks || {}).pre_run_command = (doc.hooks.pre_run_command || [])
+      if (!isOurs(commandsIn(list), 'windsurf')) list.push({ command: commandLine('windsurf', argv), show_output: false })
+      return doc
+    }),
+    note: 'This is the Windsurf IDE user file. The JetBrains plugin reads ~/.codeium/hooks.json instead.',
+  },
+  droid: {
+    // hooks.json wins over the hooks key in settings.json, so a user who only has the second keeps it
+    where: home => {
+      const hooks = path.join(home, '.factory', 'hooks.json')
+      const settings = path.join(home, '.factory', 'settings.json')
+      try {
+        if (!fs.existsSync(hooks) && JSON.parse(fs.readFileSync(settings, 'utf8')).hooks) return settings
+      } catch {}
+      return hooks
+    },
+    plan: (file, existing, { argv }) => jsonPlan(file, existing, doc => addGroup(doc, path.basename(file) === 'settings.json' ? ['hooks'] : [], 'PreToolUse',
+      { matcher: 'Execute', hooks: [{ type: 'command', command: commandLine('droid', argv), timeout: 30 }] }, 'droid')),
+  },
+  devin: {
+    where: (home, env, platform) => platform === 'win32'
+      ? path.join(env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'devin', 'config.json')
+      : path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'devin', 'config.json'),
+    plan: (file, existing, { argv }) => jsonPlan(file, existing, doc => addGroup(doc, ['hooks'], 'PreToolUse',
+      { matcher: 'exec', hooks: [{ type: 'command', command: commandLine('devin', argv) }] }, 'devin')),
+  },
+  cline: {
+    where: (home, env, platform) => path.join(env.CLINE_DIR || path.join(home, '.cline'), 'hooks', platform === 'win32' ? 'PreToolUse.ps1' : 'PreToolUse.sh'),
+    plan: (file, existing, { argv, platform }) => ownedPlan(file, existing, clineScript(argv, platform), 'cline'),
+  },
+  opencode: {
+    where: (home, env) => path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'opencode', 'plugins', 'bulkhead.js'),
+    plan: (file, existing, { argv }) => ownedPlan(file, existing, pluginSource('opencode', argv), 'opencode'),
+    note: 'Restart opencode to load the plugin.',
+  },
+  amp: {
+    where: (home, env) => path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'amp', 'plugins', 'bulkhead.ts'),
+    plan: (file, existing, { argv }) => ownedPlan(file, existing, pluginSource('amp', argv), 'amp'),
+    note: 'Run `plugins: reload` from the Amp command palette to load the plugin.',
+  },
+}
+
+const AGENT_NAMES = Object.keys(SETUP)
+
+function readIfExists(file) {
+  try { return fs.readFileSync(file, 'utf8') } catch (e) { if (e.code === 'ENOENT') return null; throw e }
+}
+
+// What `setup` would do for one agent. { file, snippet, next, error?, note }; next is null when
+// the file already has it.
+function plan(agent, { home = os.homedir(), env = process.env, platform = process.platform, argv = launcher() } = {}) {
+  const spec = SETUP[agent]
+  const file = spec.where(home, env, platform)
+  let existing
+  try { existing = readIfExists(file) } catch (e) { return { file, snippet: '', error: `cannot read ${file}: ${e.message}` } }
+  return { ...spec.plan(file, existing, { argv, platform }), existing, note: spec.note || null }
+}
+
+function backupName(file, exists = fs.existsSync, now = Date.now()) {
+  const base = file + '.bulkhead-backup'
+  return exists(base) ? `${base}-${now}` : base
+}
+
+// Writes the plan. Returns { wrote, backup }. The original is copied first and the new content
+// goes in through a temporary file, so a crash never leaves a half-written config.
+function apply(p) {
+  if (p.next === null || p.next === undefined) return { wrote: false, backup: null }
+  fs.mkdirSync(path.dirname(p.file), { recursive: true })
+  let backup = null
+  if (p.existing !== null && p.existing !== undefined) {
+    backup = backupName(p.file)
+    fs.copyFileSync(p.file, backup)
+  }
+  const tmp = `${p.file}.bulkhead-tmp-${process.pid}`
+  fs.writeFileSync(tmp, p.next, { mode: p.mode || 0o644 })
+  fs.renameSync(tmp, p.file)
+  return { wrote: true, backup }
+}
+
+function main(args, { stdout = process.stdout, stderr = process.stderr, exit = process.exit, ctx = {} } = {}) {
+  const agent = args.find(a => !a.startsWith('--'))
+  const list = () => `agents: ${AGENT_NAMES.join(', ')}`
+  if (rejectArgs('setup', args.filter(a => a !== agent), { flags: ['print', 'write'], valued: [] }, stderr, null)) return exit(1)
+  if (!agent || !SETUP[agent]) {
+    stderr.write(`usage: bulkhead setup <agent> [--print|--write]\n${list()}\n`)
+    return exit(1)
+  }
+  if (args.includes('--print') && args.includes('--write')) {
+    stderr.write('bulkhead setup: use --print or --write, not both\n')
+    return exit(1)
+  }
+  const p = plan(agent, ctx)
+  if (p.error) {
+    stderr.write(`bulkhead setup: ${p.error}\n`)
+    if (p.snippet) stderr.write(`\n${p.snippet}`)
+    return exit(1)
+  }
+  if (!args.includes('--write')) {
+    stdout.write(`# ${p.file}${p.next === null ? '  (already set up)' : ''}\n${p.snippet}`)
+    if (p.note) stdout.write(`# ${p.note}\n`)
+    return exit(0)
+  }
+  const done = apply(p)
+  stdout.write(done.wrote
+    ? `${p.existing === null ? 'created' : 'updated'} ${p.file}${done.backup ? `\nbackup of the original: ${done.backup}` : ''}\n`
+    : `${p.file} already has bulkhead; nothing changed\n`)
+  if (p.note) stdout.write(`${p.note}\n`)
+  return exit(0)
+}
+
+module.exports = { main, plan, apply, backupName, commandLine, isOurs, SETUP, AGENT_NAMES }

package/src/agents.js

@@ -0,0 +1,89 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+// The coding agents other than Claude Code that bulkhead recognizes as live sessions. Each entry
+// matches the agent's CLI process. The patterns come from the published `bin` entries of the
+// packages and the agents' install scripts (see docs/other-agents.md); an entry is only used for
+// matching, so a pattern that misses just leaves that agent out of the session list.
+const RUNTIME = /^(?:node|bun)(?:\.exe)?$/i
+const nameIs = (p, re) => re.test(p.name || '') || re.test(basename(p.cmd))
+
+function basename(cmd) {
+  const first = /^\s*(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(cmd || '')
+  const prog = first ? first[1] || first[2] || first[3] : ''
+  return prog.split(/[\\/]/).pop()
+}
+
+// `node .../bin/<name>` or `node .../<name>.js`: a script launched through its runtime.
+const script = base => new RegExp(`[\\\\/]${base}(?:\\.[cm]?js)?(?=["']?(?:\\s|$))`, 'i')
+
+const AGENTS = {
+  codex: {
+    label: 'Codex',
+    // the npm package starts a native codex binary from node; the outer node process is the root
+    match: p => nameIs(p, /^codex(?:\.exe)?$/i) || (RUNTIME.test(p.name) && /@openai[\\/]codex[\\/]bin[\\/]codex\.js/.test(p.cmd)),
+    dirs: ['.codex'],
+  },
+  gemini: {
+    label: 'Gemini',
+    // gemini relaunches itself as a child with more heap; the outer process is the root
+    match: p => nameIs(p, /^gemini(?:\.exe)?$/i) || (RUNTIME.test(p.name) && (/@google[\\/]gemini-cli[\\/]/.test(p.cmd) || script('gemini').test(p.cmd))),
+    dirs: ['.gemini'],
+  },
+  copilot: {
+    label: 'Copilot',
+    match: p => nameIs(p, /^copilot(?:\.exe)?$/i) || (RUNTIME.test(p.name) && (/@github[\\/]copilot[\\/]/.test(p.cmd) || script('copilot').test(p.cmd))),
+    dirs: ['.copilot'],
+  },
+  cursor: {
+    label: 'Cursor',
+    // the cursor-agent CLI (also installed as `agent`); the Cursor editor itself is not matched
+    match: p => nameIs(p, /^cursor-agent(?:\.exe)?$/i) || /[\\/]cursor-agent[\\/]versions[\\/]/.test(p.cmd),
+    dirs: ['.cursor'],
+  },
+  opencode: {
+    label: 'opencode',
+    match: p => nameIs(p, /^opencode(?:\.exe)?$/i) || (RUNTIME.test(p.name) && script('opencode').test(p.cmd)),
+    dirs: ['.config/opencode', '.local/share/opencode'],
+  },
+  amp: {
+    label: 'Amp',
+    match: p => nameIs(p, /^amp(?:\.exe)?$/i) || /@ampcode[\\/]cli[\\/]/.test(p.cmd),
+    dirs: ['.config/amp'],
+  },
+  cline: {
+    label: 'Cline',
+    match: p => nameIs(p, /^cline(?:\.exe)?$/i) || (RUNTIME.test(p.name) && script('cline').test(p.cmd)),
+    dirs: ['.cline'],
+  },
+  droid: {
+    label: 'Droid',
+    match: p => nameIs(p, /^droid(?:\.exe)?$/i) || (RUNTIME.test(p.name) && script('droid').test(p.cmd)),
+    dirs: ['.factory'],
+  },
+}
+
+// Names of the agents other than Claude Code (and of the ones that only have a hook, no CLI).
+const NAMES = Object.keys(AGENTS)
+
+// The agent a process is the CLI of, or null. Claude Code is decided by sessions.isClaudeCli.
+function agentOf(p) {
+  if (!p) return null
+  for (const name of NAMES) if (AGENTS[name].match(p)) return name
+  return null
+}
+
+function agentLabel(agent) {
+  return !agent || agent === 'claude' ? 'Claude' : (AGENTS[agent] && AGENTS[agent].label) || agent
+}
+
+// A user who never installed another agent has none of its folders, so a process scan that only
+// looks for other agents can be skipped without reading the process table.
+function installedAgents(home = os.homedir(), exists = fs.existsSync, env = process.env) {
+  const xdg = env.XDG_CONFIG_HOME
+  return NAMES.filter(name => AGENTS[name].dirs.some(d => exists(path.join(home, d)) || (xdg && d.startsWith('.config/') && exists(path.join(xdg, d.slice(8))))))
+}
+
+module.exports = { AGENTS, NAMES, agentOf, agentLabel, installedAgents }

package/src/allow-cli.js

@@ -0,0 +1,65 @@
+'use strict'
+const allowOnce = require('./allow-once')
+const { rejectArgs, useColor, paint, table, shortPath } = require('./cli-util')
+
+const USAGE = `usage: bulkhead allow <code>
+       bulkhead allow --list [--json]
+
+Run this yourself, in your own terminal, when a guard blocked a command you want to go ahead.
+<code> is the short code in the block message. The agent can then run that exact command, from
+the same folder, once, within allowOnce.ttlMinutes (default 10). --list shows the codes waiting.
+The agent cannot run this command: bulkhead blocks it.`
+
+function ago(ms, now) {
+  const m = Math.max(0, Math.round((now - ms) / 60000))
+  return m < 1 ? 'just now' : `${m} min ago`
+}
+
+function left(ms, now) {
+  return `${Math.max(1, Math.ceil((ms - now) / 60000))} min`
+}
+
+function renderList(entries, { now = Date.now(), color = false } = {}) {
+  if (!entries.length) return 'no codes waiting. A code appears in the message when a guard blocks a command.'
+  const rows = [['CODE', 'STATE', 'GUARD', 'RULE', 'FOLDER', 'COMMAND', 'BLOCKED', 'LEFT']]
+  for (const e of entries) {
+    rows.push([e.code, e.approved ? 'allowed' : 'waiting', e.guard, e.rule, shortPath(e.cwd), e.cmd.slice(0, 50), ago(e.created, now), left(e.expires, now)])
+  }
+  const lines = table(rows)
+  return [paint(color, 'bold', lines[0]), ...lines.slice(1)].join('\n')
+}
+
+function main(args, { stdout = process.stdout, stderr = process.stderr, env = process.env, now = Date.now(), base } = {}) {
+  if (args.includes('--help') || args.includes('-h')) return stdout.write(USAGE + '\n')
+  if (args.includes('--list')) {
+    if (rejectArgs('allow', args, { flags: ['list', 'json'], valued: [] }, stderr, USAGE)) return
+    const entries = allowOnce.list({ base, now })
+    if (args.includes('--json')) return stdout.write(JSON.stringify(entries, null, 2) + '\n')
+    return stdout.write(renderList(entries, { now, color: useColor(stdout, env) }) + '\n')
+  }
+  const codes = args.filter(a => !a.startsWith('-'))
+  if (codes.length !== 1 || args.some(a => a.startsWith('-'))) {
+    stderr.write(USAGE + '\n')
+    process.exitCode = 1
+    return
+  }
+  const res = allowOnce.approve(codes[0], { base, now })
+  if (!res.ok) {
+    const why = {
+      unknown: `no waiting code ${codes[0].toUpperCase()}. It may have expired (codes last ${Math.round(allowOnce.ttlMs() / 60000)} minutes); run the blocked command again for a new one, or \`bulkhead allow --list\`.`,
+      used: `code ${codes[0].toUpperCase()} is already allowed and waiting for the agent to retry the command.`,
+      'no-code': 'give the code from the block message, for example: bulkhead allow 7F3K',
+      unwritable: 'could not write the allow state; check that the bulkhead state directory is writable.',
+      unreadable: 'could not read the allow state; check the bulkhead state directory.',
+    }[res.reason]
+    stderr.write(`bulkhead allow: ${why}\n`)
+    process.exitCode = 1
+    return
+  }
+  const e = res.entries[0]
+  const guards = res.entries.map(x => `${x.guard} ${x.rule}`).join(', ')
+  stdout.write(`Allowed once: ${e.cmd}\n  folder ${e.cwd || '?'}\n  guards ${guards}\n` +
+    `The agent can run exactly that command now, once, within ${left(e.expires, now)}.\n`)
+}
+
+module.exports = { main, renderList, USAGE }

package/src/allow-hint.js

@@ -0,0 +1,62 @@
+'use strict'
+// How to let one blocked rule through for good: the exact config snippet and the
+// BULKHEAD_DISABLE name. Shown in block messages (one line) and by `bulkhead explain`.
+
+const RULE_KEYS = {
+  'rm-root': ['basics', 'rmRoot'],
+  'force-push-main': ['basics', 'forcePushMain'],
+  'protected-delete': ['basics', 'protectedDelete'],
+  'discard-changes': ['basics', 'discardChanges'],
+  'agent-author': ['basics', 'agentAuthor'],
+  'stage-all': ['checkoutGuard', 'stageAll'],
+  'remove-session-dir': ['checkoutGuard', 'removeSessionDir'],
+  'mass-kill': ['killGuard', 'massKill'],
+  'docker-mass': ['killGuard', 'dockerMass'],
+  'device-kill': ['killGuard', 'deviceKill'],
+  'app-quit': ['killGuard', 'appQuit'],
+  'service-stop': ['killGuard', 'serviceStop'],
+  'other-session-pid': ['killGuard', 'ownerCheck', 'owner-check'],
+}
+const SECTION = {
+  'kill-guard': 'killGuard', 'wait-guard': 'waitGuard', 'memory-guard': 'memoryGuard', 'port-guard': 'portGuard',
+  'checkout-guard': 'checkoutGuard', 'disk-guard': 'diskGuard', basics: 'basics', 'orphan-reaper': 'orphanReaper', 'secrets-guard': 'secretsGuard', 'edit-guard': 'editGuard',
+}
+
+// The shared program name a kill command aims at, to put in allowNames.
+function killName(command) {
+  try {
+    const kill = require('./kill-guard')
+    const shell = require('./shell')
+    const names = kill.nameList()
+    const words = shell.unwrap(shell.prepare(String(command || ''), 'sh'), 'sh').split(/[^\w.*?-]+/)
+    return words.map(w => w.toLowerCase().replace(/\.exe$/, '')).find(w => w && kill.nameHits(w, names)) || null
+  } catch {
+    return null
+  }
+}
+
+// { json, disable } for a guard and rule; json is null when the rule cannot be allowed.
+function allowHint(guard, rule, { command = '', message = '' } = {}) {
+  const j = o => JSON.stringify(o)
+  if (rule === 'self-allow') return { json: null, disable: null }
+  const key = RULE_KEYS[rule]
+  if (key) return { json: j({ [key[0]]: { [key[1]]: false } }), disable: key[2] || rule }
+  const section = SECTION[guard]
+  if (!section) return { json: null, disable: guard }
+  const off = { json: j({ [section]: { enabled: false } }), disable: guard }
+  if (guard === 'kill-guard') return { json: j({ killGuard: { allowNames: [killName(command) || '<name>'] } }), disable: guard }
+  if (guard === 'port-guard') {
+    const port = /\bport (\d{2,5})\b/.exec(message)
+    return port ? { json: j({ portGuard: { ignorePorts: [Number(port[1])] } }), disable: guard } : off
+  }
+  if (guard === 'secrets-guard') {
+    const file = /\(([^()\n]+)\) to the model/.exec(message)
+    return { json: j({ secretsGuard: { allow: [file && !/\s/.test(file[1]) ? file[1] : '<file>'] } }), disable: guard }
+  }
+  if (guard === 'edit-guard') return { json: j({ editGuard: { mode: 'warn' } }), disable: guard }
+  if (guard === 'wait-guard') return { json: j({ waitGuard: { limitSeconds: 600 } }), disable: guard }
+  if (guard === 'memory-guard' && rule === 'low-memory') return { json: j({ memory: { minFreeGb: 1 } }), disable: guard }
+  return off
+}
+
+module.exports = { allowHint, killName }