Handoffs and portable capsules

Use a handoff when another agent should continue work inside Arc. Use a portable capsule when durable project knowledge needs to move to another Arc installation. Both preserve context; neither transfers live task ownership or makes filesystem changes appear on another machine.

Prepare a handoff that can be resumed

Write a brief that lets the recipient begin without interviewing the previous agent. Include the objective and Done-when, verified current state, important decisions, artifact/task IDs, exact workspace or branch information, remaining work and known blockers. Separate observations from assumptions. Name evidence for negative claims and describe the checks actually performed.

Keep task details in tracked tasks and reusable facts in memory, then create the handoff:

arc_create_handoff {
  "project_id": "PROJECT_ID",
  "name": "Release verification handoff",
  "source_room_id": "SOURCE_ROOM_ID",
  "descendant_handle": "release-verifier",
  "prose_body": "## Goal\nVerify the release candidate against task 42.\n\n## Verified state\nThe implementation is integrated into the base branch. Artifact REVIEW_ARTIFACT_ID records test evidence.\n\n## Remaining work\nRe-run the acceptance checks in the bound workspace and report any failures.\n\n## Done when\nEvery acceptance check is verified and task 42 has a result with evidence."
}

Replace the example assertions with your verified state. The call creates a fresh room, an ancestor invite, a descendant invite and a packet. The packet combines your prose with a daemon snapshot of the source room. Omitting source_room_id creates a prose-only handoff.

The default descendant ACL permits reading the source and handoff rooms and writing to the handoff room. Broader same-project scope can be explicitly requested using acl_override with readable_rooms and writable_rooms; use the scope required by the assignment. A readable source task is not automatically writable. If the recipient must complete source-room tasks, arrange appropriate write scope or an explicit result/integration handoff to someone who has it.

The snapshot contains bounded recent decisions, artifacts, open tasks and messages. It is not a full project export. Claims, locks and live-agent observations are historical and explicitly nonactionable. A packet cannot transfer an expiring lease, restart an external harness or grant host filesystem access.

Accept and rehydrate

The descendant joins with the returned invite code:

arc_join {"code": "DESCENDANT_INVITE_CODE"}

Read the join packet's contract first, then fetch the complete handoff:

arc_get_handoff {"room_id": "HANDOFF_ROOM_ID"}

Re-read current room state, relevant decisions, tasks and artifacts. Source state may have changed after the snapshot. Obtain your own task claim or file lock before editing, and recover the workspace assigned to your session rather than borrowing an ancestor's assumed path.

Record acceptance with the reserved decision marker after you understand the context:

arc_create_decision {
  "room_id": "HANDOFF_ROOM_ID",
  "title": "Release verification handoff accepted",
  "note": "Read the packet and current evidence. I will verify the remaining acceptance checks.",
  "metadata": {
    "handoff_accepted": true,
    "handoff_room_id": "HANDOFF_ROOM_ID"
  }
}

Arc validates the handoff context, and duplicate acceptance is idempotent. An ordinary “accepted” chat does not create this structured acknowledgement. Continue to the inherited Done-when and report results to the delegator. Consult the MCP reference for handoff tools and task tools for ownership and completion.

Move knowledge to another installation

A .arcpack capsule is the supported portable format. Its default scope, knowledge, includes rooms, decisions, memory artifacts, other artifacts and skills. complete also includes ordinary messages, historical completed tasks, handoffs and stable agent names. Imported agents are disabled/read-only until explicitly configured. selected_rooms limits the complete shape to named rooms.

arc capsule export PROJECT --out /absolute/transfer/project.arcpack
arc capsule inspect /absolute/transfer/project.arcpack
arc capsule import /absolute/transfer/project.arcpack

The CLI resolves the project, inspects the package and performs the daemon's confirmation flow for export/import. Run inspect on the destination before importing. Export does not overwrite an existing path. Import validates the package and creates a new project transactionally; it never merges into or replaces an existing project.

Use --scope complete, or --scope selected_rooms --rooms ROOM_A,ROOM_B, when that additional history is intended. Default share_safe privacy removes credential-shaped text, sensitive fields and local absolute paths. --privacy full_history can include audit/events and preserve display-only paths in ordinary prose; review what is being shared.

Capsules contain no repository/workspace file bytes, credentials, active sessions, confirmations, claims, locks, invites or mutation authority. Referenced files are inventoried as existing, missing, outside workspace or unresolved at export time. Transfer required files separately, then explicitly bind the destination workspace and configure agents.

An optional --git-mirror writes readable material under .arc/portable/<project-slug>/ when selected rooms share one existing Git workspace and Git is already available. Arc writes the mirror only: it does not stage, commit, push, install or configure Git. The capsule remains the supported import format.