Summary

When a kanban worker subprocess hits the iteration budget, the agent loop strips tools and asks the model for a summary via _handle_max_iterations(). The model cannot call kanban_block at that point (tools are gone), so the process exits with rc=0 without ever calling kanban_complete or kanban_block. The dispatcher correctly detects this as a protocol violation but treats it as fatal — giving up after 1 failure with effective_limit: 1, stranding all downstream tasks.

Root cause

The iteration-exhaustion path in run_agent.py (line ~14944) calls _handle_max_iterations() which makes a toolless API call for a summary. After the summary returns, the agent loop exits normally. There is no hook to notify the kanban dispatcher that the worker could not complete its task.

The kanban worker contract (call kanban_complete or kanban_block before exiting) lives in the kanban-worker SKILL prompt, but the iteration-exhaustion path bypasses the skill entirely — the model receives the summary directive from the agent loop, not from the skill.

Fix

After _handle_max_iterations() returns, check if HERMES_KANBAN_TASK is set (indicating the agent is running as a kanban worker). If so, call kanban_block via handle_function_call with a reason describing the exhaustion. The dispatcher then sees a clean block transition instead of a protocol violation, and the task can be retried or escalated by a human.

The kanban_block call is wrapped in a try/except to prevent failures from crashing the agent loop — if the block call fails, we log a warning and continue with the normal exit path.

Regression coverage

Two new tests in tests/run_agent/test_run_agent.py:

1. test_kanban_block_called_on_iteration_exhaustion — sets HERMES_KANBAN_TASK, exhausts the iteration budget, and asserts that handle_function_call is called exactly once with kanban_block and the correct task_id/reason.

2. test_no_kanban_block_when_not_in_kanban_mode — exhausts the iteration budget without HERMES_KANBAN_TASK set and asserts that kanban_block is never called (no spurious side effects).

Testing

• All 325 tests in tests/run_agent/test_run_agent.py pass (including the 2 new ones).
• No pre-existing test failures introduced.

Fixes [Bug] kanban-worker exits cleanly (rc=0) on iteration-budget exhaustion without calling kanban_complete or kanban_block — protocol violation strands downstream tasks #23216