CASAN/docs/plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md

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 (Wave 0 + Wave 1 core) — bridge, adapters, tests, devkit, docs đã ship và xanh; Codex/VS Code black-box trên client thật 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. Trạng thái triển khai chi tiết: §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:

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

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	✅ 30/30 PASS (C1–C12 + threat)
DevKit templates + Windows installer (Wave 5)	packages/casan-devkit/templates/{claude,codex}/, packages/casan-devkit/windows/install-agentic.ps1	✅ (install/doctor/uninstall + manifest)
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 (30/30).
• ✅ 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 payload keys: adapter đọc nhiều alias phòng thủ; cần pin trên Codex thật (Wave 3.1).
• VS Code / extension: chưa black-box trên client thật; @casan Chat Participant (Wave 4) chưa hiện thực — vẫn giữ badge unsupported cho tới khi có evidence độc lập.
• 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ố.