Tools Quick Reference

​

Tool Tags

​

Categories

• Planning & Task Management (10 tools)
• File Operations (8 tools)
• Information Retrieval (6 tools)
• Workflow Management (22 tools)
• System & Execution (4 tools)
• Other Tools (69 tools)

​

Planning & Task Management

​

add_dependency

• blocks: from_task must complete before to_task can start
• related: informational link, no execution constraint
• parallel_with: explicitly marks tasks as parallelizable

• Task A blocks Task B: add_dependency(from_task=“A-id”, to_task=“B-id”, type=“blocks”) Means B cannot start until A completes.
• Tasks can run together: add_dependency(from_task=“A-id”, to_task=“B-id”, type=“parallel_with”) Explicitly marks A and B as safe to run in parallel.
• Informational link: add_dependency(from_task=“A-id”, to_task=“B-id”, type=“related”) No execution constraint, just documents a relationship.

​

add_task

• When you discover additional work that needs to be done
• When you encounter missing dependencies or prerequisites
• When breaking down complex work into more steps
• When pivoting approach requires new tasks

• Use parent_id to create subtasks under an existing task when you discover complexity
• Break down tasks that prove more complex than initially planned
• Create hierarchical task structures for better organization
• Each subtask inherits context from parent but can have specialized metadata

• Implementation agent finds task needs research → add subtask with preferred_agent: “research”
• Research agent discovers multiple integration points → add subtasks for each integration
• Any agent finds unfamiliar tech/patterns → add subtask with tool_hints: [“search_first”, “use_subagent”]
• Task requires multiple phases → add sequential subtasks with position ordering

• preferred_agent: Which agent should handle this (planning/research/implementation/debugging/tdd/finalize)
• tool_hints: Suggested tools to use [“use_bash”, “use_subagent”, “search_first”, “test_first”]
• dependencies: What this task depends on (packages, files, other tasks)
• notes: Important context or discoveries
• priority: high/medium/low

1. Complex Implementation Discovery: parent_id: “task_123”, title: “Research authentication patterns”, preferred_agent: “research”, notes: “Found unfamiliar OAuth flow”
2. Multi-Step Breakdown: parent_id: “task_456”, title: “Setup database schema”, position: 1 parent_id: “task_456”, title: “Create migration scripts”, position: 2
3. Cross-Agent Coordination: parent_id: “task_789”, title: “Write integration tests”, preferred_agent: “tdd”, dependencies: [“API endpoints complete”]

• Add tasks as soon as you discover they’re needed
• Use parent_id when expanding existing tasks that prove complex
• Include metadata hints for better execution
• Position subtasks logically in sequence
• Use descriptive titles and comprehensive descriptions
• Create subtasks for different agent specializations when needed

​

create_plan

• AFTER you preform your initial research and analyze the problem.
• Use this tool when you need to organize complex work into structured steps
• You typically should create plans AFTER your findings. Avoid creating tasks to research, explore, identify, or search through the codebase. You should first perform your research so you can create an informed plan.
• ESPECIALLY when you are going to delegate. If you are about to spawn sub-agents, plan first: the task graph is what tells you which of them can run at the same time. An orchestrator that spawns without a plan has no record of what is independent, and ends up delegating one agent at a time.

• Title: Clear, concise title for the plan
• Description: Detailed description including:
  • Main objective
  • Approach/strategy
  • Alternative approaches (if applicable)
  • Success criteria
• Complexity: simple|moderate|complex
• Tasks: List of tasks with title, description, optional metadata, and optional dependencies
• The plan will be associated with the current session

• task_position: The 1-indexed position of another task in the tasks array
• type: “blocks” (the other task must COMPLETE first — a real data dependency), “related” (informational only), or “parallel_with” (emphasis that two tasks are safe together; rarely needed, since anything without a “blocks” edge already is)

tasks: [
{title: "Design schema"},
{title: "Implement API",       dependencies: [{task_position: 1, type: "blocks"}]},
{title: "Implement worker",    dependencies: [{task_position: 1, type: "blocks"}]},
{title: "Implement frontend",  dependencies: [{task_position: 1, type: "blocks"}]},
{title: "End-to-end tests",    dependencies: [
{task_position: 2, type: "blocks"},
{task_position: 3, type: "blocks"},
{task_position: 4, type: "blocks"}]}
]
Tasks 2, 3 and 4 all wait on the schema and on nothing else, so once it lands
all three are ready together and should be delegated in ONE turn.

tasks: [
{title: "Write migration"},
{title: "Regenerate ORM from applied schema", dependencies: [{task_position: 1, type: "blocks"}]}
]

• preferred_agent: Which agent should handle this task
• tool_hints: Suggested tools to use
• dependencies: Informational dependency notes (free-form text)
• notes: Important context
• priority: high/medium/low

• Break down work into clear, actionable tasks
• Cut tasks along boundaries that do not overlap (package, module, directory), so independent tasks can be worked at the same time without collisions
• Use inline dependencies to define the task graph upfront, and add “blocks” ONLY where one task genuinely consumes another’s output
• Include a mini-roadmap in the description
• Document alternative approaches for pivoting
• Be specific about what needs to be done
• Consider edge cases and potential blockers
• Consider changing state in parallel with plan creation, if states are available.

​

create_subtask

• When breaking down a complex task into smaller steps
• To add more granular tracking
• When discovering additional work while implementing

• Keep subtasks focused and specific
• Use subtasks for logical groupings of work
• Don’t create too many levels of nesting

​

get_plan

• When you need to review the current plan
• To check plan status and progress
• To understand what needs to be done

• Plan details including title, description, status, and complexity
• Returns error if no plan exists for the session

​

list_ready_tasks

1. Its status is “pending” (not started yet)
2. All tasks that block it (via ‘blocks’ dependencies) have status “completed”

• List of ready tasks with their details
• Total count of ready tasks vs total pending

​

list_tasks

• When you need to see all tasks in the plan
• To check task progress and status
• To understand what work needs to be done
• BEFORE delegating: the ready set tells you what can be worked at once

• List of all tasks with their status, title, and hierarchy
• Tasks are ordered by position and show parent-child relationships
• Assignee for any task that has been claimed, so you can see what other agents are already working on and avoid handing out the same task twice
• A count of tasks that are READY (pending with no incomplete blocker). Ready tasks have no dependency between them, so they are meant to be delegated together in one turn rather than one after another.

​

remove_dependency

​

update_plan

• When you need to modify the plan based on new information
• When pivoting to a different approach
• When marking a plan as completed or cancelled

• Title: Update the plan title
• Description: Add new information, document pivots
• Status: pending|in_progress|completed|cancelled
• Complexity: simple|moderate|complex

• Document why changes are being made
• Keep the description updated with current approach
• Use this to track progress and pivots

​

update_task

