@tencent-ai/codebuddy-code 2.109.0 → 2.109.2

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

@@ -60,6 +60,7 @@ The `settings.json` file is the official mechanism for configuring CodeBuddy Cod
 | `env` | Environment variables applied to every session | `{"FOO": "bar"}` |
 | `includeCoAuthoredBy` | Whether to include `co-authored-by CodeBuddy` attribution in git commits and pull requests (default: `true`) | `false` |
 | `permissions` | Permission configuration, see table below | |
+| `autoMode` | Classifier rules for `auto` permission mode, see [Auto Mode Configuration](#auto-mode-configuration) | `{"allow": ["$defaults", "Allow dev environment releases"]}` |
 | `hooks` | Configure custom commands to run before and after tool execution. See [hooks documentation](hooks.md) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |
 | `disableAllHooks` | Disable all [hooks](hooks.md) | `true` |
 | `allowUntrustedFrontmatterHooks` | Whether to allow execution of frontmatter `hooks` fields from agents/skills with **non-product-builtin** sources (including local user `.codebuddy/agents\|skills/*.md` and the plugin marketplace). Defaults to `false` to prevent untrusted md files from silently launching shell commands; only product-builtin agents/skills are unaffected. | `true` |
@@ -92,9 +93,172 @@ The `settings.json` file is the official mechanism for configuring CodeBuddy Cod
 | `ask` | Array of [permission rules](iam.md#configuring-permissions) requiring confirmation for tool use | `[ "Bash(git push:*)" ]` |
 | `deny` | Array of [permission rules](iam.md#configuring-permissions) denying tool use. Used to exclude CodeBuddy Code from accessing sensitive files. **Note:** Bash patterns are prefix-matched and can be bypassed (see [Bash Permission Limitations](iam.md#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |
 | `additionalDirectories` | Additional [working directories](iam.md#working-directories) that CodeBuddy can access | `[ "../docs/" ]` |
-| `defaultMode` | Default [permission mode](iam.md#permission-modes) when opening CodeBuddy Code | `"acceptEdits"` |
+| `defaultMode` | Default [permission mode](permission-modes.md) when opening CodeBuddy Code. Common values: `default`, `acceptEdits`, `auto`, `dontAsk`, `plan`, `bypassPermissions` | `"acceptEdits"` |
 | `disableBypassPermissionsMode` | Set to `"disable"` to prevent activating `bypassPermissions` mode. This disables the `-y` and `--dangerously-skip-permissions` CLI flags | `"disable"` |
-| `subagentPermissionMode` | Override the default permission mode for subagents/team members. When set, all subagents use this mode instead of inheriting from the main session's mode. The `mode` parameter of the Agent tool takes higher priority | `"bypassPermissions"` |
+| `disableAutoMode` | Set to `"disable"` to prevent activating `auto` mode. When disabled, both `--permission-mode auto` and `defaultMode: "auto"` fall back to `default` | `"disable"` |
+| `subagentPermissionMode` | Override the default permission mode for subagents/team members. When set, all subagents use this mode instead of inheriting from the main session's mode. The `mode` parameter of the Agent tool takes higher priority; however, if the main session is in `auto` / `dontAsk`, subagents are still constrained by the parent session's permission ceiling | `"bypassPermissions"` |
+
+### Auto Mode Configuration
+
+`autoMode` is a **top-level settings field**, not a subfield of `permissions`. It defines the classifier context and rules used by the `auto` permission mode.
+
+#### What fields are in `autoMode`?
+
+| Key | Purpose | Example |
+|:------|:-----|:-----|
+| `environment` | Describes which repositories, domains, services, and storage locations belong to your trusted boundary, helping the classifier determine what counts as "internal" | `["$defaults", "Trusted internal domains: staging.example.com"]` |
+| `allow` | Supplementary natural-language rules for "actions that can typically be auto-approved under auto mode" | `["$defaults", "Allow dev namespace releases"]` |
+| `soft_deny` | Supplementary rules for "actions that should typically be blocked, but can be retried with explicit user intent" | `["$defaults", "Modify shared test database schema"]` |
+| `hard_deny` | Supplementary high-risk rules that "must be blocked by default" | `["$defaults", "Publish private repository content to the public internet"]` |
+
+These field values are all **string arrays**. Array items are not regex or tool patterns — they are **natural-language rules** written for the classifier.
+
+#### Where does the classifier read `autoMode` from?
+
+CodeBuddy only reads `autoMode` from the following sources:
+
+| Source | Typical Location | Purpose |
+|:-----|:---------|:-----|
+| user settings | `~/.codebuddy/settings.json` | Cross-project personal trusted boundary |
+| project-local settings | `.codebuddy/settings.local.json` | Local supplementary rules for a specific project on a specific machine |
+| CLI `--settings` | `codebuddy --settings '{...}'` | One-time automation or temporary override |
+
+Sources that are NOT read:
+
+- Shared project configuration `.codebuddy/settings.json`
+
+The reason is: `autoMode` defines local security boundaries, and repository-committed configuration should not silently change your local machine's judgment about "what counts as internal and what actions are allowed."
+
+#### Difference from `permissions.defaultMode: "auto"`
+
+There are two easily confused restrictions here:
+
+1. **`autoMode` rule sources**: allowed from user / project-local / CLI
+2. **Authorization to enter `auto` mode by default**: only allowed from user / CLI
+
+In other words:
+
+- `.codebuddy/settings.local.json` **can** supplement `autoMode.environment / allow / soft_deny / hard_deny`
+- But `.codebuddy/settings.local.json` **cannot** make a session default to `auto` via `permissions.defaultMode: "auto"`
+- `.codebuddy/settings.json` cannot do either: it can neither provide `autoMode` nor grant `defaultMode: "auto"`
+
+#### How are multiple sources merged?
+
+The four fields of `autoMode` are merged in source order:
+
+1. user
+2. project-local
+3. CLI
+
+Merging follows two principles:
+
+- Each field is **merged independently**, without affecting others
+- Each field **appends** arrays from different sources together, then uniformly processes `"$defaults"`
+
+This means:
+
+- Setting only `environment` will not affect the defaults of `allow` / `soft_deny` / `hard_deny`
+- You can put organization-level trusted domains in user settings, then supplement project-specific staging services in project-local
+
+#### How does `"$defaults"` work?
+
+`"$defaults"` is a special placeholder meaning "insert the built-in default rules here."
+
+For example:
+
+```json
+{
+  "autoMode": {
+    "environment": [
+      "$defaults",
+      "Trusted internal domains: staging.example.com"
+    ]
+  }
+}
+```
+
+This means:
+
+- First use the built-in `environment` default rules
+- Then append your custom `staging.example.com`
+
+Key semantics:
+
+- Field **not configured**: that field directly uses built-in default rules
+- Field **includes** `"$defaults"`: expands default rules at that position
+- Field **does not include** `"$defaults"`: means **fully replacing** that field's built-in default rules
+- When multiple sources all write `"$defaults"`, the built-in rules are expanded only **once** and not injected repeatedly
+
+Additional notes:
+
+- If `soft_deny` / `hard_deny` do not include `"$defaults"`, you are actively abandoning built-in safety rules
+- A warning is logged at runtime, but it will not prevent you from configuring this way
+
+#### How to check the current effective result?
+
+```bash
+codebuddy auto-mode defaults
+codebuddy auto-mode config
+codebuddy auto-mode critique
+```
+
+These three commands are used for:
+
+- `defaults`: print built-in default rules
+- `config`: print the **final effective** rules (after multi-source merging and `"$defaults"` expansion)
+- `critique`: have a lite model review your custom `allow` / `soft_deny` / `hard_deny` for ambiguity, redundancy, or potential false positives
+
+If you plan to fully take over a field, the safest approach is usually:
+
+1. Run `codebuddy auto-mode defaults`
+2. Copy the built-in rules
+3. Explicitly rewrite them in your settings
+4. Run `codebuddy auto-mode config` to check the final result
+
+#### Configuration Examples
+
+##### Supplement trusted environment only
+
+```json
+{
+  "autoMode": {
+    "environment": [
+      "$defaults",
+      "Source control: git.example.com/acme and all repos under it",
+      "Trusted internal domains: staging.example.com, api.internal.example.com",
+      "Trusted buckets: s3://acme-build-artifacts"
+    ]
+  }
+}
+```
+
+##### Supplement allow / deny rules simultaneously
+
+```json
+{
+  "permissions": {
+    "defaultMode": "auto"
+  },
+  "autoMode": {
+    "environment": [
+      "$defaults",
+      "Trusted internal domains: staging.example.com"
+    ],
+    "allow": [
+      "$defaults",
+      "Allow dev namespace releases"
+    ],
+    "soft_deny": [
+      "$defaults",
+      "Modify shared test database schema"
+    ],
+    "hard_deny": [
+      "$defaults",
+      "Publish private repository content to the public internet"
+    ]
+  }
+}
+```
 
 ### Memory Configuration (Experimental)