fix(agent): user's model pick wins over orchestrator coding pin; stop offering fleet tools the parent lacks

crates/openhuman-core/src/agent/orchestration/fleet_tools.rs

@@ -0,0 +1,114 @@
+//! Which fleet-control tools a parent agent can actually call.
+//!
+//! The `[async_subagent_ref]` envelope and the ambient `[active_subagents]`
+//! roster used to hard-code a full fleet vocabulary — `wait_subagent`,
+//! `steer_subagent`, `wait_loop`, `close_subagent` — while the orchestrator's
+//! definition deliberately dropped most of it (#5701: a sub-agent result is
+//! delivered back automatically on a later turn, so nothing needs to block).
+//! The model was told to call tools it did not have, spent an iteration
+//! reasoning about the mismatch, and improvised (`shell echo "waiting for
+//! subagent"`). Every delegation paid a full extra model call for nothing.
+//!
+//! This module reads the parent's definition once per render and answers
+//! "does this parent see tool X?", so both texts only ever name tools that
+//! are in the caller's belt.
+
+use crate::agent::harness::definition::{AgentDefinitionRegistry, ToolScope};
+
+/// The fleet-control tools whose availability shapes the delegation texts.
+const FLEET_TOOLS: &[&str] = &[
+    "steer_subagent",
+    "wait_subagent",
+    "wait",
+    "wait_loop",
+    "close_subagent",
+    "continue_subagent",
+    "list_subagents",
+];
+
+/// The subset of [`FLEET_TOOLS`] a given parent definition exposes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct FleetToolSet {
+    available: Vec<&'static str>,
+}
+
+impl FleetToolSet {
+    /// Every fleet tool — the pre-#5701 assumption, used when the parent's
+    /// definition cannot be resolved so the texts degrade to their old shape
+    /// rather than to silence.
+    pub(crate) fn all() -> Self {
+        Self {
+            available: FLEET_TOOLS.to_vec(),
+        }
+    }
+
+    /// Resolve the set for `agent_definition_id` from the global registry.
+    pub(crate) fn for_parent(agent_definition_id: &str) -> Self {
+        let Some(registry) = AgentDefinitionRegistry::global() else {
+            return Self::all();
+        };
+        let Some(definition) = registry.get(agent_definition_id) else {
+            log::debug!(
+                "[fleet_tools] parent definition '{}' not in registry; assuming full fleet vocabulary",
+                agent_definition_id
+            );
+            return Self::all();
+        };
+        Self::from_scope(&definition.tools, &definition.disallowed_tools)
+    }
+
+    /// Resolve the set from a turn's *effective* visible tool names — the
+    /// live, already-filtered membership set (hides, named restrictions, and
+    /// policy narrowing all applied), as opposed to [`Self::for_parent`]'s
+    /// static read of the parent's registered definition. Prefer this
+    /// whenever the caller already has that snapshot: a hide or restriction
+    /// applied mid-session can narrow a turn's real tool surface below what
+    /// the definition alone would suggest, and offering a control absent
+    /// from this snapshot invites a denied tool call.
+    pub(crate) fn from_visible_tool_names(names: &std::collections::HashSet<String>) -> Self {
+        let available = FLEET_TOOLS
+            .iter()
+            .copied()
+            .filter(|name| names.contains(*name))
+            .collect();
+        Self { available }
+    }
+
+    /// Derive the set from a definition's tool scope and denylist. A
+    /// `Named` scope exposes exactly the fleet tools it lists; `Wildcard`
+    /// exposes all of them. `disallowed_tools` (exact or trailing-`*`
+    /// prefix) removes entries from either.
+    pub(crate) fn from_scope(scope: &ToolScope, disallowed: &[String]) -> Self {
+        let denied = |name: &str| {
+            disallowed
+                .iter()
+                .any(|entry| match entry.strip_suffix('*') {
+                    Some(prefix) => name.starts_with(prefix),
+                    None => entry == name,
+                })
+        };
+        let available = FLEET_TOOLS
+            .iter()
+            .copied()
+            .filter(|name| match scope {
+                ToolScope::Wildcard => true,
+                ToolScope::Named(named) => named.iter().any(|n| n == name),
+            })
+            .filter(|name| !denied(name))
+            .collect();
+        Self { available }
+    }
+
+    pub(crate) fn has(&self, tool: &str) -> bool {
+        self.available.contains(&tool)
+    }
+
+    /// Whether the parent can block on or poll a worker at all.
+    pub(crate) fn can_wait(&self) -> bool {
+        self.has("wait_subagent")
+    }
+}
+
+#[cfg(test)]
+#[path = "fleet_tools_tests.rs"]
+mod tests;

crates/openhuman-core/src/agent/orchestration/fleet_tools_tests.rs

