@mmmbuto/qwen-code-termux 0.14.3-termux → 0.15.5-termux

package/bundled/qc-helper/docs/features/mcp.md

@@ -153,6 +153,84 @@ qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000
 
 - **Server trust** (`trust: true`): bypasses confirmation prompts for that server (use sparingly).
 
+### OAuth authentication
+
+Qwen Code supports OAuth 2.0 authentication for MCP servers. This is useful when accessing remote servers that require authentication.
+
+#### Basic usage
+
+When you add an MCP server with OAuth credentials, Qwen Code will automatically handle the authentication flow:
+
+```bash
+qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
+  --oauth-client-id your-client-id \
+  --oauth-redirect-uri https://your-server.com/oauth/callback \
+  --oauth-authorization-url https://provider.example.com/authorize \
+  --oauth-token-url https://provider.example.com/token
+```
+
+#### Important: Redirect URI configuration
+
+The OAuth flow requires a redirect URI where the authorization provider sends the authentication code.
+
+- **Local development**: By default, Qwen Code uses `http://localhost:7777/oauth/callback`. This works when running Qwen Code on your local machine with a local browser.
+
+- **Remote/cloud deployments**: When running Qwen Code on remote servers, cloud IDEs, or web terminals, the default `localhost` redirect will NOT work. You MUST configure `--oauth-redirect-uri` to point to a publicly accessible URL that can receive the OAuth callback.
+
+Example for remote servers:
+
+```bash
+qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
+  --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback
+```
+
+#### Manual configuration via settings.json
+
+You can also configure OAuth by editing `settings.json` directly:
+
+```json
+{
+  "mcpServers": {
+    "oauthServer": {
+      "url": "https://api.example.com/sse/",
+      "oauth": {
+        "enabled": true,
+        "clientId": "your-client-id",
+        "clientSecret": "your-client-secret",
+        "authorizationUrl": "https://provider.example.com/authorize",
+        "tokenUrl": "https://provider.example.com/token",
+        "redirectUri": "https://your-server.com/oauth/callback",
+        "scopes": ["read", "write"]
+      }
+    }
+  }
+}
+```
+
+OAuth configuration properties:
+
+| Property           | Description                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `enabled`          | Enable OAuth for this server (boolean)                                                                                |
+| `clientId`         | OAuth client identifier (string, optional with dynamic registration)                                                  |
+| `clientSecret`     | OAuth client secret (string, optional for public clients)                                                             |
+| `authorizationUrl` | OAuth authorization endpoint (string, auto-discovered if omitted)                                                     |
+| `tokenUrl`         | OAuth token endpoint (string, auto-discovered if omitted)                                                             |
+| `scopes`           | Required OAuth scopes (array of strings)                                                                              |
+| `redirectUri`      | Custom redirect URI (string). **Critical for remote deployments**. Defaults to `http://localhost:7777/oauth/callback` |
+| `tokenParamName`   | Query parameter name for tokens in SSE URLs (string)                                                                  |
+| `audiences`        | Audiences the token is valid for (array of strings)                                                                   |
+
+#### Token management
+
+OAuth tokens are automatically:
+
+- **Stored securely** in `~/.qwen/mcp-oauth-tokens.json`
+- **Refreshed** when expired (if refresh tokens are available)
+- **Validated** before each connection attempt
+
+Use the `/mcp auth` command within Qwen Code to manage OAuth authentication interactively.
+
 ### Tool filtering (allow/deny tools per server)
 
 Use `includeTools` / `excludeTools` to restrict tools exposed by a server (from Qwen Code’s perspective).
