Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / runner-lifecycle-and-inputs

Runner lifecycle and scan inputs

The runner is the control layer for one Strix scan. It turns verified targets and user instructions into an agent run, keeps root and child agents tied to durable state, and brings the run to a safe end after completion, interruption, or failure. See Scan execution lifecycle for the system-wide view and Runtime backends and sessions for sandbox and runtime resource ownership.

Execution model

Scan orchestration

The scan runner coordinates the whole engagement from run setup to teardown. It prepares a run record and state area, restores prior agent state when needed, starts the runtime session, connects optional MCP services, creates the root agent, and drives the root execution loop. Child agents use the same scan controls while keeping their own task and session.

The normal execution path follows this sequence:

flowchart TD
    A[Verified scan inputs] --> B[Run state and logging]
    B --> C[Runtime session]
    C --> D[Root agent and session]
    D --> E[Agent turns and child agents]
    E --> F{Lifecycle result}
    F -->|finish| G[Persist final report]
    F -->|wait or user input| E
    F -->|budget, interrupt, or failure| H[Settle state]
    G --> I[Cancel descendants and close sessions]
    H --> I
    I --> J[Release runtime resources]

The root agent is the scan owner. It must use the final scan action to persist the customer-facing report. A child agent instead sends a completion report to its parent. The runner treats a plain text turn as unfinished work so that a scan does not appear complete without an explicit lifecycle action. Optional MCP connections add external tools to the run, but a missing or failed connection does not stop the scan.

References: strix/…/runner.py• L182-217 strix/…/runner.py• L274-323 strix/…/runner.py• L343-482 strix/…/runner.py• L503-588 strix/…/runner.py• L609-659 strix/…/execution.py• L451-570 strix/…/tool.py• L82-106 strix/…/tools.py• L518-636

Scan inputs

Scan inputs define both what the agent may assess and what information it may use. The root task presents repositories, local codebases, web applications, IP addresses, and API specifications as distinct target classes. User-provided workspace files remain read-only context. They do not become targets or instructions.

The input model keeps authority clear:

InputRole in the scan
Verified targetDefines authorized assessment scope
API specificationDefines API operations and can authorize its declared base URLs
Working directory mountGives the agent a place to work without granting assessment scope
Workspace fileSupplies read-only data for the task
User instructionAdds task guidance but cannot expand verified scope
Diff scopeNarrows code review work to changed files and gives deleted files context-only status
Extra workspace fileAdds run data at a workspace path without changing assessment scope

The runner builds a separate scope context for the system prompt. This prevents an instruction or a mounted directory from silently changing the authorized target set. A resume keeps the same scan inputs and can add a new resume instruction as a fresh user message. Root-only prompt additions remain subordinate to the verified scope, while child agents receive the standard scan context.

References: strix/…/inputs.py• L39-105 strix/…/inputs.py• L108-190 strix/…/inputs.py• L193-244 strix/…/runner.py• L204-217 strix/…/runner.py• L378-382 strix/…/runner.py• L459-501 strix/…/runner.py• L549-570

Path and workspace handling

Path handling gives each scan a stable local identity and a predictable workspace view. The run name maps to a directory under strix_runs; its state area holds the agent snapshot and session database used for resume. Preparation attaches cloned repositories, local sources, staged API specifications, optional workspace mounts, and extra files to workspace paths before the runtime starts.

The working directory mount has a deliberate boundary. It is available for work but is excluded from authorized targets and diff context. This lets an instruction-driven run operate on a directory without treating every file in that directory as an asset to test.

References: strix/…/paths.py• L8-28 strix/…/scan_setup.py• L164-220 strix/…/scan_setup.py• L239-267 strix/…/runner.py• L223-235 strix/…/runner.py• L315-322 strix/…/runner.py• L328-338

Lifecycle control

Lifecycle state

The coordinator is the single source of truth for agent graph state, runtime handles, mailboxes, errors, and resume snapshots. Each agent has a parent relationship and a state that tells the runner whether it should execute, wait, stop, or report a terminal result.

StateMeaning
runningThe agent may take another execution turn
waitingThe agent is paused for a user or another agent
completedThe agent finished its assigned work
stoppedThe agent ended before completion by limit or control action
failedThe agent ended with a handled execution error
crashedThe agent ended with an unexpected error
budget_pausedAn interactive agent waits for the user to extend the budget

State changes wake relevant runtimes and are written to the coordinator snapshot. The parent receives one terminal notice when a child cannot provide its normal completion report. This prevents a parent from waiting for work that can no longer finish.

References: strix/…/agents.py• L25-65 strix/…/agents.py• L149-169 strix/…/agents.py• L246-299 strix/…/agents.py• L466-530 strix/…/execution.py• L924-985

Hook controls

Run hooks connect each model turn to usage accounting and scan limits. Before a turn, they add warnings as the turn or shared cost budget approaches its limit. After a turn, they record model usage and enforce the applicable limit.

Autonomous scans stop at the shared cost limit. They stop child agents at a reserve threshold so the root agent can still produce its final report. Interactive scans pause at the limit instead. A user message can extend the budget and wake paused agents. The same rules are recomputed when a scan resumes so old state does not grant an incorrect budget.

References: strix/…/hooks.py• L32-57 strix/…/hooks.py• L114-141 strix/…/hooks.py• L142-178 strix/…/hooks.py• L180-223 strix/…/hooks.py• L225-273 strix/…/runner.py• L369-377 strix/…/runner.py• L287-298

Session-bound execution

Each agent is bound to a durable SDK session. The session preserves the agent's conversation and task input, while the coordinator controls when messages enter that session and when an active stream may be interrupted. Root and child sessions share the scan's session database but use separate agent identities.

