Skip to main content
Claude Code has access to a set of built-in tools that help it understand and modify your codebase. The tool names are the exact strings you use in permission rules, subagent tool lists, and hook matchers. To disable a tool entirely, add its name to the deny array in your permission settings. To add custom tools, connect an MCP server. To extend Claude with reusable prompt-based workflows, write a skill, which runs through the existing Skill tool rather than adding a new tool entry. The Permission required column shows whether the tool prompts in the default permission mode for paths inside the working directory. File-access tools marked No, including Read, Grep, and Glob, still prompt for paths outside the working directory and additional directories. Bash is marked Yes but runs a built-in set of read-only commands without prompting.

​
Configure tools with permission rules and hooks

For the most part, Claude decides when to use these tools and you don’t need to name them yourself when interacting with Claude. You reference tool names directly when defining permissions and other configuration: All of these accept the same rule format, ToolName(specifier). The specifier depends on the tool, and several tools share a format: Tools not listed here, such as ExitPlanMode or ShareOnboardingGuide, accept only the bare tool name with no specifier. An Edit(...) allow rule also grants read access to the same path, so you don’t need a matching Read(...) rule. A Read(...) deny rule also blocks the Edit tool on the same path, including creating a new file there, because editing requires reading the result back. The Read deny check on edits requires Claude Code v2.1.208 or later. Hook matcher fields use bare tool names, not the parenthesized rule format. See matcher patterns for the matching rules. For the field names each tool passes to tool_input in hooks, see the PreToolUse input reference.

​
Agent tool behavior

The Agent tool spawns a subagent in a separate context window. The subagent works through its task autonomously, then returns a single text result to the parent conversation. The parent doesn’t see the subagent’s intermediate tool calls or outputs, only that final result. To cap how many turns a subagent runs, set maxTurns in the subagent definition. The same Agent tool also launches forked subagents when fork mode is enabled. A fork inherits the full parent conversation instead of starting fresh, always runs in the background, and still surfaces permission prompts in your terminal. The rest of this section describes named subagents. Which tools a named subagent can use depends on the tools and disallowedTools fields in the subagent definition:
  • Neither field set: the subagent inherits every tool available to the parent.
  • tools only: the subagent gets only the listed tools.
  • disallowedTools only: the subagent gets every parent tool except the listed ones.
  • Both set: disallowedTools takes precedence. A tool listed in both is removed.
When a subagent’s tools list resolves to no tools at all, for example because every entry is misspelled or names a tool that isn’t available to subagents, the Agent tool returns an error listing those entries instead of launching the subagent. Before v2.1.208, the subagent launched with no tools and could return an empty or confusing result. Launching the subagent doesn’t itself prompt for permission. Claude Code checks the subagent’s own tool calls against your permission rules as it runs. As of v2.1.198, subagents run in the background by default; Claude runs one in the foreground when it needs the result before continuing.
  • Foreground subagents show the same permission prompts you would see in the main conversation, at the moment each tool call happens.
  • Background subagents surface permission prompts in your main session as of v2.1.186. The prompt names which subagent is asking, and pressing Esc denies that one tool call without stopping the subagent. Before v2.1.186, background subagents auto-denied any tool call that would otherwise prompt and continued without that tool.
To limit what a subagent can reach in the first place, narrow its tools field, leave Bash off the list, or set deny rules in your settings, as described in Control subagent capabilities. For more on choosing between foreground and background, see Run subagents in foreground or background.

​
Bash tool behavior

The Bash tool runs each command in a separate process.

​
What persists between commands

  • When Claude runs cd in the main session, the new working directory carries over to later Bash commands as long as it stays inside the project directory or an additional working directory you added with --add-dir, /add-dir, or additionalDirectories in settings. Subagent sessions never carry over working directory changes.
    • If cd lands outside those directories, Claude Code resets to the project directory and appends Shell cwd was reset to <dir> to the tool result.
    • To disable this carry-over so every Bash command starts in the project directory, set CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1.
  • Environment variables don’t persist. An export in one command won’t be available in the next.
  • Aliases and shell functions defined in your shell startup file are available. At session start, Claude Code sources ~/.zshrc, ~/.bashrc, or ~/.profile depending on your shell, captures the resulting aliases, functions, and shell options, and applies them to every Bash command.
