@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/product.selfhosted.json

@@ -1 +1 @@
-{"agents":[{"name":"cli","instructions":"cli-agent-prompt","description":"cli agent","models":["codewise-chat"],"modelTags":["craft"],"commands":["init","compact","statusline","insights"],"tools":["Agent","Read","Write","Edit","Bash","PowerShell","Glob","Grep","EnterPlanMode","ExitPlanMode","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","StructuredOutput","ToolSearch","DeferExecuteTool","SendMessage","SendUserMessage","TeamCreate","TeamDelete","NotebookEdit","LSP","EnterWorktree","LeaveWorktree","CronCreate","CronDelete","CronList","DelegateTool","WeChatReply","WeComReply","PushNotification","ReportFindings","ComputerUse","ListMcpResources","ReadMcpResource","WaitForMcpServers","Workflow","Monitor","REPL","A2AGetAgentCard","A2ASendMessage","A2AGetTask","A2ACancelTask"],"tags":["cli","default","model:craft"]},{"name":"general-purpose","instructions":"cli-agent-prompt","description":"general-purpose agent","tools":["Read","Write","Edit","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","ToolSearch","DeferExecuteTool","StructuredOutput","SendMessage","SendUserMessage","NotebookEdit","LSP","ComputerUse","ImageGen","ImageEdit","Artifact","ArtifactControl","ListMcpResources","ReadMcpResource","WaitForMcpServers","REPL"],"tags":["cli","general-purpose"]},{"name":"compact","instructions":"compact-agent-prompt","description":"compact agent","tools":["Read"],"commands":["_compact"],"tags":["cli","compact"]},{"name":"contextSummary","instructions":"context-summary-agent-prompt","description":"Context summary agent for conversation compaction and max-token recovery","tools":[],"tags":["cli","contextSummary"]},{"name":"contentAnalyzer","instructions":"content-analyzer-agent-instructions","description":"content analyzer agent","tags":["cli","content-analyzer"],"tools":[]},{"name":"terminalTitleGenerator","instructions":"terminal-title-generator-instructions","description":"Generate terminal window titles from conversation topics.","tags":["cli","terminal-title-generator"],"tools":[]},{"name":"promptSuggestion","instructions":"prompt-suggestion-instructions","description":"Suggest the user's next prompt after a conversation turn.","tags":["cli","prompt-suggestion"],"tools":[]},{"name":"memorySelector","instructions":"memory-selector-instructions","description":"Select relevant memories for the current query.","models":["lite"],"tags":["cli","memory-selector"],"tools":[]},{"name":"summaryGenerator","instructions":"summary-generator-instructions","description":"Generate session summaries from conversation content.","tags":["cli","summary-generator"],"tools":[]},{"name":"securityReviewer","instructions":"security-reviewer-instructions","description":"Review bounded security decisions without tools.","models":["lite"],"tags":["cli","security-reviewer"],"tools":[]},{"name":"autoModeClassifier","instructions":"auto-mode-classifier-instructions","description":"Classify auto mode tool permission risk.","models":["lite"],"tags":["cli","auto-mode-classifier"],"tools":[]},{"name":"promptHookEvaluator","instructions":"prompt-hook-evaluator-instructions","description":"Evaluates prompt hooks using LLM to determine if conditions are met","models":["lite"],"tags":["cli","prompt-hook-evaluator"],"tools":[]},{"name":"insightsAnalyzer","instructions":"base-agent-instructions","description":"Analyzes user usage data facets for the /insights command","tags":["cli","insights-analyzer"],"tools":[]},{"name":"agentInstructions","instructions":"agent-instructions","description":"generating agent instructions","tags":["cli","agent-instructions"],"tools":[]},{"name":"statusline-setup","instructions":"agent-statusline-instructions","description":"Use this agent to configure the user's Codebuddy Code status line setting.","tools":["Read","Write","Edit","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Explore","instructions":"agent-explore-instructions","description":"Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. \"src/components/**/*.tsx\"), search code for keywords (eg. \"API endpoints\"), or answer questions about the codebase (eg. \"how do API endpoints work?\"). When calling this agent, specify the desired thoroughness level: \"quick\" for basic searches, \"medium\" for moderate exploration, or \"very thorough\" for comprehensive analysis across multiple locations and naming conventions.","models":["lite"],"tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","SendMessage","SendUserMessage","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Plan","instructions":"agent-plan-instructions","description":"Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a multi-step task before writing code. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. Read-only: it designs but does not modify files or exit plan mode; the caller reviews the plan and implements it.","tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","ToolSearch","DeferExecuteTool","TeamCreate","TeamDelete","SendMessage","SendUserMessage"],"asTool":true,"tags":["cli","sub-agent"]}],"models":[{"credits":"x0.01 credits","id":"codewise-chat","name":"Codewise-Chat","vendor":"tencent","maxOutputTokens":8192,"maxInputTokens":128000,"supportsToolCall":true,"supportsImages":false,"disabledMultimodal":true,"maxAllowedSize":56000}],"links":{"officialWebsite":"https://copilot.tencent.com/cli","helpDocument":"https://copilot.tencent.com/docs/cli","issueFeedback":"https://cnb.cool/codebuddy/codebuddy-code/-/issues","issueCreation":"https://cnb.cool/codebuddy/codebuddy-code/-/issues/new","mcpHelpDocument":"https://copilot.tencent.com/docs/cli/mcp","hooksHelpDocument":"https://copilot.tencent.com/docs/cli/hooks","sandboxHelpDocument":"https://copilot.tencent.com/docs/cli/bash-sandboxing","upgradeUrl":""},"productFeatures":{"BillingNotice":false,"ShareLink":true,"Artifact":true,"CodeAdoptionRate":false,"CloudAgentsSmartMerge":true,"CustomModelsJSON":true,"CustomModelIdPrefix":true,"DeferToolLoading":true,"ScheduledTasks":true,"SkipToolCallSupportCheck":true},"commit":"d5cd5f8fbbaa71808a6fa3648103e540ddb77745","date":"2026-09-30T05:49:29.879Z"}
+{"agents":[{"name":"cli","instructions":"cli-agent-prompt","description":"cli agent","models":["codewise-chat"],"modelTags":["craft"],"commands":["init","compact","statusline","insights"],"tools":["Agent","Read","Write","Edit","Bash","PowerShell","Glob","Grep","EnterPlanMode","ExitPlanMode","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","StructuredOutput","ToolSearch","DeferExecuteTool","SendMessage","SendUserMessage","TeamCreate","TeamDelete","NotebookEdit","LSP","EnterWorktree","LeaveWorktree","CronCreate","CronDelete","CronList","DelegateTool","WeChatReply","WeComReply","PushNotification","ReportFindings","ComputerUse","ListMcpResources","ReadMcpResource","WaitForMcpServers","Workflow","Monitor","REPL","A2AGetAgentCard","A2ASendMessage","A2AGetTask","A2ACancelTask"],"tags":["cli","default","model:craft"]},{"name":"general-purpose","instructions":"cli-agent-prompt","description":"general-purpose agent","tools":["Read","Write","Edit","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","ToolSearch","DeferExecuteTool","StructuredOutput","SendMessage","SendUserMessage","NotebookEdit","LSP","ComputerUse","ImageGen","ImageEdit","Artifact","ArtifactControl","ListMcpResources","ReadMcpResource","WaitForMcpServers","REPL"],"tags":["cli","general-purpose"]},{"name":"compact","instructions":"compact-agent-prompt","description":"compact agent","tools":["Read"],"commands":["_compact"],"tags":["cli","compact"]},{"name":"contextSummary","instructions":"context-summary-agent-prompt","description":"Context summary agent for conversation compaction and max-token recovery","tools":[],"tags":["cli","contextSummary"]},{"name":"contentAnalyzer","instructions":"content-analyzer-agent-instructions","description":"content analyzer agent","tags":["cli","content-analyzer"],"tools":[]},{"name":"terminalTitleGenerator","instructions":"terminal-title-generator-instructions","description":"Generate terminal window titles from conversation topics.","tags":["cli","terminal-title-generator"],"tools":[]},{"name":"promptSuggestion","instructions":"prompt-suggestion-instructions","description":"Suggest the user's next prompt after a conversation turn.","tags":["cli","prompt-suggestion"],"tools":[]},{"name":"memorySelector","instructions":"memory-selector-instructions","description":"Select relevant memories for the current query.","models":["lite"],"tags":["cli","memory-selector"],"tools":[]},{"name":"summaryGenerator","instructions":"summary-generator-instructions","description":"Generate session summaries from conversation content.","tags":["cli","summary-generator"],"tools":[]},{"name":"securityReviewer","instructions":"security-reviewer-instructions","description":"Review bounded security decisions without tools.","models":["lite"],"tags":["cli","security-reviewer"],"tools":[]},{"name":"autoModeClassifier","instructions":"auto-mode-classifier-instructions","description":"Classify auto mode tool permission risk.","models":["lite"],"tags":["cli","auto-mode-classifier"],"tools":[]},{"name":"promptHookEvaluator","instructions":"prompt-hook-evaluator-instructions","description":"Evaluates prompt hooks using LLM to determine if conditions are met","models":["lite"],"tags":["cli","prompt-hook-evaluator"],"tools":[]},{"name":"insightsAnalyzer","instructions":"base-agent-instructions","description":"Analyzes user usage data facets for the /insights command","tags":["cli","insights-analyzer"],"tools":[]},{"name":"agentInstructions","instructions":"agent-instructions","description":"generating agent instructions","tags":["cli","agent-instructions"],"tools":[]},{"name":"statusline-setup","instructions":"agent-statusline-instructions","description":"Use this agent to configure the user's Codebuddy Code status line setting.","tools":["Read","Write","Edit","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Explore","instructions":"agent-explore-instructions","description":"Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. \"src/components/**/*.tsx\"), search code for keywords (eg. \"API endpoints\"), or answer questions about the codebase (eg. \"how do API endpoints work?\"). When calling this agent, specify the desired thoroughness level: \"quick\" for basic searches, \"medium\" for moderate exploration, or \"very thorough\" for comprehensive analysis across multiple locations and naming conventions.","models":["lite"],"tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","SendMessage","SendUserMessage","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Plan","instructions":"agent-plan-instructions","description":"Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a multi-step task before writing code. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. Read-only: it designs but does not modify files or exit plan mode; the caller reviews the plan and implements it.","tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","ToolSearch","DeferExecuteTool","TeamCreate","TeamDelete","SendMessage","SendUserMessage"],"asTool":true,"tags":["cli","sub-agent"]}],"models":[{"credits":"x0.01 credits","id":"codewise-chat","name":"Codewise-Chat","vendor":"tencent","maxOutputTokens":8192,"maxInputTokens":128000,"supportsToolCall":true,"supportsImages":false,"disabledMultimodal":true,"maxAllowedSize":56000}],"links":{"officialWebsite":"https://copilot.tencent.com/cli","helpDocument":"https://copilot.tencent.com/docs/cli","issueFeedback":"https://cnb.cool/codebuddy/codebuddy-code/-/issues","issueCreation":"https://cnb.cool/codebuddy/codebuddy-code/-/issues/new","mcpHelpDocument":"https://copilot.tencent.com/docs/cli/mcp","hooksHelpDocument":"https://copilot.tencent.com/docs/cli/hooks","sandboxHelpDocument":"https://copilot.tencent.com/docs/cli/bash-sandboxing","upgradeUrl":""},"productFeatures":{"BillingNotice":false,"ShareLink":true,"Artifact":true,"CodeAdoptionRate":false,"CloudAgentsSmartMerge":true,"CustomModelsJSON":true,"CustomModelIdPrefix":true,"DeferToolLoading":true,"ScheduledTasks":true,"SkipToolCallSupportCheck":true},"commit":"d841c07d38e59b70c5527c07f5e7d636dfc5a895","date":"2026-10-04T15:58:50.402Z"}

