@tencent-ai/agent-sdk 0.3.157 → 0.3.159

package/cli/dist/web-ui/docs/en/cli/goal.md

@@ -0,0 +1,161 @@
+# Keep CodeBuddy Working Until a Goal Is Met
+
+> Use `/goal` to set a completion condition. CodeBuddy will keep working across multiple turns until the condition is satisfied before handing control back to you.
+
+> **Version requirement**: The `/goal` command requires `@tencent-ai/codebuddy-code` with the goal feature included (the `GoalService` module in agent-cli).
+
+`/goal` sets a completion condition that CodeBuddy continuously works toward without you prompting it step by step. At the end of each turn, a small-fast model evaluator checks whether the condition holds — if not, CodeBuddy automatically starts the next turn rather than returning control to you. Once the condition is met, the goal is automatically cleared.
+
+`/goal` is suitable for tracking substantial work that has a verifiable end state:
+
+- Migrating a module to a new API until all call sites compile and tests pass
+- Implementing a design doc until all acceptance criteria are met
+- Splitting a large file into focused modules until each one is within the size budget
+- Processing a list of issues with a certain label until the queue is empty
+
+This document covers:
+
+- [Comparison with other autonomous workflows](#comparison-with-other-autonomous-workflows): choosing between `/goal`, `/loop`, and Stop hooks
+- [Setting a goal](#setting-a-goal) and [tips for writing effective conditions](#writing-an-effective-condition)
+- [Checking status](#checking-status), [clearing early](#clearing-a-goal-early), [running in non-interactive mode](#running-in-non-interactive-mode)
+- [How the evaluator works](#how-the-evaluator-works)
+- [Implementation notes and known limitations](#implementation-notes-and-known-limitations)
+
+
+## Using `/goal`
+
+Each session can only have one active goal at a time. The same command takes on the role of "set / view / clear" depending on the arguments.
+
+### Setting a Goal
+
+Follow `/goal` with the condition you want to satisfy. If there is already an active goal, the new one replaces it (the old goal's hook is automatically unregistered).
+
+```text
+/goal all tests in test/auth pass and the lint step is clean
+```
+
+Once set, CodeBuddy **immediately starts a turn**, passing "the condition itself" as the instruction to the main agent — you don't need to send an additional prompt. A `⊚ /goal active (Xs)` indicator also appears at the bottom-right of the input box, refreshing every second with the elapsed time, so you always know when goal mode is active.
+
+After each turn, the evaluator returns a short reason explaining "why the condition is / is not yet met." This reason is injected into the conversation history as an `isMeta=true` internal message, allowing the model to see the evaluator's perspective on the next turn and precisely address what is missing — this is the key mechanism for the model to "know what steps remain."
+
+> **Session-level behavior**: The goal keeps running until the condition is met or you run `/goal clear`. Run `/goal` (no arguments) to see stats like turns and tokens.
+
+### Writing an Effective Condition
+
+The [evaluator](#how-the-evaluator-works) judges the condition based solely on what CodeBuddy has **already expressed** in the conversation — it does not run commands or read files itself. So the condition should be phrased in a form that "CodeBuddy's own output can prove." "All tests in `test/auth` pass" works because CodeBuddy will run the tests itself, and the results will be in the transcript for the evaluator to read.
+
+A condition that robustly supports multi-turn work typically includes:
+
+- **A measurable end state**: test results, build exit codes, file counts, an empty queue…
+- **A provable method**: e.g., ``\`npm test\` exits 0`` or ``\`git status\` is clean``
+- **Inviolable constraints**: things that must not be changed along the way, e.g., "no other test file is modified"
+
+The condition length limit is **4000 characters**.
+
+If you want to set a fallback upper bound for the goal, add a turn/time clause to the condition, e.g., `or stop after 20 turns`. CodeBuddy will check progress against this clause each turn, and the evaluator can also read it from the conversation.
+
+### Checking Status
+
+Run `/goal` without arguments:
+
+```text
+/goal
+```
+
+In the TUI this opens a goal recap panel; in Web UI / ACP clients it opens an equivalent panel via ACP broadcast; in headless / SDK environments without a UI it falls back to plain text output.
+
+Panel contents include:
+- The condition
+- Elapsed time
+- Number of evaluated turns
+- Token consumption (incremental during goal)
+- The most recent reason from the evaluator
+
+If there is no active goal but a goal was previously achieved in this session, the panel shows that goal's condition, duration, turn count, and token count.
+
+### Clearing a Goal Early
+
+```text
+/goal clear
+```
+
+The following tokens are all treated as synonyms for `clear`: `stop`, `off`, `reset`, `none`, `cancel`. These are only recognized as clear commands on **exact single-token match** — `/goal stop using deprecated API` is still treated as "set a new condition" and won't be consumed.
+
+Running `/clear` to restart the session also removes the active goal (hook unregistered + meta cleaned up).
+
+### Resuming a Session with a Goal
+
+When resuming a session via `--resume` / `--continue`, an unfinished goal is restored (both condition and scope are preserved).
+
+> **Current limitation**: On resume, the original goal's createdAt / turnCount / token starting point are carried over — the timer and counters are not reset. If you want to "restart the clock," first run `/goal clear` and then `/goal <condition>` again. Goals that were already achieved or cleared will not be restored (meta has been deleted).
+
+### Running in Non-Interactive Mode
+
+`/goal` works in [non-interactive (headless) mode](./headless.md) and [Remote Control](./remote-control.md). In `-p` mode, setting a goal causes the evaluator loop to run until completion:
+
+```bash
+codebuddy -p "/goal CHANGELOG.md has an entry for every PR merged this week"
+```
+
+To terminate early before the condition is met, press `Ctrl+C`.
+
+---
+
+## How the Evaluator Works
+
+`/goal` is a wrapper around a session-level [prompt-based Stop hook](./hooks.md). Whenever CodeBuddy's main agent finishes a turn, **the current condition + the current conversation** are sent together to the configured small-model evaluator. The evaluator returns a three-state result (yes / no / unreachable) with a short reason:
+
+- **Yes (`ok: true`)**: Clears the goal, logs an "achieved" event, and the UI shows a `✔ Goal achieved` status bar.
+- **No (`ok: false`)**: Injects the reason as an `isMeta=true` user message into the history (so the main model sees what to work on next), and lets CodeBuddy continue working. Also writes a `goal-progress` UI status bar: `◯ Goal not yet met… continuing`.
+- **Unreachable (`ok: false, impossible: true`)**: Used when the evaluator determines that "this goal simply cannot be completed in the current session" (the condition is self-contradictory, required capabilities/resources are unavailable, or the model has exhausted reasonable attempts). The goal is immediately cleared, and the UI shows `✕ Goal could not be achieved`, preventing the loop from getting stuck.
+
+The evaluator uses the small model bound to the **`lite` slot** in the product configuration (mapped to `gpt-5.1-codex-mini` / `gemini-2.5-flash` / DeepSeek `deepseek-v4-flash` etc. depending on the model provider). Evaluation only reads the existing transcript without invoking tools, so using a small model is both fast and cheap.
+
+> **Billing**: Tokens consumed by the evaluator are billed to the small model account and are typically negligible compared to the main turn.
+
+### Evaluation Window Constraint
+
+To prevent "achieved immediately after setting" — where a previously achieved goal in the same session leaves a success response in the transcript — we inject the current goal's `createdAt` (ISO 8601) into the evaluator's user prompt with an explicit instruction:
+
+> Evaluate ONLY the conversation that happened AFTER this timestamp. Earlier messages MUST NOT be used as evidence.
+
+If no qualifying activity has occurred since the goal was set, the evaluator must return `{"ok": false, "reason": "Goal was just set; no work has been done yet against the new condition."}`.
+
+### History Sanitization for the Evaluator
+
+Before feeding history to the evaluator, we filter out the following extended item types (they are project-specific and unrecognized by the SDK):
+
+- `goal-result` / `goal-progress` (goal's own UI status items)
+- `summary` / `topic` / `ai-title` / `custom-title`
+- `file-history-snapshot`
+
+These items are neither user input nor assistant responses, have no value for the evaluator's judgment, and would trigger `Unknown item type` warnings from the SDK.
+
+---
+
+## Implementation Notes and Known Limitations
+
+The following table summarizes key behaviors and known limitations of the current implementation for debugging reference:
+
+| Behavior | Status | Notes |
+| :--- | :--- | :--- |
+| Set / replace / kick-off | ✅ | Immediately starts a turn after setting; auto-replaces when there's already an active goal |
+| `/goal clear` aliases | ✅ | Supports five single-token synonyms: stop / off / reset / none / cancel |
+| `/clear` also clears active goal | ✅ | Unregisters goal hook and cleans meta on session restart |
+| Condition limit | ✅ | 4000 characters |
+| Reason feedback into history | ✅ | Injection format: `Stop hook feedback: [<condition>]: <reason>` |
+| Three-state semantics (ok / not-yet / impossible) | ✅ | Immediately clears goal on unreachable, preventing infinite loops |
+| Evaluator uses small model | ✅ | Uses the model bound to `lite` slot (mapped per provider) |
+| `/goal` no-arg → status view | ✅ | TUI / Web UI panel + headless text fallback |
+| Persistent running indicator `⊚ /goal active (Xs)` | ✅ | Always visible at bottom-right of input box, 1Hz refresh |
+| `--resume` turn / timer / token reset | ❌ Pending | Currently carries over original createdAt / turnCount; use `/goal clear` + re-set to restart |
+
+---
+
+## See Also
+
+- [`/loop` for scheduled tasks](./scheduled-tasks.md#使用-loop-创建循环任务): Triggers repeatedly on a time interval, rather than until a condition is met
+- [Hooks Guide](./hooks-guide.md) / [Hooks Reference](./hooks.md): Understand the underlying mechanism of prompt-based Stop hooks; write your own when you need more complex evaluation logic
+- [Non-interactive (headless) mode](./headless.md): Run `/goal` in CI / scripts via `-p`
+- [Remote Control](./remote-control.md): Trigger goals in Web UI / WeChat channels
+- [Slash Commands Overview](./slash-commands.md): Index of all built-in slash commands

package/cli/dist/web-ui/docs/en/cli/hooks.md

@@ -142,11 +142,13 @@ Besides shell commands (`type: "command"`), CodeBuddy Code also supports prompt-
 
 > **Supported events**: Currently only `Stop`, `UserPromptSubmit`, and `PreToolUse` events are supported.
 
+> **Session-level shortcut**: The built-in slash command [`/goal`](./goal.md) is a ready-to-use wrapper around prompt-based Stop hooks — simply type `/goal <condition>` to have CodeBuddy keep working until the condition is met, without writing hook configuration manually. If your evaluation logic can be expressed as a condition string, prefer `/goal`; only fall back to writing your own prompt hook when you need more complex prompt orchestration or cross-event coordination.
+
 ### How Prompt Hooks Work
 
 Instead of running a bash command, the hook:
 
-1. Sends the hook input plus your prompt to a fast LLM (Haiku).
+1. Sends the hook input plus your prompt to a fast small model (bound to the `lite` slot, mapped per model provider).
 2. Receives a structured JSON decision.
 3. Lets CodeBuddy Code enforce that decision.
 
@@ -201,7 +203,8 @@ The LLM must return JSON:
 ```jsonc
 {
   "ok": true | false,
-  "reason": "Explanation for the decision"  // Required when ok is false
+  "reason": "Explanation for the decision",  // Required when ok is false
+  "impossible": false                          // Optional, only effective for Stop events
 }
 ```
 
@@ -209,6 +212,9 @@ The LLM must return JSON:
 
 - `ok`: `true` to allow the operation, `false` to block it
 - `reason`: Required when `ok` is `false`, explanation shown to CodeBuddy
+- `impossible`: Optional boolean, only meaningful for `Stop` hooks. `{ok: false, impossible: true}` indicates that the evaluator has determined "this goal is fundamentally impossible to achieve within the current session" (contradictory conditions, unavailable resources, or the model has exhausted all reasonable attempts). CodeBuddy will stop looping and the UI displays a "cannot be achieved" terminal state. A plain `{ok: false}` still means "not yet achieved, keep working".
+
+**`reason` injection into history semantics**: When a `Stop` hook returns `{ok: false}`, the `reason` text is not simply "shown to CodeBuddy" — it is injected as an internal user message with `isMeta=true` into the conversation history, so that the main model sees the evaluator's perspective in the next turn and can precisely address the outstanding gaps. This is the core mechanism that allows prompt-based Stop hooks to drive multi-turn iterative convergence (the `/goal` command relies on this pipeline under the hood).
 
 ### Example: Smart Stop Hook
 
@@ -360,6 +366,8 @@ Runs after the user submits a prompt but before CodeBuddy processes it. Useful f
 
 Runs when the primary CodeBuddy agent finishes responding (skipped if the user manually interrupts).
 
+> **Session-level shortcut**: The built-in slash command [`/goal`](./goal.md) is a wrapper around session-scoped prompt-based Stop hooks — `/goal <condition>` is all it takes to register a Stop hook that keeps CodeBuddy working until the condition is met, automatically handling three-state evaluation (achieved / not yet achieved, keep working / impossible to achieve), turn counting, token statistics, and `/resume` auto-recovery. When you need a session-level "keep working until X" behavior, prefer `/goal` instead of writing hook configuration manually.
+
 ### SubagentStop
 
 Runs when a CodeBuddy sub-agent (Task tool) finishes.

package/cli/dist/web-ui/docs/en/cli/monitoring.md

@@ -1,44 +1,117 @@
 # Monitoring CodeBuddy Code with OpenTelemetry
 
-CodeBuddy Code supports exporting internal traces to your own OpenTelemetry Collector via the standard OTLP protocol, making it easy to integrate with self-hosted observability platforms.
+CodeBuddy Code supports exporting traces to your own OpenTelemetry Collector via the standard OTLP protocol, making it easy to integrate with self-hosted observability platforms.
 
-> **MVP Scope**: Currently only **traces** (distributed tracing) are supported; custom export of metrics and logs is not yet available. Support will be expanded as needed.
+> **Current Scope**: Supports **traces** (distributed tracing) + 4 privacy opt-in switches. Custom export of metrics and logs is not yet supported.
 
-## How to Enable
-
-Once the enable switch is set, traces will be exported using OTel standard environment variables:
+## Quick Start
 
 ```bash
+# 1. Enable telemetry
 export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
-export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com
+
+# 2. Configure OTLP endpoint
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+# 3. (Optional) Enable privacy opt-in content recording
+export OTEL_LOG_USER_PROMPTS=1
+export OTEL_LOG_TOOL_DETAILS=1
+export OTEL_LOG_TOOL_CONTENT=1
+
+# 4. Run
 codebuddy
 ```
 
-> A legacy alias `CLAUDE_CODE_ENABLE_TELEMETRY` is also accepted for backward compatibility and is equivalent to `CODEBUDDY_CODE_ENABLE_TELEMETRY`.
+> Claude Code compatibility: `CLAUDE_CODE_ENABLE_TELEMETRY` is equivalent to `CODEBUDDY_CODE_ENABLE_TELEMETRY`.
 
-## Key Environment Variables
+## Configuration Variables
 
-For the full list, see [env-vars.md](env-vars.md#opentelemetry-custom-export-traces). Common ones:
+### Basic Configuration
 
-| Variable | Purpose |
-|----------|---------|
-| `CODEBUDDY_CODE_ENABLE_TELEMETRY=1` | Enable the OTel export switch |
-| `OTEL_TRACES_EXPORTER` | `otlp` (default) / `console` / `none` |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP Collector address; `/v1/traces` is appended automatically |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Full URL specific to traces; takes higher priority |
-| `OTEL_EXPORTER_OTLP_HEADERS` | Request headers `k1=v1,k2=v2`; values support URL encoding |
-| `OTEL_SERVICE_NAME` | Override the default `service.name` |
-| `OTEL_RESOURCE_ATTRIBUTES` | Additional resource attributes |
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `CODEBUDDY_CODE_ENABLE_TELEMETRY` | Enable OTel export (required) | `1` |
+| `OTEL_TRACES_EXPORTER` | Exporter type | `otlp` (default), `console`, `none` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP Collector address; `/v1/traces` is appended automatically | `http://localhost:4318` |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Full URL specific to traces; takes higher priority | `http://localhost:4318/v1/traces` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Request headers `k1=v1,k2=v2`; values support URL encoding | `Authorization=Bearer%20token` |
+| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | Transport protocol | `http/protobuf` (only supported) |
+| `OTEL_SERVICE_NAME` | Override the default `service.name` | `codebuddy-code` |
+| `OTEL_RESOURCE_ATTRIBUTES` | Additional resource attributes | `team=platform,env=prod` |
 
-## Protocol Support
+### Privacy Opt-in Switches
 
-Only **`http/protobuf`** (OTLP/HTTP + Protobuf encoding) is supported, consistent with the CodeBuddy Code default.
+Spans do not record any sensitive information by default (prompt content, tool parameters, tool output, etc.). You need to opt in progressively via the following environment variables:
+
+| Variable | Purpose | Recorded Content |
+|----------|---------|-----------------|
+| `OTEL_LOG_USER_PROMPTS=1` | Record user prompts | `user_prompt` attribute (not recorded by default; only `user_prompt_length` is recorded) |
+| `OTEL_LOG_TOOL_DETAILS=1` | Record tool parameters | `tool_input` attribute (~4KB truncation) + tool-specific attributes (`file.path`, `command`, etc.) |
+| `OTEL_LOG_TOOL_CONTENT=1` | Record full tool input/output | `tool_input`/`tool_result` span events (60KB truncation) |
+| `OTEL_LOG_RAW_API_BODIES=1` | Record full API request/response bodies | Reserved, not yet implemented |
+
+## Span Structure
+
+Each user prompt produces a `codebuddy_code.interaction` root span. Tool calls are recorded as child spans:
+
+```
+codebuddy_code.interaction
+├── codebuddy_code.tool (Read)
+├── codebuddy_code.tool (Bash)
+└── codebuddy_code.tool (Agent -> child agent tool spans)
+```
 
-Setting `OTEL_EXPORTER_OTLP_PROTOCOL=grpc` or `http/json` will be ignored with a warning logged, and will fall back to the default protobuf.
+### Span Attributes
+
+All spans include a `span.type` attribute to identify the type.
+
+**`codebuddy_code.interaction`**
+
+| Attribute | Description | Controlled By |
+|-----------|-------------|---------------|
+| `span.type` | Fixed value `"interaction"` | |
+| `conversation.id` | Conversation ID | |
+| `conversation.agent` | Agent name | |
+| `user_prompt` | User prompt content (not recorded when disabled) | `OTEL_LOG_USER_PROMPTS` |
+| `user_prompt_length` | Prompt length (always recorded) | |
+| `conversation.cancelled` | `true` when conversation is cancelled | |
+
+**`codebuddy_code.tool`**
+
+| Attribute | Description | Controlled By |
+|-----------|-------------|---------------|
+| `span.type` | Fixed value `"tool"` | |
+| `tool_name` | Tool name | |
+| `tool.call_id` | Tool call ID (always recorded) | |
+| `file.path` | File path (Read/Write/Edit) | `OTEL_LOG_TOOL_DETAILS` |
+| `command` | Bash command | `OTEL_LOG_TOOL_DETAILS` |
+| `command.timeout` | Command timeout (milliseconds) | `OTEL_LOG_TOOL_DETAILS` |
+| `glob.pattern` | Glob search pattern | `OTEL_LOG_TOOL_DETAILS` |
+| `grep.pattern` | Grep regex pattern | `OTEL_LOG_TOOL_DETAILS` |
+| `http.url` | WebFetch URL | `OTEL_LOG_TOOL_DETAILS` |
+| `search.query` | WebSearch query | `OTEL_LOG_TOOL_DETAILS` |
+| `agent.prompt` | Sub-agent prompt | `OTEL_LOG_TOOL_DETAILS` |
+| `agent.type` | Sub-agent type | `OTEL_LOG_TOOL_DETAILS` |
+| `mcp.server` | MCP server name | `OTEL_LOG_TOOL_DETAILS` |
+| `mcp.tool` | MCP tool name | `OTEL_LOG_TOOL_DETAILS` |
+| `tool_input` | Tool input JSON (~4KB truncation) | `OTEL_LOG_TOOL_DETAILS` |
+| `tool_input_truncated` | Whether input was truncated | `OTEL_LOG_TOOL_DETAILS` |
+| `tool_input_original_length` | Original length before truncation | `OTEL_LOG_TOOL_DETAILS` |
+
+**`codebuddy_code.tool` span events** (requires `OTEL_LOG_TOOL_CONTENT=1`)
+
+| Event Name | Attribute | Description |
+|------------|-----------|-------------|
+| `tool_input` | `content` | Full tool input (60KB truncation) |
+| `tool_input` | `content_truncated` | Whether truncated |
+| `tool_input` | `content_original_length` | Length before truncation |
+| `tool_result` | `content` | Full tool output (60KB truncation) |
+| `tool_result` | `content_truncated` | Whether truncated |
+| `tool_result` | `content_original_length` | Length before truncation |
 
 ## Typical Scenarios
 
-### 1. Export to a Self-Hosted Enterprise Collector
+### Export to a Self-Hosted Enterprise Collector
 
 ```bash
 export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
@@ -48,16 +121,17 @@ export OTEL_SERVICE_NAME=codebuddy-code
 export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,team=copilot
 ```
 
-### 2. Local Debug Trace Output
-
-For debugging, send traces directly to stdout:
+### Local Debugging (Console Output)
 
 ```bash
 export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
 export OTEL_TRACES_EXPORTER=console
+export OTEL_LOG_USER_PROMPTS=1
+export OTEL_LOG_TOOL_DETAILS=1
+export OTEL_LOG_TOOL_CONTENT=1
 ```
 
-### 3. Temporarily Disable
+### Disable Telemetry
 
 ```bash
 export OTEL_TRACES_EXPORTER=none
@@ -68,15 +142,25 @@ export DISABLE_TELEMETRY=1
 ## Priority and Fallback
 
 1. `DISABLE_TELEMETRY=1` has the highest priority and disables all telemetry.
-2. Enable evaluation: enabled in the built-in product configuration **or** `CODEBUDDY_CODE_ENABLE_TELEMETRY` (or its legacy alias `CLAUDE_CODE_ENABLE_TELEMETRY`) is set to a truthy value (`1` / `true` / `yes` / `on`).
+2. Enable evaluation: enabled in the built-in product configuration **or** `CODEBUDDY_CODE_ENABLE_TELEMETRY` / `CLAUDE_CODE_ENABLE_TELEMETRY` is set to a truthy value (`1` / `true` / `yes` / `on`).
 3. Endpoint priority: `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` > `OTEL_EXPORTER_OTLP_ENDPOINT` > `telemetry.tracing.url` in the built-in product configuration.
 4. Headers: env and product configuration are merged; env keys with the same name override product configuration.
 
-## FAQ
+## Protocol Support
+
+Only **`http/protobuf`** (OTLP/HTTP + Protobuf encoding) is supported, consistent with the Claude Code default.
 
-### Will prompts or code content be written into traces?
+Setting `OTEL_EXPORTER_OTLP_PROTOCOL=grpc` or `http/json` will be ignored with a warning logged, falling back to the default protobuf.
 
-No. CodeBuddy Code traces only record structured metrics such as tool calls, model calls, and durations. They do not contain user conversation content or source code. If you need to record code snippets, you must separately enable the standard reporting channel (which is outside the scope of this feature).
+## Security and Privacy
+
+- Spans only record tool names and call IDs by default, **excluding** user prompts, tool parameters, file content, or source code
+- `user_prompt_length` is always recorded (length only); prompt text requires `OTEL_LOG_USER_PROMPTS=1` to be written
+- Tool parameters (file paths, commands, etc.) require `OTEL_LOG_TOOL_DETAILS=1`; individual values exceeding 512 characters are truncated, with a total limit of ~4KB
+- Full tool input/output requires `OTEL_LOG_TOOL_CONTENT=1`, recorded via span events, truncated at 60KB
+- All opt-in switches are disabled by default; enterprise administrators can configure them uniformly via managed settings
+
+## FAQ
 
 ### Does it conflict with the internal enterprise reporting channel?
 
@@ -85,3 +169,7 @@ No conflict. OTel custom export and the built-in standard reporting (`telemetry.
 ### Is metrics / logs supported?
 
 Not yet supported, but planned. If you have a strong need, please provide feedback on the corresponding Issue.
+
+### Is it compatible with Claude Code's OTEL format?
+
+Yes. Span naming, attribute naming, and truncation strategies are aligned with Claude Code's conventions (`{product}.interaction` / `{product}.tool`), ensuring upstream analysis platforms can process them uniformly.

package/cli/dist/web-ui/docs/en/cli/release-notes/README.md

@@ -17,6 +17,9 @@ Difference from CHANGELOG.md:
 
 <!-- New versions are automatically added here -->
 
+- [v2.99.0](./v2.99.0.md) - 2026-05-27
+- [v2.98.1](./v2.98.1.md) - 2026-05-25
+- [v2.98.0](./v2.98.0.md) - 2026-05-24
 - [v2.97.5](./v2.97.5.md) - 2026-05-22
 - [v2.97.4](./v2.97.4.md) - 2026-05-21
 - [v2.97.3](./v2.97.3.md) - 2026-05-19

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.98.0.md

@@ -0,0 +1,48 @@
+# 🚀 CodeBuddy Code v2.98.0 Release
+
+## 📦 Version Info
+
+| Component | Version |
+|------|------|
+| CodeBuddy Code CLI | v2.98.0 |
+| Agent SDK JS | v0.3.156 |
+| Agent SDK Python | v0.3.155 |
+
+## ✨ New Features
+
+### OpenTelemetry Custom Reporting (Traces)
+
+Support exporting internal traces to your own Collector via standard OTel environment variables, enabling integration with enterprise observability platforms:
+
+```bash
+export CODEBUDDY_CODE_ENABLE_TELEMETRY=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.corp.example.com
+export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<TOKEN>
+```
+
+Supports standard variables such as `OTEL_TRACES_EXPORTER` / `OTEL_SERVICE_NAME` / `OTEL_RESOURCE_ATTRIBUTES`. See `docs/monitoring.md` for details.
+
+### Sandbox Ecosystem Asset Directory Allowlist
+
+The sandbox security policy now allows write access to WorkBuddy ecosystem asset directories and cross-platform skill directories by default, reducing access restriction issues for plugins, skills, and connectors in sandbox environments.
+
+## 🔧 Improvements
+
+- **Auto-compact window increase**: For models without `maxInputTokens` configured, the default auto-compact window has been raised from 100k to 200k tokens
+- **Hooks inject agent_id / agent_type**: All hook event payloads now include trigger source identifiers, making it easier to distinguish between main sessions and sub-agents in global hooks
+- **Hook deduplication refinement**: Resolved "same event triggered twice" issue — same command across settings scopes is collapsed into one, while different plugin/sub-agent scopes each retain their own copy
+- **Multi-source hook hit observability**: When a single event matches ≥ 2 different hooks, logs now list all matched commands for easier conflict debugging
+- **CLI documentation updates**: Added `monitoring.md` and `codebuddy-dir.md`, completed v2.96.1 ~ v2.97.5 release notes bilingual sync and navigation updates
+
+## 🐛 Bug Fixes
+
+- **Background Bash zombie processes**: Fixed zombie processes left by background commands like `nohup`. stdout/stderr now write directly to file descriptors; added 50MB output watchdog (`CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTES` configurable) and `CODEBUDDY_BASH_BG_PIPE_MODE=1` rollback switch
+- **Official Copilot gateway retains thinking field**: Fixed an issue where the thinking field was prematurely cleared when requests with `auto` model thinking enabled were sent to the official gateway
+- **Compact type passthrough**: Fixed an issue where auto-compact and manual `/compact` could not be distinguished in ACP `_meta`
+- **Process termination reliability**: Fixed issues where `kill()` was blocked by `_disposed` flag after `dispose()`, and `disposeAll()` exit event routing was lost
+
+## 📝 Documentation Updates
+
+- **CLI Monitoring Documentation**: Added `monitoring.md` covering OpenTelemetry custom reporting
+- **Directory Structure Guide**: Added `codebuddy-dir.md` explaining `~/.codebuddy/` and `.codebuddy/` directory structure, configuration priority, and memory loading order
+- **Release Notes Index**: Added bilingual release notes for 7 versions from v2.96.1 ~ v2.97.5

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.98.1.md

@@ -0,0 +1,19 @@
+# 🚀 CodeBuddy Code v2.98.1 Release
+
+## 📦 Version Info
+
+| Component | Version |
+|------|------|
+| CodeBuddy Code CLI | v2.98.1 |
+| Agent SDK JS | v0.3.157 |
+| Agent SDK Python | v0.3.156 |
+
+## 📌 Overview
+
+v2.98.0 failed to publish to npm due to an OOM issue in the release pipeline. This version is a re-release as v2.98.1. **It is functionally identical to v2.98.0** — all new features, improvements, and fixes from v2.98.0 are included in this version. If you previously attempted to install v2.98.0 and it failed, please upgrade directly to v2.98.1.
+
+For full change details, refer to the [v2.98.0 Release Notes](./v2.98.0.md).
+
+## 🐛 Bug Fixes
+
+- **Fix agent-cli release pipeline OOM**: Increased the Node heap memory limit to 8GB during the release build stage, resolving the issue where v2.98.0 was terminated by the OOM Killer during `yarn build`, preventing the npm package from being published, and ensuring stable publishing for subsequent versions.

package/cli/dist/web-ui/docs/en/cli/release-notes/v2.99.0.md

@@ -0,0 +1,39 @@
+# 🚀 CodeBuddy Code v2.99.0 Release
+
+## 📦 Version Information
+
+| Component | Version |
+|-----------|---------|
+| CodeBuddy Code CLI | v2.99.0 |
+| Agent SDK JS | v0.3.158 |
+| Agent SDK Python | v0.3.157 |
+
+## ✨ New Features
+
+### `/goal` Command: Keep CodeBuddy Working Until Goal is Achieved
+
+New `/goal` slash command that lets you set a completion condition, after which CodeBuddy will continue working across multiple turns until the condition is met:
+
+- `/goal all tests pass` — At the end of each turn, a lightweight model evaluator checks whether the condition is met; if not, it automatically continues
+- `/goal` — View current goal status (elapsed time, turn count, token consumption)
+- `/goal clear` — End the goal early
+
+Supports tri-state evaluation: achieved (stop), not achieved (continue working), unachievable (avoid infinite loops). Goals are automatically reloaded when resuming a session via `/resume`. Web UI supports progress bars and terminal state overlays.
+
+### Credit Consumption Push
+
+Attaches `usage` details with a `credit` field to the standard ACP `usage_update`, enabling upstream systems to accumulate and display consumed Credits per turn.
+
+### Gemini-3.5-Flash Model
+
+Added Gemini-3.5-Flash model support with million-token context window, balanced reasoning capabilities, suitable for everyday use.
+
+## 🐛 Bug Fixes
+
+- **Security Fix (RCE)**: Fixed a remote code execution vulnerability where `apiKeyHelper` configuration was executed before the directory trust dialog appeared; project-scoped configurations now must wait for directory trust completion before execution
+- **Hook Input Fix**: `agent_type` now correctly reflects the configured agent name; SubagentStop's `agent_transcript_path` now points to the correct path
+- **Plan Mode Permission Restore**: Fixed an issue where ExitPlanMode incorrectly downgraded permissions when the session had already exited Plan Mode
+- **Team Task Stop Reliability**: Fixed occasional inability to stop members immediately after startup, and members still showing as running after being force-terminated
+- **Plugin Hot-Watch Infinite Loop**: Fixed an infinite loop issue with change events in PluginsProductProvider
+- **Multi-line Input Arrow Keys**: Fixed down arrow key being intercepted by shortcuts after multi-line input while background tasks are running
+- **Custom Model Tool Call**: Added `SkipToolCallSupportCheck` switch; dedicated editions no longer remove tools/tool_choice fields

package/cli/dist/web-ui/docs/en/cli/slash-commands.md

@@ -30,6 +30,7 @@ These commands are used to manage your CodeBuddy Code sessions. Here is the curr
 | `/model:image-to-image` | `[list \| model-id]` | ✅ Supported | Switch or view the currently used image-to-image model. Opens an interactive selection interface when used without parameters, `list` lists available models, or directly switches to the specified model when provided with a model ID. |
 | `/permissions` | | ✅ Supported | Manage tool permissions and workspace directory access permissions. |
 | `/plan` | | ✅ Supported | Preview the plan file content in the current plan mode. |
+| `/goal` | `<condition> \| clear` | ✅ Supported | Keep working until a condition is met. `/goal <condition>` sets a goal condition (e.g., `/goal all tests pass`), registering a session-level prompt-based Stop hook. Each time the model wants to stop, a small-model evaluator checks whether the condition is satisfied; if not, it injects the reason into history so the model continues working. `/goal` without arguments opens the recap panel. `/goal clear` (aliases: `stop` / `off` / `reset` / `none` / `cancel`) ends the goal early. See [Goal Documentation](./goal.md). |
 | `/upgrade` | | ✅ Supported | Open the upgrade page in your browser to view premium features and subscription options. |
 | `/bashes` | | ✅ Supported | List and manage background tasks. |
 | `/terminal-setup` | | ✅ Supported | Configure Shift+Enter keyboard shortcut binding for inserting line breaks in the input box. |