Built-in Tools

Swarmie registers its built-in tools in crates/tools/src/registry.rs via core_registry().

core_registry() is the portable baseline. Runtime-specific tools (for example orchestration tools like branch, and CLI runtime tooling like cron) are registered in higher layers, not in core_registry() itself.

The current core registry includes 15 tools:

Tool	Purpose	Key Parameters
`bash`	Run shell commands in the workspace.	`command` (required), `timeout`, `description`
`read`	Read file contents (text or image).	`file_path` (required), `offset`, `limit`
`glob`	Find files by glob pattern.	`pattern` (required), `path`
`grep`	Search file content by pattern.	`pattern` (required), `path`, `output_mode`, `glob`, `type`, `-i`, `-A/-B/-C`, `-n`, `multiline`, `head_limit`, `offset`
`write`	Write/replace file contents.	`file_path` (required), `content` (required)
`edit`	Replace a string in a file.	`file_path`, `old_string`, `new_string` (required), `replace_all`
`web_fetch`	Fetch a URL and return content.	`url` (required), `prompt`
`web_search`	Search the web.	`query` (required), `allowed_domains`, `blocked_domains`
`notebook_edit`	Modify Jupyter notebook cells.	`notebook_path`, `new_source` (required), `cell_number`, `cell_type`, `edit_mode`
`patch`	Apply unified diff patches.	`patch` (required), `file_path`
`file_search`	Fuzzy filename search in workspace.	`query` (required), `limit`
`memory_write`	Append project memory notes.	`content` (required), `file`
`undo`	Revert the latest ghost snapshot.	`rollout_path` (required)
`backlog`	Manage beads backlog issues (`ready`, `show`, `update`, etc.).	`command` (required), command-specific fields
`question`	Ask the user for mid-turn input and wait for a reply.	`question` (required), `options`

Examples

Read a file segment

{"file_path":"/abs/path/src/main.rs","offset":120,"limit":80}

Search text with context lines

{"pattern":"SwarmConfig","path":".","output_mode":"content","-C":2}

Apply an edit

{"file_path":"/abs/path/src/lib.rs","old_string":"foo","new_string":"bar","replace_all":false}

Fetch from the web

{"url":"https://example.com/docs","prompt":"Extract the API authentication section"}

Question Tool (Ask-User)

question is a built-in interaction tool for user input during an active turn. Instead of completing immediately, runtime emits a question request event and waits for Op::QuestionReply.

Schema:

question: string (required) - prompt text shown to the user
options: string[] (optional) - predefined answer choices

Runtime behavior:

Core intercepts this tool path in crates/core/src/turn/tool_execution.rs (handle_question_tool).
Frontends receive Event::QuestionRequest { request_id, question, options, agent_name }.
The tool result becomes the answer text returned by the user.

References:

specs/protocol.md (Event::QuestionRequest, Op::QuestionReply)
specs/core-runtime.md (NeedQuestion, AwaitingQuestion)

Notes

Input validation happens per tool implementation in crates/tools/src/*.rs.
Most filesystem tools require paths to stay within the current workspace root.
Tool usage still goes through Swarmie's permission evaluator before execution.