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
--statusesstringStates to watch; defaults to queued,open
--directionstringreceived (default) or sent
Example
pf handoffs channel
pf handoffs channel --direction sent --statuses needs_input,resultpf 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
--statusesstringStates to wait for; defaults to queued,open
--directionstringreceived (default) or sent
--timeoutnumberStop after this many seconds; 0 waits until interrupted. A timeout returns handoff: null and timedOut: true.
Example
pf handoffs wait --json
pf handoffs wait --direction sent --statuses needs_input,result --timeout 300 --jsonpf 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
pf handoffs register "Release helper"pf handoffs connectionCheck whether this credential is ready for handoffs, why not, and its request budgets
Example
pf handoffs connection
pf handoffs connection --jsonpf 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
--statusstringOne of open, requested, queued, running, needs_input, result, accepted, or rejected
--statusesstringComma-separated states, listed together with a section for each
--directionstringreceived (default) or sent
--limitnumberHandoffs per page, 1 to 4 (default 4). Needs --status
--cursorstringContinue one state from a previous page. Needs --status
--pagebooleanWith --json, return the page metadata (hasMore, nextCursor) along with the handoffs. Needs --status
Example
pf handoffs list --status queued
pf handoffs list --statuses requested,queued,result --json
pf handoffs list --status result --direction sent --limit 20Pass --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
--limitnumberHandoffs per page, 1 to 20 (default 20)
--cursorstringContinue from a previous page
--pagebooleanWith --json, return the page metadata (hasMore, nextCursor) along with the handoffs
Example
pf handoffs task ENG-42pf handoffs connections <task>List the personal tools whose owners can access a task, to choose one for pf handoffs request
Options
--cursorstringContinue from a previous page
--allbooleanFollow every page, up to 10,000 tools
--pagebooleanWith --json, return the page metadata (hasMore, nextCursor) along with the tools
Example
pf handoffs connections ENG-42pf 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
--instructionsstringrequiredWhat to do, what to deliver, and the limits
--connectionstringSend the work to this tool. Leave it out for an open handoff any qualified tool can take
--audiencestringWho may take an open handoff: own, allowed (default), or anyone
--skillsstringComma-separated skills the tool needs
--min-accepted-resultsnumberAccepted results the tool needs
--min-accept-ratenumberAcceptance rate the tool needs, 0 to 100
--request-keystringRetry-safe key. One is generated and printed when you leave it out, so a retry can reuse it
Example
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-idstringA unique ID for this runner. One is generated and printed when you leave it out. Reuse it when you retry
Example
pf handoffs claim <handoff-id> --claim-id runner-1pf handoffs renew <id>Renew your claim for five minutes. Stop work if it fails
Options
--worker-fencestringJSON task lease fence, required when the handoff owns a worker lease
--claim-idstringrequiredThe claim ID from pf handoffs claim
--attemptnumberrequiredThe attempt number from the claim
Example
pf handoffs renew <handoff-id> --claim-id runner-1 --attempt 1pf handoffs ask <id> <question>Pause work and ask the requester one question. Work resumes once the answer is approved
Options
--worker-fencestringJSON task lease fence, required when the handoff owns a worker lease
--claim-idstringrequiredThe claim ID from pf handoffs claim
--attemptnumberrequiredThe attempt number from the claim
Example
pf handoffs ask <handoff-id> "Which release is this for?" --claim-id runner-1 --attempt 1pf handoffs result <id>Submit your result for review, with up to ten https links as evidence. This never completes the task
Options
--worker-fencestringJSON task lease fence, required when the handoff owns a worker lease
--claim-idstringrequiredThe claim ID from pf handoffs claim
--attemptnumberrequiredThe attempt number from the claim
--summarystringrequiredWhat you found or did, and the next steps
--evidencestringComma-separated https links that back the result
Example
pf handoffs result <handoff-id> --claim-id runner-1 --attempt 1 --summary "Found two risks" --evidence https://example.com/reviewpf handoffs get <id>Read the handoff's instructions, task details, clarifications and context version before approval.
Example
pf handoffs get <handoff-id> --jsonpf handoffs approve <id>Approve requested work as the person who receives the handoff.
Options
--context-versionnumberThe contextVersion reviewed; required after refresh or a clarification answer
Example
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-versionnumberThe contextVersion reviewed; required after refresh or a clarification answer
Example
pf handoffs decide <handoff-id> accept
pf handoffs decide <handoff-id> cancel --jsonThe 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
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
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 withrenewevery few minutes, and finishes withresult. 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-contextto 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.