@agent-guardrails/opencode-shell-warden-hook 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# opencode-shell-warden-hook
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 @agent-guardrails/opencode-shell-warden-hook
+```
+
+`opencode.jsonc` (options per `docs/spec/shell-warden/04-shim-config.md` v2.0):
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@agent-guardrails/opencode-shell-warden-hook",
+      "options": {
+        "checker": {
+          "command": ["/opt/homebrew/bin/shell-warden", "--config", "/Users/me/.config/shell-warden/config.jsonc"]
+        },
+        "budgets": { "checkTimeoutMs": 2000, "killGraceMs": 250 },
+        "onCheckerError": "ask",
+        "actions": ["shell"]
+      }
+    }
+  ]
+}
+```
+
+## How it works
+
+```
+OpenCode server ── permission.asked ── shim ── spawn shell-warden (letter in → verdict out)
+                                     ◀── allow | ask | deny ── (one JSON verdict, then EOF)
+```
+
+- `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,34 @@
 {
   "name": "@agent-guardrails/opencode-shell-warden-hook",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "OpenCode V2 hook plugin: forwards shell permission decisions to the shell-warden engine over NDJSON JSON-RPC stdio",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agent-guardrails/opencode-shell-warden-hook.git"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@opencode/plugin": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "test": "node --test test/",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
+  "license": "MIT"
+}

package/src/apply.ts

@@ -0,0 +1,56 @@
+// Reply automation per ADR-0013 — the shim resolves published permission
+// requests programmatically (the same right the human exercises):
+//   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 { Letter, LetterVerdict } from "./types.ts"
+
+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 ?? ""}`
+}
+
+export function cacheKey(action: string, resources: readonly string[], cwd: string, agent?: string): string {
+  return createHash("sha256")
+    .update(action)
+    .update("\u0000")
+    .update((resources ?? []).join("\u0000"))
+    .update("\u0000")
+    .update(cwd)
+    .update("\u0000")
+    .update(agent ?? "")
+    .digest("hex")
+}
+
+/** Letter per 02-letter-verdict.md §2.2 — exactly the schema fields, no extras. */
+export function buildLetter(args: {
+  data: AskData
+  invocationId: string
+  projectDir?: string
+  agent?: string
+}): Letter {
+  const { data, invocationId, projectDir, agent } = args
+  return {
+    version: 1,
+    invocation: {
+      id: invocationId,
+      sessionID: data.sessionID ?? "",
+      ...(agent !== undefined ? { agent } : {}),
+      ...(projectDir !== undefined ? { projectDir } : {}),
+    },
+    action: data.action ?? "",
+    commands: (data.resources ?? []).map((raw, index) => ({ index, raw, cwd: "" })),
+  }
+}
+
+/** Maps a verdict to the reply decision: `"once"` | `"reject"` | `null` (silence). */
+export function replyDecision(v: LetterVerdict["verdict"]): "once" | "reject" | null {
+  if (v === "allow") return "once"
+  if (v === "deny") return "reject"
+  return null
+}

package/src/cache.ts

@@ -0,0 +1,46 @@
+// Verdict cache — docs/policyd-plugin-design/03-shim.md §3.4
+// Allow-only, TTL from the engine, size-bounded LRU. Denies are never cached.
+
+export interface CacheEntry {
+  verdict: "allow"
+  message?: string
+  expiresAt: number
+}
+
+export class VerdictCache {
+  private readonly maxEntries: number
+  private readonly clock: () => number
+  private map = new Map<string, CacheEntry>()
+
+  constructor(maxEntries: number, clock: () => number = Date.now) {
+    this.maxEntries = maxEntries
+    this.clock = clock
+  }
+
+  get(key: string): CacheEntry | null {
+    const e = this.map.get(key)
+    if (e === undefined) return null
+    if (e.expiresAt <= this.clock()) {
+      this.map.delete(key)
+      return null
+    }
+    // LRU touch
+    this.map.delete(key)
+    this.map.set(key, e)
+    return e
+  }
+
+  put(key: string, ttlMs: number, message?: string): void {
+    if (ttlMs <= 0) return
+    while (this.map.size >= this.maxEntries) {
+      const oldest = this.map.keys().next()
+      if (oldest.done === true) break
+      this.map.delete(oldest.value)
+    }
+    this.map.set(key, { verdict: "allow", message, expiresAt: this.clock() + ttlMs })
+  }
+
+  invalidate(): void {
+    this.map.clear()
+  }
+}

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
+  }
+}

