skip to content

In Claude Code on macOS or Linux, why do code searches show up as Bash calls rather than Grep or Glob, and what does that change?

level: seniorimportance: nice to knowfreq 6%

answer

  1. default tool set differs by platform
  2. embedded bfs and ugrep
  3. hooks and rules see Bash
  4. --tools or --allowedTools restores them
  5. Windows keeps both by default

basics

~20 s

On macOS, Linux and WSL, Glob and Grep are absent from the default tool set; Claude searches with find and grep through Bash, backed by embedded bfs and ugrep. Hooks and permission rules therefore see Bash calls, not Grep or Glob.

solid answer

~40 s

Claude Code leaves `Glob` and `Grep` out of the default tool set on macOS, Linux and WSL; on Windows both stay. Claude runs `find` and `grep` through the `Bash` tool instead, and in its shell those run embedded `bfs` and `ugrep`. The consequence is configuration: the searches reach hooks and permission rules as `Bash` calls, so a hook matching `Grep` never fires and a `Read` deny rule doesn't cover a recursive `grep` that never names the file. They come back if you name `Glob` or `Grep` in `--tools` or `--allowedTools` at launch (an allow rule in settings doesn't count), if `Bash` is removed by a deny rule, `--disallowedTools` or `--restricted`, or for a subagent that lists them in `tools` without `Bash`.

code

bash · 8 lines
bash
# Default on macOS, Linux and WSL: no Glob or Grep tool; searches run through Bash
claude

# Naming either tool in --allowedTools restores both for this session
claude --allowedTools "Grep"

# --tools restricts the built-in set to exactly the tools listed
claude --tools "Read,Edit,Write,Bash,Glob,Grep"

go deeper

for a junior

Know that on macOS and Linux Claude searches with grep and find through Bash by default, so seeing Bash in the transcript for a search is normal.

for a middle

Explain the platform split, the embedded bfs and ugrep, and the launch flags that restore Glob and Grep, including why a settings allow rule doesn't.

for a senior

Trace the consequences for guards: hooks that must match Bash, read-only commands that never prompt, and Read deny rules that miss a recursive grep, and say which boundary actually holds.

for a principal

Decide whether a fleet standardises on the dedicated search tools or on Bash-aware hooks and the sandbox, weighing consistent auditing across Windows and Unix against speed and simplicity.

## The default tool set depends on the platform Claude Code has two dedicated search tools. **`Glob`** finds files by name pattern (`**/*.ts`), and **`Grep`** searches file contents with ripgrep syntax. On **Windows** both are part of the default tool set. On **macOS, Linux and WSL**, Claude Code leaves them out, and Claude searches with `find` and `grep` through the **`Bash`** tool instead. In Claude's shell those two commands run embedded versions of **`bfs`** and **`ugrep`**, so the search is fast without a separate tool round trip. The CLI reference says the same thing from the flag side: `--tools "default"` leaves out `Glob` and `Grep` on macOS, Linux and WSL. Windows differs twice over: `Glob` and `Grep` stay in the default set, and the `PowerShell` tool, on by default for claude.ai and Console accounts there, runs shell commands natively; on macOS, Linux and WSL that tool is opt-in. ## What changes when a search is a Bash call The tools reference is explicit: "the searches reach your hooks and permission rules as `Bash` calls". That has several consequences: - **Hook matchers.** A `PreToolUse` or `PostToolUse` hook whose matcher is `Grep` or `Glob` never fires on these platforms. To inspect searches, match `Bash` and look at the command itself. - **Permission prompts.** `grep` and `find` are in Bash's built-in read-only set, so ordinary searches run without a prompt in every mode. `find` with `-exec` or `-delete`, or with an unquoted glob that could expand into a flag, still prompts in Manual mode. - **Read deny rules.** `Read` deny rules apply best-effort to the `Grep` and `Glob` tools, and to Bash file commands that **name** a file. They don't apply to a command that reads files without naming them, such as `grep -r pattern .` run above the protected file. Content you meant to hide from searches needs the sandbox for OS-level enforcement. - **Output handling.** A search result is a Bash result: past roughly 30,000 characters, Claude receives a file path and a preview rather than the whole output inline. - **Exit status.** `grep`, `rg` and `find` exiting 1 count as a valid result for the Bash tool, so "no matches" is not reported as a failed command. - **Transcript reading.** A transcript full of `Bash` calls running `grep` is the expected default, not Claude ignoring its tools. ## What the dedicated tools do when present Where they are in the tool set, the two tools behave differently from their shell counterparts: - **`Glob`** returns matches sorted by modification time, capped at 100 files with a truncation flag, and doesn't respect `.gitignore` by default. - **`Grep`** uses ripgrep's regex syntax, skips gitignored files, and returns file paths only by default, with `content` and `count` as the other output modes. ## Getting Glob and Grep back The dedicated tools return in exactly the cases the tools reference lists: 1. You name `Glob` or `Grep` in **`--tools`** or **`--allowedTools`** when the session starts, or in the equivalent Agent SDK options. With `--tools` you get the ones you list; naming either in `--allowedTools` restores both. 2. A permissions **deny rule**, the **`--disallowedTools`** flag or **`--restricted`** removes `Bash` from the session, so Claude still has a way to search. 3. A **subagent** lists `Glob` or `Grep` in its `tools` field and leaves out `Bash`. The tools come back for that subagent only, or for the whole session when it runs as the main agent through `--agent` or the `agent` setting. What does **not** work: an allow rule for `Grep` in a settings file. That rule grants permission to a tool the session doesn't have. ## Comparing the two paths | Aspect | `Grep` / `Glob` tools | `grep` / `find` through `Bash` | | :- | :- | :- | | Default on macOS, Linux, WSL | Absent | Used | | Hook matcher that sees it | `Grep`, `Glob` | `Bash` | | Read deny rules | Applied best-effort | Applied only when the command names the file | | `.gitignore` | `Grep` skips ignored files; `Glob` doesn't by default | Depends on the command | ## Diagnosing a search that "skipped" your guard When a team reports that a guard on searches never triggers, check three things in order: the platform (is `Grep` even in the tool set?), the matcher or rule (does it name `Bash`?), and the command shape (does it name the protected path, or recurse past it?). Rewriting a matcher from `Grep` to `Bash` fixes the first two; the third needs a boundary below Claude Code's own rules.

  • Why doesn't adding Grep to permissions.allow in a Claude Code settings file bring the Grep tool back on Linux?
    An allow rule grants permission to use a tool; it doesn't add a tool the session lacks. Only naming `Glob` or `Grep` in `--tools` or `--allowedTools` at launch, removing `Bash`, or a subagent that lists them in `tools` without `Bash` restores them.
  • How should a Claude Code hook that audits code searches be written on macOS or Linux?
    Match `Bash` rather than `Grep` or `Glob`, then inspect the command for `grep`, `find` or `rg`. On a mixed fleet that includes Windows, match the dedicated tools as well, and `PowerShell` where that tool is enabled, so the same audit sees every search path.

  • Claude Code always ships Grep and Glob; a Bash grep means it ignored them.
  • An allow rule for Grep in settings.json brings the Grep tool back.
  • A hook matching Grep catches every code search on any platform.
  • Read deny rules hide a file from any recursive grep Claude runs.
  • Searching through Bash always triggers a permission prompt in Manual mode.