Activate your virtualenv or conda environment before launching Claude Code. To make environment variables persist across Bash commands, set CLAUDE_ENV_FILE to a shell script before launching Claude Code, or use a SessionStart hook to populate it dynamically.

​
Timeout and output limits

Two limits bound each command:
  • Timeout: two minutes by default. Claude can request up to 10 minutes per command with the timeout parameter. Override the default and ceiling with BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS.
  • Output length: 30,000 characters by default. When a command produces more than that, Claude Code saves the full output to a file in the session directory and gives Claude the file path plus a short preview from the start. Claude reads or searches that file when it needs the rest. Raise the limit with BASH_MAX_OUTPUT_LENGTH, up to a hard ceiling of 150,000 characters.

​
Background commands

For long-running processes such as dev servers or watch builds, Claude can set run_in_background: true to start the command as a background task and continue working while it runs. List and stop background tasks with /tasks. In non-interactive mode with the -p flag, background tasks end shortly after the run’s final result. When a command reaches its timeout without finishing, Claude Code moves it to the background instead of stopping it, so Claude keeps working while the command runs to completion. Claude Code never auto-backgrounds a command that starts with sleep, and setting CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 disables auto-backgrounding along with the rest of the background task functionality. The result of a command moved this way states what happened:
  • When the timeout triggers the move, the result reports it explicitly: Command did not complete within its 120s timeout and was moved to the background, with the seconds matching the timeout that applied, followed by the task ID and the path of the file the output is being written to.
  • A cd, pushd, popd, or chdir inside a command that is moved to the background never carries over: the result states Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands., so Claude doesn’t act on a directory change that didn’t happen.

​
Edit tool behavior

The Edit tool performs exact string replacement. It takes an old_string and a new_string and replaces the first with the second. It doesn’t use regex or fuzzy matching. Three checks must pass for an edit to apply. Before any of them, a path matched by a Read deny rule is refused, including creating a new file there. The refusal requires Claude Code v2.1.208 or later.
  • Read-before-edit: Claude reads the file in the current conversation before editing it, and a read cut short with a PARTIAL view notice doesn’t count. Claude Opus 4.6, Claude Haiku 4.5, and older models always require the read. Newer models can edit an unread file when reading it wouldn’t need a permission prompt and the Read tool is available.
  • Match: old_string must appear in the file exactly as written. A single character of whitespace or indentation difference is enough to miss.
  • Uniqueness: old_string must appear exactly once. When it appears more than once, Claude either supplies a longer string with enough surrounding context to pin down one occurrence, or sets replace_all: true to replace them all.
A file that changed on disk after Claude last read it can still be edited when old_string matches the current content exactly and unambiguously and Claude Code can read the file without prompting. Matching against the file’s current content keeps this safe, and the result notes that the file carries other changes so Claude re-reads it before edits that depend on surrounding content. In any other case, such as a stale old_string or one that matches more than once without replace_all, Claude reads the file again before editing. The relaxed handling of unread and changed files requires Claude Code v2.1.208 or later; before that, Claude Code refused any edit to a file it hadn’t read in the conversation or that changed on disk after the read. Viewing a file with Bash also satisfies the read-before-edit requirement when the command is cat, head, tail, sed -n 'X,Yp', grep, egrep, or fgrep on a single file with no pipes or redirects. Piped output and other Bash commands don’t count toward the read-before-edit check. This affects edit eligibility only, not permissions. Read and Edit deny rules also apply to file commands Claude Code recognizes in Bash, such as cat, head, tail, sed, and grep, but not to arbitrary subprocesses that read or write files indirectly, like a Python or Node script that opens files itself. The set of commands recognized for deny rules is not the same as the read-before-edit list above: for example, egrep and fgrep count for read-before-edit but are not checked against Read deny rules. For OS-level enforcement that covers every process, enable the sandbox.

​
Glob tool behavior

The Glob tool finds files by name pattern. It supports standard glob syntax including ** for recursive directory matching:
  • **/*.js matches all .js files at any depth
  • src/**/*.ts matches all .ts files under src/
  • *.{json,yaml} matches .json and .yaml files in the current directory
