易良 5deddb722b docs(tools): sync shell.md with the shipped run_shell_command contract (#12841) ... * docs(tools): sync shell.md with the shipped run_shell_command contract Four statements in this file contradict the tool as shipped. is_background was documented as required -- twice in the arguments list and the Usage note, plus a "Required Background Parameter" section whose rationale was backwards. The schema is required: [command] (shell.ts:5762) and the parameter description says "Optional: ... If not specified, defaults to false (foreground execution)" (shell.ts:5743), so foreground is the fallback, not what the parameter exists to avoid. The foreground bullet list recommended cat and grep as one-time foreground commands, which the same tool description forbids in favour of the dedicated tools. #12532 replaced that list in the shipped description with one line; this mirrors it and states why the file tools are not candidates, so the list does not come back. "or by explicitly adding & to commands" offered & as a second control for backgrounding. On the managed background path a bare trailing & is stripped as redundant (stripTrailingBackgroundAmp, shell.ts:143, called at :4125). The sentence is now scoped to that path instead of claiming & never works: the example further down uses it with is_background=false, which is the unmanaged path, and is left alone deliberately. Verified against origin/main at e68822c815. No other docs file carries the "required" claim. Prettier clean. Docs only -- no code or test change. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs(tools): fix the fourth is_background mention to optional The Background execution choices bullet still called the parameter required, contradicting the rest of the page after this PR. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs(tools): state the actual trailing-& contract The page said a bare trailing & is "stripped as redundant" and that a command containing & backgrounds the call. Neither holds: validation rejects is_background:true with a trailing bare & before execution, the spawn-time strip only covers what validation does not classify, and a mid-command & never makes the tool return early. Rewrite the section lead, the background bullets, and the mislabeled example to the shipped contract. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs(tools): describe what a shell-level & actually does 56a0952a stated that a bare trailing `&` is stripped at spawn time and that `npm run dev &` with `is_background=false` runs in the foreground and blocks the turn. Neither holds. `stripTrailingBackgroundAmp` is called only from `executeBackground`, reached only when `is_background` is true; the foreground path passes the command through verbatim, so the shell detaches it and the result settles on 'close' or POST_EXIT_STREAM_DRAIN_MS after exit — ShellExecutionService names `sleep 10 &` as exactly that case. The difference that matters is tracking, not foreground versus background: only `is_background=true` registers a background task that `task_stop` can reach. Also drop the `Background PIDs` field name, which no code emits; the managed return carries `id` and `pid`. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>		2026-09-27 12:18:21 +00:00
..
_meta.ts	docs(tools): document monitor tool (#4356)	2026-05-25 15:25:07 +08:00
exit-plan-mode.md	fix(core): Require explicit approval to exit Plan mode (#6967)	2026-07-17 02:51:11 +00:00
file-system.md	feat(core): make list_directory opt-in (disabled by default) (#9424)	2026-08-21 07:24:05 +00:00
introduction.md	feat(core): enable the built-in web_search by default on ModelStudio Standard/Token Plan (#11348)	2026-09-09 04:08:29 +00:00
mcp-server.md	feat(mcp): add MCP 2026 core and WebShell Apps host (#8992)	2026-08-23 18:34:30 +00:00
monitor.md	docs(tools): document monitor tool (#4356)	2026-05-25 15:25:07 +08:00
multi-file.md	docs: fix stale defaults, CLI syntax, and tool naming drift (#5158)	2026-06-15 20:06:34 +08:00
sandbox.md	Merge branch 'main' into feat/sandbox-config-improvements	2026-03-06 14:38:39 +08:00
shell.md	docs(tools): sync shell.md with the shipped run_shell_command contract (#12841)	2026-09-27 12:18:21 +00:00
task.md	docs(agent): clarify parameter preconditions (#9580)	2026-08-24 02:27:09 +00:00
todo-write.md	feat(core): make todo_write opt-in (#10645)	2026-09-05 04:27:13 +00:00
web-fetch.md	fix(core): allow web_fetch JSON fallback (#5660)	2026-06-24 14:18:33 +00:00
web-search.md	docs(tools): add Firecrawl to the web search MCP services (#12646)	2026-09-24 16:00:24 +00:00