Skip to content

fix: add explicit is_background param for shell tool#445

Merged
Mingholy merged 3 commits into
mainfrom
feat/shell-tool-background-support
Aug 27, 2025
Merged

fix: add explicit is_background param for shell tool#445
Mingholy merged 3 commits into
mainfrom
feat/shell-tool-background-support

Conversation

@Mingholy

@Mingholy Mingholy commented Aug 25, 2025 •
edited
Loading

Copy link
Copy Markdown
Collaborator

TLDR

Experimental optimization requests for review and evaluation.

Added explicit is_background parameter to the shell tool to provide better control over background vs foreground execution of shell commands. This improvement makes it clearer when commands should run in the background (like development servers) versus foreground (like build commands), enhancing user experience and tool reliability.

Dive Deeper

Added an explicit is_background boolean parameter to the shell tool for better control over command execution modes.

What Changed:

  • New is_background parameter (defaults to false)
  • Background commands show [background] indicator in descriptions
  • Updated documentation with clear usage examples
  • Maintains backward compatibility with existing & syntax

Why This Matters:

  • Makes intent explicit: background for long-running processes (servers, watchers), foreground for one-time commands (build, lint, test)
  • Improves user experience with clearer execution control
  • Reduces confusion about when commands will block vs run in background

Reviewer Test Plan

Create a simple Hono HTTP server project to test the new is_background parameter:

  1. Setup Test Project:

    mkdir test-hono-server && cd test-hono-server
npm init -y
npm install hono @types/node typescript eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

  2. Create Basic Files:

    • src/server.ts: Simple Hono server
    • eslint.config.js: ESLint configuration
    • tsconfig.json: TypeScript configuration
    • package.json: Add dev/build scripts

  3. Test Foreground Commands (should wait for completion):

    # These should block and show results
run_shell_command(command="npx eslint src/", is_background=false, description="Run ESLint")
run_shell_command(command="npx tsc --noEmit", is_background=false, description="TypeScript check")
run_shell_command(command="npm run build", is_background=false, description="Build project")

  4. Test Background Commands (should return immediately):

    # This should start server in background and return immediately
run_shell_command(command="npm run dev", is_background=true, description="Start Hono dev server")

  5. Verify Behavior:

    • Foreground commands should show complete output and wait for finish
    • Background command should return immediately with [background] indicator
    • Dev server should be accessible on localhost while other commands can run
    • Background processes should appear in Background PIDs field

Testing Matrix

🍏 🪟 🐧
npm run ✅ ❓ ❓
npx ✅ ❓ ❓
Docker ❓ ❓ ❓
Podman ❓ - -
Seatbelt ❓ - -

Linked issues / bugs

Fixes #346

@Mingholy Mingholy requested a review from koalazf99 August 25, 2025 14:09
@Mingholy Mingholy force-pushed the feat/shell-tool-background-support branch from 13964e2 to 303c561 Compare August 25, 2025 14:12
@github-actions

github-actions Bot commented Aug 26, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

Code Coverage Summary

