From 35e69632855dc8dae9fcaaafd7038d7a2193afa1 Mon Sep 17 00:00:00 2001 From: Dragon <52599892+DragonnZhang@users.noreply.github.com> Date: Mon, 25 May 2026 15:25:07 +0800 Subject: [PATCH] docs(tools): document monitor tool (#4356) --- docs/developers/tools/_meta.ts | 1 + docs/developers/tools/introduction.md | 1 + docs/developers/tools/monitor.md | 154 ++++++++++++++++++++++++++ 3 files changed, 156 insertions(+) create mode 100644 docs/developers/tools/monitor.md diff --git a/docs/developers/tools/_meta.ts b/docs/developers/tools/_meta.ts index 2662563769..9f68d150ce 100644 --- a/docs/developers/tools/_meta.ts +++ b/docs/developers/tools/_meta.ts @@ -3,6 +3,7 @@ export default { 'file-system': 'File System', 'multi-file': 'Multi-File Read', shell: 'Shell', + monitor: 'Monitor', 'todo-write': 'Todo Write', task: 'Task', 'exit-plan-mode': 'Exit Plan Mode', diff --git a/docs/developers/tools/introduction.md b/docs/developers/tools/introduction.md index 1dafb14c88..2a6b3e2fae 100644 --- a/docs/developers/tools/introduction.md +++ b/docs/developers/tools/introduction.md @@ -45,6 +45,7 @@ Qwen Code's built-in tools can be broadly categorized as follows: - **[File System Tools](./file-system.md):** For interacting with files and directories (reading, writing, listing, searching, etc.). - **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell commands. +- **[Monitor Tool](./monitor.md) (`monitor`):** For running long-lived shell commands that stream output back as background task notifications. - **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content from URLs. - **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories, often used by the `@` command. - **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions. diff --git a/docs/developers/tools/monitor.md b/docs/developers/tools/monitor.md new file mode 100644 index 0000000000..c004552aa1 --- /dev/null +++ b/docs/developers/tools/monitor.md @@ -0,0 +1,154 @@ +# Monitor Tool (`monitor`) + +This document describes the `monitor` tool for Qwen Code. + +## Description + +Use `monitor` to start a long-running shell command that streams stdout and +stderr lines back to the agent as background task notifications. It is intended +for watch-style commands where new output matters over time, such as tailing +logs, watching build output, polling a health endpoint, or observing file +changes. + +The monitor runs in the background, so the agent can continue working while +events arrive. Each non-empty output line becomes a notification event, subject +to throttling. + +### Arguments + +`monitor` takes the following arguments: + +- `command` (string, required): The shell command to run and monitor. +- `description` (string, optional): A brief description of what the monitor is + watching. The display text is truncated to 80 characters. +- `max_events` (number, optional): Stop after this many notification events. + Must be a positive integer. Defaults to `1000`; maximum `10000` (values + outside this range are rejected, not silently clamped). +- `idle_timeout_ms` (number, optional): Stop if the command produces no output + for this many milliseconds. Must be a positive integer. Defaults to `300000` + (5 minutes); maximum `600000` (10 minutes), and values outside this range are + rejected. +- `directory` (string, optional): An absolute path to run the command in. Must + resolve (after symlink canonicalization) inside one of the registered + workspace directories, and must not be inside the user-skills directory. If + omitted, Qwen Code uses the project root. + +## How to use `monitor` with Qwen Code + +The model chooses the `monitor` tool when it needs to observe a process over +time instead of collecting a single command result. A successful invocation +returns a monitor ID, the command, the event limit, and the idle timeout. + +Usage: + +``` +monitor(command="tail -f logs/app.log", description="app log stream") +``` + +Monitor output is visible in the conversation as task notifications. You can +also inspect running and completed monitors with `/tasks` or the interactive +Background tasks dialog. + +To stop a running monitor, use the `task_stop` tool with the monitor ID: + +``` +task_stop(task_id="mon_abc123def4567890") +``` + +## `monitor` examples + +Watch an application log: + +``` +monitor( + command="tail -f logs/app.log", + description="application log stream", + max_events=200 +) +``` + +Monitor a dev server or build watcher: + +``` +monitor( + command="npm run build -- --watch", + description="watch build output", + idle_timeout_ms=600000 +) +``` + +Poll a local health endpoint: + +``` +monitor( + command="while true; do curl -s http://localhost:8080/health; sleep 5; done", + description="local health check", + max_events=120 +) +``` + +Run from a specific workspace directory: + +``` +monitor( + command="npm run dev", + description="frontend dev server", + directory="/absolute/path/to/workspace/packages/web" +) +``` + +## Monitor vs. background shell commands + +Use `monitor` when the agent needs to react to streaming output while the +command keeps running. Use `run_shell_command` instead when you need a one-shot +result or the complete command output. + +| Need | Use | +| :----------------------------------------------------- | :--------------------------------------- | +| Watch logs, build output, or periodic status updates | `monitor` | +| Run a one-time command and read the full output | `run_shell_command(is_background=false)` | +| Start a daemon that does not produce meaningful output | `run_shell_command(is_background=true)` | + +Do not add `&` to monitor commands. A trailing `&`, such as +`tail -f log &`, is stripped because the monitor manages backgrounding itself. +A non-final `&`, such as `cmd1 & cmd2`, is rejected outright; restructure such +commands without backgrounding instead. + +## Important notes + +- **Auto-stop behavior:** Monitors stop automatically when they reach + `max_events`, when `idle_timeout_ms` elapses without output, or when the + underlying command exits on its own. A monitor's status reflects the + command's outcome, not a tool error: a clean exit (`code 0`) becomes + `completed`, a non-zero exit code becomes `failed` with message + `Exit code N`, and termination by signal becomes `failed` with message + `Killed by signal SIG`. Commands cannot be interactive because stdin is + closed. When a monitor stops, Qwen Code sends `SIGTERM` to the command's + process group and escalates to `SIGKILL` after about 200 ms. On Windows, it + uses `taskkill /f /t`. If the Qwen Code process itself is hard-killed, + crashes, or runs out of memory, the detached process group is not cleaned up + automatically; recover by stopping the monitor with `task_stop` before exit + or by terminating the process group manually. +- **Concurrency limit:** Qwen Code allows up to 16 running monitors per CLI + session as a single shared pool. Monitors started by subagents count against + the same cap as monitors started by the main agent. Stop an existing monitor + before starting another if the limit is reached. +- **Output handling:** Stdout and stderr are merged into a single notification + stream with no stream prefix. Empty lines are ignored, ANSI color and control + characters are stripped, and individual lines longer than 2000 characters are + truncated. High-volume output is rate-limited with a burst of 5 events and + about 1 event per second after that; lines beyond the rate limit are dropped, + not buffered. Monitor output flows into the agent context as + `` content. Structural notification tags are defanged, but + the model still reads each line's text, so avoid monitoring streams that + external parties can write to unless you trust the model to ignore embedded + instructions. +- **Permissions:** `monitor` has its own permission boundary and permission + rules, such as `Monitor(git status)`. Read-only commands are automatically + allowed; commands that modify state require user approval; commands containing + command substitution (`$(...)`, backticks, `<(...)`, or `>(...)`) are rejected + outright. The `tools.core` and `tools.exclude` settings for + `run_shell_command` do not apply to `monitor`. +- **Workspace restriction:** The optional `directory` must be an absolute path + that resolves inside a registered workspace directory and outside the + user-skills directory. Symlinks that point outside the workspace are rejected.