plugins/ops-guards/hooks/register.js

Functions

Imports

It imports plugins/ops-guards/hooks/lib/guard.mjs, plugins/ops-guards/hooks/lib/heavy.mjs, plugins/ops-guards/hooks/lib/redact.mjs. No module of this repo imports it.

Source

1// ops-guards: three guards for sessions on this machine (job_1e4b82452fe0).
2//
3//   1. heavy lock     one install or build at a time across tabs and the scheduler
4//   2. key redaction  secrets never reach the model, and key files are never read
5//   3. command guard  no force push, no git clean -x, no recursive delete of a tree
6//                     holding a node_modules junction
7//
8// No model calls. Each guard has a switch in the plugin's options (userConfig), default
9// on. Turning one off, or all, is explained in README.md next to this plugin.
10//
11// A hooks module has to keep every `$` call visible to `claude plugin validate`, so each
12// call is written in full and `$` is passed only to functions declared in this file. The
13// decisions live in ./lib, which takes plain data and is tested with `node --test`.
14import { analyzeCommand, JUNCTION_DENY } from './lib/guard.mjs'
15import { isHeavy, lockNs, waitMessage } from './lib/heavy.mjs'
16import { isSecretPath, readsSecretFile, redactResult, SECRET_READ_DENY } from './lib/redact.mjs'
17
18// $.process.run rejects a timeoutMs over 600000 (10 minutes), and time spent inside a mods
19// API call does not count against the hook's own 10 second limit, so the wait happens
20// inside lock.mjs. A round is 9 minutes so that round plus margin stays under the cap.
21const WAIT_PER_ROUND_MS = 9 * 60_000
22const WAIT_ROUNDS = 3
23
24// How many heavy commands this session is running under the lock right now.
25let held = 0
26
27async function lockCall($, args, timeoutMs) {
28  const run = await $.process.run(['node', $.plugin.root + '/hooks/lock.mjs', ...args], { timeoutMs })
29  if (run.exitCode !== 0) throw new Error('lock.mjs ' + args[0] + ' failed: ' + (run.stderr || run.stdout))
30  return JSON.parse(run.stdout.trim().split(/\r?\n/).pop())
31}
32
33// Returns null when the lock is ours, or the message to refuse with.
34async function takeLock($, ns) {
35  if (held > 0) {
36    held += 1
37    return null
38  }
39  let got = await lockCall($, ['acquire', ns], 30_000)
40  if (!got.ok) {
41    $.ui.log('ops-guards: ' + waitMessage(got.holder) + '. Waiting for it before this install or build.')
42    for (let round = 0; round < WAIT_ROUNDS && !got.ok; round += 1) {
43      got = await lockCall($, ['wait', ns, String(WAIT_PER_ROUND_MS)], WAIT_PER_ROUND_MS + 30_000)
44    }
45  }
46  if (!got.ok) {
47    return (
48      'The heavy-work lock is still held after ' + (WAIT_ROUNDS * WAIT_PER_ROUND_MS) / 60_000 + ' minutes (' +
49      waitMessage(got.holder) + '). Do other work and retry this command later; do not delete ~/.capsid/overnight-heavy.lock ' +
50      'yourself, because a lock older than 9 hours is taken over automatically.'
51    )
52  }
53  held = 1
54  return null
55}
56
57async function dropLock($, ns) {
58  held = Math.max(0, held - 1)
59  if (held === 0) await lockCall($, ['release', ns], 30_000)
60}
61
62// The first node_modules link under a delete target, or null. The walk is junctions.mjs,
63// so the target is an argument to node and never reparsed by a shell. A probe that
64// fails throws, and the catch below refuses the delete.
65async function findJunction($, target) {
66  const run = await $.process.run(['node', $.plugin.root + '/hooks/junctions.mjs', target], { timeoutMs: 120_000 })
67  if (run.exitCode !== 0) throw new Error('junctions.mjs failed: ' + (run.stderr || run.stdout))
68  return JSON.parse(run.stdout.trim().split(/\r?\n/).pop()).link
69}
70
71const SHELL_TOOLS = ['Bash', 'PowerShell']
72
73export function register(on, options) {
74  const wants = (name) => !options || options[name] !== false
75
76  on('tool.call', async ($, e, next) => {
77    const isShell = SHELL_TOOLS.includes(e.tool)
78
79    // 3. destructive commands
80    if (wants('destructiveGuard') && isShell) {
81      const cwd = await $.session.cwd()
82      const verdict = analyzeCommand(e.command, cwd)
83      if (verdict.deny) return { deny: verdict.deny }
84      for (const target of verdict.probe ?? []) {
85        const found = await findJunction($, target)
86        if (found) return { deny: JUNCTION_DENY(target, found) }
87      }
88    }
89
90    // 2a. key files are never read
91    if (wants('redaction')) {
92      const touchesKey =
93        (isShell && readsSecretFile(e.command)) ||
94        (e.tool === 'Read' && isSecretPath(e.file_path)) ||
95        ((e.tool === 'Grep' || e.tool === 'Glob') && (isSecretPath(e.path) || isSecretPath(e.pattern)))
96      if (touchesKey) return { deny: SECRET_READ_DENY }
97    }
98
99    // 1. heavy work waits its turn
100    const heavy = wants('heavyLock') && isShell && isHeavy(e.command)
101    let result
102    if (heavy) {
103      const ns = lockNs(await $.session.id())
104      const refusal = await takeLock($, ns)
105      if (refusal) return { deny: refusal }
106      try {
107        result = await next(e)
108      } finally {
109        await dropLock($, ns)
110      }
111    } else {
112      result = await next(e)
113    }
114
115    // 2b. nothing secret in what Claude reads
116    return wants('redaction') ? redactResult(result) : result
117  }).catch(async ($, e, next) => {
118    // Fail closed: a guard that broke must not let the call through unchecked.
119    return { deny: 'ops-guards could not check this call (' + next.error.kind + '), so it was not run. Retry; if it persists, the human can disable the plugin in /plugin.' }
120  })
121
122  on('session.end', async ($, e, next) => {
123    // A tab that closes mid-install must not leave the lock for 9 hours.
124    if (held > 0) {
125      held = 0
126      await lockCall($, ['release', lockNs(await $.session.id())], 30_000)
127    }
128    return next(e)
129  })
130}