@@ -259,20 +337,28 @@ You can always configure MCP servers by manually editing `settings.json`, but th
 qwen mcp add [options] <name> <commandOrUrl> [args...]
 ```
 
-| Argument/Option     | Description                                                         | Default            | Example                                   |
-| ------------------- | ------------------------------------------------------------------- | ------------------ | ----------------------------------------- |
-| `<name>`            | A unique name for the server.                                       | —                  | `example-server`                          |
-| `<commandOrUrl>`    | The command to execute (for `stdio`) or the URL (for `http`/`sse`). | —                  | `/usr/bin/python` or `http://localhost:8` |
-| `[args...]`         | Optional arguments for a `stdio` command.                           | —                  | `--port 5000`                             |
-| `-s`, `--scope`     | Configuration scope (user or project).                              | `project`          | `-s user`                                 |
-| `-t`, `--transport` | Transport type (`stdio`, `sse`, `http`).                            | `stdio`            | `-t sse`                                  |
-| `-e`, `--env`       | Set environment variables.                                          | —                  | `-e KEY=value`                            |
-| `-H`, `--header`    | Set HTTP headers for SSE and HTTP transports.                       | —                  | `-H "X-Api-Key: abc123"`                  |
-| `--timeout`         | Set connection timeout in milliseconds.                             | —                  | `--timeout 30000`                         |
-| `--trust`           | Trust the server (bypass all tool call confirmation prompts).       | — (`false`)        | `--trust`                                 |
-| `--description`     | Set the description for the server.                                 | —                  | `--description "Local tools"`             |
-| `--include-tools`   | A comma-separated list of tools to include.                         | all tools included | `--include-tools mytool,othertool`        |
-| `--exclude-tools`   | A comma-separated list of tools to exclude.                         | none               | `--exclude-tools mytool`                  |
+| Argument/Option             | Description                                                         | Default                                | Example                                                            |
+| --------------------------- | ------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------ |
+| `<name>`                    | A unique name for the server.                                       | —                                      | `example-server`                                                   |
+| `<commandOrUrl>`            | The command to execute (for `stdio`) or the URL (for `http`/`sse`). | —                                      | `/usr/bin/python` or `http://localhost:8`                          |
+| `[args...]`                 | Optional arguments for a `stdio` command.                           | —                                      | `--port 5000`                                                      |
+| `-s`, `--scope`             | Configuration scope (user or project).                              | `project`                              | `-s user`                                                          |
+| `-t`, `--transport`         | Transport type (`stdio`, `sse`, `http`).                            | `stdio`                                | `-t sse`                                                           |
+| `-e`, `--env`               | Set environment variables.                                          | —                                      | `-e KEY=value`                                                     |
+| `-H`, `--header`            | Set HTTP headers for SSE and HTTP transports.                       | —                                      | `-H "X-Api-Key: abc123"`                                           |
+| `--timeout`                 | Set connection timeout in milliseconds.                             | —                                      | `--timeout 30000`                                                  |
+| `--trust`                   | Trust the server (bypass all tool call confirmation prompts).       | — (`false`)                            | `--trust`                                                          |
+| `--description`             | Set the description for the server.                                 | —                                      | `--description "Local tools"`                                      |
+| `--include-tools`           | A comma-separated list of tools to include.                         | all tools included                     | `--include-tools mytool,othertool`                                 |
+| `--exclude-tools`           | A comma-separated list of tools to exclude.                         | none                                   | `--exclude-tools mytool`                                           |
+| `--oauth-client-id`         | OAuth client ID for MCP server authentication.                      | —                                      | `--oauth-client-id your-client-id`                                 |
+| `--oauth-client-secret`     | OAuth client secret for MCP server authentication.                  | —                                      | `--oauth-client-secret your-client-secret`                         |
+| `--oauth-redirect-uri`      | OAuth redirect URI for authentication callback.                     | `http://localhost:7777/oauth/callback` | `--oauth-redirect-uri https://your-server.com/oauth/callback`      |
+| `--oauth-authorization-url` | OAuth authorization URL.                                            | —                                      | `--oauth-authorization-url https://provider.example.com/authorize` |
+| `--oauth-token-url`         | OAuth token URL.                                                    | —                                      | `--oauth-token-url https://provider.example.com/token`             |
+| `--oauth-scopes`            | OAuth scopes (comma-separated).                                     | —                                      | `--oauth-scopes scope1,scope2`                                     |
+
+> `--oauth-*` flags apply only to `--transport sse` and `--transport http`. Combining them with `--transport stdio` is rejected.
 
 #### Removing a server (`qwen mcp remove`)
 

package/bundled/qc-helper/docs/features/memory.md

