# 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](../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

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

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

Kiểm tra nhanh:

```powershell
python3 --version
casan version
```

## 3. Cài global và init project

```powershell
# 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

```powershell
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ử

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