Skip to main content
Handoff continues the current work in a brand-new top-level TurenOS session — a full left-nav session, not a subagent child. The current agent writes a self-contained continuation brief and calls the handoff_session tool once. TurenOS creates a root session, durably admits the brief as its first message, and starts it immediately. The new session appears in the Agents left navigation and runs independently.

​
UI path

  1. Open any session in the app.
  2. In the session composer, type @ — the @-menu lists handoff with the description “Continue this work in a new top-level session, optionally in another project”.
  3. Select @handoff and describe what should continue (and, if relevant, name another project directory).
  4. The agent writes a continuation brief covering the objective, progress, decisions, relevant files, checks run, blockers, and exact next steps, then calls handoff_session once with a concise title and that complete brief as the prompt.
Handoff entry in the session composer @-menu The new session opens from the Agents left navigation with the brief as its first message and starts immediately.

​
When to use it

  • Use handoff when the current work should continue in a separate session: context is getting long, work moves to another project directory, or you want a clean session with a written brief while the old session stays as history.
  • Stay in this session when the task is small and context is fresh — handoff costs a new session and requires a complete brief.
  • Do not use spawn_agent for this request. Subagents are children of the current task; handoff is a root session with no parent task.
  • Do not use @automations for this request. Automations are durable scheduled workflows that repeat on their own; handoff is a one-shot immediate continuation, never scheduled.
See Subagents for delegating bounded work that stays under the current task.

​
Usage

The tool uses the current project, agent, and resolved model unless you explicitly name another project directory. When a destination project is specified, its absolute path is passed as the optional project argument; otherwise project is omitted to preserve the current-project behavior.
  • title (required): short title for the new session, up to 200 characters. It cannot be empty.
  • prompt (required): the complete standalone continuation brief — objective, progress, decisions, relevant files, checks run, blockers, and next steps. Up to 256,000 characters. It cannot be empty.
  • project (optional): absolute path of the destination project directory. Omit it to stay in the current project.
The call returns the new session_id and message_id plus its title and directory.

​
Limits

  • Handoff is unavailable in task-owned sessions (subagent children cannot hand off further).
  • Handoff requires the handoff_session permission; a denial fails the call without creating anything.
  • A named project must resolve to an existing directory, otherwise the call fails. Directories outside the current project additionally require external-directory permission.
  • The new session always inherits the current agent and resolved model.
  • Calls are idempotent per originating message: retrying the same handoff reuses the same session and brief rather than creating duplicates.