Feature: Optional orchestrator-only mode - enforce subagent usage for all work

[edmondscommerce]

Summary

Create an optional set of hooks that enforce a pure orchestration model: the main Claude Code thread becomes a pure orchestrator and is blocked from doing any actual work. All coding, testing, file operations, and other work must be delegated to subagents.

Motivation

Currently, Claude Code can perform work directly in the main thread or delegate to subagents. This leads to:

• Inconsistent patterns where some work is done inline vs delegated
• Harder to enforce separation of concerns
• Difficult to track which agent actually performed work

An orchestrator-only mode would:

• Force clean separation: orchestration vs execution
• Enable better telemetry and observability
• Potentially improve quality by always using specialized subagents
• Make it easier to reason about agent behavior

Proposed Solution

Hook-Based Enforcement

Create new PreToolUse handlers that intercept "work" tools when in orchestrator mode:

• Block: Edit, Write, Bash (coding commands), direct code modifications
• Allow: Task (subagent spawning), Read, Glob, Grep (read-only exploration)
• Allow: AskUserQuestion, communication tools

The hooks would be optional - users opt-in via config:

handlers:
  pre_tool_use:
    orchestrator_mode:
      enabled: true  # Default: false
      priority: 15   # Run early, block before execution

Research Phase

Use the new debug infrastructure (scripts/debug_hooks.sh) to:

1. Capture real workflows: Record actual Claude Code sessions doing various tasks
2. Analyze tool usage patterns: Which tools are "work" vs "orchestration"?
3. Identify edge cases: When should main thread be allowed to work?
4. Design handler logic: Precise rules for what gets blocked

Example debug session:

./scripts/debug_hooks.sh start "Coding task analysis"
# User: "Add a login feature"
# Observe: Which tools fire? When? What's delegated vs inline?
./scripts/debug_hooks.sh stop

Implementation Phases

Phase 1: Research & Design

• Use debug mode to capture 5-10 different workflow types
• Document tool usage patterns
• Design exact blocking rules
• Write design doc with examples

Phase 2: Handler Implementation

• Create handlers/pre_tool_use/orchestrator_mode.py
• Implement tool classification logic
• Add comprehensive tests

Phase 3: Validation

• Test with real workflows
• Tune blocking rules based on usability
• Document best practices

Technical Details

Tools Classification (Initial Draft)

Block (work tools):

• Edit, Write, NotebookEdit - file modifications
• Bash with certain patterns - code execution, git commits, etc.
• Direct code manipulation

Allow (orchestration tools):

• Task - subagent spawning
• Read, Glob, Grep - exploration/research
• AskUserQuestion - user interaction
• TaskCreate, TaskUpdate, TaskList - task management

Context-Dependent:

• Bash for read-only operations (git log, ls, etc.) - maybe allow?
• Need research to determine

Handler Structure

class OrchestratorModeHandler(Handler):
    def __init__(self) -> None:
        super().__init__(
            name="orchestrator-mode",
            priority=15,  # Early, before work happens
            terminal=True
        )
    
    def matches(self, hook_input: dict) -> bool:
        tool_name = hook_input.get("tool_name")
        # Return True if tool is "work" that should be delegated
        return tool_name in ["Edit", "Write", "Bash", ...]
    
    def handle(self, hook_input: dict) -> HookResult:
        return HookResult(
            decision="deny",
            reason="Orchestrator mode: Please use Task tool to spawn subagent for this work",
            context={"blocked_tool": hook_input.get("tool_name")}
        )

Config Schema

Extend .claude/hooks-daemon.yaml:

handlers:
  pre_tool_use:
    orchestrator_mode:
      enabled: false  # Opt-in
      priority: 15
      allow_read_only_bash: true  # Allow safe bash commands?
      custom_allowed_tools: []     # User-defined exceptions

Next Steps

1. Use scripts/debug_hooks.sh to capture 10+ real workflow sessions
2. Analyze logs to understand tool usage patterns
3. Draft precise blocking rules (design doc)
4. Implement handler with tests
5. Validate with real usage
6. Document in CLAUDE/HANDLER_DEVELOPMENT.md

References

• Debug infrastructure: CLAUDE/DEBUGGING_HOOKS.md
• Handler development guide: CLAUDE/HANDLER_DEVELOPMENT.md
• Existing safety handlers: handlers/pre_tool_use/destructive_git.py
• Hook event types: daemon/events.py

Labels

enhancement, handlers, research-needed

[edmondscommerce]

✅ Implementation plan created: Plan 00019 - Orchestrator-Only Mode

This plan implements an optional PreToolUse handler that enforces orchestration-only patterns by blocking work tools and requiring Task delegation.

[edmondscommerce]

✅ Completed in Plan 00019

Implemented orchestrator-only mode handler:

• PreToolUse handler blocks work tools (Edit, Write, Bash mutations)
• Allows orchestration tools (Task, Read, Glob, Grep, planning)
• Configurable read-only Bash prefix allowlist
• Opt-in via config (disabled by default)
• Priority 8, terminal blocking for work tools
• Clear deny messages directing to Task tool

Merged to main: 915aa4c

[edmondscommerce]

Status Update: Handler Removed, Waiting for Upstream

The OrchestratorOnlyHandler has been removed from the codebase (commit a3b5035). It was never enabled in any config and has a fundamental limitation: Claude Code hooks provide no way to distinguish which agent (main thread vs teammate) is firing a PreToolUse event. If enabled, it blocks ALL agents equally - making agent teams unusable.

Code is archived in CLAUDE/Plan/00032-subagent-orchestration-context-preservation/archived-code/ for future reference.

The Real Solution: Upstream Delegate Mode

Claude Code already has a built-in Delegate Mode (Shift+Tab cycling) that does exactly what we need - restricts the lead agent to coordination-only tools while teammates get full access. However, it's currently broken:

The bug: Delegate mode cascades to spawned teammates, stripping them of file system tools too.

Upstream Issues to Watch

Issue	Description	Status
anthropics/claude-code#23447	Delegate mode cascades to teammates	Open
anthropics/claude-code#24073	Teammates in Delegate Mode lose tool access	Open
anthropics/claude-code#24307	Related delegate mode issue	Open
anthropics/claude-code#25037	Delegate mode breaks agent teams	Open
anthropics/claude-code#14859	Add agent_id/parent_agent_id to ALL hook events	Open
anthropics/claude-code#7881	SubagentStop can't identify which subagent finished	Open

What Would Unblock Us

Either of these upstream fixes would let us revisit:

1. Delegate mode fix (most likely) - If Anthropic fixes the cascade bug, delegate mode becomes the first-class solution and we may not need a daemon handler at all.

2. Agent hierarchy in hooks (#14859) - If agent_id/parent_agent_id fields are added to PreToolUse events, we could rebuild our handler to selectively enforce only on the main thread.

Related Plans (All On Hold)

• Plan 00032: Sub-Agent Orchestration for Context Preservation
• Plan 00034: Model-Aware Agent Team Advisor
• Plan 00035: StatusLine Data Cache + Model-Aware Advisor

Full research: RESEARCH-2026-02-23.md