Claude Code Series · Part 5/6 15 min read

40+ Tools & the Tri-State Permission Engine

The complete tool catalog organized in 6 access control sets, cascading evaluation from 4 sources, and the yolo classifier — literally an AI judging whether another AI's action is safe.

Would you let an AI decide if another AI can delete your code? Claude Code has a mode called "yolo" where exactly that happens. But it also has the most granular permission system of any coding tool. Autonomy vs. security tension, resolved with engineering.

🔧

Every Tool's Interface

Anatomy of a tool

Every tool in Claude Code implements an interface that declares not just what it does, but how dangerous it is. Four safety properties determine how the permission system treats it:

Property	Purpose	Impact
`isReadOnly()`	Does it modify state?	Affects permission evaluation
`isDestructive()`	Can it cause irreversible harm?	Triggers explicit confirmation
`isConcurrencySafe()`	Can it run in parallel?	Enables parallel tool calls
`interruptBehavior()`	What happens on user interrupt?	`allow` = stop · `block` = must complete

interface Tool {
  name: string
  call(input): Promise<ToolResult>
  
  // Safety properties
  isReadOnly(): boolean       // no side effects
  isDestructive(): boolean    // explicit confirmation required
  isConcurrencySafe(): boolean // can run in parallel
  
  // Deferred loading
  shouldDefer: boolean        // load on demand via ToolSearch
  searchHint: string          // keywords for matching
  
  // Output control
  maxResultSizeChars: number  // default: 50,000 chars
}

📦

40+ Tool Catalog

The complete registry by category

Core Tools (Always Available)

Tool	Description	ReadOnly	Concurrent
`BashTool`	Shell command execution	❌	❌
`FileReadTool`	Read file contents	✅	✅
`FileEditTool`	Edit existing files	❌	❌
`FileWriteTool`	Create/overwrite files	❌	❌
`GlobTool`	File pattern search	✅	✅
`GrepTool`	Text search in files	✅	✅
`WebFetchTool`	HTTP fetch	✅	✅
`WebSearchTool`	Web search	✅	✅
`NotebookEditTool`	Jupyter notebook editing	❌	❌
`PowerShellTool`	Windows PowerShell	❌	❌

Agent & Task Tools

Tool	Description	Gate
`AgentTool`	Spawn sub-agents	Always
`TaskOutputTool`	Return results to parent	Always
`AskUserQuestionTool`	Ask user for input	Always
`SkillTool`	Execute bundled/custom skills	Always
`ToolSearchTool`	Search for deferred tools	Always
`EnterPlanModeTool`	Enter plan mode	Always

Gated Tools (Feature Flags)

Tool	Gate	Description
`WebBrowserTool`	WEB_BROWSER	Full web browser
`LSPTool`	LSP_TOOL	Language Server Protocol
`WorktreeCreateTool`	Worktrees	Create git worktree
`SendMessageTool`	UDS_INBOX	Send message to peer agent
`TeamCreateTool`	Swarms	Create agent team
`SleepTool`	KAIROS	Put agent to sleep
`CronCreateTool`	AGENT_TRIGGERS	Schedule cron job
`PushNotificationTool`	KAIROS	Push notification to user
`SubscribePRTool`	KAIROS_GITHUB	Subscribe to PR webhooks

Deferred Tool Loading

Tools with shouldDefer = true are NOT sent to the API on every request. When the model needs one, it calls ToolSearchTool, which does keyword matching and loads it on demand. This reduces the initial payload — fewer tool definitions = fewer tokens.

🛡️

6 Access Control Sets

Who can use what

Agent-Disallowed

What sub-agents CANNOT do: TaskOutput, PlanMode, AskUser, TaskStop

Async Agent

Tools for background agents: FileRead, Bash, Grep, Edit + Worktrees if enabled

Coordinator-Only

Only 4 tools: Agent, TaskStop, SendMessage, SyntheticOutput

In-Process Teammate

Management only: TaskCreate/Get/Update/List, SendMessage, Cron

Simple Mode

Minimum viable: Bash + FileRead + FileEdit. Nothing else.

