Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

docs / case-handoffs-and-continuity

Case handoffs and work continuity

A case is a durable work record that keeps one task, its context, its documents, and its agent phases together. It lets work move between agents without losing the task identity, while access checks, activity records, and recovery rules keep the transfer safe and visible. This page complements agent work management, issue execution, execution environments, agent instructions, adapter integrations, runner evaluation and conformance, native runner execution, and reusable workflows.

Case lifecycle

Case creation

A case starts as a company-scoped record with a type, title, summary, fields, and optional project or parent case. Work normally begins when the case is linked to one primary task. A new case can create that task and seed its workflow document, or an existing eligible task can become the primary task. A new task needs a kickoff and either a reusable workflow or workflow text. Optional task documents can be seeded at the same time. Cases are an optional product feature and may be created through the case API or the native case tools. server/…/case-handoffs.ts• L336-528 server/…/native-case-tools.ts• L30-83

References: server/…/case-handoffs.ts• L336-528 server/…/native-case-tools.ts• L30-83

The primary task is the work identity that agents reuse across phases. A case can also retain links to source tasks or projects and link other tasks for reference. These links help build context, but they do not grant access by themselves. packages/…/cases.ts• L23-83

References: packages/…/cases.ts• L23-83

Case access

Case access follows the case's retained source boundaries. The reader must have current access to every retained task and project, and a source-less case still requires company-level access. This keeps a case from becoming a wider view of work that the reader could not open directly. server/…/case-access.ts• L103-167

An incoming agent receives access through the primary task only when the agent and its responsible or authorizing user can also satisfy the case's retained boundaries. A handoff therefore changes work ownership without turning the case into a broad grant over unrelated tasks. server/…/case-access.ts• L193-241

References: server/…/case-access.ts• L103-167 server/…/case-access.ts• L193-241

Context assembly

The admitted run receives one bounded case snapshot after the server confirms that the run owns the primary task and can read the case. The snapshot joins case facts with the current phase, workflow, incoming handoff instructions, recent handoff history, readable linked tasks, document references, and readable work products. Bodies of task documents remain available through their owning task and are read on demand. Skill-test runs and other task-only scopes do not receive the wider case context. server/…/case-context.ts• L29-83 server/…/case-context.ts• L84-155

The snapshot is data for the agent, not a replacement for runtime policy. It has a size limit and separate markers for case facts and incoming instructions. A continuation can reuse unchanged facts while receiving new routing or handoff data. If the incoming instruction comment was withdrawn, the context says so and directs the agent to read the current authorized comments instead. server/…/case-context.ts• L158-230

References: server/…/case-context.ts• L29-83 server/…/case-context.ts• L84-155 server/…/case-context.ts• L158-230

Handoff flow

Agent transfer

An agent handoff moves the existing primary task to another agent and records the next phase, instructions, and any workflow change. It does not create a replacement task. The sender must save findings first, provide the observed case and task versions, and yield after the handoff is accepted. The recipient then continues the same task. packages/…/handoff-case.ts• L1-3 server/…/case-handoffs.ts• L242-282

The handoff request is idempotent. Version checks reject a request based on stale routing or task state, and only one pending handoff can control a case at a time. The system also rechecks the sender's authority and the recipient's case access when it applies the transfer. These rules prevent two agents or two callers from silently taking ownership of the same phase. server/…/case-handoffs.ts• L336-357 server/…/case-handoffs.ts• L242-282 packages/…/cases.ts• L194-241

References: server/…/case-handoffs.ts• L242-282 server/…/case-handoffs.ts• L336-357 packages/…/cases.ts• L194-241

This diagram shows how a handoff changes task ownership and reaches the next agent.

flowchart LR
    A[Current agent saves work] --> B[Create durable handoff]
    B --> C{Source execution settled?}
    C -- No --> D[Request yield and wait]
    D --> C
    C -- Yes --> E[Apply next assignment]
    E --> F[Wake recipient]
    F --> G[Recipient reads case context]
    G --> H[Recipient continues same task]

Completion transfer

The done form records that the current phase intends to finish the case, but it does not mark the task or case complete by itself. Normal task completion still supplies the evidence and review gates. Only accepted task completion closes the case. server/…/case-handoff-lifecycle.ts• L165-228 packages/…/handoff-case.ts• L35-46

