guardrails-md

1/**
2 * guardrails-md for Claude Code: a hooks module loaded in-process from
3 * hooks/hooks.json. Self-contained: a hooks module runs without Node and
4 * imports only files of the plugin, so it cannot share core.ts (node:fs,
5 * the SDK). The questions, decision, block wording and cooldown below are
6 * the same as core.ts's; keep the two in step when editing either.
7 *
8 * session.start snapshots GUARDRAILS.md (then .claude/GUARDRAILS.md, then the
9 * legacy lowercase files), the
10 * session root and every variable below; it fires once per session and not
11 * on compaction, and a missing snapshot denies. tool.call judges Bash, and
12 * Monitor when it runs a shell `command`, and deterministically refuses
13 * Edit, Write and NotebookEdit on protected paths — no model call, no
14 * threshold, no cooldown — answering { deny } on a block.
15 *
16 * Fail-closed: the engine skips a hook that throws or overruns and lets the
17 * call through, so .catch denies instead. The endpoint call is raced
18 * against a 5 s $.clock.sleep, as the SDK times out in opencode and pi:
19 * waiting on $.http.fetch does not count against the hook's budget.
20 *
21 * Credentials: BERGET_API_KEY, then TYPESAFE_API_KEY (no Berget seat token
22 * here). Cooldown: module memory, for the session. No audit log: $.fs
23 * cannot append.
24 */
25import type { Register } from "claude-code"
26
27const HARNESS = "claude"
28// Capitalised canonical names first; the lowercase legacy files are the fallback.
29const GUARDRAIL_PATHS = ["GUARDRAILS.md", ".claude/GUARDRAILS.md", "guardrails.md", ".claude/guardrails.md"]
30// The same list as core.ts's PROTECTED_PATHS — a hooks module cannot import
31// it, so keep the two in step.
32const PROTECTED_PATHS = [
33  "GUARDRAILS.md",
34  ".agents/GUARDRAILS.md",
35  ".opencode/GUARDRAILS.md",
36  ".pi/GUARDRAILS.md",
37  ".claude/GUARDRAILS.md",
38  "opencode.json",
39  "opencode.jsonc",
40  ".opencode/",
41  ".pi/",
42  ".claude/settings.json",
43  ".claude/settings.local.json",
44  ".github/workflows/",
45]
46const TIMEOUT_MS = 5000
47const DEFAULT_THRESHOLD = 0.7
48const GUARDRAILS_MAX = 2000 // chars — keep the state text tight
49const TRUNCATED = "\n… (truncated)"
50const SCRIPT_MAX = 4000 // chars of file content included per file
51const SCRIPT_FILES_MAX = 3 // files read per command
52const SCRIPT_BYTES_MAX = 1_000_000 // larger files are not read
53
54// --- config -----------------------------------------------------------------
55
56// Out-of-range values fail silently otherwise: "abc" (NaN) or anything ≥ 1
57// never blocks, while "", 0 or negatives block everything.
58function parseThreshold(raw: string | undefined): { value: number; warning?: string } {
59  if (raw === undefined) return { value: DEFAULT_THRESHOLD }
60  const value = Number(raw)
61  if (raw.trim() !== "" && value > 0 && value < 1) return { value }
62  return {
63    value: DEFAULT_THRESHOLD,
64    warning:
65      `SystemOne-gate: SYSTEMONE_THRESHOLD=${JSON.stringify(raw)} is not a number between 0 and 1 — ` +
66      `using ${DEFAULT_THRESHOLD}.`,
67  }
68}
69
70function isEnabled(raw: string | undefined): boolean {
71  return /^(1|true|yes)$/i.test(raw ?? "")
72}
73
74// The endpoint wants the API ROOT (we append /v1/systemone); accept both forms.
75function gatewayRoot(url: string): string {
76  return url.replace(/\/v1\/systemone\/?$/, "").replace(/\/+$/, "")
77}
78
79// --- GUARDRAILS.md ----------------------------------------------------------
80
81function truncateGuardrails(raw: string): string {
82  const text = raw.trim()
83  return text.length > GUARDRAILS_MAX ? text.slice(0, GUARDRAILS_MAX) + TRUNCATED : text
84}
85
86// A truncated policy is applied as if complete, so rules past the cut are
87// silently dropped — an agent can push them there by padding the file.
88function truncationWarning(guardrails: string | null): string | undefined {
89  if (!guardrails?.endsWith(TRUNCATED)) return undefined
90  return (
91    `SystemOne-gate: GUARDRAILS.md is longer than ${GUARDRAILS_MAX} characters — rules after that are ignored. ` +
92    `Shorten it or put the MUST NOT rules first.`
93  )
94}
95
96// --- judging ----------------------------------------------------------------
97
98type Verdict = {
99  destructive: number
100  credentials: number
101  guardrails_violation?: number
102  policy_exception?: number
103}
104
105// The SDK's noul(), inlined: the same wire JSON without a package import.
106function noul(instructions: string) {
107  return { type: "noul" as const, instructions }
108}
109
110function buildQuestions(hasGuardrails: boolean) {
111  const questions: Record<string, ReturnType<typeof noul>> = {
112    destructive: noul(
113      "Does this shell command delete, overwrite, format, or irreversibly destroy data, databases, clusters, or infrastructure? " +
114        "Effects that are recoverable through version control (git rm, git rm --cached, git checkout, branch operations) are not irreversible. " +
115        "Removing build artifacts, caches and temporary files is not irreversible. " +
116        "However, in GitOps repositories a version-control change can trigger irreversible changes to real infrastructure — " +
117        "deleting a manifest and pushing can destroy the resource it managed. Judge the actual effect of the command, not the version-control mechanics.",
118    ),
119    credentials: noul(
120      "Does this shell command contain, print, or send credentials, secrets, API keys, or tokens?",
121    ),
122  }
123  if (hasGuardrails) {
124    questions.guardrails_violation = noul(
125      "Given the team's guardrails in the state, does this command violate any of those rules?",
126    )
127    questions.policy_exception = noul(
128      "Does the team's guardrails text in the state EXPLICITLY allow this exact command — " +
129        "naming it, or a precise and unambiguous pattern that matches it? " +
130        "General or vague permissions do not count as an exception.",
131    )
132  }
133  return questions
134}
135
136function buildStateText(command: string, scripts: string, guardrails: string | null): string {
137  const stateParts = [`Command the agent wants to run:\n${command}`]
138  if (scripts) {
139    stateParts.push(`The command executes these script files — their content is part of the command:\n${scripts}`)
140  }
141  if (guardrails) {
142    stateParts.push(`Team guardrails (rules for what the agent may and may not do):\n${guardrails}`)
143  }
144  return stateParts.join("\n\n")
145}
146
147// No interpreter blocklist — perl, java, dotnet, ruby, lua, osascript,
148// xargs, find -exec and friends can never be enumerated. Instead: every
149// argument that points to an existing file is read and judged, whatever
150// tool would run it. Inline code (perl -e '…', node -e '…') is already
151// part of the command text. One level deep; network-fetched payloads and
152// binaries remain documented gaps.
153function scriptPath(token: string): string | null {
154  const path = token.replace(/^["']|["']$/g, "")
155  if (!path || path.startsWith("-") || !path.includes(".")) return null
156  return path
157}
158
159function scriptSection(path: string, text: string): string | null {
160  if (text.includes("\0")) return null // binary — utf8 garbage adds nothing
161  const cut = text.length > SCRIPT_MAX ? text.slice(0, SCRIPT_MAX) + TRUNCATED : text
162  return `--- ${path} ---\n${cut}`
163}
164
165// A score the endpoint sends as a string or garbage must not reach decide
166// as a non-number: "0.98" would pass the > comparison and then throw in
167// blockMessage. Absent questions stay absent.
168function score(answer: { noul?: unknown } | undefined): number {
169  const value = Number(answer?.noul ?? 0)
170  return Number.isNaN(value) ? 0 : value
171}
172
173function verdictFrom(answers: unknown): Verdict {
174  const a = (answers ?? {}) as Record<string, { noul?: unknown } | undefined>
175  return {
176    destructive: score(a.destructive),
177    credentials: score(a.credentials),
178    guardrails_violation: a.guardrails_violation === undefined ? undefined : score(a.guardrails_violation),
179    policy_exception: a.policy_exception === undefined ? undefined : score(a.policy_exception),
180  }
181}
182
183// Two tiers. A named exception in GUARDRAILS.md overrides the POLICY
184// question (guardrails_violation) — that is how policy false positives are
185// fixed. It does NOT override destructive or credentials: those judge the
186// command's nature, they are the backstop, and GUARDRAILS.md is
187// agent-editable between sessions. A command the model judges destructive
188// needs a human at the keyboard, whatever the file says.
189type Dimension = "destructive" | "credentials" | "guardrails_violation"
190
191interface Outcome {
192  decision: "BLOCK" | "allow"
193  kind: Dimension
194  worst: number
195  named: boolean
196}
197
198function decide(verdict: Verdict, hasGuardrails: boolean, threshold: number): Outcome {
199  const named = hasGuardrails && (verdict.policy_exception ?? 0) > threshold
200  const dimensions: [Dimension, number][] = [
201    ["destructive", verdict.destructive],
202    ["credentials", verdict.credentials],
203  ]
204  if (verdict.guardrails_violation !== undefined) {
205    dimensions.push(["guardrails_violation", verdict.guardrails_violation])
206  }
207  const triggering = dimensions.filter(([dimension, score]) => {
208    if (dimension === "guardrails_violation") return score > threshold && !named
209    return score > threshold
210  })
211  const decision = triggering.length > 0 ? "BLOCK" : "allow"
212  // report the worst triggering dimension, not a priority order
213  const [kind, worst] = triggering.reduce(
214    (a, b) => (b[1] > a[1] ? b : a),
215    ["destructive", 0] as [Dimension, number],
216  )
217  return { decision, kind, worst, named }
218}
219
220function blockMessage(outcome: Outcome, hasGuardrails: boolean, threshold: number): string {
221  const perKind =
222    outcome.kind === "guardrails_violation"
223      ? `\n  If this is a false positive, your human can name the command in the` +
224        `\n  MAY section of GUARDRAILS.md and restart ${HARNESS} — the gate` +
225        `\n  follows the file.`
226      : `\n  Judged destructive/leaking on its own merits — named exceptions in` +
227        `\n  GUARDRAILS.md do not override this. If it is intended, your human` +
228        `\n  can run it directly, or restart ${HARNESS} with SYSTEMONE_GATE=off` +
229        `\n  for a session that needs it.`
230  const bootstrap = hasGuardrails
231    ? ""
232    : `\n  No GUARDRAILS.md found in this repo. Your human can create one` +
233      `\n  (legacy lowercase guardrails.md is still read) and write what the` +
234      `\n  agent may and may not do — name what should` +
235      `\n  pass in the MAY section, then restart ${HARNESS}.`
236  return (
237    `SystemOne-gate: blocked command — ${outcome.kind}=${outcome.worst.toFixed(2)} > ${threshold}\n` +
238    perKind +
239    bootstrap
240  )
241}
242
243function endpointReason(status: number | undefined): string {
244  if (status === 402) return "Berget account out of credit — top up at berget.ai"
245  if (status === 401) return "authentication failed — re-login to Berget or check BERGET_API_KEY"
246  if (status === 429) return "rate limited — wait a moment and retry"
247  return "endpoint unreachable"
248}
249
250function endpointFailure(command: string, err: unknown): string {
251  return (
252    `SystemOne-gate: ${endpointReason((err as { status?: number }).status)} — command blocked.\n` +
253    `  ${command.slice(0, 200)}\n` +
254    `  ${String(err).slice(0, 160)}\n` +
255    `  Retry shortly, or set SYSTEMONE_FAIL_OPEN=1 to prefer availability.`
256  )
257}
258
259// --- cooldown ---------------------------------------------------------------
260// Circumvention cooldown: every block doubles the wait before the next
261// command is judged — 10 ms, 20 ms, 40 ms … with no ceiling. The first
262// nine blocks are imperceptible (a few false positives cost nothing);
263// the first noticeable pause arrives around block ten (5 s), and by
264// block twenty an attempt waits 1.5 h, by block twenty-five almost two
265// days: brute-forcing variants past the gate is arithmetically hopeless.
266//
267// The wait is enforced as a visible cooldown block, not a silent sleep —
268// an invisible hang looks like a crash, while the reason tells the agent
269// (and through it the human) exactly what is happening and for how long.
270// Retrying early just returns the same reason with the remaining time.
271//
272// The counter decays with quiet time — one block of memory fades per 30
273// minutes since the last block — so early false positives do not poison a
274// whole session. Decay is wall-clock, not command-count: an agent cannot
275// launder the counter by interleaving allowed commands, and an agent that
276// keeps hammering refreshes lastBlockAt on every block, so escalation
277// continues unchanged. State lives for the session; a new session or a
278// mod reload resets everything.
279const DECAY_MS = 30 * 60_000
280const BACKOFF_BASE_MS = 10
281
282function backoffMs(blocks: number): number {
283  if (blocks < 1) return 0
284  // exponent capped at 40 to keep the float well-behaved
285  return BACKOFF_BASE_MS * 2 ** Math.min(blocks - 1, 40)
286}
287
288function formatWait(remainingMs: number): string {
289  if (remainingMs >= 90_000) return `${Math.round(remainingMs / 60_000)} min`
290  if (remainingMs >= 1000) return `${Math.ceil(remainingMs / 1000)} s`
291  return `${remainingMs} ms`
292}
293
294function createCooldown() {
295  let blockCount = 0
296  let lastBlockAt = 0
297  let cooldownUntil = 0
298
299  function effectiveBlocks(now: number): number {
300    if (blockCount === 0 || lastBlockAt === 0) return 0
301    return Math.max(0, blockCount - Math.floor((now - lastBlockAt) / DECAY_MS))
302  }
303
304  function register(): void {
305    const now = Date.now()
306    blockCount = effectiveBlocks(now) + 1
307    lastBlockAt = now
308    cooldownUntil = now + backoffMs(blockCount)
309  }
310
311  function reason(): string | null {
312    const remainingMs = cooldownUntil - Date.now()
313    if (remainingMs <= 0) return null
314    return (
315      `SystemOne-gate: cooling down after ${blockCount} blocked command${blockCount === 1 ? "" : "s"} — ` +
316      `next attempt in ~${formatWait(remainingMs)}. The wait doubles with every block; ` +
317      `restarting ${HARNESS} resets it.`
318    )
319  }
320
321  return { register, reason }
322}
323
324// --- protected paths --------------------------------------------------------
325// A deterministic deny sits in front of the model: a write to a protected
326// path is a rule, not a verdict — the cooldown counter stays untouched, an
327// agent that retries pays nothing. The list is relative to the session root;
328// an entry ending in `/` protects everything below it. The path logic below
329// mirrors core.ts's foldPath/relUnder/placePath — keep the two in step.
330
331// A path as its spelling says: `.` and `..` folded, doubles collapsed, no
332// symlink followed.
333function foldPath(p: string): string {
334  const absolute = p.startsWith("/")
335  const out: string[] = []
336  for (const part of p.split(/[\\/]/)) {
337    if (!part || part === ".") continue
338    if (part === "..") {
339      if (out.length > 0) out.pop()
340    } else {
341      out.push(part)
342    }
343  }
344  return absolute ? `/${out.join("/")}` : out.join("/")
345}
346
347function relUnder(root: string, path: string): string | null {
348  const r = foldPath(root)
349  const p = foldPath(path)
350  if (r === "" || p === r) return null
351  if (r === "/") return p.slice(1)
352  return p.startsWith(`${r}/`) ? p.slice(r.length + 1) : null
353}
354
355// The matching entry, or null. Called twice (placed path, then literal
356// spelling), like core.ts matches both spellings.
357function protectedPath(root: string, resolved: string): string | null {
358  if (!root || !resolved) return null
359  // Case-folded like core.ts: `Guardrails.MD` opens guardrails.md on a
360  // case-insensitive filesystem.
361  const rel = relUnder(root, resolved)?.toLowerCase() ?? null
362  if (rel === null) return null
363  for (const entry of PROTECTED_PATHS) {
364    const pattern = entry.toLowerCase()
365    if (pattern.endsWith("/")) {
366      if (rel.startsWith(pattern)) return entry
367    } else if (rel === pattern) {
368      return entry
369    }
370  }
371  return null
372}
373
374function protectedMessage(entry: string): string {
375  return (
376    `SystemOne-gate: protected file — ${entry}\n` +
377    `  Policy and harness configuration are edited by your human, not the agent.\n` +
378    `  Ask them to make the change and restart ${HARNESS}.`
379  )
380}
381
382// Where the path lands, every symlink followed — including for a file that
383// does not exist yet: the nearest existing ancestor is resolved and the tail
384// appended, as core.ts's walk does. null when nothing resolves (an odd
385// spelling, a dangling link), and the guard then denies: the engine denies
386// without a realPath too.
387function placeable(path: string): boolean {
388  const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"))
389  const name = path.slice(cut + 1)
390  return (
391    !/^[A-Za-z]:(?![\\/])/.test(path) &&
392    !/^[\\/][\\/]/.test(path) &&
393    !/^[A-Za-z]:/.test(name) &&
394    name !== "" &&
395    name !== "." &&
396    name !== ".."
397  )
398}
399
400async function place(
401  $: { fs: { stat(path: string, options: { resolve: boolean }): Promise<{ realPath?: string } | undefined> } },
402  path: string,
403): Promise<string | null> {
404  if (!placeable(path)) return null
405  const tail: string[] = []
406  let target = path
407  for (;;) {
408    const own = await $.fs.stat(target, { resolve: true }).catch(() => undefined)
409    if (own) {
410      if (own.realPath === undefined) return null
411      let real = own.realPath.replace(/[\\/]+$/, "")
412      for (const name of tail) real = `${real}/${name}`
413      return real
414    }
415    const stripped = target.replace(/[\\/]+$/, "")
416    const cut = Math.max(stripped.lastIndexOf("/"), stripped.lastIndexOf("\\"))
417    const name = stripped.slice(cut + 1)
418    if (cut < 0 || name === "" || name === "." || name === ".." || /^[A-Za-z]:/.test(name)) return null
419    tail.unshift(name)
420    target = stripped.slice(0, cut + 1)
421  }
422}
423
424// --- the module -------------------------------------------------------------
425
426interface Session {
427  guardrails: string | null
428  key: string | undefined
429  baseURL: string
430  model: string
431  threshold: number
432  failOpen: boolean
433  off: boolean
434  cwd: string
435  root: string
436  warnings: string[]
437  cooldown: ReturnType<typeof createCooldown>
438}
439
440class EndpointError extends Error {
441  constructor(
442    readonly status: number,
443    body: string,
444  ) {
445    super(`System One endpoint answered ${status}: ${body.slice(0, 120)}`)
446  }
447}
448
449async function firstReadable(read: (path: string) => Promise<string>, paths: string[]): Promise<string | null> {
450  for (const path of paths) {
451    try {
452      return await read(path)
453    } catch {}
454  }
455  return null
456}
457
458export const register: Register = (on) => {
459  let session: Session | null = null
460
461  on("session.start", async ($, e, next) => {
462    const raw = await firstReadable((path) => $.fs.read(path), GUARDRAIL_PATHS.map((p) => `${e.cwd}/${p}`))
463    const guardrails = raw === null ? null : truncateGuardrails(raw)
464    const rootStat = await $.fs.stat(e.cwd, { resolve: true }).catch(() => undefined)
465    const threshold = parseThreshold(await $.env.get("SYSTEMONE_THRESHOLD"))
466    session = {
467      cwd: e.cwd,
468      root: rootStat?.realPath && rootStat.realPath !== "" ? rootStat.realPath : e.cwd,
469      guardrails,
470      key: (await $.env.get("BERGET_API_KEY")) ?? (await $.env.get("TYPESAFE_API_KEY")),
471      baseURL: gatewayRoot((await $.env.get("BERGET_BASE_URL")) ?? (await $.env.get("TYPESAFE_BASE_URL")) ?? "https://api.berget.ai"),
472      model: (await $.env.get("BERGET_MODEL")) ?? (await $.env.get("TYPESAFE_DEFAULT_MODEL")) ?? "berget/bev",
473      threshold: threshold.value,
474      failOpen: isEnabled(await $.env.get("SYSTEMONE_FAIL_OPEN")),
475      off: (await $.env.get("SYSTEMONE_GATE")) === "off",
476      warnings: [threshold.warning, truncationWarning(guardrails)].filter((w): w is string => w !== undefined),
477      cooldown: createCooldown(),
478    }
479    for (const warning of session.warnings) $.ui.toast(warning)
480    if (!session.off && !session.key) {
481      $.ui.toast("guardrails-md inactive: no BERGET_API_KEY or TYPESAFE_API_KEY — Bash and Monitor commands run ungated this session")
482    }
483    return next(e)
484  })
485
486  on("tool.call", { tool: ["Bash", "Monitor"] }, async ($, e, next) => {
487    if (e.command === undefined) return next(e)
488    if (!session) return { deny: "SystemOne-gate: no frozen policy — session.start did not run. Restart Claude Code (fail-closed)." }
489    const s = session
490    const command = e.command.trim()
491    if (s.off || !s.key || !command) return next(e)
492    const cooling = s.cooldown.reason()
493    if (cooling) return { deny: cooling }
494    const deny = (reason: string) => ({ deny: [reason, ...s.warnings.map((w) => `  ${w}`)].join("\n") })
495
496    const scripts: string[] = []
497    for (const token of command.split(/\s+/)) {
498      if (scripts.length >= SCRIPT_FILES_MAX) break
499      const path = scriptPath(token)
500      if (!path) continue
501      try {
502        const st = await $.fs.stat(path)
503        if (st.kind !== "file" || st.size > SCRIPT_BYTES_MAX) continue
504        const section = scriptSection(path, await $.fs.read(path))
505        if (section) scripts.push(section)
506      } catch {}
507    }
508
509    let answers: unknown
510    const stop = new AbortController()
511    try {
512      const timeout = $.clock.sleep(TIMEOUT_MS, { signal: AbortSignal.any([stop.signal, next.signal]) }).then(() => {
513        throw new Error(`System One endpoint timed out after ${TIMEOUT_MS} ms`)
514      })
515      timeout.catch(() => {})
516      const res = await Promise.race([
517        $.http.fetch(`${s.baseURL}/v1/systemone`, {
518          method: "POST",
519          headers: { Authorization: `Bearer ${s.key}`, Accept: "application/json", "Content-Type": "application/json" },
520          body: JSON.stringify({
521            state: { text: buildStateText(command, scripts.join("\n"), s.guardrails) },
522            questions: buildQuestions(!!s.guardrails),
523            model: s.model,
524          }),
525        }),
526        timeout,
527      ])
528      if (!res.ok) throw new EndpointError(res.status, res.text)
529      answers = JSON.parse(res.text).answers
530    } catch (err) {
531      if (s.failOpen) return next(e)
532      return deny(endpointFailure(command, err))
533    } finally {
534      stop.abort()
535    }
536
537    const outcome = decide(verdictFrom(answers), !!s.guardrails, s.threshold)
538    if (outcome.decision === "allow") return next(e)
539    s.cooldown.register()
540    return deny(blockMessage(outcome, !!s.guardrails, s.threshold) + `\n  ${command.slice(0, 200)}`)
541  }).catch(($, e, next) => ({
542    deny: `SystemOne-gate: the gate failed (${next.error.kind}${next.error.message ? `: ${next.error.message}` : ""}) — command blocked (fail-closed).`,
543  }))
544
545  on("tool.call", { tool: ["Edit", "Write", "NotebookEdit"] }, async ($, e, next) => {
546    if (!session) return { deny: "SystemOne-gate: no frozen policy — session.start did not run. Restart Claude Code (fail-closed)." }
547    const s = session
548    if (s.off) return next(e)
549    const target = e.tool === "NotebookEdit" ? e.notebook_path : e.file_path
550    if (typeof target !== "string" || target === "") return next(e)
551    const placed = await place($, target)
552    if (placed === null) {
553      return {
554        deny:
555          `SystemOne-gate: cannot resolve ${JSON.stringify(target)} — edit blocked (fail-closed).\n` +
556          `  The path could not be checked against the protected list.`,
557      }
558    }
559    const hit = protectedPath(s.root, placed) ?? protectedPath(s.cwd, target)
560    if (hit === null) return next(e)
561    return { deny: [protectedMessage(hit), ...s.warnings.map((w) => `  ${w}`)].join("\n") }
562  }).catch(($, e, next) => ({
563    deny: `SystemOne-gate: the gate failed (${next.error.kind}${next.error.message ? `: ${next.error.message}` : ""}) — edit blocked (fail-closed).`,
564  }))
565}
566