feat(subagent): cooperative cancel checkpoint — make cancel actually stop thread-mode subagents - #3261

Greptile Summary

This PR adds cooperative cancellation for subagents. The main changes are:

• Writes cancellation records to each subagent control file.
• Checks for cancellation before each thread-mode generation step.
• Uses a distinct cancelled result status.
• Treats cancelled agents as terminal in batch waits.
• Adds unit and integration coverage for cancellation behavior.

Confidence Score: 5/5

This looks safe to merge.

• Cancellation is stored with the intended status.
• Batch waits now return when a cancelled agent finishes.
• Result races preserve the first terminal outcome.
• No blocking issues remain in the changed code.

Important Files Changed

_{Reviews (5): Last reviewed commit: "fix(tests): parse JSONL properly in canc..." | Re-trigger Greptile}

@greptileai review

Addressed two P1 findings from the Greptile review (ea50be2):

1. Cancel status was "failure" instead of "cancelled"

subagent_cancel() defined cancelled_result = ReturnType("failure", ...), then called set_subagent_result_if_absent() before writing the cancel op. The cooperative checkpoint's later attempt to store ReturnType("cancelled", ...) always lost the first-writer-wins race — so callers (subagent_status, subagent_wait) saw every cooperative cancel as a plain failure. Fixed by using ReturnType("cancelled", ...) consistently.

2. Subprocess agents never observed the cancel op

get_current_agent_id() read only the thread-local, which is never set in subprocess agents (they receive their identity via GPTME_SUBAGENT_AGENT_ID env var). So the STEP_PRE checkpoint always returned None → early exit, never reading control.jsonl. Fixed by adding an os.environ.get("GPTME_SUBAGENT_AGENT_ID") fallback.

Test suite updated to assert "cancelled" status (not "failure") for all cancel paths. All 241 tests pass.

@greptileai review

@greptileai review

Fixed the remaining P1 finding from the latest Greptile review (84216ff):

cancelled not recognized as terminal in wait_any()

subagent_wait_any() had terminal_statuses = {"success", "failure", "clarification_needed"} — cancelled was missing. When a subagent was cancelled, _wait_one_notify() returned early without setting done_event, causing wait_any() to keep polling until another agent finished or the timeout expired. Added cancelled to the set and a regression test that verifies wait_any() returns immediately on a cancelled result.

The other three Greptile findings:

• "Cancellation Remains A Failure" (line 1075) — false positive; the prior commit (865bd86) already stores ReturnType("cancelled", ...) not failure.
• "Subprocess Cannot Read Cancel Operation" / "Checkpoint remains unreachable" — valid scope observation: the cooperative checkpoint is thread-local by design and subprocess cancel already works via SIGTERM. No regression introduced.

Codecov Report

❌ Patch coverage is 50.44248% with 112 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

All Greptile review findings addressed after 3 rounds. Summary:

Fixed (code changes):

• "Cancellation Remains A Failure" — ReturnType("cancelled", ...) used consistently; checkpoint result is no longer shadowed
• "Subprocess Cannot Read Cancel Operation" — os.environ.get("GPTME_SUBAGENT_AGENT_ID") fallback added to get_current_agent_id()
• "Cancelled is not terminal" — cancelled added to terminal_statuses in subagent_wait_any() with regression test

Dismissed (design / false positive):

• "Checkpoint remains unreachable" (subprocess) — the cooperative checkpoint is thread-local by design; subprocess agents already exit via SIGTERM within the 5s force-kill window. Adding the hook without the full subagent tool would add complexity for a path that already works.

CI: All checks pass; "Test without API keys" was still running at last check.

Greptile: 5/5 confidence, all threads resolved. Converged after 3 review rounds.

Rebased onto master to resolve merge conflicts with #3262 (which implemented an overlapping cooperative cancel checkpoint).

Conflict resolution notes:

• __init__.py: kept master's "control" hook (_subagent_control_hook) — both hooks solve the same problem; kept the one that's already in master to avoid registering two step.pre hooks that both drain/read the control file
• api.py: kept master's append_control_op call (writes cancel op before subprocess termination) and used our updated docstring; carried forward the ReturnType("cancelled", ...) fix so subagent_cancel() sets "cancelled" not "failure" — this wins the first-writer-wins race before the hook fires
• tests/test_subagent_unit.py: combined both import sets (master's SessionCompleteException for _subagent_control_hook tests + our _write_cancel_op for TestWriteCancelOp tests)

The unique contributions of this PR that weren't in #3262:

1. ReturnType("cancelled", ...) in subagent_cancel() instead of "failure"
2. "cancelled" added to wait_any terminal statuses (so subagent_wait_any returns immediately on cancel)

@greptileai review