gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eef5a29eade1020206e1073f275978f7af06bfbe
CASAN/docs/plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md
T

19 KiB
Raw Blame History

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 + Plan-21 hardening — Claude black-box verified; Codex current hook schema + trust onboarding implemented; VS Code @casan packaged, host black-box 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 ✅ 37/37 PASS (C1–C12 + threat + adapters)
DevKit templates + Windows installer (Wave 5) packages/casan-devkit/templates/{claude,codex}/, packages/casan-devkit/windows/install-agentic.ps1 ✅ (install/doctor/uninstall + manifest)
Global project bootstrap .casan/casan-hook.py from packages/casan-devkit/templates/project/ ✅ auto-load config + live pin verify
VS Code/Copilot explicit route packages/casan-harness/adapters/vscode/extension/, adapters/vscode/ ✅ packaged dependency-free VSIX; @casan only
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 (37/37).
  • ✅ 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 host trust: schema đã pin theo current Codex manual; project hook chỉ load sau project + exact-hook-hash trust qua /hooks, nên clean untrusted black-box phải giữ pending_trust, không giả verified.
  • VS Code / extension host: @casan Chat Participant đã hiện thực và đóng gói VSIX; môi trường phát triển hiện không có code CLI để black-box extension host. Built-in Copilot vẫn unsupported_global_interception.
  • 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ố.
Reference in New Issue View Git Blame Copy Permalink