References: server/…/case-handoff-lifecycle.ts• L165-228 packages/…/handoff-case.ts• L35-46

Task documents

Workflow documents

The workflow document is the durable guide for the case's phases. Case creation can place it on the newly created primary task under the reserved workflow key, together with optional initial task documents. A reusable workflow is copied into that task when a phase selects it. Later changes to the reusable definition do not silently rewrite an existing task document. The document belongs to the task rather than to a temporary agent turn, so later agents can read and update the same work record. server/…/case-workflows.ts• L8-44 server/…/case-handoffs.ts• L483-497

References: server/…/case-workflows.ts• L8-44 server/…/case-handoffs.ts• L483-497

Document references

Case context exposes document metadata and read paths for the primary task and readable linked tasks. It does not copy all document bodies into the context snapshot. Agents read a selected document through the owning task or through the authorized case read path. The read path accepts a case-owned document or a document on the primary or linked task. It does not widen access to unrelated, system, or quarantined documents. server/…/case-task-documents.ts• L11-62 server/…/case-agent-read.ts• L40-76

Document reads are paged when needed and use a snapshot value for continuation. Every page rechecks current case and document authority. A change to the case, routing, linked-task access, or selected document requires a fresh read, so an agent does not join new bytes to an old view. server/…/case-agent-read.ts• L79-117 server/…/native-case-tools.ts• L50-83

References: server/…/case-task-documents.ts• L11-62 server/…/case-agent-read.ts• L40-76 server/…/case-agent-read.ts• L79-117 server/…/native-case-tools.ts• L50-83

Activity visibility

Case history

Case history records creation, updates, links, document changes, handoff requests, assignment, delivery, completion, and cancellation. Handoffs also write activity entries, so operators can follow ownership changes in the normal activity view. The history keeps the actor, run, phase, version, and outcome needed to understand what happened. packages/…/cases.ts• L86-127 server/…/case-handoffs.ts• L61-76

References: packages/…/cases.ts• L86-127 server/…/case-handoffs.ts• L61-76

Activity boundaries

Case-derived activity is visible only when the viewer can read the case itself. Case events that do not already have a matching activity entry are merged into the activity source, while handoff and document activity stay in their existing audit stream. This gives operators one view without duplicating records or leaking hidden case events. server/…/case-activity-access.ts• L6-13 server/…/case-activity-source.ts• L16-47

Case work summaries add the primary task, workflow, and active handoff to an already authorized case page. They show pending handoff details only when the viewer can also read the primary task. This prevents a readable case from exposing task instructions through a malformed or hidden task link. server/…/case-work-summary.ts• L9-63

References: server/…/case-activity-access.ts• L6-13 server/…/case-activity-source.ts• L16-47 server/…/case-work-summary.ts• L9-63

Privacy boundaries

Retained source boundaries

Retained task and project sources define the privacy boundary that a case must preserve. A private source cannot be handed into a primary task with a wider audience. A case with several private task boundaries must use an existing eligible primary task rather than create a task that cannot preserve them. Privacy follows the real parent chain of private work, not shared root labels or sibling links. server/…/case-handoffs.ts• L165-202 server/…/case-handoffs.ts• L419-445 server/…/case-handoff-privacy.test.ts• L59-100

References: server/…/case-handoffs.ts• L165-202 server/…/case-handoffs.ts• L419-445 server/…/case-handoff-privacy.test.ts• L59-100

Trust boundaries

Case work requires standard trusted execution and current authority. Low-trust runs, revoked connections, missing source identity, or changed agent authority cannot write, execute, or hand off ordinary case work. Native case tools and the wider case context are also unavailable to skill-test or other task-only runs. The system fails closed rather than promoting contained output into successor work. server/…/case-access.ts• L19-48 server/…/case-access.ts• L50-101 server/…/case-context.ts• L41-73 server/…/native-case-tools.ts• L50-72 server/…/case-handoff-authority.ts• L56-107

References: server/…/case-access.ts• L19-48 server/…/case-access.ts• L50-101 server/…/case-context.ts• L41-73 server/…/native-case-tools.ts• L50-72 server/…/case-handoff-authority.ts• L56-107