Results are sorted by modification time and capped at 100 files. If the cap is hit, Claude sees a truncation flag in the result and can narrow the pattern. Glob doesn’t respect .gitignore by default, so it finds gitignored files alongside tracked ones. This differs from Grep, which skips gitignored files. To make Glob respect .gitignore, set CLAUDE_CODE_GLOB_NO_IGNORE=false before launching Claude Code. A pattern or path value that contains a null byte returns an error asking Claude to remove it.

​
Grep tool behavior

The Grep tool searches file contents for patterns. Where Glob finds files by name, Grep finds lines inside them. Grep is built on ripgrep and uses ripgrep’s regex syntax, not POSIX grep. Patterns that include regex metacharacters need escaping. For example, finding interface{} in Go code takes the pattern interface\{\}. A pattern, glob, or file type that ripgrep rejects returns an error that includes ripgrep’s diagnostic, so Claude can correct the input and search again. Before v2.1.208, Claude Code reported a rejected input as No files found instead of an error, even when the searched-for text existed in the target files. Three output modes control what comes back:
  • files_with_matches: file paths only, no line content. This is the default.
  • content: matching lines with file and line number. When the tool’s offset parameter points past the last match for a pattern that has matches, Grep returns No entries at this offset, so Claude widens or resets the offset instead of concluding the pattern doesn’t match.
  • count: match count per file, followed by a total across all matching files. The total covers every match even when the tool’s head_limit or offset parameters truncate the listed per-file entries. Before v2.1.208, the total only summed the listed entries.
