Skip to content

Handoffs

Approve, accept, reject, or cancel personal tool handoffs with pf, and refresh a request after its task changes.

Request, run, and decide personal tool handoffs from the terminal. The CLI must use the API token of a personal tool connection that is enabled in the workspace, and the token needs task write access. Register a connection with pf handoffs register, then find handoff IDs with pf handoffs list.

Project-restricted account tokens work with these same commands. A connection's intake cannot expand the token's selected projects. Use separate tokens for tools with different project assignments, and keep following page cursors even when a filtered page is empty.

pf handoffs channelForward handoff state notices into a running Claude Code session through the Channels preview. Configure this command as a local MCP stdio server and enable the custom channel in Claude. Uses an enabled personal tool connection and the existing handoff WebSocket. Combines notices to at most one every thirty seconds. Checks the inbox on connection and stays quiet if empty; no idle inbox or event requests. Claude reads current work after a notice. Use one channel or wait per credential. Covers handoffs only.

Options

  • --statusesstring

    States to watch; defaults to queued,open

  • --directionstring

    received (default) or sent

Example

Shell
pf handoffs channel
pf handoffs channel --direction sent --statuses needs_input,result
pf handoffs waitWait in a background process for a current handoff. Opens a WebSocket, checks existing work, and rechecks the inbox on a server signal. Idle waits do not poll. The server renews access without reconnecting. Does not claim work. Waiting needs no model calls; initial connections and inbox reads count toward limits. One wait per connection, four per owner, and sixteen per workspace. An interrupted wait exits 130 for SIGINT or 143 for SIGTERM.

Options

  • --statusesstring

    States to wait for; defaults to queued,open

  • --directionstring

    received (default) or sent

  • --timeoutnumber

    Stop after this many seconds; 0 waits until interrupted. A timeout returns handoff: null and timedOut: true.

Example

Shell
pf handoffs wait --json
pf handoffs wait --direction sent --statuses needs_input,result --timeout 300 --json
pf handoffs register <name>Register this credential as a personal tool, with a recognizable name of up to 80 characters. Running it again returns the existing connection and never renames it. Enable the tool in Account > Tools & tokens before it can request or claim work

Example

Shell
pf handoffs register "Release helper"
pf handoffs connectionCheck whether this credential is ready for handoffs, why not, and its request budgets

Example

Shell
pf handoffs connection
pf handoffs connection --json
pf handoffs listList handoffs in one state or several. Received handoffs are the work this tool can take; sent ones are the work you requested. Long rows are shortened, so read the full text with pf handoffs get

alias: pf handoffs ls

Options

  • --statusstring

    One of open, requested, queued, running, needs_input, result, accepted, or rejected

  • --statusesstring

    Comma-separated states, listed together with a section for each

  • --directionstring

    received (default) or sent

  • --limitnumber

    Handoffs per page, 1 to 4 (default 4). Needs --status

  • --cursorstring

    Continue one state from a previous page. Needs --status

  • --pageboolean

    With --json, return the page metadata (hasMore, nextCursor) along with the handoffs. Needs --status

Example

Shell
pf handoffs list --status queued
pf handoffs list --statuses requested,queued,result --json
pf handoffs list --status result --direction sent --limit 20

Pass --status or --statuses, not both.

pf handoffs task <task>List the handoffs on a task, newest first, with what you can do to each: approve, review, cancel, or request approval

Options

  • --limitnumber

    Handoffs per page, 1 to 20 (default 20)

  • --cursorstring

    Continue from a previous page

  • --pageboolean

    With --json, return the page metadata (hasMore, nextCursor) along with the handoffs

Example

Shell
pf handoffs task ENG-42
pf handoffs connections <task>List the personal tools whose owners can access a task, to choose one for pf handoffs request

Options

  • --cursorstring

    Continue from a previous page

  • --allboolean

    Follow every page, up to 10,000 tools

  • --pageboolean

    With --json, return the page metadata (hasMore, nextCursor) along with the tools

Example

Shell
pf handoffs connections ENG-42
pf handoffs request <task>Ask a personal tool, or any qualified tool, to do bounded work on a task. A tool you do not own waits for its owner's approval unless the owner lets your work start automatically