• When starting work on a task (mark as in_progress)
• When completing a task (mark as completed)
• When a task is blocked or failed
• To update task description with findings
• To add notes, hints, or discoveries to metadata
• To claim a task by setting assignee + in_progress

• pending: Not started yet
• in_progress: Currently working on it
• completed: Successfully finished
• failed: Could not complete
• blocked: Waiting on something (add blocker to notes)
• skipped: Decided not to do
• cancelled: No longer needed

• Free-form text identifying who is working on this task
• Use a descriptive label: spawn title, role name, or agent identifier
• Claim pattern: update_task(task_id=“X”, status=“in_progress”, assignee=“researcher-auth”)
• Other agents see assignments in list_tasks and skip claimed work

• notes: Add discoveries, blockers, or important context
• preferred_agent: Suggest which agent should handle this
• tool_hints: Suggest tools to use [“use_bash”, “search_first”]
• dependencies: Document what this depends on
• next_steps: What to do after this task

• Update status when you start and finish tasks
• Add descriptions to document what was done
• Use metadata.notes for blockers when marking as blocked
• Add tool_hints for complex tasks to guide future execution
• Set assignee when claiming a task to prevent duplicate work

​

File Operations

​

edit

• Precise text replacements
• Creating a new file (empty old_string)
• Deleting specific content (empty new_string)
• Renaming a variable/function (with replace_all)

• Moving/renaming files: Use the shell tool’s mv command

• Insufficient context in old_string (needs 3-5 lines)
• Forgetting whitespace/indentation must match exactly
• Not checking if text appears multiple times

​

Replace Text

​

Multiple Edits

​

Create New File

​

Delete Content

​

Rename Variable

​

CRITICAL REQUIREMENTS

1. UNIQUENESS (when replace_all=false):
   • Include 3-5 lines of context BEFORE
   • Include 3-5 lines of context AFTER
   • Match whitespace/indentation EXACTLY
2. VERIFICATION CHECKLIST: Check how many times text appears Include enough context for uniqueness Verify parent directories exist (new files)
3. FAILURE CONDITIONS:
   • old_string not found → FAILS
   • Multiple matches (without replace_all) → FAILS
   • Whitespace mismatch → FAILS

​

BEST PRACTICES

• Include ample context
• Use replace_all for systematic renames
• Parallelize independent edits as separate calls in one message
• Verify edits don’t break code

​

WORKS WELL WITH

• AFTER: shell (test changes)
• ALTERNATIVE: Write (complete rewrite)

​

PARAMETERS

• file_path: Absolute path (required)
• old_string: Text to find (exact match)
• new_string: Replacement text
• replace_all: Replace all occurrences (optional)

​

find_replace

• Renaming variables, functions, or classes across multiple files
• Updating imports or module references project-wide
• Fixing consistent typos or naming conventions
• Batch updating configuration values
• Refactoring patterns across the codebase WHEN NOT TO USE:
• Single file edits: Use Edit tool instead
• Complex structural changes: Use Patch tool
• Context-dependent replacements: Use Edit or Patch for precision FEATURES:
• Glob pattern file filtering (e.g., ”**/*.js”, “src/**/*.{ts,tsx}”)
• Regular expression support with capture groups
• Case-insensitive matching option
• Preview mode to see changes before applying
• Automatic file history tracking USAGE PATTERNS:

​

Preview First (Recommended)

​

Simple Text Replacement

​

Regex with Capture Groups

​

Case-Insensitive Replacement

​

CRITICAL REQUIREMENTS

1. PREVIEW FIRST:
   • ALWAYS call with preview=true first to verify the pattern matches and scope
   • Preview shows diffs of what would change without modifying any files
   • After reviewing the preview, call again without preview to apply
2. FILE READING:
   • Checks modification times to prevent conflicts
   • Validates file access permissions
3. PATTERN MATCHING:
   • Literal text matching by default
   • Regex patterns with use_regex=true
   • Case sensitivity controlled by ignore_case
4. SAFETY CHECKS:
   • Atomic operation (all or nothing)
   • Preserves file history

​

BEST PRACTICES

• ALWAYS use preview=true first to see what changes would be made
• Use specific file globs to limit scope
• Review the preview diffs carefully before applying
• Test regex patterns with preview before committing

​

WORKS WELL WITH

• BEFORE: preview=true (see changes first)
• BEFORE: Grep (find occurrences)
• AFTER: shell (run tests)
• ALTERNATIVE: Edit (single file)
• ALTERNATIVE: Patch (complex multi-file edits)

​

PARAMETERS

• find_pattern: Text or regex pattern to find (required)
• replace_text: Replacement text (required)
• file_glob: File filter pattern (optional, defaults to all files)
• ignore_case: Case-insensitive matching (optional, default false)
• use_regex: Treat pattern as regex (optional, default false)
• preview: Preview mode - show what would change without applying (optional, default false) Remember: Use preview=true first, then apply.

​

move_code

• Reorganizing code within a file
• Moving a function/method to a different file
• Extracting code into a new location
• Copying code snippets between files
• Reordering functions in a file

• For simple cut/paste of small text - use edit tool
• For renaming across files - use find_replace tool
• For complex multi-file refactors - consider using the refactor agent

1. Extracts lines source_start to source_end from source_file
2. Inserts the extracted code AFTER target_line in target_file
3. If operation is “move” (default), deletes the original lines from source
4. If operation is “copy”, keeps the original lines

​

Move function to end of file

{
"source_file": "/path/to/file.go",
"source_start": 50,
"source_end": 75,
"target_file": "/path/to/file.go",
"target_line": 200,
"operation": "move"
}

​

Copy code block to another file

{
"source_file": "/path/to/original.go",
"source_start": 10,
"source_end": 30,
"target_file": "/path/to/new_file.go",
"target_line": 15,
"operation": "copy"
}

​

Insert at beginning of file

{
"source_file": "/path/to/source.go",
"source_start": 100,
"source_end": 120,
"target_file": "/path/to/target.go",
"target_line": 0,
"operation": "move"
}

1. Line numbers are 1-indexed
2. source_start and source_end are INCLUSIVE
3. target_line = 0 inserts at the very beginning
4. For same-file moves, the tool handles line number shifts automatically

• For same-file moves, be aware that line numbers shift after the operation
• Add blank lines in the extracted code if needed for proper spacing
• Check for any imports/dependencies that might need to be added to target file

​

prove_test

• After writing a fix and a test for it, before reporting the work done. “Confirm a new test fails before the fix and passes after” is exactly this call.
• When you are not sure a test exercises the code you changed.

1. Snapshots the exact bytes and mode of every file in files.
2. Writes each file’s baseline version (default: git HEAD; any git revision works). A file that does not exist at baseline is removed for the run; a file your fix deleted is put back.
3. Runs command and expects a NON-ZERO exit.
4. Restores your files — always, including on timeout, cancellation or a crash — and verifies them byte for byte.
5. Runs command again and expects exit 0.

