Handoff Ledger

curl -X POST https://api.prysm1.com/v1/handoff \
  -H "Authorization: Bearer prysm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws-myrepo",
    "objective": "Refactored auth module — split JWT validation into auth_jwt.py",
    "from_tool": "cursor",
    "to_tool": "claude-code",
    "files_touched": ["backend/main.py", "backend/auth_jwt.py"],
    "constraints": ["Do not change the public /v1/auth endpoint signature"],
    "risks": [{"id": "r1", "description": "Auth regression on legacy API keys"}],
    "validation": [{"id": "v1", "description": "Run python test_auth.py — all 14 assertions green"}],
    "recommended_next_action": "Add integration tests for the new auth_jwt module"
  }'

import prysm

h = prysm.handoffs.create(
    workspace_id="ws-myrepo",
    objective="Refactored auth module",
    from_tool="cursor",
    to_tool="claude-code",
    files_touched=["backend/main.py", "backend/auth_jwt.py"],
)
print(h["id"], h["risk"]["tier"])

{
  "id": "ho_9f3c2a1b8e7d4f5a",
  "workspace_id": "ws-myrepo",
  "objective": "Refactored auth module — split JWT validation into auth_jwt.py",
  "from_tool": "cursor",
  "to_tool": "claude-code",
  "prev_handoff_id": "ho_1a2b3c4d5e6f7g8h",
  "risk": {"score": 24, "tier": "auto", "factors": ["edit_action"]},
  "signed": true,
  "created_at": "2026-06-15T14:30:00+00:00"
}

All handoff endpoints require Bearer token authentication.

The Handoff Ledger is a hash-chained audit trail for session context. When an agent completes a unit of work and hands control to the next agent (or a human), it creates a handoff entry: a structured record of what was done, what was protected, what risks were identified, and what should happen next. Each entry is Ed25519-signed and linked to its predecessor via a hash chain, so any tampering (reorder, delete, mutate) is cryptographically detectable.

POST /v1/handoff

Append a signed handoff to a workspace’s chain. The server resolves prev_handoff_id and prev_signature from the latest entry in the workspace — a client cannot fork the chain by supplying stale prev links.

POST https://api.prysm1.com/v1/handoff · Auth required

Request Body

string

required

The workspace this handoff belongs to. Anchors the chain.

string

required

What this agent session accomplished (1–500 chars).

string

The agent/tool handing off (e.g. "cursor", "claude-code").

string

The agent/tool receiving (e.g. "claude-code", "human").

string[]

List of file paths modified in this session.

string[]

Constraints the next agent must respect (e.g. "Do not modify public API").

object[]

Identified risks: [{"id": "r1", "description": "Auth regression risk"}].

object[]

How to verify this work is correct: [{"id": "v1", "description": "All auth tests green"}].

string

What the receiving agent should do first.

string

Type of work: edit | refactor | deploy | review | setup. Default: edit.

number

Estimated cost in USD for this session (informational; recorded in the signed receipt).

Response

Returns the full signed receipt. Key fields:

string

Unique handoff ID (ho_...).

string

Echoed workspace ID.

string

Echoed objective.

string | null

Previous entry’s ID (null for first entry).

object

Risk assessment: score, tier (auto/confirm/approve/block), factors.

string

The canonical JSON string that was signed.

boolean

True when an Ed25519 signing key is provisioned.

string

ISO 8601 timestamp.

curl -X POST https://api.prysm1.com/v1/handoff \
  -H "Authorization: Bearer prysm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws-myrepo",
    "objective": "Refactored auth module — split JWT validation into auth_jwt.py",
    "from_tool": "cursor",
    "to_tool": "claude-code",
    "files_touched": ["backend/main.py", "backend/auth_jwt.py"],
    "constraints": ["Do not change the public /v1/auth endpoint signature"],
    "risks": [{"id": "r1", "description": "Auth regression on legacy API keys"}],
    "validation": [{"id": "v1", "description": "Run python test_auth.py — all 14 assertions green"}],
    "recommended_next_action": "Add integration tests for the new auth_jwt module"
  }'

import prysm

h = prysm.handoffs.create(
    workspace_id="ws-myrepo",
    objective="Refactored auth module",
    from_tool="cursor",
    to_tool="claude-code",
    files_touched=["backend/main.py", "backend/auth_jwt.py"],
)
print(h["id"], h["risk"]["tier"])

{
  "id": "ho_9f3c2a1b8e7d4f5a",
  "workspace_id": "ws-myrepo",
  "objective": "Refactored auth module — split JWT validation into auth_jwt.py",
  "from_tool": "cursor",
  "to_tool": "claude-code",
  "prev_handoff_id": "ho_1a2b3c4d5e6f7g8h",
  "risk": {"score": 24, "tier": "auto", "factors": ["edit_action"]},
  "signed": true,
  "created_at": "2026-06-15T14:30:00+00:00"
}

GET /v1/handoff/

Fetch a single signed handoff by ID.

GET https://api.prysm1.com/v1/handoff/{handoff_id} · Auth required

string

required

The ho_... ID returned by POST /v1/handoff.

curl https://api.prysm1.com/v1/handoff/ho_9f3c2a1b8e7d4f5a \
  -H "Authorization: Bearer prysm_sk_..."

{
  "id": "ho_9f3c2a1b8e7d4f5a",
  "workspace_id": "ws-myrepo",
  "objective": "Refactored auth module",
  "signed": true,
  "created_at": "2026-06-15T14:30:00+00:00"
}

{"error": "handoff_not_found", "message": "Handoff 'ho_...' not found."}

GET /v1/handoff/chain/

Fetch the full ordered handoff chain for a workspace and verify its cryptographic integrity.

GET https://api.prysm1.com/v1/handoff/chain/{workspace_id} · Auth required

string

required

The workspace whose chain to retrieve.

Response

string

handoff.chain

string

Echoed workspace ID.

integer

Total entries in the chain.

object[]

Ordered entries (oldest first).

object

Integrity verdict: ok (bool), n (entries verified), first_broken_index (null if intact), reasons (list of break descriptions), signing_enabled (bool).

string

URL to fetch the public signing key for offline verification.

curl https://api.prysm1.com/v1/handoff/chain/ws-myrepo \
  -H "Authorization: Bearer prysm_sk_..."

{
  "object": "handoff.chain",
  "workspace_id": "ws-myrepo",
  "count": 3,
  "data": [
    {"id": "ho_aaa", "objective": "Initial setup", "signed": true, "created_at": "..."},
    {"id": "ho_bbb", "objective": "Auth refactor", "signed": true, "created_at": "..."},
    {"id": "ho_ccc", "objective": "Deploy to staging", "signed": true, "created_at": "..."}
  ],
  "verification": {
    "ok": true,
    "n": 3,
    "first_broken_index": null,
    "reasons": [],
    "signing_enabled": true
  },
  "pubkey_endpoint": "https://api.prysm1.com/v1/proof/pubkey"
}

Workspace Governance Policy & Audit

Overview

Endpoints

Agentic Control Plane

Agentic Control Plane

Handoff Ledger

POST /v1/handoff

Request Body

Response

GET /v1/handoff/

GET /v1/handoff/chain/

Response

​POST /v1/handoff

​Request Body

​Response

​GET /v1/handoff/

​GET /v1/handoff/chain/

​Response

POST /v1/handoff

Request Body

Response

GET /v1/handoff/

GET /v1/handoff/chain/

Response