fix(runtime): tighten delegate boundary, clarify SubAgent allowlist

DelegateTool::policy_for_target now refuses narrowing in addition to
escalation. The spawned agentic loop reuses the caller's parent_tools
registry, so a narrower target policy never reaches those tool calls;
catching the narrowing at the delegate boundary turns a silent
over-grant into a loud refusal that points operators at
spawn_subagent for genuinely narrowed runs.

SubAgent allowlist fields renamed to make explicit that they carry
config aliases (the [agents.<alias>] keys) rather than backend
storage identifiers: SubAgentOverrides.allowed_agent_aliases,
SubAgentContext.parent_alias / allowed_agent_aliases,
SubAgentSpawn.parent_alias / parent_allowed_agent_aliases. Module
doc spells out that consumers building an AgentScopedMemory must
resolve via Memory::ensure_agent_uuid first (SQL backends use UUIDs
from the agents table; Markdown / Qdrant / None use the alias
verbatim per the trait default). The in-tree consumer today is
zeroclaw_memory::create_memory_for_agent, which already does the
resolution.

Drop a stale `let _ = agent_config;` in build_enriched_system_prompt
that was claiming the parameter was unused; it is used several lines
above to resolve the agent's skill bundles.

Author: singlerider

crates/zeroclaw-runtime/src/cron/scheduler.rs

