Handoffs

5 min readCore conceptUpdated 2026-05-19

What you'll learn

• What a handoff is and what it's deliberately not.
• The fields every handoff carries and how they ground the next run.
• How structured handoffs and Markdown rendering coexist.
• What the self-audit checklist tells you about a finished run.

Handoff

A durable, structured run summary for the next agent or human reviewer. It records what happened, what was validated, what remains uncertain, and where to resume.

A handoff is not a transcript and not a chat log. It's the concise continuity record that lets the next actor pick up without re-deriving everything from scratch.

The contract

Every handoff carries:

Field

Type

Purpose

task_id

id

The task this handoff closes (or pauses).

project_id

id

The project the task belongs to.

intent_lock_id

id

The scope contract the run executed under.

agent

agent_identity

Which runner produced the handoff — Codex, Claude, Gemini, a human, etc.

status

enum

completed · paused · failed · requires_review.

summary

text

One paragraph: what was attempted, what landed, what the next actor needs to know first.

completed_actions

action[]

The discrete units of work that did finish.

files_and_artifacts

artifact_ref[]

Paths the run touched and named artifacts it produced.

commands_and_validation

command[]

Validation commands run and their results — the verification trail.

assumptions

assumption[]

Open assumptions promoted, refuted, or carried forward from the case file.

context_debt

debt_item[]

Context this run knows it didn't fully chase. Material for the next run.

policy_exceptions

exception[]

Cases where the run took a fail-open path or hit a policy boundary.

receipts

id[]

Receipt ids produced during the run. Joinable to capability_receipt records.

memory_proposals

proposal[]

Facts the run wants written to memory, pending review.

next_steps

step[]

Explicit next actions: what should happen, who should do it, what to verify first.

self_audit

checklist

The honesty pass — see below.

Structured and Markdown

Craik persists handoffs as craik.handoff records in the local SQLite store. The structured handoff is the durable source of truth. The Markdown rendering is a readable view of the same record — useful for code review, release notes, and "tell me what just happened" inspection.

Create a structured handoff

craik handoff create task_review_docs \
  --summary "Updated docs and recorded current state." \
  --test-run pytest

Render the same handoff as Markdown

craik handoff show task_review_docs --markdown

Export the structured JSON

craik handoff show task_review_docs

The self-audit

Every handoff includes a self-audit checklist that asks explicit questions about the run:

schema_validated

Did the runtime check that produced records match their declared schemas?

redaction_reviewed

Did someone (human or runtime) confirm receipts and handoffs are free of unredacted secrets?

receipts_reviewed

Were the produced receipts inspected and joined back to the actions they describe?

assumptions_reviewed

Were open assumptions promoted, refuted, or explicitly carried forward?

validation_recorded

Are the commands run and their outcomes captured in commands_and_validation?

policy_exceptions_disclosed

Are all fail-open paths and policy boundary hits called out in policy_exceptions?

Incomplete handoffs are valid — a run that crashed mid-stream still writes one. What's not valid is hiding that incompleteness. The self-audit makes missing validation or unresolved context visible to whoever picks up the work next.

How the next agent uses a handoff

When craik onboard runs for the next task, it pulls in the most recent handoffs for the project (recent_handoffs in the onboarding payload). The next agent's case file inherits:

• The summary so context isn't reconstructed from scratch.
• Open assumptions and context_debt as carryovers.
• policy_exceptions so the new runner knows where the system was running hot.
• next_steps as a starting menu of actions.

That is the loop. Each handoff is a node in the work graph. Receipts are the edges that explain how the run got from case file to handoff.

What's next

Read nextThe work graphHow tasks, case files, receipts, and handoffs compose into the queryable runtime state.DoWrite good handoffsPatterns that make a handoff actually useful for the next agent.ReferenceHandoff viewerThe operator surface that renders a handoff with full context.