mirror of
https://github.com/QwenLM/qwen-code.git
synced 2026-11-13 05:41:49 -10:00
易良andQwen-Coder
5deddb722b
* 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 ate68822c815. No other docs file carries the "required" claim. Prettier clean. Docs only -- no code or test change. Co-authored-by: Qwen-Coder <[email protected]> * 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 <[email protected]> * 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 <[email protected]> * docs(tools): describe what a shell-level & actually does56a0952astated 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 <[email protected]> --------- Co-authored-by: Qwen-Coder <[email protected]>