package/docs/client.md

@@ -178,6 +178,47 @@ in-process backend 支持服务重启后的子历史读取。`runtimeStatus: 'no
 实例尚未加载；`state` 为已知的最后终态，未知则为 `null`。这时 `parentToolCallId`、
 `background` 和调用元数据也可能缺省。读取不会启动子任务或发送 `subagent/started`。
 
+## MCP OAuth
+
+远端 HTTP/SSE MCP 可由 Harness 完成 OAuth。先以不带 `headers` 的配置挂载服务器，再使用当前连接创建或恢复的会话 ID 发起登录：
+
+```ts
+const { sessionId } = await client.session.new({
+    cwd: workspace,
+    mcpServers: [{ name: 'calendar', type: 'http', url: mcpUrl, headers: [] }],
+});
+const target = { threadId: sessionId, name: 'calendar' };
+const login = await client.mcpServer.oauth.login({
+    ...target,
+    redirectUri: 'http://127.0.0.1:43123/oauth/callback',
+});
+
+// Host 先准备回调入口，再打开浏览器；也可以使用已注册的应用 URI。
+await openBrowser(login.authorizationUrl);
+const callback = await waitForOAuthCallback();
+if (callback.error || callback.state !== login.state) {
+    await client.mcpServer.oauth.cancel({ ...target, state: login.state });
+} else {
+    await client.mcpServer.oauth.complete({
+        ...target, state: callback.state, code: callback.code,
+    });
+}
+
+const { data } = await client.mcpServerStatus.list({ threadId: sessionId });
+// 授权成功后 authStatus 为 oAuth，工具目录供 Agent 和 Client 共用。
+await client.mcpServer.oauth.logout(target);
+```
+
+`openBrowser` 和 `waitForOAuthCallback` 由应用实现；Harness 不启动额外的回调监听。`redirectUri` 支持 HTTPS、loopback HTTP 或应用的自定义 URI。Host 应将回调绑定到发起它的登录窗口，并验证 `state`。用户关闭窗口或拒绝授权时调用 `cancel`。
+
+默认使用授权服务器的动态客户端注册。已有注册的客户端可传 `client: { clientId, clientSecret? }`；公共客户端省略 `clientSecret`。PKCE、授权码兑换和 token 刷新由 Executor SDK 负责。登录返回授权地址和 `state`，不返回 token。
+
+当前授权只保存在内存中，归属于当前会话的 MCP 挂载；只有拥有该挂载的 Client 可以登录、完成授权、取消或登出，共享会话的旁观 Client 不可修改认证。关闭会话、替换 MCP、断开所属 Client 或重启 Harness/Executor 后，需要重新授权。`logout` 删除本地连接凭据，不代替授权服务器的远端撤销接口。凭据不写入 Session 历史，也不读取旧 CLI 的 OAuth token。
+
+`mcpServer/startupStatus/updated` 用于通知目录就绪或失败；需要重新登录时 `failureReason` 为 `reauthenticationRequired`。状态也可通过 `mcpServerStatus.list` 查询。首次连接尚未确认认证类型时，`authStatus` 可以是 `unknown`；调用 `login` 会进行 OAuth 发现。刷新失败不会自动打开浏览器。
+
+这些方法适用于进程内、stdio、WebSocket 和 HTTP Client。已配置 `headers` 的服务器以及 Host 提供的 MCP `Transport` 继续由 Host 管理认证，本入口会拒绝覆盖；需要自定义认证头或复用跨会话登录态时使用 Host Transport。
+
 ## 连接用法
 
 完整同进程应用使用 `await createHarness()`，然后 `await client.connect(harness)`；工具和 MCP Transport 示例见 [同进程接入](in-process.md)。

package/docs/in-process.md

@@ -19,7 +19,7 @@ const showWidget = tool(
 const harness = await createHarness({
     host: { ideName: 'WorkBuddy', ideType: 'Desktop', ideVersion: '1.0.0' },
     productConfig: desktopProduct,
-    tools: { type: 'preset', preset: 'default', append: [showWidget] },
+    tools: [showWidget],
 });
 const client = createClient({
     clientInfo: { name: 'workspace-window', version: '1.0.0' },
@@ -61,7 +61,8 @@ await harness.close();
 | `productConfig` | 应用的完整 Product 配置对象，或版本化配置文件的绝对路径。显式提供时不读取、补入 Agent CLI 的 Product；省略时使用包内默认配置。 |
 | `configDir` | 本进程的配置目录，必须是绝对路径。默认继承 `CODEBUDDY_CONFIG_DIR`，再回落到 `~/.codebuddy`。 |
 | `sandboxCenter` | 默认由 Harness 在首次需要时启动并关闭原生 center。传 `{ address }` 可连接宿主已启动的 center；Harness 不会停止借用的进程。`'managed'` 可在已有进程环境地址时仍选择 Harness 管理。 |
-| `tools` | 工具预设或显式工具数组，见下文。默认使用 `default`。 |
+| `tools` | Host 的 `tool()` 定义数组，追加到默认内置工具。省略或 `[]` 均表示不注册 Host 工具；会话工具选择由插件 Agent 声明决定。 |
+| `hooks` | Functional hooks 的 `register(on, options)` 函数，每个 Harness 注册一次，见下文。 |
 | `mcp.toolsSyncTtlMs` | 工具目录的兜底刷新间隔，默认 15 分钟；`null` 关闭过期刷新，变更通知仍生效。 |
 | `strictMcpConfig` | 为 `true` 时只使用会话显式传入的 MCP；默认还发现用户和插件 MCP。 |
 | `telemetry` | Harness 的结构化日志 sink、队列和刷新设置；传入的 sink 由 Harness flush/close。Agent 内核日志在本地模式默认写入 `configDir/logs`，与此 sink 分开。 |
@@ -108,25 +109,159 @@ const harness = await createHarness({
 
 只有进程句柄不足以连接 center，宿主还需提供它启动时设置的 IPC 地址。未显式传入时，如果进程环境已有 `SANDBOX_CENTER_IPC_ADDRESS`，Harness 会借用该地址；需要由 Harness 接管启动时可显式传 `sandboxCenter: 'managed'`。借用模式下账号切换由宿主先切换 center；Harness 不会替宿主停止进程。
 
-## 工具选择
+## Functional hooks
 
-以下是独立配置示例：
+`createHarness` 的 Host hooks 与启用插件中的 functional hooks 共用 Mods 引擎、事件类型及 middleware 规则。下面区分实际接入的执行事件与宿主能力。
+
+`hooks` 使用 Mods 的 `register(on, options)` 语法，直接在宿主进程注册。注册函数可同步或异步执行；`createHarness()` 等待注册成功后才启用整组 hooks，事件回调也可以异步：
 
 ```ts
