| 1 | # Tool Contract |
| 2 | |
| 3 | <a href="./TOOL_CONTRACT.zh-CN.md">简体中文</a> |
| 4 | |
| 5 | This document records the provider-visible contract for Reasonix compile-time built-in tools. It is generated from the same canonical schema path used by the runtime registry. |
| 6 | |
| 7 | | Tool | Read-only | Description | |
| 8 | | --- | --- | --- | |
| 9 | | `bash` | false | Execute a command in the shell and return combined stdout/stderr. Use for builds, tests, git, package managers, etc. To search/read/list/edit/move files, prefer the dedicated tools (grep, read_file, ls, glob, edit_file, move_file) over shell grep/cat/ls/find/sed/mv/Move-Item - they behave identically on every OS. For symbol search or architecture questions, prefer LSP/read tools and targeted grep before shell commands. | |
| 10 | | `bash_output` | true | Read new output from a background job started with bash(run_in_background=true) or task(run_in_background=true). Returns the output produced since the last bash_output call for that job, plus its status (running/done/failed/killed). Does not block. | |
| 11 | | `code_index` | true | Lightweight built-in code symbol index. Prefer lsp_* for language semantics and installed code graph MCP tools for call graph, impact, and architecture relationships; use this as the local fallback for file outlines and symbol definition candidates, then verify with read_file or grep. | |
| 12 | | `complete_step` | true | Record the evidence-backed completion of ONE step of an approved plan. Call it as you finish each step instead of silently moving on: it signs the step off with PROOF it is done - the verification you ran (command + result), the diff/files you changed, or a manual check. A completion with no evidence is REJECTED, so don't claim a step is done until you can show why. The host advances the task list for you when you sign off - it marks this step completed and moves the next to in_progress, so you don't need a separate todo_write to mark completions. Fields: `step` (which step - its title or number, matching the task list), `result` (what is now true/changed), `evidence` (>=1 item, each with `kind` = verification\|diff\|files\|manual and a `summary`, plus optional `command`/`paths`), and optional `notes`. | |
| 13 | | `delete_range` | false | Delete a contiguous text range from a file using exact start/end text anchors. Each anchor must match exactly one line. Returns unified diff on success. Use for large deletions - smaller changes should use edit_file. | |
| 14 | | `delete_symbol` | false | Delete a named symbol (function, method, type, interface, const, var) from a Go source file using AST parsing. For non-Go files, use delete_range with manual anchors. | |
| 15 | | `edit_file` | false | Replace an exact string in a file with another. old_string must occur exactly once; add surrounding context to disambiguate. Use for targeted edits instead of rewriting the whole file. | |
| 16 | | `glob` | true | Find files matching a glob pattern (e.g. "*.go", "internal/*/*.go", "**/*.test.ts"). Supports shell metacharacters * ? [] and the recursive ** pattern. | |
| 17 | | `grep` | true | Search for a regular expression in a file, or recursively under a directory (skips hidden files and files matched by .gitignore). Returns matching lines as path:line:text, capped at 200 matches. | |
| 18 | | `kill_shell` | false | Terminate a running background job (bash or task) started with run_in_background. A no-op if the job has already finished or the id is unknown. | |
| 19 | | `ls` | true | List the entries of a directory. Directories are shown with a trailing slash; files show their byte size. Set recursive=true to list all nested files depth-first (skips .git/node_modules). | |
| 20 | | `move_file` | false | Move or rename a file from source_path to destination_path. Creates the destination parent directory as needed. Use instead of shell mv, Move-Item, or ren for file moves so workspace confinement and file-edit permissions apply. | |
| 21 | | `multi_edit` | false | Apply a list of edits to a single file atomically: each edit runs against the result of the previous one, all in memory; the file is rewritten only if every edit succeeds. Cheaper and safer than chaining edit_file calls - a failure in step 3 leaves the file untouched instead of half-edited. | |
| 22 | | `notebook_edit` | false | Edit one cell of a Jupyter notebook (.ipynb). Target a cell by 0-based cell_number (or cell_id). edit_mode: "replace" (default) swaps the cell's source; "insert" adds a new cell after cell_number (use -1 to prepend at the top), taking cell_type and new_source; "delete" removes the cell. cell_type is "code" or "markdown" (required for insert). Editing a code cell clears its outputs. Prefer this over edit_file for notebooks - it keeps the JSON valid. | |
| 23 | | `read_file` | true | Read a text file with optional line offset/limit. Output prefixes each line with its 1-based number so subsequent edit_file calls can target exact lines. Use `offset` and `limit` to page through large files; the tool reports total length and pagination hints in a trailer. | |
| 24 | | `todo_write` | true | Record and update a structured task list for the current work. Send the COMPLETE list every call - it replaces the previous one. Use it to plan multi-step work and show progress: keep exactly one item in_progress at a time, and flip an item to completed the moment it's done (don't batch completions). Skip it for trivial single-step tasks. | |
| 25 | | `update_goal` | true | Report this turn's disposition for the active goal: `continue` (work is ongoing - give a concrete next_action), `complete` (fully done and verified), or `blocked` (only the user can unblock). The host validates the claim against Delivery acceptance criteria and budget and decides whether to continue automatically. Outside an active goal turn the call fails closed without changing any state. | |
| 26 | | `wait` | true | Block until background jobs finish, then return each job's status and final output/answer. Use to collect the result of a task(run_in_background) or bash(run_in_background) before continuing. Omit job_ids to wait for every running job. | |
| 27 | | `web_fetch` | true | Fetch a URL over HTTPS/HTTP and return its text content. HTML pages are reduced to readable text; JSON / plain text / markdown bodies come back verbatim. Use to read documentation pages, API responses, or source files hosted somewhere the local filesystem can't reach. | |
| 28 | | `write_file` | false | Write content to a file at the given path (overwriting existing content). Creates parent directories as needed. | |
| 29 | |
| 30 | ## Schema Snapshot |
| 31 | |
| 32 | The exact canonical schemas are intentionally tested in code rather than copied by hand here. Run: |
| 33 | |
| 34 | ```bash |
| 35 | go test ./internal/tool -run TestBuiltinToolContractDocumentation |
| 36 | ``` |
| 37 | |
| 38 | The test checks that every registered built-in tool has a documented name, read-only flag, description row, and canonical schema generated by `tool.BuiltinContractEntries`. |
| 39 | |
| 40 | ## Default Full Boot Surface |
| 41 | |
| 42 | In a default full-token boot, Reasonix sends the built-in tools above plus the |
| 43 | session, memory, skill, subagent, LSP, install, and slash-command tools below: |
| 44 | |
| 45 | Single-model Balanced uses this exact executor tool surface. Balanced with a |
| 46 | distinct Planner and every Delivery session additionally expose one stable |
| 47 | proxy, `use_capability`, so optional MCP servers (including `auto_start=false`) |
| 48 | can be inspected and called without changing provider-visible schemas |
| 49 | mid-session. Delivery also |
| 50 | adds a stable execution contract enforced by the host: state-changing and |
| 51 | verification commands need acceptance criteria; changed work cannot finalize |
| 52 | without post-change review, verification, and an evidence-backed |
| 53 | `complete_step` sign-off; Skill/MCP `require`/`prefer` routes are gated with |
| 54 | host-proven evidence (including read-only answers — ordinary reads never skip |
| 55 | a required capability); and medium/high-risk mutations force structured |
| 56 | `review` / `security_review` results via the review-only `review_report` tool, |
| 57 | whose `reviewed_paths` must be backed by host-observed read/diff receipts. |
| 58 | |
| 59 | The two-model Planner and all task/fleet sub-agents also use `use_capability` |
| 60 | (and never direct `mcp__*` schemas). Planner and ordinary writer-capable |
| 61 | sub-agents may call installed or project-configured MCP without |
| 62 | `readOnlyHint`; Planner leaves `destructiveHint` tools for the Executor, while |
| 63 | ordinary sub-agents use the trusted MCP path (live authorization plus explicit |
| 64 | deny only). Writer/destructive calls are still serialized and recorded as |
| 65 | mutations for evidence, workspace leases, and Delivery guards. Strict read-only sub-agents |
| 66 | share the same proxy schema and Host connections but still require |
| 67 | `readOnlyHint` and non-destructive at execution time. Balanced dual-model |
| 68 | attaches independent proxy frontends to both Planner and Executor so a |
| 69 | capability discovered during planning remains directly callable after handoff; |
| 70 | their ledgers/audits are isolated while Host connections are shared. Economy |
| 71 | remains single-model without an independent Planner. |
| 72 | |
| 73 | `use_capability` resolution is side-effect free: `action=list` returns sorted |
| 74 | configured MCP servers without starting them; `action=call` on a |
| 75 | not-yet-connected server resolves to a deferred target, Plan re-checks only an |
| 76 | explicit phase opt-out on the real target, and the server process starts only |
| 77 | after the permission gate and PreToolUse hooks approve the call. On-demand children |
| 78 | share the session lifetime (they outlive the starting call and exit with the |
| 79 | session); `action=inspect` lists live tools for connected servers and cached |
| 80 | schemas otherwise, never starting a process. First discovery of a server with |
| 81 | no schema cache goes through `action=call` on the `mcp-server:` id itself: it |
| 82 | resolves to a gated connect (permission name = the server's dedicated |
| 83 | `mcp_connect__<server>` identity, so an exact rule such as |
| 84 | `deny = ["mcp_connect__github"]` blocks process startup) that connects after |
| 85 | approval and returns the live tool directory. MCP tool rules remain exact; |
| 86 | `mcp__github__*` is not a tool-name glob. Installing an MCP authorizes the |
| 87 | Planner to use its non-destructive tools; third-party servers that omit |
| 88 | `destructiveHint` are treated as user-install trust. Before every connect or |
| 89 | `tools/call`, the frontend re-checks the current runtime enablement, |
| 90 | authorization, and exact Host connection identity; another project/tab's |
| 91 | same-name shared client is rejected without process, network, or tool dispatch. |
| 92 | |
| 93 | The fixed proxy's provider-visible name, description, schema, and ordering do |
| 94 | not change when MCP inventory changes. Balanced Executor deliberately retains |
| 95 | its direct `mcp__*` tools, so its overall provider prefix may still change when |
| 96 | those direct tools are installed, connected, or refreshed. |
| 97 | |
| 98 | `ask`, `docs`, `explore`, `fleet`, `forget`, `history`, `install_skill`, `install_source`, |
| 99 | `list_sessions`, `lsp_definition`, `lsp_diagnostics`, `lsp_hover`, |
| 100 | `lsp_references`, `memory`, `parallel_tasks`, `read_only_skill`, |
| 101 | `read_only_task`, `read_session`, `read_skill`, `read_subagent_result`, `remember`, `research`, |
| 102 | `review`, `run_skill`, `security_review`, `slash_command`, `task`. |
| 103 | |
| 104 | `parallel_tasks` and `fleet` keep their combined result below the single-tool |
| 105 | output limit by returning a fair preview and a stable `Subagent reference` for |
| 106 | every persisted child. `read_subagent_result` pages through one referenced |
| 107 | final answer by UTF-8 byte offset, so long parallel research remains lossless |
| 108 | without injecting every report into the parent context at once. References are |
| 109 | restricted to the current conversation lineage and workspace. |
| 110 | |
| 111 | `use_capability` (`action` = `list` | `inspect` | `call` | `decline`): Delivery |
| 112 | Executor, plus both Planner and Executor in Balanced dual-model sessions; not |
| 113 | enabled in Economy. |
| 114 | |
| 115 | `internal/boot.TestBootToolContractMatchesProviderVisibleSurface` verifies the |
| 116 | actual boot registry contract against the provider request, including read-only |
| 117 | flags and canonical schemas. |
| 118 | |
| 119 | ## Token Economy Boot Surface |
| 120 | |
| 121 | In token economy mode, Reasonix starts with nine tools: four direct coding tools, |
| 122 | the three background-shell lifecycle tools, `ask`, and the connector used to |
| 123 | enable optional sources on demand: |
| 124 | |
| 125 | `ask`, `bash`, `bash_output`, `connect_tool_source`, `edit_file`, `kill_shell`, |
| 126 | `read_file`, `wait`, `write_file`. |
| 127 | |
| 128 | Everything else is explicit and on demand. `connect_tool_source` supports |
| 129 | `docs` (the read-only embedded `docs` tool), `search` (`code_index`, `glob`, |
| 130 | `grep`, `ls`), `files` (specialized move, |
| 131 | multi-edit, delete, and notebook tools), `workflow` (`todo_write`, |
| 132 | `complete_step`), `sessions` (`history`, `list_sessions`, `read_session`), |
| 133 | `memory` (`memory`, `remember`, `forget`), `commands` (`slash_command`), |
| 134 | `skills`, `read_only_skill`, `mcp`, `lsp`, `web_fetch`, `install_source`, |
| 135 | `task`, and `read_only_task`. Every source may be connected in Plan; subsequent |
| 136 | reader and writer calls use the same Permissions/Sandbox path as Standard mode. |
| 137 | `workflow` is the phase-specific exception: while planning it installs only |
| 138 | `todo_write`; `complete_step` joins on a fresh `workflow` connect after plan |
| 139 | approval. Use `bash` for listing and search until the dedicated `search` source |
| 140 | is needed. |
| 141 |