feat(harness): implement Plan-20 transparent agentic client bridge

Wave 0 + Wave 1 core of the transparent agentic-client integration: a developer types prompts normally in Claude Code / Codex while every certified turn still carries a full H1->H7 trace and an H6 record. - agentic_bridge.py: stdlib-only lifecycle state machine (begin/pre-tool/ post-tool/telemetry/finalize/abort + report/doctor). Single-model invariant (never calls a model), fail-closed at the side-effect point, admission TTL + canonical-project/session binding, atomic state under .specify/state/agentic-sessions/, secret redaction, null-not-zero H6. - agentic-lifecycle.schema.json: client-agnostic JSON contract. - adapters/claude-code + adapters/codex: thin hook renderers + config templates that call the core bridge. - phase-agentic-bridge-tests.sh: C1-C12 acceptance + threat suite (30/30). - devkit templates/{claude,codex} + windows/install-agentic.ps1 (install/doctor/uninstall with manifest, path-safe). - docs/casan Windows + security/bypass guides; plan status -> IMPLEMENTED. - harden generate-agentops-dashboard.py aggregation against null H6 costs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-23 20:44:07 +07:00
parent 0cc43d94d3
commit 4bb184b935
18 changed files with 2647 additions and 6 deletions
@@ -0,0 +1,36 @@
+# CASAN Claude Code adoption template (Plan-20)
+
+Drop `settings.json` into the target repo as `.claude/settings.json` (the
+installer does this). It wires the four Claude Code lifecycle hooks
+(`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) to the CASAN agentic
+bridge so a developer can type prompts normally while every certified turn still
+carries an H1→H7 trace and an H6 record.
+
+- The hook command resolves the repo root via `$CLAUDE_PROJECT_DIR`, so **no
+  machine-specific path is committed**.
+- It invokes `packages/casan-harness/adapters/claude-code/claude_hook.py`, a thin
+  renderer that calls the core bridge. The bridge **never runs a model** — Claude
+  remains the sole model executor (single-model invariant).
+- This is a **`project_hook`** integration: strong for a trusted project, but a
+  member who can edit `.claude/settings.json` can disable it. For organization
+  enforcement use a managed/pinned deployment (`managed_hook`) — see
+  `docs/casan/CASAN_AGENTIC_CLIENT_SECURITY.md`.
+
+## Install (cross-platform)
+
+```bash
+packages/casan-devkit/install.sh --target <repo> --project <id>
+# then enable the agentic client hooks:
+cp packages/casan-devkit/templates/claude/settings.json <repo>/.claude/settings.json
+```
+
+Windows: use `packages/casan-devkit/windows/install-agentic.ps1 -Client claude`.
+
+## Feature flags (environment)
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CASAN_AGENTIC_BRIDGE_ENABLED` | `1` | Master on/off. |
+| `CASAN_AGENTIC_ENFORCEMENT_MODE` | `observe` | `observe` (telemetry-only, never certified) → `enforce` (gates + certification). |
+| `CASAN_AGENTIC_INTEGRATION_MODE` | `project_hook` | `project_hook` / `managed_hook` / `casan_owned`. |
+| `CASAN_AGENTIC_CLIENT_ALLOWLIST` | (unset) | Comma list; clients outside it are `observed_only`. |
@@ -0,0 +1,51 @@
+{
+  "//": "CASAN Plan-20 Claude Code project hooks. Commit this as .claude/settings.json in the target repo (the devkit installer does this). Commands self-resolve the repo root via $CLAUDE_PROJECT_DIR — no machine-specific path is baked in. Secrets and absolute paths must NOT be added here.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/packages/casan-harness/adapters/claude-code/claude_hook.py\" --event UserPromptSubmit",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/packages/casan-harness/adapters/claude-code/claude_hook.py\" --event PreToolUse",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/packages/casan-harness/adapters/claude-code/claude_hook.py\" --event PostToolUse",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/packages/casan-harness/adapters/claude-code/claude_hook.py\" --event Stop",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -0,0 +1,26 @@
+# CASAN Codex adoption template (Plan-20)
+
+Drop `hooks.json` → `.codex/hooks.json` and merge `config.toml` into
+`.codex/config.toml` in the target repo (the installer does this). It wires the
+Codex lifecycle hooks to the CASAN agentic bridge via the thin renderer
+`packages/casan-harness/adapters/codex/codex_hook.py`.
+
+Important Codex-specific facts (Spike-20 §4.2):
+
+- **Trust review is mandatory.** Codex loads project-local hooks only after the
+  user accepts a trust prompt. Run `casan doctor --client codex` (or the bridge
+  `doctor` op) to confirm the trust/onboarding state — it is never hidden from a
+  member.
+- **Tool hooks are a guardrail, not a complete boundary.** Hosted/specialized
+  tools may fall outside hook coverage; a turn that uses an uncovered tool is
+  **downgraded** (non-certified), not silently certified.
+- **Token/cost source is not assumed.** Unless Codex supplies a stable usage
+  source, H6 records the number as `null` with `telemetry_quality=partial` — it
+  is never invented (Spike-20 X6).
+- For enterprise enforcement, pin hooks via managed policy so a member cannot
+  disable them and set `CASAN_AGENTIC_INTEGRATION_MODE=managed_hook` through the
+  managed environment (not the committed config).
+
+The command contract is stable (stdin JSON → exit 0 allow / exit 2 block); the
+exact Codex payload key names are pinned during the Wave-3 payload spike, which
+is why `codex_hook.py` reads several field aliases defensively.
@@ -0,0 +1,18 @@
+# CASAN Plan-20 Codex config fragment (.codex/config.toml).
+# Merge these keys into the target repo's .codex/config.toml. This enables the
+# project hooks in hooks.template.json after Codex trust review.
+#
+# For ENTERPRISE enforcement, the managed policy path pins hooks so a member
+# cannot disable them (Spike-20 §4.2, Plan-20 Wave 3.3). In that deployment set
+# CASAN_AGENTIC_INTEGRATION_MODE=managed_hook via managed environment/MDM, not
+# in this committed file.
+
+[hooks]
+enabled = true
+# project-local hooks load only after the user accepts the trust prompt.
+project_hooks = true
+
+[casan]
+# Bridge feature flags — safe defaults (observe first, then enforce per Plan-20 §9).
+enforcement_mode = "observe"   # observe | enforce
+integration_mode = "project_hook"
@@ -0,0 +1,18 @@
+{
+  "//": "CASAN Plan-20 Codex project hooks. Commit as .codex/hooks.json in the target repo. Codex loads project-local hooks ONLY after a trust review — run `casan doctor --client codex` to confirm the trust/onboarding state (Spike-20 §4.2). The exact key names are pinned during the Wave-3 Codex payload spike; the command contract (stdin JSON -> exit 0 allow / exit 2 block) is stable. No secrets or absolute paths here.",
+  "version": 1,
+  "hooks": {
+    "UserPromptSubmit": [
+      { "command": ["python3", "packages/casan-harness/adapters/codex/codex_hook.py", "--event", "UserPromptSubmit"], "timeout_ms": 15000 }
+    ],
+    "PreToolUse": [
+      { "matcher": "*", "command": ["python3", "packages/casan-harness/adapters/codex/codex_hook.py", "--event", "PreToolUse"], "timeout_ms": 15000 }
+    ],
+    "PostToolUse": [
+      { "matcher": "*", "command": ["python3", "packages/casan-harness/adapters/codex/codex_hook.py", "--event", "PostToolUse"], "timeout_ms": 15000 }
+    ],
+    "Stop": [
+      { "command": ["python3", "packages/casan-harness/adapters/codex/codex_hook.py", "--event", "Stop"], "timeout_ms": 15000 }
+    ]
+  }
+}