Reeve
Plugins & Extensions

Coordinator Enforcer Plugin (Legacy)

Coordinator Enforcer: Automatically block direct work tools in main sessions (superseded by role-enforcer)

Coordinator Enforcer Plugin (Legacy)

⚠️ Superseded by Role Enforcer. The Role Enforcer provides everything the Coordinator Enforcer does, plus manager-tier enforcement, file-path aware blocking, and context bloat warnings. New setups should use role-enforcer instead. See the migration guide.

Code = Law. The coordinator does ZERO implementation work.

The Coordinator Enforcer plugin automatically blocks direct work tools (Edit, Write, exec) in main coordinator sessions, ensuring the main agent delegates all implementation to sub-agents via sessions_spawn.

Philosophy

The coordinator model keeps the main agent lean and focused:

RoleResponsibility
CoordinatorPlans, researches, delegates, monitors
Sub-agentsDo the actual implementation work

Benefits of enforcement:

  1. Keeps coordinator context clean
  2. Sub-agents have fresh context = better work
  3. Auditable task history
  4. Coordinator can monitor multiple parallel tasks
  5. No "just this once" temptation

Installation

  1. Copy the plugin to your Reeve plugins location:
# User plugins (recommended)
cp -r extensions/coordinator-enforcer ~/.reeve/plugins/

# Or system-wide
cp -r extensions/coordinator-enforcer /path/to/reeve/extensions/
  1. Enable in reeve.json:
{
  "plugins": {
    "coordinator-enforcer": {
      "enabled": true
    }
  }
}
  1. Restart Reeve gateway

Configuration

Minimal Config

{
  "plugins": {
    "coordinator-enforcer": {
      "enabled": true,
      "logBlocks": true
    }
  }
}

Full Config

{
  "plugins": {
    "coordinator-enforcer": {
      "enabled": true,
      "blockMessage": "Coordinator cannot do direct work. Use sessions_spawn instead.",
      "mainSessionPatterns": ["^agent:main:main$", "^main$"],
      "blockedTools": ["Edit", "Write", "exec"],
      "allowedTools": [
        "Read", "memory_search", "memory_get",
        "sessions_spawn", "sessions_list", "sessions_poll",
        "web_search", "web_fetch", "browser",
        "image", "tts", "message", "nodes", "canvas", "process"
      ],
      "strictMode": false,
      "logBlocks": true,
      "execBlockPatterns": [
        "^git\\s+", "^npm\\s+", "^pnpm\\s+", "^yarn\\s+",
        "^rm\\s+", "^mv\\s+", "^cp\\s+"
      ],
      "execAllowPatterns": [
        "^ls\\s+", "^cat\\s+", "^head\\s+", "^tail\\s+",
        "^grep\\s+", "^find\\s+", "^pwd$", "^echo\\s+"
      ]
    }
  }
}

Options Reference

OptionTypeDefaultDescription
enabledbooleantrueEnable/disable enforcement
blockMessagestring"Coordinator cannot..."Message shown when blocked
mainSessionPatternsstring[]["^agent:main:main$", "^main$"]Regex patterns for main sessions
blockedToolsstring[]["Edit", "Write", "exec"]Tools to block
allowedToolsstring[](see above)Tools explicitly allowed
strictModebooleanfalseBlock ALL except allowedTools
logBlocksbooleantrueLog blocked attempts
execBlockPatternsstring[](see above)Exec commands to block
execAllowPatternsstring[](see above)Exec commands to allow

How It Works

Session Detection

The plugin identifies main coordinator sessions via regex patterns:

  • ^agent:main:main$ — Standard main agent session
  • ^main$ — Alternative main session key

Sub-agent sessions are NEVER blocked. Sessions containing :subagent: are automatically excluded from enforcement.

Tool Blocking Logic

Tool call arrives
    ↓
Is this a main coordinator session?
├── No → Allow (sub-agents can do anything)
└── Yes → Check tool
    ├── Edit/Write → BLOCKED
    └── exec → Check command patterns
        ├── Matches allowPattern → Allow
        ├── Matches blockPattern → BLOCKED
        └── No match → Allow

Smart Exec Handling

Not all shell commands are equal. The plugin allows read-only commands while blocking modifications:

Allowed by default:

  • ls, cat, head, tail (reading)
  • grep, find, which (searching)
  • pwd, date, whoami (info)