• files: the IMPLEMENTATION files of the fix. NOT the test file — the test must stay in place for both runs.
• command: as narrow as possible — one package, one test (‘go test -run TestX ./pkg/foo’, ‘npx vitest run src/x.test.ts’). It runs twice.

• proven: fails without the fix, passes with it.
• passes_without_fix: the test does not exercise the change. Strengthen it.
• fails_with_fix: the fix does not make the test pass.
• baseline_does_not_compile: the before-run failed to BUILD (typical when the fix adds a symbol the test calls). That is NOT proof; report it as such.
• conflict: another writer changed a named file mid-run. Their content was kept and yours preserved; the result says where.
• restore_failed / inconclusive: see the result text.

​

read_attachment

• When the conversation references an attachment (by id) whose contents you have not yet seen.
• Specifically for PDF attachments: their pages are read on demand through this tool.

• Provide the attachment_id from the attachment reference.
• For PDFs: use the pages parameter to read a page range (e.g. “1-5”). PDFs larger than 10 pages require a page range; max 20 pages per request.

• PDF pages are returned as a native document block the model can read directly (text and layout).
• Image and text attachments are already provided inline in the conversation and do not need this tool.

​

save_attachment

• An image, PDF or file already exists as an attachment and the user now wants it as a file in the project.
• A previous generate_image call reported an attachment id but was not given save_to, or its save_to write failed.

• The bytes already exist and are addressable. Calling generate_image again costs another billed generation AND produces a DIFFERENT image — image models are not deterministic, so the file you would write is not the image the user approved. Always prefer save_attachment for an image you already have.

• read_attachment pulls the contents into the conversation so you can LOOK at them. This tool moves the bytes server-side, straight from storage to the file, without routing them through the conversation. Use this one to produce a file; use that one to inspect contents.

• Pass the attachment_id and the destination path. Relative paths resolve against the working directory; use repo in a multi-repo project.

• Binary content is written byte-for-byte, so images and PDFs stay valid.
• Parent directories are created as needed.

​

view

• Reading contents of specific files (source code, configs, logs)
• Examining text-based file formats

• Provide the file path
• Optional: offset (starting line) and limit (number of lines)
• For PDFs: use the pages parameter to read a page range (e.g. “1-5”). PDFs larger than 10 pages require a page range; max 20 pages per request.
• Issue multiple view tools in a single request for improved performance

• Displays file contents with line numbers for easy reference
• Can read from any position in a file using the offset parameter
• Handles large files by limiting the number of lines read
• Automatically truncates very long lines for better display
• Suggests similar file names when the requested file isn’t found

• Maximum output size is 64KB (~16K tokens) - larger files are truncated with head+tail
• Default reading limit is 1500 lines, which reads most source files whole
• Lines longer than 500 characters are truncated
• Cannot display binary files (executables, archives, etc.)
• Images up to 5MB are supported (JPEG, PNG, GIF, BMP, SVG, WebP)
• PDFs up to 5MB are supported; large PDFs are read a page range at a time via the pages parameter

• Prefer ONE whole-file read over several paged reads: each call costs a model round-trip, while the read itself takes milliseconds. Omit offset/limit unless the file is genuinely too big to arrive in one piece.
• A file OVER ~64KB cannot arrive whole whatever limit you pass — the response is capped and you get head+tail with the middle removed. Two calls settle it, and neither is a search: read the head (default) to get the shape, then ONE offset read for the region you need. The truncation notice tells you the total line count, so you can aim the second call directly.
• Do NOT fall back to repeated ‘grep’ on a large file to page through it by symbol. Measured: eleven agents greping one 52KB proto one message at a time was the single largest recoverable cost in a long run — each grep is a whole turn and returns less context than one offset read.
• Issue several view calls in a SINGLE message to read independent files at once
• Use with Glob tool to first find files you want to view
• For code exploration, first use Grep to find relevant files, then View to examine them
• If output is truncated, use offset to read the remaining section

​

write

• Creating new files or updating existing files
• Saving generated code, configurations, or text data

• Provide the file path and content to write
• Parent directories are created automatically

• Creates new files or overwrites existing ones
• Auto-creates parent directories
• Checks for external modifications for safety
• Avoids unnecessary writes when content unchanged

• Cannot append (rewrites entire file)
• Replaces the ENTIRE file — to change part of one, prefer Edit

• Just write over it. Do NOT delete it first — that costs an extra turn and removes the very guard that protects you.
• Reading it first is optional, not required. An unread file is overwritten and the result carries a diff of what was replaced (capped at 60 lines) so you can repair a mistaken clobber with Edit.
• Reading it first is what ARMS the safety check: once you have read a file, a Write is REJECTED if it changed on disk since. That is how you find out another agent owns the file too. Read first when that matters — a shared file, a concurrent run — and report the rejection rather than re-issuing the Write.

• A turn costs a full model generation whether it carries one write or six, so the TURN COUNT is the cost, not the file count. Issue every write whose content you ALREADY HOLD in ONE message; they run in parallel.
• The exception is a write whose content depends on a previous write’s result. That one waits for it.

• Use the LS tool to verify the correct location when creating new files
• Combine with Glob and Grep tools to find and modify multiple files
• Always include descriptive comments when making changes to existing code

​

Information Retrieval

​

code_context

• “Who calls X?” / “What does X call?” — the answers grep cannot compute, because a call site never names the receiver’s type.
• “What implements this interface?” — neither Go nor TypeScript records that at the implementation site, so there is no text to search for.
• “Where is X defined?” when the name is ambiguous across packages or modules.
• Orienting in unfamiliar code: one call replaces the definition->callers->callees walk.

• Go (.go) — resolved by gopls. Authoritative.
• TypeScript / JavaScript (.ts .tsx .js .jsx .mts .cts) — resolved by tsserver from the project’s own TypeScript install. Authoritative.
• Everything else (Python, Ruby, Java, …) — a text engine reports call sites and their enclosing function. Useful for locating, but approximate: it cannot see dynamic dispatch and may include same-named methods on unrelated types. The response labels this explicitly.

• Full-text or pattern search (“find every TODO”, “which files mention retry”) — use bash + rg.
• Reading a file you already located — use view.

