ch10 phase 5: TaskStop typed dispatch via stop_task() helper

[ericleepi314]

Summary

Phase 5 — SRP cleanup hoist. The TaskStop tool layer becomes a thin formatter; dispatch logic moves to a typed helper.

• New: src/tasks/stop_task.py — stop_task(task_id, context, *, reason="") async helper. Three dispatch branches in priority order:
  1. Typed runtime_tasks lookup → get_task_by_type(state.type).kill() bounded by asyncio.wait_for(timeout=5.0).
  2. Legacy task_manager ManagedTask fallback (carries forward the Phase-0 sub-fix; documented for Phase-11 backlog removal).
  3. Not-found.
• StopTaskResult and StopTaskError are frozen dataclasses; is_error is a derived property. Return-value path (not raised exceptions), matching TS.
• StopTaskErrorCode literal includes the chapter's three codes (not_found / not_running / unsupported_type) plus kill_timeout — a Python-specific extension covering the async-kill timeout case (TS kills are sync and never time out, so the code didn't exist there). Mapping the timeout to any of the chapter's three codes would lie about the failure mode.
• _task_stop_call shrinks from ~135 lines to ~30 lines, of which one is the dispatch call: result = await stop_task(...). The rest is schema validation + output formatting.
• The Phase-0 task_manager legacy branch is folded into stop_task(); legacy TestTaskStopTool::test_task_stop now passes for the right reason via typed dispatch.
• The legacy background_bash_tasks direct-read fallback is dropped — production bash tasks are reachable via the lockstep mirror; only test fixtures needed migration.

14 new tests in tests/tasks/test_stop_task.py, including an M1 regression test (kill_timeout) that asserts the timeout path returns is_error=True instead of silently claiming success.

Stacked PR. Base: feat/ch10-coordination-phase3-4. Merge after the Phase 3+4 PR.

Test plan

• _task_stop_call body is one dispatch line + ~30 lines formatting
• All three TS-canonical error codes round-trip through dedicated tests
• Phase-0 task_manager legacy branch folded into stop_task(); legacy test still passes via typed dispatch
• M1 timeout regression preserved (renamed test, behavior identical)
• All Phase 0-3+4 tests still green

[agentforce314]

Approving — clean SRP-cleanup refactor.

What I checked

• _task_stop_call shrinking from ~135 lines to ~30 lines (one of which is the dispatch call) is the textbook outcome of hoisting business logic out of a tool layer. The remaining ~30 lines really should be schema validation + output formatting only.
• The three-branch dispatch order (typed runtime_tasks → legacy task_manager fallback → not-found) is the right priority. Documenting the legacy branch for Phase-11 backlog removal — rather than hiding it — is the right call.
• StopTaskResult / StopTaskError as frozen dataclasses with is_error as a derived property avoids the "two fields that can disagree" failure mode.

The kill_timeout divergence is well-justified

• TS kills are sync and never time out, so the code didn't exist there. Mapping the timeout to not_found / not_running / unsupported_type would lie about the failure mode — losing the ability for callers to distinguish "agent didn't respond" from "agent doesn't exist." Adding a fourth literal that doesn't exist in TS is the right call here.
• The M1 regression test (kill_timeout returns is_error=True rather than silently claiming success) is exactly the test that needs to exist for this divergence.

Nit (non-blocking)

• The asyncio.wait_for(timeout=5.0) constant should probably be a module-level named constant (e.g. _KILL_TIMEOUT_SECONDS = 5.0) — easier to find / tune later.