@tencent-ai/agent-sdk 0.3.169 → 0.3.171

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

@@ -0,0 +1,380 @@
+# Permission Rules (Permissions)
+
+> Precisely constrain what CodeBuddy Code can do with fine-grained allow / ask / deny rules, Permission Modes, and layered settings. Rules can be committed to the repository and shared with the team, or overridden locally by developers.
+
+## Permission System Overview
+
+CodeBuddy Code uses a layered evaluation mechanism to balance capability and security. Before the main agent executes any tool call, it passes through the permission service (`tool-permission-service.ts::checkToolPermission`). Eight phases are evaluated in order:
+
+| Phase | Check | Behavior on match |
+| :---- | :---- | :---------------- |
+| 1 | **Deny rules** | Reject immediately, with the highest priority |
+| 2 | **Trusted Allow rules** (user / cli / flag / session / policy / project under a trusted directory / `--allowedTools`) | Allow immediately, and **can bypass command safety checks** |
+| 3 | **Command safety check** (`checkCommandSafety`, interactive only) | Force confirmation for high-risk / dangerous commands |
+| 4 | **Ask rules** | Force confirmation |
+| 5 | **Bypass mode short-circuit** | Allow directly in `bypassPermissions` mode; downgrade to default when `disableBypassPermissionsMode` is enabled |
+| 6 | **Untrusted Allow rules** (project / local outside trusted directories, plus command / sandbox sources) | Allow, but **cannot bypass command safety checks** |
+| 7 | **Permission Mode strategy** (`tool-permission-strategy.ts`) | Decide whether approval is required based on the current [PermissionMode](permission-modes.md) |
+| 8 | dontAsk / async agent fallback | Convert `ask` to `deny` in print / async agent scenarios to avoid deadlock |
+
+> **Key point**: deny always takes precedence, and allow is split into two layers: "trusted" and "untrusted". Before the project root is listed as a trusted directory, allow rules in `.codebuddy/settings.json` **cannot bypass the command safety gate**. This differs from cc and is designed to prevent malicious repositories from bypassing local safety protections by pushing their own settings into team PRs.
+
+Read-only tools (Read / Grep / Glob, etc.) do not prompt for approval by default inside trusted directories. Editing tools and Bash always go through the full phase chain. See `tool-permission-strategy.ts::ToolPermissionDefaultStrategy` and `permission-utils.ts::isArgsInTrustedDirectories` for details.
+
+## Three Rule Behaviors
+
+The three arrays under the `permissions` object correspond to three behaviors:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm test)", "Read(/tmp/data/**)"],
+    "ask":   ["WebFetch"],
+    "deny":  ["Bash(rm -rf *)", "Edit(.git/**)"]
+  }
+}
+```
+
+- **`allow`**: CodeBuddy can use it without asking for approval
+- **`ask`**: Ask for approval every time it is used
+- **`deny`**: Never allow it to be used
+
+## Where to Manage Rules
+
+### `/permissions` command
+
+Enter `/permissions` in a session to open the permission management panel (implemented in `permissions-command-executor.ts`). You can view all current allow / ask / deny rules, which settings layer they come from, and temporarily add or remove them (written to the user, project, or project-local scope).
+
+When **"Yes, don't ask again"** is selected in the dialog, CodeBuddy writes the most stable prefix for the current command into the `allow` array of the corresponding scope's settings.
+
+### CLI Startup Arguments
+
+| Argument | Purpose |
+| :------- | :------ |
+| `--allowedTools <tools...>` | Process-level temporary allow rules. Separated by spaces or commas. Example: `--allowedTools "Bash(git:*) Edit"` |
+| `--disallowedTools <tools...>` | Process-level temporary deny rules. Same as above |
+| `--add-dir <path>` | Add an extra directory to the trusted directory scope (affects whether Read requires confirmation) |
+| `-y` / `--dangerously-skip-permissions` | Equivalent to `--permission-mode bypassPermissions` |
+
+Definitions are in `cli-provider.ts:40-55`.
+
+### Configuration Files
+
+See [Settings Configuration](settings.md) for details. CodeBuddy merges these four scopes:
+
+| Scope | Path |
+| :---- | :--- |
+| user | `~/.codebuddy/settings.json` |
+| project | `<repo>/.codebuddy/settings.json` (committed to git) |
+| project-local | `<repo>/.codebuddy/settings.local.json` (not committed to git, local override) |
+| cliArg / flagSettings / session / policySettings | Process state, not persisted to disk |
+
+See `tool-permission-service.ts:647-741` for the merge implementation.
+
+## Rule Syntax
+
+Rule form: `Tool` or `Tool(specifier)`.
+
+### Match an Entire Tool
+
+Remove the parentheses to match all calls to a tool:
+
+| Rule | Meaning |
+| :--- | :------ |
+| `Bash` | All Bash commands |
+| `WebFetch` | All web fetches |
+| `Read` | All file reads |
+| `Edit` | All file edits |
+
+`*` can also be used as a standalone rule (`permission-utils.ts:194` treats it as a full-match wildcard).
+
+### Add a Specifier for Fine-Grained Matching
+
+Write arguments inside the parentheses:
+
+| Rule | Matches |
+| :--- | :------ |
+| `Bash(npm run build)` | Exact match for `npm run build` |
+| `Bash(npm:*)` or `Bash(npm *)` | All commands starting with `npm` |
+| `Read(./.env)` | `.env` in the current directory |
+| `Edit(/src/**/*.ts)` | `src/**/*.ts` under the project root |
+| `Read(~/.zshrc)` | `.zshrc` in the user's home directory |
+| `Read(//tmp/scratch.txt)` | Absolute filesystem path `/tmp/scratch.txt` |
+| `WebFetch(domain:example.com)` | Fetch example.com |
+| `mcp__puppeteer__navigate` | The navigate tool of the MCP puppeteer service |
+| `Agent(Explore)` | The Explore subagent |
+
+## Tool-Specific Rules
+
+### Bash
+
+Bash rules support three syntax forms (implemented in `permission-utils.ts::matchSingleCommandAgainstPattern`, lines `414-450`):
+
+| Syntax | Meaning | Example |
+| :----- | :------ | :------ |
+| Exact match | The pattern is exactly equal to the command | `Bash(npm run build)` only matches `npm run build` |
+| `:*` prefix | The pattern ends with `:*` → matches the first word / multi-word prefix of the command | `Bash(git:*)` matches `git status` / `git push origin main` |
+| Wildcard | When the pattern contains `*`, use picomatch bash mode (**`*` can cross `/`**) | `Bash(npm run *)` matches `npm run build`; `Bash(ls *)` matches `ls -al /tmp/x` |
+
+> Unlike minimatch, cbc deliberately enables `bash: true` for Bash wildcard mode so that `*` can cross `/`. Otherwise, `ls *` could not match `ls -al /xxx`, which is one of the most common pitfalls for users (see the comments in `permission-utils.ts:441-446`).
+
+#### Compound Commands
+
+CodeBuddy uses `CommandParserService` (priority: tree-sitter > shell-quote > regex fallback; see `permission-utils.ts:357-378`) to parse shell operators `&&` / `||` / `;` / `|`, and evaluates each subcommand independently:
+
+- **deny / ask rules**: trigger if any subcommand matches (`matchCommandRule`, lines `305-334`)
+- **allow rules**: require **all subcommands to match** before allowing (`isCommandAllowed`, lines `478-500`). This is a different trade-off from cc: a compound command with one matching and one non-matching subcommand will still ask for approval, preventing attackers from hiding dangerous commands next to allowed ones
+
+Example:
+
+```text
+allow: ["Bash(git:*)"]
+
+git status         → allow
+git status && rm * → ask (rm * is not in allow; every subcommand must match)
+git status; rm *   → ask (same as above)
+```
+
+#### Redirection
+
+Commands containing `>` / `<` / `>>` / `<<` / `&>` require an **exact match** under allow rules (`permission-utils.ts:482-485`); wildcard rules do not apply.
+
+### Read / Edit / Write
+
+File rules use `minimatch` for glob matching and perform three layers of path normalization (`permission-utils.ts::matchFileRule` and `normalizePath`, lines `241-268`):
+
+| pattern | Explanation | Example |
+| :------ | :---------- | :------ |
+| `//path` | Absolute filesystem path | `Read(//etc/hosts)` |
+| `~/path` | Starting from the user's home directory | `Read(~/.zshrc)` |
+| `/path` | Starting from the project root | `Edit(/src/**/*.ts)` |
+| `path` or `./path` | Starting from the current working directory | `Read(.env)` |
+
+Matching options: `dot: true` (allow dotfiles), `nocase: true` (case-insensitive), `matchBase: true` (bare filenames can match at any depth).
+
+Notes:
+
+- deny rules such as `Edit(.git/**)` block all attempts through Edit / Write / NotebookEdit, but **do not block** indirect paths through Bash such as `python -c 'open(".git/config", "w")...'`. OS-level protection depends on [Bash sandboxing](bash-sandboxing.md)
+- Read rules are also intercepted and parsed for some Bash file-read commands (`cat`, `head`, `tail`, etc.; see the special handling for these commands inside `command-utils.ts::checkCommandSafety`)
+
+### WebFetch
+
+```text
+WebFetch                       # any URL
+WebFetch(domain:example.com)   # only example.com and its subdomains
+```
+
+The matching implementation is in `permission-utils.ts::matchURLRule` (line `515`) and supports the `domain:` prefix for hostname matching.
+
+### MCP Tools
+
+MCP tools are named in the format `mcp__<server>__<tool>`. Rules support three granularities:
+
+| Rule | Matches |
+| :--- | :------ |
+| `mcp__puppeteer` | All tools of the entire puppeteer server |
+| `mcp__puppeteer__*` | Same as above (wildcard form) |
+| `mcp__puppeteer__navigate` | Only the navigate tool |
+
+Starting from `tool-permission-service.ts:152`, the code checks `tool.name.startsWith('mcp__')` and enters the MCP-specific branch.
+
+### Agent (Subagent)
+
+```json
+{
+  "permissions": {
+    "deny": ["Agent(Explore)", "Agent(Plan)"]
+  }
+}
+```
+
+You can also use a CLI flag:
+
+```bash
+codebuddy --disallowedTools "Agent(Explore) Agent(Plan)"
+```
+
+After being denied, that `subagent_type` will be rejected when the main agent invokes the Agent tool.
+
+### Skill
+
+```json
+{
+  "permissions": {
+    "deny": ["Skill(dangerous-skill-name)"]
+  }
+}
+```
+
+Skill rules **must** be exact matches (`permission-utils.ts::matchSkillRule`, lines `458-464`); wildcards are not supported.
+
+## Trusted Directories
+
+By default, CodeBuddy only considers the **current working directory** trusted. The Read tool is allowed inside trusted directories and asks outside them; Edit / Bash always go through full approval (unless an allow rule applies or a permissive mode is active).
+
+Several ways to expand the trusted scope:
+
+| Method | Persistence |
+| :----- | :---------- |
+| `--add-dir <path>` startup argument | Process-level |
+| `/add-dir` command within a session | Session-level |
+| `permissions.additionalDirectories` setting | Persistent |
+| `permissions.trustedDirectories` setting | Persistent |
+
+Implementation: `permission-utils.ts:561-583`. Trusted directory list = `workspace root + settings.trustedDirectories + session.options.addDir`.
+
+> Both `--add-dir` and `permissions.additionalDirectories` only grant **file access**. They **do not** make CodeBuddy load `.codebuddy/` configuration from those directories (agents / hooks / settings, etc. still use the startup directory). This matches cc behavior.
+
+### Project Directory Trust Switch
+
+Whether you have "explicitly trusted" a repository directory also affects the trust level of allow rules (`tool-permission-service.ts:182`). When the directory is **not trusted**:
+
+- `allow` rules in `<repo>/.codebuddy/settings.json` and `.codebuddy/settings.local.json` are classified into the **untrusted** layer (Phase 6), and **cannot** bypass command safety checks
+- After the user confirms trust in the interactive UI (`directoryTrustService.isTrustDirectory`), project-level rules are promoted to the Phase 2 trusted layer
+
+This is a cbc-specific security model designed to reduce lateral risk that can arise immediately after cloning and running a repository.
+
+## Protected Files / Paths
+
+In any mode, CodeBuddy adds extra protection for a set of critical paths (overlapping with the [PermissionMode documentation](permission-modes.md#protected-critical-files)):
+
+- The repository itself: `.git`, `.gitconfig`, `.gitmodules`
+- Shell configuration: `.bashrc` / `.zshrc` / `.envrc`, etc.
+- Package management: `.npmrc` / `.yarnrc` / `bunfig.toml`, etc.
+- IDE tools: `.vscode` / `.idea` / `.husky` / `.devcontainer`
+- CodeBuddy itself: `.codebuddy` (except `.codebuddy/worktrees`)
+- MCP / configuration: `.mcp.json` / `.codebuddy.json`
+
+`bypassPermissions` mode still allows most of these through, but "catastrophic commands" such as `rm -rf /` / `rm -rf ~` are forced to ask through the `isDangerousCommand` fallback (`tool-permission-service.ts:244`).
+
+## Extending Permissions with Hooks
+
+The `PreToolUse` hook in the [Hooks system](hooks-guide.md) runs before permission approval prompts and can programmatically allow / deny / rewrite inputs.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "/path/to/bash-policy.sh" }]
+      }
+    ]
+  }
+}
+```
+
+Hook exit code semantics:
+
+| Exit code | Behavior |
+| :-------- | :------- |
+| `0` + JSON decision | Execute according to `permissionDecision` (allow / ask / deny) in the JSON |
+| `2` | Block (stderr content is passed back to the model) |
+| Other non-0 | Non-blocking error (shown but allowed) |
+
+Notes:
+
+- **deny / ask rules always take effect before hooks**. A hook returning `"allow"` cannot bypass deny in settings. This matches cc behavior
+- However, **blocking hooks** (exit code 2) can short-circuit allow rules before Phase 1, so you can "allow all Bash first, but use hooks to separately block a few specific commands"
+
+## Working with Sandboxing
+
+Permission rules and [Bash sandboxing](bash-sandboxing.md) are complementary layers:
+
+- **Rule layer**: constrains whether CodeBuddy "wants to use" a tool or access a path
+- **Sandbox layer**: constrains whether the Bash subprocess can "actually access" a resource at the OS layer
+
+Typical defense-in-depth combinations:
+
+- `deny` rules prevent CodeBuddy from actively attempting restricted tools
+- The sandbox prevents all Bash subprocesses from reaching files / networks outside the allowlist — even if prompt injection makes CodeBuddy want to bypass it, it cannot
+- WebFetch `domain:` allow rules and sandbox `allowedDomains` both apply, and the final boundary is the intersection
+
+## Settings Priority
+
+Permission rules inherit the general [Settings priority](settings.md):
+
+```
+flagSettings / cliArg / session  > userSettings > policySettings >
+projectSettings > localSettings > command/sandbox sources
+```
+
+However, the **evaluation order** is more important than settings priority:
+
+- `deny` arrays are merged from all scopes (`PermissionUtils.mergeRulesFromAllSources`), and **a deny in any scope rejects**
+- `allow` arrays are merged twice by "trusted / untrusted": user/cli/flag/session/policy are always included in the trusted merge; project/local are considered trusted only when the directory is trusted
+- `disableBypassPermissionsMode` takes effect when it is `"disable"` in any of the four layers: `user / project / local / cliArg` (see `tool-permission-service.ts:670-673`) — this adds a project-level hard-disable channel compared with cc
+
+## Example Configurations
+
+### Minimized Trust: Only Allow npm Tests + Reading Project Files
+
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(npm test)",
+      "Bash(npm run lint)",
+      "Read(/src/**)",
+      "Read(/test/**)"
+    ],
+    "deny": [
+      "Bash(rm:*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)",
+      "Edit(.git/**)",
+      "Edit(/.codebuddy/**)"
+    ]
+  }
+}
+```
+
+### CI / Pipeline Scenario: Skip Approval + Strong Deny
+
+```json
+{
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "deny": [
+      "Bash(rm -rf /:*)",
+      "Bash(sudo:*)",
+      "Bash(curl * -o /etc/*)",
+      "WebFetch(domain:internal-corp.example)"
+    ]
+  }
+}
+```
+
+### Team Shared + Personal Relaxation
+
+`<repo>/.codebuddy/settings.json` (committed to git):
+
+```json
+{
+  "permissions": {
+    "deny": ["Bash(rm:*)", "Edit(.git/**)"]
+  }
+}
+```
+
+`~/.codebuddy/settings.json` (user-level, private):
+
+```json
+{
+  "permissions": {
+    "defaultMode": "acceptEdits",
+    "allow": ["Bash(git:*)", "Bash(npm:*)"]
+  }
+}
+```
+
+## Related Resources
+
+- [Permission Modes](permission-modes.md): default / acceptEdits / plan / bypassPermissions / delegate and other modes
+- [Settings Configuration](settings.md): complete configuration fields, scopes, and merge rules
+- [Hooks system](hooks-guide.md): make programmatic permission decisions with hooks
+- [Bash sandboxing](bash-sandboxing.md): OS-level isolation for Bash commands
+- [CLI Reference](cli-reference.md): startup arguments such as `--allowedTools` / `--disallowedTools` / `--add-dir`
+- [Security](security.md): overall security model and best practices
+- [IAM Identity and Access](iam.md): organization-level identity authentication and permission control

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.103.4](./v2.103.4.md) - 2026-06-08
+- [v2.103.3](./v2.103.3.md) - 2026-06-08
+- [v2.103.2](./v2.103.2.md) - 2026-06-07
 - [v2.103.1](./v2.103.1.md) - 2026-06-04
 - [v2.103.0](./v2.103.0.md) - 2026-06-04
 - [v2.102.0](./v2.102.0.md) - 2026-06-03

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

