fix: restore delegation directive after f831fd2 regression

[barkain]

Summary

• Main agent stopped delegating after commit f831fd2 simultaneously weakened three surfaces (stub, nudge hook, output style). This PR restores delegation strength without re-introducing hard blocks.
• Stub (system-prompts/orchestrator_stub.md) gains explicit "work" definition, MUST NOT list, and self-catch directive.
• PreToolUse nudge (hooks/PreToolUse/require_delegation.py) rewrites messages to be imperative and action-specifying from violation Enhance agents in delegate #1.
• Output style (output-styles/technical-adaptive.md) removes the direct-action "after completing an edit" prime and reframes the main agent as orchestrator.

Test plan

• Start a fresh Claude Code session; prompt a multi-step task; verify main agent routes through /workflow-orchestrator:delegate instead of calling Read/Edit/Bash directly
• Trigger a single direct tool call; verify the nudge on violation Enhance agents in delegate #1 is the new "STOP. ..." imperative
• Confirm no hard blocks: if the model ignores nudges, tool calls still succeed (soft enforcement only)
• uvx ruff check --no-fix hooks/PreToolUse/require_delegation.py clean
• Plan-mode continuation Exception clause still works (no regression in the v2.0.1 fix)

🤖 Generated with Claude Code

[qodo-code-review]

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

Review Summary by Qodo

Restore delegation directive strength without hard blocks

🐞 Bug fix ✨ Enhancement

Walkthroughs

Description

• Restores delegation enforcement across three surfaces weakened by f831fd2
• Nudge messages now imperative ("STOP. Abandon...") from first violation
• Stub gains explicit "work" definition and self-catch directive
• Output style reframes main agent as orchestrator, not executor

Diagram

flowchart LR
  A["Regression f831fd2<br/>weakened delegation"] -->|Stub| B["Add work definition<br/>& self-catch"]
  A -->|Nudge| C["Imperative messages<br/>from violation #1"]
  A -->|Output Style| D["Reframe as<br/>orchestrator"]
  B --> E["Soft enforcement<br/>restored"]
  C --> E
  D --> E

Loading

File Changes

1. hooks/PreToolUse/require_delegation.py ✨ Enhancement +9/-8

Rewrite nudge messages to imperative escalation

• Violation #1 message changed from passive "delegate?" to imperative "STOP. This tool call bypasses
 delegation. Abandon this step and run: /workflow-orchestrator:delegate <your task>"
• Violation #2 message rewritten to emphasize main agent does not execute work tools
• Violation #3+ messages restructured to highlight lost benefits (planning, parallelization, context
 isolation)
• All messages now action-specifying and escalation-clear

hooks/PreToolUse/require_delegation.py

---

2. output-styles/technical-adaptive.md ✨ Enhancement +3/-1

Reframe main agent role as orchestrator

• Added preamble clarifying main agent is orchestrator, not executor
• Updated completion example from "Done. Added timeout..." to "Done. Wave 0 added timeout..." with
 delegation context
• Responses now summarize subagent output rather than describe direct tool calls

output-styles/technical-adaptive.md

---

3. system-prompts/orchestrator_stub.md ✨ Enhancement +17/-0

Add explicit work definition and self-catch directive

• Added "What counts as work" section with explicit list (Read, Grep, Glob, Edit, Write, MultiEdit,
 Bash, multi-step tasks)
• Added "What you MUST NOT do" section with prohibitions (no pre-check reads, no grep/find/ls via
 Bash, no small edits, no chaining)
• Added self-catch instruction: "If you catch yourself about to call
 Bash/Edit/Write/Read/Glob/Grep/MultiEdit, STOP and invoke /workflow-orchestrator:delegate"

system-prompts/orchestrator_stub.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Delegation tests now fail ☑ 🐞 ≡

Description

Changing require_delegation.message_for() from the old delegate?/nudge/WARNING ladder to new
"STOP..." messages breaks existing tests that assert the previous strings and message-length/token
scaling. This will cause test failures and leaves multiple docs/examples describing behavior that no
longer exists.

Code

hooks/PreToolUse/require_delegation.py[R96-109]

+        return (
+            "STOP. This tool call bypasses delegation. Abandon this step "
+            "and run: /workflow-orchestrator:delegate <your task>"
+        )
   if count == 2:
