InkdownInkdown
Start writing

Claude-Code

62 files·4 subfolders

Shared Workspace

Claude-Code
codex

03-tools-and-tasks

Shared from "Claude-Code" on Inkdown

Tools & Tasks

How Claude Code interacts with the world — executing commands, editing files, spawning agents, and managing work.

Tool System Overview

Tools are the AI's hands. Each tool provides a specific capability:

Plain text
Tool = {
  name: string              // Unique identifier
  description: string       // Shown to the model in the system prompt
  parameters: JSONSchema    // Input schema for the model
  execute(input, context)   // Execution function
  isEnabled()               // Runtime availability check
  isAutoApproved(context)   // Permission check
}
Tool Assembly (tools.ts)
0000_start_here_index_and_recommended_reading_order.md
0100_project_overview_tech_stack_runtime_modes_and_folder_map.md
0200_startup_flow_entry_points_and_cold_start_sequence.md
0300_codebase_modules_layers_state_models_and_schemas.md
0400_system_architecture_and_design_rationale.md
0500_interactive_repl_request_flow_end_to_end.md
0600_headless_sdk_and_print_mode_request_flow_end_to_end.md
0700_mcp_integration_connection_and_tool_call_flow.md
0800_external_services_sdks_storage_and_local_dependencies.md
0900_environment_variables_settings_feature_flags_and_failure_modes.md
1000_non_obvious_patterns_gotchas_and_debugging_traps.md
1100_full_codebase_file_inventory_grouped_by_directory.md
kimi
00-overview.md
01-entrypoints.md
02-state-management.md
03-query-system.md
04-tools-system.md
05-tasks-system.md
06-ui-components.md
07-bridge-remote.md
08-services.md
09-skills-plugins.md
10-commands.md
11-testing-architecture.md
12-permission-system.md
13-build-system.md
14-ink-internals.md
15-git-internals.md
16-context-compaction.md
17-vim-mode.md
18-mailbox-notifications.md
19-session-persistence.md
20-hooks-system.md
21-error-recovery.md
README.md
qwen
00-overview.md
01-entry-points.md
02-query-engine.md
03-tools-and-tasks.md
04-commands-and-skills.md
05-state-management.md
06-ink-rendering.md
07-bridge-remote.md
08-mcp-services.md
09-services-overview.md
10-multi-agent.md
11-system-prompt-constants.md
12-tool-interface.md
13-memory-system.md
14-buddy-companion.md
15-keybindings.md
16-stop-hooks.md
17-vim-mode.md
18-upstreamproxy.md
19-cost-tracking-history.md
20-contexts-styles-onboarding.md
21-hooks.md
22-screens.md
tweets-explain
claude-code-memory-analysis.md
compact
memory-system
agentic-architecture

The getTools(permissionContext) function assembles the active tool list:

  1. Start with all base tools (~40 tools)
  2. Filter by deny rules (settings-based blanket denials)
  3. Hide REPL-only tools when REPL mode is active
  4. Filter by isEnabled() checks (runtime feature gates)
  5. Merge with MCP tools (from connected MCP servers)
  6. Sort by name (for prompt cache stability)
  7. Deduplicate (built-in tools take precedence over MCP tools)
Tool Categories
CategoryTools
File OperationsFileRead, FileEdit, FileWrite, NotebookEdit, Glob, Grep
ShellBash, PowerShell
WebWebFetch, WebSearch, WebBrowser
Task ManagementTaskCreate, TaskGet, TaskUpdate, TaskList, TaskStop, TaskOutput
Agent/SwarmAgent, TeamCreate, TeamDelete, SendMessage
PlanningEnterPlanMode, ExitPlanMode
User InteractionAskUserQuestion
OrganizationTodoWrite
Skills/CommandsSkillTool, ToolSearchTool
WorktreesEnterWorktree, ExitWorktree
MCPListMcpResources, ReadMcpResource
SpecialConfigTool, TungstenTool, REPLTool, BriefTool, SleepTool
CronCronCreate, CronDelete, CronList
TestingTestingPermissionTool (test-only)

Core Tools

BashTool

The most powerful and most dangerous tool. Executes shell commands.

Features:

  • Sandboxed execution (on supported platforms)
  • Timeout management
  • Output truncation for large outputs
  • Permission checks per-command
  • Background execution with &
  • Interactive process management

Permission modes:

  • default — asks for each command
  • yolo — auto-approves safe commands, asks for dangerous ones
  • plan — read-only mode (no writes, no destructive commands)
FileEditTool

Edits files with surgical precision using SEARCH/REPLACE blocks.

Features:

  • Multiple edits in a single call
  • Validation that search text exists and is unique
  • Line number tracking for accurate edits
  • Git integration for diff tracking
  • Auto-formatting after edits
FileReadTool

Reads file contents with optional line ranges.

Features:

  • Line range selection (start_line, end_line)
  • Output truncation for large files
  • Image file support
  • Binary file detection
FileWriteTool

Writes complete file contents.

Features:

  • Overwrites existing files
  • Creates parent directories if needed
  • Permission check for existing files
GrepTool & GlobTool

Fast file search using ripgrep and find/bfs.

Features:

  • Regex search (GrepTool)
  • Pattern matching (GlobTool)
  • Ant-native: uses embedded bfs/ugrep for speed
  • Respects .gitignore
WebSearchTool

Searches the web via Anthropic's web search API.

WebFetchTool

Fetches content from a URL.

Features:

  • HTML-to-markdown conversion
  • Timeout management
  • Size limits
AskUserQuestionTool

Asks the user a clarifying question.

Features:

  • Multiple choice or free text
  • Blocks the tool loop until user responds
  • Used when the AI needs clarification
TodoWriteTool

