# CASAN Plan-20 — Transparent Agentic Client Integration

> Ngày lập: 2026-07-22  
> Cập nhật: 2026-07-23  
> Trạng thái: **IMPLEMENTED + Plan-21 hardening — Claude black-box verified; Codex current hook schema + trust onboarding implemented; VS Code `@casan` packaged, host black-box 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

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.

## 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` | ✅ **37/37 PASS** (C1–C12 + threat + adapters) |
| DevKit templates + Windows installer (Wave 5) | `packages/casan-devkit/templates/{claude,codex}/`, `packages/casan-devkit/windows/install-agentic.ps1` | ✅ (install/doctor/uninstall + manifest) |
| Global project bootstrap | `.casan/casan-hook.py` from `packages/casan-devkit/templates/project/` | ✅ auto-load config + live pin verify |
| VS Code/Copilot explicit route | `packages/casan-harness/adapters/vscode/extension/`, `adapters/vscode/` | ✅ packaged dependency-free VSIX; `@casan` only |
| 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 (37/37).
- ✅ 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 host trust**: schema đã pin theo current Codex manual; project hook
  chỉ load sau project + exact-hook-hash trust qua `/hooks`, nên clean untrusted
  black-box phải giữ `pending_trust`, không giả `verified`.
- **VS Code / extension host**: `@casan` Chat Participant đã hiện thực và đóng
  gói VSIX; môi trường phát triển hiện không có `code` CLI để black-box extension
  host. Built-in Copilot vẫn `unsupported_global_interception`.
- **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ố.