#13331: feat(sessions_spawn): add sessionKey param to reuse sub-agent sessions
agents
size: S
Cluster:
Subagent Enhancements and Features
## What
Add an optional `sessionKey` parameter to `sessions_spawn`. When provided, the sub-agent runs in a deterministic session (`agent:{agentId}:subagent:{sessionKey}`) instead of a new random-UUID session each time.
## Why
Currently every `sessions_spawn` call creates a brand-new session with a random UUID. This makes it impossible to:
- Maintain a **fixed pool** of sub-agents with persistent conversation history
- Reuse the same sub-agent session across multiple spawns
- Track sub-agent activity by a human-readable key
### Use case: fixed agent pool
A dispatcher agent can define a set of named sub-agents (e.g. `worker-1`, `worker-2`, ...) and route tasks to them by `sessionKey`. Each worker accumulates context across tasks, and the dispatcher can track which worker is busy.
## How
- Added `sessionKey` (optional string) to `SessionsSpawnToolSchema`
- Modified `childSessionKey` generation:
- If `sessionKey` is provided, use `agent:{agentId}:subagent:{sessionKey}`
- If the provided key already contains `:subagent:`, use it as-is (fully-qualified)
- If omitted, fall back to `crypto.randomUUID()` — **no behavior change**
## Tests
3 new test cases:
1. Custom `sessionKey` produces a deterministic session key
2. No `sessionKey` falls back to random UUID (backward compat)
3. Fully-qualified key is used as-is
All 21 existing spawn-related tests continue to pass.
## AI-assisted
This PR was AI-assisted (Claude). Tested locally with a patched OpenClaw instance running the fixed-session-pool pattern.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds an optional `sessionKey` parameter to `sessions_spawn` so callers can reuse a deterministic sub-agent session key instead of always creating a new UUID-based session. It updates the spawn tool’s TypeBox schema and changes `childSessionKey` generation to:
- use `agent:{agentId}:subagent:{sessionKey}` for short keys
- accept fully-qualified keys containing `:subagent:` verbatim
- otherwise keep the existing random UUID behavior
It also adds a new Vitest file covering deterministic keys, UUID fallback, and the fully-qualified passthrough behavior.
<h3>Confidence Score: 3/5</h3>
- This PR has a likely authorization bypass via fully-qualified session keys that should be fixed before merge.
- Core behavior change is small and tests cover the happy paths, but the new passthrough for fully-qualified `sessionKey` appears to let callers target another agent’s subagent session without passing the `agentId` allowlist check, which is a significant correctness/security concern.
- src/agents/tools/sessions-spawn-tool.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#20072: feat(sessions_spawn): add sessionKey param to reuse sub-agent sessions
by Be1Human · 2026-02-18
90.9%
#10748: feat: Add sessions.spawn gateway method for direct subagent spawning
by fox-openclaw · 2026-02-06
84.3%
#23506: feat(spawn): per-spawn tool permissions for sessions_spawn
by dissaozw · 2026-02-22
80.1%
#11296: fix: add sessionKey alias to sessions_spawn for backward compatibility
by jgs-jeeves · 2026-02-07
79.7%
#16247: feat(agents): declarative agent definitions for sessions_spawn
by zerone0x · 2026-02-14
78.1%
#22098: fix: isolate agent sessions by explicit --session-id
by AIflow-Labs · 2026-02-20
77.7%
#13412: fix(sessions): refresh allowAgents permissions after gateway restart
by arun-dev-des · 2026-02-10
77.2%
#17921: feat: add spawnableBy bidirectional sub-agent spawn authorization
by jacobot01 · 2026-02-16
76.7%
#13303: feat(subagents): replace silent boolean with announce enum ('user'|...
by ivalsaraj · 2026-02-10
76.7%
#7292: feat: Implement subagent model inheritance system
by levineam · 2026-02-02
76.4%