Package Lines Statements Functions Branches
CLI 73.75% 73.75% 78.81% 81.09%
Core 74.09% 74.09% 74.13% 82.22%
CLI Package - Full Text Report 
-------------------|---------|----------|---------|---------|-------------------
File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
-------------------|---------|----------|---------|---------|-------------------
All files          |   73.75 |    81.09 |   78.81 |   73.75 |                   
 src               |   55.24 |    73.58 |   66.66 |   55.24 |                   
  gemini.tsx       |   31.83 |    58.82 |      50 |   31.83 | ...01-314,324-341 
  ...ractiveCli.ts |   93.22 |    71.42 |     100 |   93.22 | ...,71-73,119,122 
  ...ActiveAuth.ts |   95.45 |    93.33 |     100 |   95.45 | 25-26             
 src/commands      |   94.11 |      100 |      50 |   94.11 |                   
  mcp.ts           |   94.11 |      100 |      50 |   94.11 | 26                
 src/commands/mcp  |   95.49 |    80.43 |    90.9 |   95.49 |                   
  add.ts           |   97.26 |    85.71 |     100 |   97.26 | 109-112,119       
  list.ts          |   90.56 |    80.76 |      80 |   90.56 | ...10-112,137-138 
  remove.ts        |     100 |    66.66 |     100 |     100 | 19-23             
 src/config        |   91.23 |    81.39 |   81.39 |   91.23 |                   
  auth.ts          |   78.72 |    90.47 |      25 |   78.72 | ...59,62-63,66-67 
  config.ts        |   96.42 |    86.99 |      70 |   96.42 | ...78,458,629-633 
  extension.ts     |   78.35 |    84.37 |     100 |   78.35 | ...07-111,120-121 
  keyBindings.ts   |     100 |      100 |     100 |     100 |                   
  sandboxConfig.ts |   51.35 |    16.66 |   66.66 |   51.35 | ...43,53-69,74-91 
  settings.ts      |   83.57 |    77.52 |   93.33 |   83.57 | ...91-392,452-453 
  ...ingsSchema.ts |     100 |      100 |     100 |     100 |                   
  ...tedFolders.ts |   91.96 |    86.95 |     100 |   91.96 | ...09,116-121,139 
 src/generated     |     100 |      100 |     100 |     100 |                   
  git-commit.ts    |     100 |      100 |     100 |     100 |                   
 src/patches       |       0 |        0 |       0 |       0 |                   
  is-in-ci.ts      |       0 |        0 |       0 |       0 | 1-17              
 src/services      |   61.42 |    88.13 |   72.22 |   61.42 |                   
  ...mandLoader.ts |     100 |      100 |     100 |     100 |                   
  ...andService.ts |     100 |      100 |     100 |     100 |                   
  ...mandLoader.ts |   92.09 |    91.89 |     100 |   92.09 | 176-181,250-257   
  ...omptLoader.ts |    9.39 |    57.14 |   33.33 |    9.39 | ...44-167,173-230 
  types.ts         |       0 |        0 |       0 |       0 | 1                 
 ...mpt-processors |   95.18 |    94.73 |     100 |   95.18 |                   
  ...tProcessor.ts |     100 |      100 |     100 |     100 |                   
  ...lProcessor.ts |   93.54 |    92.85 |     100 |   93.54 | 67-70             
  types.ts         |     100 |      100 |     100 |     100 |                   
 src/test-utils    |   90.56 |    81.81 |      75 |   90.56 |                   
  ...omMatchers.ts |   69.69 |       50 |      50 |   69.69 | 30-33,35-37,43-45 
  ...andContext.ts |     100 |      100 |     100 |     100 |                   
 src/ui            |   58.25 |    71.72 |    62.5 |   58.25 |                   
  App.tsx          |    56.9 |    60.78 |   33.33 |    56.9 | ...1183,1209-1238 
  ...tionNudge.tsx |    7.89 |      100 |       0 |    7.89 | 26-102            
  colors.ts        |   87.75 |      100 |      80 |   87.75 | 12-13,18-19,48-49 
  constants.ts     |     100 |      100 |     100 |     100 |                   
  keyMatchers.ts   |   95.65 |    95.65 |     100 |   95.65 | 29-30             
  ...tic-colors.ts |   89.47 |      100 |      80 |   89.47 | 15-16             
  types.ts         |     100 |      100 |     100 |     100 |                   
 src/ui/commands   |   81.05 |    83.05 |   81.35 |   81.05 |                   
  aboutCommand.ts  |     100 |    55.55 |     100 |     100 | 23-30             
  authCommand.ts   |     100 |      100 |     100 |     100 |                   
  bugCommand.ts    |   78.46 |    42.85 |     100 |   78.46 | 32-35,72-81       
  chatCommand.ts   |   94.16 |    83.67 |     100 |   94.16 | ...07-208,210-211 
  clearCommand.ts  |     100 |      100 |     100 |     100 |                   
  ...essCommand.ts |     100 |    88.88 |     100 |     100 | 69                
  copyCommand.ts   |     100 |      100 |     100 |     100 |                   
  corgiCommand.ts  |     100 |      100 |     100 |     100 |                   
  ...ryCommand.tsx |   70.12 |    73.07 |     100 |   70.12 | ...22-123,158-166 
  docsCommand.ts   |     100 |      100 |     100 |     100 |                   
  editorCommand.ts |     100 |      100 |     100 |     100 |                   
  ...onsCommand.ts |     100 |      100 |     100 |     100 |                   
  helpCommand.ts   |     100 |      100 |     100 |     100 |                   
  ideCommand.ts    |    55.6 |    77.27 |   44.44 |    55.6 | ...09-219,227-237 
  initCommand.ts   |   81.15 |    66.66 |     100 |   81.15 | 50,64-69,71-76    
  mcpCommand.ts    |   82.29 |    82.95 |   83.33 |   82.29 | ...83-384,437-444 
  memoryCommand.ts |   60.74 |    92.59 |   42.85 |   60.74 | ...15,222-243,267 
  ...acyCommand.ts |     100 |      100 |     100 |     100 |                   
  quitCommand.ts   |     100 |      100 |     100 |     100 |                   
  ...oreCommand.ts |   93.79 |    91.42 |     100 |   93.79 | 54-55,84-89       
  ...ngsCommand.ts |     100 |      100 |     100 |     100 |                   
  ...hubCommand.ts |   79.33 |    46.15 |     100 |   79.33 | ...16-119,122-125 
  statsCommand.ts  |   84.48 |       75 |     100 |   84.48 | 24-32             
  ...tupCommand.ts |     100 |      100 |     100 |     100 |                   
  themeCommand.ts  |     100 |      100 |     100 |     100 |                   
  toolsCommand.ts  |     100 |      100 |     100 |     100 |                   
  types.ts         |     100 |      100 |     100 |     100 |                   
  vimCommand.ts    |   44.44 |      100 |       0 |   44.44 | 14-24             
 src/ui/components |   71.44 |    82.68 |   73.33 |   71.44 |                   
  AboutBox.tsx     |     100 |       50 |     100 |     100 | 102               
  AsciiArt.ts      |     100 |      100 |     100 |     100 |                   
  AuthDialog.tsx   |    72.1 |    81.81 |      50 |    72.1 | ...26-130,138-144 
  ...nProgress.tsx |   16.66 |      100 |       0 |   16.66 | 18-62             
  ...Indicator.tsx |   15.15 |      100 |       0 |   15.15 | 17-47             
  ...ryDisplay.tsx |   89.47 |    33.33 |     100 |   89.47 | 20-21             
  ...ryDisplay.tsx |   92.04 |    94.44 |     100 |   92.04 | 82-87,92          
  ...geDisplay.tsx |     100 |      100 |     100 |     100 |                   
  ...gProfiler.tsx |      24 |      100 |       0 |      24 | 13-36             
  ...esDisplay.tsx |   10.52 |      100 |       0 |   10.52 | 24-82             
  ...ngsDialog.tsx |    7.29 |      100 |       0 |    7.29 | 27-172            
  ...ustDialog.tsx |     100 |      100 |     100 |     100 |                   
  Footer.tsx       |   75.92 |       70 |     100 |   75.92 | ...07-112,131-138 
  ...ngSpinner.tsx |      80 |    33.33 |     100 |      80 | 29,31-32          
  Header.tsx       |   78.72 |    57.14 |     100 |   78.72 | 36-39,51-53,60-62 
  Help.tsx         |    3.27 |      100 |       0 |    3.27 | 17-173            
  ...emDisplay.tsx |      70 |    56.25 |     100 |      70 | ...59-64,84-91,94 
  InputPrompt.tsx  |   88.84 |    81.94 |     100 |   88.84 | ...94-496,599-603 
  ...Indicator.tsx |     100 |      100 |     100 |     100 |                   
  ...geDisplay.tsx |   25.92 |      100 |       0 |   25.92 | 14-36             
  ...tsDisplay.tsx |     100 |      100 |     100 |     100 |                   
  ...KeyPrompt.tsx |   62.33 |    31.25 |     100 |   62.33 | ...58-111,115-123 
  PrepareLabel.tsx |      60 |       80 |     100 |      60 | 35-48             
  ...hProgress.tsx |     100 |      100 |     100 |     100 |                   
  ...ryDisplay.tsx |     100 |      100 |     100 |     100 |                   
  ...ngsDialog.tsx |   89.36 |    87.01 |     100 |   89.36 | ...23-336,342-358 
  ...ionDialog.tsx |   85.29 |      100 |   33.33 |   85.29 | 36-39,44-51       
  ...Indicator.tsx |   44.44 |      100 |       0 |   44.44 | 12-17             
  ...MoreLines.tsx |      60 |       25 |     100 |      60 | 24-27,33-40       
  StatsDisplay.tsx |   98.39 |    86.66 |     100 |   98.39 | 173-175           
  ...nsDisplay.tsx |   88.05 |    71.42 |     100 |   88.05 | 36-41,96-98       
  ThemeDialog.tsx  |    5.33 |      100 |       0 |    5.33 | 34-310            
  Tips.tsx         |      16 |      100 |       0 |      16 | 17-45             
  ...tsDisplay.tsx |     100 |     87.5 |     100 |     100 | 30-31             
  ...ification.tsx |   36.36 |      100 |       0 |   36.36 | 15-22             
 ...nents/messages |   63.15 |     81.3 |   57.14 |   63.15 |                   
  ...onMessage.tsx |   18.51 |      100 |       0 |   18.51 | 22-49             
  DiffRenderer.tsx |   96.18 |    81.92 |     100 |   96.18 | ...16-217,221,283 
  ErrorMessage.tsx |     100 |      100 |     100 |     100 |                   
  ...niMessage.tsx |   18.51 |      100 |       0 |   18.51 | 20-43             
  ...geContent.tsx |   19.04 |      100 |       0 |   19.04 | 25-43             
  InfoMessage.tsx  |     100 |      100 |     100 |     100 |                   
  ...onMessage.tsx |   35.87 |     62.5 |      20 |   35.87 | ...64-199,238-266 
  ...upMessage.tsx |   10.11 |      100 |       0 |   10.11 | 27-126            
  ToolMessage.tsx  |   87.76 |       80 |     100 |   87.76 | ...,91-95,169-171 
  UserMessage.tsx  |     100 |      100 |     100 |     100 |                   
  ...llMessage.tsx |   36.36 |      100 |       0 |   36.36 | 17-25             
 ...ponents/shared |    80.8 |    76.45 |   95.45 |    80.8 |                   
  MaxSizedBox.tsx  |   81.14 |     82.2 |   88.88 |   81.14 | ...08-509,614-615 
  ...tonSelect.tsx |   80.92 |    66.66 |     100 |   80.92 | ...52,155-156,226 
  text-buffer.ts   |   78.17 |    78.28 |   96.77 |   78.17 | ...1821,1861,1911 
  ...er-actions.ts |   86.71 |    67.79 |     100 |   86.71 | ...08-609,810-812 
 src/ui/contexts   |   84.39 |    76.66 |     100 |   84.39 |                   
  ...owContext.tsx |   91.07 |    81.81 |     100 |   91.07 | 46-47,59-61       
  ...onContext.tsx |   87.01 |      100 |     100 |   87.01 | 102-105,114-119   
  ...gsContext.tsx |   83.33 |       50 |     100 |   83.33 | 17-18             
  ...ngContext.tsx |   71.42 |       50 |     100 |   71.42 | 17-20             
  ...deContext.tsx |   76.08 |       50 |     100 |   76.08 | 46-47,51-58,76-77 
 src/ui/editors    |   93.18 |    85.71 |   66.66 |   93.18 |                   
  ...ngsManager.ts |   93.18 |    85.71 |   66.66 |   93.18 | 48,62-63          
 src/ui/hooks      |   78.91 |    82.31 |   83.78 |   78.91 |                   
  ...dProcessor.ts |    78.4 |       79 |     100 |    78.4 | ...55-458,469-487 
  ...dProcessor.ts |   95.52 |    69.23 |     100 |   95.52 | ...17-218,223-224 
  ...dProcessor.ts |   82.24 |    71.42 |   83.33 |   82.24 | ...72-376,442-470 
  ...Completion.ts |   92.73 |    89.47 |     100 |   92.73 | ...85-186,219-222 
  ...uthCommand.ts |    7.46 |      100 |       0 |    7.46 | 18-92             
  ...tIndicator.ts |     100 |      100 |     100 |     100 |                   
  ...ketedPaste.ts |     100 |      100 |     100 |     100 |                   
  ...ompletion.tsx |   94.73 |    81.81 |     100 |   94.73 | ...98-199,201-202 
  useCompletion.ts |    92.4 |     87.5 |     100 |    92.4 | ...,95-96,100-101 
  ...leMessages.ts |   98.68 |       95 |     100 |   98.68 | 55                
  ...orSettings.ts |     100 |      100 |     100 |     100 |                   
  useFocus.ts      |     100 |      100 |     100 |     100 |                   
  ...olderTrust.ts |     100 |      100 |     100 |     100 |                   
  ...miniStream.ts |   73.95 |    73.37 |     100 |   73.95 | ...76-877,907-997 
  ...BranchName.ts |   91.66 |    84.61 |     100 |   91.66 | 57-63             
  ...oryManager.ts |   98.41 |    93.33 |     100 |   98.41 | 43                
  ...putHistory.ts |    92.5 |    85.71 |     100 |    92.5 | 62-63,71,93-95    
  useKeypress.ts   |   57.71 |    86.88 |      80 |   57.71 | ...46-292,399-401 
  ...rdProtocol.ts |     100 |      100 |     100 |     100 |                   
  ...gIndicator.ts |     100 |      100 |     100 |     100 |                   
  useLogger.ts     |      25 |      100 |       0 |      25 | 14-32             
  ...raseCycler.ts |   95.45 |       75 |     100 |   95.45 | ...64-165,183-185 
  ...cySettings.ts |     3.6 |      100 |       0 |     3.6 | 22-143            
  useQwenAuth.ts   |     100 |      100 |     100 |     100 |                   
  ...lScheduler.ts |   78.92 |    94.44 |     100 |   78.92 | ...01-204,290-300 
  ...oryCommand.ts |       0 |        0 |       0 |       0 | 1-7               
  ...ompletion.tsx |     100 |     92.3 |     100 |     100 | 77                
  ...ngsCommand.ts |    87.5 |      100 |     100 |    87.5 | 13,17             
  ...ellHistory.ts |   91.26 |    79.41 |     100 |   91.26 | ...67,112-113,123 
  ...oryCommand.ts |       0 |        0 |       0 |       0 | 1-75              
  ...Completion.ts |      94 |    92.53 |     100 |      94 | 58-61,69-72,93    
  ...tateAndRef.ts |   59.09 |      100 |     100 |   59.09 | 23-31             
  ...rminalSize.ts |   18.18 |      100 |       0 |   18.18 | 12-32             
  ...emeCommand.ts |   46.98 |       75 |     100 |   46.98 | ...4,70-71,77-100 
  useTimer.ts      |   88.09 |    85.71 |     100 |   88.09 | 44-45,51-53       
  vim.ts           |   83.57 |     79.5 |     100 |   83.57 | ...38,742-750,759 
 src/ui/privacy    |   14.52 |      100 |       0 |   14.52 |                   
  ...acyNotice.tsx |   10.38 |      100 |       0 |   10.38 | 21-117            
  ...acyNotice.tsx |   14.28 |      100 |       0 |   14.28 | 16-59             
  ...acyNotice.tsx |   12.19 |      100 |       0 |   12.19 | 16-62             
  ...acyNotice.tsx |   30.76 |      100 |       0 |   30.76 | 19-36,39-41       
 src/ui/themes     |   99.52 |    66.66 |     100 |   99.52 |                   
  ansi-light.ts    |     100 |      100 |     100 |     100 |                   
  ansi.ts          |     100 |      100 |     100 |     100 |                   
  atom-one-dark.ts |     100 |      100 |     100 |     100 |                   
  ayu-light.ts     |     100 |      100 |     100 |     100 |                   
  ayu.ts           |     100 |      100 |     100 |     100 |                   
  color-utils.ts   |     100 |      100 |     100 |     100 |                   
  default-light.ts |     100 |      100 |     100 |     100 |                   
  default.ts       |     100 |      100 |     100 |     100 |                   
  dracula.ts       |     100 |      100 |     100 |     100 |                   
  github-dark.ts   |     100 |      100 |     100 |     100 |                   
  github-light.ts  |     100 |      100 |     100 |     100 |                   
  googlecode.ts    |     100 |      100 |     100 |     100 |                   
  no-color.ts      |     100 |      100 |     100 |     100 |                   
  qwen-dark.ts     |     100 |      100 |     100 |     100 |                   
  qwen-light.ts    |     100 |      100 |     100 |     100 |                   
  ...tic-tokens.ts |     100 |      100 |     100 |     100 |                   
  ...-of-purple.ts |     100 |      100 |     100 |     100 |                   
  theme-manager.ts |   91.66 |       80 |     100 |   91.66 | ...03,207,234-235 
  theme.ts         |     100 |     41.3 |     100 |     100 | 225-240           
  xcode.ts         |     100 |      100 |     100 |     100 |                   
 src/ui/utils      |   62.68 |    85.49 |   81.96 |   62.68 |                   
  ...Colorizer.tsx |   77.24 |       80 |     100 |   77.24 | ...51-154,190-216 
  ...olePatcher.ts |      96 |       75 |     100 |      96 | 59-60             
  ...nRenderer.tsx |   26.51 |       75 |     100 |   26.51 | 32-137            
  ...wnDisplay.tsx |   85.84 |    87.69 |     100 |   85.84 | ...72-280,313-336 
  ...eRenderer.tsx |   78.09 |    76.19 |     100 |   78.09 | 55-83             
  ...boardUtils.ts |   32.25 |     37.5 |     100 |   32.25 | ...55-114,129-145 
  commandUtils.ts  |   97.36 |     92.3 |     100 |   97.36 | 68,72             
  computeStats.ts  |     100 |      100 |     100 |     100 |                   
  displayUtils.ts  |     100 |      100 |     100 |     100 |                   
  formatters.ts    |   90.47 |    95.83 |     100 |   90.47 | 57-60             
  isNarrowWidth.ts |     100 |      100 |     100 |     100 |                   
  ...olDetector.ts |   13.88 |      100 |      50 |   13.88 | 16-97             
  ...nUtilities.ts |   69.84 |    85.71 |     100 |   69.84 | 75-91,100-101     
  ...mConstants.ts |     100 |      100 |     100 |     100 |                   
  terminalSetup.ts |    4.03 |      100 |       0 |    4.03 | 40-340            
  textUtils.ts     |   88.88 |    83.33 |     100 |   88.88 | 14-15             
  updateCheck.ts   |     100 |    80.95 |     100 |     100 | 26-38             
 src/utils         |   45.54 |    92.09 |   85.71 |   45.54 |                   
  checks.ts        |   33.33 |      100 |       0 |   33.33 | 23-28             
  cleanup.ts       |      96 |    85.71 |     100 |      96 | 35                
  ...ScopeUtils.ts |     100 |      100 |     100 |     100 |                   
  events.ts        |     100 |      100 |     100 |     100 |                   
  gitUtils.ts      |   94.66 |    82.35 |     100 |   94.66 | 75-78             
  ...AutoUpdate.ts |   81.14 |    95.23 |   66.66 |   81.14 | 85-99,125-132     
  ...lationInfo.ts |     100 |      100 |     100 |     100 |                   
  package.ts       |   88.88 |       80 |     100 |   88.88 | 33-34             
  readStdin.ts     |    3.44 |      100 |       0 |    3.44 | 7-39              
  resolvePath.ts   |   66.66 |       25 |     100 |   66.66 | 12-13,16,18-19    
  sandbox.ts       |       0 |        0 |       0 |       0 | 1-960             
  settingsUtils.ts |   84.48 |    93.68 |   96.55 |   84.48 | ...05-306,357-401 
  spawnWrapper.ts  |     100 |      100 |     100 |     100 |                   
  ...upWarnings.ts |   23.07 |      100 |       0 |   23.07 | 14-40             
  ...entEmitter.ts |     100 |      100 |     100 |     100 |                   
  ...upWarnings.ts |     100 |      100 |     100 |     100 |                   
  version.ts       |     100 |       50 |     100 |     100 | 11                
 ...ed-integration |   26.06 |        0 |       0 |   26.06 |                   
  acp.ts           |    2.89 |        0 |       0 |    2.89 | ...52-288,291-338 
  schema.ts        |     100 |      100 |     100 |     100 |                   
  ...ntegration.ts |    3.29 |        0 |       0 |    3.29 | ...89-784,799-849 
