Houston docs

Spawn separate sessions

A subagent reports back into the current turn. spawn_session instead spins off a separate chat that runs in the background.

  • What it gets: the agent hands it a task, optionally on its own git branch and worktree. It starts fresh with its prompt or, with context "fork", with a copy of the spawning chat so far.
  • Never more permissive. It inherits the current approval policy.
  • When it finishes, the chat that started it gets a short report (title, whether it worked, the start of its answer) as a Houston note at the start of its next turn, and you see a notice in the transcript.

In the desktop app

  • It appears in the sidebar with a live indicator, under the chat that started it, seeded with the handed-off context.
  • The arrow beside the parent folds them away. A folded parent shows the most urgent state among them, such as "1 needs input" or "2 running", and Houston remembers what you folded across restarts.
  • A session you pin or move into a group stays where you put it.
  • Its "Handoff from …" banner links back to the parent chat.

In the terminal and headless

Spawned sessions run here too:

  • they run non-interactively, and anything needing an approval is declined automatically
  • they're saved as ordinary conversations you can open later with /resume or --resume <id>
  • a one-shot headless run waits for its spawned sessions before exiting