@@ -0,0 +1,21 @@
+# 🚀 CodeBuddy Code v2.103.2 Release
+
+## 📦 Version Information
+
+| Component | Version |
+|------|------|
+| CodeBuddy Code CLI | v2.103.2 |
+| Agent SDK JS | v0.3.167 |
+| Agent SDK Python | v0.3.166 |
+
+## 🔧 Improvements
+
+- **Plan Mode Visibility Convergence**: Sub-agents can now see the exit tool only when plan mode is explicitly locked. Sub-agents that simply inherit the main session's plan mode will no longer invoke it by mistake, avoiding pollution of the main session's approval popup.
+- **Embedded Scenario Adaptation**: Added the `CODEBUDDY_DISABLE_PLAN_MODE` environment variable, allowing hosts to disable plan mode with one switch, adapting to embedded scenarios without an approval popup rendering area.
+- **Stats Model Display Name Optimization**: Model aggregation statistics now display the model names configured by users, covering model rankings in Web UI and TUI, Token trend legends, and more.
+- **Context Compaction Switch Compatibility**: Optimized compatibility logic for the compaction switch. When the new switch is explicitly disabled, it will no longer be incorrectly enabled by legacy configuration.
+
+## 🐛 Bug Fixes
+
+- **Context Compaction Recovery Stability**: Fixed recovery stability for `/compact` and automatic compaction in scenarios with extremely long context, pending approvals, and image results, reducing the probability of request interruption after compaction failures.
+- **Monitoring Metrics Reporting Loss**: Fixed MeterProvider registration failure caused by multiple OpenTelemetry API instances, ensuring metrics data is reported normally.

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

