niceeval 0.8.1 → 0.9.0

package/docs-site/zh/reference/official-adapters.mdx

@@ -15,10 +15,11 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
 ### claude-code
 
 - **鉴权**：`ANTHROPIC_API_KEY`（工厂参数 `apiKey` 可覆盖），可选 `ANTHROPIC_BASE_URL`（工厂参数 `baseUrl`）。
-- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段写进沙箱里用户级的 `~/.claude.json`（顶层 `mcpServers` 字段）。
+- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段写进沙箱里用户级的 `~/.claude.json`（顶层 `mcpServers` 字段）。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）；远程 Streamable HTTP 端点写 `url`（可带 `headers`，逐字进请求头，常用于 `Authorization`），写成 `{ "type": "http", "url": …, "headers": … }` 条目。`url` 要沙箱内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
 - **装 Skill**：`skills: SkillSpec[]`——本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进沙箱的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现（原生 `Skill` 工具调用被 adapter 归一为 `skill.loaded` 事件，不重复记成工具调用；用 `t.loadedSkill()` 断言，不是 `t.calledTool("Skill", ...)`）。
 - **装原生 Plugin**：`plugins: ClaudeCodePluginSpec[]`，每一项声明 Marketplace 连接（`name` / `source` / 可选 `ref`）和其中的 Plugin 名。这个类型只属于 claude-code，传不进 codex。
 - **官方配置文件**：`settingsFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径；它指向一份完整的 Claude Code `settings.json`。路径相对项目根，只允许普通相对路径或 `./` 前缀；`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.claude/settings.json`；不继承宿主机配置，也不 deep merge 或重新序列化。`model` 和 `env` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。Secret 走环境变量，别写进配置文件。
+- **安装后脚本**：`postSetup: SandboxHook[]`，在写 settings、挂 MCP、装 Skill 与 Plugin 全部完成后，按数组顺序在沙箱里跑你的钩子函数。典型用途是运行插件自带的 setup 脚本（比如它要往全局配置里登记 hook）——这类脚本必须等安装产物就位才能跑。钩子抛错算基础设施错误（Attempt 记 errored），不算 agent 答题失败。
 - **tracing**：claude CLI 的 beta 原生遥测（`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`），span 只有结构和计时，细节见 [OTel 接入](/zh/how-to/connect-otel)。
 
 例如，用 `configs/claude-code/no-web.json` 关闭内置联网检索：
@@ -60,15 +61,16 @@ export default defineExperiment({
 ### codex
 
 - **鉴权**：`CODEX_API_KEY`（工厂参数 `apiKey` 可覆盖，不是 `OPENAI_API_KEY`），可选 `CODEX_BASE_URL`（工厂参数 `baseUrl`）接 OpenAI 兼容代理。
-- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段追加进 `~/.codex/config.toml` 的 `[mcp_servers.<name>]` 段。
+- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段追加进 `~/.codex/config.toml` 的 `[mcp_servers.<name>]` 段。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）；远程 Streamable HTTP 端点写 `url`（可带 `headers`，写成 `[mcp_servers.<name>.http_headers]` 子表）。`url` 要沙箱内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
 
   <Warning>
     是复数 `mcp_servers`：单数 `[mcp_server.x]` 会被 codex CLI 静默忽略，MCP 压根挂不上，且不会报错——自查用 `codex mcp list`。
   </Warning>
 
 - **装 Skill**：`skills: SkillSpec[]`，与 claude-code 同一个类型。装进 `.agents/skills/<name>/`，并把发现指引写进 AGENTS.md——codex 没有 claude-code 那种原生 Skill 工具，只把文件装进去它不会主动去读；断言"用没用到"看它是否真的执行过读那个文件的 shell 命令，没有工具调用可以直接认。
-- **装原生 Plugin**：`plugins: CodexPluginSpec[]`，声明 Marketplace 连接（`name` / `source` / 可选 `ref`）和其中的 Plugin 名。这个类型只属于 codex，传不进 claude-code。
+- **装原生 Plugin**：`plugins: CodexPluginSpec[]`，声明 Marketplace 连接（`name` / `source` / 可选 `ref` / 可选 `sparse`）和其中的 Plugin 名。`sparse` 是路径数组（如 `[".agents", "plugins/repo-map"]`），每项让 `codex plugin marketplace add` 带一个 `--sparse <path>`，大仓库只拉插件所需路径，装出来的内容不变。这个类型只属于 codex，传不进 claude-code。
 - **官方配置文件**：`configFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径；它指向一份完整的 Codex `config.toml`。路径相对项目根，只允许普通相对路径或 `./` 前缀；`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.codex/config.toml`；不继承宿主机配置，也不拼接、deep merge 或解析后重写。`model`、`model_provider`、`model_providers`、`model_reasoning_effort`、`mcp_servers`、`otel` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。Secret 走环境变量，别写进配置文件。
