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>
This commit is contained in:
thanhnv
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
0cc43d94d3
commit
4bb184b935
@@ -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 |
|
||||
Reference in New Issue
Block a user