read, list, tree, glob, grep, search, edit, and write may use a path outside the workspace after approval: you, or the Review model in Review or Audit. Workspace write and edit still follow the approval mode.
bash starts in the workspace root and is approved as a side effect. Background Bash tasks are Work only.
| Rule |
Detail |
| Background tasks |
bash_start returns a session-local task ID. Use bash_status or bash_logs to observe it, and bash_stop to stop it |
| Timeout |
backgroundBashTimeoutSeconds, default 10800 seconds (3 hours) |
| Lifetime |
Not saved. Stopped when the session closes. At most 32 active tasks. Completed tasks stay queryable and do not use a slot |
| Stdin |
Closed. Commands that need terminal input are unsupported |
| Credential paths |
.ssh, .gnupg, and credentials.json stay Forbidden |
| Skipped directories |
Glob, grep, search, list, and tree skip .git, .vs, bin, obj, node_modules, and dist |
| Links |
Tree lists a directory link once, under its resolved path, and skips a link that leaves the workspace root or an outside start path |
| Binary files |
Rejected for read and edit (NUL probe) |
| Tool |
Catalog |
Purpose |
read |
Plan, Work |
Read a text file (path, optional 1-based offset and limit) |
describe_image |
Plan, Work |
Describe an image through imageModel (path, optional question). Omitted when imageModel is unset |
view_image |
Plan, Work |
Show an image to the current model (path). Present only while that model accepts images |
list |
Plan, Work |
List immediate entries (path optional, 1-based offset and limit) |
tree |
Plan, Work |
List structure under a path (path optional, depth default 2 capped at 4, files to include files). Depth-first. Subdirectories before files. Up to 1,000 entries and 20 files per directory |
glob |
Plan, Work |
List files matching a glob (pattern, optional path, 1-based offset and limit) |
grep |
Plan, Work |
Regular-expression search (pattern, optional path and file-name glob) |
search |
Plan, Work |
Rank files by name and content (query, optional path, glob, caseSensitive, 1-based offset and limit) |
todowrite |
Plan, Work |
Replace or merge the session todo list |
todoread |
Plan, Work |
Read the current todo list |
question |
Plan, Work |
Ask one or more questions, with single or multiple choices and custom answers |
skill |
Plan, Work |
Load a skill by name. Omitted when skills is false |
edit |
Work |
Replace one unique old_string |
write |
Work |
Create or overwrite a UTF-8 text file |
bash |
Work |
Run one shell command after approval (bash -lc). Timeout is bashTimeoutSeconds (default 600 seconds) |
bash_start |
Work |
Start a background command after approval and return its task ID |
bash_status |
Work |
Read status, exit code, and log offsets |
bash_logs |
Work |
Read bounded output by offset |
bash_stop |
Work |
Stop a background task and its children after approval |
| Limit |
Value |
read |
1,000,000 characters or 20,000 lines |
write |
2 MiB |
grep |
1,000 matches, 8 MiB per file |
search |
200 candidate files per page (default 50), 2 preview lines per file, 8 MiB per scanned file |
glob |
1,000 matches per page |
list |
1,000 entries per page |
tree |
1,000 entries, 4 levels, 20 files per directory |
| Tool output |
Truncated at 100,000 characters |
| Background output |
1 MiB per task. bash_logs returns at most 100,000 characters per call |