-// 默认工具由 Product、平台和启用规则决定。
-{ tools: { type: 'preset', preset: 'default' } }
+import { createClient, createHarness } from '@tencent-ai/agent-harness';
+
+const harness = await createHarness({
+    productConfig: desktopProduct,
+    hooks(on) {
+        on('prompt.submit', async ($, input, next) => {
+            const sessionId = await $.session.id();
+            const context = await desktopContext.read(sessionId, {
+                signal: next.signal,
+            });
+            return next({
+                ...input,
+                context: [...(input.context ?? []), context],
+            });
+        });
+
+        on('tool.call', async ($, input, next) => {
+            const sessionId = await $.session.id();
+            audit.started(sessionId, input.tool);
+            const result = await next(input);
+            audit.finished(sessionId, input.tool, result);
+            return result;
+        });
+    },
+});
+
+const client = createClient({
+    capabilities: { elicitation: { form: {}, url: {} } },
+});
+client.on('elicitation/create', request => desktopDialogs.elicit(request));
+await client.connect(harness);
+```
+
+示例中的 `desktopProduct`、`desktopContext`、`desktopDialogs` 和 `audit` 是宿主自己的配置与服务。回调按所属 query 运行；子任务及后台续跑继承该次执行。`$.session.id()` 和 `$.session.cwd()` 读取发起该 query 的会话与目录，不依赖全局当前会话，也不会因子任务切换而改变。
 
-// 保留默认工具并追加应用工具。
-{ tools: { type: 'preset', preset: 'default', append: [showWidget] } }
+| 事件 | 本入口支持的能力 |
+| --- | --- |
+| `prompt.submit` | 处理新提交的用户文本；`next({ ...input, text })` 改写文本，`next({ ...input, context })` 增加模型可见的隐藏上下文，返回 `{ drop: reason }` 阻止提交。图片、资源及已有隐藏上下文保留，非文本提交提供 `attachments` 元信息；不解析普通文本 badge，不重复处理历史。调用 `next()` 才提交输入；返回后的 text/context 改写不再修改已提交内容。 |
+| `prompt.context` | 处理首条消息的 `blocks`，可增删、改写及排序。改写 `instructionFiles` 会在下一层之前重新渲染 `claudeMd`；直接改写该文本块后不再提供其文件映射。按当前历史段缓存，清空或压缩后重新生成；加载失败或取消不会缓存失败结果。 |
+| `session.start` | 每次加载 hooks 后、首个 prompt 前通知一次；新建第二个会话、resume 或清空不会重复触发。回调返回值不改变 cwd。 |
+| `tool.call` | 工具执行前后 middleware，支持 `{ deny: reason }` 拒绝、`{ result }` 直接回答，以及 `next({ ...input, ...args })` 改写参数后继续。可返回 `context` 追加模型私有提醒，`isError: true` 将结果标为失败；`next()` 的失败结果也可检查及重试。内置工具、Host 工具和 MCP 的参数都在事件顶层，例如 `input.command`、`input.label`。 |
+| `tool.describe` | 修改工具描述及 `isDeferred`；不替换参数 schema。`true` 经 ToolSearch 发现、DeferExecuteTool 执行，`false` 直接放入模型工具列表，省略则保留原有放置规则。 |
+
+可以注册共享 Mods 的事件与通配符，包含 `classic.*`。事件在对应执行点发生时分发；headless Harness 不产生终端输入和渲染事件。`turn.start` 在 query 执行前触发，`turn.complete` 等待该 query 真正结束，工具审批及其续跑不会提前触发完成。现有工具检查、Agent 派发和传统 hooks 事件也使用当前会话的 Mods 运行时。
+
+`$` 提供会话身份、目录、消息、模型、用量、设置读取，及 fs、store、env、clock 等公共能力。配置目录和已装载插件目录的文件访问遵循 dataFs，工作区访问使用会话 Sandbox。`env.set` 只修改本 Mods 实例的覆盖值，不修改宿主进程环境；store 当前为内存存储。关闭会话会释放插件状态和定时器，保留的 `$` 不能继续操作已关闭会话。
+
+显示类操作（`ui.toast`、`ui.status`、`ui.open/close`、`ui.invalidate`、`audio.*` 等）在 headless 模式下 no-op，`session.surface()` 返回 `null`，`session.surfaces()` 返回空数组。`ui.log` 和插件 console 写入 Harness 诊断日志。`ui.ask` 通过会话的真实提问回调等待回答，取消或没有回调会拒绝，不产生默认同意。
+
+注册事件不等于提供所有宿主操作。`model.complete/fork`、`mcp.call`、`session.authorize`、`process.run`、`http.fetch`、动态 `tool/command/agent.register` 和嵌套 `prompt.submit` 尚未装配，调用会明确拒绝。Host 注册工具继续使用 `createHarness({ tools })`，插件 Agent 负责筛选工具。`tool.check` 可以拒绝或要求审批，其 `allow` 在 Server 中仍要经过会话原有权限检查。
+
+`tool.call` 包住实际执行：调用 `next(input)` 后，改写后的参数才进入 schema 校验、原有 PreToolUse / 权限检查及审批。用户批准后才执行工具，沙箱策略继续生效。直接返回 `{ result }` 不执行原工具，因此不会触发它的普通审批。插件 Agent 的工具筛选与 Host 工具注册规则不变；等待期间已撤销的工具不能执行。
+
+事件和嵌套普通数据不可变，改写请构造新对象。`tool`、`tool_use_id` 和 `agentId` 是固定的调用身份，改写这些字段不会改变实际调用目标。每次显式调用 `next()` 都是一次新尝试，会重新检查参数与权限；执行成功后 Hook 抛错的自动恢复只复用已完成结果，不重复执行。等待 `next()` 或 `$` 能力不消耗 Hook 自身的运行预算。Host 自己执行的异步代码计入预算，可通过 `next.signal` 响应取消。
+
+`tool`、`tool_use_id`、`agentId` 和 `consent` 是事件保留字段。若工具 schema 使用这些同名参数，Harness 会保留并原样交给工具；它们不会作为参数暴露给 Hook，也不能通过事件顶层改写。其余参数仍按 `next()` 提交的对象处理，包括删除参数。
 
-// 使用 workbuddy 预设并追加应用工具。
-{ tools: { type: 'preset', preset: 'workbuddy', append: [showWidget] } }
+改写后的工具参数及审批改参均通过当前 SDK 的 `runToolInputGuardrails` 检查。SDK 要求终止执行的 guardrail 异常不能被 hook 转为普通工具结果。公共类型复用共享 Mods 契约，具体执行能力以本入口上述装配范围为准。工具自身的参数和结果采用已注册工具的 schema。
 
-// 显式选择工具；数组会替换预设选择。
-{ tools: ['Read', 'Bash', showWidget] }
+例如，把宿主工具放到延迟目录，并让原本延迟的工具直接显示：
+
+```ts
+hooks(on) {
+    on('tool.describe', async ($, input, next) => {
+        const result = await next(input);
+        if (input.tool === 'host_fetch_issue') {
+            return { ...result, isDeferred: true };
+        }
+        if (input.tool === 'Read') {
+            return { ...result, isDeferred: false };
+        }
+        return result;
+    });
+}
 ```
 
-应用工具使用唯一名称，避免与内置工具重名。`append` 中的定义由 Agent 的 SDK MCP 装配执行，模型看到的是 `show_widget` 这样的原始名称。选择工具不代表自动批准其执行；权限交互仍由 Client 回答。
+把直连工具设为延迟时，该 Agent 的工具策略必须包含 `ToolSearch` 和 `DeferExecuteTool`，否则会报错；不会自动增加被插件策略排除的工具。这两个发现入口始终保留。Code Mode 保留自己的 REPL 目录和执行规则，本入口不把它转换为 ToolSearch 模式，也不支持在该模式下额外延迟直连工具。
+
+内置工具、Host 工具与 MCP 工具共用本轮视图，不修改进程级工具定义或其它会话的目录。描述和放置决定在同一轮内保持稳定，下一轮重新计算；等待期间撤销的工具仍不可调用。延迟调用的 `tool.call` 针对真实目标执行一次，不额外触发 `DeferExecuteTool` 的同名 middleware；代理本身的权限规则、目标参数校验、审批及 guardrails 均保留。宿主启用的高积分强制审批也继续生效，普通权限允许不会绕过它。
+
+运行中的 hook 异常、超时沿用 Mods 的隔离与诊断机制；不能把这种 middleware 当成唯一的权限检查。使用 `next.signal` 将取消传给宿主异步操作，关闭后迟到的 `next()` 不会再次执行工具。`harness.close()` 释放本次注册；重新创建 Harness 会重新注册，不继承旧实例状态。
+
+这些函数不经 JSON-RPC 传输、不写入会话历史。Client 远程注册函数尚未开放；Client 可以按会话启用已安装的插件。
+
+### 插件 functional hooks
+
+在插件的 `hooks/hooks.json` 中声明模块，可与传统 hooks 共存：
+
+```json
+{ "modules": ["./register.ts"] }
+```
+
+`hooks/register.ts`：
+
+```ts
+export function register(on) {
+    on('prompt.submit', async ($, input, next) => {
+        await $.ui.toast('Preparing input'); // headless 时无显示副作用
+        return next({ ...input, context: [...(input.context ?? []), 'Plugin context'] });
+    });
+}
+```
+
+插件元数据沿用 `.codebuddy-plugin`、`.workbuddy-plugin` 或 `.claude-plugin`。安装后通过已有会话配置选择：
+
+```ts
+await client.session.setConfigOption({
+    sessionId,
+    configId: 'enabledPlugins',
+    type: '_codebuddy.ai/plugin_overrides',
+    value: { 'desktop@my-marketplace': true },
+});
+```
+
+首次执行时从会话 dataFs 加载已启用的模块，不需要额外的 Mods 进程开关，也不要求 Host 提供 `hooks`。每个会话有自己的模块闭包、store 和环境覆盖；同一装载期间跨 query 保留。启用列表更新后在下一轮使用新的装载结果；关闭或卸载时通知 `session.end` 并取消定时器。插件的 `session.start` 每次装载触发一次，Host 注册函数仍为每个 Harness 一次。
+
+TS/JS/TSX 及插件内的相对模块可用，模块加载遵循挂载文件系统，不从宿主磁盘补读缺失模块。Node 使用包内可选依赖 esbuild，Bun/SFE 使用 Bun.build；均复用共享的隔离执行入口，插件通过 `$` 访问宿主能力。加载和注册失败会进入诊断日志，其他插件与会话仍可使用。
+
+## 注册应用工具
+
+直接传入 `tool()` 定义，支持只读数组：
+
+```ts
+const harness = await createHarness({
+    tools: [showWidget, openDocument],
+    hooks: registerDesktopHooks,
+});
+```
+
+默认内置工具继续按 Product、平台和启用规则装配。`tools` 注册 Host 实现，不替换默认集合；插件 `settings.json.agent` 指向的 Agent 声明决定当前模式的工具选择。注册 `showWidget` 不会绕过 ask / quick 等模式的选择规则，也不等于批准执行，权限交互仍由 Client 回答。
+
+应用工具使用唯一名称，避免与内置工具重名；重复的 Host 名称在创建时被拒绝。工具由 Agent 的 SDK MCP 装配执行，模型看到的是 `show_widget` 这样的原始名称。创建时捕获工具列表及定义信息，handler 和 schema 保留原实例；之后修改传入数组不会动态更新已创建的 Harness。
+
+### 从旧 tools 配置迁移
+
+这是 `createHarness` 的 API 变更；Client JSON-RPC 与 Agent Server 的 `query.options.tools` 不变。
+
+| 旧写法 | 新写法 |
+| --- | --- |
+| `{ type: 'preset', preset: 'default', append: [showWidget] }` | `tools: [showWidget]` |
+| `{ type: 'preset', preset: 'default' }` | 省略 `tools`，或 `tools: []` |
+| `tools: ['Read', 'Bash', showWidget]` | `tools: [showWidget]`，在插件 Agent 中声明 `Read`、`Bash`、`show_widget` |
+| 用 `tools: []` 禁用内置工具 | 改用插件 Agent 的 `tools: []`；Harness 的空数组只表示没有 Host 工具 |
+| `preset: 'workbuddy'` 或其它显式筛选 | 把所需工具列表放入插件 Agent 声明 |
+
+旧字符串列表和 preset 对象会在创建时明确报错。插件 Agent 的空列表仍采用原有语义：不选择普通内置及 Host 裸名工具；运行时自动提供的协作工具和命名空间 MCP 工具沿用各自规则。
 
 ## 使用官方 MCP Transport
 
@@ -172,6 +307,8 @@ await client.session.resume({ sessionId, cwd, mcpServers: [] });
 
 替换成功会关闭被移除的 MCP 连接并释放 Client 的 Transport 注册；准备失败则保留原列表。前台或 Subagent 仍在执行时，替换返回 busy，待任务结束后重试。多个 Client 共享会话时，由当前持有 MCP 的 Client 更新；旁观 Client 不会接管另一连接的 MCP。
 
+远端 MCP 的交互授权见 [MCP OAuth](client.md#mcp-oauth)。Host 自管认证的 Transport 无需接入这套登录接口。
+
 普通 HTTP/stdio MCP 描述仍然受支持。`mcpServers` 属于会话，`tools` 属于应用；两者可以一起使用。
 
 
@@ -181,7 +318,7 @@ await client.session.resume({ sessionId, cwd, mcpServers: [] });
 
 每个 Agent run 从第一次模型请求起固定直接声明给模型的工具名称、顺序、描述和参数 schema，下一次 run 才采用最新目录。工具发现仍读取实时目录；实际调用检查最新的工具可用性与权限，因此已撤销的工具不会因为旧声明仍在本轮上下文中而继续执行。
 
-应用通过 `tools` 定义的工具保持直接可用。通过 `mcpServers` 桥接的工具遵循 Agent 原有的 MCP 策略，可经 ToolSearch／DeferExecuteTool 或 Code Mode 发现和执行，并保留各个 MCP server 的身份。按需发现的工具定义进入工具结果，不会动态追加到本轮模型的 `tools` 声明。
+应用通过 `tools` 定义的工具默认直接可用，也可由 `tool.describe` 返回 `isDeferred: true` 改为延迟发现。通过 `mcpServers` 桥接的工具遵循 Agent 原有的 MCP 策略，可经 ToolSearch／DeferExecuteTool 或 Code Mode 发现和执行，并保留各个 MCP server 的身份。按需发现的工具定义进入工具结果，不会动态追加到本轮模型的 `tools` 声明。
 
 TTL 用于发现未发送通知的目录变化，与模型的 prompt cache TTL 无关。通常保留默认值，也可以按应用需要调整：
 

package/docs/server.md

@@ -39,6 +39,45 @@ Service 是业务依赖的类型和 Context key；Layer 构造实现、提供依
 
 默认服务复用 Agent CLI 的原有组件；自定义服务可以用相同 Context key 替换实现。Server 和 transport 的关闭由各自 Scope 负责。
 
+## 完整应用的依赖与生命周期
+
+CLI 与 `createHarness()` 共用内部 `Application.layer`。CLI 只负责参数、进程信号和
+Transport，进程内入口只负责宿主的连接与取消信号。两者使用相同的服务构造、关闭顺序和
+关闭预算；关闭 Client 不等于关闭应用。
+
+```text
+CLI / createHarness
+  → Application（应用 Scope、共享 Layer MemoMap）
+      → Auth、Product、Settings、RPC
+      → SessionRuntime ← AgentBackend ← AgentServer
+                                      → agent-cli/server
+                                          → 原生 Effect 服务 + CellJS 组件桥
+                                          → cbc-core → cbc-shared
+```
+
+`SessionRuntime` 是 Harness 所需的执行能力，`AgentBackend` 是把它接到 Agent 的 Layer；
+`AgentServer` 管理已发布 Server 入口的 `start()` / `stop()`。Server 继续拥有 Agent 执行、
+队列、后台续跑、历史和事件投影；Harness 拥有连接、认证、Product 解析、MCP 和权限交互。
+两边的 Effect runtime 各有自己的资源，不把 CellJS 容器暴露给 Harness，也不重复实现内核调度。
+
+构造依赖用 Service / Layer 表达，缺少依赖时由 Effect 的 `R` 类型阻止构建。应用内各阶段
+通过同一个官方 `Layer.MemoMap` 构造：同一个 Layer 对象只获取一次，最后一个持有者释放时
+才清理；不同应用使用不同 MemoMap。替换实现使用 `Layer.provide`。Layer 只负责构造，
+Auth 刷新、Product 更新和 MCP 目录更新继续使用各服务已有的方法。
+
+`cwd`、本轮 Product、凭据、权限和输入属于 Session / Query，上下文仍由现有
+`query.options` 与 Agent 执行作用域传递，不保存到全局 Service 的可变字段中。
+构造阶段解析文件系统、存储等固定依赖，不提前加载所有会话资源。
+
+关闭先停止协议接入、排空 RPC 和会话，再关闭 Agent/MCP、sandbox-center、Product，
+最后释放根 runtime 和遥测。应用 Scope 中的 finalizer 保留原生时间预算：Effect 的普通
+Scope 清理不可中断，不能用它替代子进程回收和硬截止时间。启动失败也释放已经获取的资源；
+关闭失败不会允许新 Harness 接管尚未释放的进程状态。
+
+当前仍限制每进程一个活跃 Harness / Agent Server，完整关闭后可以重建。
+Server 的启动配置、dataFs 和 CellJS 容器仍有进程级归属。仅增加 Scope 并不能安全支持
+多个实例同时运行，因此本次没有放开该限制，也没有改变 `start/query/subscribe` 的公开契约。
+
 ## 按领域定义契约和服务
 
 当前使用 Effect v4。目录按 Account、Plugin、Skills、Config、Session 等领域组织：
@@ -265,7 +304,7 @@ schema，可以添加 error schema 和 middleware。新增方法时，在所属
 [ai-docs](https://github.com/Effect-TS/effect/tree/main/ai-docs)、
 [服务与 Layer 组合](https://github.com/Effect-TS/effect/blob/main/ai-docs/src/01_effect/03_services/20_layer-composition.ts)、
 [契约与实现分离的示例](https://github.com/Effect-TS/effect/blob/main/ai-docs/src/51_http-server/10_basics.ts)，以及固定版本的
-[RpcGroup](https://github.com/Effect-TS/effect/blob/effect%404.0.0-rc.112/packages/effect/src/unstable/rpc/RpcGroup.ts)。
+[RpcGroup](https://github.com/Effect-TS/effect/blob/effect%404.0.0/packages/effect/src/rpc/RpcGroup.ts)。
 
 ### 请求上下文与反向调用
 

package/executor/lib/capsule/THIRD_PARTY_LICENSES.md

@@ -2,7 +2,7 @@
 
 The app bundles dependencies which contain the following licenses:
 
-## @effect/platform-node-shared - 4.0.0-rc.118 (MIT)
+## @effect/platform-node-shared - 4.0.0 (MIT)
 
 MIT License
 
@@ -26,7 +26,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-## @effect/platform-node - 4.0.0-rc.118 (MIT)
+## @effect/platform-node - 4.0.0 (MIT)
 
 MIT License