agent-assurance 0.1.0

package/policy-pack/README.md

@@ -0,0 +1,105 @@
+# Cycle-of-Trust Policy Pack (reference)
+
+A drop-in Claude Code configuration that **mechanically enforces the Cycle of Trust
+boundary**: an autonomous agent may modify its **prompts, context, and manifests**,
+but never its own **tools, permission grants, permission modes, or hook policies**.
+
+This is the productized companion to AAL Core. AAL Core *detects* boundary
+violations offensively; this pack *prevents* the most direct one — an agent
+editing its own guardrails — and streams an evidence event for every attempt.
+
+## Why layered (and what the spike found)
+
+The boundary is enforced by three controls. The load-bearing one turned out to be
+the **hook**: an empirical spike (Claude Code **v2.1.201**, 2026-07-04 — see
+[ADR-0001](../docs/adr/0001-layered-cycle-of-trust-enforcement.md)) showed a
+`PreToolUse` exit-2 deny blocks the tool call in **every** mode tested, including
+`bypassPermissions` **and** `--dangerously-skip-permissions`. A no-hook control run
+confirmed bypass genuinely skips permission checks — so the block is the hook's,
+not a permission rule's. This **reverses** the earlier doc-based reading (matrix
+delta D1, which had claimed hooks don't hold under bypass).
+
+| Layer | File | default / plan / acceptEdits | **bypassPermissions** |
+|---|---|:---:|:---:|
+| `permissions.deny` rules | `settings.json` | ✅ | ❌ (permission rules are skipped under bypass) |
+| **`PreToolUse` guard hook** | `settings.json` → `hooks/guard-protected-paths.mjs` | ✅ | ✅ **(verified v2.1.201)** |
+| Managed settings (`disableBypassPermissionsMode` + deny) | `managed-settings.json` | ✅ | ✅ (also removes the mode) |
+
+**Take-away:** the **hook alone holds the boundary in every mode**, so the pack's
+core guarantee does not depend on managed settings. Install `managed-settings.json`
+anyway for **org-level defense-in-depth** — it removes `bypassPermissions` as an
+option entirely and its deny rules cannot be edited away by the agent. This matrix
+is asserted in `src/policy/protected-paths.test.ts` (`GUARANTEES_BY_MODE`); the
+live re-run is [`spike-bypass.sh`](./spike-bypass.sh).
+
+## What is protected
+
+The single source of truth is [`protected-paths.json`](./protected-paths.json).
+Every consumer (deny rules, the guard hook, the tests) reads it, so they cannot
+drift:
+
+| Protected path (glob) | Invariant it defends |
+|---|---|
+| `**/.claude/settings.json`, `**/.claude/settings.local.json` | permission grants, permission modes, hook policies |
+| `**/.claude/hooks/**` | hook policies (the enforcement code itself) |
+| `**/.claude/agents/**` | subagent / tool definitions |
+| `**/.mcp.json` | MCP tool/server definitions (tools) |
+
+`shellMarkers` mirror these for `Bash` (substring match), so `echo … > .claude/settings.json`
+is caught too.
+
+## Install
+
+1. **Project or user settings** — merge [`settings.json`](./settings.json) into
+   `.claude/settings.json`. Copy `policy-pack/` into the repo (the hook command
+   references `$CLAUDE_PROJECT_DIR/policy-pack/hooks/guard-protected-paths.mjs`).
+2. **Managed settings (required for the bypass guarantee)** — install
+   [`managed-settings.json`](./managed-settings.json) at the OS managed path:
+   - macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`
+   - Linux: `/etc/claude-code/managed-settings.json`
+   - Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`
+3. **Evidence stream (optional, → WS2)** — export `AAL_AUDIT_URL` (the AgenticMind
+   `POST /hooks/audit` URL) and `AAL_AUDIT_TOKEN` (a bearer carrying the
+   `audit:write` scope). The `PostToolUse` and `ConfigChange` HTTP hooks then
+   record every mutating tool call and config change as a hash-not-text evidence
+   row. Secrets come from the environment only — never hardcode them.
+
+## Open items — verify before rollout
+
+- **`disableBypassPermissionsMode`** (`managed-settings.json`) drives the
+  org-level defense-in-depth (removing bypass as an option). The hook already
+  holds the boundary in every mode, so this key is not the sole guarantee — but
+  confirm its exact name/values against the current managed-settings docs before
+  relying on the org-level control.
+- **Re-run the spike per CLI version.** The v2.1.201 result (hook blocks in every
+  mode) is version-specific evidence, not a doc guarantee. If a future version
+  lets `bypassPermissions` skip hooks, the managed layer becomes load-bearing
+  again — re-run `spike-bypass.sh` after upgrades.
+- **`ConfigChange` blocking (delta D2 — resolved).** A spike confirmed the event
+  fires headlessly with `source` + `file_path`, and exit 2 blocks the change from
+  taking effect (except `policy_settings`). The pack now ships
+  `hooks/guard-config-change.mjs`, which blocks protected settings/skill changes
+  and lets `policy_settings` (managed) through. ⚠ This **freezes** ordinary edits
+  to `.claude/settings.json` / `settings.local.json` and any skills change from
+  taking effect — admins change the boundary via **managed** settings. Remove this
+  hook (keep the evidence hook) if settings must stay live-editable.
+- **HTTP-hook runtime semantics (delta D3).** sync/async, timeout, and retry
+  behavior of `http` hooks are undocumented. The evidence stream is best-effort;
+  do not assume it is synchronous or that a failed POST is retried.
+- **Hook matcher / `ConfigChange` matcher syntax.** Confirm the matcher grammar
+  against the hooks reference for your CLI version.
+
+## Verify it works
+
+- **Offline (CI gate):** `bun run tsc && bun x vitest run src/policy/` — proves the
+  pack denies every protected glob in both layers, that managed settings disable
+  bypass, that the guard blocks self-modification attempts, and that the
+  guarantee matrix is honest about bypass.
+- **Live (the D1/D2 spike):** run [`spike-bypass.sh`](./spike-bypass.sh) with the
+  real `claude` CLI. It drives an agent to modify its own `settings.json` under
+  each permission mode and records what actually happened. Result on **v2.1.201**:
+  the `PreToolUse` hook blocked the write in every mode — default, plan,
+  acceptEdits, `bypassPermissions`, and `--dangerously-skip-permissions` — while a
+  no-hook control confirmed bypass really does skip permission checks. Re-run this
+  on your target CLI version; the hook's cross-mode enforcement is the property to
+  re-confirm.