-------------------|---------|----------|---------|---------|-------------------
Core Package - Full Text Report 
-------------------|---------|----------|---------|---------|-------------------
File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
-------------------|---------|----------|---------|---------|-------------------
All files          |   74.09 |    82.22 |   74.13 |   74.09 |                   
 src               |     100 |      100 |     100 |     100 |                   
  index.ts         |     100 |      100 |     100 |     100 |                   
 src/__mocks__/fs  |     100 |      100 |     100 |     100 |                   
  promises.ts      |     100 |      100 |     100 |     100 |                   
 src/code_assist   |   72.15 |    76.19 |   71.05 |   72.15 |                   
  codeAssist.ts    |   18.51 |      100 |       0 |   18.51 | 13-35             
  converter.ts     |   89.23 |    96.15 |   81.81 |   89.23 | 178-182,201-211   
  oauth2.ts        |   75.23 |     61.7 |      80 |   75.23 | ...03-409,416-417 
  server.ts        |    50.6 |       80 |   53.84 |    50.6 | ...73-214,217-219 
  setup.ts         |   86.66 |    78.94 |     100 |   86.66 | ...,92-94,118-124 
  types.ts         |     100 |      100 |     100 |     100 |                   
 src/config        |   74.86 |    84.04 |   45.45 |   74.86 |                   
  config.ts        |   74.55 |    84.04 |   45.45 |   74.55 | ...42-843,862-863 
  models.ts        |     100 |      100 |     100 |     100 |                   
 src/core          |   76.73 |    75.37 |   77.21 |   76.73 |                   
  client.ts        |   79.38 |    77.27 |      75 |   79.38 | ...12,915,922-971 
  ...tGenerator.ts |   66.91 |    68.96 |     100 |   66.91 | ...47,180,190-233 
  ...lScheduler.ts |   67.69 |    70.83 |   77.27 |   67.69 | ...51-858,861-871 
  geminiChat.ts    |    54.2 |    70.83 |   51.72 |    54.2 | ...66-667,670-671 
  geminiRequest.ts |     100 |      100 |     100 |     100 |                   
  logger.ts        |   85.96 |    83.33 |     100 |   85.96 | ...60-261,277-281 
  ...tGenerator.ts |   15.33 |      100 |      20 |   15.33 | ...56-185,188-189 
  ...olExecutor.ts |   90.07 |       50 |     100 |   90.07 | 84-85,87-96,127   
  ...tGenerator.ts |   87.27 |     71.6 |     100 |   87.27 | ...1657,1660,1662 
  prompts.ts       |   93.66 |    88.23 |      75 |   93.66 | ...,96-97,429-486 
  subagent.ts      |   92.18 |    83.75 |     100 |   92.18 | ...05-613,656-657 
  tokenLimits.ts   |   14.28 |      100 |       0 |   14.28 | 15-32             
  turn.ts          |   83.68 |    83.33 |     100 |   83.68 | ...68-271,284-285 
 src/ide           |   39.79 |    87.27 |   41.66 |   39.79 |                   
  constants.ts     |     100 |      100 |     100 |     100 |                   
  detect-ide.ts    |   49.35 |      100 |      50 |   49.35 | 23-62             
  ide-client.ts    |   16.66 |    83.33 |   13.04 |   16.66 | ...96-397,400-404 
  ide-installer.ts |   59.79 |     62.5 |     100 |   59.79 | ...,81-82,104-117 
  ideContext.ts    |   83.65 |      100 |     100 |   83.65 | 74-90             
 src/mcp           |    74.2 |    80.16 |   76.31 |    74.2 |                   
  ...h-provider.ts |   86.36 |      100 |   33.33 |   86.36 | ...85,89,93,97-98 
  ...h-provider.ts |      77 |    65.62 |      90 |      77 | ...61-663,668-670 
  ...en-storage.ts |     100 |      100 |     100 |     100 |                   
  oauth-utils.ts   |   42.85 |     87.5 |      80 |   42.85 | ...32-192,216-252 
 src/mocks         |     100 |      100 |     100 |     100 |                   
  msw.ts           |     100 |      100 |     100 |     100 |                   
 src/prompts       |   26.41 |      100 |      25 |   26.41 |                   
  mcp-prompts.ts   |   18.18 |      100 |       0 |   18.18 | 11-19             
  ...t-registry.ts |   28.57 |      100 |   28.57 |   28.57 | ...42,48-55,68-73 
 src/qwen          |   91.25 |    82.88 |   95.34 |   91.25 |                   
  ...tGenerator.ts |   93.85 |    85.93 |     100 |   93.85 | ...40-241,297-298 
  qwenOAuth2.ts    |   90.07 |     81.3 |    92.3 |   90.07 | ...65-776,812-813 
 src/services      |   94.36 |    94.36 |   86.84 |   94.36 |                   
  ...eryService.ts |   93.33 |    88.46 |   85.71 |   93.33 | 31,39,84,109-110  
  gitService.ts    |   77.52 |      100 |      60 |   77.52 | ...08-112,115-119 
  ...ionService.ts |   99.23 |    97.05 |     100 |   99.23 | 287-288           
  ...ionService.ts |   96.47 |    91.17 |     100 |   96.47 | 132-134,207-208   
 src/telemetry     |   64.86 |    81.81 |   69.56 |   64.86 |                   
  constants.ts     |     100 |      100 |     100 |     100 |                   
  ...-exporters.ts |   26.47 |      100 |       0 |   26.47 | ...80,83-84,87-88 
  index.ts         |     100 |      100 |     100 |     100 |                   
  ...t.circular.ts |       0 |        0 |       0 |       0 | 1-67              
  ...t.circular.ts |       0 |        0 |       0 |       0 | 1-125             
  loggers.ts       |   64.92 |    69.56 |   64.28 |   64.92 | ...64-381,384-399 
  metrics.ts       |   61.98 |       96 |    62.5 |   61.98 | ...37-159,162-185 
  sdk.ts           |   72.95 |    26.66 |     100 |   72.95 | ...47,151-152,154 
  ...l-decision.ts |     100 |      100 |     100 |     100 |                   
  types.ts         |   79.47 |     91.3 |   78.26 |   79.47 | ...44-353,356-367 
  uiTelemetry.ts   |   99.24 |    95.45 |     100 |   99.24 | 118               
 ...learcut-logger |   35.15 |    65.85 |   35.71 |   35.15 |                   
  ...cut-logger.ts |   29.57 |       65 |   37.03 |   29.57 | ...73-774,777-780 
  ...tadata-key.ts |   87.69 |      100 |       0 |   87.69 | 228-238           
 ...ry/qwen-logger |    70.8 |    74.35 |   73.33 |    70.8 |                   
  event-types.ts   |       0 |        0 |       0 |       0 |                   
  qwen-logger.ts   |    70.8 |    73.68 |   72.41 |    70.8 | ...69-473,477-482 
 src/test-utils    |    98.8 |    91.66 |     100 |    98.8 |                   
  config.ts        |     100 |      100 |     100 |     100 |                   
  ...aceContext.ts |     100 |      100 |     100 |     100 |                   
  tools.ts         |   97.77 |     87.5 |     100 |   97.77 | 61                
 src/tools         |   69.53 |     81.5 |   76.38 |   69.53 |                   
  diffOptions.ts   |     100 |      100 |     100 |     100 |                   
  edit.ts          |   81.45 |    82.89 |   85.71 |   81.45 | ...80-481,503-542 
  glob.ts          |   85.83 |    78.72 |    87.5 |   85.83 | ...29-236,313-314 
  grep.ts          |   61.84 |    81.05 |   78.57 |   61.84 | ...46-650,660-661 
  ls.ts            |   96.81 |    90.16 |     100 |   96.81 | 136-140,323-324   
  mcp-client.ts    |   35.85 |    80.48 |   38.09 |   35.85 | ...1176,1180-1183 
  mcp-tool.ts      |   93.33 |    91.37 |    87.5 |   93.33 | ...55-165,227-228 
  memoryTool.ts    |   75.46 |    83.07 |   90.47 |   75.46 | ...05-406,490-574 
  ...iable-tool.ts |     100 |    84.61 |     100 |     100 | 94,101            
  read-file.ts     |    95.9 |     92.3 |    87.5 |    95.9 | ...10-112,209-210 
  ...many-files.ts |   79.61 |    72.58 |   85.71 |   79.61 | ...04-505,512-513 
  shell.ts         |   87.03 |    76.47 |     100 |   87.03 | ...48-449,460-461 
  tool-error.ts    |     100 |      100 |     100 |     100 |                   
  tool-registry.ts |   49.03 |     67.5 |   70.58 |   49.03 | ...62-364,387-395 
  tools.ts         |   80.38 |    89.18 |   63.63 |   80.38 | ...27-428,444-450 
  web-fetch.ts     |   50.56 |    64.28 |      70 |   50.56 | ...31-232,234-235 
  web-search.ts    |    9.52 |      100 |      20 |    9.52 | ...9,92-93,96-189 
  write-file.ts    |   83.46 |    78.78 |      80 |   83.46 | ...91-392,464-498 
 src/utils         |   84.15 |    87.16 |   87.43 |   84.15 |                   
  LruCache.ts      |   70.96 |     62.5 |     100 |   70.96 | 20-22,28,30-34    
  bfsFileSearch.ts |   89.02 |    90.47 |     100 |   89.02 | 86-94             
  browser.ts       |    8.69 |      100 |       0 |    8.69 | 17-53             
  editCorrector.ts |    77.3 |    61.11 |   91.66 |    77.3 | ...65-677,711,725 
  editor.ts        |   97.63 |    94.54 |     100 |   97.63 | 154,224,227-228   
  ...entContext.ts |     100 |      100 |     100 |     100 |                   
  errorParsing.ts  |     100 |     92.3 |     100 |     100 | 76,80,86          
  ...rReporting.ts |   83.72 |    84.61 |     100 |   83.72 | 82-86,107-115     
  errors.ts        |   39.02 |       60 |      75 |   39.02 | 21-25,41-57,61-67 
  fetch.ts         |   34.04 |      100 |       0 |   34.04 | 22-27,31-57       
  fileUtils.ts     |   95.25 |       90 |     100 |   95.25 | ...05-110,357-363 
  formatters.ts    |   54.54 |       50 |     100 |   54.54 | 12-16             
  ...eUtilities.ts |   96.03 |    95.83 |     100 |   96.03 | 28-29,57-58       
  ...rStructure.ts |   95.96 |    94.93 |     100 |   95.96 | ...14-117,345-347 
  ...noreParser.ts |     100 |    89.47 |     100 |     100 | 27,47             
  gitUtils.ts      |   51.21 |     90.9 |      50 |   51.21 | 40-41,50-73       
  ...yDiscovery.ts |   87.27 |    76.92 |   77.77 |   87.27 | ...32-333,336-337 
  ...tProcessor.ts |   93.68 |    88.75 |   84.61 |   93.68 | ...80-281,384-385 
  ...Inspectors.ts |     100 |      100 |     100 |     100 |                   
  ...kerChecker.ts |   83.33 |    83.33 |     100 |   83.33 | 64-65,75-80,88-94 
  openaiLogger.ts  |    19.1 |      100 |   33.33 |    19.1 | ...96-116,124-131 
  partUtils.ts     |     100 |      100 |     100 |     100 |                   
  paths.ts         |   84.61 |       90 |   77.77 |   84.61 | ...92-193,201-202 
  ...rDetection.ts |   76.85 |    84.31 |     100 |   76.85 | ...25-126,166-167 
  retry.ts         |   63.98 |    76.19 |     100 |   63.98 | ...74-294,339-354 
  safeJsonParse.ts |     100 |      100 |     100 |     100 |                   
  ...nStringify.ts |     100 |      100 |     100 |     100 |                   
  ...aValidator.ts |      80 |    57.14 |     100 |      80 | 23-24,26-27       
  ...r-launcher.ts |   78.57 |     87.5 |   66.66 |   78.57 | ...33,135,153-188 
  session.ts       |     100 |      100 |     100 |     100 |                   
  shell-utils.ts   |   98.26 |    97.36 |     100 |   98.26 | 76-77,94-95       
  summarizer.ts    |     100 |    88.88 |     100 |     100 | 91                
  ...emEncoding.ts |      98 |    94.11 |     100 |      98 | 106-107           
  testUtils.ts     |   84.44 |    72.72 |   83.33 |   84.44 | 27-28,34-35,70-72 
  textUtils.ts     |    12.5 |      100 |       0 |    12.5 | 15-34             
  user_account.ts  |   97.72 |    96.42 |     100 |   97.72 | 102-103           
  user_id.ts       |    75.6 |       60 |      75 |    75.6 | 19-20,28-33,46-48 
  ...aceContext.ts |   80.37 |    74.19 |      80 |   80.37 | ...17-121,149-150 
 ...ils/filesearch |   97.24 |     93.2 |     100 |   97.24 |                   
  crawlCache.ts    |     100 |      100 |     100 |     100 |                   
  fileSearch.ts    |   95.58 |     90.9 |     100 |   95.58 | ...89-190,221-222 
  ignore.ts        |     100 |      100 |     100 |     100 |                   
  result-cache.ts  |     100 |     92.3 |     100 |     100 | 46                