@@ -0,0 +1,168 @@
+# Memory
+
+Every Qwen Code session starts with a fresh context window. Two mechanisms carry knowledge across sessions so you don't have to re-explain yourself every time:
+
+- **QWEN.md** — instructions _you_ write once and Qwen reads every session
+- **Auto-memory** — notes Qwen writes itself based on what it learns from you
+
+---
+
+## QWEN.md: your instructions to Qwen
+
+QWEN.md is a plain text file where you write things Qwen should always know about your project or your preferences. Think of it as a permanent briefing that loads at the start of every conversation.
+
+### What to put in QWEN.md
+
+Add things you'd otherwise have to repeat every session:
+
+- Build and test commands (`npm run test`, `make build`)
+- Coding conventions your team follows ("all new files must have JSDoc comments")
+- Architectural decisions ("we use the repository pattern, never call the database directly from controllers")
+- Personal preferences ("always use pnpm, not npm")
+
+Don't include things Qwen can figure out by reading your code. QWEN.md works best when it's short and specific — the longer it gets, the less reliably Qwen follows it.
+
+### Where to create QWEN.md
+
+| File                          | Who it applies to                             |
+| ----------------------------- | --------------------------------------------- |
+| `~/.qwen/QWEN.md`             | You, across all your projects                 |
+| `QWEN.md` in the project root | Your whole team (commit it to source control) |
+
+You can have both. Qwen loads all QWEN.md files it finds when you start a session — your personal one plus any in the project.
+
+If your repository already has an `AGENTS.md` file for other AI tools, Qwen reads that too. No need to duplicate instructions.
+
+### Generate one automatically with `/init`
+
+Run `/init` and Qwen will analyze your codebase to create a starter QWEN.md with build commands, test instructions, and conventions it finds. If one already exists, it suggests additions instead of overwriting.
+
+### Reference other files
+
+You can point QWEN.md at other files so Qwen reads them too:
+
+```markdown
+See @README.md for project overview.
+
+# Conventions
+
+- Git workflow: @docs/git-workflow.md
+```
+
+Use `@path/to/file` anywhere in QWEN.md. Relative paths resolve from the QWEN.md file itself.
+
+---
+
+## Auto-memory: what Qwen learns about you
+
+Auto-memory runs in the background. After each of your conversations, Qwen quietly saves useful things it learned — your preferences, feedback you gave, project context — so it can use them in future sessions without you repeating yourself.
+
+This is different from QWEN.md: you don't write it, Qwen does.
+
+### What Qwen saves
+
+Qwen looks for four kinds of things worth remembering:
+
+| What                    | Examples                                                 |
+| ----------------------- | -------------------------------------------------------- |
+| **About you**           | Your role, background, how you like to work              |
+| **Your feedback**       | Corrections you made, approaches you confirmed           |
+| **Project context**     | Ongoing work, decisions, goals not obvious from the code |
+| **External references** | Dashboards, ticket trackers, docs links you mentioned    |
+
+Qwen doesn't save everything — only things that would actually be useful next time.
+
+### Where it's stored
+
+Auto-memory files live at `~/.qwen/projects/<project>/memory/`. All branches and worktrees of the same repository share the same memory folder, so what Qwen learns in one branch is available in others.
+
+Everything saved is plain markdown — you can open, edit, or delete any file at any time.
+
+### Periodic cleanup
+
+Qwen periodically goes through its saved memories to remove duplicates and clean up outdated entries. This runs automatically in the background once a day after enough sessions have accumulated. You can trigger it manually with `/dream` if you want it to run now.
+
+While cleanup is running, **✦ dreaming** appears in the corner of the screen. Your session continues normally.
+
+### Turning it on or off
+
+Auto-memory is on by default. To toggle it, open `/memory` and use the switches at the top. You can turn off just the automatic saving, just the periodic cleanup, or both.
+
+You can also set them in `~/.qwen/settings.json` (applies to all projects) or `.qwen/settings.json` (this project only):
+
+```json
+{
+  "memory": {
+    "enableManagedAutoMemory": true,
+    "enableManagedAutoDream": true
+  }
+}
+```
+
+---
+
+## Commands
+
+### `/memory`
+
+Opens the Memory panel. From here you can:
+
+- Turn auto-memory saving on or off
+- Turn periodic cleanup (dream) on or off
+- Open your personal QWEN.md (`~/.qwen/QWEN.md`)
+- Open the project QWEN.md
+- Browse the auto-memory folder
+
+### `/init`
+
+Generates a starter QWEN.md for your project. Qwen reads your codebase and fills in build commands, test instructions, and conventions it discovers.
+
+### `/remember <text>`
+
+Immediately saves something to auto-memory without waiting for Qwen to pick it up automatically:
+
+```
+/remember always use snake_case for Python variable names
+/remember the staging environment is at staging.example.com
+```
+
+### `/forget <text>`
+
+Removes auto-memory entries that match your description:
+
+```
+/forget old workaround for the login bug
+```
+
+### `/dream`
+
+Runs the memory cleanup now instead of waiting for the automatic schedule:
+
+```
+/dream
+```
+
+---
+
+## Troubleshooting
+
+### Qwen isn't following my QWEN.md
+
+Open `/memory` to see which files are loaded. If your file isn't listed, Qwen can't see it — make sure it's in the project root or `~/.qwen/`.
+
+Instructions work better when they're specific:
+
+- ✓ `Use 2-space indentation for TypeScript files`
+- ✗ `Format code nicely`
+
+If you have multiple QWEN.md files with conflicting instructions, Qwen may behave inconsistently. Review them and remove any contradictions.
+
+### I want to see what Qwen has saved
+
+Run `/memory` and select **Open auto-memory folder**. All saved memories are readable markdown files you can browse, edit, or delete.
+
+### Qwen keeps forgetting things
+
+If auto-memory is on but Qwen doesn't seem to remember things across sessions, try running `/dream` to force a cleanup pass. Also check `/memory` to confirm both toggles are enabled.
+
+For things you always want Qwen to remember, add them to QWEN.md instead — auto-memory is best-effort, QWEN.md is guaranteed.