@@ -383,7 +383,7 @@ async fn run_agent_job(
 
     let subagent_span = tracing::info_span!(
         "subagent",
-        parent_alias = %subagent_ctx.agent_id,
+        parent_alias = %subagent_ctx.parent_alias,
         run_id = %run_session_id,
         spawn_site = "cron",
     );

crates/zeroclaw-runtime/src/subagent/mod.rs

@@ -12,8 +12,19 @@
 //! [`SubAgentOverrides`]; [`SubAgentSpawn::build`] validates each
 //! override as a subset of the parent (using
 //! [`SecurityPolicy::ensure_no_escalation_beyond`] for the policy and
-//! a UUID-set containment check for the memory allowlist) and returns
-//! `Err` with the originating violation chained on any escalation.
+//! an alias-set containment check for the memory allowlist) and
+//! returns `Err` with the originating violation chained on any
+//! escalation.
+//!
+//! The memory allowlist is carried as a set of agent **aliases** (the
+//! `[agents.<alias>]` config keys), not backend storage identifiers.
+//! Consumers that build an [`AgentScopedMemory`] must resolve aliases
+//! to backend identifiers via
+//! [`zeroclaw_memory::Memory::ensure_agent_uuid`] first — SQL-backed
+//! stores use UUIDs from the `agents` table; Markdown / Qdrant / None
+//! use the alias verbatim per the trait default. Holding aliases at
+//! this layer means [`SubAgentSpawn::for_agent`] does not need a
+//! backend handle to construct.
 
 use anyhow::{Context, Result};
 use std::collections::HashSet;
@@ -36,41 +47,57 @@ pub struct SubAgentOverrides {
     /// [`SecurityPolicy::ensure_no_escalation_beyond`].
     pub policy: Option<SecurityPolicy>,
     /// Override the SubAgent's memory allowlist (the set of sibling
-    /// agent UUIDs the SubAgent may recall from). Validated as a
-    /// subset of the parent's allowlist; any UUID present here that
-    /// is not on the parent's list is rejected.
-    pub allowed_agent_ids: Option<HashSet<String>>,
+    /// agent **aliases** the SubAgent may recall from, as written in
+    /// `[agents.<alias>]` keys). Validated as a subset of the
+    /// parent's allowlist; any alias here that is not on the parent's
+    /// list is rejected.
+    ///
+    /// These are config-layer aliases, not backend storage
+    /// identifiers. Consumers that build an [`AgentScopedMemory`]
+    /// must resolve aliases to backend identifiers via
+    /// [`zeroclaw_memory::Memory::ensure_agent_uuid`] before passing
+    /// them to the wrapper (SQL backends use UUIDs; Markdown / Qdrant
+    /// / None use the alias verbatim per the trait default). The
+    /// in-tree consumer today is `zeroclaw_memory::create_memory_for_agent`,
+    /// which performs the resolution.
+    pub allowed_agent_aliases: Option<HashSet<String>>,
 }
 
 /// Constructed SubAgent context: bound parent identity, validated
 /// child policy, and the resolved memory allowlist.
 #[derive(Debug, Clone)]
 pub struct SubAgentContext {
-    /// The parent agent's identifier. SubAgents share the parent's
-    /// identity at the data layer (no separate row in the agents
-    /// table); the distinction between parent and sub-run is captured
-    /// at the tracing-span level (`agent.<alias>.subagent.<run_id>`).
-    pub agent_id: String,
+    /// The parent agent's alias (e.g. `"researcher"`). SubAgents share
+    /// the parent's identity at the data layer (no separate row in the
+    /// `agents` table); the distinction between parent and sub-run is
+    /// captured at the tracing-span level
+    /// (`agent.<alias>.subagent.<run_id>`).
+    pub parent_alias: String,
     /// The validated [`SecurityPolicy`] this SubAgent operates under.
     /// Identical to the parent's when `SubAgentOverrides::policy` is
     /// `None`; otherwise a narrowed copy that passed
     /// [`SecurityPolicy::ensure_no_escalation_beyond`].
     pub policy: Arc<SecurityPolicy>,
-    /// Resolved memory allowlist. The bound `agent_id` is always
-    /// included so the SubAgent always sees the parent's own rows;
-    /// the rest is either the parent's allowlist verbatim or a
-    /// validated subset.
-    pub allowed_agent_ids: HashSet<String>,
+    /// Resolved memory allowlist as a set of agent **aliases**. The
+    /// bound `parent_alias` is always included so the SubAgent always
+    /// sees the parent's own rows; the rest is either the parent's
+    /// allowlist verbatim or a validated subset.
+    ///
+    /// See [`SubAgentOverrides::allowed_agent_aliases`] for the
+    /// alias-vs-backend-identifier distinction; consumers that build
+    /// an [`AgentScopedMemory`] must resolve to backend identifiers
+    /// before passing the set to the wrapper.
+    pub allowed_agent_aliases: HashSet<String>,
 }
 
 /// Builder for a SubAgent spawn. The caller resolves a parent agent
 /// from the loaded config; [`Self::build`] applies any narrowing
 /// overrides and validates the result.
 #[derive(Debug)]
 pub struct SubAgentSpawn {
-    pub parent_agent_id: String,
+    pub parent_alias: String,
     pub parent_policy: Arc<SecurityPolicy>,
-    pub parent_allowed_agent_ids: HashSet<String>,
+    pub parent_allowed_agent_aliases: HashSet<String>,
 }
 
 impl SubAgentSpawn {
@@ -91,18 +118,18 @@ impl SubAgentSpawn {
                 format!("could not resolve security policy for agent {agent_alias:?}")
             })?;
 
-        let mut parent_allowed_agent_ids: HashSet<String> = agent
+        let mut parent_allowed_agent_aliases: HashSet<String> = agent
             .workspace
             .read_memory_from
             .iter()
             .map(|alias| alias.as_str().to_string())
             .collect();
-        parent_allowed_agent_ids.insert(agent_alias.to_string());
+        parent_allowed_agent_aliases.insert(agent_alias.to_string());
 
         Ok(Self {
-            parent_agent_id: agent_alias.to_string(),
+            parent_alias: agent_alias.to_string(),
             parent_policy,
-            parent_allowed_agent_ids,
+            parent_allowed_agent_aliases,
         })
     }
 
@@ -137,26 +164,26 @@ impl SubAgentSpawn {
             self.parent_policy.clone()
         };
 