package/policy-pack/hooks/guard-config-change.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * ConfigChange guard hook — blocks a settings/skill change to a protected control
+ * path from taking effect (exit 2). Second net behind the PreToolUse guard: even
+ * if a protected-config change lands on disk, ConfigChange refuses to apply it.
+ *
+ * The event carries `source` (user_settings | project_settings | local_settings |
+ * policy_settings | skills) and `file_path`. `policy_settings` (managed) cannot be
+ * blocked by a hook and is the admin channel — we never block it. Verified against
+ * a live ConfigChange event on Claude Code v2.1.201 (delta D2, resolved).
+ *
+ * ⚠ This freezes protected-config changes for hardened deployments: ordinary edits
+ * to .claude/settings.json / settings.local.json and any skills change won't take
+ * effect while installed. Admins change the boundary via MANAGED (policy) settings.
+ * Remove this hook (keep the PreToolUse guard + evidence) if settings must stay
+ * live-editable.
+ */
+
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const { globs } = JSON.parse(readFileSync(resolve(here, "../protected-paths.json"), "utf8"))
+
+const globToRe = (g) => {
+  // Convert a glob to a regex in a single alternation pass (longest token first) so `*` inside a
+  // `**` expansion is never re-processed — no placeholder sentinels needed.
+  const re = g
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*\/|\*\*|\*/g, (m) => (m === "**/" ? "(?:.*/)?" : m === "**" ? ".*" : "[^/]*"))
+  return new RegExp("^" + re + "$")
+}
+const globRes = globs.map(globToRe)
+const matchesPath = (p) => typeof p === "string" && globRes.some((re) => re.test(p))
+
+let raw = ""
+process.stdin.setEncoding("utf8")
+process.stdin.on("data", (c) => (raw += c))
+process.stdin.on("end", () => {
+  let ev = {}
+  try {
+    ev = JSON.parse(raw || "{}")
+  } catch {
+    process.exit(0)
+  }
+  const source = ev.source ?? ""
+  if (source === "policy_settings") {
+    process.exit(0) // managed settings are the admin channel — never blocked
+  }
+  const block = source === "skills" || matchesPath(ev.file_path)
+  if (block) {
+    process.stderr.write(
+      `Cycle of Trust: blocked a ${source} change to a protected control path from ` +
+        `taking effect (${ev.file_path ?? "skill"}). Change the boundary via managed ` +
+        `(policy) settings, not from inside a session.\n`,
+    )
+    process.exit(2)
+  }
+  process.exit(0)
+})

