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 dùng Claude Code, Codex, hoặc explicit @casan trong GitHub Copilot Chat, nhưng mọi turn được chứng nhận vẫn có trace H1→H7 và record H6.

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.
CASAN global đã cài bằng install.ps1; repo consumer không cần chứa packages/casan-harness.

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
casan version

3. Cài global và init project

# Từ checkout CASAN: cài một lần trên máy
pwsh .\install.ps1

cd C:\work\my-project

# Project mới: menu chọn Managed/Vendored, sau đó chọn client
casan init

# Hoặc non-interactive, chọn chính xác runtime và client
casan init --non-interactive --runtime managed --client claude,codex --mode enforce
casan init --non-interactive --runtime vendored --client vscode-copilot --mode enforce --vscode-install yes

init merge CASAN handlers vào config hiện hữu, ghi bootstrap .casan\casan-hook.py, pin Core runtime đã resolve, và tạo VSIX @casan khi Copilot được chọn. Managed dùng global installation; Vendored copy Core production-only vào .casan\runtime\casan-core. Bootstrap tự load config.json; không cần source env thủ cô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

casan doctor
casan doctor --client vscode-copilot

Doctor kiểm tra: pin/hash live, bootstrap, hook schema, adapter smoke và trạng thái VS Code extension. Codex vẫn cần review exact hook hash bằng /hooks.

5. Dùng thử

Mở repo trong Claude Code hoặc Codex; với Codex mở /hooks, review/trust.
Trong GitHub Copilot Chat, gọi @casan <prompt>; chat built-in không được CASAN intercept toàn cục.
Gõ prompt. 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.

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`	`enforce` qua init	`observe` (pilot) hoặc `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).

.casan\config.json là nguồn runtime chính; agentic.env chỉ còn là reference cho automation tương thích 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	Chạy lại `casan init --mode enforce --client ...`
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`
`casan doctor` báo integrity/bootstrap missing	Runtime đã chọn hoặc project init chưa đầy đủ	Managed: chạy lại `install.ps1`; Vendored: chạy `casan init --runtime vendored`; sau đó chạy doctor
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`

5.9 KiB Raw Blame History