plan: update plan20

docs/plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md

@@ -0,0 +1,295 @@
+# 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**  
+> 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).
+
+## 1. Mục tiêu
+
+Cho phép developer gõ prompt bình thường trong agentic coding client mà không phải chạy
+`bin/casan-chat`, nhưng mọi kết quả được CASAN chứng nhận vẫn phải có trace H1→H7 đầy đủ.
+
+Trải nghiệm đích:
+
+1. Member mở project trong Claude Code, Codex hoặc client VS Code được hỗ trợ.
+2. Member gõ prompt như bình thường.
+3. CASAN mở một admission/trace cho turn đó trước khi agent được phép tạo side effect.
+4. Mọi tool call có tác động được CASAN kiểm tra và ghi evidence.
+5. Khi turn kết thúc, CASAN finalize H3–H7 và H6 hiển thị runtime/token/cost/failure cùng
+   nguồn và chất lượng của số liệu.
+6. Turn không có admission hợp lệ hoặc không finalize được **không được gắn nhãn certified**.
+
+## 2. Phạm vi và giới hạn cam kết
+
+### Trong phạm vi
+
+- Claude Code CLI/native UI, triển khai đầu tiên bằng lifecycle hooks.
+- Codex CLI/IDE host, triển khai sau khi Claude Code đạt gate.
+- Claude Code và Codex extension trên VS Code, nếu thực nghiệm xác nhận extension dùng cùng
+  project hooks với CLI.
+- Một CASAN Chat Participant riêng cho VS Code/Copilot nếu cần tuyến chat do CASAN sở hữu.
+- Cài đặt và tài liệu cho Windows PowerShell, macOS/Linux.
+- Mapping turn/session/client vào trace H1→H7 và H6 report.
+
+### Ngoài phạm vi Plan-20
+
+- Chặn prompt trong mọi AI extension bất kỳ của bên thứ ba.
+- Khẳng định project hook là security boundary tuyệt đối khi user có thể sửa/tắt cấu hình.
+- Gọi model lần thứ hai từ hook để “chạy lại qua CASAN”.
+- Thay đổi core semantics H1→H7 hoặc cài thêm thư viện runtime.
+
+## 3. Nguyên tắc kiến trúc
+
+### 3.1 Không chạy model hai lần
+
+`chat-turn.py ask` hiện là đường CASAN sở hữu cả model execution. Native adapter **không**
+được gọi lệnh này rồi để Claude/Codex tiếp tục xử lý cùng prompt, vì sẽ tạo hai lượt model,
+hai chi phí và hai kết quả cạnh tranh.
+
+Plan-20 thêm một lifecycle bridge chỉ làm admission, policy, evidence và finalize:
+
+```mermaid
+sequenceDiagram
+    actor U as Developer
+    participant C as Claude/Codex/VS Code
+    participant B as CASAN Agentic Bridge
+    participant H as H1-H7 Harness
+    participant M as Native Model
+
+    U->>C: Prompt bình thường
+    C->>B: begin(prompt, client, session)
+    B->>H: H1 context + H4 security admission
+    H-->>B: admission_id + trace_id hoặc block
+    B-->>C: allow/context hoặc block
+    C->>M: Native model execution (một lần)
+    loop Mỗi tool call
+        C->>B: pre-tool(admission_id, tool, input)
+        B->>H: H2/H4/H5 policy gate
+        H-->>C: allow/deny
+        C->>B: post-tool(result, duration)
+        B->>H: append evidence
+    end
+    C->>B: finalize(last message, outcome)
+    B->>H: H3/H5/H7 + H6 telemetry
+    H-->>C: certified / non-certified
+```
+
+### 3.2 Certification strength phải hiển thị công khai
+
+Mỗi trace native có `integration_mode` và `certification_strength`:
+
+| Strength | Ý nghĩa | Cam kết |
+|---|---|---|
+| `casan_owned` | Launcher/SDK/Chat Participant do CASAN điều khiển toàn vòng đời | Mạnh nhất trong local client |
+| `managed_hook` | Hook/policy được tổ chức pin và user thường không thể tắt | Guardrail tổ chức |
+| `project_hook` | Hook được commit trong repo và user trust project | Guardrail theo project, có thể bị bypass bởi người có quyền sửa cấu hình |
+| `observed_only` | Chỉ thu telemetry, không đủ tool/admission gate | Không certified |
+
+UI và export H6 không được gom bốn mức trên thành một nhãn `pass` duy nhất.
+
+### 3.3 Fail-closed ở điểm tạo side effect
+
+Hook nhận prompt có thể có giới hạn fail-open của client. Vì vậy điều kiện tối thiểu để một
+turn được certified là:
+
+- có `admission_id` hợp lệ, ngắn hạn và gắn với project/session/turn;
+- mọi tool side-effect được hỗ trợ phải qua `pre-tool`;
+- tool bị từ chối khi không có admission hoặc bridge không phản hồi trong internal timeout;
+- `finalize` chỉ chứng nhận evidence thực sự quan sát được;
+- hook timeout/error được ghi là failure, không tự suy diễn các H downstream đã pass.
+
+Absolute enforcement cần `casan_owned` hoặc cấu hình `managed_hook`; Plan-20 không quảng bá
+`project_hook` như một sandbox tuyệt đối.
+
+## 4. Agentic bridge dùng chung
+
+Thêm executable Python stdlib-only trong `packages/casan-harness` với các operation:
+
+| Operation | Input chính | Output/side effect |
+|---|---|---|
+| `begin` | client, project, session, prompt | scan H1/H4, tạo trace/admission, trả client-native allow/block JSON |
+| `pre-tool` | admission, tool name/input | H2/H4/H5 decision, allow/deny/update input nếu client hỗ trợ |
+| `post-tool` | tool result/status/duration | append evidence đã redact |
+| `telemetry` | model, runtime, token/cost fields | ghi H6 cùng provenance và data quality |
+| `finalize` | stop reason, assistant summary, changed files | chạy verify/final controls và đóng trace |
+| `abort` | failure/interruption reason | đóng trace non-certified, phát failure telemetry |
+
+### State contract
+
+- State nằm dưới `.specify/state/agentic-sessions/`, dùng atomic write và file lock hiện có.
+- Không dùng raw prompt làm key; dùng hash + opaque `turn_id`.
+- Admission có TTL, project root canonical và client/session binding.
+- Không ghi secret, credential hoặc toàn bộ tool output vào audit log.
+- Hook response renderer tách theo adapter; core bridge không phụ thuộc Claude/Codex JSON.
+- Mọi record có `schema_version`, `trace_id`, `project_id`, `client`, `client_version`,
+  `integration_mode`, `certification_strength`, `occurred_at`.
+
+## 5. H6 cho native agentic client
+
+H6 cần bổ sung các field sau nhưng vẫn giữ tương thích schema hiện tại:
+
+| Nhóm | Field |
+|---|---|
+| Client | `client`, `client_version`, `adapter_version`, `integration_mode` |
+| Identity | `client_session_id_hash`, `client_turn_id_hash`, `trace_id` |
+| Runtime | `started_at`, `finished_at`, `duration_ms`, `tool_calls`, `failures`, `retries` |
+| Usage | input/output/cache token nếu client cung cấp |
+| Cost | amount, currency, `cost_source`, estimated/provider-reported |
+| Quality | `telemetry_quality=complete|partial|insufficient`, warnings, missing fields |
+| Trust | `certification_strength`, hook trust/policy mode, bypass/fallback signal |
+
+Quy tắc:
+
+- Không biến dữ liệu thiếu thành `0`.
+- Token/cost không có nguồn chính xác phải là `null` kèm warning.
+- Claude status-line estimate và session delta phải ghi rõ provenance; không gọi là
+  provider-reported.
+- Codex usage/cost chỉ được gắn `complete` sau khi spike chứng minh nguồn lifecycle ổn định.
+- H6 report cho phép filter theo `client`, `integration_mode`, `trace_id` và project.
+
+## 6. Kế hoạch thực hiện theo wave
+
+### Wave 0 — Common contract và fixtures
+
+| ID | Việc | Deliverable | Gate |
+|---|---|---|---|
+| 20.0.1 | Chốt JSON lifecycle contract | schema + fixtures begin/pre/post/finalize | invalid payload fail rõ ràng |
+| 20.0.2 | Implement bridge state machine | script + atomic state | replay/expired/cross-project admission bị chặn |
+| 20.0.3 | Nối evidence H1→H7 | trace writer dùng contract hiện có | không phát evidence downstream giả |
+| 20.0.4 | Mở rộng H6 provenance | writer/report/UI/export | thiếu token/cost hiển thị partial, không thành 0 |
+| 20.0.5 | Threat tests | tamper, timeout, bypass, injection | security suite xanh |
+
+### Wave 1 — Claude Code spike và MVP
+
+Thực hiện trước mọi code Codex/VS Code.
+
+| ID | Việc | Deliverable | Gate |
+|---|---|---|---|
+| 20.1.1 | Prototype `UserPromptSubmit` → `begin` | `.claude/settings.json` fixture + command hook | prompt allow/block đúng |
+| 20.1.2 | Prototype `PreToolUse`/`PostToolUse` | tool adapter | side effect thiếu admission bị deny |
+| 20.1.3 | Prototype `Stop`/failure | finalize/abort adapter | trace đóng đúng, không vòng lặp stop |
+| 20.1.4 | Telemetry experiment | status-line/session correlation | H6 ghi provenance + quality đúng |
+| 20.1.5 | Windows installer | PowerShell install/doctor/uninstall | clean Windows clone chạy được |
+| 20.1.6 | Claude acceptance suite | fixture + black-box test | exit gate mục 8 đạt |
+
+Project config được commit; secret và machine-specific path không được commit. Hook command
+phải tự resolve repo root và gọi interpreter có sẵn trong CASAN distribution.
+
+### Wave 2 — Claude Code hardening và rollout nhỏ
+
+- Internal timeout ngắn hơn outer hook timeout; mọi timeout tạo H6 failure.
+- PreToolUse deny side effect khi admission thiếu/expired.
+- Doctor kiểm tra hook loaded, project trust, bridge version và log permissions.
+- Pilot với ít nhất Windows PowerShell và macOS/Linux.
+- Tài liệu nêu rõ project-hook vs managed-hook.
+- Chỉ chuyển sang Codex khi Claude exit gate xanh và có rollback test.
+
+### Wave 3 — Codex spike và MVP
+
+| ID | Việc | Deliverable | Gate |
+|---|---|---|---|
+| 20.3.1 | Map Codex lifecycle payload | fixtures cho UserPromptSubmit/Pre/Post/Stop | contract mapping đầy đủ |
+| 20.3.2 | Project hook adapter | `.codex/hooks.json` + `.codex/config.toml` | trust onboarding rõ ràng |
+| 20.3.3 | Managed policy path | requirements/MDM guide | pin hook và chống disable được chứng minh |
+| 20.3.4 | Tool coverage audit | coverage matrix | tool ngoài coverage bị ghi warning/non-certified |
+| 20.3.5 | H6 usage experiment | stable source hoặc partial contract | không suy diễn token/cost |
+| 20.3.6 | Windows acceptance | install/doctor/normal prompt | cùng behavior với Claude MVP |
+
+Codex tool hooks là guardrail chứ không được xem là coverage tuyệt đối cho hosted/specialized
+tools. Certification phải hạ cấp khi một turn dùng tool mà adapter không quan sát được.
+
+### Wave 4 — VS Code và extension
+
+Thực hiện theo ba tuyến riêng, không gom thành một tuyên bố “mọi plugin”:
+
+1. **Claude Code extension:** black-box test xem project `.claude/settings.json` và hooks có
+   chạy trong extension host hay không.
+2. **Codex IDE extension:** black-box test xem `.codex/hooks.json`, trust và managed policy
+   có giống CLI hay không.
+3. **VS Code/Copilot generic:** tạo `@casan` Chat Participant nếu cần một UI do CASAN sở hữu.
+   Participant detection chỉ là auto-route best effort; built-in participant có thể được ưu
+   tiên nên không được quảng bá là chặn mọi prompt Copilot mặc định.
+
+Mỗi tuyến có capability badge riêng trong H6: `verified`, `partial`, `unsupported`.
+
+### Wave 5 — Adoption, reporting và release
+
+- Update `packages/casan-devkit` để cài config/hook theo client được chọn.
+- Thêm `casan doctor --client claude|codex|vscode` và smoke command.
+- Update hướng dẫn Windows từ clone sạch, không yêu cầu người dùng copy file thủ công.
+- H6 UI drill-down từ client session → trace → H1–H7 evidence.
+- Release notes liệt kê client/version đã test và limitation còn lại.
+- Pilot ≥ 2 project, trong đó có project Basic Design lớn trên Windows.
+
+## 7. Definition of Done
+
+Một client chỉ được ghi là `supported` khi:
+
+- gõ prompt bình thường tạo đúng một native model execution và một CASAN trace;
+- prompt bị policy block không tới model theo capability thực tế của client;
+- side-effect tool thiếu admission bị từ chối trong coverage đã công bố;
+- allow, deny, timeout, interruption và hook crash đều có automated test;
+- H6 hiển thị client/runtime/failure và token/cost theo đúng data quality;
+- H1→H7 evidence truy ngược được từ cùng `trace_id`;
+- Windows install, doctor, uninstall và restart đã chạy trên clean clone;
+- bypass limitation được ghi trong UI/docs, không dùng từ “bắt buộc tuyệt đối” sai mức;
+- core harness regression suite vẫn xanh.
+
+## 8. Exit gate theo giai đoạn
+
+### Claude Code GO để bắt đầu Codex
+
+- 100% test lifecycle fixtures pass.
+- 100% side-effect test trong published coverage bị deny khi thiếu admission.
+- Không có double model execution.
+- Timeout/hook failure tạo non-certified trace và H6 failure.
+- Windows + macOS/Linux smoke pass.
+- H6 HTML/JSON thể hiện `project_hook` hoặc `managed_hook` và telemetry quality.
+
+### Codex GO để bắt đầu VS Code
+
+- Project trust onboarding có test và doctor diagnostic.
+- Managed hook path có tài liệu/policy test.
+- Tool coverage matrix được machine-readable và phản ánh trong certification.
+- Token/cost source được chứng minh hoặc để `partial`, không giả số.
+
+### VS Code release gate
+
+- Mỗi extension/version có black-box evidence độc lập.
+- `@casan` participant được mô tả là CASAN-owned route; participant detection không được
+  dùng làm bằng chứng interception tuyệt đối.
+- Unsupported extension không được hiện `certified`.
+
+## 9. Rollout và rollback
+
+- Feature flags: `CASAN_AGENTIC_BRIDGE_ENABLED`, `CASAN_AGENTIC_ENFORCEMENT_MODE` và client
+  allowlist.
+- Bắt đầu `observe`, sau đó `enforce` trong pilot; production default chỉ đổi sau exit gate.
+- Mỗi installer lưu manifest file đã tạo để uninstall không xóa config của user.
+- Rollback chỉ tắt adapter; `bin/casan-chat` và core H1→H7 hiện tại vẫn hoạt động.
+- Trace sinh trong observe mode luôn mang `observed_only`, không retroactively certified.
+
+## 10. Deliverable dự kiến
+
+```text
+packages/casan-harness/
+  scripts/python/agentic_bridge.py
+  adapters/claude-code/
+  adapters/codex/
+  schemas/agentic-lifecycle.schema.json
+  tests/phase-agentic-bridge-tests.sh
+packages/casan-devkit/
+  templates/claude/
+  templates/codex/
+  windows/install-agentic.ps1
+docs/casan/
+  CASAN_AGENTIC_CLIENTS_WINDOWS.md
+  CASAN_AGENTIC_CLIENT_SECURITY.md
+docs/spikes/
+  CASAN_SPIKE_20_AGENTIC_CLIENT_HOOKS.md
+```
+
+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.