Summary

• Problem: ACP child sessions (agent:{id}:acp:{uuid}) were not recognized as subagent-envelope sessions by isSubagentSessionKey, so subagent tool policy, spawn-depth caps, per-parent child caps, and the subagents.allowAgents target allowlist were all skipped for ACP children spawned from within a subagent envelope.
• Why it matters: A restricted subagent could spawn an ACP child and regain access to tools blocked by the subagent deny list (e.g. sessions_send, agents_list), and bypass depth/child/allowlist caps — all while still running inside the same trusted gateway.
• What changed: Introduced isSubagentEnvelopeSession (replacing bare isSubagentSessionKey in three tool-policy call sites) to transitively detect ACP sessions parented by a subagent envelope via the spawnedBy chain. Added resolveAcpSubagentEnvelopeState to run depth, child-count, and allowAgents checks on the ACP spawn path and patch spawnDepth/subagentRole/subagentControlScope onto the child session record. Extracted DEFAULT_SUBAGENT_MAX_CHILDREN_PER_AGENT constant.
• What did NOT change: No changes to isSubagentSessionKey itself, ACP approval/allowlist classification, sandbox inheritance, per-sender authorization checks, or acp.allowedAgents default behavior.

Change Type (select all)

• Bug fix
• Security hardening

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution

Linked Issue/PR

• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: isSubagentSessionKey matches only keys with a subagent: rest segment. ACP child keys use acp:{uuid} and fell through, so pi-tools.ts, effective-tool-policy.ts, and gateway/tool-resolution.ts all skipped resolveSubagentToolPolicyForSession for them. The ACP spawn path in acp-spawn.ts also never ran the depth/child/allowAgents guards from subagent-spawn.ts.
• Missing detection / guardrail: No classification check or spawn-time guard for the ACP child case — the subagent path and ACP path shared no common enforcement point.
• Contributing context: Same inheritance-drift pattern as prior sandbox inheritance fixes — same ACP spawn call site, different boundary (subagent envelope rather than sandbox).

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
• Target test or file: src/agents/acp-spawn.test.ts, src/agents/pi-tools.create-openclaw-coding-tools.test.ts
• Scenario the test should lock in: ACP children spawned from a subagent session receive the subagent tool policy and are rejected when depth/child/allowAgents caps are exceeded.
• Why this is the smallest reliable guardrail: The spawn path and tool-policy gate are both exercised directly; no runtime or channel infrastructure required.
• Existing test that already covers this (if any): None — new cases added.

User-visible / Behavior Changes

• ACP children spawned from within a subagent envelope now inherit the subagent tool deny list. This is a restriction tightening, not a new permission.
• subagents.maxSpawnDepth, subagents.maxChildrenPerAgent, and subagents.allowAgents now apply to ACP spawns from subagent sessions (previously they applied only to runtime="subagent" spawns).
• DEFAULT_SUBAGENT_MAX_CHILDREN_PER_AGENT is now an exported constant (default value unchanged: 5).

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? Yes — tool deny lists now also apply to ACP child sessions parented by a subagent envelope. This restricts the tool surface for that session class; it does not expand it.
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux (Ubuntu)
• Runtime: Node 22
• Model/provider: N/A (unit tests only)
• Integration/channel: N/A

Steps

1. pnpm install
2. pnpm test src/agents/acp-spawn.test.ts
3. pnpm test src/agents/pi-tools.create-openclaw-coding-tools.test.ts
4. pnpm tsgo:prod

Expected

• All new test cases pass: depth rejection, child-cap rejection, allowAgents rejection, envelope field inheritance, ACP-child tool policy restriction.

Actual

• All tests pass on branch HEAD.

Evidence

• Failing test/log before + passing after — four new acp-spawn.test.ts cases and one new pi-tools integration case, all green on branch.

Human Verification (required)

⚠️ AI-assisted PR — generated by OpenAI Codex, reviewed by Claude Code. No human runtime verification was performed.

• Verified scenarios: Static analysis and unit test review confirm the three tool-policy call sites and the spawn-time gate are consistent with each other and with the prior subagent-spawn path.
• Edge cases checked: Non-subagent ACP sessions (plain ACP, not under a subagent envelope) are unaffected — isSubagentEnvelopeSession returns false for them and the spawn-time gate exits early.
• What you did not verify: Live gateway session, end-to-end channel round-trip, macOS app smoke.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — restriction tightening only; no API or config surface removed.
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: ACP children of subagents that previously had unrestricted tool access will now receive the deny list. Operators relying (intentionally or not) on the old behavior may see tool calls blocked.
  • Mitigation: The change matches the documented contract for subagent envelopes. No operator-visible config change is required. The fix aligns ACP spawn with runtime="subagent" spawn behavior.