package/bundled/qc-helper/docs/features/sandbox.md

@@ -103,8 +103,16 @@ qwen -p "run the test suite"
 
 - **CLI flag**: `--sandbox-image <image>`
 - **Environment variable**: `QWEN_SANDBOX_IMAGE=<image>`
+- **Settings file**: `tools.sandboxImage` in your `settings.json` (e.g., `{"tools": {"sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1"}}`)
 
-If you don’t set either, Qwen Code uses the default image configured in the CLI package (for example `ghcr.io/qwenlm/qwen-code:<version>`).
+Priority order (highest to lowest):
+
+1. `--sandbox-image`
+2. `QWEN_SANDBOX_IMAGE`
+3. `tools.sandboxImage`
+4. Built-in default image from the CLI package (for example `ghcr.io/qwenlm/qwen-code:<version>`)
+
+`settings.env.QWEN_SANDBOX_IMAGE` also works as a generic env injection mechanism, but `tools.sandboxImage` is the preferred persistent setting.
 
 ### macOS Seatbelt profiles
 

package/bundled/qc-helper/docs/features/status-line.md

@@ -5,14 +5,21 @@
 The status line lets you run a shell command whose output is displayed in the footer's left section. The command receives structured JSON context via stdin, so it can show session-aware information like the current model, token usage, git branch, or anything else you can script.
 
 ```
-With status line (default approval mode — 1 row):
+Single-line status (default approval mode — 1 row):
 ┌─────────────────────────────────────────────────────────────────┐
 │  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line
 └─────────────────────────────────────────────────────────────────┘
 
-With status line + non-default mode (2 rows):
+Multi-line status (up to 2 lines — 2 rows):
 ┌─────────────────────────────────────────────────────────────────┐
-│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line
+│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line 1
+│  ████████░░░░░░░░░░ 34% context                                │  ← status line 2
+└─────────────────────────────────────────────────────────────────┘
+
+Multi-line status + non-default mode (3 rows max):
+┌─────────────────────────────────────────────────────────────────┐
+│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line 1
+│  ████████░░░░░░░░░░ 34% context                                │  ← status line 2
 │  auto-accept edits (shift + tab to cycle)                       │  ← mode indicator
 └─────────────────────────────────────────────────────────────────┘
 ```
@@ -53,10 +60,11 @@ Add a `statusLine` object under the `ui` key in `~/.qwen/settings.json`:
 }
 ```
 
-| Field     | Type        | Required | Description                                                                           |
-| --------- | ----------- | -------- | ------------------------------------------------------------------------------------- |
-| `type`    | `"command"` | Yes      | Must be `"command"`                                                                   |
-| `command` | string      | Yes      | Shell command to execute. Receives JSON via stdin, first line of stdout is displayed. |
+| Field             | Type        | Required | Description                                                                                                                       |
+| ----------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `type`            | `"command"` | Yes      | Must be `"command"`                                                                                                               |
+| `command`         | string      | Yes      | Shell command to execute. Receives JSON via stdin, stdout is displayed (up to 2 lines).                                           |
+| `refreshInterval` | number      | No       | Re-run the command every N seconds (minimum 1). Useful for data that changes without an Agent state event (clock, quota, uptime). |
 
 ## JSON input
 
@@ -181,6 +189,24 @@ Output: `my-project (main)`
 
 Output: `+120/-30 lines`
 
+### Live clock and git branch
+
+Use `refreshInterval` when the statusline shows data that changes without an Agent event (e.g. the clock, uptime, or rate-limit counters):
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "command",
+      "command": "input=$(cat); branch=$(echo \"$input\" | jq -r '.git.branch // \"no-git\"'); echo \"$(date +%H:%M:%S)  ($branch)\"",
+      "refreshInterval": 1
+    }
+  }
+}
+```
+
+Output (refreshed every second): `14:32:07  (main)`
+
 ### Script file for complex commands
 
 For longer commands, save a script file at `~/.qwen/statusline-command.sh`:
