@mmmbuto/qwen-code-termux 0.16.1-termux → 0.18.0-termux

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

@@ -1,8 +1,11 @@
 # Status Line
 
-> Display custom information in the footer using a shell command.
+> Display custom information in the footer.
 
-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.
+The status line shows session-aware information — model name, token usage, git branch, and more — in the footer's left section. There are two configuration modes:
+
+- **Preset mode** — pick from built-in data items via an interactive dialog or JSON config. No scripting required.
+- **Command mode** — run a shell command that receives structured JSON context via stdin. Full flexibility for custom formatting.
 
 ```
 Single-line status (default approval mode — 1 row):
@@ -26,26 +29,130 @@ Multi-line status + non-default mode (3 rows max):
 
 When configured, the status line replaces the default "? for shortcuts" hint. High-priority messages (Ctrl+C/D exit prompts, Esc, vim INSERT mode) temporarily override the status line. The status line text is truncated to fit within the available width.
 
-## Prerequisites
-
-- [`jq`](https://jqlang.github.io/jq/) is recommended for parsing the JSON input (install via `brew install jq`, `apt install jq`, etc.)
-- Simple commands that don't need JSON data (e.g. `git branch --show-current`) work without `jq`
-
 ## Quick setup
 
-The easiest way to configure a status line is the `/statusline` command. It launches a setup agent that reads your shell PS1 configuration and generates a matching status line:
+The easiest way to configure a status line is the `/statusline` command. It opens an interactive dialog where you can select preset items, toggle theme colors, and see a live preview:
 
 ```
 /statusline
 ```
 
-You can also give it specific instructions:
+This opens the preset mode configurator. Use arrow keys to navigate, space to toggle items, and enter to confirm. Your selection is saved to settings automatically.
+
+You can also give `/statusline` specific instructions to have it generate a command-mode configuration:
 
 ```
 /statusline show model name and context usage percentage
 ```
 
-## Manual configuration
+---
+
+## Preset mode
+
+Preset mode provides a set of built-in data items that you can pick and combine — no shell commands, no `jq`, no scripting. Items are rendered as `item1 | item2 | item3` in a single line.
+
+### Configuration
+
+Add a `statusLine` object under the `ui` key in `~/.qwen/settings.json`:
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "preset",
+      "items": [
+        "model-with-reasoning",
+        "git-branch",
+        "context-remaining",
+        "current-dir",
+        "context-used"
+      ],
+      "useThemeColors": true
+    }
+  }
+}
+```
+
+| Field                  | Type       | Required | Description                                                                                                |
+| ---------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `type`                 | `"preset"` | Yes      | Must be `"preset"`                                                                                         |
+| `items`                | string[]   | Yes      | Ordered list of preset item IDs to display (see table below). Items are joined with `\|` as the separator. |
+| `useThemeColors`       | boolean    | No       | Apply the active `/theme` color to the status line text. Defaults to `true`.                               |
+| `hideContextIndicator` | boolean    | No       | Hide the built-in context usage indicator in the footer right section. Defaults to `false`.                |
+
+### Available preset items
+
+| Item ID                | Default | Description                                                        |
+| ---------------------- | ------- | ------------------------------------------------------------------ |
+| `model-with-reasoning` | Yes     | Current model name with reasoning level (e.g. `qwen-3-235b high`)  |
+| `model`                |         | Current model name without reasoning level                         |
+| `git-branch`           | Yes     | Current Git branch name (hidden when not in a git repo)            |
+| `context-remaining`    | Yes     | Percentage of context window remaining (e.g. `Context 65.7% left`) |
+| `total-input-tokens`   |         | Total input tokens used in session (e.g. `30.0k in`)               |
+| `total-output-tokens`  |         | Total output tokens used in session (e.g. `5.0k out`)              |
+| `current-dir`          | Yes     | Current working directory                                          |
+| `project-name`         |         | Project name (basename of working directory)                       |
+| `pull-request-number`  |         | Open PR number for the current branch (requires `gh` CLI)          |
+| `branch-changes`       |         | Session file change stats (e.g. `+120 -30`)                        |
+| `context-used`         | Yes     | Percentage of context window used (e.g. `Context 34.3% used`)      |
+| `run-state`            |         | Compact session state (`Ready`, `Working`, or `Confirm`)           |
+| `qwen-version`         |         | Qwen Code version (e.g. `v0.14.1`)                                 |
+| `context-window-size`  |         | Total context window size (e.g. `131.1k window`)                   |
+| `used-tokens`          |         | Current prompt token count (e.g. `45.0k used`)                     |
+| `session-id`           |         | Current session identifier                                         |
+
+Items marked **Default** are pre-selected when you first open the `/statusline` dialog.
+
+### Example output
+
+With the default items, the status line looks like:
+
+```
+qwen-3-235b high | main | Context 65.7% left | /home/user/project | Context 34.3% used
+```
+
+### Customizing via the dialog
+
+Running `/statusline` opens an interactive multi-select dialog:
+
+```
+┌ Configure Status Line ────────────────────────────────────────┐
+│ Select which items to display in the status line.             │
+│                                                               │
+│ Type to search                                                │
+│ >                                                             │
+│                                                               │
+│ [x] Use theme colors        Apply colors from the active /theme│
+│ ───────────────────────                                       │
+│ [x] model-with-reasoning    Current model name with reasoning │
+│ [ ] model-only              Current model name without reason │
+│ [x] git-branch              Current Git branch when available │
+│ [x] context-remaining       Percentage of context remaining   │
+│ ...                                                           │
+│                                                               │
+│ Preview                                                       │
+│ qwen-3-235b high | main | Context 65.7% left                 │
+│                                                               │
+│ Use up/down to navigate, space to select, enter to confirm    │
+└───────────────────────────────────────────────────────────────┘
+```
+
+- Type to filter items by name or description
+- A live preview updates as you toggle items
+- Press enter to save the configuration
+
+---
+
+## Command mode
+
+Command mode runs a shell command whose stdout is displayed in the status line. The command receives structured JSON context via stdin for session-aware output.
+
+### Prerequisites
+
+- [`jq`](https://jqlang.github.io/jq/) is recommended for parsing the JSON input (install via `brew install jq`, `apt install jq`, etc.)
+- Simple commands that don't need JSON data (e.g. `git branch --show-current`) work without `jq`
+
+### Configuration
 
 Add a `statusLine` object under the `ui` key in `~/.qwen/settings.json`:
 
@@ -60,13 +167,15 @@ 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, 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). |
+| 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). |
+| `respectUserColors`    | boolean     | No       | Preserve ANSI color codes in command output instead of applying dimmed footer styling. Defaults to `false`.                       |
+| `hideContextIndicator` | boolean     | No       | Hide the built-in context usage indicator in the footer right section. Defaults to `false`.                                       |
 