package/src/config.ts

@@ -0,0 +1,156 @@
+// Hook options — docs/spec/shell-warden/04-shim-config.md (v2.0, one-shot per-check).
+// Unknown keys ⇒ warn + ignore; clamps warn + apply; ONLY checker.command / sha256 /
+// onCheckerError:"allow" are fatal (plugin disables itself — the honest fail-closed
+// posture for load-time misconfiguration).
+
+type Resolved = { ok: true; config: Opts; warns: string[] } | { ok: false; reason: string }
+
+export interface CheckerOpts {
+  command: string[]
+  sha256: string | null
+}
+
+export interface BudgetsOpts {
+  checkTimeoutMs: number   // 100..30_000, def 2_000 — verdict deadline (SIGTERM → killGraceMs → SIGKILL)
+  killGraceMs: number      // 50..2_000,  def 250 — SIGTERM → SIGKILL
+  maxRequestCommands: number // 1..128, def 32 — breach ⇒ local degrade, no spawn (02 §2.2)
+  maxConcurrentSpawns: number // 1..64, def 8 — excess ⇒ local degrade, never queued
+}
+
+export interface OptionsOpts {
+  enabled: boolean
+  checker: CheckerOpts
+  budgets: BudgetsOpts
+  onCheckerError: "ask" | "deny"   // degrade verdict; "allow" is not a valid value (I3)
+  actions: string[]
+  actionsAll: boolean              // actions includes "*"
+  cache: { enabled: boolean; maxEntries: number; ttlMs: number }
+  rejectBudget: { maxRejections: number; windowMs: number }
+  asConfig: { observeShell: boolean }
+  debug: { enabled: boolean; dir: string | null }
+  logLevel: "debug" | "info" | "warn" | "error"
+}
+export type Opts = OptionsOpts
+
+function isInt(v: unknown): v is number { return typeof v === "number" && Number.isInteger(v) }
+
+function clampInt(v: unknown, min: number, max: number, def: number, name: string, warns: string[]): number {
+  let x = isInt(v) ? v : def
+  if (!isInt(v) && v !== undefined) warns.push(`omit/wrong type for ${name}, using ${def}`)
+  if (x < min) { warns.push(`${name} ${x} < ${min}, clamped to ${min}`); x = min }
+  if (x > max) { warns.push(`${name} ${x} > ${max}, clamped to ${max}`); x = max }
+  return x
+}
+
+/** "{env:NAME}" member substitution resolved at setup; unresolved is fatal (I2). */
+function substituteEnv(member: string): string | null {
+  const m = /^\{env:([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(member)
+  if (!m) return member
+  const value = process.env[m[1] ?? ""]
+  return value === undefined || value === "" ? null : value
+}
+
+const KNOWN_KEYS = new Set(["enabled", "checker", "budgets", "onCheckerError", "actions", "cache", "rejectBudget", "asConfig", "debug", "logLevel"])
+const CHECKER_KEYS = new Set(["command", "sha256"])
+const BUDGET_KEYS = new Set(["checkTimeoutMs", "killGraceMs", "maxRequestCommands", "maxConcurrentSpawns"])
+const CACHE_KEYS = new Set(["enabled", "maxEntries", "ttlMs"])
+const REJECT_KEYS = new Set(["maxRejections", "windowMs"])
+const ASKEYS = new Set(["observeShell"])
+const DEBUG_KEYS = new Set(["enabled", "dir"])
+
+function warnUnknown(scope: string, keys: object, known: Set<string>, warns: string[]): void {
+  for (const k of Object.keys(keys ?? {})) if (!known.has(k)) warns.push(`${scope}: unknown key "${k}" ignored`)
+}
+
+export function validateOptions(o: unknown): Resolved {
+  const warns: string[] = []
+  if (o === null || typeof o !== "object" || Array.isArray(o)) o = {}
+  const rec = o as Record<string, unknown>
+  warnUnknown("", rec, KNOWN_KEYS, warns)
+
+  const enabled = rec.enabled === undefined ? true : rec.enabled === true
+
+  // ── checker (fatal on defects) ──
+  const rawChecker = (rec.checker ?? {}) as Record<string, unknown>
+  if (rec.checker !== undefined && (typeof rec.checker !== "object")) return { ok: false, reason: "checker must be an object" }
+  warnUnknown("checker", rawChecker, CHECKER_KEYS, warns)
+  const rawCommand = rawChecker.command
+  if (!Array.isArray(rawCommand) || rawCommand.length === 0 || rawCommand.some((m) => typeof m !== "string")) {
+    return { ok: false, reason: "checker.command must be a non-empty string array" }
+  }
+  const command: string[] = []
+  for (const member of rawCommand as string[]) {
+    const resolved = substituteEnv(member)
+    if (resolved === null) return { ok: false, reason: `checker.command member "${member}" failed {env:…} substitution` }
+    command.push(resolved)
+  }
+  if (!command[0]?.startsWith("/")) return { ok: false, reason: `checker.command[0] must be an absolute path, got "${command[0]}"` }
+  const sha256raw = rawChecker.sha256
+  if (sha256raw !== undefined && sha256raw !== null && !/^[0-9a-f]{64}$/.test(String(sha256raw))) {
+    return { ok: false, reason: "checker.sha256 must be null or 64 hex chars" }
+  }
+  const sha256 = sha256raw === undefined ? null : (sha256raw as string | null)
+
+  // ── budgets ──
+  const rawBudgets = (rec.budgets ?? {}) as Record<string, unknown>
+  warnUnknown("budgets", rawBudgets, BUDGET_KEYS, warns)
+  const budgets = {
+    checkTimeoutMs: clampInt(rawBudgets.checkTimeoutMs, 100, 30_000, 2_000, "checkTimeoutMs", warns),
+    killGraceMs: clampInt(rawBudgets.killGraceMs, 50, 2_000, 250, "killGraceMs", warns),
+    maxRequestCommands: clampInt(rawBudgets.maxRequestCommands, 1, 128, 32, "maxRequestCommands", warns),
+    maxConcurrentSpawns: clampInt(rawBudgets.maxConcurrentSpawns, 1, 64, 8, "maxConcurrentSpawns", warns),
+  }
+
+  // ── onCheckerError ──
+  const onError = (rec.onCheckerError ?? "ask") as string
+  if (onError === "allow") return { ok: false, reason: "onCheckerError must be 'ask' or 'deny' — never 'allow' (I3)" }
+  if (onError !== "ask" && onError !== "deny") {
+    warns.push(`onCheckerError "${onError}" is not ask|deny, using ask`)
+  }
+  const onCheckerError: "ask" | "deny" = onError === "deny" ? "deny" : "ask"
+
+  // ── actions ──
+  const actionsAll: boolean = rec.actions === "*" || (Array.isArray(rec.actions) && rec.actions.includes("*"))
+  const actions = Array.isArray(rec.actions)
+    ? (rec.actions as unknown[]).filter((a): a is string => typeof a === "string" && a !== "*")
+    : ["shell"]
+  if (!Array.isArray(rec.actions) && rec.actions !== undefined && rec.actions !== "*") warns.push("actions must be an array, using [shell]")
+
+  // ── cache ──
+  const rawCache = (rec.cache ?? {}) as Record<string, unknown>
+  warnUnknown("cache", rawCache, CACHE_KEYS, warns)
+  const cache = {
+    enabled: rawCache.enabled === undefined ? true : rawCache.enabled === true,
+    maxEntries: clampInt(rawCache.maxEntries, 16, 100_000, 1_024, "cache.maxEntries", warns),
+    ttlMs: clampInt(rawCache.ttlMs, 0, 3_600_000, 0, "cache.ttlMs", warns),
+  }
+
+  // ── rejectBudget ──
+  const rawReject = (rec.rejectBudget ?? {}) as Record<string, unknown>
+  warnUnknown("rejectBudget", rawReject, REJECT_KEYS, warns)
+  const rejectBudget = {
+    maxRejections: clampInt(rawReject.maxRejections, 1, 10, 3, "rejectBudget.maxRejections", warns),
+    windowMs: clampInt(rawReject.windowMs, 60_000, 86_400_000, 1_800_000, "rejectBudget.windowMs", warns),
+  }
+
+  // ── asConfig / debug / logLevel ──
+  const rawAs = (rec.asConfig ?? {}) as Record<string, unknown>
+  warnUnknown("asConfig", rawAs, ASKEYS, warns)
+  const asConfig = { observeShell: rawAs.observeShell === true }
+
+  const rawDebug = (rec.debug ?? {}) as Record<string, unknown>
+  warnUnknown("debug", rawDebug, DEBUG_KEYS, warns)
+  let debugDir: string | null = typeof rawDebug.dir === "string" ? rawDebug.dir : null
+  if (debugDir !== null && !debugDir.startsWith("/")) { warns.push("debug.dir must be absolute, ignored"); debugDir = null }
+  const debug = { enabled: rawDebug.enabled === true, dir: debugDir }
+
+  const LEVELS = ["debug", "info", "warn", "error"] as const
+  const logLevel = LEVELS.includes(rec.logLevel as (typeof LEVELS)[number]) ? (rec.logLevel as OptionsOpts["logLevel"]) : "warn"
+  if (rec.logLevel !== undefined && !LEVELS.includes(rec.logLevel as (typeof LEVELS)[number])) warns.push("logLevel invalid, using warn")
+
+  return {
+    ok: true,
+    warns,
+    config: { enabled, checker: { command, sha256 }, budgets, onCheckerError, actions, actionsAll, cache, rejectBudget, asConfig, debug, logLevel },
+  }
+}

package/src/index.ts

@@ -0,0 +1,153 @@
+// opencode-shell-warden-hook — OpenCode V2 plugin entry (two-tier, ADR-0016).
+// Mechanism per ADR-0013: the native substrate is the fail-closed boundary
+// (permissions: shell → ask). The shim listens for published permission
+// requests, spawns the one-shot shell-warden checker per request
+// (letter in on stdin → verdict out on stdout, 02-letter-verdict v2.0) and
+// replies programmatically:
+//   allow → "once", deny → "reject" (with reason), ask → silence (human decides).
+// Checker defects degrade to onCheckerError ∈ {ask, deny} — never allow.
+
+import { mkdirSync, appendFileSync } from "node:fs"
+import { Plugin } from "@opencode/plugin"
+import { replyDecision, buildLetter, cacheKey, invocationIdOf, type AskData } from "./apply.ts"
+import { VerdictCache } from "./cache.ts"
+import { validateOptions, type Opts } from "./config.ts"
+import { CheckerInvoker, RejectBudgets, verifyPin, type CheckerOptions, type CheckerOutcome } from "./checker.ts"
+import { MAX_LETTER_BYTES, MAX_COMMAND_BYTES } from "./types.ts"
+
+const PLUGIN_ID = "opencode-shell-warden-hook"
+
+export default Plugin.define({
+  id: PLUGIN_ID,
+  async setup(ctx) {
+    const opts = validateOptions(ctx.options)
+    if (!opts.ok) {
+      console.error(`[${PLUGIN_ID}] Disabled: ${opts.reason}`)
+      return
+    }
+    const cfg: Opts = opts.config
+    for (const w of opts.warns) console.error(`[${PLUGIN_ID}] warn: ${w}`)
+    if (cfg.enabled === false) return
+
+    const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const
+    type Level = keyof typeof LEVELS
+    const threshold = LEVELS[cfg.logLevel]
+    const log = (level: Level, msg: string): void => {
+      if (LEVELS[level] >= threshold) console.error(msg)
+    }
+
+    // Debug NDJSON per check (03 §3.5); default dir per 04 §4.2.
+    let debugSink: ((record: Record<string, unknown>) => void) | null = null
+    if (cfg.debug.enabled) {
+      const dir = cfg.debug.dir ?? `${process.env.HOME ?? ""}/.local/state/shell-warden/hook`
+      try { mkdirSync(dir, { recursive: true }) } catch { /* debug is best-effort */ }
+      const file = `${dir}/hook.ndjson`
+      debugSink = (record) => { try { appendFileSync(file, JSON.stringify(record) + "\n") } catch { /* debug is best-effort */ } }
+    }
+
+    const checkerOpts: CheckerOptions = {
+      command: cfg.checker.command,
+      sha256: cfg.checker.sha256,
+      checkTimeoutMs: cfg.budgets.checkTimeoutMs,
+      killGraceMs: cfg.budgets.killGraceMs,
+      maxConcurrentSpawns: cfg.budgets.maxConcurrentSpawns,
+      log,
+    }
+    verifyPin(checkerOpts)
+    const checker = new CheckerInvoker(checkerOpts)
+    const cache = new VerdictCache(cfg.cache.enabled ? cfg.cache.maxEntries : 0)
+    const rejectBudgets = new RejectBudgets(cfg.rejectBudget.maxRejections, cfg.rejectBudget.windowMs)
+
+    const myLocation = ctx.location?.directory ?? ""
+    const reply = (sessionID: string, requestID: string, decision: "once" | "reject", message?: string) =>
+      (ctx as any).permission.reply({
+        sessionID,
+        requestID,
+        decision,
+        ...(message !== undefined ? { message } : {}),
+      })
+
+    const controller = new AbortController()
+    void (async () => {
+      try {
+        for await (const ev of ctx.event.subscribe({ signal: controller.signal })) {
+          if ((ev as any).type !== "permission.asked") continue
+          const d = (ev as any).data as AskData | undefined
+          if (!d?.id || !d?.sessionID || !d?.action || !Array.isArray(d.resources) || d.resources.length === 0) continue
+          // Foreign projects: this shim judges only actions of its own location.
+          const loc = (ev as any).location?.directory ?? ""
+          if (myLocation && loc !== myLocation) continue
+          try {
+            if (!(cfg.actionsAll || cfg.actions.includes(d.action))) continue
+            const invocationId = invocationIdOf(d.source, d.sessionID, d.action)
+            const projectDir = myLocation || undefined
+            const key = cacheKey(d.action, d.resources, projectDir ?? "")
+
+            if (cfg.cache.enabled) {
+              const cached = cache.get(key)
+              if (cached !== null) {
+                await reply(d.sessionID, d.id, "once", cached.message)
+                continue
+              }
+            }
+
+            // Pre-spawn bounds (02 §2.2): breach ⇒ local degrade, no spawn.
+            const letter = buildLetter({ data: d, invocationId, projectDir })
+            const letterBytes = Buffer.byteLength(JSON.stringify(letter))
+            const oversize =
+              letter.commands.length > cfg.budgets.maxRequestCommands ||
+              letterBytes > MAX_LETTER_BYTES ||
+              letter.commands.some((c) => Buffer.byteLength(c.raw) > MAX_COMMAND_BYTES)
+            if (oversize) {
+              log("warn", `letter bounds breach for ${invocationId} — degrade (${cfg.onCheckerError})`)
+              if (cfg.onCheckerError === "deny") await reply(d.sessionID, d.id, "reject", undefined).catch(() => {})
+              continue
+            }
+
+            const outcome: CheckerOutcome = await checker.check(letter)
+            debugSink?.({ ts: new Date().toISOString(), invocationId, action: d.action, outcomeOk: outcome.ok })
+            if (!outcome.ok) {
+              log(cfg.logLevel === "debug" ? "debug" : "warn", `degrade (${outcome.reason}) for ${invocationId}`)
+              if (cfg.onCheckerError === "deny") {
+                await reply(d.sessionID, d.id, "reject", undefined).catch(() => { /* human resolves */ })
+              }
+              continue
+            }
+
+            const result = outcome.verdict
+            const decision = replyDecision(result.verdict)
+            if (decision === "once") {
+              if (cfg.cache.enabled && cfg.cache.ttlMs > 0) cache.put(key, cfg.cache.ttlMs, result.message)
+              await reply(d.sessionID, d.id, "once")
+              continue
+            }
+            if (decision === "reject") {
+              // Reject budget (ADR-0010, hook-owned): exhausted ⇒ stop answering —
+              // the native ask reaches the human. Never auto-allowed.
+              const ruleId = result.commands?.[0]?.ruleId ?? "unknown"
+              if (!rejectBudgets.trySpend(d.sessionID, ruleId)) {
+                log("info", `reject budget exhausted for ${ruleId} (${invocationId}) — left to the human`)
+                continue
+              }
+              await reply(d.sessionID, d.id, "reject", result.message)
+              continue
+            }
+            // verdict "ask" → stay silent: the native dialog goes to the human
+          } catch (e) {
+            log("warn", `ask handler error: ${String(e).slice(0, 200)} — request left to the human (fail-closed)`)
+          }
+        }
+      } catch (e) {
+        log("error", `event subscription error: ${String(e).slice(0, 200)}`)
+      }
+    })()
+
+    if (cfg.asConfig.observeShell) {
+      await ctx.shell.hook("create.before", (event) => {
+        debugSink?.({ ts: new Date().toISOString(), phase: "create.before", command: event.command, cwd: event.cwd })
+      })
+    }
+
+    return () => { controller.abort() }
+  },
+})

package/src/types.ts

@@ -0,0 +1,68 @@
+// Letter & verdict types — mirror of docs/spec/shell-warden/02-letter-verdict.md (v2.0)
+// and schemas/shell-warden.letter.v1.schema.json / shell-warden.verdict.v1.schema.json.
+// Keep in sync with the schemas.
+
+export type Verdict = "allow" | "ask" | "deny"
+
+export interface LetterInvocation {
+  id: string                       // `${messageID}:${callID}` — unique per tool call
+  sessionID: string
+  agent?: string
+  projectDir?: string
+}
+
+export interface LetterCommand {
+  index: number
+  raw: string                      // command text exactly as OpenCode produced it, ≤ 8 KiB
+  cwd: string
+}
+
+export interface Letter {
+  version: 1
+  invocation: LetterInvocation
+  action: string
+  commands: LetterCommand[]
+}
+
+export interface LetterCommandVerdict {
+  index: number
+  verdict: Verdict
+  ruleId?: string
+  classification?: "static" | "opaque"
+  match?: "argv" | "raw"
+  facts?: Record<string, unknown>
+}
+
+export interface LetterVerdict {
+  invocationId: string             // echo of letter.invocation.id
+  verdict: Verdict                 // aggregate — authoritative, hook applies tighten-only
+  message?: string                 // required on deny; ≤ 512 chars
+  commands?: LetterCommandVerdict[]
+}
+
+// Bounds from 02-letter-verdict.md §2.2/§2.3 (hook enforces before spawning)
+export const MAX_LETTER_BYTES = 64 * 1024
+export const MAX_COMMAND_BYTES = 8 * 1024
+export const MAX_VERDICT_BYTES = 64 * 1024
+export const MAX_FACTS_BYTES = 16 * 1024
+export const MAX_MESSAGE_CHARS = 512
+
+// OpenCode V2 permission.asked event payload (relevant subset)
+export interface AskData {
+  id: string                          // requestID, assigned at publication
+  sessionID: string
+  action: string
+  resources: readonly string[]
+  source?: { type: "tool"; messageID: string; id: string }
+}
+
+// shell.create.before hook event (audit-only usage)
+export interface ShellCreateBefore {
+  command: string
+  cwd: string
+  timeout: number
+  shell: string
+  env: Record<string, string | undefined>
+}
+
+export const VERDICT_RANK: Record<Verdict, number> = { allow: 0, ask: 1, deny: 2 }