Claude can scope results by file with the glob parameter, such as **/*.tsx, or by language with the type parameter, such as py or rust. By default, patterns match within a single line. Claude can set multiline: true to match across line boundaries. Grep respects .gitignore, so gitignored files are skipped. To search a gitignored file, Claude passes its path directly.

​
LSP tool behavior

The LSP tool gives Claude code intelligence from a running language server. After each file edit, it automatically reports type errors and warnings so Claude can fix issues without a separate build step. Claude can also call it directly to navigate code:
  • Jump to a symbol’s definition
  • Find all references to a symbol
  • Get type information at a position
  • List symbols in a file
  • Search for a symbol by name across the workspace
  • Find implementations of an interface
  • Trace call hierarchies
The tool is inactive until you install a code intelligence plugin for your language. The plugin bundles the language server configuration, and you install the server binary separately.

​
Monitor tool

The Monitor tool lets Claude watch something in the background and react when it changes, without pausing the conversation. Ask Claude to:
  • Tail a log file and flag errors as they appear
  • Poll a PR or CI job and report when its status changes
  • Watch a directory for file changes
  • Track output from any long-running script you point it at
  • Connect to a WebSocket feed and report each message as it arrives
For most watches, Claude writes a small script, runs it in the background, and receives each output line as it arrives. For a server that already pushes events, Claude can open a WebSocket instead of running a script. You keep working in the same session and Claude interjects when an event arrives. Stop a monitor by asking Claude to cancel it or by ending the session. When Monitor runs a command, it uses the same permission rules as Bash, so allow and deny patterns you have set for Bash apply here too. The WebSocket source has its own approval prompt. The tool is not available on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry. It is also not available when DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set. Plugins can declare monitors that start automatically when the plugin is active, instead of asking Claude to start them. See plugin monitors.

​
WebSocket source

The WebSocket source requires Claude Code v2.1.195 or later.
When a server already pushes events over a WebSocket, Claude can connect to it directly instead of writing a polling script. Each kind of socket activity either becomes an event or ends the watch:
  • Text messages: each one becomes one event, even when the message spans multiple lines.
  • Binary messages: not passed through. Claude receives a placeholder line such as [binary frame, 512 bytes] instead.
  • Messages larger than 1 MiB: the watch ends, so subscribe to a filtered feed where one exists.
  • Socket close: the watch ends and Claude receives the close code.
A WebSocket watch takes a ws input in place of command, and a single Monitor call can’t combine the two. The ws input has two fields: The timeout_ms and persistent inputs behave the same as they do for a command: the watch ends at the deadline unless persistent is set, and TaskStop cancels it early. Opening a WebSocket prompts for approval, and the prompt doesn’t offer an option to skip future prompts for the same host. Claude Code denies URLs that point at a private, link-local, or cloud-metadata address, including hostnames that resolve to one. It also denies hosts in sandbox.network.deniedDomains, and when allowManagedDomainsOnly is set in managed settings, any host outside the managed allowlist.

​
NotebookEdit tool behavior

NotebookEdit modifies a Jupyter notebook one cell at a time, targeting cells by their cell_id. It doesn’t perform string replacement across the notebook the way Edit does on plain files. Three edit modes control what happens to the target cell:
  • replace: overwrite the cell’s source. This is the default.
  • insert: add a new cell after the target. With no cell_id, the new cell goes at the start of the notebook. Requires cell_type set to code or markdown.
  • delete: remove the target cell.
Permission rules use the Edit(...) path format. A rule like Edit(notebooks/**) covers NotebookEdit calls on files in that directory.

​
PowerShell tool

The PowerShell tool lets Claude run PowerShell commands natively. On Windows, this means commands run in PowerShell instead of routing through Git Bash. How the tool becomes available depends on your platform:
  • Windows without Git Bash: the tool is enabled automatically.
  • Windows with Git Bash installed: the tool is rolling out progressively.
  • Linux, macOS, and WSL: the tool is opt-in.

​
Enable the PowerShell tool

Set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 in your environment or in settings.json:
On Windows, set the variable to 0 to opt out of the rollout. On Linux, macOS, and WSL, the tool requires PowerShell 7 or later: install pwsh and ensure it is on your PATH. On Windows, Claude Code auto-detects pwsh.exe for PowerShell 7+ with a fallback to powershell.exe for PowerShell 5.1. When the tool is enabled, Claude treats PowerShell as the primary shell. The Bash tool remains available for POSIX scripts when Git Bash is installed. Claude Code spawns PowerShell with -ExecutionPolicy Bypass at process scope only, so .ps1 scripts and module imports work on default Windows installs without changing the machine’s policy. Process-scope bypass doesn’t override Group Policy MachinePolicy or UserPolicy, so enterprise policies still apply. To respect the machine’s effective execution policy instead, set CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1.

​
Shell selection in settings, hooks, and skills

Three additional settings control where PowerShell is used:
  • "defaultShell": "powershell" in settings.json: routes interactive ! commands through PowerShell. Requires the PowerShell tool to be enabled.
  • "shell": "powershell" on individual command hooks: runs that hook in PowerShell. Hooks spawn PowerShell directly, so this works regardless of CLAUDE_CODE_USE_POWERSHELL_TOOL.
  • shell: powershell in skill frontmatter: runs !`command` blocks in PowerShell. Requires the PowerShell tool to be enabled.
The same main-session working-directory reset behavior described under the Bash tool section applies to PowerShell commands, including the CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR environment variable. As of v2.1.196, the PowerShell tool matches the Bash tool’s handling of search and diff exit codes. Exit code 1 from grep, egrep, fgrep, and git grep means no matches, and exit code 1 from git diff means differences exist, so these results aren’t reported to Claude as command failures.

​
Preview limitations

The PowerShell tool has the following known limitations during the preview:
  • PowerShell profiles are not loaded
  • On Windows, sandboxing is not supported

​
Read tool behavior

The Read tool takes a file path and returns the contents with line numbers. Claude is instructed to always pass absolute paths. By default, Read returns the file from the start. When a whole-file read exceeds the token limit, Read returns the first page with a PARTIAL view notice that tells Claude how much of the file it received and how to read more with offset and limit. A read that passes an explicit offset or limit and still exceeds the token limit returns an error. A read with an explicit limit stops as soon as the selected lines exceed what the token limit could ever fit and returns an error without loading the rest of the range. The error tells Claude to use a smaller limit, or to search for specific content with Grep instead when a single line is that large. Before v2.1.208, Claude Code loaded the whole range into memory before rejecting it, so a file with an extremely long single line could exhaust memory. Reading an empty file returns a notice that the file exists but its contents are empty, and an offset past the last line returns a notice giving the file’s line count. Before v2.1.208, reading an empty file returned the past-the-end notice instead. Read handles several file types beyond plain text:
  • Images: PNG, JPG, and other image formats are returned as visual content that Claude can see, not as raw bytes. Claude Code resizes and recompresses large images to fit the model’s image size limits before sending them, so Claude may see a downscaled version of a large screenshot. As of v2.1.196, an image that is still larger than 500KB after that resize is re-encoded as a JPEG at reduced quality with its pixel dimensions unchanged. If Claude misses fine pixel-level detail in a large image, ask it to crop the region of interest first, for example with ImageMagick via Bash.
  • PDFs: Claude reads short .pdf files whole. For PDFs longer than 10 pages, it reads in ranges with a pages parameter, such as "1-5", up to 20 pages at a time.
  • Jupyter notebooks: .ipynb files return all cells with their outputs, including code, markdown, and visualizations.
Read only reads files, not directories. Claude uses ls via the Bash tool to list directory contents.

​
WebFetch tool behavior

WebFetch takes a URL and a prompt describing what to extract. It fetches the page, converts the response to Markdown when the server returns HTML, and runs the prompt against the content using a small, fast model. For most fetches, Claude receives that model’s answer, not the raw page. The conversion step is not configurable. This makes WebFetch lossy by design. The extraction prompt determines what reaches Claude, so a result that says a page doesn’t mention something may only mean the prompt didn’t ask about it. Ask Claude to fetch again with a more specific prompt, or use curl via Bash for the unprocessed page. A few behaviors shape the response Claude receives:
  • HTTP URLs are automatically upgraded to HTTPS.
  • Large pages are truncated to a fixed character limit before processing.
  • Responses are cached for 15 minutes, so repeated fetches of the same URL return quickly.
  • When a URL redirects to a different host, WebFetch returns a text result that names the original URL and the redirect target instead of following it. Claude then fetches the new URL with a second WebFetch call.
In the default and acceptEdits permission modes, WebFetch prompts the first time it reaches a new domain, except for a built-in set of preapproved documentation domains that fetch without a prompt. To allow another domain in advance without a prompt, add a permission rule like WebFetch(domain:example.com). The auto and bypassPermissions permission modes skip the prompt entirely. An explicit WebFetch(domain:...) rule in deny, ask, or allow takes precedence over the preapproved set, so you can block a preapproved domain or require a prompt for it. WebFetch sets a User-Agent header beginning with Claude-User, and an Accept header that prefers Markdown over HTML so servers that support content negotiation can return Markdown directly. You configure sandbox network rules separately, so a domain you want a sandboxed process to reach still needs an explicit sandbox permission rule.

​
WebSearch tool behavior

WebSearch runs a query against Anthropic’s web search backend and returns result titles and URLs. It doesn’t fetch the result pages. To read a page Claude finds in search results, it follows up with WebFetch. The tool may issue up to eight backend searches per call, refining the search internally before returning results. Claude can scope results with allowed_domains to include only certain hosts, or blocked_domains to exclude them. The two lists can’t be combined in a single call. The search backend is not configurable. To search with a different provider, add an MCP server that exposes a search tool. WebSearch permission rules take no specifier. A bare WebSearch entry in allow or deny is the only form.
WebSearch is available on the Claude API, Claude Platform on AWS, and Microsoft Foundry. On Google Cloud’s Agent Platform it works with Claude 4 and later models, including Opus, Sonnet, and Haiku. Amazon Bedrock doesn’t expose the server-side web search tool.

​
Write tool behavior

The Write tool creates a new file or overwrites an existing one with the full content provided. It doesn’t append or merge. If the target path already exists, Claude must have read that file at least once in the current conversation before overwriting it. A Write to an unread existing file fails with an error. This constraint doesn’t apply to new files. Viewing the file with Bash also satisfies this requirement under the same rules described in Edit tool behavior. For partial changes to an existing file, Claude uses Edit instead of Write.

​
Check which tools are available

Your exact tool set depends on your provider, platform, and settings. To check what’s loaded in a running session, ask Claude directly:
Claude gives a conversational summary. For exact MCP tool names, run /mcp.
The advisor tool is a server tool that the API runs, rather than a tool that Claude Code implements. It has no name you can reference in permission rules or hook matchers.

​
See also

  • MCP servers: add custom tools by connecting external servers
  • Permissions: permission system, rule syntax, and tool-specific patterns
  • Subagents: configure tool access for subagents
  • Hooks: run custom commands before or after tool execution