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

package/README.md

@@ -1,3 +1,76 @@
-# 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.
+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.
+
+## Install
+
+```sh
+npm install opencode-shell-warden-hook   # or reference a local checkout
+```
+
+`opencode.jsonc`:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-shell-warden-hook",
+      "options": {
+        "engine": { "command": ["/usr/local/bin/shell-warden", "serve"] },
+        "onEngineError": "ask",
+        "actions": ["shell"]
+      }
+    }
+  ]
+}
+```
+
+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
+
+```sh
+npm install
+npm test        # node --test (35 contract/unit tests, mock engine included)
+npm run typecheck
+```
+
+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.

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.1.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,86 @@
+// 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).
+
+import { createHash } from "node:crypto"
+import type { CheckParams, CheckResult, Verdict } 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 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")
+}
+
+export function buildCheckRequest(args: {
+  data: AskData
+  invocationId: string
+  cwd: string
+  projectDir?: string
+}): CheckParams {
+  const { data, invocationId, cwd, projectDir } = args
+  return {
+    invocation: {
+      id: invocationId,
+      sessionID: data.sessionID ?? "",
+      hook: "permission.asked",
+      ...(projectDir !== undefined ? { projectDir } : {}),
+      startedAt: new Date().toISOString(),
+    },
+    action: data.action ?? "",
+    commands: (data.resources ?? []).map((raw, index) => ({ index, raw, cwd })),
+    context: {
+      ...(data.source !== undefined ? { source: data.source } : {}),
+    },
+  }
+}
+
+/** Maps a verdict to the reply decision: `"once"` | `"reject"` | `null` (silence). */
+export function replyDecision(v: 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/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/config.ts

@@ -0,0 +1,168 @@
+// Shim options validation — docs/policyd-plugin-design/04-shim-config.md
+// Semantics: unknown keys => warn + ignore; budgets out of clamp => warn + clamp;
+// fatal defects (engine.command, protocolVersion, onEngineError:"allow") => plugin disables itself.
+
+export interface ResolvedBudgets {
+  handshakeTimeoutMs: number
+  checkTimeoutMs: number
+  killGraceMs: number
+  maxFrameBytes: number
+  maxInFlight: number
+  maxRequestCommands: number
+  maxViolations: number
+  maxViolationsWindowMs: number
+}
+
+export interface ResolvedConfig {
+  engine: {
+    command: string[]
+    protocolVersion: number
+    sha256: string | null
+    cwd: string | null
+    restart: { maxBackoffMs: number; windowMs: number; resetAfterMs: number }
+  }
+  budgets: ResolvedBudgets
+  onEngineError: "ask" | "deny"
+  actions: string[]
+  actionsAll: boolean
+  cache: { enabled: boolean; maxEntries: number; defaultTtlMs: number }
+  observeShell: boolean
+  logLevel: "debug" | "info" | "warn" | "error"
+}
+
+export type ValidateResult =
+  | { ok: true; config: ResolvedConfig; warns: string[] }
+  | { ok: false; reason: string; warns: string[] }
+
+const KNOWN_ACTIONS = new Set([
+  "read", "edit", "glob", "grep", "shell", "subagent", "skill", "question",
+  "webfetch", "websearch", "external_directory", "execute",
+])
+
+const KNOWN_KEYS = new Set(["enabled", "engine", "budgets", "onEngineError", "actions", "cache", "observeShell", "logLevel"])
+
+const clampInt = (v: unknown, min: number, max: number, def: number, label: string, warns: string[]): number => {
+  if (typeof v !== "number" || !Number.isFinite(v)) return def
+  const n = Math.floor(v)
+  if (n < min || n > max) {
+    warns.push(`budgets.${label}: ${n} out of clamp [${min}, ${max}], using ${Math.min(Math.max(n, min), max)}`)
+    return Math.min(Math.max(n, min), max)
+  }
+  return n
+}
+
+/** Resolves `{env:NAME}` members; returns null when substitution fails. */
+export function resolveEnvMember(s: string): string | null {
+  const m = /^\{env:([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(s)
+  if (!m) return s
+  const v = process.env[m[1] as string]
+  return v === undefined || v === "" ? null : v
+}
+
+export function validateOptions(raw: unknown, warn: (m: string) => void = () => {}): ValidateResult {
+  const warns: string[] = []
+  if (raw === null || raw === undefined || typeof raw !== "object") {
+    // Empty options are valid: everything defaults except engine.command.
+    raw = {}
+  }
+  const o = raw as Record<string, unknown>
+  for (const key of Object.keys(o)) {
+    if (!KNOWN_KEYS.has(key)) warns.push(`unknown option "${key}" ignored`)
+  }
+  if (o.enabled === false) return { ok: false, reason: "disabled by options.enabled=false", warns }
+
+  // --- engine (fatal on defects) ---
+  const eng = (o.engine ?? {}) as Record<string, unknown>
+  const rawCommand = eng.command
+  if (!Array.isArray(rawCommand) || rawCommand.length === 0 || rawCommand.some((m) => typeof m !== "string")) {
+    return { ok: false, reason: 'engine.command must be a non-empty string array', warns }
+  }
+  const command: string[] = []
+  for (const member of rawCommand as string[]) {
+    const resolved = resolveEnvMember(member)
+    if (resolved === null) {
+      return { ok: false, reason: `engine.command member "${member}" failed {env:…} substitution`, warns }
+    }
+    command.push(resolved)
+  }
+  if (command[0] === "" || !command[0]!.startsWith("/")) {
+    return { ok: false, reason: `engine.command[0] must be an absolute path, got "${command[0]}"`, warns }
+  }
+  const protocolVersion = typeof eng.protocolVersion === "number" ? eng.protocolVersion : 1
+  if (!Number.isInteger(protocolVersion) || protocolVersion < 1) {
+    return { ok: false, reason: `engine.protocolVersion must be a positive integer, got ${String(eng.protocolVersion)}`, warns }
+  }
+  const sha256 = typeof eng.sha256 === "string" && /^[0-9a-f]{64}$/.test(eng.sha256) ? eng.sha256 : null
+  if (eng.sha256 !== undefined && eng.sha256 !== null && sha256 === null) {
+    return { ok: false, reason: "engine.sha256 must be null or 64 hex chars", warns }
+  }
+  const cwd = typeof eng.cwd === "string" && eng.cwd.startsWith("/") ? eng.cwd : null
+
+  // --- restart (clamp) ---
+  const rs = (eng.restart ?? {}) as Record<string, unknown>
+  const restart = {
+    maxBackoffMs: clampInt(rs.maxBackoffMs, 1_000, 300_000, 30_000, "restart.maxBackoffMs", warns),
+    windowMs: clampInt(rs.windowMs, 10_000, 3_600_000, 300_000, "restart.windowMs", warns),
+    resetAfterMs: clampInt(rs.resetAfterMs, 10_000, 3_600_000, 300_000, "restart.resetAfterMs", warns),
+  }
+
+  // --- budgets (clamp) ---
+  const b = (o.budgets ?? {}) as Record<string, unknown>
+  const budgets: ResolvedBudgets = {
+    handshakeTimeoutMs: clampInt(b.handshakeTimeoutMs, 100, 60_000, 5_000, "handshakeTimeoutMs", warns),
+    checkTimeoutMs: clampInt(b.checkTimeoutMs, 1, 30_000, 5_000, "checkTimeoutMs", warns),
+    killGraceMs: clampInt(b.killGraceMs, 50, 2_000, 250, "killGraceMs", warns),
+    maxFrameBytes: clampInt(b.maxFrameBytes, 4_096, 1_048_576, 65_536, "maxFrameBytes", warns),
+    maxInFlight: clampInt(b.maxInFlight, 1, 64, 8, "maxInFlight", warns),
+    maxRequestCommands: clampInt(b.maxRequestCommands, 1, 128, 32, "maxRequestCommands", warns),
+    maxViolations: clampInt(b.maxViolations, 1, 10, 3, "maxViolations", warns),
+    maxViolationsWindowMs: clampInt(b.maxViolationsWindowMs, 5_000, 3_600_000, 60_000, "maxViolationsWindowMs", warns),
+  }
+
+  // --- onEngineError (fatal on "allow") ---
+  const onEngineError = o.onEngineError
+  if (onEngineError === "allow") {
+    return { ok: false, reason: 'onEngineError must be "ask" or "deny" — "allow" is never valid (fail-closed)', warns }
+  }
+  const degrade = onEngineError === "deny" ? "deny" : "ask"
+
+  // --- actions ---
+  let actions: string[] = []
+  let actionsAll = false
+  const rawActions = o.actions
+  if (Array.isArray(rawActions) && rawActions.length > 0) {
+    for (const a of rawActions) {
+      if (a === "*") actionsAll = true
+      else if (typeof a === "string" && KNOWN_ACTIONS.has(a)) actions.push(a)
+      else warns.push(`actions: unknown action "${String(a)}" dropped`)
+    }
+  }
+  if (!actionsAll && actions.length === 0) actions = ["shell"]
+
+  // --- cache ---
+  const c = (o.cache ?? {}) as Record<string, unknown>
+  const cache = {
+    enabled: c.enabled !== false,
+    maxEntries: clampInt(c.maxEntries, 16, 100_000, 1_024, "cache.maxEntries", warns),
+    defaultTtlMs: clampInt(c.defaultTtlMs, 0, 3_600_000, 0, "cache.defaultTtlMs", warns),
+  }
+
+  const logLevel = o.logLevel === "debug" || o.logLevel === "info" || o.logLevel === "error" ? o.logLevel : "warn"
+
+  for (const w of warns) warn(`[opencode-shell-warden-hook] ${w}`)
+
+  return {
+    ok: true,
+    warns,
+    config: {
+      engine: { command, protocolVersion, sha256, cwd, restart },
+      budgets,
+      onEngineError: degrade,
+      actions: actionsAll ? ["*"] : actions,
+      actionsAll,
+      cache,
+      observeShell: o.observeShell === true,
+      logLevel,
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,143 @@
+// opencode-shell-warden-hook — OpenCode V2 plugin entry.
+// Mechanism per ADR-0013: the native substrate is the fail-closed boundary
+// (permissions: shell → ask). The shim listens for published permission
+// requests, consults the shell-warden engine, and replies programmatically:
+// allow → "once", deny → "reject" (with reason), ask → silence (human decides).
+// Fail-closed: with the hook absent every ask reaches the human / headless
+// auto-reject — nothing executes silently.
+
+import { Plugin } from "@opencode/plugin"
+import { replyDecision, buildCheckRequest, cacheKey, invocationIdOf, type AskData, InvocationRegistry } from "./apply.ts"
+import { VerdictCache } from "./cache.ts"
+import { validateOptions } from "./config.ts"
+import { EngineSupervisor, type SupervisorOptions } from "./supervisor.ts"
+
+const VERSION = "0.1.0"
+const PLUGIN_ID = "opencode-shell-warden-hook"
+
+export default Plugin.define({
+  id: PLUGIN_ID,
+  async setup(ctx) {
+    const opts = validateOptions(ctx.options, (m) => console.error(m))
+    if (!opts.ok) {
+      console.error(`[${PLUGIN_ID}] Disabled: ${opts.reason}`)
+      return
+    }
+    const cfg = opts.config
+    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)
+    }
+
+    const supOpts: SupervisorOptions = {
+      command: cfg.engine.command,
+      protocolVersion: cfg.engine.protocolVersion,
+      sha256: cfg.engine.sha256,
+      cwd: cfg.engine.cwd,
+      clientVersion: VERSION,
+      budgets: {
+        handshakeTimeoutMs: cfg.budgets.handshakeTimeoutMs,
+        checkTimeoutMs: cfg.budgets.checkTimeoutMs,
+        killGraceMs: cfg.budgets.killGraceMs,
+        maxFrameBytes: cfg.budgets.maxFrameBytes,
+        maxInFlight: cfg.budgets.maxInFlight,
+        maxViolations: cfg.budgets.maxViolations,
+        maxViolationsWindowMs: cfg.budgets.maxViolationsWindowMs,
+        maxBackoffMs: cfg.engine.restart.maxBackoffMs,
+        windowMs: cfg.engine.restart.windowMs,
+        resetAfterMs: cfg.engine.restart.resetAfterMs,
+      },
+      log,
+    }
+    const supervisor = new EngineSupervisor(supOpts)
+    const cache = new VerdictCache(cfg.cache.enabled ? cfg.cache.maxEntries : 0)
+    const registry = new InvocationRegistry()
+
+    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 cwd = ""  // v0.1: no OpenCode HTTP calls from the ask handler (deadlock finding). M1: session-event cache
+            const key = cacheKey(d.action, d.resources, cwd)
+
+            if (cfg.cache.enabled) {
+              const cached = cache.get(key)
+              if (cached !== null) {
+                await reply(d.sessionID, d.id, "once", cached.message)
+                continue
+              }
+            }
+
+            if (!cfg.actionsAll && d.resources.length > cfg.budgets.maxRequestCommands) {
+              await reply(d.sessionID, d.id, "reject", "too many commands for one guard evaluation")
+              continue
+            }
+
+            const outcome = await supervisor.check(buildCheckRequest({ data: d, invocationId, cwd }))
+            if (!outcome.ok) {
+              log(cfg.logLevel === "debug" ? "debug" : "warn", `degrade (${outcome.reason}) for ${invocationId}`)
+              // fail-closed: onError → either reject (hard-fail mode) or silence
+              if (cfg.onEngineError === "deny") {
+                await reply(d.sessionID, d.id, "reject", undefined).catch(() => { /* human resolves */ })
+              }
+              continue
+            }
+            const { verdict, message } = outcome.result
+            if (verdict === "allow") {
+              const ttl = outcome.result.commands?.find((c) => c.index === 0)?.cacheTtlMs ?? cfg.cache.defaultTtlMs
+              if (cfg.cache.enabled && ttl > 0) {
+                cache.put(key, ttl, message)
+                registry.remember(invocationId, key)
+              }
+              await reply(d.sessionID, d.id, "once")
+              continue
+            }
+            if (verdict === "deny") {
+              await reply(d.sessionID, d.id, "reject", message)
+              continue
+            }
+            // verdict "ask" → stay silent: the dialog goes to the human (escalation by silence)
+          } 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.observeShell) {
+      await ctx.shell.hook("create.before", (event) => {
+        supervisor.observe({ phase: "create.before", command: event.command, cwd: event.cwd })
+      })
+    }
+    await ctx.tool.hook("execute.after", (event) => {
+      const source = (event as { source?: { messageID?: string; id?: string } }).source
+      if (source?.messageID === undefined || source.id === undefined) return
+      const key = registry.keyFor(`${source.messageID}:${source.id}`)
+      if (key !== undefined) registry.remember(`${source.messageID}:${source.id}`, key)
+    })
+
+    return () => { controller.abort(); supervisor.dispose() }
+  },
+})

package/src/protocol.ts

@@ -0,0 +1,87 @@
+// NDJSON JSON-RPC framing — docs/policyd-plugin-design/02-protocol.md §2.1–2.2
+// One UTF-8 JSON value per \n-terminated line; lines over the byte cap are a
+// protocol violation; unparseable lines are a protocol violation.
+
+import type { WireMessage } from "./types.ts"
+
+export class FrameError extends Error {
+  readonly kind: "frame-limit" | "parse"
+  constructor(kind: "frame-limit" | "parse") {
+    super(`protocol violation: ${kind}`)
+    this.kind = kind
+  }
+}
+
+export function encodeMessage(msg: WireMessage, maxFrameBytes: number): string {
+  const line = JSON.stringify(msg)
+  if (Buffer.byteLength(line, "utf8") + 1 > maxFrameBytes) {
+    throw new FrameError("frame-limit")
+  }
+  return line + "\n"
+}
+
+/**
+ * Incremental line parser for a byte stream. After `fatal` is set the parser
+ * stops consuming input; the caller must treat the connection as violated.
+ */
+export class FrameParser {
+  private buf = ""
+  private queue: WireMessage[] = []
+  fatal: string | null = null
+
+  private readonly maxFrameBytes: number
+  constructor(maxFrameBytes: number) {
+    this.maxFrameBytes = maxFrameBytes
+  }
+
+  push(chunk: Buffer | string): void {
+    if (this.fatal !== null) return
+    this.buf += typeof chunk === "string" ? chunk : chunk.toString("utf8")
+    for (;;) {
+      const nl = this.buf.indexOf("\n")
+      if (nl === -1) {
+        if (Buffer.byteLength(this.buf, "utf8") > this.maxFrameBytes) this.fatal = "frame-limit"
+        return
+      }
+      const line = this.buf.slice(0, nl)
+      this.buf = this.buf.slice(nl + 1)
+      if (Buffer.byteLength(line, "utf8") > this.maxFrameBytes) {
+        this.fatal = "frame-limit"
+        return
+      }
+      if (line.trim().length === 0) {
+        this.fatal = "parse" // blank lines are not valid NDJSON
+        return
+      }
+      let msg: unknown
+      try {
+        msg = JSON.parse(line)
+      } catch {
+        this.fatal = "parse"
+        return
+      }
+      if (msg === null || typeof msg !== "object") {
+        this.fatal = "parse"
+        return
+      }
+      this.queue.push(msg as WireMessage)
+    }
+  }
+
+  drain(): WireMessage[] {
+    const q = this.queue
+    this.queue = []
+    return q
+  }
+}
+
+/** Monotonic JSON-RPC id source; reset per engine connection. */
+export class IdPool {
+  private next = 1
+  take(): number {
+    return this.next++
+  }
+  reset(): void {
+    this.next = 1
+  }
+}

package/src/supervisor.ts

@@ -0,0 +1,412 @@
+// Engine supervisor — docs/policyd-plugin-design/03-shim.md §3.3, 02-protocol.md §2.7
+// Lazy spawn (empty env, absolute argv), exact-version handshake, per-check
+// deadlines, violation/restart ladder, unhealthy cooldown, fail-closed dispose.
+
+import { spawn } from "node:child_process"
+import type { ChildProcess } from "node:child_process"
+import { createHash } from "node:crypto"
+import { createReadStream } from "node:fs"
+import { FrameParser, IdPool, encodeMessage } from "./protocol.ts"
+import type { CheckParams, CheckResult, WireMessage } from "./types.ts"
+import type { CheckOutcome } from "./apply.ts"
+
+export interface SupervisorOptions {
+  command: string[]
+  protocolVersion: number
+  sha256: string | null
+  cwd: string | null
+  clientVersion: string
+  budgets: {
+    handshakeTimeoutMs: number
+    checkTimeoutMs: number
+    killGraceMs: number
+    maxFrameBytes: number
+    maxInFlight: number
+    maxViolations: number
+    maxViolationsWindowMs: number
+    maxBackoffMs: number
+    windowMs: number
+    resetAfterMs: number
+  }
+  log?: (level: "debug" | "info" | "warn" | "error", msg: string) => void
+}
+
+type Waiter = {
+  resolve: (o: CheckOutcome) => void
+  timer: ReturnType<typeof setTimeout>
+  id: number | null
+  params: CheckParams
+}
+
+const MAX_QUEUED = 64
+const FATAL_COOLDOWN_MS = 15 * 60_000
+const KILL_KINDS = new Set(["frame-limit", "parse", "version-mismatch", "handshake-timeout", "timeout", "exit", "spawn"])
+
+export class EngineSupervisor {
+  private state: "cold" | "spawning" | "handshaking" | "ready" | "restarting" | "unhealthy" | "disposed" = "cold"
+  private child: ChildProcess | null = null
+  private parser: FrameParser
+  private ids = new IdPool()
+  private pending = new Map<number, Waiter>()
+  private queue: Waiter[] = []
+  private handshakeId: number | null = null
+  private handshakeTimer: ReturnType<typeof setTimeout> | null = null
+  private violations = { count: 0, windowStart: 0 }
+  private restartsAt: number[] = []
+  private backoffLevel = 0
+  private unhealthyUntil = 0
+  private lastReadyAt = 0
+  private spawnTimer: ReturnType<typeof setTimeout> | null = null
+  private graceTimer: ReturnType<typeof setTimeout> | null = null
+  private stderrRing: string[] = []
+  private stderrBytes = 0
+  private disposed = false
+
+  private readonly opts: SupervisorOptions
+  private readonly now: () => number
+
+  constructor(opts: SupervisorOptions, now: () => number = Date.now) {
+    this.opts = opts
+    this.now = now
+    this.parser = new FrameParser(opts.budgets.maxFrameBytes)
+  }
+
+  get currentState(): string {
+    return this.state
+  }
+
+  lastStderr(): string {
+    return this.stderrRing.join("")
+  }
+
+  async check(params: CheckParams): Promise<CheckOutcome> {
+    if (this.disposed || this.state === "disposed") return { ok: false, reason: "disposed" }
+    if (this.now() < this.unhealthyUntil) return { ok: false, reason: "unhealthy" }
+    void this.ensureEngine()
+    return new Promise<CheckOutcome>((resolve) => {
+      if (this.state === "ready" && this.child !== null && this.pending.size < this.opts.budgets.maxInFlight) {
+        this.sendCheck(resolve, params)
+        return
+      }
+      if (this.queue.length >= MAX_QUEUED) {
+        resolve({ ok: false, reason: "backpressure" })
+        return
+      }
+      const waiter: Waiter = {
+        resolve,
+        id: null,
+        params,
+        timer: setTimeout(() => this.failWaiter(waiter, "timeout"), this.opts.budgets.checkTimeoutMs),
+      }
+      this.queue.push(waiter)
+    })
+  }
+
+  /** Fire-and-forget audit notification (policy/observe); dropped unless ready. */
+  observe(notification: Record<string, unknown>): void {
+    if (this.state !== "ready" || this.child === null) return
+    try {
+      this.child.stdin?.write(encodeMessage({ jsonrpc: "2.0", method: "policy/observe", params: notification }, this.opts.budgets.maxFrameBytes))
+    } catch {
+      /* audit must never throw */
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.state = "disposed"
+    this.clearTimers()
+    this.rejectPending("disposed")
+    this.rejectQueued("disposed")
+    if (this.child !== null) {
+      try {
+        this.child.kill("SIGKILL")
+      } catch {
+        /* already gone */
+      }
+      this.child = null
+    }
+  }
+
+  // ---------- internal ----------
+
+  private ensureEngine(): void {
+    if (this.disposed || this.state !== "cold") return
+    if (this.now() < this.unhealthyUntil) {
+      this.rejectQueued("unhealthy")
+      return
+    }
+    if (this.lastReadyAt !== 0 && this.now() - this.lastReadyAt >= this.opts.budgets.resetAfterMs) {
+      this.restartsAt = []
+      this.backoffLevel = 0
+    }
+    this.state = "spawning"
+    void this.spawnNow()
+  }
+
+  private async spawnNow(): Promise<void> {
+    if (this.disposed || this.state !== "spawning") return
+    if (this.opts.sha256 !== null) {
+      const ok = await this.verifySha256(this.opts.sha256)
+      if (!ok) {
+        this.markFatal("engine binary sha256 mismatch")
+        return
+      }
+    }
+    const [cmd, ...args] = this.opts.command
+    const child = spawn(cmd as string, args, {
+      env: {},
+      cwd: this.opts.cwd ?? undefined,
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+    this.child = child
+    this.parser = new FrameParser(this.opts.budgets.maxFrameBytes)
+    this.ids.reset()
+    this.handshakeId = null
+    this.state = "handshaking"
+    child.on("error", (err: Error & { code?: string }) => {
+      this.protocolViolation(`spawn:${err.code ?? "error"}`)
+    })
+    child.stdout?.setEncoding("utf8")
+    child.stdout?.on("data", (chunk: string) => {
+      this.parser.push(chunk)
+      if (this.parser.fatal !== null) {
+        this.protocolViolation(`frame:${this.parser.fatal}`)
+        return
+      }
+      for (const msg of this.parser.drain()) this.route(msg)
+    })
+    child.stderr?.setEncoding("utf8")
+    child.stderr?.on("data", (chunk: string) => {
+      this.stderrRing.push(chunk)
+      this.stderrBytes += chunk.length
+      while (this.stderrBytes > 8 * 1024 && this.stderrRing.length > 0) {
+        const head = this.stderrRing.shift() as string
+        this.stderrBytes -= head.length
+      }
+    })
+    child.on("exit", (code, signal) => this.onExit(code, signal))
+    this.sendHandshake()
+  }
+
+  private sendHandshake(): void {
+    const id = this.ids.take()
+    this.handshakeId = id
+    this.handshakeTimer = setTimeout(() => {
+      this.handshakeId = null
+      this.protocolViolation("handshake-timeout")
+    }, this.opts.budgets.handshakeTimeoutMs)
+    this.write({
+      jsonrpc: "2.0",
+      id,
+      method: "initialize",
+      params: { protocolVersion: this.opts.protocolVersion, client: { name: "opencode-shell-warden-hook", version: this.opts.clientVersion } },
+    })
+  }
+
+  private completeHandshake(result: unknown): void {
+    if (this.handshakeTimer !== null) clearTimeout(this.handshakeTimer)
+    this.handshakeTimer = null
+    this.handshakeId = null
+    if (this.state !== "handshaking") return
+    const r = result as { protocolVersion?: number } | null
+    if (r === null || typeof r !== "object" || r.protocolVersion !== this.opts.protocolVersion) {
+      this.protocolViolation("version-mismatch")
+      return
+    }
+    this.state = "ready"
+    this.log("info", `engine ready: ${JSON.stringify((result as InitializeLike).engine ?? {})}`)
+    this.flushQueue()
+  }
+
+  private flushQueue(): void {
+    while (this.state === "ready" && this.queue.length > 0 && this.pending.size < this.opts.budgets.maxInFlight) {
+      const waiter = this.queue.shift()
+      if (waiter === undefined) break
+      this.sendCheck(waiter.resolve, waiter.params, waiter)
+    }
+  }
+
+  private sendCheck(resolve: (o: CheckOutcome) => void, params: CheckParams, existing?: Waiter): void {
+    let waiter: Waiter
+    if (existing !== undefined) {
+      waiter = existing
+    } else {
+      const w: Waiter = { resolve, params, id: null, timer: null! }
+      w.timer = setTimeout(() => this.failWaiter(w, "timeout"), this.opts.budgets.checkTimeoutMs)
+      waiter = w
+    }
+    const id = this.ids.take()
+    waiter.id = id
+    this.pending.set(id, waiter)
+    this.write({ jsonrpc: "2.0", id, method: "policy/check", params })
+  }
+
+  private route(msg: WireMessage): void {
+    if ("method" in msg && !("id" in msg)) {
+      if (msg.method === "audit/event") this.log("info", `audit: ${JSON.stringify(msg.params ?? {})}`)
+      return // unknown notifications ignored (forward compatibility)
+    }
+    if ("error" in msg) {
+      if (msg.id === null) return
+      const waiter = this.pending.get(msg.id)
+      if (waiter !== undefined) {
+        this.pending.delete(msg.id)
+        clearTimeout(waiter.timer)
+        waiter.resolve({ ok: false, reason: "engine-error" })
+      }
+      if (msg.error.data?.fatal === true) this.markFatal(`engine fatal: ${msg.error.message}`)
+      return
+    }
+    if (!("result" in msg)) return
+    const id = msg.id
+    if (id === this.handshakeId) {
+      this.completeHandshake(msg.result)
+      return
+    }
+    const waiter = this.pending.get(id)
+    if (waiter === undefined) return // unknown/late id — ignore
+    this.pending.delete(id)
+    clearTimeout(waiter.timer)
+    const result = msg.result as CheckResult | null
+    if (result === null || typeof result !== "object" || typeof (result as CheckResult).verdict !== "string") {
+      this.protocolViolation("bad-result-shape")
+      waiter.resolve({ ok: false, reason: "malformed-response" })
+      return
+    }
+    waiter.resolve({ ok: true, result })
+  }
+
+  private failWaiter(waiter: Waiter, reason: string): void {
+    if (waiter.id !== null) this.pending.delete(waiter.id)
+    else this.queue = this.queue.filter((w) => w !== waiter)
+    waiter.resolve({ ok: false, reason })
+    if (reason === "timeout") this.protocolViolation("timeout")
+  }
+
+  private onExit(_code: number | null, _signal: string | null): void {
+    if (this.graceTimer !== null) clearTimeout(this.graceTimer)
+    this.graceTimer = null
+    if (this.disposed || this.state === "restarting" || this.state === "unhealthy" || this.state === "disposed") return
+    this.rejectPending("engine-exited")
+    this.protocolViolation("exit")
+  }
+
+  private protocolViolation(kind: string): void {
+    if (this.disposed) return
+    this.log("warn", `violation: ${kind}`)
+    const now = this.now()
+    if (now - this.violations.windowStart > this.opts.budgets.maxViolationsWindowMs) {
+      this.violations = { count: 1, windowStart: now }
+    } else {
+      this.violations.count += 1
+    }
+    if (this.violations.count >= this.opts.budgets.maxViolations) {
+      this.violations = { count: 0, windowStart: 0 }
+      this.killAndRestart(`violations:${kind}`)
+      return
+    }
+    if (KILL_KINDS.has(kind) || kind.startsWith("spawn:")) this.killAndRestart(kind)
+  }
+
+  private killAndRestart(reason: string): void {
+    if (this.disposed) return
+    const now = this.now()
+    this.restartsAt.push(now)
+    this.restartsAt = this.restartsAt.filter((t) => now - t <= this.opts.budgets.windowMs)
+    this.state = "restarting"
+    this.rejectPending("engine-restarting")
+    this.killChild()
+    if (this.restartsAt.length > this.opts.budgets.maxViolations) {
+      this.unhealthyUntil = now + this.opts.budgets.windowMs
+      this.state = "unhealthy"
+      this.rejectQueued("unhealthy")
+      this.log("error", `engine unhealthy until ${new Date(this.unhealthyUntil).toISOString()} (${reason})`)
+      return
+    }
+    const delay = Math.min(250 * 2 ** this.backoffLevel, this.opts.budgets.maxBackoffMs)
+    this.backoffLevel += 1
+    this.log("warn", `restart #${this.restartsAt.length} in ${delay}ms (${reason})`)
+    this.spawnTimer = setTimeout(() => {
+      this.spawnTimer = null
+      this.state = "cold"
+      void this.ensureEngine()
+    }, delay)
+  }
+
+  private killChild(): void {
+    const child = this.child
+    this.child = null
+    if (child === null) return
+    try {
+      child.kill("SIGTERM")
+    } catch {
+      /* already gone */
+    }
+    this.graceTimer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL")
+      } catch {
+        /* already gone */
+      }
+    }, this.opts.budgets.killGraceMs)
+  }
+
+  private markFatal(reason: string): void {
+    this.unhealthyUntil = this.now() + FATAL_COOLDOWN_MS
+    this.state = "unhealthy"
+    this.rejectPending("unhealthy")
+    this.rejectQueued("unhealthy")
+    this.killChild()
+    this.log("error", `fatal: ${reason}`)
+  }
+
+  private rejectPending(reason: string): void {
+    for (const [, waiter] of this.pending) {
+      clearTimeout(waiter.timer)
+      waiter.resolve({ ok: false, reason })
+    }
+    this.pending.clear()
+  }
+
+  private rejectQueued(reason: string): void {
+    for (const waiter of this.queue) {
+      clearTimeout(waiter.timer)
+      waiter.resolve({ ok: false, reason })
+    }
+    this.queue = []
+  }
+
+  private clearTimers(): void {
+    if (this.handshakeTimer !== null) clearTimeout(this.handshakeTimer)
+    if (this.spawnTimer !== null) clearTimeout(this.spawnTimer)
+    if (this.graceTimer !== null) clearTimeout(this.graceTimer)
+  }
+
+  private write(msg: WireMessage): void {
+    if (this.child === null) return
+    try {
+      this.child.stdin?.write(encodeMessage(msg, this.opts.budgets.maxFrameBytes))
+    } catch {
+      this.protocolViolation("frame-limit")
+    }
+  }
+
+  private log(level: "debug" | "info" | "warn" | "error", msg: string): void {
+    this.opts.log?.(level, `[opencode-shell-warden-hook] ${msg}`)
+  }
+
+  private async verifySha256(expected: string): Promise<boolean> {
+    const path = this.opts.command[0] as string
+    return new Promise((resolve) => {
+      const hash = createHash("sha256")
+      const stream = createReadStream(path)
+      stream.on("data", (chunk) => hash.update(chunk))
+      stream.on("end", () => resolve(hash.digest("hex") === expected))
+      stream.on("error", () => resolve(false))
+    })
+  }
+}
+
+type InitializeLike = { engine?: { name?: string; version?: string } }

