Hermes Delegation Batch

Hermes Delegation — Batch Dispatch

When you have 2+ truly independent tasks, dispatch them in one delegate_task batch instead of sequential calls. Faster, less context pollution, same audit trail.

When to Use

• 2+ independent tasks (different problem domains, no shared mutable state)
• Each task has its own success criterion and verification command
• Wall-clock savings matter (independent investigations, parallel reviews, parallel research)
• Each task fits a single subagent's lifetime (minutes, not hours)

When NOT to Use

• Any task depends on another's output (run sequentially)
• Tasks share mutable state on disk (two writers on same file)
• User needs linear / narrative progression
• Single simple action — subagent overhead > benefit
• You need real-time interactive answer (subagents don't ping back)

Concurrency Rules (Hermes Hard Limits)

• delegation.max_concurrent_children defaults to 3 for the current profile (see ~/.hermes/config.yaml).
• Exceeding the cap queues; the cap is NOT a bug, do not try to "raise it" mid-batch.
• Each child is role=leaf by default → they cannot delegate further. Use role=orchestrator ONLY if you intend a 1-level-deep tree.
• Children get isolated context (no session history) and the tools you grant via toolsets=[...]. The more tools, the more tokens per child.
• Children do NOT share memory, the working directory, or git state beyond what you pass in context.

Batch Template

delegate_task(
  tasks=[
    {
      "goal": "<single sentence, with the success criterion embedded>",
      "context": "<path:line refs + 1-3 sentences of background>",
      "toolsets": ["terminal", "file"],   # or narrower
    },
    {
      "goal": "...",
      "context": "...",
      "toolsets": ["web", "file"],
    },
    {
      "goal": "...",
      "context": "...",
      "toolsets": ["terminal"],
    },
  ]
)

Rules for each task dict:

• goal MUST include the verification command (e.g., "Implement X; run pytest tests/x -q and paste the last 5 lines on success").
• context MUST use path:line references, not pasted file content. Limit to the 5-15 most relevant references.
• toolsets should be the minimum the task needs:
  • terminal — for code execution, tests, git, file ops
  • file — read_file / write_file / patch / search_files
  • web — web_search / web_extract / browser_*
  • delegation — only if you grant role=orchestrator
  • default is broad; prefer narrower

Pre-Dispatch Checklist (do not skip)

1. Verify independence — no task's goal requires another task's output. If unsure, sequential.
2. Verify isolation — tasks touch disjoint file paths. If two tasks edit the same file, one wins; serialize.
3. Verify token cost — sum of context sizes ≤ 50% of your remaining context budget. Hermes copies each task's context into the child.
4. Verify toolsets — if a task needs git push, it needs terminal. If it needs web search, web. Don't grant web to a code-only task.
5. Verify success criteria — every goal ends with a concrete output the parent can check (command exit, file path, JSON shape).

What to Read in the Results

Subagents return only the FINAL summary. Don't ask the parent to read subagent stdout. Verify yourself:

# After batch returns
for path in <changed_files>:
    terminal(f"git diff --stat {path}")           # confirm changes
terminal("pytest tests/ -q")                       # run shared test if applicable
terminal("git status --short")                     # ensure no untracked garbage

If a subagent's summary is too thin to verify, re-dispatch that one task with a stricter goal. Don't accept "I did the work" without evidence.

Common Pitfalls

1. Granting web to code-only tasks — wastes tokens, expands blast radius. Default to no.
2. No verification command in goal — agent reports success without proving it.
3. Pasting long file content into context — use path:line. Pasting inflates every child.
4. Tasks with shared file writes — one wins, the other silently loses. Audit git diff --stat after.
5. Forgetting role=orchestrator — children are leaves; if you need a 2-level tree, set the role explicitly.
6. Re-dispatching after partial failure — if 2/3 tasks succeed, you can re-dispatch ONLY the failed one. Don't replay the whole batch.
7. Cap exceeded — references/delegate-task-concurrency-diagnosis.md has the three real cap paths. If none fired, the model is self-limiting; raise concurrency budget in the goal, not by retrying.

Verifying Independence (Concrete Heuristics)

Verification Checklist

• All tasks pass independence + isolation checks above
• Sum of context < 50% of remaining budget
• toolsets are minimum-permissive
• Every goal ends with a verification command or success criterion
• delegate_task returned summaries for ALL tasks (no queued failures)
• Parent re-verified each result with a terminal command
• git status clean (no orphan files)
• If HIGH risk: L2 review ran after batch (see review-gate skill)