@tencent-ai/agent-sdk 0.3.155 → 0.3.158

package/cli/dist/web-ui/docs/en/cli/codebuddy-dir.md

@@ -0,0 +1,309 @@
+# .codebuddy Directory Structure
+
+> A deep dive into the files and subdirectories under CodeBuddy Code's configuration directory `~/.codebuddy` and the project-level `.codebuddy` directory.
+
+CodeBuddy Code uses two configuration directories:
+
+- **Global directory** `~/.codebuddy/`: stores user-level configuration, history, runtime data, etc., affecting all projects
+- **Project directory** `.codebuddy/` (located at the project root): stores project-level configuration, rules, skills, commands, etc., shared with the team via version control
+
+
+### User-Level Extension Directories
+
+#### `agents/`
+
+Stores user-level custom sub-agents that take effect across all projects. Each agent is a single `.md` file:
+
+```
+~/.codebuddy/agents/
+├── code-reviewer.md      # Code review agent
+└── translator.md         # Translation agent
+```
+
+File format (YAML frontmatter + system prompt):
+
+```markdown
+---
+name: code-reviewer
+description: Code review expert; use proactively after writing code
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are a senior code reviewer focused on code quality, security, and best practices...
+```
+
+See [Sub-Agent Documentation](sub-agents.md) for details.
+
+#### `rules/`
+
+Stores user-level rule files that take effect across all projects. All `.md` files are loaded automatically; subdirectories are supported:
+
+```
+~/.codebuddy/rules/
+├── preferences.md        # Personal coding preferences
+└── workflows.md          # Common workflow conventions
+```
+
+Rule files support frontmatter to control loading behavior:
+
+```markdown
+---
+alwaysApply: false
+paths: src/**/*.ts
+---
+
+# TypeScript Conventions
+
+- Prefer `interface` over `type`
+- Disallow `any`
+```
+
+See [Memory Management - Rule System](memory.md#using-codebuddyrules-for-modular-rules) for details.
+
+#### `skills/`
+
+Stores user-level skills that take effect across all projects. Each skill is a self-contained directory containing a `SKILL.md`:
+
+```
+~/.codebuddy/skills/
+└── pdf/
+    └── SKILL.md
+```
+
+See [Skills Documentation](skills.md) for details.
+
+---
+
+### Runtime Data Directories
+
+These directories are maintained automatically by CodeBuddy Code and typically do not require manual operation:
+
+| Directory | Description |
+|------|------|
+| `projects/` | Per-project runtime data, including session records (`.jsonl`) and sub-agent tool output (`tool-results/`) |
+| `sessions/` | Active session data |
+| `plans/` | Plan files generated in plan mode |
+| `logs/` | Runtime logs grouped by date and process |
+| `traces/` | OpenTelemetry execution trace data |
+| `file-history/` | Snapshots of files operated on within each session, used by `/rewind` |
+| `history.jsonl` | Global conversation history (used by `/resume`) |
+| `blobs/` | Binary resources such as images and screenshots, stored by content hash |
+| `tasks/` | Task management system data (TaskCreate/TaskUpdate) |
+| `teams/` | Agent team (TeamCreate) runtime data |
+| `shell-snapshots/` | Bash sandbox startup snapshots that speed up sandbox creation |
+| `plugins/` | File contents of installed plugins |
+| `local_storage/` | CLI internal key-value persistent storage (`.info` files named by content hash) |
+
+---
+
+## Project Directory `.codebuddy/`
+
+Located at the project root and intended to be committed to version control so the team can share it:
+
+```
+.codebuddy/
+├── settings.json              # Project shared configuration
+├── settings.local.json        # Local personal configuration (auto-ignored by .gitignore)
+├── CODEBUDDY.md               # Project-level memory file
+│
+├── agents/                    # Project-level custom sub-agents
+├── rules/                     # Project-level rule files
+├── skills/                    # Project-level skills
+├── commands/                  # Custom slash commands
+```
+
+### Configuration Files
+
+#### `settings.json`
+
+Project shared configuration synced with the team via version control. Suitable for setting team-wide model, permission rules, plugins, and so on:
+
+```json
+{
+  "permissions": {
+    "allow": ["Read", "Edit", "Bash(git:*)", "Bash(npm:*)"],
+    "deny": ["Read(./.env)", "Read(./secrets/**)"]
+  },
+  "enabledPlugins": {
+    "pr-review-toolkit@company-tools": true
+  },
+  "extraKnownMarketplaces": {
+    "company-tools": {
+      "source": {
+        "source": "github",
+        "repo": "myorg/codebuddy-plugins"
+      }
+    }
+  }
+}
+```
+
+#### `settings.local.json`
+
+Local personal configuration. CodeBuddy Code automatically adds it to `.gitignore`. Suitable for personal overrides (such as local debug ports or personal keys) that should not affect other team members.
+
+#### `CODEBUDDY.md`
+
+Project-level memory file shared via version control. Stores team knowledge such as project architecture, conventions, and common commands:
+
+```markdown
+# Project Overview
+
+This project is a TypeScript monorepo (Yarn workspaces).
+
+## Common Commands
+
+- `yarn build` — build all packages
+- `yarn test` — run all tests
+
+## Architectural Conventions
+
+- Uses the CellJS dependency injection framework
+- Protocol definitions live in `*-protocol.ts` files
+```
+
+> **Tip**: You can also place the memory file at the project root as `CODEBUDDY.md` (outside the `.codebuddy/` directory). Both locations are equivalent.
+
+---
+
+### Project-Level Extension Directories
+
+#### `agents/`
+
+Stores project-specific sub-agents, which take precedence over user-level agents. When names collide, the project-level agent overrides the user-level one.
+
+```
+.codebuddy/agents/
+├── blog-translator.md     # Blog translation agent
+└── docs-reviewer.md       # Documentation review agent
+```
+
+#### `rules/`
+
+Stores project-level rules shared via version control. Suitable for team-wide code conventions, workflow agreements, etc. Subdirectories are supported:
+
+```
+.codebuddy/rules/
+├── code-style.md          # Code style conventions
+├── testing.md             # Testing conventions
+├── security.md            # Security requirements
+└── frontend/
+    ├── react.md           # React component conventions
+    └── styles.md          # Styling conventions
+```
+
+All `.md` files are recursively loaded automatically.
+
+#### `skills/`
+
+Stores project-level skills. Each skill is its own directory containing a `SKILL.md` and optional supporting files:
+
+```
+.codebuddy/skills/
+├── case-executor/
+│   ├── SKILL.md           # Skill definition
+│   ├── scripts/           # Helper scripts
+│   └── references/        # Reference materials
+└── cnb-api/
+    └── SKILL.md
+```
+
+`SKILL.md` format:
+
+```markdown
+---
+name: case-executor
+description: Executes JSON test cases and generates reports
+allowed-tools: Read, Write, Bash
+---
+
+You are a test execution expert responsible for running UI test cases in JSON format...
+```
+
+See [Skills Documentation](skills.md) for details.
+
+#### `commands/`
+
+Stores custom slash commands invoked via `/command-name`. Nested directories are supported (invoked using `/group:command`):
+
+```
+.codebuddy/commands/
+├── deploy.md              # /deploy command
+├── team/
+│   ├── issue-start.md     # /team:issue-start command
+│   └── create-issue.md    # /team:create-issue command
+└── openspec/
+    └── propose.md         # /openspec:propose command
+```
+
+Command file format:
+
+```markdown
+---
+description: Create a new Issue
+argument-hint: "<description> ; <type> ; <product>"
+allowed-tools: Bash
+---
+
+Create an Issue based on the following description: $ARGUMENTS
+```
+
+See [Slash Command Documentation](slash-commands.md) for details.
+
+---
+
+## Configuration Priority
+
+Multi-layer configuration is applied with the following priority (higher priority overrides lower priority):
+
+```
+Command-line arguments              (highest priority)
+    ↓
+.codebuddy/settings.local.json    (project local, not committed)
+    ↓
+.codebuddy/settings.json          (project shared, team-wide)
+    ↓
+~/.codebuddy/settings.json        (user global, personal preferences)
+    ↓
+Built-in product defaults           (lowest priority)
+```
+
+Priority for agents/skills/rules: **project-level > user-level > plugin-level**. When names collide, the project level wins.
+
+## Memory Loading Order
+
+```
+1. User-level memory: ~/.codebuddy/CODEBUDDY.md
+2. User-level rules: ~/.codebuddy/rules/*.md (recursive)
+3. Project-level memory: CODEBUDDY.md (searched recursively upward from cwd)
+4. Project-level rules: .codebuddy/rules/*.md (cwd only, no upward search)
+5. Project local memory: CODEBUDDY.local.md
+6. Subdirectory memory: dynamically loaded `CODEBUDDY.md` from a subdirectory when tools operate on files there
+```
+
+## Version Control Recommendations
+
+| File / Directory | Commit to VCS | Notes |
+|-----------|:---:|------|
+| `.codebuddy/settings.json` | ✅ Recommended | Team shared configuration |
+| `.codebuddy/settings.local.json` | ❌ Do not commit | Auto-added to .gitignore |
+| `CODEBUDDY.md` / `.codebuddy/CODEBUDDY.md` | ✅ Recommended | Team shared knowledge |
+| `CODEBUDDY.local.md` | ❌ Do not commit | Auto-added to .gitignore |
+| `.codebuddy/agents/` | ✅ Recommended | Team shared sub-agents |
+| `.codebuddy/rules/` | ✅ Recommended | Team shared rules |
+| `.codebuddy/skills/` | ✅ Recommended | Team shared skills |
+| `.codebuddy/commands/` | ✅ Recommended | Team shared commands |
+
+## Related Resources
+
+- [Settings](settings.md) — Complete configuration field reference
+- [Memory Management](memory.md) — Detailed guide to CODEBUDDY.md and the rule system
+- [Sub-Agents](sub-agents.md) — Create and use custom sub-agents
+- [Skills Documentation](skills.md) — In-depth guide to the skill system
+- [Slash Commands](slash-commands.md) — Custom command reference
+- [MCP Documentation](mcp.md) — MCP server configuration
+
+---
+
+*Use the `.codebuddy` directory wisely to help CodeBuddy Code better understand your project and team conventions.*

package/cli/dist/web-ui/docs/en/cli/env-vars.md

@@ -39,8 +39,10 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands (default: 120000) |
 | `BASH_MAX_OUTPUT_LENGTH` | Maximum characters of bash output retained in memory (default: 30000, max: 150000). Content exceeding the limit is mid-truncated (keeping head 20% + tail 80%), and the full output is automatically saved to disk |
 | `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands (default: 600000) |
-| `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | Main conversation response budget (milliseconds, default `0`=off). When set to `>0`, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. Aligns with Claude Code's `ASSISTANT_BLOCKING_BUDGET_MS` (CC's official default value `15000`) |
+| `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | Main conversation response budget (milliseconds, default `0`=off). When set to `>0`, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. Aligns with CodeBuddy Code's `ASSISTANT_BLOCKING_BUDGET_MS` (the official default value is `15000`) |
 | `CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED` | Set to `1` to disable timeout auto-backgrounding; foreground commands fall back to the old SIGTERM/kill hard-kill behavior on timeout. Only used for debugging or temporary rollback when encountering regressions; keep the default (unset) in normal scenarios |
+| `CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTES` | Total byte limit for the on-disk file of stdout+stderr for background bash tasks (default `52428800` = 50MB). When exceeded, the size watchdog fires `SIGKILL` and marks the task as `killed`, with a notice injected at the end of stderr. CodeBuddy Code in `ShellCommand.ts` hardcodes the equivalent threshold as a constant; here it is exposed as an env var for operators to tune. Only effective in file fd mode (in pipe mode, child process output is not persisted to disk) |
+| `CODEBUDDY_BASH_BG_PIPE_MODE` | Set to `1` to force background tasks back to pipe mode (not using file fds), for rollback or debugging. The default (unset) uses file fd mode, which solves the zombie process issue caused by grandchild processes (e.g., spawned via `nohup`) holding parent pipe fds; the sandbox path automatically falls back to pipe and does not require explicit setting. There is no equivalent toggle elsewhere; this is a CodeBuddy Code fallback to remain compatible with legacy sandbox/PTY paths |
 
 ## Tool Output Externalization
 
@@ -64,6 +66,7 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `CODEBUDDY_DEFER_TOOL_LOADING` | Set to `false` or `0` to disable MCP tool deferred loading |
 | `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | Set to `true` or `1` to show full descriptions for all deferred tools |
 | `CODEBUDDY_DISABLE_CRON` | Set to `1` to disable scheduled tasks |
