feat(stop): use agent.cancel() to stop the event loop

[Unshure]

Summary

Proposal to unify the different agent cancellation strategies within the sdk around agent.cancel. This will be used for moving the stop tool out of experimental, and used to stop the bidi agent.

[github-actions]

Assessment: Comment

The design is well-structured and follows the template — the Problem/Current State is accurate (I verified stop_event_loop at event_loop.py:842 and the TS WeakSet + AfterToolsEvent.endTurn marker pattern both exist as described), and it weighs real alternatives. The main blockers are a PR-framing mismatch and a couple of open decisions the doc leaves unresolved.

Review themes

• PR framing vs. content: The title (feat(stop):) and description describe completed Python/TS code changes with passing test counts (16/16, 17/17), but the actual diff is a single Proposed design doc. Per team/designs/README.md, a design is merged first, then implemented in a separate PR that references it. Recommend reframing this as docs(design): (proposal only) so reviewers and git history aren't misled.
• Unresolved decisions: The composability policy is listed as a goal but never chosen, and the TS implementation path is left as an "actually, a simpler way…" aside rather than a committed decision. Both should be resolved before approval (inline).
• Core API decision: Overloading cancel() for a cooperative stop sits in tension with the doc's own argument that cancel() is an aggressive abort — worth a stronger justification against the dedicated-method alternative (inline).
• Scope gap: Behavior under the concurrent tool executor isn't addressed; examples assume sequential (inline).
• Nits: future date (2026-07-27) and Issue: TBD.

Solid proposal overall — resolving the open policy/decision questions would make it straightforward to approve.

[mehtarac]

@strandly-the-agent do a fresh review of this PR

[mehtarac]

Is this ready for review? just curious

[github-actions]

Assessment: Comment

Fresh review as requested (@mehtarac). The doc has improved substantially since the last pass — it's tighter, retitled to Unified Agent Cancellation, and the earlier open items are resolved: the composability policy is now decided (last-write-wins, with rationale), the TS implementation path commits to a choice (option (a) preferred), and the PR description no longer claims completed code. I also confirmed the proposal is backward-compatible — today's cancel() takes no args in both SDKs (agent.py:604, agent.ts:1045), so adding optional params doesn't break existing callers.

Remaining items (all minor)

• Template header: **Status** and **Issue** fields were dropped — only **Date** remains, and the date is a future value (2026-07-27). (inline)
• Cross-SDK signature shape: Python takes message positionally while TS uses an options bag; for a doc about a unified API this divergence is worth either aligning or justifying, plus a TS example in the DX section. (inline)
• Nit: filename slug (0019-deferred-cancel.md) no longer matches the new title.

Strong proposal — cleaning up the header fields and the cross-SDK signature note would make this ready to approve.

[Unshure]

@strandly-the-agent can you help create a pull request for this design?

[strandly-the-agent]

@Unshure done — two draft PRs, one per SDK (per the repo's one-sub-project-per-PR rule):

• Python: feat(stop): use agent.cancel() to stop the event loop (Python) #4833 — Agent.cancel(message=None, *, after_current_tools=False), stop tool becomes the one-liner, stop_event_loop removed. ruff/mypy clean, 7363 tests pass.
• TypeScript: feat(stop): use agent.cancel() to stop the event loop (TypeScript) #4834 — agent.cancel({ message, afterCurrentTools }), STOP_INVOCATION_STATE_KEY + the WeakSet/hook install removed, site docs updated. tsc/eslint clean, 4803 tests pass (2 telemetry failures are my sandbox's OTEL env, not the change).

One thing worth your call before merging, flagged in both bodies: agent-as-tool maps a sub-agent's cancelled result to an error tool result (_agent_as_tool.py:252, agent-as-tool.ts:215), so a sub-agent that ends via stop now reports an error to its parent where it previously returned its content. That's the stop-reason-override question liramon2 raised; I left it as-is rather than guess.

Other scope notes

• message becomes the final assistant message on every cancel exit (streaming, pre-tools, post-batch) in both SDKs; omitted keeps today's behaviour. Last write wins.
• Python LocalAgent protocol and BidiAgent.cancel() are unchanged (Agent widens compatibly); bidi is the follow-up the design mentions.
• My independent review subagent timed out, so the PRs carry my self-review only — please read with that in mind.