Oh My Pi

Oh My Pi is an open-source terminal coding agent published by can1357 as a fork of Pi. Its model-facing file family is six dedicated tools: read, write, edit, bash, glob, and grep. The read tool takes one path string with an optional selector suffix and reads files, directories, archives, SQLite databases, images, documents, URLs, and internal resources through the same parameter. The default edit mode is hashline: read output carries a [path#TAG] snapshot header, and the edit tool requires that tag in every section it touches. Search, edit parsing, and the shell run in a native Rust addon.

Source

Tool inventory

Four more built-ins touch files and are outside this page: ast_edit (on by default through astEdit.enabled), ast_grep (off by default), eval (persistent Python or JavaScript that can call the agent's tools), and lsp. Their description strings were not extracted in the survey. There is no separate list tool: read on a directory lists it. edit and write declare concurrency = "exclusive"; bash is shared unless pty is set.

Read

Signature

read({ path: string })

One required string. Line selection is a suffix on the path: :50, :50-200, :50+150, :-60, :5-16,960-973, :raw, and :raw:2-4. Other suffixes select conflicts, SVG rasterisation, archive members, SQLite tables and rows, video frames, and vision questions through ?q=. Line numbers are one-based. A literal path wins over selector parsing when lstat finds it, so a file named report:1-2 reads as a file.

Description

read: 3284 characters, 3342 bytes, 33 lines, approximately 996 tokens.

read (3284 characters)

Read files, directories, archives, SQLite, images, documents, internal resources, and web URLs via `path`.

<instruction>
- SHOULD parallelize independent reads.
- SHOULD use `read` (not browser) for web content; browser only when `read` can't deliver.
</instruction>

## Selectors — append `:<sel>` to `path` (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`)

- `:50` / `:50-` — from line 50 | `:50-200` — inclusive | `:50+150` — 150 lines from 50 | `:-60` — last 60 lines | `:5-16,960-973` — multiple ranges
- `:raw` — verbatim, no anchors/prefixes | `:2-4:raw` / `:raw:2-4` — range + verbatim
- `:conflicts` — one line per unresolved git merge conflict block
- `:img` — rasterize a local `.svg`/`.svgz` as a PNG image; use when visual layout matters
- Bare image path → sent directly to the active model when it supports image input.
- `?q=<question>` — image only (also `.svg:img?q=`, `attachment://N?q=`, `local://…?q=`): vision-model answer as text instead of pixels (works on any model); prefer bare image path when active model supports image input.
- Videos (`.mp4`, `.mov`, `.mkv`, `.webm`, `.m4v`, `.avi`, `.wmv`) need system `ffmpeg`/`ffprobe`: bare read returns a preview grid plus metadata (resolution, codecs, duration, fps); `:412` extracts frame 412, `:1h5m42s`/`:90s`/`:01:23` seeks to a timestamp

## Source kinds

- Parseable code, no selector → structural summary (declarations only, body elided). Footer names recovery selector — re-issue ONLY those ranges.
- File + selector → `[foo.ts#1A2B]` snapshot header + numbered lines. Copy `[FILENAME#TAG]` for anchored edits; NEVER fabricate the tag.
- Directory → depth-limited dirent listing. Root is complete; page long listings with `:N-M`/`:-N`. Child dirs cap at 12 entries (`… N more` marker) — read the sub-path to expand.
- SQLite (`.sqlite`, `.sqlite3`, `.db`, `.db3`): `file.db` (tables), `file.db:table` (schema+rows), `file.db:table:key` (by PK), `?limit=`/`?where=`/`?q=SELECT`.
- Archives (`.zip` family incl. `.jar`/`.apk`/`.whl`, `.tar` incl. `.tar.{gz,bz2,xz,zst}`, `.rar`, `.7z`, `.iso`, `.cab`, `.deb`/`.rpm`/`.cpio`/`.ar`/`.a`, `.lzh`/`.arj`, `.asar`; single-stream `.gz`/`.bz2`/`.xz`/`.zst`): `archive.ext:path/inside/archive` reads a member.
- Documents → extracted text. Notebooks → editable cells. Images → decoded inline for vision-capable models (prefer bare image path); `img.png?q=<question>` asks a vision model and returns text (spares context; works on any model). Videos → preview grid plus metadata. SVGs read as text unless `:img` is specified; `:raw` bypasses converters.
- URLs → reader-mode clean text/markdown; `:raw` → untouched HTML. Bare `host:port` needs trailing slash.
- Internal URIs — all schemes take selectors. `artifact://<id>` recovers spilled output; page with `:N-M`/`:raw:N-M`.
- `ssh://host/<path>` reads remote file/dir (UTF-8, ≤1 MiB); bare `ssh://` lists hosts; writable with `write` and searchable with `grep`.
  Literal `:`, `?`, `#` → percent-encode (`%3A`/`%3F`/`%23`). Requires a verified POSIX shell on the remote host. For Windows or other unsupported hosts, use `bash` with a remote SSH command or mount with `sshfs`.

<critical>
Summary footer names elided ranges? Re-issue ONLY those ranges. NEVER guess `..`/`…` content.
</critical>

Path handling

resolveToCwd resolves relative paths against the session cwd, expands ~, strips a leading @, converts file:// URLs, folds several Unicode space characters to a plain space, handles Windows drive aliases, and maps a bare / to the cwd. Absolute paths and .. are accepted. There is no containment check.

When the resolved path does not exist, resolveReadPath in path-utils.ts tries a shell-escape stripped variant when the string holds both a backslash and a slash, then four macOS variants in order: a narrow no-break space (U+202F) before AM or PM, the NFD form of the path, straight apostrophes replaced by U+2019, and NFD with curly quotes together. The first variant that exists is read. The model is not told that a variant was used.

When stat still fails, three more attempts run: a path containing ; is split and read as several files; a unique workspace suffix match runs glob for **/<normalized path> from the cwd with a five second timeout, and one match is used with a notice at the top of the output; an approved-plan alias is tried for plan files. Remote mount prefixes skip the glob. Zero or several suffix matches fall through to the error.

[Path '<from>' not found; resolved to '<to>' via suffix match]

Path '<path>' not found

Symlinks: followed with no check on the ordinary read path. The optional speculative read path resolves the real path and rejects targets outside the cwd, non-regular files, and files above 4 MiB, but that path protects latency and stale authorisation, not confinement.

Permissions

Binary and conversion

Limits

A ranged read adds one leading and three trailing context lines around the requested range (RANGE_LEADING_CONTEXT_LINES and RANGE_TRAILING_CONTEXT_LINES in read-format.ts). :raw disables the context.

Output

[src/app.ts#1A2B]
1:import { x } from "./x"
2:export const y = x

The example is reconstructed from the format code. A parseable code file read with no selector returns a structural summary instead of numbered lines: declarations stay, bodies collapse to 12-40:function f() { … } rows, and a footer such as […180ln elided; re-read needed ranges with src/app.ts:12-40,55-90] names the ranges to fetch. read.summarize.enabled defaults to true; read.summarize.prose is off, so Markdown and plain text are not summarised.

Notable

• The snapshot header tag is a hash of the whole file when the file fits the 4 MiB buffer or a whole-file window was read. A partial view of a larger file records only the displayed line provenance. Every numbered line shown is recorded as seen for the edit.enforceSeenLines guard.
• Block-aware rendering can insert … rows for elided lines inside a ranged view.
• An empty file returns Line 1 is beyond end of file (0 lines total). The file is empty. An empty directory returns (empty directory).
• A directory read builds a depth-two tree. The root has no entry cap; each child directory shows up to 12 entries with a … N more marker. Selectors page the rendered listing: [<n> more lines in listing. Use :<n> to continue].
• The tool accepts an abort signal and checks it between steps; the plain-file line collector runs without the signal so a read is never abandoned mid-stream.
• When an ACP client supplies an editor buffer, read uses that buffer and falls back to disk if the bridge fails.
• No repeat-read guard, no content injection after the read, no redaction.
• read is not in the exclusive concurrency set, so it can run beside a write or edit on the same path inside one tool batch.

Edit

Signature

write({ path: string, content: string })
edit({ input: string })

edit takes one input string in the default hashline mode, and also in apply_patch and sloppy modes. The other modes change the schema: replace takes path, old_string, new_string, and optional replace_all; patch takes path and an edits array of op, rename, and diff entries. The mode is the edit.mode setting and is fixed for the session. write on a .zip, .jar, .war, .ear, .apk, .tar, .tar.gz, .tgz, .tar.zst, or .asar member path rewrites the archive; on a SQLite db:table or db:table:key path it inserts, updates, or deletes a row.

Description

write: 764 characters, 766 bytes, 14 lines, approximately 187 tokens. edit: 5235 characters, 5267 bytes, 135 lines, approximately 1574 tokens.

write (764 characters)

Creates or overwrites file at specified path.

<conditions>
- Creating new files explicitly required by task
- Replacing entire file contents when editing would be more complex
- Supports `.zip` (and ZIP-based `.jar`/`.war`/`.ear`/`.apk`), `.tar`, `.tar.gz`/`.tgz`, `.tar.zst`, and `.asar` archive entries via `archive.ext:path/inside/archive`; other archive formats (`.rar`, `.7z`, `.iso`, …) are read-only
- Supports SQLite row operations via `db.sqlite:table` (insert), `db.sqlite:table:key` (update with JSON content, delete with empty content)
</conditions>

<critical>
- You SHOULD use Edit tool for modifying existing files
- You NEVER create documentation files (*.md, README) unless explicitly requested
- You NEVER use emojis unless requested
</critical>

edit (5235 characters)

Line-anchored patch language: name original lines/gaps to replace, insert, cut, or paste; then give new content. `:` headers take `+` body rows; colonless paste `PUT`, `CUT`, `REM`, `MV` take none.

<headers>
Section: `[PATH#TAG]`; `TAG`: 4-hex snapshot from latest `read`/`search`, REQUIRED each section. New files: `write`; hashline edits existing files only.
</headers>

<ops>
`PUT N.=M:`: replace original inclusive lines N–M with body.
`PUT N*:`: replace syntactic block beginning N; closing line resolved.
`PUT <N:` insert body rows before line N (`PUT <1:` = file head).
`PUT >N:` insert body rows after line N (`PUT >$:` = file tail).
`PUT >N*:`: insert after block N's end, at sibling depth. Append inside block: `PUT >M:`.
`PUT <N @name` / `PUT >N @name` paste register `@name` at the gap before/after line N; omit `@name` for the anonymous register.
`PUT N.=M @name` / `PUT N* @name` paste `@name` over the range / resolved block; `@name` required here.
`CUT N.=M` / `CUT N*`: delete and capture inclusive lines N–M / block N; anonymous or given `@name`.
`REM`: delete section file. `MV DEST`: move/rename (quote paths with spaces); prior edits apply to source, final content to `DEST`.
Single line: `PUT N.=N:` / `CUT N.=N`. Ranges name original inclusive touched lines; body length irrelevant.
</ops>

<body-rows>
Only below `:` headers. Row: verbatim `+TEXT` (leading whitespace preserved); `+`: blank. NEVER `-old`, bare, or context rows: range deletes; body is final content. Keep line: exclude it from every range. Literal initial `-`/`+`: `- item` → `+- item`; `+ item` → `++ item`.
</body-rows>

<rules>
- Numbers and `#TAG`: latest `read`/`search` `LINE:TEXT`; numbers are original, never shifted by hunks.
- Each edit renumbers and changes `#TAG` → next numbers from edit response or fresh `read`.
- Touch displayed lines only; undisplayed hunks REJECTED. Far from read window: re-`read`; confirm construct.
- Elisions UNSEEN: `…`, `..`, collapsed `N-M:` rows. NEVER hunk in/across one; `read` first.
- NEVER start/end range mid-expression or mid-block.
- Ranges: changed lines only; NEVER widen over keepers. Non-adjacent changes: separate hunks.
- Whole construct: `PUT N*:`; internal lines: `PUT N.=M:`.
- `PUT N*:` resolves exactly node N. Leading decorators/attributes/doc-comments are separate nodes: point N at first decorator to include both. Standalone line-comments never swept: use `PUT N.=M:`.
- Block ops: opening line of multi-line construct, NEVER closer, last line, bare inner statement. One statement: plain `PUT N.=N:` / `CUT N.=N` / `PUT >N:`. At closer: `PUT >M:`.
- Markdown headings are block openers. Block op on `##`/`###`: whole section through deeper headings to next same/higher heading. After section `PUT >N*:`: end body with blank line to separate next heading.
- Pure addition: `PUT <N:` / `PUT >N:`, NEVER widened `PUT N.=M:`.
- Move: `CUT`+`PUT`; `CUT 5.=9 @fn` → `@fn`, `PUT >40 @fn` pastes. Single call-local move: unlabeled `CUT` + `PUT >40`. Named registers persist across edit calls.
- NEVER format/restyle with this tool; run project formatter.
</rules>

<example>
`read` output shape:
```
[greet.py#A1B2]
1:def greet(name):
2:    msg = "Hello, " + name
3:    print(msg)
4:greet("world")
```

Edit, then move:
```
[greet.py#A1B2]
PUT 1.=3:
+def greet(name):
+    print(f"Hi, {name}")
MV lib/greet.py
```

Markdown bullets — file receives `- task`:
```
[PLAN.md#A1B2]
PUT >2:
+- task
+  - nested task
```

Move `greet` to sibling file via named register; flows across sections:
```
[greet.py#A1B2]
CUT 1* @fn
[other.py#3C4D]
PUT <1 @fn
```

`PUT 1*:` resolves lines 1–3 (`def` through `print(msg)`); line 4 separate, remains:
```
[greet.py#A1B2]
PUT 1*:
+def greet(name):
+    print(f"Hello, {name}")
```

Decorator/doc-comment separate block: point N at decorator to include both; anchoring `def` line 2 orphans `@cache`:
```
[svc.py#C3D4]
PUT 1*:
+@cache
+def load(key):
+    return store[key]
```
</example>

<anti-patterns>
# WRONG — empty `PUT` to delete. RIGHT: `CUT 4.=4`
PUT 4.=4:

# WRONG — range sized to the post-edit content. RIGHT: `PUT 1.=1:` (body length irrelevant)
PUT 1.=2:
+def greet(name):

# WRONG — `-` rows / bare context lines do not exist; the range deletes, the body is only new content.
PUT 3.=3:
    msg = "Hello, " + name
-   print(msg)
+   return msg
# RIGHT
PUT 3.=3:
+   return msg

# WRONG — pure insertion as a widened `PUT`: retyped keepers get dropped (here line 4).
PUT 2.=4:
+    msg = "Hello, " + name
+    extra = compute(name)
+    print(msg)
# RIGHT — touch nothing you keep.
PUT >2:
+    extra = compute(name)

# WRONG — `PUT >N*:` anchored on the closing delimiter / last visible line. RIGHT: plain `PUT >M:`
PUT >3*:
+after()
# RIGHT
PUT >3:
+after()

# WRONG — body rows under register PUT; register pastes take no body. RIGHT: bodyless `PUT >20 @fn`.
PUT >20 @fn:
+function f() {}
</anti-patterns>

<critical>
1. RE-GROUND AFTER EVERY EDIT: edits renumber and change `#TAG`; take next numbers from edit response or fresh `read`. Stale tag/surprise: STOP; re-`read`.
2. RANGES TIGHT: changed lines only. Whole construct: `PUT N*:`.
3. BODY FINAL CONTENT: every row starts `+`; Markdown bullet: `+- item`, not `- item`.
</critical>

Whole-file write

write resolves the path, checks plan mode and the auto-generated-file guard, refuses a path that looks like a read-selector misfire, and refuses content that ends with a read truncation notice and covers less than the current file. It then routes through the ACP bridge when an editor owns the path, or through the LSP writethrough callback, or calls Bun.write directly. The destination is written in place. There is no temporary file and rename for ordinary files, no expected hash, and no compare-and-swap. A permission-denied write can be brokered through a host-provided privileged channel, which receives the symlink-resolved target. Parent directories: Unverified. The Bun runtime documents that Bun.write creates missing parents; the tool adds no mkdir of its own. Mode: a file whose content starts with #! is made executable and the result says [Notice: Made executable via chmod +x]. BOM and line endings: Not surveyed. The content is written as supplied.

Archive-member writes read the archive, replace one member, write a temporary whole archive, and rename it over the original. SQLite writes open with a busy timeout and run one statement.

After the write the LSP writethrough can format the content and return diagnostics. Formatter drift is recorded so the returned snapshot tag matches what landed on disk. The scan cache used by glob is invalidated.

Matching

Hashline is content-addressed and line-addressed, not text-matched. Every section names a path and a four-hex tag from the latest read or grep output. The engine compares the tag with the current file hash. A recognised tag from an earlier snapshot in the session can be recovered: the engine remaps anchors onto unchanged live lines and adds a warning to the result. An unrecognised tag or unrecoverable drift rejects the edit before any file is staged. Line numbers in PUT and CUT ranges are original numbers from that read; PUT N*: resolves a syntactic block from its opening line through the native parser. With edit.enforceSeenLines (off by default) a range that a prior read or search never displayed in full is rejected with a preview of the actual lines.

replace, patch, and sloppy modes match text. They use fuzzy matching when edit.fuzzyMatch is on, which is the default, at a similarity threshold of 0.95. The model is not told when a fuzzy match was used in those modes.

Multi-file patch

Present in every mode. A hashline payload can carry several [PATH#TAG] sections, including MV moves and REM deletes, and apply_patch takes a *** Begin Patch envelope. The engine stages every file in memory, validates every operation and plan restriction, then calls the host writer file by file in payload order. A writer failure after earlier files landed leaves those files written. Validation is all-or-nothing; application is ordered and best-effort. Two sections that resolve to the same file are rejected.

Verification and mutation state

Output

Notable

• Notebook edits run on the virtual cell text and serialise back to notebook JSON, preserving metadata and outputs where possible. write on an existing notebook expects notebook JSON.
• The edit tool streams argument fragments: the native EditSession parses the payload as it arrives and emits previews before execution. edit.recoverInlineEdits (on by default) turns a hashline payload the model emitted as plain text into a tool call.
• Internal URL writes: local:// for the plan sandbox, vault://, conflict://N to replace one registered merge-conflict block, conflict://* for all blocks, and xd:// as a transport that runs a mounted tool under that tool's own approval tier.
• The auto-generated-file guard (edit.blockAutoGenerated, on by default) refuses files whose name or first 1 KiB matches a generator marker.
• No undo tool in this family; checkpoint is a separate tool.

Shell

Signature

bash({ command: string, env?: Record<string, string>, timeout?: number, cwd?: string, pty?: boolean, async?: boolean })

timeout is in seconds and defaults to 300. Zero disables the deadline. Other values are clamped to 1 to 3600 and to tools.maxTimeout when that setting is above zero, with a notice: Timeout clamped to <n>s (requested <m>s; allowed range 1-3600s). env values apply to one command. cwd sets the working directory; a leading cd <path> && on the first line is lifted into cwd when the parameter is absent. pty requests a pseudo-terminal. async returns a job ID and is present in the schema when async.enabled is on, which is the default.

Description

bash: 1649 characters, 1655 bytes, 24 lines, approximately 454 tokens. Rendered with the setting defaults: async and auto-background enabled, a 60 second threshold, ast_edit on, ast_grep off, grep, glob, hub, and JavaScript eval on, in-process shell builtins on, skills present, and a non-Windows host.

bash (1649 characters)

Runs commands in a persistent shell.

Use ONLY for one binary or a short pipeline that computes a fact (`wc -l`, `sort | uniq -c`, `diff`).
Inline scripts, heredocs, `$(…)`, complex control flow/quoting, and non-trivial pipelines → `eval`.

<instruction>
- Set `cwd` instead of `cd`; use `env: { NAME: "…" }` for multiline/quote-heavy values.
- `pty: true` only for terminal interaction (`sudo`, `ssh`).
- Order-dependent commands use `&&` in one call; independent calls may run concurrently.
- Skill instructions resolve as `skill://<name>`; other internal URIs auto-resolve to paths.
- aux utils available: mkdir, wc, sort, comm, diff, uniq, base64, cmp, md5sum, sha{1,224,256,384,512}sum, b2sum, basename, dirname, readlink, realpath, touch, stat, date, mktemp, seq, yes, printenv, truncate, tac, nproc, uname, whoami, hostname, which, ps, pgrep, pkill, pidwait, top, cut, tee, tr, paste, sed, xargs, jq, rm, mv, ln, ts, sponge, ifne, isutf8, combine, errno
- `async: true` defers a finite command's result; it does not extend `timeout`.
</instruction>

<critical>
- NEVER use shell `grep`/`rg`; use built-in `grep`.
- List directories with `read` and find paths with `glob`; NEVER use `ls`/`find`.
- Avoid `head`, `tail`, and redirection: output is captured, truncated, and linked as `artifact://<id>`.
- Services, watchers, debuggers, and REPLs MUST use `hub` (`op:"start"`).
</critical>

Long foreground calls may auto-background by the configured threshold and deliver later.
`timeout: 0` disables the job deadline; otherwise `timeout` sets it without extending foreground waiting.
No truncation footer means the displayed output is complete.

Working directory and environment

The working directory is the session cwd unless cwd is given. A persistent shell keeps the cwd across calls: a command that changes directory changes the next command's start point. The shell is an embedded fork of brush running inside the native addon. It loads no user profile by default and registers bash builtins plus in-process utilities from pi-builtins: cat, head, tail, wc, sort, uniq, ls, find, grep, rg, fd, sed, jq, diff, rm, mv, ln, checksums, and process tools. PI_DISABLE_UUTILS_BUILTINS turns the utility set off.

Non-interactive calls run with a hardened environment: pagers disabled, TERM=dumb, NO_COLOR, non-interactive Git and package-manager defaults, and reduced credential prompts. PTY calls skip that hardening. Session environment values apply when the shell is created; the env parameter is scoped to one command. A configured snapshot can restore aliases, functions, and options, and direnv or devenv preflight can add project variables. Login shell: None.

Process lifecycle

Output limits

Sandbox

None. No OS sandbox, container, seccomp, or Seatbelt policy. The network is unrestricted. The child runs under the Oh My Pi process account. Task isolation can give a child task its own worktree, branch, copy-on-write filesystem, or overlay, but that is a task feature and does not change a top-level bash call.

Approval

Every tool declares a tier: read, write, or exec. bash is exec. The mode decides what is auto-approved:

The schema default is yolo. ACP adapters can keep a client permission gate until yolo is configured explicitly. tools.approval.<name> can allow, prompt, or deny a tool in every mode, and a tool-declared denial wins. Bash pattern rules (bash.approvalRules) match literal commands or approved && chains, with * wildcards only. Critical patterns force a prompt: destructive root removal, fork bombs, remote fetch-and-execute, sensitive system-file writes, and shutdown commands. The rules inspect command text and do not confine the process.

The bash interceptor (bashInterceptor.enabled, off by default) can block cat, grep, find, sed -i, and redirection misuse with a message naming the replacement tool when that tool is active. The eval tool has its own approval path, so a bash rule is not a global shell policy.

Notable

• A non-zero exit is an error result: the output, a blank line, and Command exited with code <n>, flagged isError with details.exitCode.
• A timeout is an error result with details.timedOut: the output then [Command timed out after <n> seconds]. The renderer uses a warning border instead of error red.
• Abort throws: the sink prepends [Command cancelled]; PTY and bridge output gets [Command aborted] appended instead.
• pty: true makes the call exclusive in the concurrency scheduler and uses portable-pty with an interactive environment.
• Services, watchers, and REPLs are routed to the separate hub tool by the description.
• No streaming of partial output to the model. The TUI receives streamed chunks.

Search and listing

Tools

glob has no separate pattern argument: the glob is the path string, or a ;-separated list of them, and a simple pattern matches recursively. Results are newest-first, grouped by directory, with / on directories and mtime metadata in details. A path that is a file or does not exist fails with Path is not a directory: <path> or Path not found: <path>; searching from / is refused. The native pi-walker scan cache (1000 ms TTL, 16 entries, 64 MiB budget) serves glob and AST discovery and is invalidated by write, edit, rename, and delete, not by shell commands.

grep accepts a file, directory, glob, ;-delimited list, <file>:<lines> selector, archive member, URL, or internal URL. The native engine tries Rust regex, then PCRE2 for lookaround and backreferences, and falls back to a literal search when both reject the pattern. Files larger than 4 MiB are searched over a leading 4 MiB window and the result says so: Searched only the first 4MB of large files (...). Output groups matches under relative paths. In hashline mode each file gets a [<path>#<TAG>] header and rows read *N:text for a match and N:text for context, with ... between gaps; with hashline off the separator is |. When the file window fills, the result ends with Showing files <a>-<b> of <total>. Use skip=<n> for the next page, or narrow paths/pattern. Zero matches return No matches found.

Description

glob: 705 characters, 707 bytes, 16 lines, approximately 171 tokens. grep: 498 characters, 500 bytes, 13 lines, approximately 130 tokens.

glob (705 characters)

Globs files, directories, and path-backed internal URLs with fast pattern matching.

<instruction>
- `path`: glob, file, directory, or path-backed internal URL; separate targets with `;` (`src/**/*.ts; test/**/*.ts`).
- `memory://` glob patterns are supported. `ssh://` has no local path; use `read`. Other internal URLs accept exact paths only.
- `gitignore` defaults `true`. Set `false` for ignored files such as `.env*`, logs, or build output.
- `hidden` defaults `true`; pair it with `gitignore: false` for ignored dotfiles.
</instruction>

<output>
Matches are newest-first and grouped by directory; directories end in `/`.
</output>

<avoid>
Open-ended multi-round discovery → Task + scout.
</avoid>

grep (498 characters)

Searches files/internal URLs: Rust regex, PCRE2 fallback.

<instruction>
- `path`: known files, directories, globs, internal URLs; roots `;`-separated.
- Broad searches may time out → narrow scope or use `glob` first.
- One-file line selector: `src/foo.ts:50-100`; never selects search root.
- Literal `\n` or `\\n` enables cross-line patterns.
</instruction>

<critical>
- MUST use instead of shell `grep`/`rg`.
- Open-ended multi-round search MUST use Task + scout, not chained calls.
</critical>

Errors

Invalid path and regex errors are ToolError text. Native edit engine failures come back as isError outcomes rather than rejected promises. A completed command with a non-zero exit is an error result even though the process finished. Permission denials and host bridge failures may throw. There is no stable error code across the family; the structured details object carries exit codes, truncation, and diagnostics for the TUI.