[DJProspero1]

Problem

A Claude Code CLI conversation should be able to continue in T3 with its full message, tool, reasoning and subagent history. Importing a transcript while the CLI still owns the conversation does not safely transfer control.

Change

Add t3 thread attach SESSION --project PROJECT and t3 thread handoff THREAD_ID, backed by one service exposed through the existing MCP toolkit.

• If the source CLI is running, ask whether to wait for it and its agents to exit or interrupt them. Waiting is the default; unattended callers must select a policy when the source is running. Ctrl+C cancels waiting without stopping the source.
• On Linux, explicit interruption verifies the source PID/start identity and owned descendants before stopping them. Other platforms support waiting for the source to exit.
• Once the source stops, import complete root and child records, keep imported history before subsequent managed runs, and resume the exact native Claude transcript through the existing adapter.
• After interruption, commit one continuation effect with the completed handoff. The existing outbox and effect worker deliver T3's interrupted-work prompt with retries and command deduplication.
• Preserve old subagents as history. Their processes are not restored; resumed work must inspect and restart unfinished tasks. New work uses T3's normal streaming, approvals and agent controls.

The contracts, CLI/MCP handlers, import service, persistence guards, ordering and adapter changes all support this transfer. Import cursors use the existing runtime repository; process verification reuses the ACP implementation through a shared module. The user guide explains the commands and platform limits.

This is a Claude-only handoff. It does not provide simultaneous CLI/T3 control, live-follow while waiting, or attachment for other providers. It introduces no database migrations, updater changes or web/mobile controls.

Scope and approval

Upstream approval is pending. This fork draft is not yet eligible for upstream submission.

CONTRIBUTING.md requires explicit maintainer approval of feature direction and scope, including draft PRs. This adds a workflow and does not qualify as a small bug fix or configuration-only exception. The fork owner's authorization and vouch:trusted label do not supply upstream approval.

Maintainer guidance on an earlier teleport proposal calls for a smaller product decision and staged implementation. That comment is context, not approval of this proposal. The proposed scope here is one-way Claude handoff; shared control and other providers are excluded.

Related requests include continuing a terminal conversation in T3 and continuing Claude Code threads. The full research index below is background, not a claim that this PR resolves every linked report.

Related reports and prior implementations

Research references collected on 2026-11-02. These are non-closing links; status is intentionally omitted. No automatic issue-closing keywords are used.

Direct requests and sync proposals (11)

• Issue #25518: [Feature]: Live read-only view of agent sessions running outside T3 (tmux / CLI), with take-over
• Issue #2863: [Feature]: Bidirectional communication with Claude Code session
• Issue #207: request: import or recreate sessions from Codex
• Issue #3881: [Feature]: Load all session in t3code within a project , even if it's opened via cli
• Issue #4519: [Bug]: Opened a folder I'd previously used Claude Code inside, tried typing /resume - nothing happens - cannot resume
• Issue #5346: Resume Claude Code sessions that weren't started in T3
• Issue #5358: [Feature]: continue threads from claude code
• Issue #6590: [Feature]: First-class interop/sync between T3 threads and local Claude Code CLI sessions
• Issue #9865: /resume does not surface Claude CLI sessions despite #6590
• Issue #15234: [Feature]: Continue a Codex or Claude Code session started in the terminal as a T3 Code thread
• Issue #7748: [Feature]: Auto-import Codex conversations created outside T3 Code

Implementations and import entry points (18)

• PR #4617: feat(orchestration): import an existing Claude Code or Codex session by ID
• PR #5499: feat(orchestration-v2): import an existing Claude Code or Codex session by id, with two-way transcript sync
• PR #5146: feat(codex): import existing sessions
• PR #5741: feat(codex): sync persisted threads into T3
• PR #7135: Draft: teleport backend — import/export engine
• PR #7136: Draft: two-way teleport with native CLI sessions
• PR #8357: Two-way teleport with native CLI sessions
• PR #5362: feat(web): first-run welcome wizard with agent setup and project import
• PR #8066: feat(web): import recent Codex and Claude threads during onboarding
• PR #10386: feat(web): auto-reconcile external agent sessions on project open
• PR #10631: feat(web): import individual Claude sessions from a project
• PR #10969: feat(web): auto-reconcile external agent sessions on project open
• PR #11453: feat(server): import Claude Code and Codex history automatically
• PR #13961: feat: resume external CLI sessions from new threads
• PR #25476: feat(server): support recoverable Codex and Claude session handoff
• PR #22411: fix(web): import Claude Code and Codex sessions after onboarding
• PR #27358: feat(web): import projects from Claude Code and Codex in Settings
• PR #8054: feat(codex): import conversations created outside T3 Code

