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,131 @@
+# CASAN Agentic Clients trên Windows (Plan-20)
+
+Tài liệu hướng dẫn cài đặt tích hợp **transparent agentic client** của CASAN cho
+Windows: developer gõ prompt bình thường trong Claude Code hoặc Codex, nhưng mọi
+turn được chứng nhận vẫn có trace H1→H7 và record H6 đầy đủ.
+
+Liên quan:
+[Plan-20](../plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) ·
+[Spike-20](../spikes/CASAN_SPIKE_20_AGENTIC_CLIENT_HOOKS.md) ·
+[Bảo mật/bypass](CASAN_AGENTIC_CLIENT_SECURITY.md).
+
+## 1. Nguyên tắc quan trọng
+
+- **Không chạy model hai lần.** Bridge chỉ làm admission/policy/evidence/finalize.
+  Claude/Codex vẫn là bộ chạy model duy nhất (single-model invariant).
+- **Fail-closed tại điểm side-effect.** Một tool có tác động bị từ chối khi không
+  có admission hợp lệ, còn hạn và gắn đúng project/session.
+- **Certification strength hiển thị công khai.** Mỗi trace mang
+  `project_hook` / `managed_hook` / `casan_owned` / `observed_only`; observe mode
+  luôn là `observed_only` và không bao giờ được cấp certified.
+
+## 2. Yêu cầu nền
+
+- Windows PowerShell 5.1 trở lên (hoặc PowerShell 7+/`pwsh`).
+- Python 3 trên PATH (`python3`, `python`, hoặc `py`). Bridge chỉ dùng stdlib —
+  không cài thư viện mới.
+- Repo dự án đã adopt CASAN core (`packages/casan-harness` tồn tại). Nếu chưa,
+  xem [CASAN_ADOPTION_WINDOWS.md](CASAN_ADOPTION_WINDOWS.md).
+
+Kiểm tra nhanh:
+
+```powershell
+python3 --version
+Test-Path .\packages\casan-harness\scripts\python\agentic_bridge.py
+```
+
+## 3. Cài đặt từ clone sạch (không copy file thủ công)
+
+Installer PowerShell tự đặt config vào đúng chỗ và ghi manifest để gỡ sạch.
+
+```powershell
+# Cài cho cả Claude Code lẫn Codex, bắt đầu ở chế độ observe (an toàn)
+pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Client all -Mode observe
+
+# Chỉ Claude Code
+pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Client claude
+
+# Bật enforce khi đã sẵn sàng cấp certified
+pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Client all -Mode enforce
+```
+
+Installer sẽ:
+
+1. Copy `settings.json` → `.claude\settings.json` và/hoặc `hooks.json`/`config.toml`
+   → `.codex\`. File cũ của bạn được backup thành `*.casan-bak`.
+2. Ghi feature flags vào `.casan\agentic.env`.
+3. Ghi `.casan\agentic-install-manifest.json` để uninstall không đụng config
+   riêng của bạn.
+4. Chạy doctor tự động.
+
+> Đường dẫn có dấu cách được xử lý đúng (ví dụ `C:\Users\Nguyen Van A\project`).
+
+## 4. Doctor và smoke test
+
+```powershell
+pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Action doctor -Client all
+```
+
+Doctor kiểm tra: interpreter Python, sự hiện diện của hook config, các gate
+H4/H2, quyền ghi state, và chạy một turn begin→admission thật trên state tạm.
+
+Có thể gọi bridge trực tiếp:
+
+```powershell
+python3 .\packages\casan-harness\scripts\python\agentic_bridge.py doctor
+```
+
+## 5. Dùng thử
+
+1. Mở repo trong Claude Code (hoặc Codex).
+2. Với Codex: chấp nhận **trust prompt** để project hook được load (bước bắt
+   buộc, doctor sẽ nhắc).
+3. Gõ prompt bình thường. Một prompt vi phạm policy (ví dụ chứa role-hijack) bị
+   chặn trước model theo khả năng của client.
+4. Khi turn kết thúc, xem H6:
+
+```powershell
+# Lọc report H6 theo client / integration_mode / trace_id / project
+python3 .\packages\casan-harness\scripts\python\agentic_bridge.py report --client claude-code
+```
+
+## 6. Feature flags
+
+Đặt trong `.casan\agentic.env` hoặc biến môi trường session:
+
+| Biến | Mặc định | Ý nghĩa |
+|---|---|---|
+| `CASAN_AGENTIC_BRIDGE_ENABLED` | `1` | Bật/tắt tổng. |
+| `CASAN_AGENTIC_ENFORCEMENT_MODE` | `observe` | `observe` (chỉ telemetry, không certified) → `enforce`. |
+| `CASAN_AGENTIC_INTEGRATION_MODE` | `project_hook` | `project_hook` / `managed_hook` / `casan_owned`. |
+| `CASAN_AGENTIC_CLIENT_ALLOWLIST` | (trống) | Danh sách client; ngoài danh sách → `observed_only`. |
+| `CASAN_AGENTIC_TTL_SECONDS` | `1800` | TTL admission. |
+| `CASAN_AGENTIC_INTERNAL_TIMEOUT` | `8` | Internal timeout của bridge (ngắn hơn outer hook timeout). |
+| `CASAN_AGENTIC_H2_REGISTRY` | `0` | Bật thêm H2 tool-registry gate (cho managed deployment có agent identity). |
+
+Nạp flags trong PowerShell:
+
+```powershell
+Get-Content .\.casan\agentic.env | Where-Object { $_ -and -not $_.StartsWith('#') } | ForEach-Object {
+  $k,$v = $_ -split '=',2; Set-Item -Path Env:$k -Value $v
+}
+```
+
+## 7. Gỡ cài đặt (không xóa config của user)
+
+```powershell
+pwsh .\packages\casan-devkit\windows\install-agentic.ps1 -Action uninstall -Client all
+```
+
+Uninstall chỉ xóa file do CASAN tạo (theo manifest) và khôi phục bản backup
+`*.casan-bak` nếu có.
+
+## 8. Xử lý sự cố
+
+| Triệu chứng | Nguyên nhân | Cách xử lý |
+|---|---|---|
+| Prompt không bị chặn dù có hook | Outer hook timeout của client (fail-open đã ghi nhận) | Side-effect vẫn bị `PreToolUse` từ chối khi thiếu admission; giảm tải hook, xem log H6 failure |
+| Codex không chạy hook | Chưa qua trust review | Mở repo trong Codex, chấp nhận trust; chạy lại doctor |
+| Turn hiện `observed_only` | Đang ở observe mode hoặc client ngoài allowlist | Đặt `-Mode enforce`, thêm client vào allowlist |
+| Token/cost là `null` | Client chưa cấp nguồn usage đáng tin | Đúng theo thiết kế — không bịa số; `telemetry_quality=partial` |
+| `bridge doctor` báo gate missing | Repo chưa adopt core đầy đủ | Chạy lại DevKit install core |
@@ -0,0 +1,98 @@
+# CASAN Agentic Client — Mô hình bảo mật & giới hạn bypass (Plan-20)
+
+Tài liệu này nêu rõ **CASAN đảm bảo gì và không đảm bảo gì** khi developer gõ
+prompt trực tiếp trong một agentic client (Claude Code, Codex, VS Code). Mục tiêu
+là không dùng từ “bắt buộc tuyệt đối” sai mức: một số tuyến chỉ là guardrail theo
+project, có thể bị người có quyền sửa cấu hình bypass.
+
+Liên quan:
+[Plan-20 §3](../plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) ·
+[Spike-20 §9](../spikes/CASAN_SPIKE_20_AGENTIC_CLIENT_HOOKS.md).
+
+## 1. Certification strength — bốn mức, không gộp
+
+| Strength | Ý nghĩa | Cam kết | Bypass |
+|---|---|---|---|
+| `casan_owned` | Launcher/SDK/Chat Participant do CASAN điều khiển toàn vòng đời | Mạnh nhất trong local client | Rất khó với người dùng thường |
+| `managed_hook` | Hook/policy được tổ chức pin, user không tắt được | Guardrail tổ chức | Cần quyền quản trị môi trường |
+| `project_hook` | Hook commit trong repo, user trust project | Guardrail theo project | **Có thể bypass** bởi người sửa/tắt config |
+| `observed_only` | Chỉ telemetry, không đủ admission/tool gate | Không certified | N/A |
+
+UI và export H6 **không** được gộp bốn mức trên thành một nhãn `pass`. Turn ở
+`observed_only` không bao giờ hiển thị `certified`.
+
+## 2. Điều kiện tối thiểu để một turn được certified
+
+1. Có `admission_id` hợp lệ, còn hạn (TTL), gắn đúng project root canonical và
+   session/turn.
+2. Mọi side-effect tool trong coverage đã công bố đều qua `pre-tool`.
+3. Enforcement mode = `enforce` và certification strength ∈
+   {`project_hook`, `managed_hook`, `casan_owned`}.
+4. Không có tín hiệu bypass coverage (ví dụ tool cross-project, tool ngoài
+   coverage).
+5. `finalize` chạy đúng một lần và các control kết thúc không đánh flag.
+
+Nếu bất kỳ điều kiện nào thiếu → turn là **non-certified**. Bridge fail-closed:
+khi không quyết định được trong internal timeout → block/deny.
+
+## 3. Những gì CASAN KHÔNG hứa
+
+- **Không** chặn được mọi prompt trong mọi AI extension bên thứ ba.
+- **Không** coi `project_hook` là security boundary tuyệt đối khi user có quyền
+  sửa/tắt `.claude/settings.json` hoặc `.codex/hooks.json`.
+- **Không** gọi model lần hai từ hook để “chạy lại qua CASAN”.
+- **Không** suy diễn token/cost khi client không cấp nguồn tin cậy — số thiếu là
+  `null` kèm warning, không phải `0`.
+- Codex tool hooks là guardrail, **không** phủ 100% hosted/specialized tools; turn
+  dùng tool ngoài coverage bị hạ cấp, không certified.
+
+## 4. Threat model đã kiểm thử
+
+Suite `tests/phase-agentic-bridge-tests.sh` (Spike-20 C1–C12 + threat) kiểm:
+
+| Mối đe dọa | Phòng thủ | Test |
+|---|---|---|
+| Side-effect không admission | Deny fail-closed | C4 |
+| Replay admission hết hạn | TTL check → deny | C5 |
+| Dùng lại admission khác project | Project binding → deny + bypass_signal | C5, THREAT bypass |
+| Prompt injection | H4 admission scan → block trước model | C2 |
+| Tamper `admission_id` (path traversal) | Chỉ chấp nhận uuid hex, chặn `..` | THREAT tamper |
+| Bridge/hook timeout | Internal timeout ngắn hơn outer → block/deny; ghi H6 failure | C6 |
+| Outer hook timeout (fail-open của client) | Side-effect vẫn bị `pre-tool` deny nếu thiếu admission | C7/C4 |
+| Stop loop | finalize idempotent, `stop_hook_active` guard | C8/C9 |
+| Secret/tool output lọt log | Redact + chỉ lưu hash, không lưu raw prompt/output | C11 |
+| Cost hiding (bịa số 0) | Missing → null + `telemetry_quality` | C10 |
+| Certified giả ở observe mode | Observe luôn `observed_only`, không certified | THREAT observe |
+
+## 5. Contract dữ liệu & privacy
+
+- State ở `.specify/state/agentic-sessions/`, ghi atomic + lock per-turn.
+- **Không** dùng raw prompt làm key; dùng salted hash + `turn_id` opaque.
+- Admission có TTL, project root canonical, và session binding.
+- **Không** ghi secret/credential hoặc toàn bộ tool output vào audit; evidence chỉ
+  giữ bản redact + hash.
+- Mỗi record mang `schema_version`, `trace_id`, `project_id`, `client`,
+  `client_version`, `integration_mode`, `certification_strength`, `occurred_at`.
+
+## 6. Khi cần enforcement mạnh
+
+Absolute enforcement cần `casan_owned` hoặc `managed_hook`:
+
+- **managed_hook:** pin hook/policy qua managed environment/MDM/requirements; user
+  không tắt được. Đặt `CASAN_AGENTIC_INTEGRATION_MODE=managed_hook` qua môi trường
+  quản trị, **không** commit trong repo.
+- **casan_owned:** dùng launcher/SDK/Chat Participant do CASAN sở hữu toàn bộ vòng
+  đời (ví dụ `@casan` VS Code Chat Participant — tuyến CASAN-owned, không phải
+  global interceptor cho mọi prompt Copilot).
+
+Plan-20 **không** quảng bá `project_hook` như một sandbox tuyệt đối.
+
+## 7. Rollout & rollback
+
+- Feature flags: `CASAN_AGENTIC_BRIDGE_ENABLED`,
+  `CASAN_AGENTIC_ENFORCEMENT_MODE`, `CASAN_AGENTIC_CLIENT_ALLOWLIST`.
+- Bắt đầu `observe`, sau đó `enforce` trong pilot; production default chỉ đổi sau
+  exit gate.
+- Trace sinh trong observe mode luôn `observed_only`, **không** retroactively
+  certified.
+- Rollback chỉ tắt adapter; `bin/casan-chat` và core H1→H7 hiện tại vẫn hoạt động.
@@ -1,10 +1,12 @@
 # CASAN Plan-20 — Transparent Agentic Client Integration

 > Ngày lập: 2026-07-22  
-> Trạng thái: **PLAN — thực hiện sau khi Spike-20 đạt exit gate**  
+> Cập nhật: 2026-07-23  
+> Trạng thái: **IMPLEMENTED (Wave 0 + Wave 1 core) — bridge, adapters, tests, devkit, docs đã ship và xanh; Codex/VS Code black-box trên client thật còn CONDITIONAL**  
 > Thứ tự bắt buộc: **Claude Code → Codex → Claude/Codex trên VS Code**

 Kết quả khảo sát và test matrix: [CASAN Spike-20](../spikes/CASAN_SPIKE_20_AGENTIC_CLIENT_HOOKS.md).
+Trạng thái triển khai chi tiết: [§11 Implementation status](#11-implementation-status).

 ## 1. Mục tiêu

@@ -293,3 +295,47 @@ docs/spikes/

 Tên/file cụ thể có thể điều chỉnh sau Spike-20, nhưng lifecycle contract, single-model
 invariant và certification strength là quyết định kiến trúc bắt buộc.
+
+## 11. Implementation status
+
+Cập nhật 2026-07-23. Ba quyết định kiến trúc bắt buộc đều được hiện thực và có test bao phủ:
+**lifecycle contract**, **single-model invariant** (bridge không gọi model — có test grep
+nguồn), **certification strength** (bốn mức, không gộp).
+
+### Deliverable đã ship
+
+| Deliverable | File | Trạng thái |
+|---|---|---|
+| Lifecycle JSON contract (20.0.1) | `packages/casan-harness/schemas/agentic-lifecycle.schema.json` | ✅ |
+| Bridge state machine (20.0.2/0.3/0.4) | `packages/casan-harness/scripts/python/agentic_bridge.py` (stdlib-only, Py3.9+) | ✅ |
+| Claude Code adapter (20.1.1–20.1.3) | `packages/casan-harness/adapters/claude-code/` (`claude_hook.py`, `settings.template.json`) | ✅ |
+| Codex adapter (20.3.1/0.2) | `packages/casan-harness/adapters/codex/` (`codex_hook.py`, `hooks.template.json`, `config.template.toml`) | ✅ mapping defensive, chờ pin trên client thật |
+| Threat + acceptance suite (20.0.5/1.6) | `packages/casan-harness/tests/phase-agentic-bridge-tests.sh` | ✅ **30/30 PASS** (C1–C12 + threat) |
+| DevKit templates + Windows installer (Wave 5) | `packages/casan-devkit/templates/{claude,codex}/`, `packages/casan-devkit/windows/install-agentic.ps1` | ✅ (install/doctor/uninstall + manifest) |
+| Docs Windows + Security/bypass | `docs/casan/CASAN_AGENTIC_CLIENTS_WINDOWS.md`, `docs/casan/CASAN_AGENTIC_CLIENT_SECURITY.md` | ✅ |
+| H6 provenance + report filter (20.0.4) | superset record trong bridge + `agentic_bridge.py report --client/--integration-mode/--trace-id/--project-id` | ✅ null-not-zero, filter được |
+
+### Ánh xạ exit gate (mục 8)
+
+- ✅ 100% test lifecycle fixtures pass (30/30).
+- ✅ 100% side-effect test bị deny khi thiếu admission (C4, cross-project, expired, traversal).
+- ✅ Không có double model execution (invariant test trên nguồn bridge).
+- ✅ Timeout/hook failure tạo non-certified + H6 failure (C6, abort).
+- ⏳ Windows smoke: installer PowerShell viết theo path-safe + doctor; **cần chạy trên máy
+  Windows thật** (host phát triển không có `pwsh`). macOS/Linux smoke: ✅ qua suite.
+- ✅ H6 JSON thể hiện `project_hook`/`observed_only` + telemetry quality.
+
+### Còn CONDITIONAL (đúng theo phạm vi Spike-20, chưa đóng)
+
+- **Codex payload keys**: adapter đọc nhiều alias phòng thủ; cần pin trên Codex thật (Wave 3.1).
+- **VS Code / extension**: chưa black-box trên client thật; `@casan` Chat Participant (Wave 4)
+  chưa hiện thực — vẫn giữ badge `unsupported` cho tới khi có evidence độc lập.
+- **Windows exit-gate smoke**: cần chạy `install-agentic.ps1` trên clean Windows clone.
+
+### Quyết định thiết kế cần lưu
+
+- H2 tool-registry gate là **opt-in** (`CASAN_AGENTIC_H2_REGISTRY=1`) cho managed deployment
+  có agent identity; gate side-effect luôn-bật của luồng transparent là **admission gate**
+  (side-effect thiếu admission hợp lệ → deny). Xem `CASAN_AGENTIC_CLIENT_SECURITY.md`.
+- Certified có thể đi kèm `telemetry_quality=insufficient`: certification dựa trên
+  admission/evidence/coverage; chất lượng telemetry được báo cáo riêng, không bịa số.