feat: add Claude Code CLI driver and release 0.1.13

Adds `claude` as a fifth builtin agent driver on the Structured transport,
using Claude Code's own stream-json stdio surface rather than a third-party
ACP shim. The adapter is its own family under src/adapters/claude/ and sits
directly on the generic JSONL process layer, because stream-json is a
newline-delimited message stream and not JSON-RPC.

Protocol notes established against Claude Code 2.1.233:

- The `system`/`init` frame is emitted only after the first user message, so
  it cannot serve as a handshake. start() uses the SDK control protocol
  instead: `initialize` observes `current_permission_mode` and proves the
  process is alive without a model turn, then `set_permission_mode`
  establishes bypassPermissions. Only a set refusal or downgrade is
  NATIVE_POLICY_BLOCKED; the deferred init frame still verifies session_id,
  cwd and permissionMode on the first turn.
- Cancellation reports two abort reasons: aborted_streaming mid-token and
  aborted_tools during tool execution. Both normalize to turn.cancelled and
  leave the stdio process usable for the next turn.
- An interrupt that loses the race to a settling turn leaves the CLI owing a
  second result frame, which is absorbed within the cancel window.
  result.num_turns counts agent iterations per prompt, so it cannot correlate
  a result with a turn.
- Interactive control requests (can_use_tool, elicitation,
  request_user_dialog) are denied at the wire boundary and fail the turn with
  UNEXPECTED_NATIVE_INTERACTION. GroupX still has no approval subsystem.
- The initialize payload also carries account, organization, model and
  command inventories; only current_permission_mode and pid are projected.

Unrestricted access is applied through argv only and GroupX never writes
Claude Code's settings files. Claude Code rewrites its own ~/.claude.json
session-state file on any invocation; that is native CLI behavior and is
recorded as a diagnostic rather than gated.

Command resolution covers the native single-file build and the npm package
on both platforms: Windows PATH, %USERPROFILE%\.local\bin\claude.exe, then
the npm-global entrypoint (APPDATA is read only for that last layer); POSIX
PATH, $HOME/.local/bin/claude, then the npm-global cli.js under this Node
prefix, Homebrew or /usr/local, without shelling out to `npm root -g`.

Like Hermes, `claude` is not auto-enabled when the agents field is omitted,
and it carries independent native-live evidence rather than entering the
core codex/grok/kimi M0 gate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: honor00

AGENTS.md

@@ -17,7 +17,7 @@ This file defines the implementation boundary for agents working in `D:\GroupX`.
 
 1. GroupX is a transparent local broker, not a security, authentication, authorization, or governance boundary.
 2. v0.1 has one fixed access policy, `unrestricted`: GroupX must launch each native CLI with the documented maximum-open process/session settings in this repository. Do not expose `access` as a user setting and do not add a second GroupX approval or sandbox policy.
-3. GroupX must not write or override a user's global Codex, Grok, Kimi, or Hermes configuration. Apply the fixed unrestricted policy through process argv or native thread/session configuration. Active Structured Kimi accepts official default global settings and establishes `auto` with `session/set_mode` after every new/load; Hermes is launched with `--yolo acp` and establishes `dont_ask` after every new/load. Do not gate either driver on mutable global permission defaults. The deprecated Direct compatibility code may retain a bounded read-only preflight, but it is not a product entry or Structured prerequisite. GroupX cannot bypass Windows UAC, file ACLs, enterprise requirements, server-side policy, or native static deny rules.
+3. GroupX must not write or override a user's global Codex, Grok, Kimi, Hermes, or Claude Code configuration. Apply the fixed unrestricted policy through process argv or native thread/session configuration. Active Structured Kimi accepts official default global settings and establishes `auto` with `session/set_mode` after every new/load; Hermes is launched with `--yolo acp` and establishes `dont_ask` after every new/load; Claude Code is launched with `--permission-mode bypassPermissions` and re-establishes that mode with a `set_permission_mode` control request after every start/resume. Do not gate these drivers on mutable global permission defaults. Claude Code rewrites its own `~/.claude.json` session-state file on any invocation; that is native CLI behavior, not a GroupX write, and only the user-owned settings files are covered by this invariant. The deprecated Direct compatibility code may retain a bounded read-only preflight, but it is not a product entry or Structured prerequisite. GroupX cannot bypass Windows UAC, file ACLs, enterprise requirements, server-side policy, or native static deny rules.
 4. Bind the Web/API server to loopback by default. Non-loopback serving is outside M0-M2.
 5. The Broker is the only authoritative storage writer. CLI processes never write the database directly.
 6. `from` and actor provenance are assigned by the Broker from the adapter/session binding. Never take sender identity from message text or tool arguments. A binding is a provenance/correlation handle, not a secret, credential, or defense against a hostile local process.
