cc-tools crate. It defines the Tool trait, a registry of 33 built-in tools, and the ToolContext struct that carries runtime state into every tool call.
The Tool trait
Every tool is a zero-sized struct that implements theTool trait, defined in crates/tools/src/lib.rs:
PermissionLevel
Each tool declares aPermissionLevel that controls which permission modes will allow it to run automatically:
| Level | Meaning |
|---|---|
None | No permission check required (metadata tools, signalling tools) |
ReadOnly | Safe to run automatically in Default and AcceptEdits modes |
Write | Requires user approval in Default mode; automatic in AcceptEdits |
Execute | Runs shell commands; requires explicit approval or BypassPermissions |
Dangerous | Highest risk; denied in Plan mode |
ToolResult
ToolContext
ToolContext is passed to every execute() call and carries all runtime state a tool needs:
ctx.resolve_path(path) resolves relative paths against working_dir. ctx.check_permission(tool_name, description, is_read_only) runs the permission check and returns Err(ClaudeError::PermissionDenied(...)) if access is denied.
Input schema validation
Tool input schemas are generated using schemars (derive-based) and serialized toserde_json::Value. The schemas follow JSON Schema draft-07. The query loop validates tool inputs against these schemas before calling execute().
The tool schema cache: ToolDefinition structs produced by to_definition() are collected once at startup into a Vec<ApiToolDefinition> and reused across turns. The last tool in the list automatically receives a CacheControl::ephemeral() annotation from cc-api, enabling prompt caching on the tools block.
Registry functions
Tool categories and names
File tools
File tools
| Tool name | Permission | Description |
|---|---|---|
Read | ReadOnly | Read file contents with optional line offset and limit |
Write | Write | Create or overwrite a file; creates parent directories automatically |
Edit | Write | Replace exact string in a file; replace_all flag for bulk replacement |
NotebookEdit | Write | Edit Jupyter .ipynb cells: replace, insert, or delete |
Shell tools
Shell tools
| Tool name | Permission | Description |
|---|---|---|
Bash | Execute | Run a shell command via bash -c (or cmd /C on Windows); default timeout 120s, max 600s |
PowerShell | Execute | Run a PowerShell command; uses pwsh on non-Windows |
Search tools
Search tools
| Tool name | Permission | Description |
|---|---|---|
Glob | ReadOnly | Find files by glob pattern, sorted by modification time; max 250 results |
Grep | ReadOnly | Search file contents with a regex; three output modes: files_with_matches, content, count |
Agent tools
Agent tools
| Tool name | Permission | Description |
|---|---|---|
Task | Execute | Spawn a sub-agent that runs its own run_query_loop(); returns the final assistant message |
Web tools
Web tools
| Tool name | Permission | Description |
|---|---|---|
WebFetch | ReadOnly | HTTP GET with HTML stripping; 30s timeout; 100K character limit |
WebSearch | ReadOnly | Search via Brave Search API (with BRAVE_SEARCH_API_KEY) or DuckDuckGo fallback |
MCP tools
MCP tools
| Tool name | Permission | Description |
|---|---|---|
ListMcpResources | ReadOnly | List all resources from connected MCP servers |
ReadMcpResource | ReadOnly | Read a resource by URI from a connected MCP server |
Task management tools
Task management tools
| Tool name | Permission | Description |
|---|---|---|
TaskCreate | None | Create a task in the global TASK_STORE with a UUID |
TaskGet | None | Retrieve a task by ID |
TaskUpdate | None | Update task fields; status=deleted removes from store |
TaskList | None | List all non-deleted tasks, with optional status filter |
TaskStop | None | Set a task’s status to Failed |
TaskOutput | None | Append text to a task’s output vector |
TodoWrite | None | Replace the entire todo list atomically |
Scheduling tools
Scheduling tools
| Tool name | Permission | Description |
|---|---|---|
CronCreate | None | Create a scheduled task with a 5-field cron expression; max 50 jobs |
CronDelete | None | Delete a scheduled task by ID |
CronList | None | List all scheduled tasks with human-readable schedules |
Plan mode tools
Plan mode tools
| Tool name | Permission | Description |
|---|---|---|
EnterPlanMode | None | Switch the session to Plan (read-only) permission mode |
ExitPlanMode | None | Return from plan mode; accepts an optional summary |
Worktree tools
Worktree tools
| Tool name | Permission | Description |
|---|---|---|
EnterWorktree | None | Create a git worktree on a new branch and switch the session to it |
ExitWorktree | None | Return from a worktree session; keep or remove the worktree |
Meta / utility tools
Meta / utility tools
| Tool name | Permission | Description |
|---|---|---|
ToolSearch | None | Find tools by keyword with a scoring algorithm; select:Name for exact lookup |
AskUserQuestion | None | Surface a question to the user in the TUI; returns error in non-interactive mode |
SendMessage | None | Deliver a message to a named recipient in the shared INBOX map |
Brief | None | Attach files and a status message for TUI rendering |
Sleep | None | Async delay up to 300 seconds |
Config | None | Read or write fields in ~/.claude/settings.json |
Skill | None | Load and execute a skill from .claude/commands/ or ~/.claude/commands/ |
Simplified tool implementation example
The following example is representative of how a read-only tool is structured, based on the pattern used throughoutcc-tools:
Tool names in
cc-tools match the TypeScript constants exactly (e.g. "Bash", "Read", "Edit", "Task"). This ensures full compatibility with any system that references tools by name.