kandev/docs/specs/tasks/blocked-task-escalation.md

status, created, owner

status	created	owner
draft	2026-04-28	cfl

Blocked Task Escalation

Why

When an agent hits a decision point it cannot resolve on its own — a missing credential, an ambiguous requirement, a design choice only the human can make — it currently has two options: post a comment and exit, or spin indefinitely. Neither gives the human a clean, actionable queue. Comments get buried in the task thread and there is no way to filter for "things that need my attention right now." The result is that blocked agents sit idle while the human has no structured signal that their input is required.

What

• When an agent is blocked and needs human input (design decision, access credentials, external approval, architectural choice), it creates a new task titled Decision needed: <question> and assigns it to the human user.
• The new task is linked as a blocker of the agent's current task: the agent task's blockedBy list includes the human task's ID.
• The agent task moves to Blocked status. The agent exits cleanly after creating the blocker task and posting a comment.
• The human sees a dedicated, filterable card in their kanban view. When the human resolves the decision task (marks it done), the orchestrator detects that all blockers for the agent task have cleared and sends a task_blockers_resolved wakeup to the agent.
• The agent resumes with the resolution context included in its wake payload.
• This behavior is taught to agents via a new bundled skill (kandev-escalation) rather than being hardcoded in the backend. The skill provides the pattern and CLI commands; the underlying infrastructure (task create --blocked-by, task_blockers_resolved wakeup) already exists.

Scenarios

• GIVEN an agent working on "Implement OAuth login" encounters an ambiguous requirement about which OAuth provider to support, WHEN it creates a human task Decision needed: Which OAuth providers should we support? blocked-by the agent task and sets the agent task to blocked, THEN a new unassigned "Decision needed" card appears on the kanban board and the agent's task shows a blocker badge pointing to that card.

• GIVEN the human sees the "Decision needed" card, reads the question in the description, and marks it done, WHEN the orchestrator processes the task-completion event, THEN it detects the blocked agent task has no remaining open blockers and queues a task_blockers_resolved wakeup for the assigned agent.

• GIVEN the task_blockers_resolved wakeup fires, WHEN the agent wakes, THEN KANDEV_WAKE_REASON is task_blockers_resolved and the wake payload includes the resolved blocker title so the agent can reference the decision in its next message.

• GIVEN multiple blockers exist (e.g., the agent escalated two separate questions), WHEN the human resolves each human task one by one, THEN the wakeup fires only after the last open blocker is resolved (existing coalescing/idempotency behavior in queueBlockersResolvedWakeups handles this correctly).

Out of scope

• Automatically assigning the human task to a specific user account (kandev currently has no user account model; "assigned to the human" means unassigned or assigned by a workspace human_user_id setting if one is configured).
• Backend changes to the orchestrator or scheduler — the existing task_blockers_resolved event chain is sufficient.
• A dedicated UI widget for "awaiting my decision" items; the standard kanban filter covers this.
• Automatic escalation timeouts (agent wakes after N hours if human hasn't responded).
• Any changes to the clarification/permission system — this is a task-creation pattern, not a request/response channel.

Open questions

• Should the human task be left unassigned (relies on the human scanning the board) or should a KANDEV_HUMAN_USER_ID workspace setting be introduced so the task is explicitly assigned? The unassigned approach works today; explicit assignment requires adding the setting.