-        return "nudge: use /workflow-orchestrator:delegate for multi-step work"
-    if count <= 4:
       return (
-            f"WARNING: {count} direct tool calls bypassing delegation. "
-            "Use /workflow-orchestrator:delegate <task>."
+            "STOP. 2nd direct tool call this turn. The main agent does not "
+            "execute work tools. Run: /workflow-orchestrator:delegate <your task>"
       )
   return (
-        f"WARNING: {count}+ direct tool calls. The orchestrator plans, "
-        "parallelizes, and isolates context — direct use loses these benefits. "
-        "Run /workflow-orchestrator:delegate <task> now."
+        f"STOP. {count} direct tool calls bypassing delegation. You are "
+        "losing planning, parallelization, and context isolation. Abandon "
+        "the current plan and run: /workflow-orchestrator:delegate <your task>"
   )

Evidence

The hook now emits only "STOP..." strings for counts 1, 2, and 3+, but the test suite and
documentation still expect the old escalation ladder (delegate? → nudge → WARNING) and also assert
specific length scaling that is no longer true given the much longer first-level message.

hooks/PreToolUse/require_delegation.py[88-109]
tests/test_require_delegation.py[112-153]
CLAUDE.md[111-123]
README.md[191-216]
CHANGELOG.md[32-37]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`hooks/PreToolUse/require_delegation.py` changed its escalation messages (now "STOP..."), but tests and docs still assert/document the previous ladder (`delegate?`, `nudge: ...`, `WARNING: ...`) and old token/length expectations.
## Issue Context
This will break `tests/test_require_delegation.py` immediately and leaves repo guidance (CLAUDE.md/README.md/CHANGELOG.md) misleading.
## Fix Focus Areas
- hooks/PreToolUse/require_delegation.py[88-109]
- tests/test_require_delegation.py[112-153]
- CLAUDE.md[111-123]
- README.md[191-216]
- CHANGELOG.md[32-37]
## What to change
- Update the unit tests to match the new semantics. Prefer robust assertions (e.g., contains `/workflow-orchestrator:delegate` and maybe startswith `STOP.`) rather than exact legacy tokens like `delegate?`/`nudge`/`WARNING`.
- Rework the length-scaling assertions so they reflect the new ladder (the first message is no longer "short", so `lengths[-1] > lengths[0] * 5` will not hold).
- Update CLAUDE.md/README.md/CHANGELOG.md examples and tables to reflect the new emitted strings (and any revised token-cost guidance).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Stub guidance inconsistent with /ask ☑ 🐞 ⚙

Description

orchestrator_stub.md now instructs using /workflow-orchestrator:ask for file-backed questions, but
it also states the main agent should use only Tasks API, AskUserQuestion, and
/workflow-orchestrator:delegate, creating contradictory routing rules. The new "work" tool list
also omits NotebookEdit even though the enforcement hook tracks it as a work tool.

Code

system-prompts/orchestrator_stub.md[R17-23]

+## What counts as "work"
+
+ANY of these = delegate:
+- Reading, searching, editing, or writing files (Read, Grep, Glob, Edit, Write, MultiEdit)
+- Running shell commands (Bash) for anything beyond a single trivial status check
+- Investigating the codebase to answer a question that requires file access → use /workflow-orchestrator:ask
+- Multi-step tasks, even if each step looks simple in isolation

Evidence

The stub’s earlier rule limits allowed commands to delegate only, while the newly-added "work"
definition and the existing "Pure Q&A" section explicitly recommend /workflow-orchestrator:ask.
Additionally, the newly-added explicit work-tool examples omit NotebookEdit, but the hook’s
WORK_TOOLS set includes it, creating inconsistent guidance about what must be delegated.

system-prompts/orchestrator_stub.md[11-12]
system-prompts/orchestrator_stub.md[17-23]
system-prompts/orchestrator_stub.md[40-42]
hooks/PreToolUse/require_delegation.py[42-52]
CLAUDE.md[49-55]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`system-prompts/orchestrator_stub.md` contains conflicting routing guidance: it says to use only Tasks API/AskUserQuestion/`/workflow-orchestrator:delegate`, but it also directs use of `/workflow-orchestrator:ask` for read-only codebase investigation. The new "work" examples also omit `NotebookEdit`, which is tracked as a work tool by the enforcement hook.
## Issue Context
The stub is a system prompt; ambiguity here can weaken delegation compliance and confuse future edits.
## Fix Focus Areas
- system-prompts/orchestrator_stub.md[11-12]
- system-prompts/orchestrator_stub.md[17-23]
- system-prompts/orchestrator_stub.md[40-42]
- hooks/PreToolUse/require_delegation.py[42-52]
## What to change
- Update the stub’s allowed-command sentence to explicitly include `/workflow-orchestrator:ask` (or rephrase to “use only Tasks API, AskUserQuestion, and workflow-orchestrator slash commands (/delegate, /ask)”).
- Update the "What counts as work" tool examples to include `NotebookEdit` (to match the tracked WORK_TOOLS set) or avoid enumerating specific tool names if you want to prevent drift.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[barkain]

/agentic_review