claw-code/rust/crates/tools/AGENTS.md

AGENTS.md — rust/crates/tools

OVERVIEW

Single-crate tool surface: registry, 55 tool specs, permission-gated dispatch, all implementations. One flat src/lib.rs (10,892 lines, ~37% tests).

lib.rs MAP

Lines	Landmark
1–74	Imports + six global_*_registry() OnceLock singletons (Lsp, McpTool, Team, Cron, Task, Worker)
75–483	Registry API: ToolManifestEntry, ToolSource, ToolRegistry, ToolSpec, GlobalToolRegistry, RuntimeToolDefinition, canonical_allowed_tool_name
484–1348	mvp_tool_specs() static table of 55 tools with inline JSON schemas
1349–1524	enforce_permission_check + execute_tool() string-match dispatch, permission classification helpers
1525–2735	run_* wrappers: deserialize input, call into execute_* or runtime fns
2736–2763	workspace_traversal_guard_tests mod
2764–3354	~45 private serde IO structs
3355–6824	Real implementations: web fetch/search, todo store, skill resolution, agent/subagent spawning (ProviderRuntimeClient L5182, SubagentToolExecutor L5361), notebook edit, sleep, config, plan-mode, structured output, REPL, PowerShell
6825–6826	pub mod lane_completion; pub mod pdf_extract;
6829–10892	mod tests (~4000 lines)

ADDING A TOOL

1. Add a ToolSpec entry in mvp_tool_specs(). Include name, description, input_schema (inline JSON), and required_permission: PermissionMode.
2. Add a dispatch arm in execute_tool() matching the tool name string.
3. Write a run_<tool>() wrapper. Deserialize input from a dedicated serde struct.
4. Implement the actual logic below L3355 (or call into another crate).
5. Add inline tests in mod tests. Follow BDD naming: given_x_when_y_then_z.
6. Permission gating is automatic: GlobalToolRegistry / SubagentToolExecutor hold an optional PermissionEnforcer checked pre-dispatch.

CONVENTIONS

• Tool boundary signature: Result<String, String>. Always.
• Tool naming: snake_case for file/shell tools, PascalCase otherwise. canonical_allowed_tool_name normalizes aliases.
• State: OnceLock registries for global singletons. JSON state files under config dirs for persistence.
• Input validation: reject empty strings for todos, descriptions, prompts, messages, code. ~12 validation sites between L3806–6167. Keep that contract.
• Test naming: BDD style (given_x_when_y_then_z).
• Env-mutating tests: acquire env_lock() mutex first.
• Dependencies: runtime, api, plugins, commands, reqwest(blocking), aspect-*, tokio.

ANTI-PATTERNS

• Don't add more #[allow(clippy::...)] suppressions. ~50 needless_pass_by_value and several too_many_lines allows exist as legacy debt. Don't extend.
• Don't skip input validation. Empty-string rejection is a contract across all user-facing text fields.
• Don't scatter implementation across new submodules. The crate is intentionally flat (one lib.rs + two leaf mods). Only lane_completion and pdf_extract break out.
• Don't duplicate tool names. The canonical name mapping already handles aliases.
• Don't bypass enforce_permission_check. Every tool dispatch goes through permission gating. No exceptions.