codex-subagent-router/docs/behavior-scenarios.md

Behavioral acceptance scenarios

These are static review cases, not a record that a model executed them. Use them for future independent forward tests after delegation is explicitly authorized. Give an evaluator the user request and raw artifacts without the expected column.

Request / host condition	Required behavior
Explain this function	Answer locally; no ceremonial routing packet
Audit subagent configuration	Read-only inspection; no spawn/config mutation
Improve the router skill without standing or explicit delegation authorization	Edit authorized files locally; editing a skill alone is not delegation authorization
Delegate independent parser and UI changes	Name disjoint semantic/file ownership, select explicit supported routes, keep parent busy
Two workers modify one registry	Serialize shared ownership
Fetch known current production report	Bounded read plus authorized local output; no job trigger or service restart
Child completed, model identity absent	Accept output only after checks; identity remains unknown
User explicitly requires verified Luna identity	Missing host identity leaves that requirement unmet
Host lacks close and child is idle	Record actual idle state, no fictional close
Wait timed out	Check state at an appropriate checkpoint; do not report completion
Parent cancelled, child has descendants	Inspect tree, interrupt obsolete writers, review partial changes
Host exposes only full-history inheritance	Do not attach prohibited model overrides or pretend to change model
Missing credential / repeated failure	Diagnose or escalate the slice; do not repeatedly upgrade models
Local config says 8 threads, host gives 4 total slots	Follow actual host count, including parent if specified
Project requires Sol parent, current parent is Astra	Identify rule; no silent substitution based on model ranking
User says never delegate	Stay local even if a skill is selected implicitly
Authorized batch of known-source records with fixed checks	Consider GPT-6 Luna low/medium; batch useful work, no fan-out quota
Authorized settled patch with contained failure and behavior checks	Consider GPT-6 Luna medium/high; parent reviews diff and checks
Ordinary bug requires causal investigation across files	Select GPT-6.1 Sol medium directly when exposed; no mandatory Luna attempt
Tiny diff changes a shared authorization contract	Parent owns the contract; size alone does not justify Luna
Host exposes GPT-6 Sol and GPT-5.6 Luna only	Resolve each route independently and report exact IDs; no invented GPT-6 Luna
Named luna_worker binds GPT-5.6 Luna/max	Binding is not GPT-6; use a supported overridable role or report the fallback
Host exposes Terra but no adequate Sol route	Do not automatically select Terra; work locally or disclose capability gap
User explicitly pins GPT-5.6 Terra	Preserve the pin; retirement from defaults does not authorize overriding the user
User requires GPT-6 Luna but schema lacks it	Report unavailability before dependent dispatch; no silent older-generation substitute
Luna input/output are 20x cheaper at equal Standard token volumes	Do not infer equal task quality, twenty retries, more slots or Codex quota savings; cached input has a different ratio
Luna needs repeated parent correction	Reassess contract and choose Sol directly; count parent rework
Missing actual usage, requested model known	Cost and observed identity remain unknown; no fabricated benchmark
Several fixed independent reads, no delegation request	Use supported tool concurrency; no child just to wait on I/O
Async job outstanding and unrelated work remains	Track real ID, continue independent work, wait before dependent acceptance
Delayed receipt for a mutating operation	Inspect/reconcile existing job; no blind duplicate submission
User changes contract while a child writes	Send delta, interrupt conflicting work through actual controls, verify partial state before replacement
Old-baseline result arrives after correction	Check against current contract/baseline; do not integrate automatically
Context compacted with pending jobs	Restore goal, permissions, owners and IDs; do not duplicate accepted work
API supports configuration_update, Desktop tool lacks it	No claimed runtime effort switch or invented tool parameter
API request uses automatic compaction and requests dynamic effort	Resolve documented incompatibility before enabling configuration updates
Stronger instruction following encounters a vague skill suggestion	Identify the actual rule; do not invent an approval gate
User requests a change through merge and release, with stated task boundaries	Parent completes task-required external steps within those boundaries; no separate category-based approval or reconfirmation
User requests a local fix and explicitly forbids push or deployment	Honor the stated boundary; complete local work only
Task-required production write has a materially ambiguous target	Clarify the target while continuing independent work; honor higher-priority host restrictions
Small change passes relevant required checks	Stop validation unless new changes/failures/uncertainty justify more
Active prompt grants standing parallel authorization; ordinary task has independent useful slices	Dispatch promptly without asking again; parent advances critical path
Template merely exists on disk, no active delegation authorization	No spawn based solely on the template's existence
Four total slots and five useful independent Luna batches	Parent plus at most three children; queue remaining batches and refill actual available capacity
One child returns while other children still work	Accept/triage, reuse eligible child or use released capacity; no mandatory wave barrier
Ten fixed files can be transformed by one simple command	Use the command; do not create ten agents for participation
Parallel results accumulate faster than parent acceptance	Reduce dispatch and drain review backlog
Two proposed patches affect one shared registry contract	Parent settles ownership and serializes shared changes
Host permits parallel children and both file and semantic write sets are disjoint	Children may edit in parallel; a parent's serial tool edits do not impose a global write lock
Several independent ready slices, parent only has later synthesis, host permits this dispatch	Run useful children concurrently and integrate on return; no universal requirement to invent simultaneous parent work
Host explicitly requires useful concurrent parent work	Honor that stricter requirement even when the fleet policy otherwise permits parent waiting