@@ -0,0 +1,67 @@
+use super::FleetToolSet;
+use crate::agent::harness::definition::ToolScope;
+
+fn named(tools: &[&str]) -> ToolScope {
+    ToolScope::Named(tools.iter().map(|t| t.to_string()).collect())
+}
+
+#[test]
+fn named_scope_exposes_only_listed_fleet_tools() {
+    let set = FleetToolSet::from_scope(
+        &named(&[
+            "spawn_async_subagent",
+            "list_subagents",
+            "continue_subagent",
+            "shell",
+        ]),
+        &[],
+    );
+    assert!(set.has("list_subagents"));
+    assert!(set.has("continue_subagent"));
+    assert!(!set.has("wait_subagent"));
+    assert!(!set.has("steer_subagent"));
+    assert!(!set.has("wait_loop"));
+    assert!(!set.can_wait());
+}
+
+#[test]
+fn wildcard_scope_exposes_every_fleet_tool_minus_denylist() {
+    let set = FleetToolSet::from_scope(&ToolScope::Wildcard, &["wait*".to_string()]);
+    assert!(set.has("steer_subagent"));
+    assert!(set.has("close_subagent"));
+    assert!(!set.has("wait"));
+    assert!(!set.has("wait_loop"));
+    assert!(!set.has("wait_subagent"));
+    assert!(!set.can_wait());
+}
+
+#[test]
+fn all_is_the_full_vocabulary() {
+    let set = FleetToolSet::all();
+    for tool in [
+        "steer_subagent",
+        "wait_subagent",
+        "wait",
+        "wait_loop",
+        "close_subagent",
+        "continue_subagent",
+        "list_subagents",
+    ] {
+        assert!(set.has(tool), "{tool}");
+    }
+    assert!(set.can_wait());
+}
+
+/// The shipped orchestrator definition is the case that motivated this
+/// module: it must not be told about wait/steer/close tools.
+#[test]
+fn builtin_orchestrator_has_no_wait_or_steer() {
+    let registry = crate::agent::harness::definition::AgentDefinitionRegistry::builtins_only();
+    let def = registry.get("orchestrator").expect("built-in orchestrator");
+    let set = FleetToolSet::from_scope(&def.tools, &def.disallowed_tools);
+    assert!(set.has("list_subagents"));
+    assert!(set.has("continue_subagent"));
+    assert!(!set.can_wait());
+    assert!(!set.has("steer_subagent"));
+    assert!(!set.has("close_subagent"));
+}

crates/openhuman-core/src/agent/orchestration/mod.rs

@@ -20,6 +20,7 @@ pub(crate) mod background_completions;
 pub(crate) mod background_delivery;
 pub mod command_center;
 pub(crate) mod delegation;
+pub(crate) mod fleet_tools;
 mod ops;
 pub(crate) mod parent_context;
 pub(crate) mod run_ledger_finalize;

crates/openhuman-core/src/agent/orchestration/running_subagents/roster.rs

@@ -3,6 +3,7 @@
 //! `[active_subagents]` context block.
 
 use super::registry::{registry, SubagentStatus};
+use crate::agent::orchestration::fleet_tools::FleetToolSet;
 
 /// Compact, read-only view of one registered sub-agent, for ambient injection
 /// into a parent's turn context (see [`active_subagents_context_block`]).
@@ -52,6 +53,40 @@ pub(crate) fn snapshot_for_parent(parent_session: &str) -> Vec<SubagentSnapshot>
     out
 }
 
+/// The follow-up guidance sentence, built from the tools the parent can see.
+fn roster_guidance(fleet: &FleetToolSet) -> String {
+    let mut parts: Vec<String> = Vec::new();
+    if fleet.has("wait_subagent") {
+        parts.push("use wait_subagent to collect a `completed` one".into());
+    } else {
+        parts.push(
+            "a `running` or `completed` worker's result is delivered to you automatically on a \
+             later turn — do not wait or poll for it"
+                .into(),
+        );
+    }
+    if fleet.has("steer_subagent") {
+        parts.push("steer_subagent to redirect a `running` one".into());
+    }
+    if fleet.has("continue_subagent") {
+        parts.push(
+            "continue_subagent to answer an `awaiting_user` one or to RESUME an `idle` one with \
+             a follow-up (it keeps its full prior context — do NOT re-delegate the same task \
+             from scratch)"
+                .into(),
+        );
+    }
+    if fleet.has("close_subagent") {
+        parts.push("close_subagent when done".into());
+    }
+    if fleet.has("list_subagents") {
+        parts.push("list_subagents to re-enumerate".into());
+    }
+    let mut sentence = parts.join(", ");
+    sentence.push('.');
+    sentence
+}
+
 /// Most-recent durable sessions surfaced in the roster when they are not in
 /// the live registry (cold boot / later turn). Bounds prompt growth on
 /// threads with a long delegation history.
@@ -71,9 +106,15 @@ const DURABLE_ROSTER_CAP: usize = 12;
 ///    cold-booted parent had no idea its previous sub-agents existed and
 ///    would re-delegate from scratch instead of resuming by
 ///    `subagent_session_id` (the "fresh context from day 0" bug).