Options

  • --instructionsstringrequired

    What to do, what to deliver, and the limits

  • --connectionstring

    Send the work to this tool. Leave it out for an open handoff any qualified tool can take

  • --audiencestring

    Who may take an open handoff: own, allowed (default), or anyone

  • --skillsstring

    Comma-separated skills the tool needs

  • --min-accepted-resultsnumber

    Accepted results the tool needs

  • --min-accept-ratenumber

    Acceptance rate the tool needs, 0 to 100

  • --request-keystring

    Retry-safe key. One is generated and printed when you leave it out, so a retry can reuse it

Example

Shell
pf handoffs request ENG-42 --connection <connection-id> --instructions "Review the plan and list risks"
pf handoffs request ENG-42 --audience own --skills review --instructions "Draft the release notes"

A second open request for the same task and tool fails with the reason duplicate_request and the open handoff's ID.

pf handoffs claim <id>Claim approved or open work for five minutes. Prints the instructions, task details, and the attempt number to send with every later report

Options

  • --claim-idstring

    A unique ID for this runner. One is generated and printed when you leave it out. Reuse it when you retry

Example

Shell
pf handoffs claim <handoff-id> --claim-id runner-1
pf handoffs renew <id>Renew your claim for five minutes. Stop work if it fails

Options

  • --worker-fencestring

    JSON task lease fence, required when the handoff owns a worker lease

  • --claim-idstringrequired

    The claim ID from pf handoffs claim

  • --attemptnumberrequired

    The attempt number from the claim

Example

Shell
pf handoffs renew <handoff-id> --claim-id runner-1 --attempt 1
pf handoffs ask <id> <question>Pause work and ask the requester one question. Work resumes once the answer is approved

Options

  • --worker-fencestring

    JSON task lease fence, required when the handoff owns a worker lease

  • --claim-idstringrequired

    The claim ID from pf handoffs claim

  • --attemptnumberrequired

    The attempt number from the claim

Example

Shell
pf handoffs ask <handoff-id> "Which release is this for?" --claim-id runner-1 --attempt 1
pf handoffs result <id>Submit your result for review, with up to ten https links as evidence. This never completes the task

Options

  • --worker-fencestring

    JSON task lease fence, required when the handoff owns a worker lease

  • --claim-idstringrequired

    The claim ID from pf handoffs claim

  • --attemptnumberrequired

    The attempt number from the claim

  • --summarystringrequired

    What you found or did, and the next steps

  • --evidencestring

    Comma-separated https links that back the result

Example

Shell
pf handoffs result <handoff-id> --claim-id runner-1 --attempt 1 --summary "Found two risks" --evidence https://example.com/review
pf handoffs get <id>Read the handoff's instructions, task details, clarifications and context version before approval.

Example

Shell
pf handoffs get <handoff-id> --json
pf handoffs approve <id>Approve requested work as the person who receives the handoff.

Options

  • --context-versionnumber

    The contextVersion reviewed; required after refresh or a clarification answer

Example

Shell
pf handoffs approve <handoff-id>
pf handoffs decide <id> <decision>Approve, accept, reject, or cancel a handoff, depending on your part in it.

Options

  • --context-versionnumber

    The contextVersion reviewed; required after refresh or a clarification answer

Example

Shell
pf handoffs decide <handoff-id> accept
pf handoffs decide <handoff-id> cancel --json

The decision must be approve, accept, reject, or cancel. Any other value fails before a request is sent.

pf handoffs refresh-context <id>Update requested or queued work with the task's current title and description.

Example

Shell
pf handoffs refresh-context <handoff-id>
pf handoffs answer <id> <attempt> <answer>Answer the question a receiving tool asked, using the attempt number from the handoff.

Example

Shell
pf handoffs answer <handoff-id> 1 "Use the October plan"
  • The receiving person approves requested work. Approving a teammate's request needs the token of the receiving tool.
  • The requesting person accepts or rejects a result. Either person can cancel.
  • A tool takes work with claim, keeps it with renew every few minutes, and finishes with result. Pass the same claim ID and the attempt number from the claim to each.
  • Trust settings, which decide whose work a tool starts automatically, are managed in the app only.
  • A request waits when its task title or description has changed. Run refresh-context to copy the current task details into the request. Read them with pf handoffs get, then approve with --context-version set to the version you reviewed. Clarification answers also require approval of the current version unless current trust permits automatic work.

If a handoff command fails

A 403 means the key lacks task write access or the workspace blocks it. A 404 means the handoff is missing or inaccessible. A 409 means the handoff state or reviewed context has changed. Review it again before approving. A 429 includes retry timing. Invalid input returns 400. Read it again with pf handoffs get before retrying. See the Handoffs API for the full rules and personal tool handoffs for setup.

Image preview
100%