@@ -27,13 +27,13 @@ This file defines the implementation boundary for agents working in `D:\GroupX`.
 10. Keep full transcript, curated public memory, per-Agent core memory, per-Agent dated memory, generated summaries, configured Agent identity, and legacy identity records as distinct data classes. Core memory is explicitly curated by the owning Agent or Web operator; dated memory is a recoverable per-day semantic rollup whose only source rows are successful Turns' bounded current messages and final responses. It is not written once per Turn. Reasoning and tool records never enter either layer.
 11. Collect only fields defined by the GroupX data model. Do not intentionally ingest complete environment dumps, persist raw CLI configuration, or retain unbounded stderr. A bounded parser may read a native config file only to project explicitly allowlisted preflight fields; all other fields stay outside GroupX records and diagnostics. GroupX does not promise to detect or remove secrets that a user or model puts in ordinary message or memory content.
 12. A2A is an optional edge adapter. Do not replace the internal GroupX Envelope with the full A2A task model in the first implementation.
-13. v0.1 keeps `direct | structured` only as storage/history vocabulary; `structured` is the sole runnable product and release transport. Structured means Codex App Server over stdio plus Grok/Kimi/Hermes ACP over stdio. Direct is deprecated: config parsing, Adapter factory, and runtime construction must reject it before opening runtime resources. Direct source and historical records remain only for audit/migration compatibility; do not restore a runtime entry, feature work, native-live Gate, release claim, or fallback. GroupX MCP current-Turn Agent calls are available only in structured mode.
+13. v0.1 keeps `direct | structured` only as storage/history vocabulary; `structured` is the sole runnable product and release transport. Structured means Codex App Server over stdio, Grok/Kimi/Hermes ACP over stdio, and Claude Code stream-json over stdio. Every Structured driver must speak its own vendor's first-party protocol entrypoint; do not introduce a third-party protocol shim as a driver. Direct is deprecated: config parsing, Adapter factory, and runtime construction must reject it before opening runtime resources. Direct source and historical records remain only for audit/migration compatibility; do not restore a runtime entry, feature work, native-live Gate, release claim, or fallback. GroupX MCP current-Turn Agent calls are available only in structured mode.
 14. If the selected adapter cannot initialize, establish its native session/process, or honor the unrestricted contract, fail clearly and persist the failure. Once a prompt may have reached a native session/process, reconcile when the selected transport supports it and never automatically replay the prompt as a new native turn.
 
 ## Implementation discipline
 
 - Implement milestones in the order defined by `docs/IMPLEMENTATION.md`.
-- M0 maintains one active Structured core release baseline from real Codex, Grok, and Kimi runs under the fixed unrestricted policy. A newly added driver such as Hermes must carry its own versioned fixture/no-model probe and must not claim native model/MCP verification until that evidence exists. Direct is marked `DEPRECATED`; prior Direct evidence is historical only and cannot satisfy a current Gate. Native interaction requests must be verified as fail-closed configuration errors, never as an approval-relay feature.
+- M0 maintains one active Structured core release baseline from real Codex, Grok, and Kimi runs under the fixed unrestricted policy. A newly added driver such as Hermes or Claude must carry its own versioned fixture/no-model probe and must not claim native model/MCP verification until that evidence exists. A driver whose native protocol defers its session banner until the first model turn must still establish and prove the unrestricted contract without consuming one. Direct is marked `DEPRECATED`; prior Direct evidence is historical only and cannot satisfy a current Gate. Native interaction requests must be verified as fail-closed configuration errors, never as an approval-relay feature.
 - Standard protocol features and experimental features must be labeled separately. Do not make Codex `dynamicTools` or App Server WebSocket transport an M0 dependency.
 - Keep adapter-specific wire events out of the core. Normalize them at the adapter boundary.
 - Use explicit argv arrays and hidden child processes on Windows; do not invoke CLI commands through a shell unless an adapter contract proves it is necessary.

README.md

@@ -2,7 +2,7 @@
 
 # ⚡ GroupX
 
