fix: constrain wildcard subagent targets (#84357)

joshavant · web-flow · commit 00da318350e2 · 2026-05-19T19:21:13.000-05:00
* fix subagent wildcard targets

* add changelog for subagent wildcard fix
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -29,6 +29,7 @@ Docs: https://docs.openclaw.ai
 
 - Agents: include bounded trajectory queued-writer diagnostics in `pi-trajectory-flush` timeout warnings so flush stalls show pending writes, queued bytes, and append state. Fixes #82961. (#82962) Thanks @galiniliev.
 - Agents/subagents: recover stale completion announces by retrying unsupported transcript-wait wakes without transcript waiting and forcing a message-tool handoff when the requester run is already stale. Fixes #83699. (#83700) Thanks @galiniliev.
+- Agents/subagents: constrain wildcard subagent target allowlists to configured agents while preserving explicitly listed compatibility targets. Fixes #84040. (#84357) Thanks @joshavant.
 - Agents: honor explicit `models.providers.<id>.timeoutSeconds` values above the default idle watchdog for cloud and self-hosted providers, so long first-token waits no longer fall back at ~120s when the provider timeout is higher. (#83979) Thanks @yujiawei.
 - Agents/subagents: skip stale embedded-run wake probes for dormant completion requesters, so late subagent completions go straight to requester-agent/direct handoff instead of producing `reason=no_active_run` queue noise. (#82964) Thanks @galiniliev.
 - CLI: retry config snapshot reads after a transient failure so one rejected read no longer poisons later commands in the same process. (#83931) Thanks @honor2030.
diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md
@@ -1092,7 +1092,7 @@ for provider examples and precedence.
 - `runtime`: optional per-agent runtime descriptor. Use `type: "acp"` with `runtime.acp` defaults (`agent`, `backend`, `mode`, `cwd`) when the agent should default to ACP harness sessions.
 - `identity.avatar`: workspace-relative path, `http(s)` URL, or `data:` URI.
 - `identity` derives defaults: `ackReaction` from `emoji`, `mentionPatterns` from `name`/`emoji`.
-- `subagents.allowAgents`: allowlist of agent ids for explicit `sessions_spawn.agentId` targets (`["*"]` = any; default: same agent only). Include the requester id when self-targeted `agentId` calls should be allowed.
+- `subagents.allowAgents`: allowlist of agent ids for explicit `sessions_spawn.agentId` targets (`["*"]` = any configured target; default: same agent only). Include the requester id when self-targeted `agentId` calls should be allowed.
 - Sandbox inheritance guard: if the requester session is sandboxed, `sessions_spawn` rejects targets that would run unsandboxed.
 - `subagents.requireAgentId`: when true, block `sessions_spawn` calls that omit `agentId` (forces explicit profile selection; default: false).
 
diff --git a/docs/gateway/config-tools.md b/docs/gateway/config-tools.md
@@ -401,7 +401,7 @@ Experimental built-in tool flags. Default off unless a strict-agentic GPT-5 auto
 ```
 
 - `model`: default model for spawned sub-agents. If omitted, sub-agents inherit the caller's model.
-- `allowAgents`: default allowlist of target agent ids for `sessions_spawn` when the requester agent does not set its own `subagents.allowAgents` (`["*"]` = any; default: same agent only).
+- `allowAgents`: default allowlist of target agent ids for `sessions_spawn` when the requester agent does not set its own `subagents.allowAgents` (`["*"]` = any configured target; default: same agent only).
 - `runTimeoutSeconds`: default timeout (seconds) for `sessions_spawn` when the tool call omits `runTimeoutSeconds`. `0` means no timeout.
 - `announceTimeoutMs`: per-call timeout (milliseconds) for gateway `agent` announce delivery attempts. Default: `120000`. Transient retries can make the total announce wait longer than one configured timeout.
 - Per-subagent tool policy: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md
@@ -340,7 +340,7 @@ See [Configuration reference](/gateway/configuration-reference) and
 ### Allowlist
 
 <ParamField path="agents.list[].subagents.allowAgents" type="string[]">
-  List of agent ids that can be targeted via explicit `agentId` (`["*"]` allows any). Default: only the requester agent. If you set a list and still want the requester to spawn itself with `agentId`, include the requester id in the list.
+  List of agent ids that can be targeted via explicit `agentId` (`["*"]` allows any configured target). Default: only the requester agent. If you set a list and still want the requester to spawn itself with `agentId`, include the requester id in the list.
 </ParamField>
 <ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
   Default target-agent allowlist used when the requester agent does not set its own `subagents.allowAgents`.
diff --git a/src/agents/acp-spawn.test.ts b/src/agents/acp-spawn.test.ts
@@ -1230,6 +1230,78 @@ describe("spawnAcpDirect", () => {
     expectAcceptedSpawn(result);
   });
 
+  it("allows configured ACP harness ids when subagent allowlist contains wildcard", async () => {
+    replaceSpawnConfig({
+      ...hoisted.state.cfg,
+      acp: {
+        ...hoisted.state.cfg.acp,
+        allowedAgents: ["codex", "writer"],
+      },
+      agents: {
+        ...hoisted.state.cfg.agents,
+        list: [
+          {
+            id: "main",
+            default: true,
+            subagents: {
+              allowAgents: ["*"],
+            },
+          },
+        ],
+      },
+    });
+
+    const result = await spawnAcpDirect(
+      createSpawnRequest({
+        agentId: "writer",
+      }),
+      {
+        ...createRequesterContext(),
+        agentSessionKey: "agent:main:subagent:parent",
+      },
+    );
+
+    expectAcceptedSpawn(result);
+  });
+
+  it("rejects unconfigured ACP harness ids when subagent allowlist contains wildcard", async () => {
+    replaceSpawnConfig({
+      ...hoisted.state.cfg,
+      acp: {
+        ...hoisted.state.cfg.acp,
+        allowedAgents: [],
+      },
+      agents: {
+        ...hoisted.state.cfg.agents,
+        list: [
+          {
+            id: "main",
+            default: true,
+            subagents: {
+              allowAgents: ["*"],
+            },
+          },
+        ],
+      },
+    });
+
+    const result = await spawnAcpDirect(
+      createSpawnRequest({
+        agentId: "writer",
+      }),
+      {
+        ...createRequesterContext(),
+        agentSessionKey: "agent:main:subagent:parent",
+      },
+    );
+
+    const failed = expectFailedSpawn(result, "forbidden");
+    expect(failed.errorCode).toBe("subagent_policy");
+    expect(failed.error).toBe(
+      'agentId "writer" is not in the configured agent registry (allowed: main)',
+    );
+  });
+
   it("rejects ACP spawns to agents outside the subagent allowlist", async () => {
     replaceSpawnConfig({
       ...hoisted.state.cfg,
diff --git a/src/agents/acp-spawn.ts b/src/agents/acp-spawn.ts
@@ -70,7 +70,7 @@ import {
   resolveAcpSpawnStreamLogPath,
   startAcpSpawnParentStreamRelay,
 } from "./acp-spawn-parent-stream.js";
-import { resolveAgentConfig, resolveDefaultAgentId } from "./agent-scope.js";
+import { listAgentIds, resolveAgentConfig, resolveDefaultAgentId } from "./agent-scope.js";
 import {
   findAcpUnsupportedInheritedToolAllow,
   findAcpUnsupportedInheritedToolDeny,
@@ -447,11 +447,41 @@ function resolveTargetAcpAgentId(params: {
 
 function isExplicitlyAllowedAcpAgent(cfg: OpenClawConfig, agentId: string): boolean {
   return (cfg.acp?.allowedAgents ?? []).some((entry) => {
+    if (entry.trim() === "*") {
+      return true;
+    }
     const normalized = normalizeOptionalAgentId(entry);
-    return normalized === "*" || normalized === agentId;
+    return normalized === agentId;
   });
 }
 
+function resolveConfiguredAcpSubagentTargetIds(cfg: OpenClawConfig): string[] {
+  const ids = new Set<string>(listAgentIds(cfg));
+  for (const agent of cfg.agents?.list ?? []) {
+    if (agent.runtime?.type !== "acp") {
+      continue;
+    }
+    const acpAgent = normalizeOptionalAgentId(agent.runtime.acp?.agent);
+    if (acpAgent) {
+      ids.add(acpAgent);
+    }
+  }
+  const defaultAgent = normalizeOptionalAgentId(cfg.acp?.defaultAgent);
+  if (defaultAgent) {
+    ids.add(defaultAgent);
+  }
+  for (const entry of cfg.acp?.allowedAgents ?? []) {
+    if (entry.trim() === "*") {
+      continue;
+    }
+    const id = normalizeOptionalAgentId(entry);
+    if (id) {
+      ids.add(id);
+    }
+  }
+  return Array.from(ids);
+}
+
 function normalizeOptionalAgentId(value: string | undefined | null): string | undefined {
   const trimmed = normalizeOptionalString(value) ?? "";
   if (!trimmed) {
@@ -801,6 +831,7 @@ function resolveAcpSubagentEnvelopeState(params: {
     allowAgents:
       resolveAgentConfig(params.cfg, requesterAgentId)?.subagents?.allowAgents ??
       params.cfg.agents?.defaults?.subagents?.allowAgents,
+    configuredAgentIds: resolveConfiguredAcpSubagentTargetIds(params.cfg),
   });
   if (!targetPolicy.ok) {
     return {
diff --git a/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.test.ts b/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.test.ts
@@ -137,14 +137,39 @@ describe("subagent spawn allowlist + sandbox guards", () => {
     expectChildSessionKey(result, /^agent:beta:subagent:/);
   });
 
-  it("allows any agent when allowlist contains *", async () => {
+  it("allows configured agents when allowlist contains *", async () => {
+    setConfig({
+      agents: {
+        list: [{ id: "main", subagents: { allowAgents: ["*"] } }, { id: "beta" }],
+      },
+    });
+    const result = await spawn({ agentId: "beta" });
+    expectStatus(result, "accepted");
+  });
+
+  it("rejects unconfigured agent ids when allowlist contains *", async () => {
     setConfig({
       agents: {
         list: [{ id: "main", subagents: { allowAgents: ["*"] } }],
       },
     });
     const result = await spawn({ agentId: "beta" });
+    expectStatus(result, "forbidden");
+    expect(result.error ?? "").toBe(
+      'agentId "beta" is not in the configured agent registry (allowed: main)',
+    );
+    expect(hoisted.callGatewayMock).not.toHaveBeenCalled();
+  });
+
+  it("allows explicit unconfigured agent ids when allowlist also contains *", async () => {
+    setConfig({
+      agents: {
+        list: [{ id: "main", subagents: { allowAgents: ["*", "beta"] } }],
+      },
+    });
+    const result = await spawn({ agentId: "beta" });
     expectStatus(result, "accepted");
+    expectChildSessionKey(result, /^agent:beta:subagent:/);
   });
 
   it("normalizes allowlisted agent ids", async () => {
diff --git a/src/agents/subagent-spawn.ts b/src/agents/subagent-spawn.ts
@@ -12,7 +12,7 @@ import type { SubagentLifecycleHookRunner } from "../plugins/hooks.js";
 import { isValidAgentId, normalizeAgentId, parseAgentSessionKey } from "../routing/session-key.js";
 import { normalizeOptionalString } from "../shared/string-coerce.js";
 import type { DeliveryContext } from "../utils/delivery-context.types.js";
-import { resolveAgentDir } from "./agent-scope-config.js";
+import { listAgentIds, resolveAgentDir } from "./agent-scope-config.js";
 import type { BootstrapContextMode } from "./bootstrap-files.js";
 import {
   inheritedToolAllowPatch,
@@ -93,6 +93,10 @@ export type {
 
 export { decodeStrictBase64 };
 
+function resolveConfiguredAgentIds(cfg: OpenClawConfig): string[] {
+  return listAgentIds(cfg);
+}
+
 type SubagentSpawnDeps = {
   callGateway: typeof callGateway;
   forkSessionFromParent: typeof forkSessionFromParent;
@@ -839,6 +843,7 @@ export async function spawnSubagentDirect(
     allowAgents:
       resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ??
       cfg?.agents?.defaults?.subagents?.allowAgents,
+    configuredAgentIds: resolveConfiguredAgentIds(cfg),
   });
   if (!targetPolicy.ok) {
     return {
diff --git a/src/agents/subagent-target-policy.test.ts b/src/agents/subagent-target-policy.test.ts
@@ -64,4 +64,59 @@ describe("subagent target policy", () => {
       allowedIds: ["planner"],
     });
   });
+
+  it("limits wildcard allowlists to configured agents plus the requester", () => {
+    expect(
+      resolveSubagentAllowedTargetIds({
+        requesterAgentId: "main",
+        allowAgents: ["*"],
+        configuredAgentIds: ["planner", "checker"],
+      }),
+    ).toEqual({
+      allowAny: true,
+      allowedIds: ["checker", "main", "planner"],
+    });
+  });
+
+  it("rejects wildcard targets outside the configured registry", () => {
+    const result = resolveSubagentTargetPolicy({
+      requesterAgentId: "main",
+      targetAgentId: "bogus",
+      requestedAgentId: "bogus",
+      allowAgents: ["*"],
+      configuredAgentIds: ["main", "planner"],
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      throw new Error("Expected target policy to reject unconfigured wildcard target");
+    }
+    expect(result.allowedText).toBe("main, planner");
+    expect(result.error).toBe(
+      'agentId "bogus" is not in the configured agent registry (allowed: main, planner)',
+    );
+  });
+
+  it("preserves explicit targets when wildcard allowlists are mixed", () => {
+    expect(
+      resolveSubagentAllowedTargetIds({
+        requesterAgentId: "main",
+        allowAgents: ["*", "beta"],
+        configuredAgentIds: ["main", "planner"],
+      }),
+    ).toEqual({
+      allowAny: true,
+      allowedIds: ["beta", "main", "planner"],
+    });
+
+    expect(
+      resolveSubagentTargetPolicy({
+        requesterAgentId: "main",
+        targetAgentId: "beta",
+        requestedAgentId: "beta",
+        allowAgents: ["*", "beta"],
+        configuredAgentIds: ["main", "planner"],
+      }),
+    ).toEqual({ ok: true });
+  });
 });
diff --git a/src/agents/subagent-target-policy.ts b/src/agents/subagent-target-policy.ts
@@ -43,6 +43,10 @@ export function resolveSubagentAllowedTargetIds(params: {
     const configuredIds = (params.configuredAgentIds ?? [])
       .map((id) => normalizeAgentId(id))
       .filter(Boolean);
+    configuredIds.push(...policy.allowedIds);
+    if (requesterAgentId) {
+      configuredIds.push(requesterAgentId);
+    }
     return {
       allowAny: true,
       allowedIds: Array.from(new Set(configuredIds)).toSorted((a, b) => a.localeCompare(b)),
@@ -59,6 +63,7 @@ export function resolveSubagentTargetPolicy(params: {
   targetAgentId: string;
   requestedAgentId?: string;
   allowAgents?: readonly string[];
+  configuredAgentIds?: readonly string[];
 }): SubagentTargetPolicyResult {
   const requesterAgentId = normalizeAgentId(params.requesterAgentId);
   const targetAgentId = normalizeAgentId(params.targetAgentId);
@@ -69,11 +74,19 @@ export function resolveSubagentTargetPolicy(params: {
   const allowed = resolveSubagentAllowedTargetIds({
     requesterAgentId,
     allowAgents: params.allowAgents,
+    configuredAgentIds: params.configuredAgentIds,
   });
-  if (allowed.allowAny || allowed.allowedIds.includes(targetAgentId)) {
+  if (allowed.allowedIds.includes(targetAgentId)) {
     return { ok: true };
   }
   const allowedText = allowed.allowedIds.length > 0 ? allowed.allowedIds.join(", ") : "none";
+  if (allowed.allowAny) {
+    return {
+      ok: false,
+      allowedText,
+      error: `agentId "${targetAgentId}" is not in the configured agent registry (allowed: ${allowedText})`,
+    };
+  }
   return {
     ok: false,
     allowedText,
diff --git a/src/config/types.agent-defaults.ts b/src/config/types.agent-defaults.ts
@@ -434,7 +434,7 @@ export type AgentDefaultsConfig = {
   subagents?: {
     /** Prompt-only guidance for how strongly the main agent should delegate work. Default: "suggest". */
     delegationMode?: SubagentDelegationMode;
-    /** Default allowlist of target agent ids for sessions_spawn. Use "*" to allow any. */
+    /** Default allowlist of target agent ids for sessions_spawn. Use "*" to allow any configured target. */
     allowAgents?: string[];
     /** Max concurrent sub-agent runs (global lane: "subagent"). Default: 1. */
     maxConcurrent?: number;
diff --git a/src/config/types.agents.ts b/src/config/types.agents.ts
@@ -131,7 +131,7 @@ export type AgentConfig = {
   subagents?: {
     /** Prompt-only guidance for how strongly this agent should delegate work. */
     delegationMode?: SubagentDelegationMode;
-    /** Allow spawning sub-agents under other agent ids. Use "*" to allow any. */
+    /** Allow spawning sub-agents under other agent ids. Use "*" to allow any configured target. */
     allowAgents?: string[];
     /** Per-agent default model for spawned sub-agents (string or {primary,fallbacks}). */
     model?: AgentModelConfig;
