Add agent coordination hooks to prevent duplicate work and conflicting actions

[geoffjay]

Overview

Add Claude Code hooks that enforce coordination between agents before they create issues, close issues, post announcements, or take other multi-step actions. This directly addresses the coordination failures observed during the v0.9.0 planning session where agents created 68 duplicate issues across 4 competing milestones because they didn't check what other agents were doing.

Problem Statement

During the v0.9.0 planning session:

• 3 agents independently created overlapping milestones and 68 duplicate issues
• Agents posted 4 competing announcements to the announcements channel
• Agents closed each other's issues without comparing content quality
• Agents continued creating duplicates after being asked to stop in the engineering channel
• One agent reported deleted milestones and closed issues as if they were still active

Root cause: no mechanism exists to check what other agents are doing before taking action. Agents operate in isolated context windows with no awareness of concurrent activity.

Proposed Hooks

1. PreToolUse hook on issue creation

Intercepts Bash commands matching gh issue create. Before allowing the command:

• Query the engineering room via communicate service for recent messages (last 30 min)
• Check for active "filing in progress" lock messages from other agents
• Search existing open issues for similar titles (fuzzy match)
• If a lock is active or a similar issue exists, inject a warning into the agent's context and block the action

2. PreToolUse hook on issue close/reopen

Intercepts Bash commands matching gh issue close or gh issue reopen. Before allowing:

• If closing: compare the issue's content length/quality with any referenced duplicate
• If the issue being kept is less detailed than the one being closed, warn the agent
• Check engineering room for context about whether this closure was coordinated

3. PreToolUse hook on announcements

Intercepts communicate service send commands targeting the announcements room. Before allowing:

• Fetch the last 5 messages in announcements
• If a message on the same topic was posted in the last hour, block and warn
• Require that engineering channel discussion preceded the announcement

4. Lock/unlock protocol via communicate service

Agents post coordination signals to engineering before multi-step operations:

[LOCK] planner: filing v0.9.0 milestone issues -- hold all issue creation
[UNLOCK] planner: filing complete, 36 issues created

The PreToolUse hook checks for active locks before allowing issue mutations.

Implementation

Hook script location

.claude/hooks/check-coordination.sh (or similar)

settings.json configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": ".claude/hooks/check-coordination.sh"
      }
    ]
  }
}

Hook script behavior

1. Parse the Bash command from stdin
2. If command matches gh issue create|close|reopen or agent communicate send.*announcements:
   a. Query communicate service for engineering room messages (last 30 min)
   b. Check for active LOCK messages
   c. If blocked, output a JSON warning that gets injected into agent context
   d. If clear, allow the command to proceed
3. For non-matching commands, pass through immediately (no latency impact)

Environment requirements

• Communicate service must be reachable (fall back to allow if service is down)
• Hook must be fast (< 2 second timeout, with fallback to allow on timeout)

Acceptance Criteria

• PreToolUse hook exists and is configured in settings.json
• Hook intercepts gh issue create commands and checks for locks/duplicates
• Hook intercepts gh issue close commands and warns on quality mismatch
• Hook intercepts announcements and checks for recent duplicates
• Lock/unlock protocol is documented and referenced in all agent system prompts
• Hook fails open (allows action) if communicate service is unreachable
• Hook adds < 2 seconds latency to intercepted commands
• All agent system prompts updated to include lock/unlock protocol for multi-step operations

Context

This issue is part of Epic 5: Platform Changes for Autonomy (#637), alongside:

• Add agent file-path scoping to restrict which files each agent type can modify #642 (agent file-path scoping) -- what files agents can touch
• Define and enforce human approval gates for autonomous operations #643 (human approval gates) -- what operations need human sign-off
• This issue -- preventing duplicate/conflicting work between agents

Together these three form the safety and coordination layer for autonomous operation.

Caution

All work in this milestone must branch off feature/autonomous-pipeline and PR back into it -- never directly to main.

[geoffjay]

Implemented in PR #703. Added check-coordination.py PreToolUse hook plus lock/unlock protocol in planner, worker, conductor, and triage system prompts.