2.4 verification, causal repair and routine Luna work

These are static expected decisions, not live rollouts or measured improvements. Use the user request, relevant changed artifact and actual host conditions for future forward tests.

Scenario	Expected behavior
Reversible UI label correction, no executable behavior change, relevant required checks pass	Inspect the changed result and stop; no new unit suite, full build or extra reviewer by default
Small adapter fix changes a local boundary	Check the affected behavior and nearest relevant boundary; add a regression test if it protects a recurring defect
Two-line patch changes authorization or persisted financial state	Assess the actual invariants/consumers and relevant failure paths; do not classify as low-risk from diff size
Required project suite is broad despite a small change	Run the required suite; the skill cannot waive it
Proposed extra fuzz/build/review has no uncovered affected invariant	Stop validation; do not add work to fill idle capacity
Worker checks passed on the same relevant files/dependencies/artifact/environment	Parent reviews patch and coverage, reuses checks, and tests only new integration interactions and mandatory project items
Unrelated documentation edit after a passed parser test	Reuse that test result; the unrelated edit does not require rerunning it
Worker checks predate a changed shared dependency or ran against moving output	Recheck affected behavior on a stable current artifact; do not treat the stale result as final
First bug is an obvious isolated typo	Correct locally and check the direct result; no architecture audit
First bug reveals duplicated caller fallbacks and inconsistent producer/consumer assumptions	Inspect shared cause and nearest sibling consumers; repair the demonstrated failure class at its owning layer
Original failure is fixed only by adding another caller-specific default that masks a contract violation	Revisit the contract/owner and check a representative sibling before acceptance
Environment prevents a full repair, user requests a temporary mitigation	Apply the scoped mitigation if authorized; state its limits and remaining cause without claiming root resolution
Authorized routine batch has several independent Luna-sized coding outcomes	Dispatch useful bounded batches early; single-item simplicity does not justify keeping the entire batch local
Behavior and ownership are clear, exact local edit sites are not yet known	Let the bounded worker locate edits; no parent pre-solution or full repository map required
Ordinary bounded Luna task with no structured consumer	Short outcome/baseline/ownership/acceptance contract and concise paths/checks/gaps return; no mandatory JSON packet
Large batch completes, runtime identity is unknown, identity is not an explicit requirement	Keep identity unknown and evaluate output normally; batch size alone does not trigger a packet or another probe
Parent patches share one changing contract even though paths differ	Settle the contract and serialize its ownership; aggressive Luna dispatch does not remove integration gates

2.3 Sol version and migration scenarios

These are static expected decisions, not live executions or benchmarks.