-------------------|---------|----------|---------|---------|-------------------

For detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run.

@github-actions github-actions Bot added the bug label Aug 26, 2025
@github-actions

github-actions Bot commented Aug 26, 2025

Copy link
Copy Markdown
Contributor

📋 Review Summary

This PR introduces an explicit is_background parameter to the shell tool, providing better control over background vs foreground execution of shell commands. This enhancement makes it clearer when commands should run in the background (like development servers) versus foreground (like build commands), improving user experience and tool reliability. The changes include updates to the tool implementation, documentation, and comprehensive test coverage.

🔍 General Feedback

  • The implementation is well-structured and follows good practices
  • Documentation has been updated comprehensively with clear usage examples
  • Test coverage is thorough, covering various scenarios including edge cases
  • The change maintains backward compatibility with existing & syntax
  • Good attention to detail in handling command wrapping and background process detection

🎯 Specific Feedback

🟡 High

  • File: packages/core/src/tools/shell.ts:416 - The schema definition marks is_background as a required parameter, but the interface ShellToolParams defines it as optional (is_background?: boolean). This inconsistency could lead to runtime errors when the parameter is not provided. Consider making the schema consistent with the interface by marking it as optional, or update the interface to match the schema.

🟢 Medium

  • File: packages/core/src/tools/shell.ts:360 - The tool description in the schema has extensive documentation about background/foreground execution. While comprehensive, this might make the help text in UI a bit verbose. Consider whether this level of detail is necessary in the schema description or if it could be simplified.