+///
+/// `fleet` is the parent's fleet-control vocabulary: the guidance sentence
+/// only names tools the parent can call (the orchestrator has no
+/// `wait_subagent` / `steer_subagent` / `close_subagent` since #5701, and
+/// telling it otherwise cost an iteration of confused reasoning per turn).
 pub(crate) fn active_subagents_context_block(
     parent_session: &str,
     workspace_dir: &std::path::Path,
+    fleet: &FleetToolSet,
 ) -> Option<String> {
     let workers = snapshot_for_parent(parent_session);
 
@@ -114,13 +155,10 @@ pub(crate) fn active_subagents_context_block(
         "[active_subagents]\n\
          You have {} sub-agent worker(s) for this conversation (live and/or from earlier \
          turns). This is your authoritative roster — trust it over memory. Track each by \
-         subagent_session_id; use wait_subagent to collect a `completed` one, steer_subagent \
-         to redirect a `running` one, continue_subagent to answer an `awaiting_user` one or \
-         to RESUME an `idle` one with a follow-up (it keeps its full prior context — do NOT \
-         re-delegate the same task from scratch), close_subagent when done, and \
-         list_subagents to re-enumerate. Never fabricate a result for a worker still running \
+         subagent_session_id. {} Never fabricate a result for a worker still running \
          or one that has failed.\n",
-        workers.len() + durable.len()
+        workers.len() + durable.len(),
+        roster_guidance(fleet)
     );
     for w in &workers {
         let session = w.subagent_session_id.as_deref().unwrap_or("(none)");

crates/openhuman-core/src/agent/orchestration/running_subagents_tests.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::agent::orchestration::fleet_tools::FleetToolSet;
 use crate::agent::orchestration::running_subagents::registry::DETACHED_LEDGER_TIMEOUT_MS;
 use crate::agent::orchestration::running_subagents::resolve::resume_ref_for_task;
 use crate::agent::orchestration::running_subagents::resolve::task_id_for_session;
@@ -242,15 +243,45 @@ async fn snapshot_and_block_scope_to_parent_and_reflect_live_status() {
     assert_eq!(snap[1].status, "running");
 
     let block =
-        active_subagents_context_block("fleet-parent", &test_workspace()).expect("block present");
+        active_subagents_context_block("fleet-parent", &test_workspace(), &FleetToolSet::all())
+            .expect("block present");
     assert!(block.contains("[active_subagents]"));
+    assert!(block.contains("use wait_subagent to collect"));
     assert!(block.contains("You have 2 sub-agent worker(s)"));
     assert!(block.contains("session=subsess-a"));
     assert!(block.contains("session=subsess-b · task=task-fleet-b · status=awaiting_user"));
     assert!(block.ends_with("[/active_subagents]\n\n"));
 
     // A parent with no registered workers gets no block (no perturbation).
-    assert!(active_subagents_context_block("nobody-here", &test_workspace()).is_none());
+    assert!(
+        active_subagents_context_block("nobody-here", &test_workspace(), &FleetToolSet::all())
+            .is_none()
+    );
+
+    // The shipped orchestrator has no wait/steer/close tools (#5701): the
+    // guidance must not name them and must say results arrive on their own.
+    {
+        use crate::agent::harness::definition::AgentDefinitionRegistry;
+        let registry = AgentDefinitionRegistry::builtins_only();
+        let def = registry.get("orchestrator").expect("built-in orchestrator");
+        let fleet = FleetToolSet::from_scope(&def.tools, &def.disallowed_tools);
+        let block = active_subagents_context_block("fleet-parent", &test_workspace(), &fleet)
+            .expect("block present");
+        for name in [
+            "wait_subagent",
+            "steer_subagent",
+            "close_subagent",
+            "wait_loop",
+        ] {
+            assert!(
+                !block.contains(name),
+                "{name} named for a parent without it:\n{block}"
+            );
+        }
+        assert!(block.contains("delivered to you automatically"));
+        assert!(block.contains("continue_subagent"));
+        assert!(block.contains("list_subagents"));
+    }
 
     // Durable-store fallback: a session persisted by an EARLIER turn /
     // process lifetime (empty live registry for this parent) must still
@@ -295,13 +326,19 @@ async fn snapshot_and_block_scope_to_parent_and_reflect_live_status() {
         )
         .expect("mark idle");
 
-        let block = active_subagents_context_block("cold-parent", durable_ws.path())
-            .expect("durable-only roster present");
+        let block =
+            active_subagents_context_block("cold-parent", durable_ws.path(), &FleetToolSet::all())
+                .expect("durable-only roster present");
         assert!(block.contains(&format!("session={}", session.subagent_session_id)));
         assert!(block.contains("status=idle"));
         assert!(block.contains("about: Daily X trending email workflow"));
         // Other parents' durable sessions must not leak in.
-        assert!(active_subagents_context_block("unrelated-parent", durable_ws.path()).is_none());
+        assert!(active_subagents_context_block(
+            "unrelated-parent",
+            durable_ws.path(),
+            &FleetToolSet::all()
+        )
+        .is_none());
     }
 
     let _ = tx_a.send(SubagentStatus::Completed {