Import correctness and history problems (28)

• Issue #10961: [Bug]: Session import is unreachable after onboarding, so externally started sessions can never be imported
• Issue #10933: Imported agent sessions duplicate T3-native threads: import dedup never consults the native thread namespace
• PR #10950: fix(server): skip imports of native agent sessions
• PR #15634: fix(server): skip native sessions during bulk import
• Issue #15243: [Bug]: Imported Claude Code threads fail on their first follow-up with "Session ID … is already in use"
• PR #15376: fix(server): imported Claude Code sessions resume on their first follow-up
• PR #23219: fix(server): imported Claude sessions resume on their first turn
• PR #15495: fix(server): a restart no longer resends imported history to a session that already has it
• Issue #12276: [Bug]: Imported Claude Code threads drop the user's renamed title (custom-title / customTitle)
• PR #12292: fix(server): keep Claude renames when importing sessions
• Issue #16222: [Bug]: Session import turns every Codex subagent into its own top-level thread
• PR #16662: fix(server): session import skips Codex subagent sessions
• Issue #17236: Claude thread loses context and cannot fork after its provider association moves to an imported thread
• Issue #17484: [Bug]: Shared import record limit skips valid conversations
• PR #19161: fix(server): import long Claude sessions that are mostly tool records
• Issue #21755: Session import ignores compressed Codex rollouts (.jsonl.zst), so their conversations are never discovered
• Issue #24067: [Bug]: Initial import misses or misgroups conversations and exposes raw internal records on Windows
• PR #25923: fix(server): imported Codex and Claude history no longer shows internal records
• Issue #27163: Session import scan stops at a fixed 64 MiB metadata budget, so the oldest sessions can never be imported
• PR #27215: fix(server): repeated session imports reach transcripts behind the scan budget
• Issue #27580: [Bug]: Imported Claude/Codex threads are silently truncated to the last 200 messages
• Issue #27581: [Bug]: Session import silently skips many sessions (30-day window, excluded folders) and cannot be re-run or refreshed
• Issue #29153: [Bug]: Claude Code session import skips long sessions (transcript over 32 MiB memory budget)
• PR #29183: fix(server): long Claude sessions import instead of being skipped
• Issue #14838: [Bug]: Session scanner marks a replaced transcript as already imported on Windows
• Issue #23727: [Bug]: Session import offers T3 Code's own scratch folders as projects when the T3 home is a symlink
• PR #23728: fix(server): session import skips T3 Code's own folders behind a symlinked home
• PR #23801: fix(server): session import skips scratch folders behind symlinked T3 home

Related subagent lifecycle and status problems (31)

• Issue #28331: [Bug]: Claude subagents carried over from an earlier process stay Running forever, and subagent.stop cannot clear them
• PR #28356: fix(server): Claude subagents left by a stopped process no longer stay Running
• PR #27487: fix(server): background subagents stop showing as running after their Claude session is released
• Issue #22279: [Bug]: Claude background subagent completion is overwritten by a late 'running' update, and Stop/cancel can't settle it
• Issue #17099: [Bug]: Claude background subagents stay Running forever when their wake continuation runs on another provider
• Issue #16355: [Bug]: Nested Claude subagent stays Running after the SDK reports it completed during a user turn
• Issue #19440: [Bug]: A background Claude subagent stays running forever when the Claude process exits while its parent is idle
• Issue #17809: [Bug]: Claude background subagents stay Running after their completion wake on the same provider
• Issue #18910: Claude background subagent stays Running in Lineage for hours after its task_notification reports completed
• Issue #19993: [Bug]: Nested Claude subagents stay Running in the UI after their parent subagent hits the usage limit, while the thread list reports them idle
• Issue #22033: Claude wake latch: a wake queued behind a held run swallows later wakes, so idle-launched subagents stay Running
• Issue #24337: Claude background subagents still stay Running after their completion arrives in a wake continuation (0.1.2, follow-up to #17809)
• Issue #17154: [Bug]: Cancelling a delegated task leaves its Claude native subagents running forever (task stuck waiting_for_children)
• Issue #18646: [Bug]: After a server restart, Claude background subagents keep running and billing while the thread is told they were cancelled
• Issue #13400: Restart continuation skips threads whose turn ended while Claude subagents or background shells were still running
• Issue #14802: [Bug]: Agents panel keeps a finished Claude subagent as running, or interrupted, after the thread's process restarts
• Issue #20430: [Bug]: A held queued continuation run jams the Claude adapter's continuation gate: later wakes are swallowed, wake-turn output is never recorded, and background subagents stay Running
• PR #23831: fix(server): show self-resumed Claude subagents as running
• PR #21327: fix(server): Claude subagents stopped by a replaced session no longer stay Running
• PR #18967: fix(server): Claude subagents stopped by a replaced session no longer stay Running
• PR #16814: fix(server): Claude subagents from a closed process no longer stay running
• PR #13730: fix(server): finished Claude subagents leave no running rows
• Issue #16000: [Bug]: Runtime-mode, instance and worktree changes detach the Claude session and kill live subagents without the background-work check
• Issue #12694: [Bug]: Claude session replacement suppresses exit and silently stops live subagent tasks
• PR #13080: fix(server): do not replace Claude session while live tasks run
• PR #12723: fix(server): do not replace Claude session while live tasks run
• Issue #29319: [Bug]: Claude background subagents die when T3 restarts the session after auto-compaction or idle, then show as "stopped by the user"
• Issue #18877: [Bug]: Stopped Claude tasks still stay Running after session replacement following #18778
• Issue #16484: [Bug]: A background Claude subagent's thread and card stop updating when the parent's turn ends, and its work appears only after it finishes
• Issue #17486: [Bug]: Subagent failure notification keeps a red Failed badge while the resumed subagent runs
• Issue #24222: [Bug]: After a restart, an old Claude process keeps running with parent PID 1 beside a new one resuming the same session