🔵 Low

  • File: packages/core/src/tools/shell.ts:64 - The comment "append background indicator" could be more descriptive. Consider updating it to explain why this indicator is added (e.g., "append background indicator for user clarity").

✅ Highlights

  • Well-implemented feature with clear separation of concerns
  • Comprehensive documentation updates with practical examples
  • Thorough test coverage including edge cases
  • Good backward compatibility maintenance
  • Clear user guidance on when to use background vs foreground execution

@pomelo-nwu

pomelo-nwu commented Aug 26, 2025

Copy link
Copy Markdown
Collaborator

@Mingholy This is a great feature—perhaps we could submit a PR to the upstream Gemini CLI.

tanzhenxin
tanzhenxin approved these changes Aug 26, 2025
View reviewed changes
Comment thread packages/core/src/tools/shell.ts
},
},
required: ['command'],
required: ['command', 'is_background'],

@tanzhenxin tanzhenxin Aug 26, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should set is_background as optional parameter, since it has default value as false.

@Mingholy

Mingholy commented Aug 27, 2025

Copy link
Copy Markdown
Collaborator Author

@tanzhenxin Setting is_background as an optional parameter may not work as expected. Did a little test:
is_background is not required:
image
During a cold start, if no additional instructions are given, the model tends to execute commands like node server.js or npm run start in the foreground, even though this is mentioned in the tool description.
While is_background is required:
image
I assume that when a model is forced to provide an is_background parameter, it is more likely to follow the instructions in the tool description to make the decision.