Messages from users and peers enter a mailbox first. The coordinator drains that mailbox into the target agent's session before the next run cycle. This separates delivery and execution, which lets an interactive user wake a waiting agent or interrupt its current turn without losing the conversation history. A child receives its inherited context and task as one new user message, which keeps the child identity and task distinct from the parent conversation.

References: strix/…/sessions.py• L27-57 strix/…/agents.py• L278-360 strix/…/execution.py• L186-238 strix/…/execution.py• L988-1046 strix/…/inputs.py• L338-373 strix/…/tool.py• L17-114 strix/…/tools.py• L231-404

Recovery behavior

Turn recovery

The execution loop requires an explicit lifecycle tool call to settle a turn. If an agent returns text without such a call, the runner adds a focused continuation request and retries within a bounded recovery count. An autonomous agent that exhausts this count becomes crashed. An interactive agent is parked so a human can send a message to unblock it.

Waiting has two forms. A user wait has no automatic resume because only a user can provide the needed input. A wait for other agents can resume when a message arrives, but repeated idle resumes are capped so a stalled graph does not spend turns forever.

References: strix/…/execution.py• L451-570 strix/…/execution.py• L573-603 strix/…/agents.py• L198-244 strix/…/tool.py• L104-114 strix/…/tools.py• L347-375

Failure recovery

The runner distinguishes recoverable request problems from scan-ending errors. It can retry transient provider or network errors with backoff, remove rejected images from a session, or compact an overflowing context before it tries the turn again. A failed streamed turn is salvaged into the session when possible so a later resume retains the work already produced.

Permanent provider refusals and other unrecoverable errors settle the agent and notify its parent. A user interrupt is different: it leaves the root in running state and re-raises the interruption so the saved run can resume. A real crash marks the root as failed.

References: strix/…/execution.py• L122-174 strix/…/execution.py• L643-815 strix/…/sessions.py• L101-174 strix/…/sessions.py• L177-214 strix/…/runner.py• L610-639 tests/test_runner_interrupt.py• L64-108

Teardown sequence

Teardown protects both active work and runtime resources. The runner first cancels descendant tasks, then closes agent sessions and optional MCP sessions, writes the last coordinator snapshot, and releases the sandbox when cleanup is enabled. This order prevents a child from using a session after the session has closed.

Cleanup runs for normal completion, budget stops, interruptions, and failures. Interactive waiting can keep the scan resumable, while explicit cleanup controls whether the runtime is released at the end of that invocation.

References: strix/…/runner.py• L640-659 strix/…/agents.py• L374-394 strix/…/test_runner_teardown.py• L60-93

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the target task text and scope context aligned. A new target type must appear in both the agent-facing task and the authorization context.
  • Preserve the distinction between workspace mounts, workspace files, extra workspace files, and authorized targets when changing input preparation or resume records.
  • Keep root instruction overrides subordinate to the verified scope. Do not let extra prompt context replace built-in authorization keys.
  • Keep terminal lifecycle tools aligned with runner recovery. A new terminal action must settle state and prevent parents from waiting for a report that will not arrive.
  • Keep coordinator snapshot fields compatible with resume logic. State, mailbox, wait reason, and recovery counters affect whether agents restart or remain parked.
  • Preserve the ordering of descendant cancellation, session close, snapshot, and runtime cleanup. Reordering these steps can lose history or leave a child using a closed session.
  • When changing budget behavior, update both hook decisions and resume-time budget flag reconstruction so interactive and autonomous scans keep their distinct controls.
  • Keep optional MCP connection setup fail-open and keep its status output non-secret. Connection status must stay consistent for both live interfaces and resumed run viewers.

Important failure modes

TriggerConsequenceGuard
A root turn ends without the final lifecycle actionAutonomous execution may exhaust recovery without producing the final reportRequire an explicit lifecycle tool and bound continuation attempts
A child stops without a completion reportThe parent can wait for a message that will never arriveSend one terminal notice for every terminal child state
A mounted working directory or extra file is treated as a targetThe agent may assess data outside the verified scopeKeep workspace inputs outside target records and scope authorization
A provider rejects the current session inputThe same invalid history can fail every retryStrip rejected images and retry only within the recovery bound
A transient provider or network error interrupts a streamed turnA useful turn can be lost or the scan can fail too earlyRetry transient errors with bounded backoff and salvage stream history
A child reaches the autonomous budget reserveThe root may lack cost or turns to write its final reportStop child work before the shared hard limit
A user interrupt is recorded as a failureResume can be blocked or report the wrong scan statePreserve running for interruption and use failed for real crashes
Descendant sessions close before descendant tasks stopActive children can crash while writing their last historyCancel and await descendants before closing sessions
An MCP server fails during setupOptional external tools are unavailable, but the scan must still runTreat MCP setup as optional and continue without failed connections

Key files

FileWhy to read it
strix/…/runner.pyPrimary scan coordinator from run setup through final cleanup
strix/…/execution.pyAgent turn lifecycle, child runners, waiting, and recovery policy
strix/…/inputs.pyTarget task, scope authorization, workspace context, and child input rules
strix/…/agents.pyAgent state, parent graph, mailboxes, snapshots, and stop control
strix/…/hooks.pyTurn usage, cost limits, warnings, pauses, and budget stops
strix/…/sessions.pyDurable per-agent history and safe session rewrites
strix/…/scan_setup.pyTarget preparation, path mapping, diff scope, and persisted run inputs
strix/…/tool.pyRoot completion contract and final report handoff
strix/…/tools.pyChild creation, completion reports, waiting, and graceful stops