-**把 Codex App Server、Grok ACP、Kimi ACP 和 Hermes ACP 放进同一个本地 Agent 房间。**
+**把 Codex App Server、Grok ACP、Kimi ACP、Hermes ACP 和 Claude Code CLI 放进同一个本地 Agent 房间。**
 
 一个 Web UI，统一完成群聊路由、会话恢复、上下文压缩与本地记忆。
 
@@ -27,7 +27,8 @@ GroupX 是一个只监听本机 loopback 的多 Agent 群聊 Broker。用户从
 - Codex：App Server；
 - Grok：ACP；
 - Kimi：ACP；
-- Hermes：ACP。
+- Hermes：ACP；
+- Claude：Claude Code CLI stream-json。
 
 历史 `direct` 代码没有运行入口，不参与当前发布，也不会在 Structured 失败时自动 fallback。
 
@@ -43,6 +44,14 @@ GroupX 是一个只监听本机 loopback 的多 Agent 群聊 Broker。用户从
 - **两层 Agent 记忆**：每个 Agent 拥有主动维护的核心记忆，以及把成功回合批量整理成每日一条的私有工作记忆。
 - **会话恢复与故障收敛**：原生 session 支持 resume/load；可能已送达的业务 Prompt 不会自动重放。
 
+## 0.1.13 更新
+
+- 新增 Claude Code CLI driver（`claude`），可在首次引导页或 Agent 设置中添加多个 Claude 实例。
+- 固定使用 `claude --print --input-format stream-json --output-format stream-json --verbose --include-partial-messages --permission-mode bypassPermissions`，unrestricted 由 `set_permission_mode` 建立；GroupX 不写 Claude Code 的 settings 文件。
+- `start()` 先发 `control_request`/`initialize` 读取 `current_permission_mode`（观测），再发 `control_request`/`set_permission_mode` 建立 `bypassPermissions`；只有 set 被拒绝或降级才是 `NATIVE_POLICY_BLOCKED`。
+- 由 GroupX 自己分配原生 session id（`--session-id <uuid>`），恢复使用 `--resume <uuid>`；取消走 `control_request`/`interrupt`，进程可继续用于下一回合。
+- Windows 依次解析 `PATH`、`%USERPROFILE%\.local\bin\claude.exe` 与 npm 全局 `@anthropic-ai/claude-code/cli.js`（经 node 启动，此层才需要 `APPDATA`）；POSIX 为 `PATH`、`$HOME/.local/bin/claude`，再按当前 Node 前缀 / Homebrew / `/usr/local` 找 npm 全局 `cli.js`；`groupx doctor` 可检测 Claude。
+
 ## 0.1.12 更新
 
 - Agent 设置保存后，主房间会立即合并最新名册并刷新参与者数量；新增但尚未启动的 Agent 显示为“等待重启”。
@@ -80,7 +89,7 @@ GroupX 是一个只监听本机 loopback 的多 Agent 群聊 Broker。用户从
 前置条件：
 
 - Node.js `>=24.14.1 <25`；
-- 至少安装并登录 `codex`、`grok`、`kimi`、`hermes` 中的一种 CLI。
+- 至少安装并登录 `codex`、`grok`、`kimi`、`hermes`、`claude` 中的一种 CLI。
 
 ```bash
 npm i -g @susyimes/groupx
@@ -130,7 +139,7 @@ GroupX 当前保持单房间结构，房间 ID 为 `room:main`。
 
 ## Agent 配置
 
-推荐通过首次引导页或右上角“Agent 设置”维护。`agents` 的键是稳定 Agent ID；内置 ID 可省略 `driver`，自定义 ID 必须声明 `driver: codex | grok | kimi | hermes`。
+推荐通过首次引导页或右上角“Agent 设置”维护。`agents` 的键是稳定 Agent ID；内置 ID 可省略 `driver`，自定义 ID 必须声明 `driver: codex | grok | kimi | hermes | claude`。
 
 ```json
 {
@@ -160,6 +169,11 @@ GroupX 当前保持单房间结构，房间 ID 为 `room:main`。
       "command": "hermes",
       "cwd": ".",
       "enabled": false
+    },
+    "claude": {
+      "command": "claude",
+      "cwd": ".",
+      "enabled": false
     }
   }
 }