Based on the result above, I updated the docs to make a clear explanation and leave the discussion here.

@tanzhenxin

tanzhenxin commented Aug 27, 2025

Copy link
Copy Markdown
Collaborator

@tanzhenxin Setting is_background as an optional parameter may not work as expected. Did a little test: is_background is not required: image During a cold start, if no additional instructions are given, the model tends to execute commands like node server.js or npm run start in the foreground, even though this is mentioned in the tool description. While is_background is required: image I assume that when a model is forced to provide an is_background parameter, it is more likely to follow the instructions in the tool description to make the decision.

Based on the result above, I updated the docs to make a clear explanation and leave the discussion here.

LGTM!

@Mingholy Mingholy merged commit de279b5 into main Aug 27, 2025
17 checks passed
@Mingholy Mingholy deleted the feat/shell-tool-background-support branch August 27, 2025 09:46
@PhilipAD PhilipAD mentioned this pull request Aug 27, 2025
Open
zhutao100 added a commit to zhutao100/qwen-code that referenced this pull request Sep 17, 2025
@zhutao100
Revert "fix: add explicit is_background param for shell tool (QwenLM#445
f084d73 
)"

This reverts commit de279b5.
zhutao100 added a commit to zhutao100/qwen-code that referenced this pull request Sep 18, 2025
@zhutao100
Revert "fix: add explicit is_background param for shell tool (QwenLM#445
00cc176 
)"

