Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
feat(profiles): route sub-agent requests to a profile-level subagent_target (#112)
Lin Jia060ad758fe50
diff --git a/.agents/skills/dco-signoff/SKILL.md b/.agents/skills/dco-signoff/SKILL.mdnew file mode 100644index 000000000..8a6728395--- /dev/null+++ b/.agents/skills/dco-signoff/SKILL.md@@ -0,0 +1,109 @@+---+name: dco-signoff+description: Fix missing DCO (Developer Certificate of Origin) sign-off on branch commits and prevent the issue going forward. Use when CI reports a DCO check failure, a PR is blocked by "Signed-off-by missing", or a collaborator asks you to add sign-off to commits.+---++# DCO Sign-Off++Every commit merged into Switchyard must carry a `Signed-off-by` trailer:++```+Signed-off-by: Your Name <[email protected]>+```++This is enforced by the DCO bot on every pull request. A branch with any commit missing this trailer will be blocked from merge.++## Detect missing sign-offs++Check which branch commits are missing the trailer:++```bash+git log origin/main..HEAD --format="%H %s" | while read sha msg; do+ if ! git show -s --format="%B" "$sha" | grep -q "^Signed-off-by:"; then+ echo "MISSING: $sha $msg"+ fi+done+```++If the output is empty, all commits are already signed and no action is needed.++## Fix: add sign-off to all branch commits++Rebase the branch onto `origin/main`, adding `--signoff` to retrofit the trailer on every commit:++```bash+git rebase origin/main --signoff+```++Then push. Because a rebase rewrites SHAs, you must force-push:++```bash+git push --force-with-lease origin HEAD+```++`--force-with-lease` is safer than `--force`: it aborts if the remote has received new commits since your last fetch, protecting against overwriting a collaborator's work.++### When the rebase hits a conflict++Resolve each conflict normally, then continue:++```bash+git add <resolved-files>+git rebase --continue+```++The `--signoff` flag was set at rebase-start; `--continue` applies it to each commit as it lands. You do not need to pass `--signoff` again.++## Prevent it going forward++Pass `-s` (shorthand for `--signoff`) on every `git commit`:++```bash+git commit -s -m "type(scope): your message"+```++Or add it to the repo's local git config so it is applied automatically:++```bash+git config commit.gpgSign false # unrelated — don't confuse with signoff+```++There is no `commit.signoff = true` git config option; the `-s` flag must be used explicitly each time, or the workflow must always pass it. The safest habit is to include `-s` in every `git commit` invocation.++## What a correct trailer looks like++```+fix(protocol): correct sub-agent detection for Claude Code++Signed-off-by: Lin Jia <[email protected]>+```++The name and email must match the contributor's Git identity (`git config user.name` and `git config user.email`). A mismatch causes the DCO bot to reject the commit even when the trailer is present.++## Verify the fix++After rebasing and pushing, confirm locally before relying on CI:++```bash+git log origin/main..HEAD --format="%H %s%n%b" | grep -E "(^[0-9a-f]{40}|Signed-off-by)"+```++Every commit SHA should be followed by a `Signed-off-by:` line.++## Boundaries++### Always do++- Use `--force-with-lease` instead of `--force` when pushing a rebased branch.+- Verify that `git config user.name` and `git config user.email` match the expected identity before adding sign-off — a mismatch is caught by the DCO bot.+- Run the detection check first; if all commits already have sign-off, do nothing.++### Ask first++- Rebasing a branch that has open review comments attached to specific commit SHAs — the rewrite makes those comments orphaned on GitHub.+- Force-pushing a branch that is also used by another collaborator's local checkout.++### Never do++- Force-push `main` or any protected branch to add sign-off. The correct fix for a merged commit is to ensure future commits are signed; retroactive rewriting of main history is not possible.+- Use `--no-verify` to skip the DCO pre-push hook if one is configured — that bypasses the gate without fixing the root cause.diff --git a/.agents/skills/switchyard-lib-core/SKILL.md b/.agents/skills/switchyard-lib-core/SKILL.mdindex 7a1207663..7bf5268bd 100644--- a/.agents/skills/switchyard-lib-core/SKILL.md+++ b/.agents/skills/switchyard-lib-core/SKILL.md@@ -39,6 +39,7 @@ right validation set. If the change is driven by a launcher need, also read| An OpenAI-compatible provider target such as NVIDIA Inference Hub or OpenRouter | Use the existing OpenAI-compatible backend/profile with `base_url`, `api_key`, and model id wiring. Add a new backend only when the provider has a real wire-format, auth, retry, or health contract that cannot fit that path. || Direct Rust component bindings | Add concrete PyO3 classes under `crates/switchyard-py/src/component_bindings/`, keep config bindings near the component binding that consumes them, and expose them lazily from `switchyard_rust/components.py`. Do not keep growing `core_bindings.rs` or `switchyard_rust/core.py` with concrete component classes. || Route YAML / model dispatch | Use `switchyard/cli/route_bundle.py` and `switchyard/lib/route_table_builders.py`. They build `RouteTable` entries from profile-backed runtimes and keep launchers plus `switchyard serve --routing-profiles` on one path. |+| Route sub-agent traffic to a fixed worker target | Set `subagent_target: <target-id>` in any profile's common envelope (consumed like `type` in Rust `SerializedProfileConfig`, `crates/switchyard-components-v2/src/config/parsing.rs`). The Python loader (`switchyard/lib/profiles/loader.py`) wraps the built profile in `SubagentOverrideProfile`; detection is the Rust-bound `is_subagent_request(headers)` from `switchyard_rust.profiles`, a thin wrapper over `Metadata::from_headers` + `Metadata::is_subagent_work` in `crates/protocol/src/metadata.rs` (the canonical lineage fact and work-vs-maintenance policy). On the libsy `Algorithm` path, wrap with the `SubagentOverride` combinator (`crates/libsy/src/algorithms/subagent_override.rs`; Python: `switchyard.libsy.algorithms.subagent_override`). Do not re-implement header sniffing inside individual profiles or algorithms. || Shared/persistent session-affinity pins across workers or pod churn | Configure the latency route with `session_affinity: true` + `affinity_store: redis` + `affinity_store_url` (optional `affinity_store_ttl_seconds`, `affinity_key_prefix`); the escalation_router route takes the same `affinity_store*` keys (no `session_affinity` flag — its latch is always on; default prefix `swyd:esc:`). `SessionAffinity` keeps the Rust `SessionCache` as L1 and reads/writes through the `AffinityPinStore` L2 (`switchyard/lib/redis_pin_store.py`), fail-open behind a 0.1s socket timeout and a 3-failure/10s-cooldown circuit breaker (`switchyard_affinity_l2_breaker_open` gauge). Requires the `switchyard[affinity-redis]` extra. || Stats / telemetry | Reuse `StatsRequestProcessor`, `StatsResponseProcessor`, `StatsLlmBackend`, and `StatsAccumulator`. A profile config should thread one accumulator through all three when stats are enabled. Do not write a parallel collector. || A fixed-path endpoint contributed by per-route components | Set `Endpoint.register_once = True`; `build_switchyard_app(...)` mounts the first instance while still running every component's lifecycle. Leave the default `False` for configurable endpoint classes that may mount distinct instances. |diff --git a/Cargo.lock b/Cargo.lockindex 9f7955951..b10531a52 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1687,6 +1687,7 @@ dependencies = ["switchyard-components","switchyard-components-v2-macros","switchyard-core",+ "switchyard-protocol","tokio","toml","tracing",@@ -1772,6 +1773,7 @@ dependencies = ["switchyard-components-v2","switchyard-core","switchyard-libsy",+ "switchyard-protocol","switchyard-translation","tokio","tracing",diff --git a/crates/libsy/src/algorithms.rs b/crates/libsy/src/algorithms.rsindex 4f1522931..c2b500704 100644--- a/crates/libsy/src/algorithms.rs+++ b/crates/libsy/src/algorithms.rs@@ -10,8 +10,10 @@ pub mod fall_through;pub mod llm_class;pub mod noop;pub mod rand;+pub mod subagent_override;pub use fall_through::{FallThrough, FallThroughDecision};pub use llm_class::{ClassifierDecision, ClassifierTier, LlmClassifier};pub use noop::{Noop, NoopDecision};pub use rand::{Random, RandomDecision};+pub use subagent_override::{SubagentDecision, SubagentOverride};diff --git a/crates/libsy/src/algorithms/subagent_override.rs b/crates/libsy/src/algorithms/subagent_override.rsnew file mode 100644index 000000000..599213b1f--- /dev/null+++ b/crates/libsy/src/algorithms/subagent_override.rs@@ -0,0 +1,208 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Sub-agent override combinator built on the [`Algorithm`] interfaces.+//!+//! Wraps any algorithm without changing its behavior for normal traffic. A+//! request whose [`Metadata`] marks delegated sub-agent work+//! ([`Metadata::is_subagent_work`]) is served by one fixed worker target —+//! keeping a sub-agent loop on an intentional, cache-compatible target —+//! while every other request delegates to the wrapped algorithm. The wrapped+//! algorithm never learns about harnesses or lineage headers, and a worker+//! failure surfaces as a normal target error rather than re-entering the+//! wrapped algorithm.++use std::error::Error;+use std::sync::Arc;++use async_trait::async_trait;++use crate::{Algorithm, Context, Decision, Driver, LlmTarget, Metadata, Request, Response};++/// Decision produced by [`SubagentOverride`] when it routes to the worker target.+pub struct SubagentDecision {+ /// The fixed worker target selected for the sub-agent request.+ pub selected_model: String,+ /// Human-readable explanation of the override.+ pub reasoning: String,+}++impl Decision for SubagentDecision {+ fn selected_model(&self) -> &str {+ &self.selected_model+ }++ fn reasoning(&self) -> Option<&str> {+ Some(&self.reasoning)+ }++ fn as_any(&self) -> &dyn std::any::Any {+ self+ }+}++/// Routes delegated sub-agent work to a fixed worker target; delegates the rest.+pub struct SubagentOverride {+ inner: Arc<dyn Algorithm>,+ worker: LlmTarget,+}++impl SubagentOverride {+ /// Wraps `inner`, sending recognized sub-agent work to `worker` instead.+ ///+ /// Wrap it in an [`Arc`] and drive it with [`Algorithm::run`] or+ /// [`Algorithm::run_stream`].+ pub fn new(inner: Arc<dyn Algorithm>, worker: LlmTarget) -> Self {+ Self { inner, worker }+ }+}++#[async_trait]+impl Algorithm for SubagentOverride {+ async fn create_run_task(+ self: Arc<Self>,+ ctx: Context,+ driver: Driver,+ request: Request,+ ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ let is_subagent_work = request+ .metadata+ .as_ref()+ .is_some_and(Metadata::is_subagent_work);+ if !is_subagent_work {+ return Arc::clone(&self.inner)+ .create_run_task(ctx, driver, request)+ .await;+ }++ let selected = self.worker.semantic_name.clone();+ let decision: Arc<dyn Decision> = Arc::new(SubagentDecision {+ reasoning: format!("sub-agent work routed to fixed worker target '{selected}'"),+ selected_model: selected,+ });+ driver.info(ctx.clone(), Arc::clone(&decision)).await?;+ driver+ .call_llm_target(ctx, &self.worker, request, decision)+ .await+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::collections::BTreeMap;++ use switchyard_protocol::{completion_text, text_request, text_response};++ use crate::algorithms::Random;+ use crate::{LlmResponse, LlmTargetSet, RoutedLlmClient};++ /// Echoes the selected target so tests can inspect which target was called.+ struct EchoClient;++ #[async_trait]+ impl RoutedLlmClient for EchoClient {+ async fn call(+ &self,+ _ctx: Context,+ _request: Request,+ decision: Arc<dyn Decision>,+ ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ Ok(Response {+ llm_response: LlmResponse::Agg(text_response(None, decision.selected_model())),+ metadata: None,+ })+ }+ }++ fn target(name: &str) -> LlmTarget {+ LlmTarget {+ semantic_name: name.to_string(),+ llm_client: Some(Arc::new(EchoClient)),+ }+ }++ fn request(headers: &[(&str, &str)]) -> Request {+ let metadata = (!headers.is_empty()).then(|| {+ Metadata::from_headers(+ &headers+ .iter()+ .map(|(name, value)| ((*name).to_string(), (*value).to_string()))+ .collect::<BTreeMap<_, _>>(),+ )+ });+ Request {+ llm_request: text_request(Some("auto".to_string()), "hi"),+ raw_request: None,+ metadata,+ }+ }++ /// Wraps single-target random routing so the inner selection is deterministic.+ fn algorithm() -> Arc<dyn Algorithm> {+ let inner: Arc<dyn Algorithm> =+ Arc::new(Random::new(LlmTargetSet::new(vec![target("orchestrator")])));+ Arc::new(SubagentOverride::new(inner, target("worker")))+ }++ async fn selected_model(+ headers: &[(&str, &str)],+ ) -> Result<String, Box<dyn Error + Send + Sync>> {+ let (trace, response) = algorithm()+ .run(Context::default(), request(headers))+ .await?;+ let selected = response+ .llm_response+ .as_agg()+ .map(completion_text)+ .unwrap_or_default();+ assert_eq!(+ trace.last().map(|d| d.selected_model().to_string()),+ Some(selected.clone())+ );+ Ok(selected)+ }++ #[tokio::test]+ async fn requests_without_metadata_delegate_to_the_wrapped_algorithm(+ ) -> Result<(), Box<dyn Error + Send + Sync>> {+ assert_eq!(selected_model(&[]).await?, "orchestrator");+ Ok(())+ }++ #[tokio::test]+ async fn subagent_work_is_routed_to_the_worker_target(+ ) -> Result<(), Box<dyn Error + Send + Sync>> {+ // Claude Code child-agent lineage.+ let claude = &[+ ("x-claude-code-session-id", "root"),+ ("x-claude-code-agent-id", "child-1"),+ ];+ assert_eq!(selected_model(claude).await?, "worker");++ // Codex delegated-work kinds.+ assert_eq!(+ selected_model(&[("x-openai-subagent", "review")]).await?,+ "worker"+ );+ assert_eq!(+ selected_model(&[("x-openai-subagent", "collab_spawn")]).await?,+ "worker"+ );+ Ok(())+ }++ #[tokio::test]+ async fn harness_maintenance_turns_stay_on_the_wrapped_algorithm(+ ) -> Result<(), Box<dyn Error + Send + Sync>> {+ assert_eq!(+ selected_model(&[("x-openai-subagent", "compact")]).await?,+ "orchestrator"+ );+ assert_eq!(+ selected_model(&[("x-switchyard-is-subagent", "false")]).await?,+ "orchestrator"+ );+ Ok(())+ }+}diff --git a/crates/protocol/src/metadata.rs b/crates/protocol/src/metadata.rsindex a54502766..ae18b3cd7 100644--- a/crates/protocol/src/metadata.rs+++ b/crates/protocol/src/metadata.rs@@ -54,9 +54,8 @@ const CLAUDE_SESSION_ID_HEADER: &str = "x-claude-code-session-id";const CLAUDE_AGENT_ID_HEADER: &str = "x-claude-code-agent-id";const CLAUDE_PARENT_AGENT_ID_HEADER: &str = "x-claude-code-parent-agent-id";-// OpenCode session headers.+// OpenCode session header — used for session_id correlation only (not a routing signal).const OPENCODE_SESSION_ID_HEADER: &str = "x-session-id";-const OPENCODE_PARENT_SESSION_ID_HEADER: &str = "x-parent-session-id";// Generic Codex-compatible correlation headers.const SESSION_ID_HEADER: &str = "session-id";@@ -65,16 +64,10 @@ const TASK_ID_HEADER: &str = "x-task-id";const REQUEST_ID_HEADER: &str = "x-request-id";const CLIENT_REQUEST_ID_HEADER: &str = "x-client-request-id";-/// Header/JSON-path signals that, when any is present, mark a request as a sub-agent.-const SUBAGENT_SIGNAL_PATHS: &[&str] = &[- SWITCHYARD_PARENT_AGENT_ID_HEADER,- RELAY_SUBAGENT_ID_HEADER,- DYNAMO_PARENT_SESSION_ID_HEADER,- CODEX_PARENT_THREAD_ID_PATH,- CODEX_SUBAGENT_KIND_PATH,- CODEX_PARENT_THREAD_ID_HEADER,- OPENAI_SUBAGENT_HEADER,-];+/// Harness-defined sub-agent kinds that carry delegated user work rather than+/// harness maintenance (`compact`, `memory_consolidation`, ...). Unknown kinds+/// are excluded deliberately; extend with captured request fixtures.+const SUBAGENT_WORK_KINDS: &[&str] = &["collab_spawn", "review"];/// Ordered candidate lookup paths for each correlation field, keyed by the field's/// canonical `x-switchyard-*` header name.@@ -172,6 +165,11 @@ pub struct Metadata {pub parent_agent_id: Option<String>,/// Whether the harness identified this request as coming from a child agent.pub is_subagent: bool,+ /// Whether this request carries delegated sub-agent *work* and should be+ /// routed to the sub-agent target. Computed from raw harness signals only,+ /// independent of [`Self::agent_kind`], which may be set by an unrelated+ /// operator label (`x-switchyard-agent-kind`).+ pub is_delegated_work: bool,/// Harness-defined kind of agent call, such as `collab_spawn` or `review`.pub agent_kind: Option<String>,/// Semantic agent role, such as `explorer`, `worker`, or `reviewer`.@@ -199,23 +197,24 @@ impl Metadata {/// Normalizes harness-specific request headers into correlation metadata.////// Explicit `x-switchyard-*` headers win. NeMo Relay and Dynamo correlation- /// headers are accepted without linking either runtime. Codex's structured turn- /// metadata is preferred over its compatibility projections. Claude Code and- /// OpenCode carry their agent lineage in native headers: a Claude Code request- /// naming a distinct `x-claude-code-agent-id` under its session is treated as a- /// child agent (its parent inferred to be the session when not stated). Subagent- /// status is taken from an explicit `x-switchyard-is-subagent` header when- /// present, and otherwise inferred from any parent/child lineage header.+ /// headers are accepted for observability without driving routing. Codex's+ /// structured turn metadata is preferred over its compatibility projections.+ /// Claude Code carries agent lineage in native headers: a request with a+ /// non-empty `x-claude-code-agent-id` is treated as a child agent (its parent+ /// inferred from the session when not stated). Sub-agent routing status is taken+ /// from an explicit `x-switchyard-is-subagent` header when present, and otherwise+ /// inferred from Claude Code lineage or Codex harness signals.pub fn from_headers(headers: &BTreeMap<String, String>) -> Self {let headers = &normalize_headers(headers);- let (parent_agent_id, is_subagent) = parse_sub_agent(headers);+ let (parent_agent_id, is_subagent, is_delegated_work) = parse_sub_agent(headers);Metadata {session_id: sy_header(headers, SWITCHYARD_SESSION_ID_HEADER),agent_id: sy_header(headers, SWITCHYARD_AGENT_ID_HEADER),parent_agent_id,is_subagent,+ is_delegated_work,agent_kind: sy_header(headers, SWITCHYARD_AGENT_KIND_HEADER),agent_role: sy_header(headers, SWITCHYARD_AGENT_ROLE_HEADER),task_id: sy_header(headers, SWITCHYARD_TASK_ID_HEADER),@@ -228,61 +227,76 @@ impl Metadata {..Metadata::default()}}-}-/// Returns `(parent_agent_id, is_subagent)` from the headers-fn parse_sub_agent(headers: &BTreeMap<String, String>) -> (Option<String>, bool) {- let mut is_subagent = false;- let sy_is_sub_agent = header(headers, SWITCHYARD_IS_SUBAGENT_HEADER).and_then(parse_bool);- let mut parent: Option<String> = sy_header(headers, SWITCHYARD_PARENT_AGENT_ID_HEADER);- if let Some(is_sub) = sy_is_sub_agent {- if parent.is_some() {- return (parent, is_sub);- }+ /// Whether this request should be routed to the sub-agent target.+ ///+ /// Returns `self.is_delegated_work`, which is computed in `parse_sub_agent`+ /// from raw harness signals only — independent of `agent_kind`, which may+ /// be populated by an unrelated operator label (`x-switchyard-agent-kind`).+ pub fn is_subagent_work(&self) -> bool {+ self.is_delegated_work}- is_subagent |= sy_is_sub_agent.unwrap_or(false);+}- let (claude_parent, claude_subagent) = claude_lineage(headers);- is_subagent |= claude_subagent;- parent = parent.or_else(|| claude_parent.map(str::to_string));- if is_subagent && parent.is_some() {- return (parent, is_subagent);- }+/// Returns `(parent_agent_id, is_subagent, is_delegated_work)` from the headers.+///+/// Recognized sub-agent signals: Claude Code `x-claude-code-agent-id`, Codex+/// `x-openai-subagent` / `x-codex-turn-metadata.subagent_kind`, and explicit+/// `x-switchyard-is-subagent`. Correlation-only headers (Relay, Dynamo, OpenCode+/// parent sessions) populate observability fields but do not drive routing.+///+/// `is_delegated_work` is computed from raw harness signals, not from `agent_kind`,+/// which may be set by an unrelated operator label (`x-switchyard-agent-kind`).+fn parse_sub_agent(headers: &BTreeMap<String, String>) -> (Option<String>, bool, bool) {+ let explicit = header(headers, SWITCHYARD_IS_SUBAGENT_HEADER).and_then(parse_bool);- parent = parent.or_else(|| opencode_parent(headers).map(str::to_string));- is_subagent = parent.is_some() || is_subagent;- if is_subagent && parent.is_some() {- return (parent, is_subagent);- }+ let (claude_parent, claude_subagent) = claude_lineage(headers);- is_subagent |= SUBAGENT_SIGNAL_PATHS- .iter()- .any(|path| resolve_path(headers, path).is_some());+ // Harness routing signal: Codex turn-metadata kind or flat OpenAI subagent header.+ // `x-switchyard-agent-kind` (operator semantic label) is intentionally excluded.+ let harness_kind = resolve_path(headers, CODEX_SUBAGENT_KIND_PATH)+ .or_else(|| header(headers, OPENAI_SUBAGENT_HEADER).map(str::to_string));++ // Parent resolved via HEADER_CONFIG precedence (covers Dynamo/Codex correlation);+ // falls back to the Claude Code session the child was spawned under.+ let parent = sy_header(headers, SWITCHYARD_PARENT_AGENT_ID_HEADER)+ .or_else(|| claude_parent.map(str::to_string));++ let is_subagent = explicit.unwrap_or(claude_subagent || harness_kind.is_some());++ let is_delegated_work = match explicit {+ Some(false) => false,+ Some(true) => harness_kind+ .as_deref()+ .map(|k| SUBAGENT_WORK_KINDS.contains(&k))+ .unwrap_or(true),+ None => {+ claude_subagent+ || harness_kind+ .as_deref()+ .is_some_and(|k| SUBAGENT_WORK_KINDS.contains(&k))+ }+ };- (parent, is_subagent)+ (parent, is_subagent, is_delegated_work)}/// Claude Code's `(parent_agent, is_subagent)` from its native lineage headers.///-/// A request naming an `x-claude-code-agent-id` distinct from its session is a child-/// agent; its parent is the explicit parent-agent header, else the session it was-/// spawned under. A root agent (no distinct child id) has no parent.+/// Claude Code only sends `x-claude-code-agent-id` for spawned sub-agents and+/// teammates; root agents omit it. Any non-empty value is therefore a+/// sub-agent signal. The parent is the explicit parent-agent header when+/// present, else the session the child was spawned under.fn claude_lineage(headers: &BTreeMap<String, String>) -> (Option<&str>, bool) {let session = header(headers, CLAUDE_SESSION_ID_HEADER);let agent = header(headers, CLAUDE_AGENT_ID_HEADER);- let is_subagent = matches!((agent, session), (Some(a), Some(s)) if a != s);+ let is_subagent = agent.is_some();let parent = is_subagent.then(|| header(headers, CLAUDE_PARENT_AGENT_ID_HEADER).or(session)).flatten();(parent, is_subagent)}-/// OpenCode's parent session, meaningful only alongside its own session header.-fn opencode_parent(headers: &BTreeMap<String, String>) -> Option<&str> {- header(headers, OPENCODE_SESSION_ID_HEADER)- .and(header(headers, OPENCODE_PARENT_SESSION_ID_HEADER))-}-/// Parses the common textual spellings of a boolean header value.fn parse_bool(value: &str) -> Option<bool> {match value.trim().to_ascii_lowercase().as_str() {@@ -393,6 +407,31 @@ mod tests {assert!(!metadata.is_subagent);}+ #[test]+ fn codex_parent_thread_id_alone_is_not_a_subagent_signal() {+ // Parent-thread-id is correlation data, not a routing signal. A Codex+ // turn that carries a parent thread id but no `x-openai-subagent` must+ // not be treated as sub-agent work.+ let headers = BTreeMap::from([(+ CODEX_TURN_METADATA_HEADER.to_string(),+ serde_json::json!({+ "session_id": "root-session",+ "thread_id": "child-thread",+ "parent_thread_id": "root-thread",+ "turn_id": "turn-3",+ // no subagent_kind+ })+ .to_string(),+ )]);++ let metadata = Metadata::from_headers(&headers);+ // Parent id is still captured for observability.+ assert_eq!(metadata.parent_agent_id.as_deref(), Some("root-thread"));+ // But it must not drive routing.+ assert!(!metadata.is_subagent);+ assert!(!metadata.is_subagent_work());+ }+#[test]fn explicit_switchyard_subagent_flag_overrides_inference() {let headers = BTreeMap::from([@@ -425,6 +464,8 @@ mod tests {#[test]fn normalizes_relay_and_dynamo_child_headers() {+ // Relay and Dynamo headers are correlation data, not routing signals.+ // They populate observability fields but must not trigger sub-agent routing.let headers = BTreeMap::from([("x-nemo-relay-session-id".to_string(),@@ -443,13 +484,15 @@ mod tests {let metadata = Metadata::from_headers(&headers);assert_eq!(metadata.session_id.as_deref(), Some("relay-session"));assert_eq!(metadata.agent_id.as_deref(), Some("relay-child"));- assert!(metadata.is_subagent);+ assert_eq!(metadata.parent_agent_id.as_deref(), Some("relay-parent"));+ assert!(!metadata.is_subagent);+ assert!(!metadata.is_subagent_work());}#[test]fn claude_code_agent_lineage_marks_subagent_and_infers_parent() {- // A distinct agent id under a session is a child agent; with no explicit- // parent header its parent is inferred to be the session it was spawned under.+ // Any non-empty agent id is a child agent. Without an explicit parent+ // header the parent is inferred to be the session it was spawned under.let metadata = Metadata::from_headers(&BTreeMap::from([("x-claude-code-session-id".to_string(),@@ -466,6 +509,19 @@ mod tests {assert_eq!(metadata.parent_agent_id.as_deref(), Some("claude-session"));}+ #[test]+ fn claude_code_agent_id_alone_marks_subagent() {+ // The agent-id header is the detection predicate; the session header is+ // correlation data. A request with only agent-id is still a child agent.+ let metadata = Metadata::from_headers(&BTreeMap::from([(+ "x-claude-code-agent-id".to_string(),+ "claude-agent".to_string(),+ )]));+ assert!(metadata.is_subagent);+ assert_eq!(metadata.agent_id.as_deref(), Some("claude-agent"));+ assert_eq!(metadata.parent_agent_id, None);+ }+#[test]fn explicit_claude_parent_agent_overrides_inferred_session() {let metadata = Metadata::from_headers(&BTreeMap::from([@@ -489,9 +545,9 @@ mod tests {}#[test]- fn claude_root_agent_without_distinct_child_is_not_a_subagent() {- // Session but no distinct agent id: a root agent. A stray parent-agent header- // is only meaningful for a distinct child, so it must not leak in.+ fn claude_root_agent_without_agent_id_is_not_a_subagent() {+ // Root agents omit x-claude-code-agent-id entirely. A stray parent-agent+ // header without an agent-id must not mark the request as a child.let metadata = Metadata::from_headers(&BTreeMap::from([("x-claude-code-session-id".to_string(),@@ -509,7 +565,9 @@ mod tests {}#[test]- fn opencode_parent_session_marks_subagent() {+ fn opencode_session_headers_are_correlation_only() {+ // OpenCode's x-session-id / x-parent-session-id are correlation headers;+ // they populate session_id for observability but do not trigger routing.let metadata = Metadata::from_headers(&BTreeMap::from([("x-session-id".to_string(), "opencode-run".to_string()),(@@ -518,14 +576,14 @@ mod tests {),]));assert_eq!(metadata.session_id.as_deref(), Some("opencode-run"));- assert!(metadata.is_subagent);- assert_eq!(metadata.parent_agent_id.as_deref(), Some("opencode-parent"));+ assert!(!metadata.is_subagent);+ assert_eq!(metadata.parent_agent_id, None);}#[test]- fn opencode_parent_ignored_without_opencode_session() {- // The OpenCode parent header only applies with OpenCode's own session header;- // next to a Codex `session-id` it must not surface as a parent.+ fn opencode_parent_header_is_not_a_parent_agent_id_source() {+ // x-parent-session-id is not listed in HEADER_CONFIG for parent_agent_id;+ // it must not surface as a parent regardless of adjacent session headers.let metadata = Metadata::from_headers(&BTreeMap::from([("session-id".to_string(), "codex-run".to_string()),(@@ -603,4 +661,77 @@ mod tests {)]));assert_eq!(metadata.session_id.as_deref(), Some("codex-run"));}++ #[test]+ fn explicit_subagent_flag_decides_without_a_parent_header() {+ // Explicit `false` wins over presence-based inference even when no+ // parent id accompanies it; the flag decides in both directions.+ let metadata = Metadata::from_headers(&BTreeMap::from([+ ("x-switchyard-is-subagent".to_string(), "false".to_string()),+ ("x-openai-subagent".to_string(), "review".to_string()),+ ]));+ assert!(!metadata.is_subagent);++ let metadata = Metadata::from_headers(&BTreeMap::from([(+ "x-switchyard-is-subagent".to_string(),+ "true".to_string(),+ )]));+ assert!(metadata.is_subagent);+ }++ #[test]+ fn operator_agent_kind_does_not_suppress_harness_subagent_routing() {+ // x-switchyard-agent-kind is an operator semantic label and must not filter+ // routing signals from the harness (x-openai-subagent, x-switchyard-is-subagent).+ let with_openai = Metadata::from_headers(&BTreeMap::from([+ ("x-openai-subagent".to_string(), "review".to_string()),+ (+ "x-switchyard-agent-kind".to_string(),+ "researcher".to_string(),+ ),+ ]));+ assert!(with_openai.is_subagent);+ assert!(with_openai.is_subagent_work());++ let with_explicit = Metadata::from_headers(&BTreeMap::from([+ ("x-switchyard-is-subagent".to_string(), "true".to_string()),+ (+ "x-switchyard-agent-kind".to_string(),+ "researcher".to_string(),+ ),+ ]));+ assert!(with_explicit.is_subagent);+ assert!(with_explicit.is_subagent_work());+ }++ #[test]+ fn subagent_work_requires_a_delegated_work_kind_when_kinded() {+ // Kindless lineage (Claude Code child agent) counts as delegated work.+ let claude_child = Metadata::from_headers(&BTreeMap::from([+ ("x-claude-code-session-id".to_string(), "root".to_string()),+ ("x-claude-code-agent-id".to_string(), "worker".to_string()),+ ]));+ assert!(claude_child.is_subagent_work());++ // Codex delegated-work kinds route as sub-agent work.+ let review = Metadata::from_headers(&BTreeMap::from([(+ "x-openai-subagent".to_string(),+ "review".to_string(),+ )]));+ assert!(review.is_subagent_work());++ // Harness maintenance and unknown kinds stay on normal routing even+ // though the lineage fact still marks them as child-agent requests.+ for kind in ["compact", "memory_consolidation", "brand_new_kind"] {+ let metadata = Metadata::from_headers(&BTreeMap::from([(+ "x-openai-subagent".to_string(),+ kind.to_string(),+ )]));+ assert!(metadata.is_subagent, "{kind} keeps the lineage fact");+ assert!(!metadata.is_subagent_work(), "{kind} is not routed as work");+ }++ // A non-subagent request is never work, whatever its kind says.+ assert!(!Metadata::default().is_subagent_work());+ }}diff --git a/crates/switchyard-components-v2/Cargo.toml b/crates/switchyard-components-v2/Cargo.tomlindex 204c2a2eb..8e6b06374 100644--- a/crates/switchyard-components-v2/Cargo.toml+++ b/crates/switchyard-components-v2/Cargo.toml@@ -23,6 +23,7 @@ serde_json = "1"switchyard-components = { path = "../switchyard-components" }switchyard-components-v2-macros = { path = "../switchyard-components-v2-macros" }switchyard-core = { path = "../switchyard-core" }+switchyard-protocol = { path = "../protocol" }toml = "1.1"tracing = { version = "0.1", default-features = false, features = ["std"] }yaml_serde = "0.10"diff --git a/crates/switchyard-components-v2/src/config/parsing.rs b/crates/switchyard-components-v2/src/config/parsing.rsindex 8e87ead6a..e20fbb42a 100644--- a/crates/switchyard-components-v2/src/config/parsing.rs+++ b/crates/switchyard-components-v2/src/config/parsing.rs@@ -57,6 +57,13 @@ impl ProfileConfigDocument {.map(SerializedProfileConfig::body)}+ /// Returns a profile's envelope `subagent_target` reference, if configured.+ pub fn profile_subagent_target(&self, profile_id: &ProfileId) -> Option<&LlmTargetId> {+ self.profiles+ .get(profile_id)+ .and_then(SerializedProfileConfig::subagent_target)+ }+/// Returns a copy of this document with the selected profiles removed.pub fn without_profiles(&self, profile_ids: &[ProfileId]) -> Self {let omitted = profile_ids.iter().collect::<BTreeSet<_>>();@@ -68,16 +75,22 @@ impl ProfileConfigDocument {}}-/// Serialized profile body split into a type discriminator and profile-owned fields.+/// Serialized profile body split into a type discriminator, common envelope+/// fields, and profile-owned fields.#[derive(Clone, Debug, PartialEq)]pub(super) struct SerializedProfileConfig {profile_type: String,+ subagent_target: Option<LlmTargetId>,body: Value,}impl SerializedProfileConfig {/// Creates a serialized profile config after verifying the body is an object.- fn new(profile_type: impl Into<String>, body: Value) -> Result<Self> {+ fn new(+ profile_type: impl Into<String>,+ subagent_target: Option<LlmTargetId>,+ body: Value,+ ) -> Result<Self> {let profile_type = profile_type.into();if profile_type.trim().is_empty() {return Err(SwitchyardError::InvalidConfig(@@ -89,7 +102,11 @@ impl SerializedProfileConfig {"profile config body must be an object".to_string(),));}- Ok(Self { profile_type, body })+ Ok(Self {+ profile_type,+ subagent_target,+ body,+ })}/// Returns the profile type discriminator from the file's `type` field.@@ -97,7 +114,12 @@ impl SerializedProfileConfig {&self.profile_type}- /// Returns the profile-owned config fields without the `type` discriminator.+ /// Returns the envelope `subagent_target` reference from the file, if any.+ pub(super) fn subagent_target(&self) -> Option<&LlmTargetId> {+ self.subagent_target.as_ref()+ }++ /// Returns the profile-owned config fields without the envelope fields.pub(super) fn body(&self) -> &Value {&self.body}@@ -118,7 +140,21 @@ impl<'de> Deserialize<'de> for SerializedProfileConfig {let Value::String(profile_type) = profile_type else {return Err(de::Error::custom("profile config `type` must be a string"));};- SerializedProfileConfig::new(profile_type, value).map_err(de::Error::custom)+ // `subagent_target` is a common envelope field consumed here, like `type`,+ // so profile-owned bodies (which deny unknown fields) never see it.+ let subagent_target = match map.remove("subagent_target") {+ None => None,+ Some(Value::String(target_id)) => {+ Some(LlmTargetId::new(target_id).map_err(de::Error::custom)?)+ }+ Some(_) => {+ return Err(de::Error::custom(+ "profile config `subagent_target` must be a target id string",+ ));+ }+ };+ SerializedProfileConfig::new(profile_type, subagent_target, value)+ .map_err(de::Error::custom)}}@@ -131,6 +167,12 @@ impl Serialize for SerializedProfileConfig {return Err(ser::Error::custom("profile config body must be an object"));};map.insert("type".to_string(), Value::String(self.profile_type.clone()));+ if let Some(subagent_target) = &self.subagent_target {+ map.insert(+ "subagent_target".to_string(),+ Value::String(subagent_target.as_str().to_owned()),+ );+ }Value::Object(map).serialize(serializer)}}diff --git a/crates/switchyard-components-v2/src/config/resolving.rs b/crates/switchyard-components-v2/src/config/resolving.rsindex e7fcd6092..b019e0c74 100644--- a/crates/switchyard-components-v2/src/config/resolving.rs+++ b/crates/switchyard-components-v2/src/config/resolving.rs@@ -11,16 +11,18 @@ use switchyard_core::{};use super::parsing::{ProfileConfigDocument, SerializedProfileConfig, TargetConfig};-use crate::profiles::ProfileConfigEntry;+use crate::profiles::{ProfileConfigEntry, SubagentOverrideProfile};use crate::{Profile, ProfileHooks};impl ProfileConfigDocument {/// Resolves endpoints and validates every profile through its owning profile type.pub fn resolve(&self) -> Result<ProfileConfigPlan> {let targets = self.resolve_targets()?;+ let (profiles, profile_subagent_targets) = self.resolve_profiles(&targets)?;Ok(ProfileConfigPlan {- profiles: self.resolve_profiles(&targets)?,targets,+ profiles,+ profile_subagent_targets,})}@@ -37,19 +39,35 @@ impl ProfileConfigDocument {}// Parses profile-specific config bodies into the generated typed profile enum.+ // Also collects resolved sub-agent targets for profiles that declare one.fn resolve_profiles(&self,targets: &BTreeMap<LlmTargetId, LlmTarget>,- ) -> Result<BTreeMap<ProfileId, ProfileConfigEntry>> {+ ) -> Result<(+ BTreeMap<ProfileId, ProfileConfigEntry>,+ BTreeMap<ProfileId, LlmTarget>,+ )> {let env = ProfileBuildEnv::new(targets);let mut profiles = BTreeMap::new();+ let mut subagent_targets: BTreeMap<ProfileId, LlmTarget> = BTreeMap::new();for (profile_id, profile) in &self.profiles {+ // The envelope-level sub-agent override must name a resolvable target;+ // an unknown reference is a startup configuration error.+ if let Some(target_id) = profile.subagent_target() {+ let target = targets.get(target_id).ok_or_else(|| {+ SwitchyardError::InvalidConfig(format!(+ "profile {profile_id}: subagent_target references unknown target {}",+ target_id.as_str()+ ))+ })?;+ subagent_targets.insert(profile_id.clone(), target.clone());+ }profiles.insert(profile_id.clone(),resolve_profile(profile_id, profile, &env)?,);}- Ok(profiles)+ Ok((profiles, subagent_targets))}}@@ -150,6 +168,8 @@ pub struct ProfileConfigPlan {targets: BTreeMap<LlmTargetId, LlmTarget>,/// Typed profile configs keyed by the user-facing profile ID.profiles: BTreeMap<ProfileId, ProfileConfigEntry>,+ /// Resolved sub-agent override targets for profiles that declare one.+ profile_subagent_targets: BTreeMap<ProfileId, LlmTarget>,}impl fmt::Debug for ProfileConfigPlan {@@ -227,14 +247,26 @@ impl ProfileConfigPlan {}// Builds one typed profile config with profile-ID context in errors.+ // Wraps with SubagentOverrideProfile when the profile declares a subagent_target.fn build_typed_profile(&self,profile_id: &ProfileId,profile: &ProfileConfigEntry,) -> Result<Box<dyn Profile>> {- profile.build_boxed().map_err(|error| {+ let inner = profile.build_boxed().map_err(|error| {SwitchyardError::InvalidConfig(format!("profile {profile_id}: {error}"))- })+ })?;+ if let Some(target) = self.profile_subagent_targets.get(profile_id) {+ SubagentOverrideProfile::new(inner, target.clone())+ .map(|p| Box::new(p) as Box<dyn Profile>)+ .map_err(|error| {+ SwitchyardError::InvalidConfig(format!(+ "profile {profile_id}: subagent override: {error}"+ ))+ })+ } else {+ Ok(inner)+ }}}diff --git a/crates/switchyard-components-v2/src/profiles/mod.rs b/crates/switchyard-components-v2/src/profiles/mod.rsindex 91ca996b2..f83960023 100644--- a/crates/switchyard-components-v2/src/profiles/mod.rs+++ b/crates/switchyard-components-v2/src/profiles/mod.rs@@ -11,6 +11,7 @@ mod passthrough;mod profile_types;mod random_routing;mod stage_router;+mod subagent_override;pub use latency_service::{EndpointHealth, EndpointHealthStatus, LatencyServiceProcessedRequest, LatencyServiceProfile,@@ -31,3 +32,4 @@ pub use stage_router::{StageRouterPickerMode, StageRouterProcessedRequest, StageRouterProfile,StageRouterProfileConfig, StageRouterTier,};+pub(crate) use subagent_override::SubagentOverrideProfile;diff --git a/crates/switchyard-components-v2/src/profiles/subagent_override.rs b/crates/switchyard-components-v2/src/profiles/subagent_override.rsnew file mode 100644index 000000000..b9275b4bd--- /dev/null+++ b/crates/switchyard-components-v2/src/profiles/subagent_override.rs@@ -0,0 +1,90 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Sub-agent override combinator for v2 profiles.+//!+//! Wraps any profile without changing its behavior for normal traffic. A+//! request whose headers mark delegated sub-agent work+//! ([`switchyard_protocol::Metadata::is_subagent_work`]) is served directly by+//! a fixed worker target — keeping a sub-agent loop on an intentional,+//! cache-compatible target — while every other request delegates to the wrapped+//! profile. A worker failure surfaces as a normal target error and is never+//! silently re-routed through the wrapped profile.++use std::collections::BTreeMap;+use std::time::Instant;++use async_trait::async_trait;+use switchyard_components::StatsAccumulator;+use switchyard_core::{LlmTarget, Result};++use crate::backend::{native_target_backend, TargetBackend};+use crate::profile_stats_accumulator;+use crate::stats_recording::record_usage_or_wrap_stream;+use crate::{Profile, ProfileInput, ProfileResponse};++/// Wraps a profile, routing delegated sub-agent work to a fixed worker target.+pub(crate) struct SubagentOverrideProfile {+ inner: Box<dyn Profile>,+ worker: TargetBackend,+ stats: StatsAccumulator,+}++impl SubagentOverrideProfile {+ /// Wraps `inner`, routing recognized sub-agent work requests to `worker`.+ pub(crate) fn new(inner: Box<dyn Profile>, target: LlmTarget) -> Result<Self> {+ Ok(Self {+ inner,+ worker: native_target_backend(target)?,+ stats: profile_stats_accumulator(),+ })+ }+}++/// Returns true when the request headers signal delegated sub-agent work.+///+/// Normalizes multi-value headers to single-value (first occurrence wins)+/// before calling the protocol-layer detection logic.+fn is_subagent_work(headers: &BTreeMap<String, Vec<String>>) -> bool {+ let flat: BTreeMap<String, String> = headers+ .iter()+ .filter_map(|(k, vs)| vs.first().map(|v| (k.clone(), v.clone())))+ .collect();+ switchyard_protocol::Metadata::from_headers(&flat).is_subagent_work()+}++#[async_trait]+impl Profile for SubagentOverrideProfile {+ /// Routes sub-agent work to the worker target; delegates everything else.+ async fn run(&self, mut input: ProfileInput) -> Result<ProfileResponse> {+ if !is_subagent_work(&input.metadata.headers) {+ return self.inner.run(input).await;+ }++ let profile_started_at = Instant::now();+ let target_model = self.worker.target().model.clone();+ input.request.set_model(target_model.as_str());++ let backend_started_at = Instant::now();+ let response = match self.worker.call(&input.request).await {+ Ok(response) => response,+ Err(error) => {+ self.stats.record_error(target_model.as_str(), None)?;+ return Err(error);+ }+ };++ let backend_latency_ms = backend_started_at.elapsed().as_secs_f64() * 1000.0;+ self.stats+ .record_success(target_model.to_string(), Some(backend_latency_ms), None)?;+ let response = record_usage_or_wrap_stream(+ &self.stats,+ target_model.as_str(),+ None,+ profile_started_at,+ backend_latency_ms,+ response,+ )?;+ Ok(ProfileResponse::from(response))+ }+}diff --git a/crates/switchyard-components-v2/tests/config.rs b/crates/switchyard-components-v2/tests/config.rsindex 2be46883c..943a34cf8 100644--- a/crates/switchyard-components-v2/tests/config.rs+++ b/crates/switchyard-components-v2/tests/config.rs@@ -696,3 +696,100 @@ fn profile_config_format_rejects_unknown_extension() {.unwrap_or_else(|| "expected extension failure".to_string());assert!(error.contains("unsupported profile config extension"));}++// The envelope-level `subagent_target` is consumed before profile-owned parsing,+// so profile types that deny unknown fields still resolve, and the reference+// stays readable from the parsed document.+#[test]+fn subagent_target_envelope_field_is_stripped_and_exposed() -> Result<()> {+ let input = r#"+targets:+ weak:+ model: weak/model+ format: openai+profiles:+ direct:+ type: passthrough+ target: weak+ subagent_target: weak+"#;+ let config = parse_yaml(input)?;+ let profile_id = ProfileId::new("direct")?;+ assert_eq!(+ config.profile_subagent_target(&profile_id),+ Some(&LlmTargetId::new("weak")?)+ );+ let body_has_field = config+ .profile_body(&profile_id)+ .and_then(|body| body.get("subagent_target"))+ .is_some();+ assert!(!body_has_field);+ config.resolve()?;+ Ok(())+}++// A profile without the envelope field reports no sub-agent target.+#[test]+fn subagent_target_is_absent_by_default() -> Result<()> {+ let input = r#"+targets:+ weak:+ model: weak/model+ format: openai+profiles:+ direct:+ type: passthrough+ target: weak+"#;+ let config = parse_yaml(input)?;+ assert_eq!(+ config.profile_subagent_target(&ProfileId::new("direct")?),+ None+ );+ Ok(())+}++// An unknown `subagent_target` reference is a startup configuration error.+#[test]+fn subagent_target_referencing_unknown_target_is_rejected_at_resolve() -> Result<()> {+ let input = r#"+targets:+ weak:+ model: weak/model+ format: openai+profiles:+ direct:+ type: passthrough+ target: weak+ subagent_target: ghost+"#;+ let error = parse_yaml(input)?+ .resolve()+ .err()+ .map(|error| error.to_string())+ .unwrap_or_else(|| "expected resolve failure".to_string());+ assert!(error.contains("profile direct"));+ assert!(error.contains("subagent_target references unknown target ghost"));+ Ok(())+}++// The envelope field must be a target id string, not a structured value.+#[test]+fn subagent_target_must_be_a_target_id_string() {+ let input = r#"+targets:+ weak:+ model: weak/model+ format: openai+profiles:+ direct:+ type: passthrough+ target: weak+ subagent_target: [weak]+"#;+ let error = parse_yaml(input)+ .err()+ .map(|error| error.to_string())+ .unwrap_or_else(|| "expected parse failure".to_string());+ assert!(error.contains("`subagent_target` must be a target id string"));+}diff --git a/crates/switchyard-py/Cargo.toml b/crates/switchyard-py/Cargo.tomlindex 560ea2f65..fbd9fba93 100644--- a/crates/switchyard-py/Cargo.toml+++ b/crates/switchyard-py/Cargo.toml@@ -25,6 +25,7 @@ pythonize = "0.28.0"serde = "1"serde_json = "1"switchyard-core = { path = "../switchyard-core" }+switchyard-protocol = { path = "../protocol" }switchyard-components = { path = "../switchyard-components" }switchyard-components-v2 = { path = "../switchyard-components-v2" }switchyard-translation = { path = "../switchyard-translation" }diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex 02ce29037..8eedb7195 100644--- a/crates/switchyard-py/src/libsy_bindings.rs+++ b/crates/switchyard-py/src/libsy_bindings.rs@@ -10,10 +10,10 @@ use async_trait::async_trait;use pyo3::exceptions::{PyTypeError, PyValueError};use pyo3::prelude::*;use serde_json::{json, Value};-use switchyard_libsy::algorithms::{Noop, Random};+use switchyard_libsy::algorithms::{Noop, Random, SubagentOverride};use switchyard_libsy::{- AggLlmResponse, Algorithm, Context, Decision, LlmResponse, LlmTarget, LlmTargetSet, Request,- Response, RoutedLlmClient,+ AggLlmResponse, Algorithm, Context, Decision, LlmResponse, LlmTarget, LlmTargetSet, Metadata,+ Request, Response, RoutedLlmClient,};use crate::errors::py_libsy_error;@@ -111,12 +111,23 @@ impl PyAlgorithm {#[pymethods]impl PyAlgorithm {/// Run to completion using the clients configured on the algorithm's targets.- fn run<'py>(&self, py: Python<'py>, request: &Bound<'_, PyAny>) -> PyResult<Bound<'py, PyAny>> {+ ///+ /// `headers`, when given, is normalized into the request's correlation+ /// [`Metadata`] exactly as an HTTP host would (`Metadata::from_headers`),+ /// so metadata-driven algorithms such as `subagent_override` see the same+ /// signals in Python as when served over HTTP.+ #[pyo3(signature = (request, headers=None))]+ fn run<'py>(+ &self,+ py: Python<'py>,+ request: &Bound<'_, PyAny>,+ headers: Option<std::collections::BTreeMap<String, String>>,+ ) -> PyResult<Bound<'py, PyAny>> {let algorithm = Arc::clone(&self.inner);let request = Request {llm_request: from_python(request)?,raw_request: None,- metadata: None,+ metadata: headers.map(|headers| Metadata::from_headers(&headers)),};pyo3_async_runtimes::tokio::future_into_py(py, async move {let (decisions, response) = algorithm@@ -167,6 +178,24 @@ fn random_algorithm(py: Python<'_>, targets: Vec<Py<PyLlmTarget>>) -> PyResult<P)))))}+/// Wrap `inner`, routing delegated sub-agent work to a fixed worker target.+///+/// Detection and the work-vs-maintenance policy are the protocol crate's+/// `Metadata::from_headers` / `Metadata::is_subagent_work`, driven by the+/// `headers` passed to `Algorithm.run`.+#[pyfunction(name = "subagent_override")]+fn subagent_override_algorithm(+ py: Python<'_>,+ inner: Py<PyAlgorithm>,+ worker: Py<PyLlmTarget>,+) -> PyResult<PyAlgorithm> {+ let inner = Arc::clone(&inner.bind(py).get().inner);+ let worker = worker.bind(py).try_borrow()?.clone_core(py);+ Ok(PyAlgorithm::new(Arc::new(SubagentOverride::new(+ inner, worker,+ ))))+}+fn boxed_python_error(error: PyErr) -> BoxError {std::io::Error::other(error.to_string()).into()}@@ -177,6 +206,10 @@ pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {libsy_module.add_class::<PyLlmTarget>()?;libsy_module.add_function(wrap_pyfunction!(noop_algorithm, &libsy_module)?)?;libsy_module.add_function(wrap_pyfunction!(random_algorithm, &libsy_module)?)?;+ libsy_module.add_function(wrap_pyfunction!(+ subagent_override_algorithm,+ &libsy_module+ )?)?;libsy_module.add("LibsyError", module.getattr("LibsyError")?)?;module.add_submodule(&libsy_module)?;Ok(())diff --git a/crates/switchyard-py/src/profile_bindings/mod.rs b/crates/switchyard-py/src/profile_bindings/mod.rsindex 3438ae398..eb0822847 100644--- a/crates/switchyard-py/src/profile_bindings/mod.rs+++ b/crates/switchyard-py/src/profile_bindings/mod.rs@@ -66,6 +66,15 @@ impl PyProfileConfigDocument {.map(std::borrow::ToOwned::to_owned))}+ /// Return a parsed profile's envelope `subagent_target` reference, or `None`.+ fn profile_subagent_target(&self, profile_id: &str) -> PyResult<Option<String>> {+ let profile_id = parse_profile_id(profile_id)?;+ Ok(self+ .inner+ .profile_subagent_target(&profile_id)+ .map(|target_id| target_id.as_str().to_owned()))+ }+/// Return a parsed profile's body without the `type` discriminator.fn profile_body(&self, py: Python<'_>, profile_id: &str) -> PyResult<Option<Py<PyAny>>> {let profile_id = parse_profile_id(profile_id)?;@@ -264,6 +273,25 @@ fn py_parse_profile_config_path(path: PathBuf) -> PyResult<PyProfileConfigDocume.map_err(py_core_error)}+/// Report whether normalized request headers mark delegated sub-agent work.+///+/// A thin binding over the canonical detection and routing policy owned by+/// the protocol crate: `switchyard_protocol::Metadata::from_headers` for the+/// lineage fact (explicit `x-switchyard-is-subagent`, Claude Code agent+/// lineage, Codex/relay markers) and `Metadata::is_subagent_work` for the+/// work-vs-maintenance kind policy, so Codex `compact` /+/// `memory_consolidation` turns stay on normal profile routing.+#[pyfunction]+fn is_subagent_request(headers: &Bound<'_, PyAny>) -> PyResult<bool> {+ let headers = typed::metadata_headers_from_python(headers)?;+ // Lineage headers are single-valued; keep the first value when repeated.+ let headers: std::collections::BTreeMap<String, String> = headers+ .into_iter()+ .filter_map(|(name, values)| values.into_iter().next().map(|value| (name, value)))+ .collect();+ Ok(switchyard_protocol::Metadata::from_headers(&headers).is_subagent_work())+}+/// Parse and resolve a components-v2 profile config file.#[pyfunction]fn load_profile_config(path: PathBuf) -> PyResult<PyProfileConfigPlan> {@@ -300,6 +328,7 @@ pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {module.add_function(wrap_pyfunction!(py_parse_profile_config_str, module)?)?;module.add_function(wrap_pyfunction!(py_parse_profile_config_path, module)?)?;module.add_function(wrap_pyfunction!(load_profile_config, module)?)?;+ module.add_function(wrap_pyfunction!(is_subagent_request, module)?)?;typed::register(module)?;Ok(())}diff --git a/crates/switchyard-py/src/profile_bindings/typed.rs b/crates/switchyard-py/src/profile_bindings/typed.rsindex c62006aa5..2a905bee2 100644--- a/crates/switchyard-py/src/profile_bindings/typed.rs+++ b/crates/switchyard-py/src/profile_bindings/typed.rs@@ -190,7 +190,7 @@ fn parse_request_id(request_id: Option<String>) -> PyResult<Option<RequestId>> {.map_err(|error| PyValueError::new_err(format!("invalid request_id: {error}")))}-fn metadata_headers_from_python(+pub(crate) fn metadata_headers_from_python(headers: &Bound<'_, PyAny>,) -> PyResult<BTreeMap<String, Vec<String>>> {let dict = PyDict::new(headers.py());diff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.mdindex 386c1d6a9..dc7440c3d 100644--- a/docs/routing_algorithms/overview.md+++ b/docs/routing_algorithms/overview.md@@ -85,6 +85,38 @@ profiles:Use the profile ID to select policy behavior (`fast` or `smart`) and a target IDto bypass routing (`weak` or `strong`).+## Sub-agent override (`subagent_target`)++Any profile can name an optional `subagent_target` in its common envelope,+alongside `type`. When a request carries a recognized sub-agent signal —+Codex delegated-work kinds (`x-openai-subagent: collab_spawn` or `review`),+Claude Code agent lineage headers, or an explicit+`x-switchyard-is-subagent: true` — it bypasses the profile's routing and runs+as a direct passthrough to that target:++```yaml+profiles:+ smart:+ type: random-routing+ strong: strong+ weak: weak+ strong_probability: 0.3+ subagent_target: weak+```++This keeps a sub-agent loop on one intentional, cache-compatible target+instead of re-routing every worker turn. Codex harness-maintenance turns+(`compact`, `memory_consolidation`) and unrecognized kinds stay on normal+profile routing, as does everything else when the field is absent. An unknown+target reference fails at startup, and a sub-agent target failure surfaces as+a normal target error — it is never silently re-routed through the profile.++To suppress sub-agent routing for a request that carries a recognized signal,+send `x-switchyard-is-subagent: false`. This explicit header overrides Codex+and Claude Code lineage signals in either direction: `false` keeps the request+on normal profile routing even when delegated-work headers are present, and+`true` marks a request as a sub-agent even when no harness headers appear.+## Direct targets and passthrough aliasesFor new profile configs, use one public model concept:diff --git a/switchyard/lib/profiles/loader.py b/switchyard/lib/profiles/loader.pyindex ee56925be..ed9b2a491 100644--- a/switchyard/lib/profiles/loader.py+++ b/switchyard/lib/profiles/loader.py@@ -16,6 +16,7 @@ from pathlib import Pathfrom typing import Any, castfrom switchyard.lib.profiles.protocols import ProfileInput, ProfileRunner+from switchyard.lib.profiles.subagent_override import SubagentOverrideProfilefrom switchyard.lib.profiles.table import (ProfileConfigError,build_profile,@@ -63,9 +64,43 @@ def load_profiles_and_targets(built[profile_id] = _RustProfileRunner(plan.build_profile(profile_id))for profile_id, (profile_type, body) in python_profiles.items():built[profile_id] = _build_python_profile(profile_id, profile_type, body, plan)+ for profile_id in list(built):+ built[profile_id] = _wrap_subagent_override(profile_id, built[profile_id], document, plan)return built, _targets(plan)+def _wrap_subagent_override(+ profile_id: str,+ profile: ProfileRunner,+ document: Any,+ plan: ProfileConfigPlan,+) -> ProfileRunner:+ """Wrap a built profile when its envelope names a ``subagent_target``.++ Rust profiles already apply :class:`SubagentOverrideProfile` internally at+ build time, so Python-level wrapping is skipped for them. Python-defined+ profiles receive the Python wrapper here, which adds sub-agent routing+ without Rust-level stats (stats for Python profiles remain in the+ Python stats pipeline).++ An unknown target reference is a startup configuration error.+ """+ target_id = document.profile_subagent_target(profile_id)+ if target_id is None:+ return profile+ # Rust profiles handle subagent routing internally; skip double-wrapping.+ if isinstance(profile, _RustProfileRunner):+ return profile+ target = plan.target(target_id)+ if target is None:+ raise ProfileConfigError(+ f"profile {profile_id}: subagent_target references unknown target {target_id!r}"+ )+ from switchyard.lib.profiles.passthrough import PassthroughProfileConfig++ return SubagentOverrideProfile(profile, PassthroughProfileConfig(target=target).build())++class _RustProfileRunner:"""Adapts an erased Rust ``Profile`` to the ``run(input)`` runner contract."""diff --git a/switchyard/lib/profiles/subagent_override.py b/switchyard/lib/profiles/subagent_override.pynew file mode 100644index 000000000..794932693--- /dev/null+++ b/switchyard/lib/profiles/subagent_override.py@@ -0,0 +1,103 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++"""Sub-agent override wrapper routing delegated worker requests to a fixed target."""++from __future__ import annotations++from dataclasses import dataclass+from typing import Any++from switchyard.lib.profiles.protocols import (+ ContextAwareProfile,+ ProfileLifecycle,+ ProfileRunner,+)+from switchyard.lib.proxy_context import ProxyContext+from switchyard_rust.core import ChatResponse+from switchyard_rust.profiles import ProfileInput, is_subagent_request+++@dataclass(slots=True)+class SubagentProcessedRequest:+ """Pairs the branch selected for one request with its request-side state."""++ branch: Any+ processed: Any+++class SubagentOverrideProfile:+ """Route recognized sub-agent requests to a fixed override branch.++ Wraps a built profile without changing its behavior for normal traffic. A+ request whose headers carry a delegated sub-agent signal runs through the+ override branch (a passthrough to the profile's configured+ ``subagent_target``); every other request runs the wrapped profile+ unchanged. The override never rewrites the request or response, and an+ override-branch failure surfaces as a normal target error — it is not+ re-routed through the wrapped profile.+ """++ def __init__(self, inner: ProfileRunner, override: ProfileRunner) -> None:+ """Wrap ``inner``, sending sub-agent requests to ``override`` instead."""+ self._inner = inner+ self._override = override++ def iter_components(self) -> list[object]:+ """Return lifecycle components of both branches in startup order."""+ return [*_components(self._inner), *_components(self._override)]++ def _branch(self, input: ProfileInput) -> Any:+ return self._override if is_subagent_request(input.metadata.headers) else self._inner++ async def run(self, input: ProfileInput) -> ChatResponse:+ """Execute the branch selected by the request's sub-agent signal."""+ response = await self._branch(input).run(input)+ return response # type: ignore[no-any-return]++ async def run_with_context(+ self,+ input: ProfileInput,+ ctx: ProxyContext,+ ) -> ChatResponse:+ """Execute the selected branch, preserving the caller-owned context."""+ branch = self._branch(input)+ if isinstance(branch, ContextAwareProfile):+ return await branch.run_with_context(input, ctx)+ response = await branch.run(input)+ return response # type: ignore[no-any-return]++ async def process(self, input: ProfileInput) -> SubagentProcessedRequest:+ """Run the selected branch's request side, remembering the branch."""+ branch = self._branch(input)+ return SubagentProcessedRequest(branch, await branch.process(input))++ async def process_with_context(+ self,+ input: ProfileInput,+ ctx: ProxyContext,+ ) -> SubagentProcessedRequest:+ """Run the selected branch's request side with the caller's context."""+ branch = self._branch(input)+ if isinstance(branch, ContextAwareProfile):+ return SubagentProcessedRequest(branch, await branch.process_with_context(input, ctx))+ return SubagentProcessedRequest(branch, await branch.process(input))++ async def rprocess(+ self,+ processed: SubagentProcessedRequest,+ response: ChatResponse,+ ) -> ChatResponse:+ """Run the response side of the branch that processed the request."""+ result = await processed.branch.rprocess(processed.processed, response)+ return result # type: ignore[no-any-return]+++def _components(profile: object) -> list[object]:+ """Return a branch's lifecycle components, mirroring ``ProfileSwitchyard``."""+ if isinstance(profile, ProfileLifecycle):+ return profile.iter_components()+ return [profile]+++__all__ = ["SubagentOverrideProfile", "SubagentProcessedRequest"]diff --git a/switchyard/libsy/algorithms.py b/switchyard/libsy/algorithms.pyindex 434526feb..d5f2e64a9 100644--- a/switchyard/libsy/algorithms.py+++ b/switchyard/libsy/algorithms.py@@ -5,5 +5,6 @@from switchyard_rust.libsy import noop as noopfrom switchyard_rust.libsy import random as random+from switchyard_rust.libsy import subagent_override as subagent_override-__all__ = ["noop", "random"]+__all__ = ["noop", "random", "subagent_override"]diff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.pyindex b7ef7bfbe..ff6c3123e 100644--- a/switchyard_rust/libsy.py+++ b/switchyard_rust/libsy.py@@ -10,7 +10,9 @@ from typing import TYPE_CHECKING, Any, Protocolfrom switchyard_rust.core import _load_native-_EXPORTS = frozenset({"Algorithm", "LibsyError", "LlmTarget", "noop", "random"})+_EXPORTS = frozenset(+ {"Algorithm", "LibsyError", "LlmTarget", "noop", "random", "subagent_override"}+)class LlmClient(Protocol):@@ -44,12 +46,15 @@ if TYPE_CHECKING:async def run(self,request: Mapping[str, object],+ headers: Mapping[str, str] | None = None,) -> tuple[list[dict[str, object]], dict[str, object]]: ...def noop() -> Algorithm: ...def random(targets: Sequence[LlmTarget]) -> Algorithm: ...+ def subagent_override(inner: Algorithm, worker: LlmTarget) -> Algorithm: ...+def __getattr__(name: str) -> object:if name in _EXPORTS:diff --git a/switchyard_rust/profiles.py b/switchyard_rust/profiles.pyindex 088ba54d7..7da35c46c 100644--- a/switchyard_rust/profiles.py+++ b/switchyard_rust/profiles.py@@ -26,6 +26,7 @@ _PROFILE_EXPORTS = ("parse_profile_config_str","ProfileInput","ProfileRequestMetadata",+ "is_subagent_request",)__all__ = _PROFILE_EXPORTSdiff --git a/switchyard_rust/profiles.pyi b/switchyard_rust/profiles.pyiindex 866d63696..7c00a0d61 100644--- a/switchyard_rust/profiles.pyi+++ b/switchyard_rust/profiles.pyi@@ -1,6 +1,7 @@# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.# SPDX-License-Identifier: Apache-2.0+from collections.abc import Mappingfrom os import PathLikefrom typing import Literal@@ -33,6 +34,7 @@ def parse_profile_config_str() -> ProfileConfigDocument: ...def parse_profile_config_path(path: str | PathLike[str]) -> ProfileConfigDocument: ...def load_profile_config(path: str | PathLike[str]) -> ProfileConfigPlan: ...+def is_subagent_request(headers: Mapping[str, str | list[str]]) -> bool: ...# --- Metadata for direct typed profile calls ----------------------------------diff --git a/tests/test_libsy_minimal_bindings.py b/tests/test_libsy_minimal_bindings.pyindex b2014a33a..504ab3cd9 100644--- a/tests/test_libsy_minimal_bindings.py+++ b/tests/test_libsy_minimal_bindings.py@@ -99,6 +99,37 @@ async def test_invalid_request_is_rejected_at_the_boundary() -> None:)+async def test_subagent_override_routes_marked_work_to_the_worker() -> None:+ orchestrator = EchoClient("orchestrator")+ worker = EchoClient("worker")+ algorithm = algorithms.subagent_override(+ algorithms.random([LlmTarget("orchestrator", orchestrator)]),+ LlmTarget("worker", worker),+ )++ # No headers: the wrapped algorithm serves the request.+ _, response = await algorithm.run(request_body())+ assert response["model"] == "orchestrator"++ # Claude Code child-agent lineage routes to the fixed worker target.+ decisions, response = await algorithm.run(+ request_body(),+ headers={+ "x-claude-code-session-id": "root",+ "x-claude-code-agent-id": "child-1",+ },+ )+ assert response["model"] == "worker"+ assert decisions[-1]["selected_model"] == "worker"++ # Harness maintenance stays on the wrapped algorithm.+ _, response = await algorithm.run(+ request_body(), headers={"x-openai-subagent": "compact"}+ )+ assert response["model"] == "orchestrator"+ assert len(worker.calls) == 1++async def test_client_failure_becomes_libsy_error() -> None:class FailingClient:async def call(self, request: dict[str, Any]) -> dict[str, Any]:diff --git a/tests/test_subagent_routing.py b/tests/test_subagent_routing.pynew file mode 100644index 000000000..310f98172--- /dev/null+++ b/tests/test_subagent_routing.py@@ -0,0 +1,319 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++"""Tests for envelope-level sub-agent routing (``subagent_target``).++A profile config may name a ``subagent_target`` in its common envelope; the+loader then wraps the built profile so recognized sub-agent requests run+through a passthrough to that target while all other traffic keeps the+profile's own routing.+"""++import json+import threading+from collections.abc import Iterator+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer+from pathlib import Path+from typing import Any++import pytest++from switchyard import load_profiles+from switchyard.lib.profiles import ProfileConfigError+from switchyard.lib.profiles.subagent_override import SubagentOverrideProfile+from switchyard_rust.core import ChatRequest, SwitchyardConfigError+from switchyard_rust.profiles import (+ ProfileInput,+ ProfileRequestMetadata,+ is_subagent_request,+)++SUBAGENT_HEADERS = {+ "x-claude-code-session-id": "root-session",+ "x-claude-code-agent-id": "worker-1",+}+++class _MockOpenAIServer(ThreadingHTTPServer):+ calls: list[dict[str, Any]]++ def __init__(self) -> None:+ super().__init__(("127.0.0.1", 0), _MockOpenAIHandler)+ self.calls = []++ @property+ def base_url(self) -> str:+ host, port = self.server_address+ return f"http://{host}:{port}"+++class _MockOpenAIHandler(BaseHTTPRequestHandler):+ server: _MockOpenAIServer++ def do_POST(self) -> None:+ content_length = int(self.headers.get("content-length", "0"))+ raw_body = self.rfile.read(content_length)+ body = json.loads(raw_body.decode("utf-8")) if raw_body else {}+ self.server.calls.append({"path": self.path, "body": body})+ response = {+ "id": "chatcmpl-subagent",+ "object": "chat.completion",+ "model": body.get("model"),+ "mock_path": self.path,+ "choices": [+ {+ "index": 0,+ "message": {"role": "assistant", "content": "ok"},+ "finish_reason": "stop",+ }+ ],+ "usage": {"prompt_tokens": 2, "completion_tokens": 1, "total_tokens": 3},+ }+ payload = json.dumps(response).encode("utf-8")+ self.send_response(200)+ self.send_header("content-type", "application/json")+ self.send_header("content-length", str(len(payload)))+ self.end_headers()+ self.wfile.write(payload)++ def log_message(self, _format: str, *_args: object) -> None:+ return+++def mock_openai_server() -> Iterator[_MockOpenAIServer]:+ try:+ server = _MockOpenAIServer()+ except PermissionError as exc:+ pytest.skip(f"loopback socket binding is unavailable in this sandbox: {exc}")+ thread = threading.Thread(target=server.serve_forever, daemon=True)+ thread.start()+ try:+ yield server+ finally:+ server.shutdown()+ thread.join(timeout=5)+ server.server_close()+++def _config(base_url: str) -> str:+ """Rust and Python profiles that both name a ``subagent_target``."""+ return f"""+targets:+ strong:+ model: provider/strong+ format: openai+ base_url: "{base_url}/strong/v1"+ api_key: test-key+ worker:+ model: provider/worker+ format: openai+ base_url: "{base_url}/worker/v1"+ api_key: test-key++profiles:+ direct:+ type: passthrough+ target: strong+ subagent_target: worker+ smart:+ type: header-routing+ strong: strong+ weak: strong+ subagent_target: worker+ plain:+ type: passthrough+ target: strong+"""+++def _write(tmp_path: Path, text: str, name: str = "profiles.yaml") -> Path:+ path = tmp_path / name+ path.write_text(text, encoding="utf-8")+ return path+++def _request(model: str = "client/x") -> ChatRequest:+ return ChatRequest.openai_chat(+ {"model": model, "messages": [{"role": "user", "content": "hello"}]}+ )+++def _subagent_input() -> ProfileInput:+ return ProfileInput(+ _request(),+ ProfileRequestMetadata(headers=dict(SUBAGENT_HEADERS)),+ )+++# --- Detection ------------------------------------------------------------+++ ("headers", "expected"),+ [+ # No signal at all.+ ({}, False),+ # Claude Code lineage: any non-empty agent id marks a child agent.+ (SUBAGENT_HEADERS, True),+ # Agent id alone (no session header) is still a child agent.+ ({"x-claude-code-agent-id": "child-1"}, True),+ # Session alone — root agent, no agent-id sent.+ ({"x-claude-code-session-id": "s"}, False),+ # Codex delegated-work kinds route as sub-agent work.+ ({"x-openai-subagent": "review"}, True),+ ({"x-openai-subagent": "collab_spawn"}, True),+ # Codex harness maintenance and unknown kinds stay on normal routing.+ ({"x-openai-subagent": "compact"}, False),+ ({"x-openai-subagent": "memory_consolidation"}, False),+ ({"x-openai-subagent": "brand_new_kind"}, False),+ # The explicit Switchyard header decides the lineage fact, in both+ # directions; the work-kind policy still applies on top of it.+ ({"x-switchyard-is-subagent": "true"}, True),+ ({"x-switchyard-is-subagent": "false", "x-openai-subagent": "review"}, False),+ ({"x-switchyard-is-subagent": "true", "x-openai-subagent": "compact"}, False),+ # Header names are case-insensitive and values are trimmed.+ ({"X-OpenAI-Subagent": " review "}, True),+ # Bug #2 fix: operator label x-switchyard-agent-kind must not suppress+ # routing signals from the harness (x-openai-subagent, x-switchyard-is-subagent).+ ({"x-openai-subagent": "review", "x-switchyard-agent-kind": "researcher"}, True),+ ({"x-switchyard-is-subagent": "true", "x-switchyard-agent-kind": "researcher"}, True),+ # Bug #1 fix: correlation-only headers are not routing signals.+ ({"x-switchyard-parent-agent-id": "parent"}, False),+ ({"x-nemo-relay-subagent-id": "relay-child"}, False),+ ({"x-dynamo-parent-session-id": "dynamo-parent"}, False),+ ({"x-session-id": "s", "x-parent-session-id": "p"}, False),+ ],+)+def test_is_subagent_request_detection(headers: dict[str, str], expected: bool) -> None:+ assert is_subagent_request(headers) is expected+++# --- Loader wiring ----------------------------------------------------------+++def test_loader_wraps_profiles_with_subagent_target(tmp_path: Path) -> None:+ path = _write(tmp_path, _config("http://127.0.0.1:9"))+ profiles = load_profiles(path)+ # Rust profiles (direct / passthrough) handle subagent routing at the Rust level;+ # the Python loader must not double-wrap them with SubagentOverrideProfile.+ assert not isinstance(profiles["direct"], SubagentOverrideProfile)+ # Python profiles (smart / header-routing) still receive the Python wrapper.+ assert isinstance(profiles["smart"], SubagentOverrideProfile)+ assert not isinstance(profiles["plain"], SubagentOverrideProfile)+++async def test_rust_profile_routes_subagent_requests_to_target(+ mock_openai_server: _MockOpenAIServer,+ tmp_path: Path,+) -> None:+ path = _write(tmp_path, _config(mock_openai_server.base_url))+ profiles = load_profiles(path)++ normal = await profiles["direct"].run(ProfileInput(_request()))+ assert normal.body["model"] == "provider/strong"+ assert normal.body["mock_path"] == "/strong/v1/chat/completions"++ subagent = await profiles["direct"].run(_subagent_input())+ assert subagent.body["model"] == "provider/worker"+ assert subagent.body["mock_path"] == "/worker/v1/chat/completions"+++async def test_python_profile_routes_subagent_requests_to_target(+ mock_openai_server: _MockOpenAIServer,+ tmp_path: Path,+) -> None:+ path = _write(tmp_path, _config(mock_openai_server.base_url))+ profiles = load_profiles(path)++ normal = await profiles["smart"].run(ProfileInput(_request()))+ assert normal.body["model"] == "provider/strong"++ subagent = await profiles["smart"].run(_subagent_input())+ assert subagent.body["model"] == "provider/worker"+ assert subagent.body["mock_path"] == "/worker/v1/chat/completions"+++async def test_maintenance_kinds_keep_normal_routing(+ mock_openai_server: _MockOpenAIServer,+ tmp_path: Path,+) -> None:+ path = _write(tmp_path, _config(mock_openai_server.base_url))+ profiles = load_profiles(path)++ metadata = ProfileRequestMetadata(headers={"x-openai-subagent": "compact"})+ response = await profiles["direct"].run(ProfileInput(_request(), metadata))+ assert response.body["model"] == "provider/strong"+++def test_rust_profile_unknown_subagent_target_is_rejected(tmp_path: Path) -> None:+ config = """+targets:+ strong:+ model: provider/strong+ format: openai+ base_url: http://127.0.0.1:9/v1+ api_key: test-key++profiles:+ direct:+ type: passthrough+ target: strong+ subagent_target: ghost+"""+ path = _write(tmp_path, config)+ with pytest.raises(SwitchyardConfigError, match="unknown target ghost"):+ load_profiles(path)+++def test_python_profile_unknown_subagent_target_is_rejected(tmp_path: Path) -> None:+ config = """+targets:+ strong:+ model: provider/strong+ format: openai+ base_url: http://127.0.0.1:9/v1+ api_key: test-key++profiles:+ smart:+ type: header-routing+ strong: strong+ weak: strong+ subagent_target: ghost+"""+ path = _write(tmp_path, config)+ with pytest.raises(ProfileConfigError, match="unknown target 'ghost'"):+ load_profiles(path)+++# --- Wrapper behavior -------------------------------------------------------+++class _StubRunner:+ def __init__(self, label: str) -> None:+ self.label = label+ self.calls = 0++ async def run(self, input: ProfileInput) -> Any:+ self.calls += 1+ return self.label+++def test_iter_components_spans_both_branches() -> None:+ inner = _StubRunner("inner")+ override = _StubRunner("override")+ wrapper = SubagentOverrideProfile(inner, override)+ assert wrapper.iter_components() == [inner, override]+++async def test_override_failure_is_not_rerouted_to_the_wrapped_profile() -> None:+ class _FailingRunner:+ async def run(self, input: ProfileInput) -> Any:+ raise RuntimeError("worker target unavailable")++ inner = _StubRunner("inner")+ wrapper = SubagentOverrideProfile(inner, _FailingRunner())+ with pytest.raises(RuntimeError, match="worker target unavailable"):+ await wrapper.run(_subagent_input())+ assert inner.calls == 0