• symbol (REQUIRED): the identifier alone, unqualified and with no regex. Good: “ResolveDaemon”, “classifyDaemonWait”, “DaemonRegistryService”. Bad: “svc.ResolveDaemon” (drop the receiver), “Resolve.*” (not a pattern), “func ResolveDaemon” (just the name).
• want: which relationships to return. Default “all”. “all” definition + source + call map + implementations “callers” who reaches this — trace a request path inbound “callees” what this drives — see the work a function delegates “implementations” on an interface: who implements it. On a concrete method: which interfaces it satisfies (the reverse lookup). “definition” still includes the graph; narrows the emphasis, not the answer.
• depth: levels of call graph to expand as a tree. Default 3, max 5. Depth 3 answers “who ultimately triggers this” for typical handler->service->repo layering. Use depth 1 when you only want the immediate neighbors as flat lists.
• file: a path FRAGMENT to disambiguate when a name is declared many times (Execute has dozens here). The response tells you when this is needed and lists the alternatives — pass e.g. file: “daemon_router_nats.go”.
• include_source: first ~30 lines of the definition. On by default, because the usual next question is “what does it do” and that would cost another turn. Set false when you want only the graph.
• scope: “project” (default) keeps results in this workspace INCLUDING sibling repos linked into it, and excludes the standard library, node_modules and vendored code. Use “all” only to deliberately read into a dependency.
• repo: multi-repo projects only — “root” or a repo name. Omit otherwise.
• limit: max entries per flat section. Default 25, max 200. The response says when a section was truncated.

• The first call in a large repo pays a one-time index cost (a few seconds); later calls are fast.
• Results include test files; they are real callers.
• If a language server is missing, the response says so and names the install command.

​

fetch

• Use when you need to download content from a URL
• Helpful for retrieving documentation, API responses, or web content
• Useful for getting external information to assist with tasks

• Provide the URL to fetch content from
• Specify the desired output format (text, markdown, or html)
• Optionally set a timeout for the request (default 30s, hard cap 60s)

• Automatic content extraction using Mozilla Readability (strips nav, ads, footers)
• Supports three output formats: text, markdown, and html
• Follows up to 5 HTTP redirects, http/https only
• Detects likely JavaScript-rendered pages and warns you
• Sets reasonable timeouts to prevent hanging

• max_size: Maximum bytes to read from the response (default: 16000, ~16KB; hard cap: 1048576, 1 MiB). Values above the cap are lowered to it. When the response is longer than the limit it is cut off and a “[Content truncated …]” note is appended; the call still succeeds. The limit applies to the decompressed body.

• Cannot render JavaScript. Single-page apps (SPAs) will return little or no content. The response metadata will include possible_js_rendered=true when this is detected. For JS-heavy sites, consider using browser tools instead.
• Default maximum response size is 16KB (use max_size to raise it, up to 1 MiB)
• Only supports HTTP and HTTPS protocols
• Cannot handle authentication or cookies
• Some websites may block automated requests

