Task handoff records and human-approval state (v0.2.0)

[mrchatam]

Based on community feedback: when a test fails or the worker needs human approval, the supervisor should keep the task as blocked, with the failed check, the owner and the exact next action, so a later agent can resume it without guessing.

What changes

Handoff record on every finished task (task.handoff, persisted in task.json; returned in full by task_result, summarized in task_status and list_tasks). The daemon derives it deterministically from the verdict and data it already has. The model never writes it. When the worker's RESULT block asks for something, that request is quoted.

Field	Meaning
state	done, needs_fix, needs_review, needs_approval, needs_input, blocked, retryable, closed
failed_checks	tests (command, exit code, failing test names, excerpt), integrity, blocked_calls (with examples), timeout, stall, interrupted, worker_error, worker_status, result_block, no_changes
owner	who acts next: supervisor, human or a named owner
next_action	one exact instruction, e.g. "Run continue_task with instructions to fix the failing test(s) test_divide …"
resume	task_id, suggested tool + args, whether the session can be reused, worktree path, branch, base commit
context	worker summary, worker request, remaining concerns, diffstat, diff_path, previous attempts
notes, history, updated_at, updated_by	edits by the supervisor or a human

Parked status needs_approval. A task parks when the worker reports needs_approval or needs_input, or reports blocked with a needs: request or after blocked tool calls. The verdict stays blocked. No worker process runs. task_status returns terminal: true, parked: true, so existing pollers stop. Retention keeps the worktree unless retention.parked_days is set. With it set, an expired parked task loses its worktree (the diff is archived) and is closed. continue_task works on parked tasks.

New MCP tools

• update_handoff(task_id, state?, owner?, next_action?, note?, by?). Setting state needs_approval or needs_input parks a finished task. Any other state unparks it.
• approve_task(task_id, decision: approve|reject, instructions?, note?, timeout_minutes?, profile?, by?). approve resumes the task through the continue path: same worktree, and the same session when the backend matches, with the approval noted. reject closes the task (status cancelled, worktree kept), or redirects it when you pass instructions. Approval does not lift sandbox rules.
• list_tasks: new filters status: "needs_attention" (parked tasks plus handoffs that are not done or closed) and status: "parked", and a new owner filter.

CLI: workhorse handoff <id> [--state --owner --next --note --by], workhorse approve <id>, workhorse reject <id>, workhorse attention, workhorse tasks --status/--owner, workhorse cleanup-old --parked-days N.

Also in this PR

• Worker contract: RESULT statuses needs_approval and needs_input, plus an optional needs: line.
• test_results.failing_tests is filled when tests fail.
• health_report adds parked_tasks, oldest_parked_days and needs_attention.
• Audit events: parked, handoff_updated, approval, closed.
• cancel_task or cleanup_task on a parked task closes it.
• Docs: new docs/handoff.md, plus updates to architecture, configuration, security, troubleshooting, README and the delegation skill draft.
• CHANGELOG: 0.2.0 (Unreleased). package.json is now 0.2.0.

Compatibility

• Existing statuses, verdicts and MCP tool arguments are unchanged. A parked task's verdict is the existing blocked.
• Behavior change: a worker that reports blocked with a concrete request or after blocked tool calls used to end as completed + blocked. It now ends as needs_approval + blocked. Without either, it still ends as completed.
• list_tasks status: "terminal" now also includes parked tasks, since no worker is running.
• Tasks finished before 0.2.0 get a handoff derived on the fly when asked.

Tests

• npm test (local, Kilo CLI + bwrap + mock LLM): 76 tests, 75 pass, 0 fail, 1 skipped (the live test). Before this PR: 53 pass, 1 skipped.
• npm run test:unit: 47 pass. This now includes test/handoff.test.mjs (derivation for each verdict, parsing, failing-test extraction) and test/handoff-flow.test.mjs (a Manager-level flow that needs no backend CLI, so it runs in CI: parking, filters, retention, approve and reject, update_handoff, persistence across restart, legacy tasks).
• A new mock-LLM integration test covers needs_approval → update_handoff → approve_task → resume in the same session → done. The escape test now also asserts that the task parks.