# src/tools KNOWLEDGE BASE
## OVERVIEW
Built-in provider tool runtime: dispatch, JSON args, cwd/root containment, mutation locks, bounded shell/search/browser/subagents, dynamic MCP tool definitions, provider-safe results, and local display metadata.
## STRUCTURE
```text
src/tools/
├── mod.rs # facade exports, module boundary, test-only schema helpers
├── capability.rs # canonical tool enum, provider schemas, ordering
├── contract.rs # shared arg names and provider contract constants
├── dispatch.rs # tool name -> typed args -> implementation -> ToolResult
├── args.rs # serde(deny_unknown_fields) DTOs and validation helpers
├── runtime.rs # ToolRuntime, cwd/root/settings/shared state
├── fs.rs # read/write/list/find/repo-map path resolution and mutation locks
├── grep/ # grep engine, matcher, reader
├── hash_edit/ # hashline edit parser/apply/recovery/snapshots
├── bash.rs process.rs # shell execution, bounded process pipes, timeout/cancel cleanup
├── exa.rs url_fetch.rs browser.rs view_image.rs # external URL/web/browser/image bridges
├── skill.rs # discovered skill/reference reads only
└── workspace.rs # workspace/root helper contracts
```
## WHERE TO LOOK
| Module boundary | `mod.rs` | Facade exports, test-only aliases, schema exposure. |
| Runtime state | `runtime.rs` | `ToolRuntime`, cwd canonicalization, settings, shared locks, skill/subagent/browser handles. |
| Dispatch path | `dispatch.rs` | Tool name -> validated args -> implementation -> `ToolResult`. |
| Schemas/names | `capability.rs`, `contract.rs`, `descriptions.rs` | Canonical names, aliases, provider JSON schemas, prompt descriptions, metadata keys. |
| Args/limits | `args.rs` | `serde(deny_unknown_fields)`, hard caps, validation helpers. |
| Filesystem | `fs.rs` | Path resolution, containment, symlink rejection, read/write behavior, repo map. |
| Hash edit | `hash_edit/` | Hashline edit tokenization, parser, apply/recovery, snapshots. |
| Search | `grep/`, `find.rs`, `ast_grep.rs` | Literal regex search, path search, structural AST search. |
| Shell | `bash.rs`, `process.rs` | cwd preflight, bounded pipes, timeout/cancel cleanup. |
| Browser/image/web | `browser.rs`, `view_image.rs`, `exa.rs`, `url_fetch.rs` | External tool bridges and URL-read bridge with bounded stdout/content. |
| Skills | `skill.rs` | Discovered skill/reference reads only; no arbitrary path mode. |
| Tests | `tests/`, inline `#[cfg(test)]` | Safety contracts, schemas, aliases, limits. |
## CONVENTIONS
- Filesystem tools resolve through `ToolRuntime.cwd_root` helpers before disk access; setting-gated absolute paths must name the setting in errors.
- Reject symlink targets for writes; re-check parent containment before atomic write.
- `hash_edit` is hashline patch flow. Missing/ambiguous/overlap failures must be explicit.
- Serialize write/hash_edit mutations per canonical or lexical-normalized path.
- Keep `ToolCapability::MVP_TOOL_CAPABILITIES` order stable; providers see this order.
- Keep canonical tool names, aliases, schemas, metadata keys stable unless compatibility tests change.
- Keep loose JSON only at tool protocol edge; deserialize to typed args immediately.
- Cap each tool result at implementation boundary: file reads, process pipes, grep hits, Exa/code content, browser snapshots, image inspection, and child-agent summaries.
- On timeout/cancel/truncation, kill shell process tree and report cleanup warnings.
- Child-agent tool exposure is depth-gated by runtime state; nested runs must keep configured count/output limits.
- Provider-visible `content` stays bounded/sanitized; local display data carries diffs/previews.
## ANTI-PATTERNS
- Do not bypass `resolve_existing_path`, `resolve_for_write`, or `ensure_inside_with_setting`.
- Do not canonicalize after write only; containment must happen before disk mutation too.
- Do not follow final symlink targets for write or permit parent symlink escape races unchecked.
- Do not add tool outputs without explicit caps in that implementation and schema-facing tests for truncation/summary behavior.
- Do not ignore `AgentCancellation` in long-running tool paths.
- Do not add new dispatch names, aliases, schema fields, metadata keys, or ordering casually.
- Do not route skills/references into arbitrary filesystem reads.
- Do not bypass dynamic MCP tool definition filtering/disabled-tool filtering.