# Tools agent guide
Built-in contracts, routing, filesystem access, and external bridges live here.
## Where to look
| Canonical registry, schemas, arguments | `capability.rs`, `contract.rs`, `args.rs` |
| Provider descriptions | `descriptions.rs`, `../../prompts/tools/` |
| Routing and runtime state | `dispatch.rs`, `runtime.rs`, `mod.rs` |
| Path policy, writes, traversal | `fs.rs`, `workspace.rs`, `fs_cache.rs` |
| Anchored editing and content search | `hash_edit/`, `grep/`; read their local guides |
| AST search and outline | `ast_grep.rs`; `ast_grep/search.rs`, `ast_grep/outline.rs`, `ast_grep/embedded.rs` |
| Process execution | `bash.rs`, `process.rs` |
| Public research and page cache | `exa.rs`; URL open uses `url_fetch.rs` |
| Discovered skill references | `skill.rs` |
| Regression coverage | `tests/` and module-local tests |
## Local contracts
- `MVP_TOOL_CAPABILITIES` is the canonical built-in registry, not a directory inventory. Keep its order, aliases, typed arguments, dispatch, descriptions, and schemas aligned.
- Resolve paths with each tool's runtime absolute-path setting and filesystem policy; neither blanket root-only checks nor string-prefix checks replace these policies.
- Mutation locks use canonical paths, with lexical normalization for missing paths. Preserve final-symlink rejection, cross-process locks, and atomic writes. `fs.rs` rechecks parents after creation; this reduces races but is not a complete OS sandbox.
- Keep provider content separate from local `ToolResultDisplay` data. Preserve cancellation and output-limit reporting across bridges.
- `skill.rs` reads discovered skills and contained references, not arbitrary files.
- AST search, read-only rewrite previews, and outline are embedded: no external CLI, project configs, or custom extractors. Preserve bounded reads, bundled outline rules, and cooperative parsing deadlines.
## Web routing
- `exa.rs` selects Codex search from dispatch provider/model context and calls `providers/openai/codex/web_search.rs` under `src/`; other search uses Exa with environment-only `EXA_API_KEY`.
- Codex rejects domain/date filters, returns synthesis/citations without page-cache insertion, and never falls back to Exa on errors. Do not add MCP fallback.
- Direct URL open uses protected `url_fetch.rs` transport without credentials. Cached open is bounded, runtime-local, shared by runtime clones, and never refetches on a miss.