[FEATURE] Peer-requested context reset: let one session hand a collaborator a clean context and a continuation prompt

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

The agent-invokable compaction family is well covered and I am not filing against it: #63807 (consolidation plus a Compact tool proposal), #71803, #78165, #19877, #18027. Those all ask an agent to summarize its own context. This asks for a reset requested by a peer. I found nothing covering the cross-session case.

Problem Statement

I run long multi-session work where a coordinator drives several named sessions over SendMessage. Each collaborator accumulates context it no longer needs: exploration that dead-ended, tool output already acted on, a finished phase already written to a state file.

The coordinator knows when a collaborator is done with a phase. The collaborator cannot act on that. /clear and /compact come from a human keystroke or from the harness hitting a token threshold, and a peer message cannot carry either. Verified against the 2.1.236 bundle: the SendMessage delivery path enqueues {mode:"prompt", origin:{kind:"peer", …}, skipSlashCommands:true, isMeta:true}, and the gate is if (e.skipSlashCommands && PCn(e.origin)) return false, where PCn(e) is e?.kind === "peer" || e?.kind === "slack-ping". Peer-delivered slash commands are refused by name.

That gate looks intentional and I am not asking to widen it. A peer must not be able to run privileged commands in my session.

So the only way to give a collaborator a clean context is to kill it and spawn a replacement. For a throwaway subagent that is the right answer. For a long-lived session it costs three things a reset would not: the prompt cache dies with the process, so the replacement re-prefills from zero, compute-bound and superlinear in history length (see @schoggie in #63807 on 700k-token re-prefills); anything the session had not yet written down is lost, so every collaborator needs a checkpoint discipline purely to survive its own restart; and the coordinator has to rebuild the replacement's addressing, cwd, and mode.

Proposed Solution

A context reset that a peer can request, delivered through the existing cross-session consent path rather than the slash-command path.

• The coordinator asks a named session to reset and passes a continuation prompt as data. It becomes the recipient's next user turn and is never parsed as a command.
• Delivery reuses what already exists for peer messages: that path runs E9n(d) !== "accept" before enqueueing, and held / denied / expired / delivered states already surface to the user. A reset request is one more thing that pipeline can hold or deny.
• Opt-in per recipient, off by default, so no session is resettable by a peer unless its owner allowed it.
• The recipient's own hooks fire first, so a PreCompact-style hook can flush state before history drops.

Two properties matter more than the exact API. Resetting rather than compacting needs no summarization pass, so nothing bloats the fresh context, nothing waits several minutes (#75837 recorded durationMs: 144075 on a large context), and the outcome is deterministic; the durable state is already on disk in memory and state files, and a summary duplicates it worse. And having a peer decide answers the standing objection to self-compaction, that a degraded agent is judging its own degradation: the coordinator holds the plan and the phase boundary, so it already knows where the safe point is.

Most of the primitive exists. showClearContextOnPlanAccept and the yes-auto-clear-context branch already do clear-history-then-continue-with-this-text at plan approval. This asks to reach that from a second trigger.

Alternative Solutions

Any of these would solve it:

1. A tool the recipient exposes, say ContextReset({continuation}), callable by the session itself and requestable by a peer under the consent gate. It composes with the Compact tool in #63807: reset and compact are the two ends of one control.
2. A reset verb on SendMessage, typed rather than free text, so it cannot be confused with a prompt.
3. A recipient-side hook that can answer an inbound peer message with "reset before you handle this".

I am deliberately not asking for peer messages to reach the slash parser. That is the PCn gate and it should stay shut.

What I do today: the coordinator writes a checkpoint file, TaskStops the collaborator, and spawns a fresh one pointed at the file. The results are correct and it pays a full re-prefill every time.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

A coordinator drives three sessions through a five-phase migration. Session B finishes phase 2, writes its findings to a state file, and its context is now mostly phase-2 residue. The coordinator sends a reset whose continuation is "Phase 3: apply the transform to the sites listed in state/phase2.md. Read that file first." B's hook flushes, history drops, and B picks up phase 3 clean, same identity and cwd.

That last step does not exist today. The coordinator either lets B run until auto-compact fires mid-phase, or kills B and rebuilds a replacement.

Additional Context

Read out of the shipped 2.1.236 binary rather than inferred from docs:

| Injection path | skipSlashCommands |
|---|---|
| Human keystrokes | unset |
| Peer message (uds-messaging) | true, origin.kind === "peer" |
| Observer report, peer-idle notice, SendMessage-to-main | true |
| MCP channel message | true |
| Auto-continuation | true |
| Cron / ScheduleWakeup fire | true, no origin set |

Every non-human path sets it. Only the peer and slack-ping origins are gated by PCn, and the peer path sets both, so this is a closed door and not an oversight.