REPL Mode (Ant-Only)

Everything inside a REPL VM. Hides all primitive tools.

The Design Principle

Each agent type receives exactly the tools it needs and nothing more. The coordinator can't execute code directly — only delegate. Sub-agents can't talk to the user — only report to the parent. Least privilege applied to AI agents.

⚖️

Permission Engine

Cascading evaluation from 4 sources

Every tool request goes through an evaluation pipeline: deny first, then allow, then mode-based default. Rules come from 4 cascading sources — each can override the previous one.

Evaluation Flow

Tool request arrives
    │
    ├── Check DENY rules first (cascading sources)
    │   └── Match → REJECT immediately
    │
    ├── Check ALLOW rules (with glob/path matching)
    │   └── Match → APPROVE
    │
    ├── Fall back to mode-based default
    │   ├── bypassPermissions → APPROVE
    │   ├── plan → PROPOSE (show plan, ask approval)
    │   ├── auto → yoloClassifier (AI decides if safe)
    │   └── default → check risk level
    │       ├── LOW    → APPROVE
    │       ├── MEDIUM → APPROVE (within project scope)
    │       └── HIGH   → ASK user
    │
    └── If ASK → User confirmation prompt

4 Rule Sources (Cascading)

Platform

Anthropic defaults — the base layer

Organization

Enterprise/team policies — fetched from API

Project

.claude/settings.json in project root

User

~/.claude/settings.json in user home

🤖

The Yolo Classifier

AI judging whether another AI's action is safe

When permission mode is auto, Claude Code makes an LLM call to classify whether the operation is safe:

• bashClassifier.ts — for shell commands
• yoloClassifier.ts — for general operations

It's literally an AI judging whether another AI is safe — recursive AI safety.

Denial Tracking — Circuit Breaker

Circuit breaker pattern: after N consecutive permission denials, the system changes its approach — stops attempting similar operations. Prevents infinite loops of "attempt → deny → attempt → deny."

⚠️

Risk Taxonomy

LOW · MEDIUM · HIGH

LOW — Auto-approved

read, search, format, git status, glob, grep

No side effects, no risk. Always approved.

MEDIUM — Contextually approved

write, create branch, build, install dependencies

Side effects contained within the project. Approved if within scope.

HIGH — Explicit confirmation

rm -rf, DROP TABLE, git push --force, publish packages

Potentially irreversible. Always requires user confirmation.

📋

Plan Mode

Propose before executing

EnterPlanModeTool / ExitPlanModeV2Tool — the model proposes operations instead of executing them. The user reviews the plan and approves or rejects.

Ideal for: large changes, teams with review processes, security audits, or when you simply want to understand what it will do before it does it.

📏

Limits & Truncation

The numeric guardrails

Limit	Value	Context
`MAX_RESULT_SIZE_CHARS`	50,000	Per tool result
`MAX_TOOL_RESULT_TOKENS`	100,000	Per result (tokens)
`MAX_TOOL_RESULT_BYTES`	400,000	Per result (bytes)
`MAX_RESULTS_PER_MESSAGE`	200,000	Total per turn (chars)
`IMAGE_MAX_SIZE`	5 MB	Per image (base64)
`PDF_MAX_SIZE`	20 MB	Max per PDF
`PDF_MAX_PAGES`	100	Max pages per PDF
`MAX_MEDIA_PER_REQUEST`	100	Images/PDFs per request

💡

Reusable Patterns

What you can copy for your own AI agents

Permission cascading (platform → org → project → user) — 4 levels of rules where each can override the previous. More flexible than a single-level binary allow/deny system.

Tri-state (allow/deny/ask) instead of binary — the third "ask" state enables contextual decisions without blocking the entire workflow.

AI-as-judge for auto-approval — risky but effective. The yolo classifier is a pragmatism that acknowledges enumerating all possible rules is impossible; a generalist AI can cover edge cases.

Risk taxonomy with 3 clear categories — LOW/MEDIUM/HIGH with different behaviors per level. Simple, understandable, extensible.