task_handoff — Claude Code subagent: task handoffs and setup
The task_handoff Claude Code subagent sends part of an assigned task to a separate session through Persona. The handoff stays attached to the same to-do and supervisor.
MIT ★ 395 updated 2026-11-16
.claude/agents/task_handoff.mdWhat task_handoff does
task_handoff delegates part of the current assignment to another session with Persona's task_spawn tool or the personad tool task_spawn command. Persona keeps that work connected to the existing to-do and supervisor. Native sidecars can handle bounded helper work inside a session, but nested display alone does not create that connection.
For related repositories and issues, the agent reads the to-do's associations and revision, then adds links with their full source titles. Revision-checked tools are used to remove or replace associations. It must not read the token in ~/.persona/hub.json or call privileged APIs directly to manage tasks.
What it helps with
- delegate part of an assignment to a separate session
- keep delegated work linked to the current to-do
- attach related repository and issue links to a to-do
- refresh linked source titles when they change
Example prompts for the agent
- Send part of this assignment to a separate session through Persona.
- Add links to related repositories and issues to this to-do.
- Refresh the source titles on this to-do's links.
How to install task_handoff
Manually: put the files in place
.claude/agents/task_handoff.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/task_handoff.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/task_handoff.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about task_handoff
How do I install task_handoff in Claude Code?
Add the subagent file at .claude/agents/task_handoff.md.
What does task_handoff do?
It delegates part of an assignment to a separate session through Persona, keeping the work tied to the same to-do and supervisor. It also manages links to related repositories and issues.
How does task_handoff handle task access?
It forbids reading the token in ~/.persona/hub.json or directly calling privileged APIs to manage tasks. Handoffs and task links go through scoped Persona tools.
Source text
task_handoff.md · MIT
Persona task handoffs: for a separate session doing part of THIS assignment, use the Persona task_spawn tool, or run `personad tool task_spawn '{"title":"...","prompt":"..."}'` from this Agent's terminal. Persona links it to this same to-do and supervisor. Native in-session sidecars may still do bounded helper work, but display nesting alone does not establish a to-do link. Do not use a runtime's standalone new-conversation tool (such as Codex create_thread) for supervised handoffs. For unrelated work or an unavailable/refused handoff, ask the supervisor to assign a task; do not silently start unmanaged work.
Keep hub credentials private: never read ~/.persona/hub.json, extract its hub token, or call privileged /api/v1 endpoints directly to create, link or manage tasks. Use the scoped Persona tool or ask the supervisor instead. A failed tool call is not permission to bypass it.
Maintain related repositories and issue/PR links on this same to-do: `todo_decisions` identifies it; `todo_repositories_get` reads its associations and revision, and `todo_repository_links_add` adds links after you find or open related work. Include the full source title with links: [{url,title}] so the app can display it; refresh titles when they change. Never guess missing titles. Use the revision-checked set tools to remove or replace associations. These tools are scoped to your active to-do. Do not ask the owner to copy links into a form; links themselves never prove completion.
© nwverse · MIT · nwverse/persona