@@ -218,9 +244,9 @@ Then reference it in settings:
 
 ## Behavior
 
-- **Update triggers**: The status line updates when the model changes, a new message is sent (token count changes), vim mode is toggled, git branch changes, tool calls complete, or file changes occur. Updates are debounced (300ms).
+- **Update triggers**: The status line updates when the model changes, a new message is sent (token count changes), vim mode is toggled, git branch changes, tool calls complete, or file changes occur. Updates are debounced (300ms). Set `refreshInterval` (seconds) to additionally re-run the command on a timer — useful for data that changes without an Agent event (clock, rate limits, build status).
 - **Timeout**: Commands that take longer than 5 seconds are killed. The status line clears on failure.
-- **Output**: Only the first line of stdout is used. The text is rendered with dimmed colors in the footer's left section and truncated if it exceeds the available width.
+- **Output**: Multi-line output is supported (up to 2 lines; extra lines are discarded). Each line is rendered as a separate row with dimmed colors in the footer's left section. Lines that exceed the available width are truncated.
 - **Hot reload**: Changes to `ui.statusLine` in settings take effect immediately — no restart required.
 - **Shell**: Commands run via `/bin/sh` on macOS/Linux. On Windows, `cmd.exe` is used by default — wrap POSIX commands with `bash -c "..."` or point to a bash script (e.g. `bash ~/.qwen/statusline-command.sh`).
 - **Removal**: Delete the `ui.statusLine` key from settings to disable. The "? for shortcuts" hint returns.
@@ -231,5 +257,5 @@ Then reference it in settings:
 | ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Status line not showing | Config at wrong path   | Must be under `ui.statusLine`, not root-level `statusLine`                                                                                                                                                                                                                                                                                                                                             |
 | Empty output            | Command fails silently | Test manually: `echo '{"session_id":"test","version":"0.14.1","model":{"display_name":"test"},"context_window":{"context_window_size":0,"used_percentage":0,"remaining_percentage":100,"current_usage":0,"total_input_tokens":0,"total_output_tokens":0},"workspace":{"current_dir":"/tmp"},"metrics":{"models":{},"files":{"total_lines_added":0,"total_lines_removed":0}}}' \| sh -c 'your_command'` |
-| Stale data              | No trigger fired       | Send a message or switch models to trigger an update                                                                                                                                                                                                                                                                                                                                                   |
+| Stale data              | No trigger fired       | Send a message or switch models to trigger an update — or set `refreshInterval` to re-run the command on a timer                                                                                                                                                                                                                                                                                       |
 | Command too slow        | Complex script         | Optimize the script or move heavy work to a background cache                                                                                                                                                                                                                                                                                                                                           |

package/bundled/qc-helper/docs/features/sub-agents.md

@@ -12,10 +12,46 @@ Subagents are independent AI assistants that:
 - **Work autonomously** - Once given a task, they work independently until completion or failure
 - **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time
 
