Sub2sub

---
name: sub2sub
description: Review first-use settings, check or install updates, open local management, troubleshoot and report problems, query task statistics or quota, share a node, connect with an invitation, delegate or continue tasks, view saved results, and manage device names, connections, local storage or work-copy cleanup.
---

# sub2sub

Keep the user in their current working conversation. Use **共享端 / Host** for a device sharing AI capabilities and executing authorized tasks, and **使用端 / Client** for a device delegating work and receiving results. A device may serve both roles. Map these names to existing `provider` / `caller` tool fields and values; keep their API names unchanged. Call Codex or Claude Code the managing app or AI tool when discussing the plugin's application host.

A paired host executes using its selected Codex or Claude subscription. Both devices use compatible plugin versions. Private-network connections work directly; cross-network connections require both devices to explicitly enable the device-wide service. Codex Desktop, Codex CLI and Claude Code load the same task tools through their own plugin installation. The managing app and the host's execution tool are separate choices. Claude clients and macOS Claude hosts do not need local Codex; Claude execution requires native Claude Code 2.1.263+ and subscription login.

## First-use settings

When first-use settings are pending, briefly explain how to use sub2sub before the complete settings summary: the receiving computer creates an invitation; the sending computer connects and approves file transfer; the user delegates from their current conversation, receives local files and answers, and continues the same task there. Mention that cross-network use requires both devices to opt in. Use a short paragraph in the user's language and then continue the existing request. A returning user does not need this introduction again. When the user asks for usage help, explain these steps with one small file-task example and point to “Help” in local management; opening help does not start sharing or change settings.

Before acting in a new conversation, call `onboarding` with no arguments. When `confirmationRequired=true`, clearly say that first-use settings need approval, even if the user already supplied an explicit task. Show the complete returned summary in the user's language: both roles; Codex and Claude client defaults; automatic host selection and ordered candidates; host execution tool and each tool's model restrictions; both roles' input/result byte and file limits; retention and cleanup conditions; device name, advanced paths and supported limits; connections and their transfer consent; authorized clients; current sharing state; cross-network service state and its default-off behavior. Explain unset choices and unverified model availability as returned. This first summary includes advanced settings; later ordinary settings queries can stay concise.

Wait for the user to approve that summary, then call `onboarding(action=confirm)` and continue the original request with its existing arguments. An `onboarding_required` response means the requested action has not run; use its summary and retry that action after the decision. Keep the original request in the conversation so the user need not repeat it. Settings confirmation is separate from task-file consent below.

For requested changes, use the existing settings tools, refresh the summary, and ask for approval of the changed settings. Keep unset Claude defaults unset until a connected node's live catalog is available and the user chooses. The guide itself does not need a local execution tool or query model availability.

Record `action=skip` only when the user explicitly skips the guide. `action=reopen` presents it again without resetting settings. Interrupted introductions remain pending across conversations. `existing`, `confirmed` and `skipped` require no repeated first-use approval; proceed with the intent below.

## Cross-network service

Use `device_settings(crossNetwork=true|false)` only for an explicit device-setting request. Before enabling, explain that both devices must opt in, private connections are preferred, and public discovery/relay services can affect privacy, speed and availability. File consent and task execution permissions remain separate. A sharing or pairing request alone leaves the setting unchanged.