@@ -169,11 +183,13 @@ GroupX 当前保持单房间结构，房间 ID 为 `room:main`。
 
 Hermes 使用固定的 `hermes --yolo acp` 启动形状，并在每次 `session/new` 或 `session/load` 后、首个 prompt 前设置 ACP mode 为 `dont_ask`。可先运行 `hermes acp --check` 检查本机 ACP 安装。GroupX 不修改 Hermes 的全局配置。
 
+Claude 使用固定的 `claude --print --input-format stream-json --output-format stream-json --verbose --include-partial-messages --permission-mode bypassPermissions` 启动形状；存在 GroupX MCP 绑定时追加 `--mcp-config <json>`，最后追加 `--session-id <uuid>`（新建）或 `--resume <uuid>`（恢复）。Claude Code 的 `system`/`init` 帧要在首条用户消息之后才发出，因此 GroupX 改用 SDK control request：先 `initialize` 读取 `current_permission_mode`（观测），再 `set_permission_mode` 建立 `bypassPermissions`，不消耗模型回合。unrestricted 由 set 建立，不因 initialize 回显用户默认模式而失败；GroupX 不写 Claude Code 的 settings 文件。注意：Claude Code 在任何调用下都会重写自己的 `~/.claude.json` 会话状态文件，那是原生 CLI 行为，不是 GroupX 的写入。
+
 ## 数据与运行边界
 
 - Web/API 默认只监听 `127.0.0.1`。
 - SQLite/WAL 是消息、Turn、记忆和摘要的本地权威事实源。
-- GroupX 不修改 Codex、Grok、Kimi 或 Hermes 的全局配置。
+- GroupX 不修改 Codex、Grok、Kimi、Hermes 或 Claude 的全局配置。
 - GroupX 按固定 `unrestricted` profile 启动原生 CLI，但不能绕过操作系统权限、企业策略、静态 deny rule 或服务端限制。
 - GroupX 没有审批系统；如果 native CLI 仍请求审批、权限或用户交互，当前 Turn 会明确失败。
 - GroupX 不扫描普通消息或记忆中的秘密内容。不要把凭据发送到群聊。