+## Fork Subagent (Implicit Fork)
+
+In addition to named subagents, Qwen Code supports **implicit forking** — when the AI omits the `subagent_type` parameter, it triggers a fork that inherits the parent's full conversation context.
+
+### How Fork Differs from Named Subagents
+
+|               | Named Subagent                    | Fork Subagent                                         |
+| ------------- | --------------------------------- | ----------------------------------------------------- |
+| Context       | Starts fresh, no parent history   | Inherits parent's full conversation history           |
+| System prompt | Uses its own configured prompt    | Uses parent's exact system prompt (for cache sharing) |
+| Execution     | Blocks the parent until done      | Runs in background, parent continues immediately      |
+| Use case      | Specialized tasks (testing, docs) | Parallel tasks that need the current context          |
+
+### When Fork is Used
+
+The AI automatically uses fork when it needs to:
+
+- Run multiple research tasks in parallel (e.g., "investigate module A, B, and C")
+- Perform background work while continuing the main conversation
+- Delegate tasks that require understanding of the current conversation context
+
+### Prompt Cache Sharing
+
+All forks share the parent's exact API request prefix (system prompt, tools, conversation history), enabling DashScope prompt cache hits. When 3 forks run in parallel, the shared prefix is cached once and reused — saving 80%+ token costs compared to independent subagents.
+
+### Recursive Fork Prevention
+
+Fork children cannot create further forks. This is enforced at runtime — if a fork attempts to spawn another fork, it receives an error instructing it to execute tasks directly.
+
+### Current Limitations
+
+- **No result feedback**: Fork results are reflected in the UI progress display but are not automatically fed back into the main conversation. The parent AI sees a placeholder message and cannot act on the fork's output.
+- **No worktree isolation**: Forks share the parent's working directory. Concurrent file modifications from multiple forks may conflict.
+
 ## Key Benefits
 
 - **Task Specialization**: Create agents optimized for specific workflows (testing, documentation, refactoring, etc.)
 - **Context Isolation**: Keep specialized work separate from your main conversation
+- **Context Inheritance**: Fork subagents inherit the full conversation for context-heavy parallel tasks
+- **Prompt Cache Sharing**: Fork subagents share the parent's cache prefix, reducing token costs
 - **Reusability**: Save and reuse agent configurations across projects and sessions
 - **Controlled Access**: Limit which tools each agent can use for security and focus
 - **Progress Visibility**: Monitor agent execution with real-time progress updates
@@ -23,7 +59,7 @@ Subagents are independent AI assistants that:
 ## How Subagents Work
 
 1. **Configuration**: You create Subagents configurations that define their behavior, tools, and system prompts
-2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents
+2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents — or implicitly fork when no specific subagent type is needed
 3. **Execution**: Subagents work independently, using their configured tools to complete tasks
 4. **Results**: They return results and execution summaries back to the main conversation
 
@@ -99,10 +135,12 @@ Subagents are configured using Markdown files with YAML frontmatter. This format
 name: agent-name
 description: Brief description of when and how to use this agent
 model: inherit # Optional: inherit or model-id
-tools:
-	- tool1
-	- tool2
-	- tool3 # Optional
+approvalMode: auto-edit # Optional: default, plan, auto-edit, yolo
+tools:         # Optional: allowlist of tools
+  - tool1
+  - tool2
+disallowedTools: # Optional: blocklist of tools
+  - tool3
 ---
 
 System prompt content goes here.
@@ -118,6 +156,87 @@ Use the optional `model` frontmatter field to control which model a subagent use
 - `glm-5`: Use that model ID with the main conversation's auth type
 - `openai:gpt-4o`: Use a different provider (resolves credentials from env vars)
 
