docs: state portable handoff limits

Explain the eligible timeline items, whitespace-normalized 240-character prefixes, omitted tail risk, and practical preparation for provider or fork handoffs. Distinguish this rule from the legacy import's 32,000-character transcript suffix. Audit: D04 Written by GPT-5.6 Sol with Codex.

Julius Marminge committed 2 months ago

Commit 01fb9b21 parent b9918343 files · +42 −0Browse files

Unified · Split

3 files

docs/internals/context-handoffs.md +19 −0
docs/user/cursor.md +4 −0
docs/user/portable-handoffs.md +19 −0

docs/internals/context-handoffs.md+19−0

@@ -0,0 +1,19 @@
	1	+# Context handoffs
	2	+
	3	+Portable provider and fork handoffs are textual summaries. They do not claim native provider context
	4	+parity.
	5	+
	6	+`ContextHandoffServiceV2` includes user messages, assistant messages, command executions, file
	7	+changes, checkpoints, and prior handoffs. It skips other turn item types. For text-bearing items,
	8	+`compactText` replaces every whitespace run with one space, trims the result, and returns at most
	9	+240 characters. A truncated value contains the first 237 characters followed by `...`. File changes
	10	+carry the filename, while checkpoints carry only the number of files.
	11	+
	12	+Provider handoffs use either the full eligible app history or the delta since that provider last
	13	+participated. Fork merge-back handoffs summarize eligible delta items from the child. Neither path
	14	+reconstructs provider-native session state, tool state, approvals, or omitted text.
	15	+
	16	+Legacy v1 continuation uses a separate algorithm. It considers only user and assistant messages,
	17	+walks backward from the newest message, and builds a transcript suffix within a 32,000-character
	18	+budget. Do not describe that migration budget as the limit for portable handoffs, and do not describe
	19	+the 240-character prefix as a migration rule.

docs/user/cursor.md+4−0

@@ -35,6 +35,10 @@ provider turns. Same-provider Cursor forks use the orchestrator's portable full- · 34 unmodified lines
35	35	handoff into a fresh Cursor agent. The SDK has in-process custom callback tools, but the V2 adapter
36	36	intentionally uses the authenticated, thread-scoped MCP server instead.
37	37
	38	+Portable handoffs summarize eligible timeline items and can omit the end of long messages. Read
	39	+[Context in portable handoffs](./portable-handoffs.md) before using a fork for work whose exact
	40	+instructions must carry forward.
	41	+
38	42	Cursor task events include an `agentId`, but the local SDK does not register that identifier as a
39	43	resumable agent: `Agent.resume()` returns `AgentNotFoundError`. The adapter therefore does not attach
40	44	a provider thread to native task projections or advertise subagent thread IDs. Sending a new message

docs/user/portable-handoffs.md+19−0

@@ -0,0 +1,19 @@
	1	+# Context in portable handoffs
	2	+
	3	+T3 Code sometimes starts a fresh provider session instead of resuming a provider's native session.
	4	+This happens when you switch providers, continue through portable restart steering, or use a fork
	5	+that the provider cannot resume itself.
	6	+
	7	+The new provider receives a text handoff. This handoff is useful context, but it is not a copy of
	8	+the original provider session. For each included user message, assistant message, command, or prior
	9	+handoff, T3 Code collapses whitespace and keeps up to 240 characters from the beginning. File
	10	+changes appear by filename, and checkpoints appear with a file count. Other timeline items may not
	11	+appear in the handoff.
	12	+
	13	+Text near the end of a long message can be omitted. Before switching providers or continuing a
	14	+portable fork, put the current goal, hard constraints, and any unresolved failure in a short message.
	15	+You can also paste the exact detail again after the new provider starts.
	16	+
	17	+This 240-character rule is different from migration of older threads. A migrated thread gives its
	18	+first fresh provider session the newest transcript suffix within a separate 32,000-character budget.
	19	+See [Threads from older T3 Code versions](./thread-migration.md) for that migration path.