Research: Tool Dispatcher Complexity (#358)

Research – Tool Dispatcher Complexity (#358)

Date: 2026-02-05 Owner: Claude Code Phase: Completed (see PR #366) Git Commit: 9ed9739dda91c3f4f463c4c8f58687f75879afc7 Completed: 2026-02-05 via PR #366

Note: This research was completed in PR #366. The tool_dispatcher was decomposed into 6 focused submodules. See the plan document and PR for implementation details.

Goal

Map the current complexity issues in tool_dispatcher.py and identify refactoring patterns in the codebase for reducing complexity while maintaining behavior.

Findings

Current File Metrics

Complexity Hotspots

dispatch_tools function (lines 413-464)

• Lines: 52 total; 30 excluding docstring
• Branches / decision points: 4 if statements; ~7 decision points if counting and/boolean ops
• Nesting levels: 2 maximum (file max is 3 in _collect_structured_tool_calls)
• Phases: 4 sequential phases (collect structured → fallback → execute → log summary) + optional state-transition hook

_collect_structured_tool_calls (lines 220-267)

• Complexity: ~8 (loop + 4 conditionals + 2 debug branches)
• Dead parameters: tool_callback (line 224), node (line 222) - passed but never used

_collect_fallback_tool_calls (lines 275-341)

• Complexity: ~10 (loop + 5 conditionals + debug branch + assertions)
• Contains assertions: assert isinstance(result, tuple) and assert isinstance(result, list)

Dead Code Identified

Magic Numbers

Deferred Imports (5 total)

Seven Responsibilities Mapped

Additional responsibilities:

• Debug logging/diagnostics - Scattered throughout (lines 246-265, 288, 300-327)
• Tool name validation - Lines 51-57, 60-65
• Dispatch summary logging - Lines 388-405
• Tool call args retrieval - Lines 158-166

Related Files

Files using tool_dispatcher.py:

• /home/tuna/tunacode/src/tunacode/core/agents/agent_components/orchestrator/orchestrator.py - Imports dispatch_tools, has_tool_calls
• /home/tuna/tunacode/src/tunacode/core/agents/agent_components/orchestrator/tool_returns.py - Imports consume_tool_call_args

Test files:

• /home/tuna/tunacode/tests/integration/tools/test_tool_dispatcher_coverage.py - 10 test functions
• /home/tuna/tunacode/tests/integration/core/test_tool_call_lifecycle.py - 26 test functions
• Total: 36 test functions across both files

Sibling orchestrator modules:

• orchestrator.py - Main orchestrator
• tool_returns.py - Tool return processing
• message_recorder.py - Message recording
• usage_tracker.py - Token usage tracking
• debug_format.py - Debug formatting

Key Patterns / Solutions Found

1. Node Orchestrator Pattern (orchestrator.py)

The main orchestrator delegates each step to focused modules:

1. Transition to ASSISTANT state
2. Process inbound tool returns (emit_tool_returns)
3. Record agent thought (record_thought)
4. Track token usage (update_usage)
5. Extract text content
6. Dispatch outbound tool calls (dispatch_tools)
7. Check for node result
8. Transition to RESPONSE state

This is the pattern tool_dispatcher.py should follow - further decomposition into focused modules.

2. 4-Phase Dispatch Architecture

# Phase 1: Collect structured tool calls
# Phase 2: Fallback to text parsing if no structured calls
# Phase 3: Execute if we have a callback
# Phase 4: Log summary

These phases could be extracted into separate modules or classes.

3. Registry Pattern (tool_registry.py)

The ToolCallRegistry class at /home/tuna/tunacode/src/tunacode/core/types/tool_registry.py demonstrates:

• Immutable updates via dataclasses.replace()
• Order preservation for listing
• Lifecycle tracking: PENDING → RUNNING → COMPLETED/FAILED/CANCELLED

4. Tool Executor Pattern (tool_executor.py)

• Batched parallel execution respecting TUNACODE_MAX_PARALLEL
• Exponential backoff with jitter for retries
• Non-retryable error whitelist
• Failure callback notification

5. State Machine Pattern (state_transition.py)

• Thread-safe state transitions with explicit rules
• State machine ownership stays in orchestrator
• Transitions injected via callbacks (e.g., response_state_transition)

Knowledge Gaps

1. Test Coverage: Are there edge cases in _collect_fallback_tool_calls that are not covered by tests?
2. Debug Mode Usage: The 6 debug_mode-guarded conditionals add branching complexity - are all necessary?
3. Fallback Parsing: Is the fallback text parsing (_collect_fallback_tool_calls) actively used, or legacy code?
4. Import Coupling: Why are imports deferred inside functions? (likely to avoid circular imports)
5. State Transition Callback: The response_state_transition callback is passed but not always called - clarify contract

Refactoring Opportunities

Immediate (Low Risk)

1. Extract magic number 100 → DEBUG_PREVIEW_MAX_LENGTH
2. Remove dead parameters node and tool_callback from _collect_structured_tool_calls
3. Add constant for MS_PER_SECOND = 1000

Medium (Behavior Preserving)

1. Extract Tool Collection Module: Move _collect_structured_tool_calls and _collect_fallback_tool_calls to a new tool_collection.py module
2. Extract Tool Registry Module: Move _register_tool_call, _mark_tool_calls_running, _record_tool_failure to a registry operations module
3. Extract Logging Module: Move _log_dispatch_summary and debug logging to a separate module
4. Extract Constants: Move all constants at top of file to a separate file

Architectural

1. Create ToolDispatcher Class: Instead of module-level functions, create a class to hold state and reduce parameter passing
2. Simplify dispatch_tools: The main function should orchestrate, not implement - delegate all work to sub-modules

References

GitHub Permalinks

• tool_dispatcher.py: https://github.com/tunacode/tunacode/blob/9ed9739dda91c3f4f463c4c8f58687f75879afc7/src/tunacode/core/agents/agent_components/orchestrator/tool_dispatcher.py
• orchestrator.py: https://github.com/tunacode/tunacode/blob/9ed9739dda91c3f4f463c4c8f58687f75879afc7/src/tunacode/core/agents/agent_components/orchestrator/orchestrator.py
• tool_registry.py: https://github.com/tunacode/tunacode/blob/9ed9739dda91c3f4f463c4c8f58687f75879afc7/src/tunacode/core/types/tool_registry.py
• tool_executor.py: https://github.com/tunacode/tunacode/blob/9ed9739dda91c3f4f463c4c8f58687f75879afc7/src/tunacode/core/agents/agent_components/tool_executor.py

Test Files

• test_tool_dispatcher_coverage.py: https://github.com/tunacode/tunacode/blob/9ed9739dda91c3f4f463c4c8f58687f75879afc7/tests/integration/tools/test_tool_dispatcher_coverage.py
• test_tool_call_lifecycle.py: https://github.com/tunacode/tunacode/blob/9ed9739dda91c3f4f463c4c8f58687f75879afc7/tests/integration/core/test_tool_call_lifecycle.py

Issue

• GitHub Issue #358: Tool dispatcher complexity and dead code