Execution recovery

Release and delivery

An accepted handoff first waits for the outgoing run and its workspace to settle. Only then does the system apply the new assignment and wake the recipient. The release record is written after authoritative stop and cleanup checks. Delivery uses durable records, leases, retry times, and an admission receipt, so a process restart can resume the intent without sending duplicate work. server/…/case-handoff-delivery.ts• L15-20 server/…/case-handoff-delivery.ts• L81-120 server/…/case-handoff-lifecycle.ts• L231-246

References: server/…/case-handoff-delivery.ts• L15-20 server/…/case-handoff-delivery.ts• L81-120 server/…/case-handoff-lifecycle.ts• L231-246

The source run is fenced after it yields. Late output cannot complete or mutate the transferred task, and the native runtime reports a yielded result tied to the exact persisted handoff. This preserves one owner for the open task while delivery is in progress. server/…/case-handoffs.ts• L204-212 server/…/native-case-handoff.ts• L6-38

References: server/…/case-handoffs.ts• L204-212 server/…/native-case-handoff.ts• L6-38

Recovery evidence

Terminal run status alone does not prove that a handoff can proceed. Recovery first verifies the exact source identity recorded by the failed run. It checks the company, task, run, recovery action, bound allocation, provider, working directory, and current ownership state. It never discovers a source by recency, mutable settings, or a provider search. A reusable allocation can support preservation after an accepted native result, but it cannot become an execution source through this path. server/…/workspace-recovery-source.ts• L67-157 server/…/workspace-recovery-source.test.ts• L114-155

Recovery also checks provider stop evidence, native ownership, execution blockers, pending cleanup, and workspace cleanup. If the controller stops at an awkward point, the durable handoff remains pending until these checks prove that the old execution no longer owns the task. Local legacy runs can recover from recorded process-stop and scratch-cleanup evidence, but an expired controller lease is not enough. Workspace recovery uses the same proof-first rule: it does not treat a failed export or a stopped process as proof that saved work is safe. server/…/case-handoff-lifecycle.ts• L78-114 server/…/case-handoff-lifecycle.ts• L249-275 server/…/workspace-recovery.ts• L112-169

References: server/…/workspace-recovery-source.ts• L67-157 server/…/workspace-recovery-source.test.ts• L114-155 server/…/case-handoff-lifecycle.ts• L78-114 server/…/case-handoff-lifecycle.ts• L249-275 server/…/workspace-recovery.ts• L112-169

Workspace preservation

Workspace recovery preserves work left in an execution environment before a successor can use it. A recovery request records durable intent, then a worker verifies the exact source allocation, stops it with provider evidence, reopens it only for preservation, and saves the workspace before final cleanup. The source remains retained when any proof or save step fails, so a later attempt can continue without destructive cleanup. server/…/workspace-recovery.ts• L71-78 server/…/workspace-recovery.ts• L108-179 server/…/workspace-recovery.ts• L193-241

The recovery record also separates saved-work repair from later environment destruction. Cleanup is scheduled only after the saved workspace has a verified repair receipt and the original resource disposition requires destruction. Repeated recovery work uses the same durable operation and does not export the same source again after a lost acknowledgement. Once recovery succeeds, normal result finalization and authorized continuation can resume. An exhausted recovery may be evaluated in isolation but cannot replay the old assignment. server/…/workspace-recovery.ts• L244-278 server/…/workspace-recovery.ts• L294-315 server/…/workspace-recovery.ts• L346-405 server/…/workspace-recovery.test.ts• L622-669

References: server/…/workspace-recovery.ts• L71-78 server/…/workspace-recovery.ts• L108-179 server/…/workspace-recovery.ts• L193-241 server/…/workspace-recovery.ts• L244-278 server/…/workspace-recovery.ts• L294-315 server/…/workspace-recovery.ts• L346-405 server/…/workspace-recovery.test.ts• L622-669

Operator control

Operators can inspect the handoff history and retry or cancel a pending transfer. Retry clears the delivery error and schedules the durable intent again. Cancellation records the reason and prevents that intent from assigning the task, while later task decisions can also cancel a superseded handoff. server/…/case-handoffs.ts• L12-36 server/…/case-handoffs.ts• L565-600