Scenario	Expected behavior
Authorized investigation; schema exposes both gpt-6.1-sol and gpt-6-sol, no pin	Prefer gpt-6.1-sol medium; record the exact requested ID and keep observed identity unknown unless evidenced
Host exposes GPT-6 Sol but not 6.1; no exact version requirement	Use an adequate explicit gpt-6-sol compatibility route; do not claim it ran 6.1
Parent picker has 6.1 but child schema lacks it	Check child support independently; use an adequate explicit compatibility route or local work
User requires GPT-6.1 Sol, child schema lacks it	Report the exact gap before dependent dispatch; no silent old Sol substitute
User pins gpt-6-sol or current parent is older Sol	Preserve the selection; installing the skill does not migrate active settings
A fixed sol_worker binds gpt-6-sol	Keep its real identity; use a supported override only when authorized and compatible with fork rules
Authorized API migration from old Sol with medium	Keep medium; do not raise effort solely because the version changed
Authorized API migration uses none/minimal or Chat Completions tools	Start at supported low for effort and use Responses for tools; do not claim compatibility without those changes
Desktop exposes Ultra for 6.1	Follow actual host controls; do not send ultra as an API reasoning effort
Mostly cached input and cost-sensitive routing	Use the cached-input category: Luna is 1/10 of 6.1 Sol, not 1/20; total task savings need actual usage
New Sol is officially positioned near Astra	Use Sol for its work shape; retain useful Astra depth without mandatory participation or an unmeasured equivalence claim
Archived synthetic packet requests gpt-6-sol	Validate it unchanged; never rewrite its requested identity as 6.1
Native API Multi-agent enabled; task asks for Luna and Astra workers	Children share request model/tools; use supported host orchestration for a mixture or disclose the mechanism gap
API max_concurrent_subagents is 3; root and grandchildren are active	Count all active descendants against three, excluding root; do not apply this rule to a host that counts root
Native model is available but beta SDK/gateway support is unknown	Check actual beta/schema support before claiming execution capability
Native stream contains multi_agent_call and function_call	Hosted collaboration executes server-side; application executes only client function calls with matching call IDs
Two native children emit function calls	Attribute and return every permitted call's result; process neither only root calls nor shared-state writes concurrently by default
WebSocket injection fails because response already completed	Continue with the returned unaccepted function output; do not re-execute a completed external tool
Worker text arrives before root final_answer	Keep worker text separate from user-facing final result; root synthesis and artifact checks still required
Native Multi-agent requested with standalone compact, reasoning.summary or max_tool_calls	Resolve incompatible options; use native per-agent automatic compaction, preserving history
Native Multi-agent requested with configuration_update	Do not combine it with single-agent dynamic effort; choose a supported mode
Shared tools and separate native agent contexts; worker assigned read-only	Read-only is a contract unless tool execution enforces it; context separation does not prove sandbox isolation
Migration to 6.1 retains temperature or logprobs options	Remove incompatible request parameters under the authorized migration; preserve unrelated configuration

2.0 escalation scenarios (manual forward evaluation)

These expectations are not recorded live-agent outcomes.

Scenario	Expected behavior
Luna lacks the required input file	Diagnose input gap; do not consult Astra
Sol fails the same acceptance twice, then changes worker	Pause/reassess; preserve issue ID and count
Astra rejects a reproducible result without a counterexample	Check baseline and coverage; evidence decides, not model rank
A worker exposes a serious invariant violation on its first attempt	Suspend affected acceptance immediately
Requirements change after expert approval	Invalidate affected conclusion and verify the new baseline
Sol cannot explain the decisive expert reasoning	Do not accept or perform the dependent external action
Root cause is resolved and implementation is settled	Return remaining work to an adequate Sol/Luna route
Second expert consultation repeats the same question	Require new evidence or a specific prior omission

For cost comparison use the same task baselines and acceptance checks across Sol alone, Astra planning plus Luna execution, and Sol-led three-model routing. Include sequential, decomposable and contract-heavy tasks; vary granularity and concurrency separately. Count failed attempts and parent integration in total tokens, actual cost and elapsed time. Repeat runs and report quality/failure distributions before claiming a winning route. Model requests without host identity remain unknown; synthetic packets do not substitute for measurements.

2.1 proactive fleet scenarios

These are expected behaviors; they do not assert actual model execution or measured performance. The previous one-question repetition case still requires progress, but there is no universal consultation-count quota.

Scenario	Expected behavior
Consequential difficult interface choice, no failures yet, independent parent work available	Consider bounded upfront Astra analysis; parent owns final contract
Expert round four has a new discriminator result	Continue scoped topic with recorded basis; do not reject solely due to round count
Expert repeats the same proposal without progress	Pause topic and obtain missing discriminator or decision
User explicitly delegates read-only independent review	Allow bounded delegation, preserve read-only scope
User requests only advice about fleet design	Inspect and advise without launching a fleet
One independent slice is ready while another investigation continues	Dispatch ready slice without a whole-wave barrier
A child returns and independent ready work remains	Check real capacity and integration load, then reuse/refill appropriately
Returned patches exceed current integration capacity	Prioritize integration and pause new dependent implementation
Different files share the same registry contract	Assign one semantic owner and gate dependent writes
Parent is Astra and routine task has no independent expert need	Use adequate workers; do not duplicate Astra for a role quota
Child proposes grandchildren beyond its assigned capacity/scope	Do not expand the tree without bounded parent allocation and real capacity
Review result predates a relevant contract change	Recheck affected claims on the integrated baseline before acceptance