fix(agent): gate the kanban worker protocol on dispatch context, not tool presence

[Sora-bluesky]

Fixes #68592.

Problem

The kanban worker task-execution protocol (KANBAN_GUIDANCE — "You have been assigned ONE task… Call kanban_show() first") was injected into the system prompt on mere kanban_show tool presence. But _check_kanban_mode (tools/kanban_tools.py) exposes the kanban tool surface in two situations: dispatcher-spawned workers (HERMES_KANBAN_TASK set) and profiles with kanban in their toolsets config (orchestrator mode, no task id). On an orchestrator profile, every agent run — notably every cron run — was instructed to call kanban_show() first, which fails with task_id is required and logs a warning per run. The gating comment in agent_init.py ("kanban_show tool is present iff HERMES_KANBAN_TASK is set") described a constraint that no longer held.

Fix

Three-way split at both injection sites (the session-static resolution in agent_init.py and the bypass-agent_init fallback in agent/system_prompt.py):

• HERMES_KANBAN_TASK set + tool present → full worker protocol, unchanged.
• Tool present, no task id → new lean KANBAN_ORCHESTRATOR_GUIDANCE: board-routing rules only, explicitly stating there is no assigned task and kanban_show() needs an explicit task_id.
• No tool → nothing, unchanged.

The orchestrator block deliberately preserves the routing rules that were folded into the always-injected guidance when the standalone kanban-orchestrator skill was removed (#50473): discover profiles before assigning (the dispatcher silently drops cards with unknown assignees), express dependencies via parents=[...], never invent created-card ids, attach artifacts instead of pasting links, and don't shell out to hermes kanban. Removing the guidance wholesale would have regressed those.

The env-var gate matches how workers are actually spawned: _default_spawn starts the worker host-locally with HERMES_KANBAN_TASK in Popen(env=...); Docker/SSH/Modal are terminal backends inside that process, not separate spawn paths. (Custom plugin spawn_fn implementations own their environment contract.)

Operational note

Durable sessions restore their persisted system prompt verbatim, so an interactive orchestrator session resumed from before this fix keeps the old mandatory-kanban_show() text until its prompt is rebuilt. Cron runs are unaffected (each run gets a fresh session). No cache invalidation is attempted here — that's a separate design decision; #68598 (input-fingerprint restore gating) provides the general mechanism.

Tests

• RED-first: new test_kanban_guidance_not_in_orchestrator_profile_prompt (kanban toolset via config.yaml, no env var → tool surface present, worker protocol absent, board guidance present) failed before the fix.
• New test_kanban_guidance_fallback_three_way_split covers the system_prompt.py fallback directly (deletes _kanban_worker_guidance to simulate bypassing agent_init).
• tests/tools/test_kanban_tools.py: 116 passed. tests/agent/test_system_prompt.py + tests/agent/test_platform_hint_desktop.py: 32 passed. The 8 failures in tests/hermes_cli/test_kanban_core_functionality.py on this Windows machine reproduce identically on clean upstream/main (pre-existing, unrelated).

🤖 Generated with Claude Code

[teknium1]

Thanks for carrying the full worker/orchestrator split.

Current main still has the reported defect: tools/kanban_tools.py:92-108 exposes kanban_show for a profile configured with the kanban toolset even without HERMES_KANBAN_TASK, while agent/agent_init.py:1420-1423 injects the worker protocol on tool presence alone. That protocol requires kanban_show() first (agent/prompt_builder.py:215-219), and the handler rejects an unscoped call at tools/kanban_tools.py:404-408.

The PR also covers the separate bypass-init injection at agent/system_prompt.py:238-243, rather than fixing only the primary initialization path. Its separate orchestrator guidance fits the intent of 84e1d31e5442eeff0bfcf1c2ffab6acf7fe95f45, which folded routing rules into the injected Kanban guidance when the standalone skills were removed.

Automated hermes-sweeper review.

[Sora-bluesky]

Thanks for tracing both injection sites. The bypass-init one at agent/system_prompt.py:238-243 is the reason this is not a one-line gate: fixing only the toolset path in agent/agent_init.py would leave a profile that skips init still receiving the worker protocol, and the handler at tools/kanban_tools.py:404-408 would keep rejecting the call the protocol asks for first.

[roboticsalign]

Independently verified against current main: the reported failure is reproducible in an interactive Desktop/orchestrator session when the profile has the kanban toolset but no HERMES_KANBAN_TASK. The current code injects the worker protocol, which prompts an unscoped kanban_show() call and produces task_id is required.

PR #68608 fixes that failure through the three-way worker/orchestrator/no-Kanban split while preserving board-routing guidance. It merges cleanly with current main, and the relevant suites pass after the merge (66 passed). I found no blocking issues.