package/src/types.ts

@@ -0,0 +1,86 @@
+// Wire protocol types — mirror of docs/policyd-plugin-design/02-protocol.md (v1)
+// and schemas/wire.v1.schema.json. Keep in sync with the schema.
+
+export type Verdict = "allow" | "ask" | "deny"
+
+export interface InitializeParams {
+  protocolVersion: number
+  client: { name: string; version: string; opencode?: string }
+}
+
+export interface InitializeResult {
+  protocolVersion: number
+  engine: { name: string; version: string }
+  capabilities?: Record<string, unknown>
+  config?: { source?: string; stages?: string[]; loadedAt?: string }
+}
+
+export interface CheckCommand {
+  index: number
+  raw: string
+  cwd: string
+}
+
+export interface CheckParams {
+  invocation: {
+    id: string
+    sessionID: string
+    agent?: string
+    hook: string
+    projectDir?: string
+    startedAt?: string
+  }
+  action: string
+  commands: CheckCommand[]
+  context?: {
+    source?: { type: "tool"; messageID?: string; id?: string }
+    metadata?: Record<string, unknown>
+  }
+}
+
+export interface CheckCommandResult {
+  index: number
+  verdict: Verdict
+  stage?: string | null
+  ruleId?: string | null
+  reason?: string
+  classification?: "static" | "opaque"
+  cacheTtlMs?: number
+}
+
+export interface CheckResult {
+  invocationId: string
+  verdict: Verdict
+  message?: string
+  commands?: CheckCommandResult[]
+  engine?: { checkMs?: number }
+}
+
+export type WireMessage =
+  | { jsonrpc: "2.0"; id: number; method: string; params: unknown }
+  | { jsonrpc: "2.0"; id: number; result: unknown }
+  | { jsonrpc: "2.0"; id: number | null; error: { code: number; message: string; data?: { fatal?: boolean } } }
+  | { jsonrpc: "2.0"; method: string; params?: unknown }
+
+// OpenCode V2 permission evaluate hook event (mutable: effect, message)
+export interface PermissionEvaluation {
+  readonly sessionID: string
+  readonly agent?: string
+  readonly action: string
+  readonly resources: readonly string[]
+  readonly metadata?: Record<string, unknown>
+  readonly source?: { type: "tool"; messageID: string; id: string }
+  effect: Verdict
+  message?: 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 }