+| `CODEBUDDY_DISABLE_FORK_SUBAGENT` | Set to `1` to disable the Agent tool's fork sub-agent mode (`subagent_type="fork"`). When enabled, the fork-mode section is automatically hidden from the Agent tool description, so the model will not see this feature; if the model still passes `subagent_type="fork"`, the runtime falls back to a custom agent named `fork` (e.g., one defined by the user at `.codebuddy/agents/fork.md`), or otherwise rewrites it to a `general-purpose` regular sub-agent. Useful for host scenarios that need to avoid request amplification caused by recursive fork spawning |
 | `CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFS` | Set to `true` to rehydrate image blob references to full base64 data in `-p` mode streaming output. Useful for downstream integrations that need direct access to image data |
 
 ## Context and Memory
@@ -145,6 +148,24 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `DISABLE_AUTOUPDATER` | Set to `1` to disable auto-updates |
 | `DISABLE_FEEDBACK_COMMAND` | Set to `1` to disable the `/feedback` command |
 
+### OpenTelemetry Custom Reporting (traces)
+
+CodeBuddy Code supports reporting internal traces to your own Collector via the OTLP protocol. Environment variables follow the [OpenTelemetry specification](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). For detailed usage, see [Monitoring](monitoring.md).
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CODE_ENABLE_TELEMETRY` | Set to `1` to enable OTel custom reporting; the legacy alias `CLAUDE_CODE_ENABLE_TELEMETRY` is also accepted for backward compatibility |
+| `OTEL_TRACES_EXPORTER` | `otlp` (default) / `console` (output to logs, useful for debugging) / `none` (off) |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Generic OTLP endpoint; the tool automatically appends `/v1/traces` |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Traces-specific endpoint, used as a complete URL; takes priority over the generic variable |
+| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP request headers in the format `k1=v1,k2=v2`; values support URL encoding |
+| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Traces-specific request headers; takes priority over the generic variable |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | Only `http/protobuf` (default) is supported; other values (such as `grpc`, `http/json`) fall back and emit a warning |
+| `OTEL_SERVICE_NAME` | Override the default `service.name` |
+| `OTEL_RESOURCE_ATTRIBUTES` | Resource attributes in the format `k1=v1,k2=v2`; merged into the trace resource |
+
+> When `DISABLE_TELEMETRY=1`, OTel reporting is turned off regardless of the variables above.
+
 ## Tasks and Background Work
 
 | Environment Variable | Description |
@@ -257,7 +278,7 @@ codebuddy --model your-model-name
 
 #### Connecting to DeepSeek Example
 
-To connect to any third-party model service compatible with the Anthropic protocol (such as DeepSeek), you only need to configure the Base URL, API Key, and model variables — no additional `models.json` modifications are required:
+To connect to any third-party model service compatible with the protocol (such as DeepSeek), you only need to configure the Base URL, API Key, and model variables — no additional `models.json` modifications are required:
 
 ```bash
 # Endpoint and key

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/http-api.md

