Research: Agent Loop, Tool Calling, and Large File Handling in Crush

[BlueHotDog]

Research: Agent Loop, Tool Calling, and Large File Handling in Crush

Date: 2025-10-03T07:19:56+0000
Researcher: Claude Code
Git Commit: 255aa3bcaaa79a270b48da607b2adab6a7e89bbd
Branch: main
Repository: crush

Research Question

How does this code deal with the need for an agent to read complex files, provide a deep dive analysis and research how the agent loop, tool calling and works in general and how it's coordinated for large
files?

Summary

The Crush codebase implements a goroutine-based agentic loop that coordinates iterative interactions between users, LLM providers, and tool execution.
The system handles complex file reading through the View tool with hard limits (250KB max file size, 2000 line default chunks) and manual pagination via offset/limit parameters. Tool calling follows a streaming event pattern where the LLM provider emits granular events (ToolUseStart, ToolUseDelta, ToolUseStop) that build tool calls incrementally, which are then executed sequentially with permission checks before results are appended to message history for the next iteration.

The architecture separates concerns across three main areas:

1. Agent Loop (agent.go:440-505) - Infinite loop handling message streaming and tool use continuation
2. Tool Calling (agent.go:585-702) - Sequential tool execution with cancellation and permission support
3. File Reading (view.go:252-301) - Two-pass line-based chunking with fixed limits

Detailed Findings

Agent Loop Architecture

Core Loop Location: /Users/danni/dev/crush/internal/llm/agent/agent.go:440-505

The agent implements an infinite for loop that continues until the LLM responds without tool calls. The execution flow:

1. Entry (agent.go:347-366): Run() creates a cancellable context, spawns a goroutine for async processing, and immediately returns an event channel
2. History Loading (agent.go:400-438): Loads existing messages from database, optionally truncates to summary, appends new user message
3. Iteration (agent.go:440-505):

• Calls streamAndHandleEvents() to stream LLM response
• If finish reason is FinishReasonToolUse, appends tool results to history and continues loop
• If finish reason is FinishReasonEndTurn with queued prompts, appends prompts and continues
• Otherwise completes and returns final event

Key Implementation Details:

• Goroutine spawned at line 366 allows async execution while returning event channel immediately
• Context cancellation checked at line 442 before each iteration
• Prompt queue system (lines 352-359) batches multiple user inputs without spawning new runs
• Session-based state management tracks active requests per session ID in activeRequests map (line 363)

Cancellation Pattern:

• Cancel function stored in activeRequests map (line 363)
• Context propagates through all goroutines
• Cancel() method (line 242) retrieves and invokes cancel function
• Tools check ctx.Done() during execution (lines 640-651)

Tool Calling Mechanism

Tool Interface: /Users/danni/dev/crush/internal/llm/tools/tools.go:69-73

type BaseTool interface {
    Info() ToolInfo          // Returns metadata with name, description, JSON schema
    Name() string            // Tool identifier
    Run(ctx, ToolCall) (ToolResponse, error)  // Executes tool
}

Registration Flow:

1. Base tools created lazily via baseToolsFn (lines 177-202): Bash, Edit, Grep, Glob, View, Write, etc.
2. MCP tools loaded from external servers via mcpToolsFn (lines 203-214)
3. getAllTools() aggregates and filters based on agentCfg.AllowedTools (lines 517-538)

Streaming Tool Calls from Provider (anthropic.go:339-484):

The Anthropic provider (and others) emit events as the LLM streams its response:

• EventToolUseStart (lines 374-383): When LLM begins a tool call, sends event with tool ID and name
• EventToolUseDelta (lines 402-413): Incrementally builds the JSON parameters string
• EventToolUseStop (lines 414-422): Marks tool call as complete
• EventComplete (lines 427-444): Sends full tool calls array with finish reason

Processing Events (agent.go:709-753):

Each event type updates the assistant message incrementally:

• EventToolUseStart → assistantMsg.AddToolCall() (line 729)
• EventToolUseDelta → assistantMsg.AppendToolCallInput() (line 734)
• EventToolUseStop → assistantMsg.FinishToolCall() (line 738)
• EventComplete → assistantMsg.SetToolCalls() and sets finish reason (line 746)

Execution Loop (agent.go:585-702):

After streaming completes, tools are executed sequentially (not concurrently):