-## JSON input
+### JSON input
 
 The command receives a JSON object via stdin with the following fields:
 
@@ -91,6 +200,13 @@ The command receives a JSON object via stdin with the following fields:
   "git": {
     "branch": "main"
   },
+  "worktree": {
+    "name": "fix-auth",
+    "path": "/home/user/project/.qwen/worktrees/fix-auth",
+    "branch": "fix-auth",
+    "original_cwd": "/home/user/project",
+    "original_branch": "main"
+  },
   "metrics": {
     "models": {
       "qwen-3-235b": {
@@ -133,6 +249,12 @@ The command receives a JSON object via stdin with the following fields:
 | `workspace.current_dir`               | string           | Current working directory                                                          |
 | `git`                                 | object \| absent | Present only inside a git repository.                                              |
 | `git.branch`                          | string           | Current branch name                                                                |
+| `worktree`                            | object \| absent | Present only when inside an active worktree (created by `enter_worktree`).         |
+| `worktree.name`                       | string           | Worktree slug name                                                                 |
+| `worktree.path`                       | string           | Absolute path to the worktree directory                                            |
+| `worktree.branch`                     | string           | Branch checked out in the worktree                                                 |
+| `worktree.original_cwd`               | string           | Working directory before entering the worktree                                     |
+| `worktree.original_branch`            | string           | Branch that was active before entering the worktree                                |
 | `metrics.models.<id>.api`             | object           | Per-model API stats: `total_requests`, `total_errors`, `total_latency_ms`          |
 | `metrics.models.<id>.tokens`          | object           | Per-model token usage: `prompt`, `completion`, `total`, `cached`, `thoughts`       |
 | `metrics.files`                       | object           | File change stats: `total_lines_added`, `total_lines_removed`                      |
@@ -140,9 +262,9 @@ The command receives a JSON object via stdin with the following fields:
 
 > **Important:** stdin can only be read once. Always store it in a variable first: `input=$(cat)`.
 
-## Examples
+### Examples
 
-### Model and token usage
+#### Model and token usage
 
 ```json
 {
@@ -157,7 +279,7 @@ The command receives a JSON object via stdin with the following fields:
 
 Output: `qwen-3-235b  ctx:34%`
 
-### Git branch + directory
+#### Git branch + directory
 
 ```json
 {
@@ -174,7 +296,7 @@ Output: `my-project (main)`
 
 > Note: The `git.branch` field is provided directly in the JSON input — no need to shell out to `git`.
 
-### File change stats
+#### File change stats
 
 ```json
 {
@@ -189,7 +311,7 @@ Output: `my-project (main)`
 
 Output: `+120/-30 lines`
 
-### Live clock and git branch
+#### 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):
 
@@ -207,7 +329,7 @@ Use `refreshInterval` when the statusline shows data that changes without an Age
 
 Output (refreshed every second): `14:32:07  (main)`
 
-### Script file for complex commands
+#### Script file for complex commands
 
 For longer commands, save a script file at `~/.qwen/statusline-command.sh`:
 
@@ -244,18 +366,32 @@ 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). 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**: 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.
+**Both modes:**
+
+- **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).
+- **Output**: Up to 2 lines. Each line is rendered as a separate row 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.
 
+**Command mode only:**
+
+- **Timeout**: Commands that take longer than 5 seconds are killed. The status line clears on failure.
+- **Refresh**: 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).
+- **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`).
+
+**Preset mode only:**
+
+- **No external dependencies**: Preset items are computed internally — no shell commands, no `jq`, no timeouts.
+- **Theme integration**: When `useThemeColors` is `true` (default), the status line text uses the active `/theme` color. When `false`, dimmed footer styling is applied.
+- **PR lookup**: The `pull-request-number` item runs `gh pr view` in the background (2s timeout). It only triggers when the branch changes, not on every update.
+
 ## Troubleshooting
 
-| Problem                 | Cause                  | Fix                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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 — 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                                                                                                                                                                                                                                                                                                                                           |
+| Problem                     | Cause                          | Fix                                                                                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Status line not showing     | Config at wrong path           | Must be under `ui.statusLine`, not root-level `statusLine`                                                                                                                                                                                                                                                                                                                                             |
+| Empty output (command mode) | 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 (command mode)   | 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                                                                                                                                                                                                                                                                                                                                           |
+| Preset items missing        | Conditional items have no data | `git-branch` is hidden outside git repos; `context-used` is hidden when usage is 0; `branch-changes` is hidden when no files changed. This is expected — items appear once their data is available                                                                                                                                                                                                     |
+| PR number not showing       | `gh` CLI not installed         | Install [GitHub CLI](https://cli.github.com/) and authenticate with `gh auth login`. The lookup runs with a 2s timeout                                                                                                                                                                                                                                                                                 |

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

@@ -275,6 +275,66 @@ disallowedTools:
 ---
 ```
 
+#### Claude Code Compatibility Fields
+
+Qwen Code accepts the Claude Code 2.1.168 frontmatter fields below so you
+can drop a CC agent file into `.qwen/agents/` and have the supported fields
+parse identically. Optional fields with invalid values are silently dropped
+at parse time rather than rejected — the same lenient posture CC uses.
+
+| Field            | Type             | Notes                                                                                                                                                                                                                                                                            |
+| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `permissionMode` | enum string      | `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`. Mapped to `approvalMode` at parse time; when both are set, the explicit `approvalMode` wins.                                                                                                           |
+| `maxTurns`       | positive integer | Caps the agent's turn budget. Wired into `runConfig.max_turns` at runtime; when both are set, the top-level field wins. The legacy nested value is pruned from the on-disk file on save to avoid two sources of truth.                                                           |
+| `color`          | enum string      | Display color. Allowlist: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` (mirrors CC's `_Y`). The legacy qwen sentinel `auto` is preserved for backward compatibility. Other values are silently dropped on parse.                                         |
+| `mcpServers`     | record of specs  | Per-agent MCP server overrides. Merged with the session-level MCP server set when the agent spawns; on key collision the agent's spec wins (matching CC's `scope: 'agent'` semantics). Malformed entries are dropped per-key with a warning rather than failing the whole agent. |
+| `hooks`          | record of arrays | Per-agent hooks. Keys are CC hook event names (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, …); values are arrays of `{ matcher?, hooks: [...] }` definitions in the same shape as `settings.json`'s `hooks` field. Registered while the agent runs, removed when it stops.  |
+
+Example with all of the above:
+
+```
+---
+name: rigorous-reviewer
+description: Deep code review with a turn cap
+permissionMode: plan
+maxTurns: 50
+color: cyan
+tools:
+  - read_file
+  - grep_search
+  - glob
+mcpServers:
+  filesystem:
+    type: stdio
+    command: node
+    args: [/usr/local/lib/mcp-fs/server.js]
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: echo "review-agent about to run a shell command"
+---
+
+You are a code reviewer. Analyze the code thoroughly and report findings
+ordered by severity.
+```
+
+The remaining CC frontmatter fields — `effort`, `skills`, `initialPrompt`,
+`memory`, `isolation` — are documented in the declarative-agent design doc
+and land in follow-up PRs once the prerequisite infrastructure exists
+(`effort` needs a model-layer parameter; `memory` needs a scoped memory
+subsystem; `--agent` CLI flag enables `initialPrompt`; etc.).
+
+> **`hooks` v1 limitation.** While a subagent declaring `hooks` is running,
+> its hook entries fire for every matching event in the session, not only
+> for that subagent's own tool calls. If two subagents with different
+> per-agent hook sets run concurrently, both sets fire for both agents.
+> Per-agent scope filtering at hook-firing time is left to a follow-up;
+> for v1, prefer per-agent hooks that are safe to fire globally for the
+> duration of the agent's run (e.g. logging) over hooks that mutate
+> behavior.
+
 #### Example Usage
 
 ```