Manages a todo list visible in the UI.

Features:

  • Create, update, complete todos
  • Nested todos
  • Displayed in the expanded view
SkillTool

Invokes skills (prompt-based capabilities from /skills/ directories).

Features:

  • Discovers available skills
  • Executes skill prompts
  • Skills can add their own sub-commands

AgentTool — Sub-Agent Spawning

The AgentTool lets the AI spawn a sub-agent to work on a task independently.

How It Works
Plain text
User: "Refactor the auth module"
    │
    ▼
AI: calls AgentTool with task description
    │
    ▼
AgentTool:
  1. Creates a new subprocess (or in-process agent)
  2. Sets up a fresh query context
  3. Passes the task description as the initial prompt
  4. Returns immediately with a task ID
    │
    ▼
AI: continues with other work
    │
    ▼
Sub-agent: works on the task independently
    │
    ▼
Sub-agent: completes → result delivered as <task-notification>
    │
    ▼
AI: sees the result and incorporates it
Agent Types
TypeDescription
LocalShellRuns in a subprocess with shell access
LocalAgentRuns in-process (lighter weight)
RemoteAgentRuns on a remote machine
DreamBackground processing (auto-dream feature)
LocalWorkflowWorkflow script execution (feature-gated)
MonitorMcpMCP monitoring task (feature-gated)
Tool Availability for Agents

Sub-agents get a restricted tool set:

  • No TeamCreate/TeamDelete (can't spawn more agents)
  • No SendMessage (can't message other agents)
  • No SyntheticOutputTool (internal tool)
  • Gets: Bash, Read, Edit, Write, Grep, Glob, etc.

Task System (tasks/)

Tasks are the execution contexts for work. Each task type implements the Task interface:

TypeScript
interface Task {
  type: TaskType
  name: string
  description: string
  spawn(params): TaskHandle
}
Task Lifecycle
Plain text
spawn({ taskDescription, tools, context })
    │
    ▼
TaskHandle:
  ├─ id: string              // Unique task ID
  ├─ status: 'running' | 'completed' | 'failed' | 'stopped'
  ├─ result: string | null   // Task output
  ├─ kill()                  // Stop the task
  └─ onStatusChange(callback)
Task Management Tools
ToolPurpose
TaskCreateCreate a new task
TaskGetGet task details/result
TaskUpdateUpdate task status/description
TaskListList all tasks
TaskStopStop a running task
TaskOutputGet streaming output from a task

Tool Permission System

Permission Modes
ModeBehavior
defaultAsk for each tool use
yoloAuto-approve safe tools, ask for dangerous ones
planRead-only (no writes, no destructive commands)
bypassPermissionsAuto-approve everything (sandbox only)
Permission Context
TypeScript
ToolPermissionContext = {
  mode: PermissionMode
  deniedTools: Set<string>        // Explicitly denied tools
  autoApprovedTools: Set<string>  // Auto-approved tools
  deniedRules: DenyRule[]         // Pattern-based denials
  autoApprovedRules: AutoRule[]   // Pattern-based approvals
}
Permission Setup (utils/permissions/permissionSetup.ts)
  1. Parse CLI flags (--tools, --dangerously-skip-permissions)
  2. Load settings-based permissions
  3. Apply policy limits (enterprise restrictions)
  4. Initialize the permission context
  5. Strip dangerous permissions for auto-mode

Tool Definition Base (Tool.ts)

All tools extend/implement the Tool interface:

TypeScript
interface Tool {
  // Identity
  name: string
  description: string

  // Schema
  parameters: JSONSchema7
  input_schema: ToolInputJSONSchema

  // Runtime
  isEnabled(): boolean
  isAutoApproved(context): boolean

  // Execution
  execute(input, context): AsyncIterable<ToolResult>

  // Optional
  backfillObservableInput?(input): void
  maxResultSizeChars?: number
}

Special Tools

REPLTool

Ant-only tool that wraps the entire REPL inside a tool. Used for internal testing and debugging.

ConfigTool

Ant-only tool for modifying settings programmatically.

TungstenTool

Ant-only tool for internal debugging/diagnostics.

BriefTool

Generates a brief summary of the conversation (KAIROS feature).

SleepTool

Tells the AI to "sleep" until a condition is met (PROACTIVE/KAIROS feature).

Cron Tools

Schedule recurring tasks (AGENT_TRIGGERS feature).

Key Files Reference

FilePurpose
src/tools.tsTool assembly, presets, merging
src/Tool.tsTool base interface
src/tasks.tsTask type registry
src/Task.tsTask base interface
src/tools/BashTool/Shell execution
src/tools/FileEditTool/File editing (SEARCH/REPLACE)
src/tools/FileReadTool/File reading
src/tools/FileWriteTool/File writing
src/tools/GrepTool/Regex search
src/tools/GlobTool/Pattern matching
src/tools/WebSearchTool/Web search
src/tools/WebFetchTool/URL fetching
src/tools/AskUserQuestionTool/User interaction
src/tools/TodoWriteTool/Todo management
src/tools/AgentTool/Sub-agent spawning
src/tools/SkillTool/Skill invocation
src/tools/TaskCreateTool/Task creation
src/tools/TaskStopTool/Task termination
src/tools/TaskOutputTool/Task output streaming
src/tools/TeamCreateTool/Swarm team creation
src/tools/TeamDeleteTool/Swarm team deletion
src/tools/SendMessageTool/Inter-agent messaging
src/tools/REPLTool/REPL wrapper (ant-only)
src/tools/WorkflowTool/Workflow execution
src/tools/LSPTool/Language Server Protocol
src/tools/WebBrowserTool/Headless browser
src/tools/ComputerUseTool/Screen capture & control