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
| Trigger | Consequence | Guard |
|---|---|---|
| A sender uses stale case or task versions | The transfer is rejected instead of changing newer work | Version checks and one pending handoff per case |
| The outgoing run has not settled | The recipient is not assigned yet | Release proof, workspace cleanup, and source-run fencing |
| A recipient cannot read a retained source | The handoff is blocked | Current access checks for every retained boundary |
| A private source is copied into a wider task | The handoff is rejected before task content crosses the boundary | Primary-task privacy ancestry checks |
| A workflow document changes after a handoff captures it | Delivery holds instead of overwriting newer task work | Base document revision conflict check |
| A handoff delivery attempt loses its process | The durable intent stays pending for recovery | Lease expiry, retry time, and admission receipt |
| A continuation uses a page snapshot after routing or access changes | The read fails instead of joining old and new data | Current authorization and snapshot match |
| A completion request is recorded but task completion is not accepted | The case remains open | Normal completion, evidence, and review gates |
| Recovery starts without terminal execution, required evidence, or an exact recorded source | No workspace recovery intent is accepted | Terminal-run, recovery-evidence, and source-identity checks |
| A reusable source has no accepted result or its allocation is shared with another lease | Source preservation is blocked | Accepted-result and physical-allocation ownership checks |
| Workspace stop or save proof is missing | The source stays retained and the recovery remains pending | Exact-allocation checks, provider receipts, and durable retry state |
| A repaired workspace has no matching saved-work receipt or destroy disposition | Destructive cleanup is not scheduled | Verified repair and original disposition checks |
| Recovery is exhausted | The system can assess an isolated continuation but does not replay the old assignment | Recovery outcome gates normal dispatch |
Key files
| File | Why to read it |
|---|---|
| server/…/case-handoffs.ts | Main case creation, task binding, transfer, completion intent, and handoff control flow |
| server/…/case-access.ts | Case access, retained privacy boundaries, trust checks, and recipient admission |
| server/…/case-context.ts | Bounded context assembly for new and resumed agent turns |
| server/…/case-workflows.ts | Workflow selection, capture, and safe application to the task workflow document |
| server/…/case-work-summary.ts | Authorized case-page enrichment with primary work and pending handoff state |
| server/…/case-task-documents.ts | Task-owned document references exposed through a case |
| server/…/case-handoff-delivery.ts | Durable wakeup, leases, retries, and recipient delivery |
| server/…/case-handoff-lifecycle.ts | Source release, cleanup recovery, cancellation, and terminal completion |
| server/…/workspace-recovery.ts | Durable workspace recovery admission, preservation, cleanup, and continuation after execution failure |
| server/…/workspace-recovery-source.ts | Exact source binding and ownership checks before workspace preservation |
| server/…/native-case-handoff.ts | Native runner yield and exact handoff continuation behavior |
| server/…/native-case-tools.ts | Narrow native case access and mutation surface with feature and scope gates |
| server/…/case-agent-read.ts | Authorized and paged case reads for agents |
| server/…/case-activity-access.ts | Privacy filter for case-derived activity |
| server/…/cases.ts | HTTP case creation, reads, document changes, and access enforcement |
| server/…/case-handoffs.ts | HTTP handoff, history, retry, and cancellation entry points |
| packages/…/case-handoffs.ts | Shared handoff rules and result states |
| packages/…/cases.ts | Durable case, event, source, document, and handoff relationships |