• For GitHub repos, use raw.githubusercontent.com URLs instead of github.com (e.g., https://raw.githubusercontent.com/org/repo/main/README.md)
• For API docs that are JS-rendered SPAs, look for the OpenAPI/Swagger JSON spec URL instead
• Use text or markdown format for documentation (html returns raw markup with all chrome)
• If the response says possible_js_rendered=true, the page needs JavaScript to render. Try finding an alternative URL, a raw content source, or use browser tools.
• Adjust max_size for larger documents, up to the 1 MiB cap (but consider context limits)
• Pages larger than 1 MiB are always truncated; look for a smaller raw/API URL instead

• content_length: Size of the extracted content
• raw_html_size: Size of the original HTML before extraction (for HTML pages)
• truncated: Whether content was truncated to fit max_size
• encoding_used: The format that was applied
• page_title: Page title extracted by Readability (when available)
• possible_js_rendered: True if the page appears to be JavaScript-rendered (very little content extracted)
• used_readability: True if Readability content extraction was applied

​

project_analyzer

​

shell

​

⚠️ THE EXECUTING MACHINE’S PLATFORM IS NOT KNOWN — DO NOT ASSUME BASH

• Run one cheap command first (uname -s, or $PSVersionTable) and read the result to find out which shell you actually have, then commit to that dialect.
• Until you know: prefer one command per call over chaining, avoid &&, ||, $VAR expansion, POSIX redirection and shell globbing, all of which mean different things (or nothing) in PowerShell.
• Do not guess path separators; use paths exactly as they were given to you.

​

WHEN NOT TO USE THIS TOOL

• File editing → Use Edit/Write tools
• File reading → Use View tool

​

🔎 SEARCHING THE CODEBASE

​

Go and TypeScript — use the ‘code_context’ TOOL, not this one

​

Other languages

• Otherwise use ‘rg’ when available, falling back to ‘grep -r’ / ‘find’ when it is not.
• ALWAYS search from a relative path (‘rg pattern .’, ‘rg pattern internal/’), never an absolute root.
• Exclude vendored trees, which are large and rarely what you want: rg —glob ‘!node_modules’ —glob ‘!.git’ —glob ‘!dist’ —glob ‘!vendor’ (‘rg’ already honours .gitignore, which usually covers these.)
• Bound the results: ‘rg -l’ for filenames only, ‘rg -m 20’, or pipe to ‘head’. An unbounded match dump can exhaust the output budget on a large repo.
• ⚠️ ‘rg -r’ IS NOT RECURSIVE — do not reach for it out of grep habit. In rg, -r is —replace, so ‘rg -r pattern .’ silently treats your PATTERN as the replacement text and the next argument as the pattern, printing rewritten lines that look like real matches. rg already searches recursively by default, so the flag you want is no flag at all: ‘rg pattern .’.
• Other flags that differ from grep: -t/-T select file TYPES (‘rg -t go’), not the grep meanings, and -f reads patterns from a file.

​

🚫 NEVER SCAN THE FILESYSTEM

• To find something in the project → search a relative path, as above.
• To find a DEPENDENCY’s source on disk → ask the package manager, do not scan: ‘go list -m -f “{{.Dir}}” <module>’, ‘go env GOMODCACHE’, ‘npm root’.
• If you truly need a filesystem search, name a specific directory.

​

⛓️ CHAIN PROBES — ONE CALL ANSWERS MANY QUESTIONS

​

Output Processing

• Default output limit is 16000 bytes (use max_output to customize)
• Use tail_lines to get only the last N lines of output
• Output metadata includes truncation info and original size

• The command argument is required.
• You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 60 seconds.
• Use ‘run_in_background: true’ to run long-running commands in the background. You can then use shell_output to check output, shell_kill to terminate, and shell_list to see all running processes.
• Searching the codebase IS a use of this tool (prefer ‘rg’, scoped to a relative path — see above). For reading whole files, prefer the View tool over ‘cat’/‘head’/‘tail’.
• VERY IMPORTANT: YOU MUST AVOID WRITING FILES USING SHELL. Please use the appropriate edit and create tools.
• When issuing multiple commands, use the ’;’ or ’&&’ operator to separate them. DO NOT use newlines (newlines are ok in quoted strings).

• IMPORTANT: Each command runs in a fresh, stateless shell. Environment variables and directory changes from previous commands do NOT persist.
• IMPORTANT: The current working directory is ALWAYS automatically set to the current worktree. There is NO need to cd to the worktree before running commands - just run them directly.
• To change to a subdirectory within the worktree, use ‘cd’ as part of a compound command (e.g., ‘cd subdir && npm test’).
• Environment variables set in prior shell sessions will NOT be included. Use the ‘env’ parameter to set environment variables for a specific command execution.
• If you need to maintain state across commands (e.g., activating a virtual environment), combine commands with && or ; operators.
• Background processes run in separate shell instances and also start fresh without inherited state.

pytest /foo/bar/tests

cd /foo/bar && pytest tests

• Return an empty response - the user will see the output directly
• Never update git config

​

sourcegraph

• Use when you need to find code examples or implementations across public repositories
• Helpful for researching how others have solved similar problems
• Useful for discovering patterns and best practices in open source code

• Provide a search query using Sourcegraph’s query syntax
• Optionally specify the number of results to return (default: 10)
• Optionally set a timeout for the request

• Basic search: “fmt.Println” searches for exact matches
• File filters: “file:.go fmt.Println” limits to Go files
• Repository filters: “repo:^github.com/golang/go$ fmt.Println” limits to specific repos
• Language filters: “lang:go fmt.Println” limits to Go code
• Boolean operators: “fmt.Println AND log.Fatal” for combined terms
• Regular expressions: “fmt.(Print|Printf|Println)” for pattern matching
• Quoted strings: ""exact phrase"" for exact phrase matching
• Exclude filters: “-file:test” or “-repo:forks” to exclude matches

• Repository filters:
  • “repo:name” - Match repositories with name containing “name”
  • “repo:^github.com/org/repo$” - Exact repository match
  • “repo:org/repo@branch” - Search specific branch
  • “repo:org/repo rev:branch” - Alternative branch syntax
  • “-repo:name” - Exclude repositories
  • “fork:yes” or “fork:only” - Include or only show forks
  • “archived:yes” or “archived:only” - Include or only show archived repos
  • “visibility:public” or “visibility:private” - Filter by visibility
• File filters:
  • “file:.js$” - Files with .js extension
  • “file:internal/” - Files in internal directory
  • “-file:test” - Exclude test files
  • “file:has.content(Copyright)” - Files containing “Copyright”
  • “file:has.contributor([email protected])” - Files with specific contributor
• Content filters:
  • “content:“exact string"" - Search for exact string
  • “-content:“unwanted"" - Exclude files with unwanted content
  • “case:yes” - Case-sensitive search
• Type filters:
  • “type:symbol” - Search for symbols (functions, classes, etc.)
  • “type:file” - Search file content only
  • “type:path” - Search filenames only
  • “type:diff” - Search code changes
  • “type:commit” - Search commit messages
• Commit/diff search:
  • “after:“1 month ago"" - Commits after date
  • “before:“2023-01-01"" - Commits before date
  • “author:name” - Commits by author
  • “message:“fix bug"" - Commits with message
• Result selection:
  • “select:repo” - Show only repository names
  • “select:file” - Show only file paths
  • “select:content” - Show only matching content
  • “select:symbol” - Show only matching symbols
• Result control:
  • “count:100” - Return up to 100 results
  • “count:all” - Return all results
  • “timeout:30s” - Set search timeout

• “file:.go context.WithTimeout” - Find Go code using context.WithTimeout
• “lang:typescript useState type:symbol” - Find TypeScript React useState hooks
• “repo:^github.com/kubernetes/kubernetes$ pod list type:file” - Find Kubernetes files related to pod listing
• “repo:sourcegraph/sourcegraph$ after:“3 months ago” type:diff database” - Recent changes to database code
• “file:Dockerfile (alpine OR ubuntu) -content:alpine:latest” - Dockerfiles with specific base images
• “repo:has.path(.py) file:requirements.txt tensorflow” - Python projects using TensorFlow

• “term1 AND term2” - Results containing both terms
• “term1 OR term2” - Results containing either term
• “term1 NOT term2” - Results with term1 but not term2
• “term1 and (term2 or term3)” - Grouping with parentheses

• Only searches public repositories
• Rate limits may apply
• Complex queries may take longer to execute
• Maximum of 20 results per query

• Use specific file extensions to narrow results
• Add repo: filters for more targeted searches
• Use type:symbol to find function/method definitions
• Use type:file to find relevant files

​

websearch

• Finding current information not available in the assistant’s training data
• Researching documentation, tutorials, or examples online
• Looking up error messages or debugging information
• Finding libraries, tools, or frameworks
• Checking current status of services or projects
• Discovering recent developments or news about technologies

• Provide a search query as you would in a web browser
• Optionally specify the number of results (default: 10, max: 20)

• Use simple, natural language queries with specific keywords
• Keep queries short and focused (3-8 words works best)
• Use minus (-) to exclude terms: python tutorial -django
• Quotes work for simple exact phrases: “react hooks” tutorial

• Boolean operators: OR, AND (e.g. “PUT” OR “POST” will FAIL)
• Complex quoted phrase combinations (multiple quoted phrases with operators)
• site: operator is unreliable and often returns no results
• filetype: operator is unreliable If you need boolean-style searches, run multiple simple queries instead.

• “golang context timeout example” - Simple keywords
• “anthropic claude api documentation” - Natural language
• “Customer.io transactional API” - Product + feature
• “react hooks tutorial 2024” - Topic + timeframe

• “PUT” OR “POST” OR “PATCH” email content - Boolean operators don’t work
• site:customer.io/docs/api specific-page - site: is unreliable
• “exact phrase 1” OR “exact phrase 2” - Complex boolean combos fail

• Start with broad queries, then narrow based on results
• If a search returns 0 results, SIMPLIFY the query - don’t add complexity
• After 3-4 searches on the same topic, synthesize what you have rather than keep searching
• For API documentation, search for the official SDK/client library on GitHub instead
• For GitHub content, prefer fetching raw.githubusercontent.com URLs over github.com

• Title: The title of the search result
• Description: A brief description/snippet from the page
• URL: The link to the resource

• Maximum of 20 results per query
• May have rate limits if used excessively
• DuckDuckGo HTML search has limited query syntax (see above)
• Results may be less comprehensive than Google for niche technical queries

• Start with fewer results (5-10) for faster responses
• Use specific queries to get more relevant results
• Combine with the fetch tool to retrieve full page content from results

​

Workflow Management

​

cel_eval

• To test a trigger filter, an input mapping or a condition in ONE call, instead of activating the trigger and waiting for an event
• To check what a template produces, and what type (a pure {{ }} keeps its type: a number stays a number)
• To find out why an expression fails (the error says whether it is syntax, compile or evaluation, and where)

• integration + event: trigger.payload is GENERATED from the payload that integration declares for the event (the same schema workflow validation checks filters against). Supply trigger_payload to override just the fields your expression depends on; it is merged over the sample.
• trigger_payload alone: a webhook or other source you describe yourself.
• inputs / nodes: values for inputs.* and nodes.<id>.* (scope run).
• With no expression, returns the trigger the event delivers, so you can see what there is to write against.

​

create_workflow

• name: (optional) Workflow name. A random name is generated if omitted.
• content: (optional) Complete workflow YAML. The default agent template is used if omitted.
• complete: (optional) true to mark it complete (runnable). Default: draft.

{}

{
"name": "my-review-workflow",
"content": "name: my-review-workflow\nentry: [agent]\nnodes:\n  - id: agent\n    type: call_llm"
}

​

delete_scenario

​

edit_scenario

{
"name": "happy_path",
"old_string": "outcome: completed",
"new_string": "outcome: error"
}

​

edit_workflow

• Adding or modifying a node
• Updating an edge condition
• Changing input parameters

• id: (required) Workflow UUID, slug, or name (the id returned by create_workflow, or from list_workflows).
• old_string: (required) Exact text to replace.
• new_string: (required) Replacement text.
• expected_version: (optional) Version number for conflict detection.
• complete: (optional) true = mark complete, false = save as draft, omitted = keep current status.

{
"old_string": "  - id: agent\n    type: call_llm",
"new_string": "  - id: agent\n    type: call_llm\n    model: \"{{inputs.model}}\""
}

​

fire_trigger

​

get_cel_reference

• When writing conditions, args, or dynamic values in workflows
• To understand available namespaces and their fields
• To see available custom functions

• All namespaces (inputs, workflow, nodes, iter, output, outputs)
• Field documentation for each namespace
• Custom functions (parseJson, coalesce, etc.)
• Common patterns and examples

​

get_integration_schema

• After search_integrations, before writing a type: action node that uses the ref
• To learn which keys go in the node’s with: and which are required
• To learn the output fields reachable as nodes.<id>.data.<field> in later nodes

​

get_preset

• To view preset configurations
• To understand what a preset provides
• To copy and adapt preset settings

• name: The preset name (from list_presets)

​

get_schema

• When you see a field type like “thread: ThreadConfig” and need details
• When you need to understand node output structure (e.g., CallLLMOutput)
• To explore top-level types (Workflow, Edge)
• To get full field documentation for any type

• Node types: call_llm, loop, workflow, run, execute_tools, join, etc.
• Input types: string, number, boolean, enum, model, message, etc.
• Config types: ThreadConfig, SaveMessageConfig, ProjectConfig, ResponseTool, etc.
• Output types: CallLLMOutput, ExecuteToolsOutput, RunOutput, LoopOutput, etc.
• Top-level: Workflow, Edge, EdgeCase

• get_schema(name=“call_llm”) // Node type
• get_schema(name=“ThreadConfig”) // Config type
• get_schema(name=“CallLLMOutput”) // Output structure
• get_schema(name=“Workflow”) // Top-level workflow structure
• get_schema(name=“Edge”) // Edge routing structure

​

get_workflow

• To view the current state of the workflow you’re editing
• Before making edits to understand the structure
• To read a builtin or project workflow as a starting point

• id: (required) Workflow UUID, slug, or name — including a builtin or project workflow name straight out of list_workflows, or the id from create_workflow.

​

get_workflow_suggestions

• Before starting a new workflow design
• When encountering complexity or unexpected behavior
• To learn best practices for edges, joins, loops, and conditions

• Structure and organization
• Edge routing patterns
• Node vs edge conditions
• Join behavior with conditional sources
• Loop patterns and outputs
• Testing strategies

​

list_presets

• To discover available presets for agent configurations
• To find the right preset for a specific task
• Before using get_preset to view details

​

list_scenarios

​

list_trigger_events

​

list_triggers

​

list_workflows

• To discover available workflows
• To find workflow patterns for common use cases
• Before using get_workflow to view details

​

run_scenario

​

search_integrations

• Before writing a workflow node of type: action: find the ref to put in its uses:
• To check whether an integration (GitHub, Slack, HTTP, …) can do something
• To see which integrations the user has already connected

• id: open_issue type: action uses: github/issue.create@1 # the ref with: { ... } # keys from the params schema

​

view_scenario

​

write_scenario

name: scenario_name
description: What this scenario tests
events:
  - node: node_id           # Optional: target specific node
    output:                  # Mock output for the node
      message:
        role: assistant
        text: "Hello!"
      response_text: "Hello!"
expect:
  outcome: completed         # or "error" / "failed"
  reached: ["node1", "node2"]
  not_reached: ["node3"]

  - node: call_llm
    type: llm_response       # llm_response | tool_result; any other node takes a raw output
    text: "Hello!"
    tool_calls: [{name: bash, input: {command: ls}}]
  - node: execute_tools
    type: tool_result
    tool: bash
    tool_output: {result: "file.txt"}
    is_error: false          # marks the tool result as failed

• outcome: completed | error | failed
• reached / not_reached: whether a node was SCHEDULED. reached includes nodes that were skipped or errored, so it does NOT prove a node ran.
• completed: nodes that must have EXECUTED successfully. This is the assertion that excludes skipped nodes — use it, not reached, to prove a branch ran.
• skipped: nodes that must have been scheduled but skipped by a false condition.
• error_contains / error_node: for outcome: error
• node_outputs: {node_id: {field: expected}} — partial match on a node’s output
• outputs: {name: expected} — the workflow’s declared outputs. Keys support dotted paths (e.g. “response.choice”: “complete”).

• Top-level nodes: node: “call_llm”
• Inner loop nodes: node: “agent_loop.call_llm” (dot-separated)
• Nested loops: node: “outer_loop.inner_loop.call_llm”

{
"name": "happy_path",
"content": "name: happy_path\ndescription: Test happy path\nevents:\n  - output:\n      message:\n        role: assistant\n        text: Hello!\n      response_text: Hello!\nexpect:\n  outcome: completed"
}

​

write_workflow

{
"content": "name: my-workflow\nentry: [agent]\nnodes:\n  - id: agent\n    type: call_llm"
}

• name: Workflow name
• entry: List of entry point node IDs
• nodes: Array of node definitions
• edges: Array of edge definitions (optional for single-node workflows)

• id: (required) Workflow UUID, slug, or name (the id returned by create_workflow, or from list_workflows).
• name: (optional) Overrides the name in YAML. Used for display name.
• content: (required) Complete workflow YAML content.
• expected_version: (optional) Version number for conflict detection.
• complete: (optional) true = mark complete, false = save as draft, omitted = keep current status.

​

System & Execution

​

shell_kill

• Can kill any process in the current workspace, regardless of which chat started it
• Multiple chats in the same workspace share process visibility
• This enables coordination: one chat can stop a server started by another

• Process IDs are provided when you start a background process with run_in_background: true
• You can only kill processes that are currently running
• After killing a process, its output is still available via shell_output
• Use shell_list to see all running background processes in the workspace

1. Start a background process: bash(command=“npm run dev”, run_in_background=true)
2. Kill the process: shell_kill(process_id=“<id-from-step-1>”)

​

shell_list

• Processes are scoped to the current workspace (worktree)
• Multiple chats in the same workspace share the same process list
• This enables coordination: one chat can start a server, another can check its status
• Use shell_output to view output and shell_kill to terminate any workspace process

• By default, shows only running processes in the current workspace
• Use ‘all: true’ to include completed, failed, and killed processes
• Process IDs can be used with shell_output and shell_kill tools

• Running processes: Shows ID, command, and how long they’ve been running
• Completed processes: Shows ID, command, exit code, and duration
• Failed processes: Shows ID, command, exit code, and error indication

1. List running processes: shell_list()
2. List all processes including completed: shell_list(all=true)

​

shell_output

• Can read output from any process in the current workspace, regardless of which chat started it
• Multiple chats in the same workspace share process visibility
• This enables monitoring: check on servers or builds started by other chats

• Process IDs are provided when you start a background process with run_in_background: true
• The tool will indicate if the process is still running or has completed
• If the process has completed, the exit code will be provided
• Output is not cleared after reading - you can re-read from any position

1. Standard Pagination (default):
   • offset: Start reading from byte N (default: 0)
   • limit: Read up to N bytes (default: 16000)
   • Can be combined: offset + limit
2. Tail Mode:
   • tail: Get last N lines
   • Cannot be combined with: regex, offset, limit
3. Regex Filter Mode:
   • regex: Filter output to lines matching pattern
   • When set, tool filters FIRST, then applies offset/limit to filtered results
   • Can be combined with: offset, limit, regex_case_insensitive, regex_context_before, regex_context_after
   • Cannot be combined with: tail
   • Optional parameters:
     • regex_case_insensitive: Case-insensitive matching
     • regex_context_before: Include N lines before match (like grep -B)
     • regex_context_after: Include N lines after match (like grep -A)

• offset + limit (standard pagination)
• tail (alone)
• regex (alone)
• regex + offset + limit (filtered pagination)
• regex + regex_case_insensitive + regex_context_before + regex_context_after

• tail + regex
• tail + offset
• tail + limit
• regex_case_insensitive without regex
• regex_context_before/after without regex

1. Start a background process: bash(command=“npm run dev”, run_in_background=true)
2. Get first chunk: shell_output(process_id=“<id>”)
3. Get next chunk: shell_output(process_id=“<id>”, offset=16000)
4. Get last 100 lines: shell_output(process_id=“<id>”, tail=100)
5. Filter for errors: shell_output(process_id=“<id>”, regex=“ERROR|FATAL”)
6. Filter with context: shell_output(process_id=“<id>”, regex=“ERROR”, regex_context_after=3)
7. Filter and paginate: shell_output(process_id=“<id>”, regex=“WARN”, offset=0, limit=10000)

• has_more: true if more output is available
• next_offset: where to start reading for the next chunk
• total_available: total bytes available in the (filtered or original) output
• filter_applied: true if regex was used
• total_matches: number of matching lines (when filtered)
• matches_in_response: number of matches in this chunk

​

shell_wait

• Waiting for a long build, test suite, or install to finish
• Any time the next thing you do depends on a background process being done

• A long-running server you never expect to exit (use shell_output to check on it)
• You only want progress so far, not completion (use shell_output)

1. Start the work in the background: bash(command=“npm test”, run_in_background=true)
2. Do any useful work that does not depend on the result — read the next file, prepare the following edit. The process runs while you do.
3. Wait for it: shell_wait(process_id=“<id>”)

• Exit code and status once the process has exited
• The last tail_lines lines of output (default 50), so a passing build or a failing test usually needs no follow-up call
• timed_out: true, with no exit code, if the budget elapsed first

​

Other Tools

​

ask_user

1. Clarify ambiguous instructions
2. Get user preferences or decisions
3. Offer choices about implementation direction
4. Confirm before taking significant actions

• The user will always have an option to provide freetext input in addition to any predefined options.
• If you recommend a specific option, list it first and add “(Recommended)” to the label.
• Use allow_multiple: true when choices are not mutually exclusive.
• Group related questions in a single call (up to 4 questions).

​

component_library

• Building any UI — search for relevant components first
• Creating charts or diagrams — components handle all coordinate math
• Building pitch deck slides — use deck components as templates
• Need a layout pattern — search by use case (dashboard, landing, portal, crm)
• Building CRUD/admin interfaces — badge, modal, tabs, pagination, toast, etc.

• search: Find components with unified keyword search Examples: search(query=“crud table admin”), search(query=“chart dashboard”), search(tag=“deck”)
• get: Retrieve full source code for a specific component Example: get(name=“quadrant_chart”)
• install: Write a component file to disk at the given path Example: install(name=“sidebar_left”, path=“src/components/layouts/sidebar_left.tsx”)
• list: Browse all components (optionally filtered by tag or category)

• forge_integrated: Set to true in forge-generated projects to get integration guidance for useUiStore, useEventBus, and useAuth

​

control_run

• pause: park the run at its next step boundary. It stays alive and resumable.
• resume: continue a paused (or interrupted) run from where it stopped.
• cancel: hard-stop the run. This is terminal — a cancelled run is not resumed; sending it a message starts a fresh run in the same chat.

​

generate_image

• The user asks for an image, illustration, diagram, icon, logo or mockup.
• You need a visual asset to write into the project (pair with save_to).

• Describe the image in detail. Prompt quality dominates the result: name the subject, the style, the composition, the palette, and any text that must appear. A one-line prompt gets a one-line-prompt image.
• Use size to choose orientation, quality to trade cost for fidelity, and background=transparent for anything that will sit on top of other content.
• Set save_to to also write the file into the project. Without it the image is still generated and returned; it just is not written to disk.

• The image itself, which you can see and describe or critique.
• An attachment id. Cite that id when referring to this image later, and pass it to read_attachment to look at it again in a future turn.

• standard (default): the best everyday image model. Use it for finals.
• fast: the quicker model, for drafts, thumbnails and quick iterations.
• To pin one exact model instead, pass model with an id.
• Ask the user first when cost matters. The result names the model that ran and why; tell the user, and change tier if it was not what they wanted.
• tier picks WHICH model; quality (below) is how hard that model works.

• One image per call. Call again to iterate; say what to change rather than repeating the original prompt verbatim.
• A model or tier the user’s providers cannot serve returns an error naming the tiers that are available.

​

generate_video

• standard (default): the everyday choice. A multimodal generalist: best for iterating, editing a previous clip (edit_from), keeping characters consistent with reference images, and physically plausible motion. 3–10s. It RENDERS at 720p; 1080p and 4K are upscaled from that, so they are not truly sharper.
• cinematic: a polished one-shot final. A dedicated cinematic engine that renders 1080p and 4K NATIVELY, with native audio and the best clean first-pass quality. Pick it when sharpness or a finished look matters. Costs about 4x more than standard, and cannot be edited conversationally (it can only be extended), so each change is a full re-render.
• fast: drafts and previews. The cheapest tier; no 4K, no reference images.
• To pin one exact model instead, pass model with an id.
• Ask the user first when the trade-off matters, for example cost when they want 4K or a long cinematic clip.
• The result names the model that actually ran and why. Tell the user, and change quality if it was not what they wanted.

• Costs roughly $0.05 to $0.60 PER SECOND of video, depending on the model and resolution. Resolution defaults to 720p to keep cost down. Prefer short clips.
• A render takes 30 seconds to several minutes and blocks this turn until it finishes.

• Describe the subject, the action, the camera and the style. Mention sound or dialogue if you want it.
• BY DEFAULT THE MODEL CUTS BETWEEN SEVERAL SHOTS and invents a small narrative. Unless the user wants cuts, write “in a single continuous shot, no scene cuts” (or “single unbroken scene”) into the prompt. Without it a request for one moment comes back as a montage.
• To animate an existing image set start_frame to its attachment id.
• To refine a clip you already made, pass its edit handle as edit_from and describe ONLY the change (“make it slower, keep everything else the same”). Keep edit prompts short: long, descriptive ones change things you did not ask about. Only models that support edits give you an edit handle; otherwise regenerate with the full prompt.

• Text only. YOU CANNOT SEE THE VIDEO. The user can play it in the chat. Say what you asked for, not what the video shows, and invite them to review it.
• An attachment id, and an edit handle when the model supports edits.

• A model or quality the user’s providers cannot serve returns an error naming the tiers that are available.

​

get_run

​

github__branch_get

​

github__code_search

​

github__issue_comment

​

github__issue_comment_list

​

github__issue_comment_update

​

github__issue_create

​

github__issue_get

​

github__issue_labels_add

​

github__issue_labels_remove

​

github__issue_search

​

github__issue_update

​

github__labels_create

​

github__labels_list

​

github__pr_create

​

github__pr_get

​

github__pr_list_files

​

github__pr_review_comment_reply

​

github__pr_review_comments_list

​

github__pr_review_create

​

github__pr_reviews_list

​

github__pr_update

​

github__repo_get

​

github__repo_get_content

​

github__repo_get_tree

​

github__repo_list_for_user

​

github__user_get

​

github__workflow_dispatch

​

gmail__label_list

​

gmail__message_get

​

gmail__message_list

​

gmail__message_send

​

http__request

​

list_pending_questions

• Before you finish a task: check for async questions still unanswered. If you went ahead on a default and the answer no longer matters, withdraw it with withdraw_question so it leaves the user’s inbox. If it still matters, say so in your final answer.
• Before asking the user something: avoid asking a question that is already pending.

​

list_runs

​

load_tool

• Load a specific tool by name: {"name": "sourcegraph"}
• Load every tool carrying a tag in one call: {"name": "tag:workflow"} (each tool is still individually checked against what this agent may load)
• Search for tools by keyword or tag name: {"query": "workflow"}

​

metadata_writer

​

report_bug

• reliant: a tool returns wrong or broken output, a message reaches you truncated or garbled (e.g. “[content trimmed]”), the daemon, workspace or working directory vanishes, a chat or sub-agent is stuck or cannot resume, the UI shows something wrong.
• forge: a forge command fails, hangs or generates something wrong, or a forge lint, skill or doc is wrong.

​

request_machine

​

send_to_run

​

sentry__event_get

​

sentry__issue_get

​

sentry__issue_list

​

sentry__issue_update

​

sentry__project_list

​

skill

• section: fetch one markdown section by heading. Preferred — every load lists the skill’s sections, so this is usually one targeted call rather than guessing byte ranges.
• offset / limit: page through the current view by byte range.
• regex (+ regex_case_insensitive, regex_context_before, regex_context_after): deliver only matching lines, numbered, to locate content before fetching it.

​

slack__conversations_history

​

slack__conversations_list

​

slack__message_post

​

slack__message_reply

​

slack__message_update

​

slack__reaction_add

​

slack__user_lookup_by_email

​

spawn_send

​

spawn_status

• Only shows/waits on agents YOU spawned (your direct children), never a sibling’s or another thread’s sub-agents.
• Exception: if this chat was BRANCHED from a conversation that had already spawned agents, those are listed too, marked “Inherited … (read-only)”. You can inspect them (agent_id without wait), but they still belong to the original conversation: their results are delivered there, and only it can wait on, message, or stop them.

1. LISTING (omit agent_id): returns every sub-agent you spawned — agent_id, title, preset, status, elapsed time, last activity time, turn count, and whether it appears gated on a question or approval (best-effort — this signal can be unavailable and is never a hard guarantee).
2. SINGLE AGENT (agent_id set): returns that agent’s status and its LAST ASSISTANT MESSAGE — “is it done, and what did it say?” without cancelling it.

​

spawn_stop

​

start_run

​

twilio__message_get

​

twilio__message_list

​

twilio__message_send

​

twilio__phone_number_list

​

wait_for_machine

• The tool failed for some other reason (bad arguments, a command that exited non-zero). Only a machine that is not connected is worth waiting on.
• To start, wake or restart the machine. This never does — it only watches.

• connected: true once the machine is attached — retry the call that failed
• otherwise its last known state (disconnected, starting, suspended, failed, removed) with what to do about it

​

withdraw_question

​

worktree

1. create - Required: name. Optional: branch, base_branch, copy_files, force Returns the worktree id, the workspace root path, the branch, and the path of each repository’s checkout. The name must be unique among the project’s live worktrees; an archived (deleted) worktree’s name can be reused.
2. list - List the project’s worktrees (any state: creating, active, failed)
3. get - Required: name. Details, paths and owner of one worktree
4. delete - Required: name. Archives the worktree; its directory is removed later, only when it is clean, its work is pushed or already merged, and it is unused. Refuses your own current worktree and any worktree a chat is using.

• Pass its name to spawn: spawn(worktree=<name>) runs the sub-agent inside it, so its shell and file tools work on that branch.
• Or use the absolute paths from the result with commands that take a path (cd <path> && …).
• Commit and push from inside the worktree; each repository’s checkout is on its own branch.

• copy_files: exact paths relative to the project root, for gitignored files a fresh checkout lacks (the new worktree mirrors the project’s layout)
• Nothing is searched for: “.env” copies only the root .env; name “frontend/.env” to copy that one
• A directory is copied whole (e.g. “web/node_modules”); a missing path is skipped
• When you are working inside a worktree, files are copied from that worktree

• Result fields are stored in CEL context as ‘worktree_data’: id, name, path, branch, base_branch, project_id, status, session_id, checkouts

{
"action": "create",
"name": "feature-auth",
"base_branch": "main",
"copy_files": [".env", "frontend/.env.local"]
}
then spawn a sub-agent in it with spawn(worktree="feature-auth").