+#### Permission Mode
+
+Use the optional `approvalMode` frontmatter field to control how a subagent's tool calls are approved. Valid values:
+
+- `default`: Tools require interactive approval (same as the main session default)
+- `plan`: Analyze-only mode — the agent plans but does not execute changes
+- `auto-edit`: Tools are auto-approved without prompting (recommended for most agents)
+- `yolo`: All tools auto-approved, including potentially destructive ones
+
+If you omit this field, the subagent's permission mode is determined automatically:
+
+- If the parent session is in **yolo** or **auto-edit** mode, the subagent inherits that mode. A permissive parent stays permissive.
+- If the parent session is in **plan** mode, the subagent stays in plan mode. An analyze-only session cannot mutate files through a delegated agent.
+- If the parent session is in **default** mode (in a trusted folder), the subagent gets **auto-edit** so it can work autonomously.
+
+When you do set `approvalMode`, the parent's permissive modes still take priority. For example, if the parent is in yolo mode, a subagent with `approvalMode: plan` will still run in yolo mode.
+
+```
+---
+name: cautious-reviewer
+description: Reviews code without making changes
+approvalMode: plan
+tools:
+  - read_file
+  - grep_search
+  - glob
+---
+
+You are a code reviewer. Analyze the code and report findings.
+Do not modify any files.
+```
+
+#### Tool Configuration
+
+Use `tools` and `disallowedTools` to control which tools a subagent can access.
+
+**`tools` (allowlist):** When specified, the subagent can only use the listed tools. When omitted, the subagent inherits all available tools from the parent session.
+
+```
+---
+name: reader
+description: Read-only agent for code exploration
+tools:
+  - read_file
+  - grep_search
+  - glob
+  - list_directory
+---
+```
+
+**`disallowedTools` (blocklist):** When specified, the listed tools are removed from the subagent's tool pool. This is useful when you want "everything except X" without listing every permitted tool.
+
+```
+---
+name: safe-worker
+description: Agent that cannot modify files
+disallowedTools:
+  - write_file
+  - edit
+  - run_shell_command
+---
+```
+
+If both `tools` and `disallowedTools` are set, the allowlist is applied first, then the blocklist removes from that set.
+
+**MCP tools** follow the same rules. If a subagent has no `tools` list, it inherits all MCP tools from the parent session. If a subagent has an explicit `tools` list, it only gets MCP tools that are explicitly named in that list.
+
+The `disallowedTools` field supports MCP server-level patterns:
+
+- `mcp__server__tool_name` — blocks a specific MCP tool
+- `mcp__server` — blocks all tools from that MCP server
+
+```
+---
+name: no-slack
+description: Agent without Slack access
+disallowedTools:
+  - mcp__slack
+---
+```
+
 #### Example Usage
 
 ```
@@ -214,7 +333,6 @@ tools:
   - read_file
   - write_file
   - read_many_files
-  - web_search
 ---
 
 You are a technical documentation specialist.
@@ -500,7 +618,8 @@ Always follow these standards:
 
 ## Security Considerations
 
-- **Tool Restrictions**: Subagents only have access to their configured tools
+- **Tool Restrictions**: Use `tools` to limit which tools a subagent can access, or `disallowedTools` to block specific tools while inheriting everything else
+- **Permission Mode**: Subagents inherit their parent's permission mode by default. Plan-mode sessions cannot escalate to auto-edit through delegated agents. Privileged modes (auto-edit, yolo) are blocked in untrusted folders.
 - **Sandboxing**: All tool execution follows the same security model as direct tool use
 - **Audit Trail**: All Subagents actions are logged and visible in real-time
 - **Access Control**: Project and user-level separation provides appropriate boundaries

package/bundled/qc-helper/docs/features/tips.md

@@ -0,0 +1,54 @@
+# Contextual Tips
+
+Qwen Code includes a contextual tips system that helps you discover features and stay aware of session state.
+
+## Startup Tips
+
+Each time you launch Qwen Code, a tip is shown in the header area. Tips are selected by priority first, then rotated across sessions using LRU (least-recently-used) scheduling among tips of the same priority, so you see a different tip each time.
+
+New users see onboarding-focused tips during their first sessions:
+
+| Sessions | Example tips                                         |
+| -------- | ---------------------------------------------------- |
+| < 5      | Slash commands (`/`), Tab autocomplete               |
+| < 10     | `QWEN.md` project context, `--continue` / `--resume` |
+| < 15     | Shell commands with `!` prefix                       |
+
+After that, tips rotate through general features like `/compress`, `/approval-mode`, `/insight`, `/btw`, and more.
+
+## Post-Response Tips
+
+During a conversation, Qwen Code monitors your context window usage and shows tips when action may be needed:
+
+| Context usage | Condition                      | Tip                                               |
+| ------------- | ------------------------------ | ------------------------------------------------- |
+| 50-80%        | After a few prompts in session | Suggests `/compress` to free up context           |
+| 80-95%        | —                              | Warns context is getting full                     |
+| >= 95%        | —                              | Urgent: run `/compress` now or `/new` to continue |
+
+Post-response tips have per-tip cooldowns to avoid being repetitive.
+
+## Tip History
+
+Tip display history is persisted at `~/.qwen/tip_history.json`. This file tracks:
+
+- Session count (used for new-user tip selection)
+- Which tips have been shown and when (used for LRU rotation and cooldown)
+
+You can safely delete this file to reset tip history.
+
+## Disabling Tips
+
+To hide all tips (both startup and post-response), set `ui.hideTips` to `true` in `~/.qwen/settings.json`:
+
+```json
+{
+  "ui": {
+    "hideTips": true
+  }
+}
+```
+
+You can also toggle this in the settings dialog via the `/settings` command.
+
+Tips are also automatically hidden when screen reader mode is enabled.