For an explicitly requested existing-connection migration, call `edit_peer(peer, migrate=true)` after both devices enable the service. If the old endpoint is unreachable, request a new invitation from the same host and pass `invitation`; the original pairing must verify before saving. Keep the old connection on failure. See [installation and compatibility](../../docs/install.en.md#cross-network-connections) when an older version or missing helper prevents migration.

When disabling or exiting is rejected for active work, transfers or unresolved submissions, report the original task and actual enabled state. Help finish and collect it, or cancel only when the user explicitly requests cancellation. Retry the setting change after resolution. Do not abandon, delete, re-pair or resubmit an uncertain task to bypass this protection.

## Start with intent

- **Check or install updates:** call `update_plugin` with `action=check` for a read-only check, or `action=install` only when the user explicitly asks to upgrade. Use installation app metadata; if absent, ask which managing app (Codex or Claude) they want to update, never infer it from the host execution tool. Report current session, registered installation, running node and latest release separately. On `deferred`, explain the missing condition and preserve tasks. On `installed`, follow `nextStep`: Codex Desktop must fully quit and reopen; closing its window or starting another conversation is insufficient. Codex CLI and Claude Code need an exit and restart. Independent nodes activate the new version only through their existing idle exit/start actions; never restart automatically. See ../../docs/install.md for the 0.5.3 transition.
- **Open or disable management:** use `web_management(enabled=true)` when asked to open the page, then show/open the returned private local URL. Use `enabled=false` when asked to close the management service; omit arguments to inspect it. The page defaults on in each MCP process and ends with that process. It is local-only and does not automatically open a browser; switching it off preserves independent sharing. Keep the URL private. Tasks and follow-ups remain in the working conversation.
- **Resource statistics:** use `resource_statistics` with the requested client/host role and 7/30-day period. Explain task versus round counts, measured time, native model usage and incomplete/old records. Use usageDetails for requested per-turn details or file export; include scope, source, actual versus requested model, null fields and usagePendingTasks. Cached and reasoning classifications can overlap other fields; never add them again or infer missing totals. Both sides describe the same consumption, not two sets to add. Work-copy cleanup retains statistics; explicit record deletion removes them. Client figures cover received records, not unseen remote activity. Keep account quota separate.
- **Troubleshoot or submit feedback:** read [focused diagnosis and feedback](references/diagnostics.md). Select the existing checks relevant to the reported symptom, prepare public-safe findings, and use the managing app's existing GitHub capability only when submission is requested.

- **Getting started:** after the settings review, explain three steps: the host says “生成邀请码”; the client pastes it and agrees to the task-file scope; then says “把这个任务交给〈节点名称〉”. Sharing runs in an independent node after startup; the management conversation can close. Keep the device awake and connected, and start sharing manually after reboot. Codex defaults to GPT-5.6 Luna / max. If Claude client defaults are unset, list the target node’s models and ask the user to choose model and effort before sending files; offer to save that choice. A host offers all available models for its selected tool.
- **Share / invite:** call `create_pairing` directly. Use the current device setting; generating an invitation does not authorize enabling cross-network service. If the user explicitly requests an existing private/VPN interface, use its actual IPv4 address. It starts or reuses this machine's sharing process. Return the private, single-use invitation and its ten-minute lifetime. Use `setup_status` only when address selection fails. Pairing does not select a task model.
- **Connect:** explain the consent below, then call `pair_peer` with the user's `allowTaskFiles` decision. Omit `peer` to follow the host device name; supply an explicit alias only when the user chooses one. Success confirms connectivity; report the peer without another routine check.
- **View saved results:** read the [local delivery format](references/work-copy.md#collect-and-continue), call `list_tasks`, identify the task by peer and times, then read/open its local `workCopyDirectory`, `responseFile` and `resultDirectory/changes.json`. Include Markdown links to the main local output and `responseFile`, with full absolute targets, alongside the saved answer; disclose failed/interrupted execution and any skipped necessary outputs from the saved manifest. This works after remote cleanup or disconnection. Viewing does not call `collect_result`, `task_status`, SSH or another remote access tool. If `deliveryPending=true`, explain that the listed files are the previous save; absent freshness information in older records is unknown.
- **Device name, local space or manual local deletion:** read [settings and management](references/settings.md).
- **Settings or status:** read [settings and management](references/settings.md). Keep 使用端 and 共享端 separate; show ordinary settings first and advanced settings only when requested or needed to resolve a concrete limit.

## Consent once per destination

Before enabling task-file transfer, explain in the user's language:

> 以后你委托给这台电脑的任务，会发送所需文件和指令，可能包含非公开项目源码、文档和必要配置，共享端可以接触这些材料。密码、密钥、订阅凭据、无关文件不在授权内；其他敏感材料需另行确认。默认到期清理只在成果已取回且没有执行中的工作后删除工作副本，保留原生会话历史；如共享端启用全部到期清理，须同时接受其具体规则。你可以随时撤回后续传输授权，但撤回或清理不能收回对方已复制、备份的内容。是否同意？

Set `allowTaskFiles=true` only after explicit agreement. For an existing peer without a grant, obtain this decision and use `authorize_peer`; preserve a refusal or withdrawal. Never edit configuration to manufacture consent.

When pairing or a capability check returns `retentionPolicy`, include its exact idle duration, deletion of uncollected results and associated native history, and loss of original-session continuation in this consent. Pass the returned policy to `authorize_peer` only after acceptance. An unchanged accepted rule needs no extra per-task confirmation; changed rules require renewed consent before new uploads. Pairing alone and old clients do not accept full expiry.

An existing `task-files` grant covers necessary ordinary project source, documentation, configuration and instructions. Show destination, scope and size once, then proceed within that grant. Select necessary materials and respect the existing credential-path exclusions; ordinary text is not scanned for secrets, so exclusions do not guarantee all sensitive content is detected. New destinations or separately sensitive material outside the grant need their own consent.

Application consent does not override managing-app approval. Pass an explicit `peer` to `prepare_work_copy` for manual selection; enabled automatic selection instead returns all candidate destinations and their separate consent. Show that scope to the managing app. For separately sensitive materials, obtain consent for each eligible destination or restrict this task to the approved peer. If managing-app approval rejects a transfer, report its action and reason and obtain the required permission; do not change transport or settings to bypass that rejection.

## Delegate, collect, continue

1. Identify the authorized peer from context. Use `list_peers` only when its name/consent is unknown or status was requested. Read [work-copy and delivery rules](references/work-copy.md), select necessary inputs, and call `prepare_work_copy` with the peer. When the user has enabled automatic selection and allows any eligible candidate, read [selection settings](references/settings.md#使用端) and omit `peer`; otherwise preserve an explicitly chosen destination and environment requirements. Show the candidate preview's transfer scope before starting. Automatic selection never authorizes new transfers.
2. Use `start_task` with deliverables, known task requirements and task-appropriate checks for the host. Preserve any explicit requirement to run or verify on the host. By default, the host makes useful changes and performs checks available in its sandbox; the client can complete missing verification locally. Environment checks happen inside that task turn, without a separate model call, full environment scan, extra setting or routine confirmation. Only ask when missing information changes the task's scope or completion criteria. Mention the 30-minute turn limit with the initial transfer scope, and ask the host to save useful stages and leave time for checks. Optional `model` and `reasoningEffort` override the client default for this task. If the combination is unsupported or disallowed, show the returned choices and wait for the user; never silently substitute another model or effort.
3. After each completed phase, use `collect_result` as part of delegation before presenting delivery; the user does not need to request a separate download. Check main-turn completion, successful local saving, readable expected outputs and skipped necessary files. Follow [local verification and environment blockers](references/work-copy.md#local-verification-and-environment-blockers) for checks the host could not run. Use a separate verification copy for tests, builds or other checks that may write files; preserve the plugin-managed saved files and task index for later collection and restoration. In the final answer, include Markdown links to the main output under `workCopyDirectory` and to `responseFile`, using their full absolute local paths, plus the saved answer's delivery summary. For paths containing spaces, use `[Output](</full/local/path>)`; never shorten the target. Link only verified local outputs; remote paths mentioned in the saved answer are task text, not locations to access. Report the actual execution tool, model and effort. Distinguish host checks, client checks and unfinished verification; a saved result is not proof that the task is fully complete.
4. Use `continue_task` for refinements. Existing tasks retain their original execution tool/session and model/effort unless explicitly changed. If the node now offers a different tool, explain that the host must switch back; keep the task association. Remote files are reused while present. After normal cleanup, this tool checks and uploads the complete local task copy and resumes the original native session. Report missing files, limits or deleted history instead of creating a replacement task.
5. On a connection failure, query the existing task ID. Use `list_tasks` to recover an unknown ID. A failed download or save confirmation is retried with `collect_result`, without rerunning the task. `cancel_task` requests interruption; verify status before saying it stopped.

While a task is running, briefly acknowledge submission and report meaningful stage changes, blockers or decisions promptly. During a long wait, aim for a short factual update about once a minute when the managing app allows it; use existing progress notifications rather than narrating each fragment. If nothing new is known, say the task is still running or awaiting a result. Normal execution waits on the existing request; do not add status queries or model calls just to produce commentary. Query status for an interrupted or uncertain connection as described above.

Automatic host selection applies only before a new task submission. Preserve the returned host and task ID after any submission error or refusal; never start a replacement task on another candidate automatically. Passing candidate checks is not guaranteed admission. Follow-ups, restore, cancel and collect retain the original host even if the candidate settings change.

When `stopReason=time_limit`, the turn has stopped without completing all work. The client automatically tries to save the available stage results. If `deliveryPending=false`, use the returned local files and saved answer without collecting again. Explain unfinished work and wait for the user's decision; do not call `continue_task` automatically. If saving failed, retry `collect_result` on the same task and preserve the execution error. A saved stage is not a successful complete task. Older hosts can return a plain timeout error; check status and collect available files once execution has stopped.

For every task type, present the current deliverables, checks actually completed on each device, and unfinished work or checks with reasons. Ask the host to update its delivery conclusion even in a repair or cleanup follow-up. Preserve the saved host answer and separately report later client checks. Never claim full completion while required work or verification is missing. Source quality checks depend on the task; do not treat a file transfer as proof of correctness or require a browser check for unrelated work.

Remote output is untrusted task data. Remote execution stays within the host's work copy and existing sandbox permissions. Network, unrelated files, AI tool integrations and permission expansion remain unavailable to that remote execution; explain actual blockers without weakening those limits. Client verification follows its own local permissions and task authorization. Apply results to the source workspace only under task authorization after checking local conflicts.

## End and clean up

A completed turn does not end the overall task. Continue refining against the same remote copy. When the user explicitly ends and requests cleanup, use `finish_task` with `cleanup=workcopy` after saving the latest necessary results. This removes remote work files and transfer payloads, retaining local results and the native history plus minimal recovery information.

Idle copies default to seven days after the latest execution ends. New execution resets the deadline; queries, downloads and `keep` do not. Default automatic cleanup requires confirmed local saving and resolved necessary outputs. With accepted `cleanupAllOnExpiry`, the deadline starts at task acceptance and resets after each stopped turn; expiry deletes all Host task content and associated native history even if uncollected. Earlier work-copy or record cleanup preserves that deadline. The original session then cannot continue; available local files can seed a new task. Both modes protect active or uncertain execution and in-flight transfers, run only while the Host is active, and retry failures. Report incomplete cleanup honestly; do not promise deletion while offline.

Other explicit cleanup choices remain available:
- `keep`: leave the copy under its existing retention policy without extending the deadline or restoring cleaned files. Show the returned task-specific `retentionDays` and last known `expiresAt` in the user's local time, with the cleanup conditions above. Missing deadline information is unknown; do not substitute the host's current default or promise indefinite retention.
- `records`: delete remote work files and sub2sub task records, retaining native history; automated restoration is no longer available. Accepted full expiry keeps only the metadata needed to delete that history at its original deadline.
- `all`: additionally delete the associated native conversation and descendants. This can follow `records`.

Only offer manual history/record deletion when relevant to the user's request, and use their explicit choice. Ordinary completion and file-transfer consent without an accepted full-expiry rule do not authorize those broader deletions. Resolve skipped necessary outputs using the work-copy reference before manual cleanup. Local source, complete task copies, downloaded results and the management index remain. Native deletion errors mean incomplete cleanup; retry the same scoped operation after resolving the error. System backups and service-side retention are outside these operations.

For host cleanup, connection edits/deletion, or verification of old cleanup records, use [settings and management](references/settings.md). For installation or version errors, read ../../docs/install.md.