1. Tool Lookup (lines 602-609): Finds tool by name from available tools
2. Goroutine Execution (lines 628-635): Runs tool.Run(ctx, toolCall) in goroutine to enable cancellation
3. Permission Check: Tools request permission via permissions.Request() before executing (e.g., bash.go:297-314)
4. Result Collection (lines 676-681): Creates ToolResult with response content and metadata
5. Message Creation (lines 688-699): Wraps all results as ContentPart slice in new message with role Tool

Key Patterns:

• Permission Gateway: Tools check permissions at execution time, requesting user approval via UI
• Context Propagation: Session ID and Message ID flow through context values (tools.SessionIDContextKey)
• Cancellation Safety: Each tool runs in goroutine with select on ctx.Done()
• Permission Denied Handling (lines 659-674): If any tool is denied permission, all remaining tools are cancelled

File Reading for Large/Complex Files

Primary Implementation: /Users/danni/dev/crush/internal/llm/tools/view.go

Hard Limits:
MaxReadSize = 250 * 1024 // 250KB maximum file size
DefaultReadLimit = 2000 // Default lines per read
MaxLineLength = 2000 // Maximum characters per line

Reading Strategy (view.go:252-301):

The readTextFile() function uses a two-pass approach:

Pass 1 - Skip to Offset (lines 262-276):

• Uses LineScanner (wrapper around bufio.Scanner)
• Scans through offset lines without storing them
• Seeks back to start if offset is 0 for efficiency

Pass 2 - Read Requested Lines (lines 278-289):

• Pre-allocates slice: make([]string, 0, limit)
• Scans up to limit lines, appending each to slice
• Truncates lines exceeding 2000 characters with "..." suffix

Pass 3 - Count Remaining (lines 291-294):

• Continues scanning to get total line count
• Enables pagination indicator in output

Size Enforcement (view.go:177-181):

• Checks fileInfo.Size() > MaxReadSize before reading
• Files > 250KB rejected with error message

No Automatic Chunking Decision: The system does NOT analyze files and automatically decide when to chunk. Instead:

• Fixed 250KB size limit enforced
• Default 2000-line reads
• User/AI controls pagination via offset and limit parameters
• Prompt guidance suggests: "Always read at least 2000 lines of code at a time to ensure you have enough context"

Special File Handling:

• Binary Detection: Checks file extension and null bytes in first 512 bytes (grep.go:417-456)
• Image Files: Detected by extension (.jpg, .png, etc.) but not displayed; returns error (lines 189-193)
• UTF-8 Validation: All content validated as UTF-8 before returning (lines 197-200)

Output Formatting:

• Line numbers added with 6-character padding (lines 227-250)
• Content wrapped in ... tags
• Truncation notification appended if more content exists (lines 211-214)

Integration Features:

• LSP Notification (line 205): Informs language servers of file access via notifyLSPs()
• Diagnostics (line 216): Appends compiler/linter errors via getDiagnostics()
• Access Tracking (line 217): Records file reads in thread-safe map via recordFileRead()
• Permission System (lines 115-138): Requests permission for files outside working directory

Coordination Between Systems

Message as State Container: The Message object (/Users/danni/dev/crush/internal/message/message.go) serves as the primary state container with Parts []ContentPart holding heterogeneous content:

• TextContent - Regular text response
• ReasoningContent - Thinking/reasoning text
• ToolCall - Tool invocation request
• ToolResult - Tool execution result
• Finish - Completion metadata with reason

Data Flow for File Reading in Agent Loop:

1. User Request: "Read the file main.go"
2. Agent Loop: User message appended to history (line 438)
3. LLM Streaming: Provider streams response with tool call events
4. Tool Call Built: Events incrementally build ToolCall{Name: "view", Input: "{"file_path":"main.go"}"}
5. Tool Execution: View tool's Run() called with parameters
6. File Reading:

• Checks size < 250KB (line 178)
• Reads first 2000 lines via readTextFile() (line 252)
• Adds line numbers and wraps in tags

7. Tool Result: Returns ToolResponse{Content: "...file content..."} (line 206)
8. Message History: Tool result appended as new message with role Tool (lines 692-697)
9. Next Iteration: Loop continues at line 477 with updated history containing file content
10. LLM Analysis: Provider receives history including file content, generates analysis

Handling Large Files:

If a file has 10,000 lines:

1. First iteration reads lines 0-2000
2. Tool result indicates "(File has more lines. Use 'offset' parameter to read beyond line 2000)"
3. LLM decides to read next chunk
4. Second iteration uses {"file_path": "main.go", "offset": 2000, "limit": 2000}
5. Tool reads lines 2000-4000
6. Process repeats until LLM has sufficient context or file is exhausted

File Size Rejection:

If file is 300KB:

1. View tool checks size at line 178
2. Returns error: "File is too large (307200 bytes). Maximum size is 256000 bytes"
3. Tool result contains error flag (line 56)
4. LLM receives error in next iteration
5. LLM may suggest using Grep to search specific sections or ask user to handle differently

Code References

Agent Loop

• internal/llm/agent/agent.go:347 - Run() entry point
• internal/llm/agent/agent.go:397 - processGeneration() main loop
• internal/llm/agent/agent.go:440 - Infinite for loop
• internal/llm/agent/agent.go:540 - streamAndHandleEvents() stream processor

Tool Calling

• internal/llm/tools/tools.go:69-73 - BaseTool interface
• internal/llm/agent/agent.go:517-538 - getAllTools() aggregation
• internal/llm/agent/agent.go:585-702 - Tool execution loop
• internal/llm/provider/anthropic.go:339-484 - Streaming tool call parser
• internal/llm/agent/agent.go:709-753 - Event processor

File Reading

• internal/llm/tools/view.go:88 - View tool Run() entry
• internal/llm/tools/view.go:252 - readTextFile() core implementation
• internal/llm/tools/view.go:46-51 - Hard limit constants
• internal/llm/tools/view.go:323-343 - LineScanner wrapper

Supporting Infrastructure

• internal/message/message.go - Message structure with Parts
• internal/message/content.go:116 - ContentPart types
• internal/permission/permission.go - Permission management
• internal/llm/agent/mcp-tools.go - MCP tool integration

Architecture Documentation

Agent Loop Design Principles

1. Goroutine-Based Async: Main processing in goroutine allows immediate return of event channel
2. Infinite Iteration: Loop continues until LLM decides to stop (no more tool calls)
3. Session-Based State: Each session tracked independently with own cancel context
4. Streaming Events: Provider returns channel of granular events for real-time UI updates
5. Message History: All interactions stored as message sequence in database
6. Prompt Queuing: Multiple user inputs batched without spawning new agent runs

Tool Calling Design Principles

1. Streaming Event Pattern: Tool calls built incrementally from LLM streaming events
2. Sequential Execution: Tools run one at a time (not parallel) to simplify error handling
3. Permission Gateway: Tools request approval before execution via UI dialogs
4. Context Cancellation: All tools support immediate cancellation via context
5. Lazy Loading: Tools initialized on-demand to optimize startup time
6. MCP Extensibility: External tools integrated via Model Context Protocol

File Reading Design Principles

1. Fixed Limits: Hard constraints (250KB, 2000 lines) prevent memory issues
2. Manual Pagination: User/AI controls chunking via offset/limit parameters
3. Line-Based Chunking: Uses bufio.Scanner for efficient line-by-line reading
4. No Auto-Chunking Logic: System doesn't analyze and decide; enforces fixed limits
5. Early Rejection: Size check before reading prevents wasted work
6. Metadata Integration: LSP notifications and diagnostics appended to file content

Coordination Patterns

1. Message Parts as Protocol: Heterogeneous content types (text, tool calls, tool results) in single message structure
2. Finish Reason Routing: Agent loop routes based on finish reason (tool use → continue, end turn → complete)
3. Tool Result Continuation: Tool results appended to history trigger next LLM iteration
4. Session Context Flow: Session ID and Message ID propagate through context for permission requests

Related Research

No existing research documents found in thoughts/ directory.

Open Questions

1. Parallel Tool Execution: Could tools be executed in parallel for performance? Current sequential execution seems intentional for simpler error handling and permission flow.
2. Dynamic File Reading: Would adaptive chunking based on file characteristics (syntax complexity, token density) improve efficiency over fixed 2000-line chunks?
3. Streaming File Content: Could large files be streamed token-by-token to LLM rather than batch-loading chunks?
4. Tool Call Batching: Could multiple independent tool calls be executed concurrently when they don't depend on each other?
5. File Size Limit Rationale: Is 250KB limit based on token limits, memory constraints, or UX considerations?