@agent-guardrails/opencode-shell-warden-hook 0.1.0 → 0.2.1

package/README.md

@@ -1,42 +1,28 @@
 # opencode-shell-warden-hook
 
-Thin **OpenCode V2** plugin (the "hook" part of the shell-warden system): it receives permission
-evaluation events from OpenCode and asks the **shell-warden engine** for a verdict over
-NDJSON JSON-RPC on stdio.
-
-The shim contains **no policy logic** — only transport, supervision, budgets, verdict application
-and fail-closed degradation. Spec: `agent-guardrails/opencode-adrs` → `docs/policyd-plugin-design/`
-(`03-shim.md`, `04-shim-config.md`, `02-protocol.md`).
-
-## How it works
-
-```
-OpenCode server ── permission.hook("evaluate") ── shim ── policy/check ──▶ shell-warden engine
-                        ◀── tighten-only verdict ───────────── verdict: allow | ask | deny
-```
-
-- `allow` / `deny` are applied to the hook event; `ask` falls through to OpenCode's native prompt.
-- The shim never loosens a decision and never synthesizes `allow`: any engine anomaly
-  (crash, timeout, malformed frame, bad protocol version) degrades to `onEngineError` (`ask` or `deny`).
-- Engine runs as a persistent child process spawned **without inherited environment**, from an
-  **absolute** argv, with an exact `protocolVersion` handshake.
+OpenCode V2 hook plugin: forwards shell permission decisions to the shell-warden
+checker over the one-shot letter protocol ([ADR-0016](https://github.com/agent-guardrails/docs/blob/main/adr/0016-two-tier-enforcement.md) —
+no server, no long-lived process; the checker is spawned fresh on every check).
 
 ## Install
 
 ```sh
-npm install opencode-shell-warden-hook   # or reference a local checkout
+npm install @agent-guardrails/opencode-shell-warden-hook
 ```
 
-`opencode.jsonc`:
+`opencode.jsonc` (options per `docs/spec/shell-warden/04-shim-config.md` v2.0):
 
 ```jsonc
 {
   "plugins": [
     {
-      "package": "opencode-shell-warden-hook",
+      "package": "@agent-guardrails/opencode-shell-warden-hook",
       "options": {
-        "engine": { "command": ["/usr/local/bin/shell-warden", "serve"] },
-        "onEngineError": "ask",
+        "checker": {
+          "command": ["/opt/homebrew/bin/shell-warden", "--config", "/Users/me/.config/shell-warden/config.jsonc"]
+        },
+        "budgets": { "checkTimeoutMs": 2000, "killGraceMs": 250 },
+        "onCheckerError": "ask",
         "actions": ["shell"]
       }
     }
@@ -44,33 +30,24 @@ npm install opencode-shell-warden-hook   # or reference a local checkout
 }
 ```
 
-All options, defaults and clamps: `04-shim-config.md` in the spec repo. Unknown keys are ignored
-with a warning; invalid `engine.command` (relative path, failed `{env:…}` substitution) disables
-the plugin at load — that is the fail-closed posture for misconfiguration.
-
-## Development
+## How it works
 
-```sh
-npm install
-npm test        # node --test (35 contract/unit tests, mock engine included)
-npm run typecheck
+```
+OpenCode server ── permission.asked ── shim ── spawn shell-warden (letter in → verdict out)
+                                     ◀── allow | ask | deny ── (one JSON verdict, then EOF)
 ```
 
-Layout:
-
-| Module | Responsibility |
-|---|---|
-| `src/protocol.ts` | NDJSON framing, byte caps, frame parser, id pool |
-| `src/supervisor.ts` | engine lifecycle: spawn → handshake → ready, violations → restart → unhealthy, dispose |
-| `src/cache.ts` | allow-only TTL LRU verdict cache |
-| `src/apply.ts` | request building, cache keys, tighten-only verdict mapping |
-| `src/config.ts` | options validation (fatal vs warn+clamp) |
-| `src/index.ts` | `Plugin.define` + hook registrations |
-
-Tests run on Node ≥ 22.6 using native TypeScript type-stripping (no build step).
-The engine side (segmentation, rules, verdicts) is a separate project: `agent-guardrails/shell-warden`.
-
-## Status
-
-M0/M1 (shim): implemented — protocol codec, supervisor, cache, apply, config, hook wiring.
-Not yet: `policy/observe` hardening, sha256 pinning is implemented at spawn only (no MDM story), engine itself.
+- `allow` → the request is confirmed (`once`); `deny` → rejected with the checker's
+  prescriptive message; `ask` → the request is left untouched for the native prompt.
+- The checker is a pure function of (letter, config): one spawn per check, empty
+  child environment, no cache, no network, no state (02-letter-verdict §2.1).
+- The shim never loosens a decision and never synthesizes `allow`: checker defects
+  (exit ≠ 0, timeout, malformed output, schema drift) degrade to `onCheckerError`
+  (`ask` or `deny`).
+- Hook-owned state: allow-only cache (`cache.ttlMs`) and the reject budget per rule
+  per session (`rejectBudget`) — exhaustion hands the ask to the human.
+
+All options, defaults and clamps: `04-shim-config.md` in the spec repo. Unknown keys
+are ignored with a warning; only a broken `checker.command` / `sha256` /
+`onCheckerError: "allow"` disables the plugin at load — the fail-closed posture
+for misconfiguration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-guardrails/opencode-shell-warden-hook",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "OpenCode V2 hook plugin: forwards shell permission decisions to the shell-warden engine over NDJSON JSON-RPC stdio",
   "type": "module",
   "repository": {

package/src/apply.ts

@@ -1,23 +1,15 @@
 // Reply automation per ADR-0013 — the shim resolves published permission
 // requests programmatically (the same right the human exercises):
-//   engine allow → reply "once" (command runs)
-//   engine deny  → reply "reject" (with reason)
-//   engine ask   → no reply (escalation by silence — the human decides)
-// The shim never mutates permission events (the evaluate-allow path is not
-// honored by OpenCode v2.2.x anyway — live-proven).
+//   checker allow → reply "once" (command runs)
+//   checker deny  → reply "reject" (with the prescriptive reason)
+//   checker ask   → no reply (escalation by silence — the human decides)
+// The shim never mutates permission events and never synthesizes allow.
 
 import { createHash } from "node:crypto"
-import type { CheckParams, CheckResult, Verdict } from "./types.ts"
+import type { Letter, LetterVerdict } from "./types.ts"
 
-export type CheckOutcome = { ok: true; result: CheckResult } | { ok: false; reason: string }
-
-export interface AskData {
-  id: string                          // requestID, assigned at publication
-  sessionID: string
-  action: string
-  resources: readonly string[]
-  source?: { type: "tool"; messageID: string; id: string }
-}
+export type { AskData, Verdict, LetterCommandVerdict } from "./types.ts"
+import type { AskData } from "./types.ts"
 
 export function invocationIdOf(source?: { messageID: string; id: string }, sessionID?: string, action?: string): string {
   return source ? `${source.messageID}:${source.id}` : `anon:${sessionID ?? ""}:${action ?? ""}`
@@ -35,52 +27,35 @@ export function cacheKey(action: string, resources: readonly string[], cwd: stri
     .digest("hex")
 }
 
-export function buildCheckRequest(args: {
+/** Letter per 02-letter-verdict.md §2.2 — exactly the schema fields, no extras.
+ * `projectDir` is required and non-empty: the engine invalidates every letter whose
+ * commands[].cwd is empty ("letter commands[0].cwd must be 1..4096 chars"), and the
+ * ask payload carries no per-command cwd — the permission request's directory is the
+ * only cwd the shim has. Callers without a directory must degrade before calling. */
+export function buildLetter(args: {
   data: AskData
   invocationId: string
-  cwd: string
-  projectDir?: string
-}): CheckParams {
-  const { data, invocationId, cwd, projectDir } = args
+  projectDir: string
+  agent?: string
+}): Letter {
+  const { data, invocationId, projectDir, agent } = args
+  if (!projectDir) throw new Error("buildLetter: projectDir is required — the engine rejects letters with an empty commands[].cwd")
   return {
+    version: 1,
     invocation: {
       id: invocationId,
       sessionID: data.sessionID ?? "",
-      hook: "permission.asked",
-      ...(projectDir !== undefined ? { projectDir } : {}),
-      startedAt: new Date().toISOString(),
+      ...(agent !== undefined ? { agent } : {}),
+      projectDir,
     },
     action: data.action ?? "",
-    commands: (data.resources ?? []).map((raw, index) => ({ index, raw, cwd })),
-    context: {
-      ...(data.source !== undefined ? { source: data.source } : {}),
-    },
+    commands: (data.resources ?? []).map((raw, index) => ({ index, raw, cwd: projectDir })),
   }
 }
 
 /** Maps a verdict to the reply decision: `"once"` | `"reject"` | `null` (silence). */
-export function replyDecision(v: Verdict): "once" | "reject" | null {
+export function replyDecision(v: LetterVerdict["verdict"]): "once" | "reject" | null {
   if (v === "allow") return "once"
   if (v === "deny") return "reject"
   return null
 }
-
-/** Best-effort per-invocation cache eviction registry (bounded). */
-export class InvocationRegistry {
-  private readonly cap: number
-  private map = new Map<string, string>()
-  constructor(cap = 256) {
-    this.cap = cap
-  }
-  remember(invocationId: string, key: string): void {
-    this.map.set(invocationId, key)
-    while (this.map.size > this.cap) {
-      const oldest = this.map.keys().next()
-      if (oldest.done === true) break
-      this.map.delete(oldest.value)
-    }
-  }
-  keyFor(invocationId: string): string | undefined {
-    return this.map.get(invocationId)
-  }
-}

package/src/checker.ts

@@ -0,0 +1,181 @@
+// One-shot checker invoker — docs/spec/shell-warden/02-letter-verdict.md (v2.0).
+// Spawn the checker for each check with an EMPTY environment (I1), feed exactly
+// one letter, read exactly one verdict. Any deviation (exit≠0, timeout, non-JSON,
+// shape mismatch, oversize) is a checker defect ⇒ degrade (§2.4 / 09 §9.4):
+// the hook never parses garbage into a verdict.
+
+import { spawn } from "node:child_process"
+import { createHash } from "node:crypto"
+import { readFileSync } from "node:fs"
+import type { Letter, LetterVerdict, Verdict } from "./types.ts"
+import { MAX_VERDICT_BYTES, MAX_FACTS_BYTES, MAX_MESSAGE_CHARS } from "./types.ts"
+
+export interface CheckerOptions {
+  command: string[]
+  sha256: string | null
+  checkTimeoutMs: number
+  killGraceMs: number
+  maxConcurrentSpawns: number
+  log: (level: "debug" | "info" | "warn" | "error", msg: string) => void
+}
+
+export type CheckerOutcome = { ok: true; verdict: LetterVerdict } | { ok: false; reason: string }
+
+// Binary pin (I8): sha256 of checker.command[0]; mismatch = fatal for every spawn.
+let pinState: "unverified" | "ok" | "mismatch" | "unreadable" = "unverified"
+
+export function verifyPin(o: CheckerOptions): void {
+  if (o.sha256 === null) { pinState = "ok"; return }
+  try {
+    const digest = createHash("sha256").update(readFileSync(o.command[0] ?? "")).digest("hex")
+    pinState = digest === o.sha256 ? "ok" : "mismatch"
+  } catch {
+    pinState = "unreadable"
+  }
+  if (pinState !== "ok") o.log("warn", `checker sha256 pin (${pinState}) — every check will degrade`)
+}
+
+export class CheckerInvoker {
+  private inflight = 0
+  private readonly opts: CheckerOptions
+
+  constructor(opts: CheckerOptions) {
+    this.opts = opts
+  }
+
+  async check(letter: Letter): Promise<CheckerOutcome> {
+    if (this.inflight >= this.opts.maxConcurrentSpawns) return { ok: false, reason: "spawn budget exceeded (local degrade)" }
+    if (pinState === "mismatch" || pinState === "unreadable") return { ok: false, reason: `checker sha256 pin ${pinState}` }
+    this.inflight++
+    try {
+      return await this.runOnce(letter)
+    } finally {
+      this.inflight--
+    }
+  }
+
+  private runOnce(letter: Letter): Promise<CheckerOutcome> {
+    const { command, checkTimeoutMs, killGraceMs, log } = this.opts
+    return new Promise<CheckerOutcome>((resolve) => {
+      const bin = command[0] ?? ""
+      const child = spawn(bin, command.slice(1), {
+        env: {},             // I1: empty environment — no PATH, no variables
+        stdio: ["pipe", "pipe", "pipe"],
+      })
+
+      let out = ""
+      const kill = setTimeout(() => {
+        child.kill("SIGTERM")
+        setTimeout(() => { try { child.kill("SIGKILL") } catch { /* already dead */ } }, killGraceMs)
+      }, checkTimeoutMs)
+
+      child.stdout?.setEncoding("utf8")
+      child.stdout?.on("data", (chunk: string) => {
+        out += chunk
+        if (out.length > MAX_VERDICT_BYTES) {
+          try { child.kill("SIGTERM") } catch { /* already dead */ }
+        }
+      })
+
+      child.on("error", (err) => {
+        clearTimeout(kill)
+        resolve({ ok: false, reason: `spawn failure: ${err.message}` })
+      })
+      child.stdin?.on("error", () => { /* EPIPE on early exit — close handler decides */ })
+      child.stdio[2]?.on("data", (chunk: string) => log("debug", `checker: ${String(chunk).trim()}`))
+
+      child.stdin?.end(JSON.stringify(letter))
+
+      let settled = false
+      const done = (o: CheckerOutcome) => {
+        if (settled) return
+        settled = true
+        clearTimeout(kill)
+        resolve(o)
+      }
+      child.on("close", (code) => {
+        if (code !== 0) { done({ ok: false, reason: `checker exit ${code ?? "signal"}` }); return }
+        if (out.length === 0) { done({ ok: false, reason: "checker produced no verdict" }); return }
+        const parsed = parseVerdict(letter, out)
+        done(parsed.ok ? { ok: true, verdict: parsed.value } : { ok: false, reason: parsed.reason ?? "verdict shape" })
+      })
+    })
+  }
+}
+
+function parseVerdict(letter: Letter, raw: string): { ok: true; value: LetterVerdict } | { ok: false; reason: string } {
+  let value: unknown
+  try {
+    value = JSON.parse(raw.trim())
+  } catch (e) {
+    return { ok: false, reason: `unparseable verdict: ${e instanceof Error ? e.message.slice(0, 120) : "not json"}` }
+  }
+  if (value === null || typeof value !== "object") return { ok: false, reason: "verdict is not an object" }
+  const v = value as Record<string, unknown>
+
+  if (v.invocationId !== letter.invocation.id) return { ok: false, reason: "verdict.invocationId mismatch" }
+  const verdict = v.verdict
+  if (verdict !== "allow" && verdict !== "ask" && verdict !== "deny") return { ok: false, reason: `verdict "${String(verdict)}" invalid` }
+  if (typeof v.message !== "undefined") {
+    if (typeof v.message !== "string" || v.message.length > MAX_MESSAGE_CHARS) return { ok: false, reason: "verdict.message overbound" }
+    if (verdict === "deny" && v.message.length === 0) return { ok: false, reason: "deny without prescriptive message" }
+  } else if (verdict === "deny") {
+    return { ok: false, reason: "deny without prescriptive message" }
+  }
+
+  // commands[]: exactly one entry per letter command, indexes match.
+  const cmds = v.commands
+  if (!Array.isArray(cmds) || cmds.length !== letter.commands.length) {
+    return { ok: false, reason: "verdict.commands must cover every letter command" }
+  }
+  for (let i = 0; i < letter.commands.length; i++) {
+    const c = cmds[i]
+    if (c === null || typeof c !== "object") return { ok: false, reason: `verdict.commands[${i}] is not an object` }
+    const cv = c as Record<string, unknown>
+    if (cv.index !== letter.commands[i]?.index) return { ok: false, reason: `verdict.commands[${i}].index mismatch` }
+    if (cv.verdict !== "allow" && cv.verdict !== "ask" && cv.verdict !== "deny") {
+      return { ok: false, reason: `commands[${i}].verdict invalid` }
+    }
+    if (typeof cv.classification !== "undefined" && cv.classification !== "static" && cv.classification !== "opaque") {
+      return { ok: false, reason: `commands[${i}].classification invalid` }
+    }
+    if (typeof cv.match !== "undefined" && cv.match !== "argv" && cv.match !== "raw") {
+      return { ok: false, reason: `commands[${i}].match invalid` }
+    }
+    if (cv.facts !== undefined) {
+      const bytes = JSON.stringify(cv.facts).length
+      if (bytes > MAX_FACTS_BYTES) return { ok: false, reason: `commands[${i}].facts overbound` }
+    }
+  }
+  return { ok: true, value: { invocationId: v.invocationId as string, verdict: verdict as Verdict, ...(typeof v.message === "string" ? { message: v.message } : {}) } }
+}
+
+/** Reject-budget per ruleId per session (ADR-0010 / 04 §4.2): on exhaustion the hook
+ * stops answering — the ask flows to the human; never auto-allowed. */
+export class RejectBudgets {
+  private readonly maxRejections: number
+  private readonly windowMs: number
+  private spend = new Map<string, { count: number; until: number }>()
+
+  constructor(maxRejections: number, windowMs: number) {
+    this.maxRejections = maxRejections
+    this.windowMs = windowMs
+  }
+
+  /** Returns false when the rule is exhausted for this session. */
+  trySpend(sessionID: string, ruleId: string, now = Date.now()): boolean {
+    if (this.maxRejections <= 0) return false
+    const key = `${sessionID}\u0000${ruleId}`
+    const cur = this.spend.get(key)
+    if (cur === undefined || cur.until <= now) {
+      this.spend.set(key, { count: 1, until: now + this.windowMs })
+      return true
+    }
+    cur.count++
+    if (cur.count > this.maxRejections) {
+      cur.until = now + this.windowMs
+      return false
+    }
+    return true
+  }
+}