+- **安装后脚本**：`postSetup: SandboxHook[]`，语义与 claude-code 相同：全部安装步骤完成后按序在沙箱里跑你的钩子函数，适合运行插件自带的 setup 脚本。脚本往 codex 全局配置登记的 hook 不需要交互式信任确认——运行时 `codex exec` 已绕过 hook 信任门槛，hook 直接生效。
 - **tracing**：内置，通过 `config.toml` 的 `[otel.trace_exporter.otlp-http]` 段配置，协议 `http/json`。
 
 例如，用 `configs/codex/no-web.toml` 关闭内置联网检索：
@@ -87,6 +89,7 @@ export default defineExperiment({
   agent: codexAgent({
     mcpServers: [
       { name: "browser", command: "npx", args: ["-y", "@anthropic/mcp-browser"] },
+      { name: "team-memory", url: "https://mem.example.com/mcp/", headers: { Authorization: `Bearer ${process.env.MEM_API_KEY}` } },
     ],
     skills: [{ kind: "repo", source: "Effect-TS/skills", ref: "8f3c1a2", skills: ["effect"] }],
     plugins: [
@@ -109,6 +112,7 @@ export default defineExperiment({
 - **装插件**：`pythonPlugins: PythonPluginSpec[]`（`{ package }`：PyPI 包、版本约束或 git URL），`setup` 阶段进 `uv tool install … --with <package>`。这个类型只属于 bub；package 集合进安装 checkpoint key，插件不同的两个变体不会复用同一份安装缓存。
 - **预制 Bub**：NiceEval 的 E2B 配方会把 Bub、OTel 插件和 Python 插件集合算成安装指纹。Adapter 只复用指纹完全一致的环境；仅在 PATH 里放一个 `bub` 不足以证明兼容。构建入口见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
 - bub 没有 `mcpServers`——MCP 只属于支持它的 Adapter，Config 上压根没有这个字段。
+- **安装后脚本**：`postSetup: SandboxHook[]`，语义与另外两个 Adapter 相同：全部安装步骤完成后按序在沙箱里跑你的钩子函数。
 - **安装方式**：走 `uv tool install`（PyPI 包，不是 npm 包），首次安装会建 checkpoint 缓存加速后续沙箱。
 - **tracing**：内置，通过环境变量注入，协议 `http/protobuf`。
 
@@ -132,15 +136,16 @@ export default defineExperiment({
 | | claude-code | codex | bub |
 |---|---|---|---|
 | 鉴权环境变量 | `ANTHROPIC_API_KEY` | `CODEX_API_KEY` | `BUB_API_KEY` + `BUB_API_BASE` |
-| MCP server | ✅ `mcpServers` | ✅ `mcpServers` | ❌ |
+| MCP server | ✅ `mcpServers`（stdio + HTTP） | ✅ `mcpServers`（stdio + HTTP） | ❌ |
 | Skill | ✅ `skills: SkillSpec[]`（原生发现） | ✅ `skills: SkillSpec[]`（+ 发现指引） | ✅ `skills: SkillSpec[]`（+ 发现指引） |
 | 原生 Plugin | ✅ `plugins: ClaudeCodePluginSpec[]` | ✅ `plugins: CodexPluginSpec[]` | ❌ |
 | 官方配置文件 | ✅ `settingsFile`（完整 settings.json） | ✅ `configFile`（完整 config.toml） | ❌ |
 | Python Plugin | ❌ | ❌ | ✅ `pythonPlugins: PythonPluginSpec[]` |
+| 安装后脚本 | ✅ `postSetup: SandboxHook[]` | ✅ `postSetup: SandboxHook[]` | ✅ `postSetup: SandboxHook[]` |
 | tracing | ✅（beta，仅结构与计时） | ✅ | ✅ |
 | 安装方式 | npm 全局包 | npm 全局包 | `uv tool install`（PyPI） |
 
-装了什么有据可查：Adapter 在 `setup` 收尾把安装清单写进沙箱的 `__niceeval__/agent-setup.json`，运行器把它存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`）。清单只记来源、ref、Skill/Plugin 名、解析出的版本，以及官方配置文件的项目相对路径和 SHA-256；不保存配置正文、API Key 或环境变量值。
+装了什么有据可查：Adapter 在 `setup` 收尾把安装清单写进沙箱的 `__niceeval__/agent-setup.json`，运行器把它存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`）。清单只记来源、ref、Skill/Plugin 名、解析出的版本，以及官方配置文件的项目相对路径和 SHA-256；不保存配置正文、API Key 或环境变量值。MCP server 同理只记非敏感字段：stdio 形态记 `name` / `command` / `args` 不记 `env`，HTTP 形态记 `name` / `url` 不记 `headers`。
 
 ## 非 Sandbox 适配器
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -172,6 +172,7 @@
     "tiers:check": "node scripts/sync-tiers.mjs check",
     "view:build": "vite build --config src/view/app/vite.config.ts",
     "build:report": "tsc -p tsconfig.report-build.json && node scripts/prune-report-dist.mjs",
+    "build:index": "tsx scripts/generate-reference.ts --bundled-index",
     "site:dev": "cd site && node scripts/dev.mjs",
     "site:build": "cd site && next build",
     "docs:dev": "node scripts/docs-dev.mjs",

package/src/agents/bub.ts

@@ -11,7 +11,8 @@ import {
 import { writeAgentSetupManifest } from "./manifest.ts";
 import { createCheckpoint, restoreCheckpoint } from "../sandbox/checkpoint.ts";
 import { mapBubSpans } from "../o11y/otlp/mappers/bub.ts";
-import type { Agent, AgentContext, AgentSetupManifest, Sandbox, SkillSpec } from "../types.ts";
+import { runPostSetupHooks } from "./post-setup.ts";
+import type { Agent, AgentContext, AgentSetupManifest, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -61,6 +62,13 @@ export interface BubConfig {
    * 安装 checkpoint(否则第二个变体会静默拿到第一个变体的环境)。
    */
   pythonPlugins?: PythonPluginSpec[];
+  /**
+   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在装 bub、装 Skills /
+   * Python package、写 manifest 全部完成后执行。钩子返回的 cleanup 按 LIFO 与 teardown 一起
+   * 收尾;抛错按基础设施错误计(attempt errored)。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  postSetup?: SandboxHook[];
 }
 
 const UV = "$HOME/.local/bin/uv";
@@ -278,6 +286,10 @@ export function bubAgent(config?: BubConfig): Agent {
       if (manifest.skills.length || manifest.pythonPlugins?.length) {
         await writeAgentSetupManifest(sb, manifest);
       }
+
+      // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
+      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
+      return await runPostSetupHooks(sb, ctx, config?.postSetup);
     },
 
     async send(input, ctx) {

package/src/agents/claude-code.test.ts

@@ -218,7 +218,7 @@ describe("claudeCodeAgent settingsFile · setup", () => {
     await rm(root, { recursive: true, force: true });
   });
 
-  const ctx = {} as AgentContext; // claude 的 setup 不读 ctx
+  const ctx = {} as AgentContext; // 本组用例不配 postSetup,setup 不会读 ctx 的字段
 
   it("原始字节原样上传并 mv 成用户级 ~/.claude/settings.json;manifest 记项目相对路径 + SHA-256,不落正文", async () => {
     const body = '{\n  "$schema": "https://json.schemastore.org/claude-code-settings.json",\n  "permissions": { "deny": ["WebSearch", "WebFetch"] }\n}\n';
@@ -271,3 +271,45 @@ describe("claudeCodeAgent settingsFile · setup", () => {
     expect(box.written["__niceeval__/agent-setup.json"]).toBeUndefined();
   });
 });
+
+describe("claudeCodeAgent mcpServers · 形态落位", () => {
+  const ctx = {} as AgentContext;
+
+  it("HTTP 形态写成 ~/.claude.json 的 type http + url + headers 条目,stdio 条目不变;manifest 只记非 secret 字段", async () => {
+    const box = sb();
+    await claudeCodeAgent({
+      apiKey: "k",
+      mcpServers: [
+        { name: "browser", command: "npx", args: ["-y", "server"], env: { TOKEN: "env-sekret" } },
+        { name: "team-memory", url: "https://mem.example.com/mcp/", headers: { Authorization: "Bearer sekret" } },
+      ],
+    }).setup!(asSandbox(box), ctx);
+
+    // 用户级 MCP 配置经 heredoc 写进 ~/.claude.json(shared.writeFile),内容在命令里。
+    const write = box.commands.find((c) => c.includes("cat > ~/.claude.json"))!;
+    expect(write).toContain('"type": "http"');
+    expect(write).toContain('"url": "https://mem.example.com/mcp/"');
+    expect(write).toContain('"Authorization": "Bearer sekret"');
+    expect(write).toContain('"command": "npx"');
+
+    const manifestRaw = box.written["__niceeval__/agent-setup.json"]!;
+    const manifest = JSON.parse(manifestRaw) as AgentSetupManifest;
+    expect(manifest.mcpServers).toEqual([
+      { name: "browser", command: "npx", args: ["-y", "server"] },
+      { name: "team-memory", url: "https://mem.example.com/mcp/" },
+    ]);
+    expect(manifestRaw).not.toContain("sekret");
+  });
+
+  it("边界:HTTP 形态无 headers → 条目不带 headers 字段", async () => {
+    const box = sb();
+    await claudeCodeAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "team-memory", url: "https://mem.example.com/mcp/" }],
+    }).setup!(asSandbox(box), ctx);
+
+    const write = box.commands.find((c) => c.includes("cat > ~/.claude.json"))!;
+    expect(write).toContain('"type": "http"');
+    expect(write).not.toContain("headers");
+  });
+});

package/src/agents/claude-code.ts

@@ -14,7 +14,9 @@ import {
 import { mapClaudeCodeSpans } from "../o11y/otlp/mappers/claude-code.ts";
 import { t } from "../i18n/index.ts";
 import { DEFAULT_CLAUDE_CODE_CLI_VERSION } from "./coding-cli-versions.ts";
-import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from "../types.ts";
+import { assertMcpServers, isHttpMcp, mcpManifestEntries } from "./mcp.ts";
+import { runPostSetupHooks } from "./post-setup.ts";
+import type { Agent, AgentSetupManifest, McpServer, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
 // Claude Code 的 agent adapter(沙箱型)。
@@ -69,7 +71,8 @@ export interface ClaudeCodeConfig {
   maxTurns?: number;
   /**
    * 额外 MCP server(每个沙箱 setup 时写进用户级 ~/.claude.json)。
-   * 示例:{ name: "browser", command: "npx", args: ["-y", "@anthropic/mcp-browser"] }
+   * stdio 形态写 command(可带 args / env);Streamable HTTP 形态写 url(可带 headers,
+   * 逐字进请求头),落成 { "type": "http", "url": …, "headers": … } 条目。
    */
   mcpServers?: McpServer[];
   /**
@@ -88,6 +91,14 @@ export interface ClaudeCodeConfig {
    * setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
    */
   settingsFile?: string;
+  /**
+   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写 settings、挂 MCP、
+   * 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+   * 「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
+   * 抛错按基础设施错误计(attempt errored)。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  postSetup?: SandboxHook[];
 }
 
 export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
@@ -115,7 +126,7 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       }),
     },
 
-    async setup(sb) {
+    async setup(sb, ctx) {
       // 预制模板已把 claude 烘焙进镜像(PATH 上)就跳过安装;否则 npm 全局装。
       await sb.runShell(
         `command -v claude >/dev/null 2>&1 || npm install -g @anthropic-ai/claude-code@${DEFAULT_CLAUDE_CODE_CLI_VERSION}`,
@@ -140,13 +151,20 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       }
 
       if (config?.mcpServers?.length) {
+        assertMcpServers(config.mcpServers);
         const servers: Record<string, object> = {};
         for (const s of config.mcpServers) {
-          servers[s.name] = {
-            command: s.command,
-            ...(s.args?.length && { args: s.args }),
-            ...(s.env && { env: s.env }),
-          };
+          servers[s.name] = isHttpMcp(s)
+            ? {
+                type: "http",
+                url: s.url,
+                ...(s.headers && Object.keys(s.headers).length && { headers: s.headers }),
+              }
+            : {
+                command: s.command,
+                ...(s.args?.length && { args: s.args }),
+                ...(s.env && { env: s.env }),
+              };
         }
         // 用户级 MCP 配置在 ~/.claude.json(顶层 mcpServers 字段),不是 ~/.claude/claude.json
         // ——后者 claude CLI 根本不读,MCP 静默挂不上(本机 `claude mcp list` 可核对)。
@@ -161,12 +179,8 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
         manifest.nativePlugins = await installPlugins(sb, config.plugins);
       }
       if (config?.mcpServers?.length) {
-        // manifest 里只记「挂了哪个 server、怎么起」;env 里可能有 token,不落盘。
-        manifest.mcpServers = config.mcpServers.map((s) => ({
-          name: s.name,
-          command: s.command,
-          ...(s.args?.length ? { args: [...s.args] } : {}),
-        }));
+        // manifest 里只记「挂了哪个 server、怎么连」;env / headers 里可能有 token,不落盘。
+        manifest.mcpServers = mcpManifestEntries(config.mcpServers);
       }
       if (settings) {
         // 只记来源路径与字节哈希,不落正文(任意官方配置都可能带敏感字符串)。
@@ -181,6 +195,10 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       ) {
         await writeAgentSetupManifest(sb, manifest);
       }
+
+      // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
+      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
+      return await runPostSetupHooks(sb, ctx, config?.postSetup);
     },
 
     async send(input, ctx) {

package/src/agents/codex.test.ts

@@ -17,7 +17,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { codexAgent, installPlugins, type CodexPluginSpec } from "./codex.ts";
 import { createAgentSession } from "../context/session.ts";
-import type { AgentContext, AgentSetupManifest, CommandOptions, CommandResult, Sandbox, SandboxFile } from "../types.ts";
+import type { AgentContext, AgentSetupManifest, CommandOptions, CommandResult, McpServer, Sandbox, SandboxFile } from "../types.ts";
 
 /** 内存沙箱:runShell 记命令(可按命令包含的子串打脚本化输出),uploadFile / writeFiles 记内容。 */
 class FakeSandbox implements Partial<Sandbox> {
@@ -91,6 +91,32 @@ describe("codex installPlugins · 命令构造", () => {
     ]);
   });
 
+  it("marketplace.sparse 逐项生成 --sparse <path>(缺省不含由上面的精确命令断言覆盖);manifest 不记录 sparse", async () => {
+    const box = sb();
+    const out = await installPlugins(asSandbox(box), [
+      {
+        marketplace: {
+          name: "acme",
+          source: "acme/codex-plugins",
+          sparse: [".agents", "plugins/repo-map"],
+        },
+        name: "repo-map",
+      },
+    ]);
+    expect(box.commands[0]).toBe(
+      "codex plugin marketplace add 'acme/codex-plugins' --sparse '.agents' --sparse 'plugins/repo-map'",
+    );
+    expect(out[0]!.marketplace).toEqual({ name: "acme", source: "acme/codex-plugins" });
+  });
+
+  it("marketplace.sparse 空数组与缺省等价:add 命令不含 --sparse", async () => {
+    const box = sb();
+    await installPlugins(asSandbox(box), [
+      { marketplace: { name: "acme", source: "acme/codex-plugins", sparse: [] }, name: "repo-map" },
+    ]);
+    expect(box.commands[0]).toBe("codex plugin marketplace add 'acme/codex-plugins'");
+  });
+
   it("同名 marketplace 只连一次:两个 plugin 共用一个 marketplace.name → 只有一条 marketplace add,两条 plugin add", async () => {
     const box = sb();
     const plugins: CodexPluginSpec[] = [
@@ -339,3 +365,144 @@ describe("codexAgent · live step feedback", () => {
     expect(ctx.session.id).toBe("thread-1");
   });
 });
+
+describe("codexAgent · exec 信任姿态", () => {
+  // bug: memory/codex-hook-trust-headless-silent-skip.md
+  it("首轮与 resume 的 exec 命令都含 --dangerously-bypass-hook-trust(headless 下未授信 hook 被 codex 静默跳过,零报错)", async () => {
+    const stdout = JSON.stringify({ type: "thread.started", thread_id: "thread-1" }) + "\n";
+    const box = sb([{ match: "codex exec", result: () => ({ stdout }) }]);
+    const ctx: AgentContext = {
+      signal: new AbortController().signal,
+      flags: {},
+      sandbox: asSandbox(box),
+      session: createAgentSession(),
+      progress() {},
+      diagnostic() {},
+      log() {},
+    };
+    const agent = codexAgent({ apiKey: "test-key" });
+
+    await agent.send!({ text: "first" }, ctx);
+    await agent.send!({ text: "second" }, ctx);
+
+    const execs = box.commands.filter((c) => c.startsWith("codex exec"));
+    expect(execs).toHaveLength(2);
+    expect(execs[0]).not.toContain("codex exec resume");
+    expect(execs[1]).toContain("codex exec resume thread-1");
+    for (const cmd of execs) expect(cmd).toContain("--dangerously-bypass-hook-trust");
+  });
+});
+
+describe("codexAgent mcpServers · 形态落位", () => {
+  const ctx = { flags: {} } as AgentContext;
+
+  it("HTTP 形态:url 行 + [mcp_servers.<name>.http_headers] 子表;manifest 只记 name/url,headers 值不落盘", async () => {
+    const box = sb();
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [
+        { name: "team-memory", url: "https://mem.example.com/mcp/", headers: { Authorization: "Bearer sekret" } },
+      ],
+    }).setup!(asSandbox(box), ctx);
+
+    const mcp = box.commands.find((c) => c.includes("[mcp_servers.team-memory]"))!;
+    expect(mcp).toContain('url = "https://mem.example.com/mcp/"');
+    expect(mcp).toContain("[mcp_servers.team-memory.http_headers]");
+    expect(mcp).toContain('"Authorization" = "Bearer sekret"');
+    expect(mcp).not.toContain("command =");
+
+    const manifestRaw = box.written["__niceeval__/agent-setup.json"]!;
+    const manifest = JSON.parse(manifestRaw) as AgentSetupManifest;
+    expect(manifest.mcpServers).toEqual([{ name: "team-memory", url: "https://mem.example.com/mcp/" }]);
+    expect(manifestRaw).not.toContain("sekret");
+  });
+
+  it("边界:HTTP 形态无 headers → 不写空 http_headers 子表", async () => {
+    const box = sb();
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "team-memory", url: "https://mem.example.com/mcp/" }],
+    }).setup!(asSandbox(box), ctx);
+
+    const mcp = box.commands.find((c) => c.includes("[mcp_servers.team-memory]"))!;
+    expect(mcp).toContain('url = "https://mem.example.com/mcp/"');
+    expect(mcp).not.toContain("http_headers");
+  });
+
+  it("反例:同一 server 同时给出 command 与 url → setup 报错点名该 server,不写 MCP 块", async () => {
+    const box = sb();
+    // 形状判别不设 kind 标签,双字段的错误配置在类型上可能混得进来 —— 运行期兜底点名报错。
+    const dup = { name: "dup-server", command: "npx", url: "https://x.example.com/mcp" } as McpServer;
+    await expect(codexAgent({ apiKey: "k", mcpServers: [dup] }).setup!(asSandbox(box), ctx)).rejects.toThrow(
+      /dup-server/,
+    );
+    expect(box.commands.some((c) => c.includes("[mcp_servers."))).toBe(false);
+  });
+});
+
+describe("codexAgent postSetup · 安装后钩子", () => {
+  const mkCtx = (): AgentContext =>
+    ({
+      flags: {},
+      experimentId: "exp-1",
+      signal: new AbortController().signal,
+      progress: () => {},
+      diagnostic: () => {},
+    }) as unknown as AgentContext;
+
+  it("钩子在 Adapter 安装与 manifest 之后按数组顺序执行,拿到 SandboxHook 窄上下文", async () => {
+    const box = sb();
+    const seen: string[] = [];
+    let manifestPresentAtHook = false;
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "browser", command: "npx" }],
+      postSetup: [
+        async (sandbox, hookCtx) => {
+          manifestPresentAtHook = box.written["__niceeval__/agent-setup.json"] !== undefined;
+          seen.push(`a:${hookCtx.experimentId}`);
+          await sandbox.runShell("post-hook-a");
+        },
+        async (sandbox) => {
+          seen.push("b");
+          await sandbox.runShell("post-hook-b");
+        },
+      ],
+    }).setup!(asSandbox(box), mkCtx());
+
+    expect(seen).toEqual(["a:exp-1", "b"]);
+    expect(manifestPresentAtHook).toBe(true);
+    const configIdx = box.commands.findIndex((c) => c.includes("config.toml"));
+    const aIdx = box.commands.indexOf("post-hook-a");
+    const bIdx = box.commands.indexOf("post-hook-b");
+    expect(aIdx).toBeGreaterThan(configIdx);
+    expect(bIdx).toBeGreaterThan(aIdx);
+  });
+
+  it("钩子返回的 cleanup 合成一个闭包交还 runner,按 LIFO 执行", async () => {
+    const box = sb();
+    const order: string[] = [];
+    const cleanup = await codexAgent({
+      apiKey: "k",
+      postSetup: [() => () => void order.push("a"), () => () => void order.push("b")],
+    }).setup!(asSandbox(box), mkCtx());
+
+    expect(typeof cleanup).toBe("function");
+    await (cleanup as () => Promise<void> | void)();
+    expect(order).toEqual(["b", "a"]);
+  });
+
+  it("反例:钩子抛错从 setup 传播(attempt errored 通道)", async () => {
+    const box = sb();
+    await expect(
+      codexAgent({
+        apiKey: "k",
+        postSetup: [
+          () => {
+            throw new Error("hook boom");
+          },
+        ],
+      }).setup!(asSandbox(box), mkCtx()),
+    ).rejects.toThrow("hook boom");
+  });
+});

package/src/agents/codex.ts

@@ -19,7 +19,9 @@ import {
 import { mapCodexSpans } from "../o11y/otlp/mappers/codex.ts";
 import { t } from "../i18n/index.ts";
 import { DEFAULT_CODEX_CLI_VERSION } from "./coding-cli-versions.ts";
-import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from "../types.ts";
+import { assertMcpServers, isHttpMcp, mcpManifestEntries } from "./mcp.ts";
+import { runPostSetupHooks } from "./post-setup.ts";
+import type { Agent, AgentSetupManifest, McpServer, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
 // OpenAI Codex CLI 的 agent adapter(沙箱型)。
@@ -59,6 +61,12 @@ export interface CodexPluginSpec {
     source: string;
     /** 固定 Marketplace 的 Tag、Commit 或 Branch(→ `codex plugin marketplace add --ref`)。 */
     ref?: string;
+    /**
+     * sparse 拉取的路径列表,每项生成一个 `codex plugin marketplace add --sparse <path>`
+     * (codex 的 `--sparse` 必须带路径参数、可重复):大仓库只取插件所需路径,省略或空数组即全量 clone。
+     * 只影响拉取速度,不影响装出来的内容;manifest 不记录它。
+     */
+    sparse?: string[];
   };
   /** Marketplace 中的 Plugin 名。 */
   name: string;
@@ -71,7 +79,8 @@ export interface CodexConfig {
   baseUrl?: string;
   /**
    * 额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
-   * 格式对应 codex config.toml 的 [mcp_servers.<name>] 表。
+   * stdio 形态(command/args/env)写 [mcp_servers.<name>] 的 command 行;
+   * Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.<name>.http_headers] 子表。
    */
   mcpServers?: McpServer[];
   /**
@@ -92,6 +101,14 @@ export interface CodexConfig {
    * 项目相对路径与字节 SHA-256,不落正文。
    */
   configFile?: string;
+  /**
+   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
+   * 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+   * 「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
+   * 抛错按基础设施错误计(attempt errored)。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  postSetup?: SandboxHook[];
 }
 
 export function codexAgent(config?: CodexConfig): Agent {
@@ -155,15 +172,25 @@ export function codexAgent(config?: CodexConfig): Agent {
       }
 
       if (config?.mcpServers?.length) {
+        assertMcpServers(config.mcpServers);
         const mcpToml = config.mcpServers
           .map((s) => {
             // 注意是复数 mcp_servers:单数 [mcp_server.x] 会被 codex 静默忽略,
             // MCP 压根挂不上(实测 codex-cli 0.142.x,`codex mcp list` 可核对)。
-            const lines: string[] = [`[mcp_servers.${s.name}]`, `command = "${s.command}"`];
-            if (s.args?.length) lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
-            if (s.env && Object.keys(s.env).length) {
-              lines.push(`[mcp_servers.${s.name}.env]`);
-              for (const [k, v] of Object.entries(s.env)) lines.push(`${k} = "${v}"`);
+            const lines: string[] = [`[mcp_servers.${s.name}]`];
+            if (isHttpMcp(s)) {
+              lines.push(`url = "${s.url}"`);
+              if (s.headers && Object.keys(s.headers).length) {
+                lines.push(`[mcp_servers.${s.name}.http_headers]`);
+                for (const [k, v] of Object.entries(s.headers)) lines.push(`"${k}" = "${v}"`);
+              }
+            } else {
+              lines.push(`command = "${s.command}"`);
+              if (s.args?.length) lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
+              if (s.env && Object.keys(s.env).length) {
+                lines.push(`[mcp_servers.${s.name}.env]`);
+                for (const [k, v] of Object.entries(s.env)) lines.push(`${k} = "${v}"`);
+              }
             }
             return lines.join("\n");
           })
@@ -184,12 +211,8 @@ export function codexAgent(config?: CodexConfig): Agent {
         manifest.nativePlugins = await installPlugins(sb, config.plugins);
       }
       if (config?.mcpServers?.length) {
-        // manifest 只记「挂了哪个 server、怎么起」;env 里可能有 token,不落盘。
-        manifest.mcpServers = config.mcpServers.map((s) => ({
-          name: s.name,
-          command: s.command,
-          ...(s.args?.length ? { args: [...s.args] } : {}),
-        }));
+        // manifest 只记「挂了哪个 server、怎么连」;env / headers 里可能有 token,不落盘。
+        manifest.mcpServers = mcpManifestEntries(config.mcpServers);
       }
       if (nativeConfig) {
         // 只记来源路径与字节哈希,不落正文(任意官方配置都可能带敏感字符串)。
@@ -203,6 +226,10 @@ export function codexAgent(config?: CodexConfig): Agent {
       ) {
         await writeAgentSetupManifest(sb, manifest);
       }
+
+      // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
+      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
+      return await runPostSetupHooks(sb, ctx, config?.postSetup);
     },
 
     tracing: {
@@ -223,7 +250,12 @@ export function codexAgent(config?: CodexConfig): Agent {
 
     async send(input, ctx) {
       const sb = ctx.sandbox;
-      const flags = "--json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check";
+      // hook trust bypass 是 runtime-only(config.toml 设不了):headless 下 codex 对非 managed
+      // 来源 hook 的交互式授信永远无人应答,不带它插件装的 hook 会被静默跳过、零报错
+      // (见 memory/codex-hook-trust-headless-silent-skip.md)。沙箱内 hook 来源全部由实验配置
+      // 声明,与 approvals/sandbox bypass 同一信任层级。
+      const flags =
+        "--json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --dangerously-bypass-hook-trust";
       const prompt = shared.shellQuote(input.text);
       const resuming = ctx.session.id;
       const cmd = resuming
@@ -324,8 +356,12 @@ export async function installPlugins(
     const { marketplace } = plugin;
     if (!connected.has(marketplace.name)) {
       const refFlag = marketplace.ref ? ` --ref ${shared.shellQuote(marketplace.ref)}` : "";
+      // --sparse 只影响拉取速度,不影响装出来的内容;manifest 不记录它。
+      const sparseFlags = (marketplace.sparse ?? [])
+        .map((path) => ` --sparse ${shared.shellQuote(path)}`)
+        .join("");
       const add = await sb.runShell(
-        `codex plugin marketplace add ${shared.shellQuote(marketplace.source)}${refFlag}`,
+        `codex plugin marketplace add ${shared.shellQuote(marketplace.source)}${refFlag}${sparseFlags}`,
       );
       if (add.exitCode !== 0) {
         throw new Error(

package/src/agents/mcp.ts

@@ -0,0 +1,31 @@
+// MCP server 的形态判别与 manifest 映射 —— Claude Code / Codex 两个 adapter 共用。
+// 契约见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」:
+// stdio(command)与 Streamable HTTP(url)按形状判别;双字段是配置错误,setup 点名报错。
+
+import { t } from "../i18n/index.ts";
+import type { AgentSetupManifest, McpHttpServer, McpServer } from "./types.ts";
+
+/** 形态判别:有 url 的是 HTTP。调用前先过 {@link assertMcpServers}(双字段在那里报错)。 */
+export function isHttpMcp(server: McpServer): server is McpHttpServer {
+  return "url" in server && typeof server.url === "string";
+}
+
+/** 双字段(command + url)的配置错误在写任何沙箱配置前抛出,点名 server。 */
+export function assertMcpServers(servers: readonly McpServer[]): void {
+  for (const server of servers) {
+    if ("command" in server && "url" in server) {
+      throw new Error(t("mcp.ambiguousTransport", { name: server.name }));
+    }
+  }
+}
+
+/** manifest 条目:只记非 secret 字段(stdio 不含 env,HTTP 不含 headers)。 */
+export function mcpManifestEntries(
+  servers: readonly McpServer[],
+): NonNullable<AgentSetupManifest["mcpServers"]> {
+  return servers.map((s) =>
+    isHttpMcp(s)
+      ? { name: s.name, url: s.url }
+      : { name: s.name, command: s.command, ...(s.args?.length ? { args: [...s.args] } : {}) },
+  );
+}