This reverts commit de279b5.
zhutao100 added a commit to zhutao100/qwen-code that referenced this pull request Sep 27, 2025
@zhutao100
Revert "fix: add explicit is_background param for shell tool (QwenLM#445
85e110b 
)"

This reverts commit de279b5.
zhutao100 added a commit to zhutao100/qwen-code that referenced this pull request Sep 30, 2025
@zhutao100
Revert "fix: add explicit is_background param for shell tool (QwenLM#445
ae920ff 
)"

This reverts commit de279b5.
zhutao100 added a commit to zhutao100/qwen-code that referenced this pull request Oct 20, 2025
@zhutao100
Revert "fix: add explicit is_background param for shell tool (QwenLM#445
d604b89 
)"

This reverts commit de279b5.
@pomelo-nwu pomelo-nwu mentioned this pull request Oct 27, 2025
Closed
xaelistic pushed a commit to xaelistic/qwen-code that referenced this pull request Jun 7, 2026
@Mingholy
fix: add explicit is_background param for shell tool (QwenLM#445)
15a3aa2 
* fix: add explicit background param for shell tool

* fix: explicit param schema

* docs(shelltool): update `is_background` description
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tanzhenxin tanzhenxin tanzhenxin approved these changes

@koalazf99 koalazf99 Awaiting requested review from koalazf99

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

During npm start development request qwen-cli hangs for minutes

4 participants

@Mingholy @pomelo-nwu @tanzhenxin @MochiMosa