CASAN/docs/casan/CASAN_AGENTIC_CLIENTS_WINDOWS.md

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 · Spike-20 · Bảo mật/bypass.

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

KHÔNG cần WSL2 cho luồng agentic client. Bridge là Python stdlib + PowerShell thuần. Chỉ cầ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.
• bash trên PATH để chạy security gate H4/H2 — khuyến nghị Git for Windows (Git Bash), nhẹ hơn WSL2 nhiều và đa số máy dev đã có. Đây là điều kiện để turn được certified.
• Repo dự án đã adopt CASAN core (packages/casan-harness tồn tại). Nếu chưa, xem CASAN_ADOPTION_WINDOWS.md.

Graceful degradation: nếu máy không có bash, bridge vẫn chạy — admission/telemetry/redaction bằng Python thuần — nhưng H4/H2 gate không chạy được nên turn bị hạ cấp observed_only (không certified) và không chặn developer. Cài Git Bash để bật lại certification. Không bao giờ certify âm thầm khi thiếu gate.

Nếu Git Bash cài ở đường dẫn không chuẩn, trỏ trực tiếp:

$Env:CASAN_AGENTIC_BASH = "C:\Program Files\Git\bin\bash.exe"

Kiểm tra nhanh:

python3 --version
Test-Path .\packages\casan-harness\scripts\python\agentic_bridge.py
# Xác nhận gate chạy được (bash_available / gates_runnable = true)
python3 .\packages\casan-harness\scripts\python\agentic_bridge.py doctor

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.

# 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

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:

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:

# 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:

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)

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
Mọi turn hiện observed_only trên Windows	Không có bash (thiếu Git Bash) → gate H4/H2 không chạy	Cài Git for Windows hoặc set CASAN_AGENTIC_BASH; doctor sẽ báo gates_runnable=true