-        let allowed_agent_ids = if let Some(child_allowed) = overrides.allowed_agent_ids {
-            for id in &child_allowed {
-                if !self.parent_allowed_agent_ids.contains(id) {
+        let allowed_agent_aliases = if let Some(child_allowed) = overrides.allowed_agent_aliases {
+            for alias in &child_allowed {
+                if !self.parent_allowed_agent_aliases.contains(alias) {
                     anyhow::bail!(
-                        "subagent allowlist override contains agent_id {id:?} not present on \
+                        "subagent allowlist override contains alias {alias:?} not present on \
                          parent's memory allowlist; SubAgent overrides may only narrow"
                     );
                 }
             }
             let mut resolved = child_allowed;
-            resolved.insert(self.parent_agent_id.clone());
+            resolved.insert(self.parent_alias.clone());
             resolved
         } else {
-            self.parent_allowed_agent_ids
+            self.parent_allowed_agent_aliases
         };
 
         Ok(SubAgentContext {
-            agent_id: self.parent_agent_id,
+            parent_alias: self.parent_alias,
             policy,
-            allowed_agent_ids,
+            allowed_agent_aliases,
         })
     }
 }
@@ -189,9 +216,9 @@ mod tests {
             .expect("for_agent must succeed for a configured agent")
             .build(SubAgentOverrides::default())
             .expect("inherits-verbatim build must succeed");
-        assert_eq!(ctx.agent_id, "alpha");
+        assert_eq!(ctx.parent_alias, "alpha");
         assert!(
-            ctx.allowed_agent_ids.contains("alpha"),
+            ctx.allowed_agent_aliases.contains("alpha"),
             "an agent always sees its own rows"
         );
     }
@@ -211,11 +238,11 @@ mod tests {
         let config = config_with_agent("alpha");
         let spawn = SubAgentSpawn::for_agent(&config, "alpha").unwrap();
         let parent_policy = spawn.parent_policy.clone();
-        let parent_allowlist = spawn.parent_allowed_agent_ids.clone();
+        let parent_allowlist = spawn.parent_allowed_agent_aliases.clone();
 
         let ctx = spawn.build(SubAgentOverrides::default()).unwrap();
         assert!(Arc::ptr_eq(&ctx.policy, &parent_policy));
-        assert_eq!(ctx.allowed_agent_ids, parent_allowlist);
+        assert_eq!(ctx.allowed_agent_aliases, parent_allowlist);
     }
 
     #[test]
@@ -240,7 +267,7 @@ mod tests {
     }
 
     #[test]
-    fn build_rejects_allowlist_override_with_id_not_on_parent() {
+    fn build_rejects_allowlist_override_with_alias_not_on_parent() {
         let config = config_with_agent("alpha");
         let spawn = SubAgentSpawn::for_agent(&config, "alpha").unwrap();
 
@@ -249,13 +276,13 @@ mod tests {
 
         let err = spawn
             .build(SubAgentOverrides {
-                allowed_agent_ids: Some(rogue),
+                allowed_agent_aliases: Some(rogue),
                 ..SubAgentOverrides::default()
             })
-            .expect_err("allowlist override with foreign UUID must be rejected");
+            .expect_err("allowlist override with foreign alias must be rejected");
         assert!(
             err.to_string().contains("rogue-agent"),
-            "expected the rogue UUID in the error chain, got: {err}"
+            "expected the rogue alias in the error chain, got: {err}"
         );
     }
 
@@ -264,15 +291,15 @@ mod tests {
         let config = config_with_agent("alpha");
         let spawn = SubAgentSpawn::for_agent(&config, "alpha").unwrap();
 
-        // Empty subset is still allowed; the bound agent_id is added back.
+        // Empty subset is still allowed; the bound parent alias is added back.
         let ctx = spawn
             .build(SubAgentOverrides {
-                allowed_agent_ids: Some(HashSet::new()),
+                allowed_agent_aliases: Some(HashSet::new()),
                 ..SubAgentOverrides::default()
             })
             .expect("narrowing to {} is a valid subset");
-        assert_eq!(ctx.allowed_agent_ids.len(), 1);
-        assert!(ctx.allowed_agent_ids.contains("alpha"));
+        assert_eq!(ctx.allowed_agent_aliases.len(), 1);
+        assert!(ctx.allowed_agent_aliases.contains("alpha"));
     }
 
     #[test]

crates/zeroclaw-runtime/src/tools/delegate.rs

@@ -306,19 +306,31 @@ impl DelegateTool {
     }
 
     /// Build a `SecurityPolicy` for the delegated target agent
-    /// validated as a subset of the caller's policy with shared
-    /// action / cost tracker.
+    /// validated as **mutually equivalent** to the caller's policy
+    /// (neither escalates nor narrows), with the caller's action /
+    /// cost tracker shared into the returned policy.
     ///
     /// Returns:
     /// - `Ok(target_policy)` when `root_config` is set, the target
-    ///   resolves, and its policy is a subset of the caller's
-    ///   (`ensure_no_escalation_beyond`). The returned policy's
-    ///   `tracker` field is the caller's `Arc`-shared tracker so
-    ///   delegated actions count against the caller's
-    ///   `max_actions_per_hour` / `max_cost_per_day_cents`.
+    ///   resolves, and the target's policy is equivalent to the
+    ///   caller's under [`SecurityPolicy::ensure_no_escalation_beyond`]
+    ///   in both directions. The returned policy's `tracker` field is
+    ///   the caller's `Arc`-shared tracker so delegated actions count
+    ///   against the caller's `max_actions_per_hour` /
+    ///   `max_cost_per_day_cents`.
     /// - `Err(_)` on escalation: the target's risk profile or
     ///   workspace.access map would widen permissions beyond the
     ///   caller. The originating `EscalationViolation` is chained.
+    /// - `Err(_)` on narrowing: the target's policy is strictly
+    ///   tighter than the caller's. `DelegateTool` reuses the
+    ///   caller's `parent_tools` registry whose tools each hold the
+    ///   caller's `Arc<SecurityPolicy>` from registration time, so a
+    ///   narrower target would silently inherit the caller's broader
+    ///   allowlist — an over-grant the validator catches loudly here
+    ///   instead of letting it ship as an enforcement gap. The error
+    ///   message names `spawn_subagent` as the supported path for
+    ///   narrowed runs (it re-enters `agent::run`, which rebuilds the
+    ///   tool registry under the validated child policy).
     /// - `Ok(self.security)` (caller's policy) when `root_config`
     ///   is `None`. This branch only fires for the legacy unit-test
     ///   constructors that don't plumb root config.
@@ -338,6 +350,28 @@ impl DelegateTool {
                     "delegate target {target_alias:?} policy escalates beyond caller: {violation}"
                 )
             })?;
+        // Refuse strict narrowing. `DelegateTool::execute_agentic`
+        // reuses the caller's `parent_tools` registry (every tool
+        // there holds the caller's `Arc<SecurityPolicy>` from
+        // registration time); a narrower target policy would not
+        // reach those tools, so the target would silently inherit
+        // the caller's broader allowlist. Catching the narrowing
+        // here turns a silent over-grant into a loud refusal.
+        // Operators with truly narrowed sub-agents should use
+        // `spawn_subagent`, which re-enters `agent::run` with the
+        // validated child policy and rebuilds the tool registry
+        // under it.
+        self.security
+            .ensure_no_escalation_beyond(&target_policy)
+            .map_err(|violation| {
+                anyhow::anyhow!(
+                    "delegate target {target_alias:?} policy narrows the caller's ({violation}); \
+                     DelegateTool reuses the caller's tool registry, so narrowing is not enforced \
+                     by the spawned tool calls. Either align caller and target risk_profile / \
+                     workspace.access so the policies are equivalent, or use `spawn_subagent` for \
+                     a narrowed run."
+                )
+            })?;
         target_policy.tracker = self.security.tracker.clone();
         Ok(Arc::new(target_policy))
     }