@@ -287,6 +287,7 @@ Aligned with E2B process.proto, mapping gRPC methods to REST endpoints:
 | GET | `/api/v1/plugins/marketplaces` | List configured plugin marketplaces |
 | POST | `/api/v1/plugins/marketplaces` | Add plugin marketplace |
 | POST | `/api/v1/plugins/marketplaces/browse` | Browse available plugins in marketplace |
+| POST | `/api/v1/plugins/marketplaces/update` | Update marketplace (sync remote repository content) |
 | DELETE | `/api/v1/plugins/marketplaces/:name` | Delete plugin marketplace |
 
 ### Settings Management
@@ -547,6 +548,11 @@ curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/browse \
   -H "Content-Type: application/json" \
   -d '{"marketplace": "my-marketplace"}'
 
+# Update marketplace (actually pulls latest content from remote)
+curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/update \
+  -H "Content-Type: application/json" \
+  -d '{"marketplace": "my-marketplace"}'
+
 # Delete plugin marketplace
 curl -X DELETE http://127.0.0.1:8080/api/v1/plugins/marketplaces/my-marketplace
 ```

package/cli/dist/web-ui/docs/en/cli/ide-integrations.md

@@ -42,7 +42,8 @@ Behavior description:
 
 - CodeBuddy will scan lock files created by IDE plugins in the current user directory to detect available IDE instances
 - Only considers an IDE as "valid" if its workspace contains the current directory
-- Prioritizes connecting to IDEs whose "workspace matches and process chain is upstream of the current terminal"
+- Auto-connection only happens when **exactly one** valid IDE matches the current working directory; if zero or multiple match, auto-connection is silently skipped, and you can use `/ide` to manually select
+- Stale lock files for IDE processes that have already exited are cleaned up before detection, avoiding connections to invalid ports
 - After successful connection, the CLI will obtain from the IDE MCP server:
   - File/diff preview (openFile / openDiff)
   - Diagnostic information (getDiagnostics)