Skip to main content

Shell, Web, and Background Tasks

These tools run shell commands, fetch web pages, search the web, and manage background tasks. They reach outside the project, so permission rules and the sandbox matter most for them. For example, Bash with run_in_background set to true starts a long command and returns at once. The Yes and No columns are explained on Tools.

You approve or deny each call by rule or by prompt. The switches are CLAUDE_CODE_USE_POWERSHELL_TOOL, CLAUDE_CODE_DISABLE_WEB_FETCH=1, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, or a deny rule. PowerShell, the WebFetch switch, and GetTask are gated.

Tools​

Source: Tools Reference, Configure Permissions, Create Custom Subagents, and the program.

ToolStatusWhat It DoesHow It WorksAvailable InRead-OnlyParallelDeferred
BashDocumentedRuns a shell command.See Bash Parameters.Main session and subagents. Kept in background subagents.❌❌❌
PowerShellDocumented GatedRuns a Windows PowerShell command.Same parameters as Bash, but command is a PowerShell command and description has a shorter text.Main session and subagents. Kept in background subagents.❌❌❌
MonitorDocumentedStreams the output of a background command or a WebSocket as notifications.See Monitor Parameters.Main session and subagents. Kept in background subagents.❌✅✅
WebFetchDocumented GatedFetches a URL and applies a prompt to the page text.url (URL string, required), prompt (string, required), offset (int, 0 or more, optional, character offset for a long page). The off switch needs 2.1.285 or later.Main session and subagents. Kept in background subagents.✅✅✅
WebSearchDocumented GatedSearches the web.query (string, at least 2 characters, required), allowed_domains (string array, optional), blocked_domains (string array, optional).Main session and subagents. Kept in background subagents.✅✅✅
TaskStopDocumentedStops a running background task.task_id (string, optional; also takes a teammate or named background agent by ID or name), shell_id (string, optional, deprecated).Main session and subagents. Kept in background subagents.❌✅✅
GetTaskUndocumented GatedChecks a background shell command by task ID.taskId (string, required).❓✅✅❌

Bash Parameters​

ParameterWhat It DoesRequired
commandThe shell command to run.✅
timeoutTime limit in milliseconds for a foreground command.❌
descriptionA short note on what the command does.❌
run_in_backgroundStarts the command as a background task and returns at once.❌
dangerouslyDisableSandboxRuns the command without the sandbox.❌
allowed_domainsNetwork hosts that this command may reach. Offered only when the sandbox network lists are on.❌
machineName of an attached machine to run the call on. Offered only when machines are attached.❌

PowerShell takes the same parameters, except that it has no allowed_domains unless the network lists are on. Source: the program (the Bash input schema).

Monitor Parameters​

ParameterWhat It DoesRequired
descriptionShort note on what is watched, shown in notifications.✅
commandShell command whose output lines become notifications.❌
wsWebSocket target to stream. Give exactly one of command or ws.❌
timeout_msKills the monitor after this time. At least 1000, with a default and a cap.❌
persistentRuns until TaskStop or the end of the session, with no timeout.❌
allowed_domainsNetwork hosts for a command monitor, offered only when the sandbox network lists are on.❌

Source: the program (the Monitor input schema).

Example​

Turn on the PowerShell tool and turn off web fetching for one project.

.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "CLAUDE_CODE_DISABLE_WEB_FETCH": "1"
  }
}

How It Works​

  • Background subagents keep Bash, PowerShell, Monitor, TaskStop, WebFetch, and WebSearch. See Create Custom Subagents.
  • CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 also disables auto-backgrounding and the Ctrl+B key (Environment Variables).
  • A true value for CLAUDE_AUTO_BACKGROUND_TASKS gives the Agent tool a 120000 ms auto-background time. Source: the program (the env name). It is not in the saved docs, so it is Undocumented.