# Handoffs
Source: https://docs.treeship.dev/guides/handoffs

> A handoff is a signed transfer of work between actors or across Treeships.

A handoff records the chain of custody when work moves between agents, between humans and agents, or between organizations.

## Handoff scenarios

<Cards>
  <Card title="Agent to Agent" description="One agent hands off research results to another agent for execution, with a signed transfer record." />

  <Card title="Agent to Human" description="An agent produces output that a human needs to review. The handoff proves what was delivered and when." />

  <Card title="Cross-Treeship" description="Work moves between organizations. Each side has its own keys. The handoff bridges trust domains." />
</Cards>

## Same-Treeship handoff

```bash
treeship attest handoff \
  --from agent://researcher \
  --to agent://executor \
  --artifacts art_research_001,art_validate_002
```

```
✓ handoff attested
  id:        art_handoff_xyz
  from:      agent://researcher
  to:        agent://executor
  artifacts: art_research_001, art_validate_002
```

The receiver can verify the handoff before acting:

```bash
treeship verify art_handoff_xyz
# ✓ verified -- chain intact, 2 artifacts transferred
```

## Cross-Treeship handoff (cross-org)

When work moves between organizations, each side has its own Treeship and keys.

```bash
# Company A -- attest a handoff
treeship attest handoff \
  --from agent://company-a/researcher \
  --to agent://company-b/legal-review \
  --artifacts art_output_123

treeship hub push art_handoff_xyz
# -> https://treeship.dev/verify/art_handoff_xyz
# Share this URL with Company B
```

```bash
# Company B -- verify before acting
treeship hub pull art_handoff_xyz
treeship verify art_handoff_xyz --trusted-key ./company-a-public.pem

# ✓ verified
#   from:      agent://company-a/researcher
#   artifacts: 1 transferred
#   chain:     intact
```

<Callout type="info">
  No shared infrastructure required. The signature is the trust. Company B does not need to trust the Hub or any third party -- only the public key of Company A.
</Callout>

## Handoff flags

| Flag                   | Required | Description                                    |
| ---------------------- | -------- | ---------------------------------------------- |
| `--from <uri>`         | Yes      | Actor URI of the sender                        |
| `--to <uri>`           | Yes      | Actor URI of the receiver                      |
| `--artifacts <ids>`    | Yes      | Comma-separated artifact IDs being transferred |
| `--approvals <ids>`    | No       | Approval IDs the receiver inherits             |
| `--obligations <text>` | No       | Obligations the receiver must satisfy          |