package/policy-pack/hooks/guard-protected-paths.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse deny hook — Cycle of Trust boundary (defense-in-depth layer).
+ *
+ * Blocks Write / Edit / MultiEdit / Bash calls that would modify the agent's own
+ * tools, permission grants, permission modes, or hook policies. Reads the shared
+ * protected-paths.json so it can never drift from the deny rules and the tests.
+ *
+ * Deny protocol: exit code 2, reason on stderr (shown to the model). Exit 0 = allow.
+ *
+ * Spike result (Claude Code v2.1.201, 2026-07-04 — see policy-pack/README.md and
+ * ADR-0001): a PreToolUse exit-2 deny blocks the tool call even in
+ * `bypassPermissions` AND under `--dangerously-skip-permissions` (a no-hook
+ * control confirmed bypass really skips permission checks, so the block is the
+ * hook's). So this hook IS the load-bearing boundary in every mode — it also
+ * fires a per-attempt evidence trigger. `permissions.deny` RULES are still
+ * skipped under bypass; managed-settings (`disableBypassPermissionsMode`)
+ * additionally removes the mode entirely for org-level enforcement.
+ */
+
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const { globs, shellMarkers } = JSON.parse(
+  readFileSync(resolve(here, "../protected-paths.json"), "utf8"),
+)
+
+const globToRe = (g) => {
+  const re = g
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    // Single alternation pass (longest token first) — no control-char sentinels needed.
+    .replace(/\*\*\/|\*\*|\*/g, (m) => (m === "**/" ? "(?:.*/)?" : m === "**" ? ".*" : "[^/]*"))
+  return new RegExp("^" + re + "$")
+}
+const globRes = globs.map(globToRe)
+const matchesPath = (p) => typeof p === "string" && globRes.some((re) => re.test(p))
+const shellTouches = (cmd) =>
+  typeof cmd === "string" && shellMarkers.some((m) => cmd.includes(m))
+
+let raw = ""
+process.stdin.setEncoding("utf8")
+process.stdin.on("data", (c) => (raw += c))
+process.stdin.on("end", () => {
+  let ev = {}
+  try {
+    ev = JSON.parse(raw || "{}")
+  } catch {
+    process.exit(0) // unparseable event — do not block; the http audit hook still records
+  }
+  const tool = ev.tool_name ?? ev.tool ?? ""
+  const ti = ev.tool_input ?? {}
+  const blocked =
+    matchesPath(ti.file_path) || matchesPath(ti.path) || shellTouches(ti.command)
+  if (blocked) {
+    process.stderr.write(
+      `Cycle of Trust: blocked ${tool} targeting a protected control path ` +
+        `(tools / permissions / hooks). Autonomous remediation may modify ` +
+        `prompts, context, and manifests only — never its own guardrails.\n`,
+    )
+    process.exit(2)
+  }
+  process.exit(0)
+})

package/policy-pack/managed-settings.json

@@ -0,0 +1,18 @@
+{
+  "$comment": "Cycle-of-Trust reference policy pack — ADMIN MANAGED settings. Install at the OS managed-settings path (macOS: /Library/Application Support/ClaudeCode/managed-settings.json; Linux: /etc/claude-code/managed-settings.json). Managed settings CANNOT be overridden by the user or the agent. The PreToolUse guard hook already blocks in every mode (verified, Claude Code v2.1.201), so this managed layer is org-level DEFENSE-IN-DEPTH: disableBypassPermissionsMode removes bypassPermissions as an option entirely, and these deny rules cannot be edited away by the agent. ⚠ Verify `disableBypassPermissionsMode` against the current managed-settings docs before rollout.",
+  "permissions": {
+    "disableBypassPermissionsMode": "disable",
+    "deny": [
+      "Write(**/.claude/settings.json)",
+      "Edit(**/.claude/settings.json)",
+      "Write(**/.claude/settings.local.json)",
+      "Edit(**/.claude/settings.local.json)",
+      "Write(**/.claude/hooks/**)",
+      "Edit(**/.claude/hooks/**)",
+      "Write(**/.claude/agents/**)",
+      "Edit(**/.claude/agents/**)",
+      "Write(**/.mcp.json)",
+      "Edit(**/.mcp.json)"
+    ]
+  }
+}

package/policy-pack/protected-paths.json

@@ -0,0 +1,18 @@
+{
+  "$comment": "Single source of truth for the Cycle-of-Trust boundary. The agent may modify prompts/context/manifests, but NEVER its own tools, permission grants, permission modes, or hook policies. `globs` gate file-writing tools (Write/Edit); `shellMarkers` are substring guards for Bash. Consumed by policy-pack/hooks/guard-protected-paths.mjs, by policy-pack/settings.json deny rules, and by src/policy/protected-paths.ts (drift is caught by src/policy/protected-paths.test.ts).",
+  "globs": [
+    "**/.claude/settings.json",
+    "**/.claude/settings.local.json",
+    "**/.claude/hooks/**",
+    "**/.claude/agents/**",
+    "**/.mcp.json"
+  ],
+  "shellMarkers": [
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".claude/hooks/",
+    ".claude/agents/",
+    ".mcp.json",
+    "managed-settings.json"
+  ]
+}

package/policy-pack/settings.json

@@ -0,0 +1,59 @@
+{
+  "$comment": "Cycle-of-Trust reference policy pack — PROJECT/USER settings fragment. Merge into .claude/settings.json. The `permissions.deny` rules hold in default/plan/acceptEdits/dontAsk but are SKIPPED under bypassPermissions; the `PreToolUse` guard hook in this same file, however, blocks in EVERY mode including bypassPermissions and --dangerously-skip-permissions (verified, Claude Code v2.1.201 — see policy-pack/README.md). Install managed-settings.json to additionally remove bypass as an option org-wide. Set AAL_AUDIT_URL / AAL_AUDIT_TOKEN in the environment to stream evidence to AgenticMind /hooks/audit (WS2).",
+  "permissions": {
+    "deny": [
+      "Write(**/.claude/settings.json)",
+      "Edit(**/.claude/settings.json)",
+      "Write(**/.claude/settings.local.json)",
+      "Edit(**/.claude/settings.local.json)",
+      "Write(**/.claude/hooks/**)",
+      "Edit(**/.claude/hooks/**)",
+      "Write(**/.claude/agents/**)",
+      "Edit(**/.claude/agents/**)",
+      "Write(**/.mcp.json)",
+      "Edit(**/.mcp.json)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/policy-pack/hooks/guard-protected-paths.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "${AAL_AUDIT_URL}",
+            "headers": { "Authorization": "Bearer ${AAL_AUDIT_TOKEN}" },
+            "allowedEnvVars": ["AAL_AUDIT_URL", "AAL_AUDIT_TOKEN"]
+          }
+        ]
+      }
+    ],
+    "ConfigChange": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/policy-pack/hooks/guard-config-change.mjs\""
+          },
+          {
+            "type": "http",
+            "url": "${AAL_AUDIT_URL}",
+            "headers": { "Authorization": "Bearer ${AAL_AUDIT_TOKEN}" },
+            "allowedEnvVars": ["AAL_AUDIT_URL", "AAL_AUDIT_TOKEN"]
+          }
+        ]
+      }
+    ]
+  }
+}