@@ -1393,7 +1427,6 @@ impl DelegateTool {
         // sub-agent's own workspace dir. Each missing file is silently
         // skipped — the operator may not have authored every file.
         let target_workspace = self.agent_workspace(agent_alias);
-        let _ = agent_config; // kept for callers; no longer used here.
         let identity_files = [
             "AGENTS.md",
             "SOUL.md",
@@ -3270,4 +3303,74 @@ mod tests {
             "without root_config the helper returns the caller's Arc verbatim"
         );
     }
+
+    /// Build a config where `caller` has a strictly broader policy
+    /// than `target`. The caller-only command is the narrowing axis
+    /// the validator should catch.
+    fn config_with_narrowed_target() -> Arc<zeroclaw_config::schema::Config> {
+        use zeroclaw_config::schema::{AliasedAgentConfig, Config, RiskProfileConfig};
+        let mut config = Config::default();
+        config.risk_profiles.insert(
+            "broad".to_string(),
+            RiskProfileConfig {
+                allowed_commands: vec!["git".into(), "cargo".into()],
+                ..RiskProfileConfig::default()
+            },
+        );
+        config.risk_profiles.insert(
+            "narrow".to_string(),
+            RiskProfileConfig {
+                allowed_commands: vec!["git".into()],
+                ..RiskProfileConfig::default()
+            },
+        );
+        config.agents.insert(
+            "caller".to_string(),
+            AliasedAgentConfig {
+                risk_profile: "broad".to_string(),
+                model_provider: "ollama.caller".into(),
+                ..AliasedAgentConfig::default()
+            },
+        );
+        config.agents.insert(
+            "target".to_string(),
+            AliasedAgentConfig {
+                risk_profile: "narrow".to_string(),
+                model_provider: "ollama.target".into(),
+                ..AliasedAgentConfig::default()
+            },
+        );
+        Arc::new(config)
+    }
+
+    #[tokio::test]
+    async fn delegate_rejects_target_whose_policy_narrows_caller() {
+        // DelegateTool's spawned agentic loop reuses the caller's
+        // parent_tools registry — a narrower target would silently
+        // inherit the caller's broader allowlist. The validator
+        // must catch the narrowing at the delegate boundary and
+        // refuse to dispatch.
+        let config = config_with_narrowed_target();
+        let caller_policy =
+            Arc::new(SecurityPolicy::for_agent(&config, "caller").expect("caller policy resolves"));
+        let mut delegate_agents = HashMap::new();
+        for (name, agent) in &config.agents {
+            delegate_agents.insert(name.clone(), agent.clone());
+        }
+        let tool = DelegateTool::new(delegate_agents, None, caller_policy)
+            .with_root_config(config.clone());
+
+        let err = tool
+            .policy_for_target("target")
+            .expect_err("narrowing target must be rejected at delegate boundary");
+        let chain = format!("{err:#}");
+        assert!(
+            chain.contains("narrows the caller"),
+            "expected narrowing error, got: {chain}"
+        );
+        assert!(
+            chain.contains("spawn_subagent"),
+            "error must point operators at spawn_subagent for narrowed runs, got: {chain}"
+        );
+    }
 }

crates/zeroclaw-runtime/src/tools/spawn_subagent.rs

@@ -100,7 +100,7 @@ impl Tool for SpawnSubagentTool {
         let run_id = uuid::Uuid::new_v4().to_string();
         let span = tracing::info_span!(
             "subagent",
-            parent_alias = %subagent_ctx.agent_id,
+            parent_alias = %subagent_ctx.parent_alias,
             run_id = %run_id,
             spawn_site = "tool",
         );