Blocked by default:

  • git (version control)
  • npm, pnpm, yarn, cargo (package managers)
  • rm, mv, cp (file operations)
  • python *.py, node *.js (script execution)

Error Messages

When blocked, the agent receives helpful guidance:

Coordinator cannot do direct work. Use sessions_spawn instead.

Blocked tool: Edit
Session: agent:main:main

To edit a file, spawn a sub-agent:
  sessions_spawn(task="Edit file X to do Y", label="edit-task")

Gateway API

Check Status

reeve gateway call coordinator-enforcer.status

Returns:

{
  "ok": true,
  "enabled": true,
  "strictMode": false,
  "stats": {
    "blockedCalls": 42,
    "allowedCalls": 1337,
    "lastBlockedTool": "Edit",
    "blocksByTool": { "Edit": 30, "exec": 12 }
  }
}

Check Session

reeve gateway call coordinator-enforcer.check-session \
  '{"sessionKey": "agent:main:main"}'

Simulate Tool Call

reeve gateway call coordinator-enforcer.simulate '{
  "sessionKey": "agent:main:main",
  "toolName": "exec",
  "command": "git status"
}'

Reset Stats

reeve gateway call coordinator-enforcer.reset-stats

Examples

Wrong: Coordinator doing direct work

# Main session tries to edit - BLOCKED!
Edit(path="file.py", oldText="x", newText="y")
# Error: Coordinator cannot do direct work...

Right: Coordinator delegates

# Main session delegates - ALLOWED!
sessions_spawn(
  task="Change x to y in file.py",
  label="fix-typo"
)
# Returns: spawned subagent ID

Strict Mode

For maximum enforcement, enable strict mode:

{
  "plugins": {
    "coordinator-enforcer": {
      "enabled": true,
      "strictMode": true,
      "allowedTools": [
        "Read",
        "memory_search",
        "sessions_spawn",
        "sessions_list",
        "sessions_poll",
        "web_search"
      ]
    }
  }
}

In strict mode, ONLY tools in allowedTools are permitted—everything else is blocked.

Troubleshooting

Plugin not blocking?

  1. Check enabled: true in config
  2. Verify session key matches mainSessionPatterns
  3. Check logs: grep "coordinator-enforcer" ~/.reeve/logs/gateway.log

Need to allow specific exec commands?

Add patterns to execAllowPatterns:

{
  "execAllowPatterns": [
    "^ls\\s+",
    "^reeve\\s+",
    "^my-safe-script$"
  ]
}

Sub-agents being blocked?

Sub-agent sessions (containing :subagent:) are automatically excluded. If issues persist, check your session key patterns.

Need to disable temporarily?

{
  "plugins": {
    "coordinator-enforcer": {
      "enabled": false
    }
  }
}

Or call the gateway:

reeve gateway call coordinator-enforcer.disable

Integration with Operating Model

This plugin codifies the principles in:

Using with Pipeline V3

The coordinator-enforcer works seamlessly with Pipeline V3 tools:

# The pipeline spawns sub-agents for all work
# Main session stays clean, enforcer never triggered
./bin/run-pipeline-v3.py --spec docs/plan.md --repo ./app

# Audit tools also spawn sub-agents for fixes
./bin/run-audit-v3.py --repo ./app

# Logic audit verifies via sub-agents
./bin/run-logic-audit-v3.py --frontend ./frontend --backend ./backend

The pipeline tools use ReeveLLMCaller which spawns sessions with IDs like pipeline-Architect-1, which are automatically excluded from enforcement (not main sessions).

See Also

Plugin agent tools

Write agent tools in a plugin (schemas, optional tools, allowlists)

Role Enforcer Plugin

Role Enforcer: Unified three-tier enforcement for Coordinator → Manager → Worker

On this page

Coordinator Enforcer Plugin (Legacy)PhilosophyInstallationConfigurationMinimal ConfigFull ConfigOptions ReferenceHow It WorksSession DetectionTool Blocking LogicSmart Exec HandlingError MessagesGateway APICheck StatusCheck SessionSimulate Tool CallReset StatsExamplesWrong: Coordinator doing direct workRight: Coordinator delegatesStrict ModeTroubleshootingPlugin not blocking?Need to allow specific exec commands?Sub-agents being blocked?Need to disable temporarily?Integration with Operating ModelUsing with Pipeline V3See Also