References: server/…/case-handoffs.ts• L12-36 server/…/case-handoffs.ts• L565-600

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the primary task, case version, and task status version checks aligned across handoff acceptance and delivery.
  • Preserve the same case access rule for case reads, context assembly, recipient admission, and activity reads.
  • Keep workflow selection, task-document revisions, and conflict checks aligned when changing case creation or phase transitions.
  • Keep native case reads, page snapshots, and linked-task document checks behind the same current case boundary.
  • Preserve the release proof and cleanup gates before changing wakeup, retry, or recovery behavior.
  • Keep source verification bound to the failed run's recorded allocations. Do not replace it with recency, provider discovery, or mutable allocation settings.
  • Keep reusable allocation preservation separate from permission to reuse that allocation for agent execution.
  • Keep workspace recovery intent, source-allocation checks, saved-work receipts, and deferred cleanup as separate recovery stages.
  • Keep recovered work eligible for normal authorized continuation, while preventing exhausted recovery from replaying the old assignment.
  • Keep terminal handoff intent separate from normal task completion and review.

Important failure modes

TriggerConsequenceGuard
A sender uses stale case or task versionsThe transfer is rejected instead of changing newer workVersion checks and one pending handoff per case
The outgoing run has not settledThe recipient is not assigned yetRelease proof, workspace cleanup, and source-run fencing
A recipient cannot read a retained sourceThe handoff is blockedCurrent access checks for every retained boundary
A private source is copied into a wider taskThe handoff is rejected before task content crosses the boundaryPrimary-task privacy ancestry checks
A workflow document changes after a handoff captures itDelivery holds instead of overwriting newer task workBase document revision conflict check
A handoff delivery attempt loses its processThe durable intent stays pending for recoveryLease expiry, retry time, and admission receipt
A continuation uses a page snapshot after routing or access changesThe read fails instead of joining old and new dataCurrent authorization and snapshot match
A completion request is recorded but task completion is not acceptedThe case remains openNormal completion, evidence, and review gates
Recovery starts without terminal execution, required evidence, or an exact recorded sourceNo workspace recovery intent is acceptedTerminal-run, recovery-evidence, and source-identity checks
A reusable source has no accepted result or its allocation is shared with another leaseSource preservation is blockedAccepted-result and physical-allocation ownership checks
Workspace stop or save proof is missingThe source stays retained and the recovery remains pendingExact-allocation checks, provider receipts, and durable retry state
A repaired workspace has no matching saved-work receipt or destroy dispositionDestructive cleanup is not scheduledVerified repair and original disposition checks
Recovery is exhaustedThe system can assess an isolated continuation but does not replay the old assignmentRecovery outcome gates normal dispatch

Key files

FileWhy to read it
server/…/case-handoffs.tsMain case creation, task binding, transfer, completion intent, and handoff control flow
server/…/case-access.tsCase access, retained privacy boundaries, trust checks, and recipient admission
server/…/case-context.tsBounded context assembly for new and resumed agent turns
server/…/case-workflows.tsWorkflow selection, capture, and safe application to the task workflow document
server/…/case-work-summary.tsAuthorized case-page enrichment with primary work and pending handoff state
server/…/case-task-documents.tsTask-owned document references exposed through a case
server/…/case-handoff-delivery.tsDurable wakeup, leases, retries, and recipient delivery
server/…/case-handoff-lifecycle.tsSource release, cleanup recovery, cancellation, and terminal completion
server/…/workspace-recovery.tsDurable workspace recovery admission, preservation, cleanup, and continuation after execution failure
server/…/workspace-recovery-source.tsExact source binding and ownership checks before workspace preservation
server/…/native-case-handoff.tsNative runner yield and exact handoff continuation behavior
server/…/native-case-tools.tsNarrow native case access and mutation surface with feature and scope gates
server/…/case-agent-read.tsAuthorized and paged case reads for agents
server/…/case-activity-access.tsPrivacy filter for case-derived activity
server/…/cases.tsHTTP case creation, reads, document changes, and access enforcement
server/…/case-handoffs.tsHTTP handoff, history, retry, and cancellation entry points
packages/…/case-handoffs.tsShared handoff rules and result states
packages/…/cases.tsDurable case, event, source, document, and handoff relationships