Adjacent mechanisms, not equivalent to live Claude attachment (7)

• PR #4666: Resume Claude Code sessions + Remote Control support
• PR #2999: feat(server): multi-instance support + Claude Remote Control launch
• PR #6475: feat(terminals): add observable tmux sessions
• Issue #22015: [Bug]: Imported ACP sessions never show history or root-session output outside a T3 turn
• PR #22155: fix(server): imported ACP sessions show their native history
• Issue #15644: Manage Cursor, Codex, and Claude cloud sessions from inside T3
• Issue #5699: [Feature]: Append attributed external-agent messages without starting a provider turn

Discussions (7)

• Discussion #6873: Continue threads from Claude Code
• Discussion #25673: Live read-only view of external sessions, with takeover
• Discussion #6994: First-class interop/sync with local Claude CLI sessions
• Discussion #6680: Import or recreate sessions from Codex
• Discussion #7023: Resume Claude sessions not started in T3
• Discussion #14511: Related external-session continuation proposal
• Discussion #11697: Re-scan / re-import CLI conversations for existing projects

Verification

The original verification below applies to 90b5d7d948b48567463a86fd04945aa9185a96b0, based on upstream cefb544af3c9. The current head is 7adb470f02b4cde3384596850eabf153df41d69d.

An official-update compatibility defect was found in a previously deployed build: timestamp-sized imported positions sorted after newly allocated native run positions. The importer now uses T3's unchanged position allocator. The handoff regression asserts imported items occupy the normal history range. vp run check:changed HEAD --concurrency 2 passed before this fix was committed: formatting, lint, both Knip passes, GraphQL generation, typechecks for three packages, and four tests across three files. Existing histories written by the experimental builds require a separate data repair; changing the importer does not repair those stored positions.

The recorded local run of vp run check:changed HEAD --concurrency 2 before committing passed formatting, lint, both Knip passes, dependency-patch validation, GraphQL generation, typechecks for 40 affected packages, and 630 tests across 16 files. Its saved output was checked again during this description audit; tests were not rerun for this metadata-only update.

Focused coverage and observed results:

• CLI wait/interrupt selection and cancellation; blocked handoff leaves the source running. An isolated real Linux parent/child fixture verifies that interruption stops only the verified owned process tree.
• Complete import of large 26 MiB records; partial UTF-8, replaced files and symlink escapes; preservation of human text, tool/reasoning records, child lineage and settled statuses.
• Cursor retries retain model and workspace metadata. The existing adapter test resumes the exact transcript even when its original checkout directory has been deleted.
• Forced outbox insertion failure rolls back handoff completion. Recovery reclaims an abandoned continuation; draining the effect worker twice sends one continuation. Retried handoff preserves an already-managed runtime, including after history compaction.
• New imports use the existing no-run history range, and subsequent managed runs use the normal run ranges. No custom ordering behavior is required in later official releases.

A read-only merge simulation against upstream 3d369d5596 completed without conflicts, and git diff --check passed. This does not replace validation after updating the branch.

Not verified: an end-to-end CLI-to-T3 run of this optimized head on either Linux or Windows. The deployed machines still use the earlier build, so their behavior is not evidence for this head. The MCP model-evaluation case is present but has not been run. No GitHub CI or paid model evaluation was started for this audit. No web/mobile UI code changes, screenshots or recordings are included.

Implemented with GPT-6 Astra through the Codex harness in T3 Code. Architectural review by Opus 5.5 through Claude Code.