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	handoff into a fresh Cursor agent. The SDK has in-process custom callback tools, but the V2 adapter	35	handoff into a fresh Cursor agent. The SDK has in-process custom callback tools, but the V2 adapter
36	intentionally uses the authenticated, thread-scoped MCP server instead.	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	Cursor task events include an `agentId`, but the local SDK does not register that identifier as a	42	Cursor task events include an `agentId`, but the local SDK does not register that identifier as a
39	resumable agent: `Agent.resume()` returns `AgentNotFoundError`. The adapter therefore does not attach	43	resumable agent: `Agent.resume()` returns `AgentNotFoundError`. The adapter therefore does not attach
40	a provider thread to native task projections or advertise subagent thread IDs. Sending a new message	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.