Skip to content

Agent-initiated launches

This page describes session and workflow launches requested by a running agent.

Agent-Initiated Session Launches

User-initiated launches are direct: prompts submitted through normal launch surfaces, including prompts containing %i(suffix, session=parent), do not require launch approval.

When a running agent requests another launch, SASE creates a typed LaunchApproval request and spawns nothing until a human approves it. Agents use the generated /sase_run skill and submit a structured request:

sase launch request -f launch_request.json -o json

The request may contain %i(suffix, session=parent) in its prompt, so the approved launch joins an existing session with any valid suffix. launch_preview.md shows the resolved launch plan before approval. Inside an agent, the request creates a pending LAUNCH gate turn, hands off the session lane, and ends the requesting turn. Its default requester_continuation.mode is resume_requester: after approval, rejection, timeout, or gate/dispatch failure, one successor resumes the original assignment with the gate decision, feedback, typed launch results, requester identity, workspace/session context, and the recorded checkpoint. A stopped gate remains terminal. Set the mode explicitly to terminal_handoff when the requester truly has no remaining work; no settlement branch then resumes it.

The approved helper prompt and requester continuation cannot both target the requester's session lane. If the stored prompt uses session=parent (or names that same session), target a different session or select terminal_handoff so the lane has one owner. Outside an agent, the request defaults to terminal handoff, prints the creation descriptor, and returns immediately. A script that needs to block can use its request_id with sase gate wait -i <request-id> -k launch -j as a separate step.

Approve or reject from sase's TUI, or use:

sase launch approve <selector>
sase launch reject <selector> [-f <feedback>]

The selector may be a request ID, notification ID, or unique notification prefix. Approval verifies the neutral request bundle, revalidates and replans the stored prompt in its original working directory, and records host dispatch status in the write-once response. A multi-slot launch is all-or-nothing. In-flight requests from the older launch-request layout remain answerable during the compatibility window.

For the complete request schema, preview behavior, slot limits, and dispatch rules, see Launch Approval and sase launch request --help.

sase run

Moved to sase run.

Moved to Agent-initiated launches.

Command behavior

When invoked with no arguments, opens $EDITOR for composing a prompt interactively. When invoked with ., opens a prompt history picker. All prompts launch as detached background agents, and multi-prompt queries (containing --- separators) are launched as sequential detached background agents.

From an interactive terminal outside an agent or durable proc, a prompt whose %hold preview combines future with scope=host prints the preview and asks Arm this hold? [y/N]. An over-threshold pending capture also asks when the preview can resolve project context; typed launch plans can do so, while a plain project-scoped sase run prompt currently cannot and skips this confirmation. Declining prints Hold not armed; launch cancelled. and exits 1. Despite that prompt text, accepting only permits the launch during the current beta; it does not arm the hold.

Daily Operation

Flag and option details live in the generated CLI command groups:

Workflows: TUI, Scheduler, Monitors, Prompt history, VCS, Notifications, Macros.

sase stitch list --origin ORIGIN accepts stitch, auto, or manual; repeat the flag to OR multiple origins. sase stitch list --format json includes the same canonical value as each commit's "origin" field.

sase run launches detached background agents that appear in sase's TUI Agents tab. It can start from prompt text, macro or workflow references, the editor, or the prompt-history picker, and multi-prompt input expands into sequential background launches. sase's TUI uses the same launch machinery when users start agents from the TUI. When sase run is used from an interactive terminal (not from inside an agent or a durable proc) and its %hold preview is broad, it prints the preview and asks Arm this hold? [y/N]; declining cancels the launch and exits 1. A host-scoped hold that includes future is always broad. A pending hold is broad when its live capture exceeds agent_hold_confirm_capture_threshold, but that check needs project context: typed launch plans can resolve it, while a plain project-scoped sase run prompt currently cannot and therefore skips this confirmation. Once accepted, the launch submission pre-arms the hold before admission can race ahead, then rebinds ownership to the launched runner. Narrow and non-interactive holds use that same pre-arm path without the extra prompt.

The short option -n is not one flag across commands: sase agent kill -n NAME and sase agent hold create -n NAME are --name (for kill it is required; a bare name is a usage error), sase agent drain -n and sase agent restart -n are --dry-run (the agent name or provider is positional), and sase monitor start -n is --next. Likewise, sase agent wait -a is --all: it snapshots the eligible agents running when the wait starts, while sase agent list -a means include recent completed agents in a list view. sase agent hold create -p is --pending, not --project.

Moved to Launch directives.

Moved to Agent Auto-Restart.

Moved to Query Language Reference.

Moved to Agent sessions.

Moved to Agent holds.

Moved to Service host initialization.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.