docs(specs): agent handoffs and consults for mid-thread @-mentions

[philmerrell]

Summary

Draft spec: docs/specs/agent-handoffs-and-consults.md. Docs only, no code changes.

Since #1115, an @-mention in a thread that already has messages opens a new conversation with the Agent. That protects the thread's history and prompt cache, but the Agent starts with no context ("draft a rubric for this"). The spec covers that gap in two phases.

Phase 0: task chips (useful on its own, and the measurement for Phase 1)

• 0a Handoff with context. A mid-thread mention opens the Agent's conversation with a context card: a deterministic, size-capped excerpt of the old thread, rendered server-side, that the user can review, edit or remove before sending.
• 0b Send back. "Send to original conversation" on replies in a spawned conversation. It only appends to the original thread, so that thread's cached prompt is untouched.
• 0c Suggested tasks. A non-blocking suggest_task tool with a fixed definition (no list of Agents, so pin changes don't bust the cache). It is rate-limited and opt-in.

The gate (§7). Six weeks of Phase 0 counts (handoffs, edits to the context card, send-backs) decide whether Phase 1 gets built.

Phase 1: consults. An @-mentioned Agent runs in place in its own hidden session, before the main agent, and a size-capped report is appended to the user's message. Pauses (OAuth consent, tool approval, questions, sign-in) end the consult instead of resuming in v1.

Both phases are designed around the three failures of the removed one-turn borrow: the split history (#741/#751), the full re-cache of the thread's prompt, and tools silently disappearing on the next turn.

Review asks

• §7 gate thresholds are placeholders. They should be agreed before Phase 0 ships.
• §12 open questions, especially Q2 (sending the handoff immediately vs. letting the user review the context first) and Q3 (a consult "direct mode" that skips the main agent's reply).

Test plan

• Spec review only; no code or tests in this PR.

🤖 Generated with Claude Code