02 — Tools
The tool catalog the agent has access to. Every tool exposed to the model is registered through the same interface, validated by the same schema layer, and executed through the same sandbox. New tools — built-in or MCP-provided — slot in without modifying the loop.
Tool call protocol
A small core set rides on every turn: read, write, edit, glob, grep, bash / pwsh, todo_write, ask_user_question, skill, subagent, recall, plus the two gateway tools tool_search and tool_call. Everything else is a deferred tool: listed in the tool catalog, costing nothing until it is used, and reached with tool_call(name, arguments) after tool_search(query) or a read of ~/.picasso/tool-catalog/INDEX.md (see lean-context-architecture.md). The tool catalog holds 70 tools in six groups:
| Group | Tools |
|---|---|
| core (14) | the always-on set above |
| jobs-terminal (9) | job_list, job_output, job_kill, terminal_open / read / send / signal / list / close |
| team-subagents (13) | create_worktree, spawn_teammate, subagent_fork, send_message, message_subagent, wait_agent, list_agents, interrupt_agent, interrupt_subagent, team_task_create / get / list / update |
| workflow-goal (10) | create_goal, get_goal, update_goal, exit_plan_mode, ralph, workflow, schedule_create / edit / list / view |
| session-web (10) | web_fetch, web_search, read_image, present, working_directory, session_search, session_trace, session_event_read / search / trace |
| picasso-extensions (14) | browser_navigate / click / type / press_key / scroll / snapshot / screenshot / console, remember, repo_map, repo_search, send_mail, present_options, x_read |
MCP servers add one <server>_call(tool, arguments) gateway each; a direct <server>_call runs without a catalog read first, and a changed MCP configuration reaches the next new session.
Asking the person: present_options
present_options shows 2–4 options (each HTML, an image, code or text) and waits for a pick. Picasso for Mac opens an options window (Pick this or 1–4, an optional note, Send ⏎, Skip esc); the terminal app shows a numbered list (←/→ or n/p to move, o opens one). When a turn asks two or more questions or approvals at once, they arrive as one numbered Decisions card ("N of M answered", then Continue); approvals offer Allow / Allow for this thread / Deny (1/2/3 in the terminal app).
Reading X: x_read, /x and picasso x
X blocks plain page fetches, so Picasso reads public X through the third-party x.md service (mdfromx.com). A web_fetch of an x.com, twitter.com or t.co link is rewritten to x.md automatically. The deferred x_read tool covers a post, replies, a search, a profile, followers, following, history and an interaction circle. People use /x <url>, /x search <query> [feed], /x @handle [followers|following|history] and /x circle @handle in the terminal app and the Mac app (which also offer an X-link paste card), or picasso x … [--json] in a shell. X links you open are sent to this third-party service. It is on by default; picasso settings set xReader off (or the Mac Settings card) turns it off, and an optional x.md key is kept in the Keychain with picasso settings x-reader-key set|remove|status. Private, protected, DM and List content is not supported, and a failed read is an error, never an invented answer.
Runtime note
The core tool set (read/write/edit/glob/grep/bash/subagent/jobs/skill/goal/todo/web_search) executes inside the engine; tool names pass through tool-called/tool-returned LoopEvents. See architecture.