@@ -0,0 +1,15 @@
+# 🚀 CodeBuddy Code v2.103.3 Release
+
+## 📦 Version Information
+
+| Component | Version |
+|------|------|
+| CodeBuddy Code CLI | v2.103.3 |
+| Agent SDK JS | v0.3.168 |
+| Agent SDK Python | v0.3.167 |
+
+## 🐛 Bug Fixes
+
+- **Custom Model Authentication Error Recognition**: Invalid custom model API keys (401/403) are no longer misidentified as platform login expiration, avoiding "log in again" popups that interrupt sessions.
+- **Session History Replay Stability**: When a session is reopened after being interrupted (such as force quit or crash), unfinished tool calls are now correctly rendered as "Canceled" instead of disappearing or showing non-localizable text. Pending questions that are still alive are no longer misidentified as orphan calls, preserving normal interaction capability.
+- **OTel Metrics Stability**: Reverted the previous metrics fix to restore stable telemetry behavior and avoid mainline regressions.

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

@@ -0,0 +1,13 @@
+# 🚀 CodeBuddy Code v2.103.4 Release
+
+## 📦 Version Information
+
+| Component | Version |
+|------|------|
+| CodeBuddy Code CLI | v2.103.4 |
+| Agent SDK JS | v0.3.169 |
+| Agent SDK Python | v0.3.168 |
+
+## 🔧 Improvements
+
+- **Model Optimization Assistance Switch**: Added the global `enableModelOptimization` setting, which controls whether to participate in model optimization. When enabled, requests carry the corresponding identifier. Custom models do not send this identifier, giving you clearer control over the scope of data usage.