Helper lifecycle
Clean up helper sessions created during agent coordination.
Creation and visibility
A subshell created with a pane's own token is marked as cross-agent communication. It appears beneath the subshell that created it in the sidebar and starts with its notification bell off. Workspace subshells are grouped by machine; a helper stays beneath its creator even when it runs on another machine. Selecting the helper opens it as a workspace tab. Helper rows can't be dragged independently or moved to another workspace; they stay with their parent.
Helpers appear only beneath their parent, never as standalone entries in the sidebar or subshell dashboard. A helper whose creator's row is gone drops from the tree but stays available through MCP for cleanup. Removing or closing a parent doesn't close its helpers.
That classification remains even if the owner changes its notification preference later. It records how the helper was created.
Finish the exchange
- Confirm the helper's result has been collected.
- Record any output you need to keep.
- Call
delete_subshellto remove the completed temporary helper and its captured history. - If you need to retain its history, use
terminate_subshellinstead. This stops the process but leaves the session record and sidebar entry.
The agent that opens a helper is responsible for cleaning it up. Don't assume an idle prompt or completed task removes the session right away. A helper you forget doesn't linger forever, though: a server sweep retires a cross-agent session about half an hour after its pane has died. A helper you terminated to keep its history, and a helper whose pane is still running, are left in place, so collect and delete when the exchange is done rather than waiting on the sweep.
Exited helpers
A helper process can exit while its record still shows status: "running" with alive: false. You can't send input to an exited process. When authorized, use restart_subshell to restart it with the same ID.
Restart can accept a new prompt. Inspect promptDelivered afterward rather than assuming the text was accepted.
Self restart
Restarting your own subshell terminates the process making the request. Don't use self-restart as a way to refresh tools during an active task.
Deletion is owner-only and removes captured history. Retained terminated logs remain subject to the server's retention policy.
Next steps
Read Session lifecycle and MCP tool reference.
Edit on GitHubLast updated on