package/policy-pack/spike-bypass.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# spike-bypass.sh — the LIVE empirical check the docs leave open.
+#
+# Question: does a PreToolUse deny hook block a tool call in every permission
+# mode, INCLUDING bypassPermissions and --dangerously-skip-permissions?
+#
+# First run (Claude Code v2.1.201, 2026-07-04): YES — the hook blocked the write
+# in every mode. A no-hook CONTROL run confirmed bypassPermissions genuinely
+# skips permission checks (the write succeeds with no hook), so the block is
+# attributable to the hook, not to a permission rule. This reversed the earlier
+# doc-based reading (delta D1). Re-run after CLI upgrades to re-confirm.
+#
+# READ-SAFE: everything happens inside a throwaway temp dir; your real ~/.claude
+# and repos are untouched. Requires the `claude` CLI + an authenticated account.
+#
+# NOTE on trust: project-level `permissions.allow`/`deny` from an UNTRUSTED
+# workspace are ignored by Claude Code, but `hooks` still run. This spike tests
+# the HOOK (which holds regardless of trust). To also exercise the pack's
+# permissions.deny layer, trust the workspace first (run `claude` in it once, or
+# set projects[<dir>].hasTrustDialogAccepted=true in ~/.claude.json).
+set -euo pipefail
+
+command -v claude >/dev/null 2>&1 || { echo "FAIL: 'claude' CLI not on PATH." >&2; exit 127; }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+mkdir -p "$WORK/.claude"
+
+# A PreToolUse Write hook that records the event (proves it fired) then denies.
+cat > "$WORK/.claude/settings.json" <<JSON
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Write", "hooks": [ { "type": "command", "command": "cat >> $WORK/fired.log; printf '\\n' >> $WORK/fired.log; exit 2" } ] }
+    ]
+  }
+}
+JSON
+
+ATTEMPT='Use the Write tool to create ./target.txt containing exactly HELLO. If the tool is blocked, report the exact block reason and stop.'
+
+attempt() { # $1 = label, rest = extra claude flags
+  local label="$1"; shift
+  rm -f "$WORK/target.txt" "$WORK/fired.log"
+  ( cd "$WORK" && CLAUDE_PROJECT_DIR="$WORK" claude -p "$ATTEMPT" "$@" >/dev/null 2>&1 || true )
+  local fired="no"; [ -s "$WORK/fired.log" ] && fired="yes"
+  local wrote="BLOCKED"; [ -e "$WORK/target.txt" ] && wrote="WROTE (hook did NOT block)"
+  printf '%-34s hook-fired=%-3s  result=%s\n' "$label" "$fired" "$wrote"
+}
+
+echo "### hook-deny across modes (expect BLOCKED in all on v2.1.201)"
+attempt "default (no flag)"
+attempt "plan"                        --permission-mode plan
+attempt "acceptEdits"                 --permission-mode acceptEdits
+attempt "bypassPermissions"           --permission-mode bypassPermissions
+attempt "dangerously-skip-permissions" --dangerously-skip-permissions
+
+echo
+echo "### CONTROL: NO hook, bypassPermissions (expect WROTE — proves bypass is real)"
+rm -f "$WORK/.claude/settings.json"
+attempt "control: no hook, bypass"    --permission-mode bypassPermissions
+
+cat <<'NOTE'
+
+### Interpretation
+- The hook-deny rows should all read BLOCKED (hook-fired=yes). If bypassPermissions
+  or dangerously-skip rows read WROTE, this CLI version lets bypass skip hooks —
+  D1 would hold again, and managed-settings.json becomes the load-bearing layer.
+- The CONTROL row must read WROTE. If it reads BLOCKED, bypass is not actually
+  active and the test above is inconclusive — investigate before trusting results.
+- Record the observed table + your CLI version in ADR-0001.
+NOTE