@@ -228,3 +244,4 @@ npm run build
 - [Kimi ACP](https://www.kimi.com/code/docs/en/kimi-code-cli/reference/kimi-acp)
 - [Grok CLI](https://docs.x.ai/build/cli/reference)
 - [Hermes ACP](https://github.com/nousresearch/hermes-agent/blob/main/website/docs/user-guide/features/acp.md)
+- [Claude Code headless（stream-json）](https://docs.claude.com/en/docs/claude-code/headless)

docs/ACCEPTANCE_TESTS.md

@@ -41,6 +41,11 @@
 | G-010 | 并发启动 bind 竞态 | 预检后 `EADDRINUSE` 会有界复查；同 key 赢家按复用成功，无法识别的 listener 返回友好错误，失败方不修改现有 binding/session |
 | G-011 | Hermes Structured 启动 | argv 固定 `hermes --yolo acp`；initialize 必须标识 `hermes-agent`；new/load 后首 prompt 前成功设置 `dont_ask`；不写全局配置 |
 | G-012 | Hermes capability 兼容 | raw initialize 未声明 HTTP 时只有 Hermes driver 可按官方实现接收 HTTP MCP descriptor；其他 ACP driver 仍 fail-closed；报告不得把 descriptor 冒充 actual call |
+| G-013 | Claude Structured 启动 | argv 固定 `claude --print --input-format stream-json --output-format stream-json --verbose --include-partial-messages --permission-mode bypassPermissions`，有 GroupX MCP 绑定时追加 `--mcp-config <json>`，末尾为 `--session-id <uuid>` 或 `--resume <uuid>`；`start()` 完成 `control_request`/`initialize` 与 `control_request`/`set_permission_mode(bypassPermissions)`；不写 Claude Code settings 文件 |
+| G-014 | Claude permission mode 负向 | 仅 `set_permission_mode` 被拒绝或降级时为 `NATIVE_POLICY_BLOCKED`；`initialize` 回显非目标模式不得单独失败启动；缺 `current_permission_mode` 为 `PROTOCOL_INVALID_MESSAGE`；普通协议失败按 Adapter 错误收敛；不写 settings、不 fallback |
+| G-015 | Claude 延后 `system`/`init` 帧 | `init` 帧只在首条用户消息之后到达，不得当作握手；到达时 `session_id`、`cwd` 与 `permissionMode` 必须与 GroupX 启动值一致，无法解析或不一致都使当前 Turn 失败 |
+| G-016 | Claude 取消与迟到 `result` | `aborted_streaming`(流式中) 与 `aborted_tools`(工具执行中) 都归一化为 `turn.cancelled` 且不污染 session；interrupt 输给正在收敛的 Turn 时补发的 `result` 必须在 cancel 窗口内被吸收，不得终结下一个 Turn |
+| G-017 | Claude 交互类 control request | `can_use_tool`、`elicitation`、`request_user_dialog` 一律拒绝并以 `UNEXPECTED_NATIVE_INTERACTION` 失败当前 Turn；`hook_callback` 等非决策类只回协议错误，不影响 Turn |
 
 精确 native profile：
 
@@ -50,6 +55,7 @@
 | Grok | flags 在前：`--no-auto-update --permission-mode bypassPermissions --sandbox off --no-plan [--resume <sessionId>] --output-format streaming-json --single <prompt>` | 同一 flags 在前，追加 `agent stdio` |
 | Kimi | deprecated Direct 参考实现保留 preflight 后的 one-shot argv | `kimi acp`；不要求 global default mode；new/load（含 Adapter resume）后首 prompt 前 `session/set_mode {sessionId,modeId:"auto"}` |
 | Hermes | `NOT_APPLICABLE` | `hermes --yolo acp`；new/load 后首 prompt 前 `session/set_mode {sessionId,modeId:"dont_ask"}` |
+| Claude | `NOT_APPLICABLE` | `claude --print --input-format stream-json --output-format stream-json --verbose --include-partial-messages --permission-mode bypassPermissions`；有 GroupX MCP 绑定时追加 `--mcp-config <json>`；末尾 `--session-id <uuid>`（新建）或 `--resume <uuid>`（恢复）；`start()` 先 `control_request`/`initialize`，再 `control_request`/`set_permission_mode(bypassPermissions)` |
 
 Kimi ACP 不读取 global defaults 作为启动门禁；mode 不持久化，任何新建或恢复 session 都要重设。Codex thread sandbox 必须是当前 0.147 wire 的 kebab-case `danger-full-access`；不能误用 `dangerFullAccess`。
 
@@ -65,6 +71,8 @@ Structured release 合同：三 Agent 都能用 fixed argv/mode 握手、建立/
 
 Hermes 是后加 driver，不改变上述核心三 Agent Gate。它的 adapter fixture 与 0.20.1 无模型 initialize/new/set-mode/cold-load probe 可以证明 wiring 和 session contract；在 Hermes 真实模型回复、GroupX MCP actual call、cancel 后复用与 clean close 的 matching live evidence 完成前，相关 Hermes 能力只能标 `documented/probed`，不能借用核心三 Agent 的 PASS。
 
+Claude 同样是后加 driver，也不改变核心三 Agent Gate。它有自己的版本化 native-live probe：2026-08-16 对 win32 上的 Claude Code 2.1.233 确认基础 Turn、streaming delta、经 http binding 恰好一次的 GroupX MCP `memory_search` 调用、runtime 重启后 `--resume` 恢复、clean shutdown、无遗留进程与用户 settings 未被修改，证据位于 `.groupx/evidence/claude-live/`。该证据只支撑 Claude 自己的能力分级，不进入 codex/grok/kimi 的核心 M0 Gate，也不能借用其 PASS。
+
 ## 5. 协议与 sender provenance
 
 | ID | 用例 | 通过标准 |
@@ -243,7 +251,7 @@ Broker 指标不含模型网络/推理；只测 Structured session startup/reuse
 - 默认 Structured 三 Agent 的全部适用 M0 case PASS，才可关闭 v0.1 release transport Gate；
 - Direct 不得被宣称为 active/完整可用；其 baseline、Agent 和适用 case 保持 `DEPRECATED`；
 - Structured 三 Agent actual MCP call 全部 verified，才可宣称全向当前回合主动互调；
-- 新增 Hermes driver 的产品入口可以随实现交付，但 Hermes native/MCP 能力声明必须按其独立 evidence 分级；
+- 新增 Hermes 与 Claude driver 的产品入口可以随实现交付，但它们的 native/MCP 能力声明必须按各自独立 evidence 分级；
 - native interaction 负向合同通过，且无 approval surface；
 - 无自动 fallback、跨 transport recovery 或 replay。