#20072: feat(sessions_spawn): add sessionKey param to reuse sub-agent sessions

Add an optional `sessionKey` parameter to `sessions_spawn`. When provided, the sub-agent runs in a deterministic session instead of a new random-UUID session each time, preserving conversation history across spawns. - If `sessionKey` is a short key, maps to `agent:{agentId}:subagent:{sessionKey}` - If `sessionKey` is fully-qualified (contains ":subagent:"), validates that the embedded agentId matches targetAgentId to prevent cross-agent session injection - Falls back to `crypto.randomUUID()` when omitted — no behavior change Fixes: session key bypasses allowlist (Greptile review finding) Tests: 4 cases covering deterministic key, UUID fallback, fully-qualified passthrough, and cross-agent mismatch rejection. ## Summary Describe the problem and fix in 2–5 bullets: - Problem: - Why it matters: - What changed: - What did NOT change (scope boundary): ## Change Type (select all) - [ ] Bug fix - [ ] Feature - [ ] Refactor - [ ] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [ ] Gateway / orchestration - [ ] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [ ] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes # - Related # ## User-visible / Behavior Changes List user-visible changes (including defaults/config). If none, write `None`. ## Security Impact (required) - New permissions/capabilities? (`Yes/No`) - Secrets/tokens handling changed? (`Yes/No`) - New/changed network calls? (`Yes/No`) - Command/tool execution surface changed? (`Yes/No`) - Data access scope changed? (`Yes/No`) - If any `Yes`, explain risk + mitigation: ## Repro + Verification ### Environment - OS: - Runtime/container: - Model/provider: - Integration/channel (if any): - Relevant config (redacted): ### Steps 1. 2. 3. ### Expected - ### Actual - ## Evidence Attach at least one: - [ ] Failing test/log before + passing after - [ ] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) ## Human Verification (required) What you personally verified (not just CI), and how: - Verified scenarios: - Edge cases checked: - What you did **not** verify: ## Compatibility / Migration - Backward compatible? (`Yes/No`) - Config/env changes? (`Yes/No`) - Migration needed? (`Yes/No`) - If yes, exact upgrade steps: ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: - Files/config to restore: - Known bad symptoms reviewers should watch for: ## Risks and Mitigations List only real risks for this PR. Add/remove entries as needed. If none, write `None`. - Risk: - Mitigation: <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR adds an optional `sessionKey` parameter to `sessions_spawn` to allow sub-agents to reuse deterministic sessions instead of always creating a new random-UUID session. Short keys are namespaced to `agent:{agentId}:subagent:{key}`, fully-qualified keys are validated against the target agent to prevent cross-agent session injection, and omitting the parameter preserves the existing random-UUID behavior. - **Blocking: test file will not compile** — the test imports `createOpenClawTools` from `./openclaw-tools.js`, which does not exist. All other subagent spawn tests import `createClawdbotTools` from `./clawdbot-tools.js`. This needs to be corrected for the tests to run. - **Case-sensitivity bug in cross-agent validation** — the embedded agentId extracted from a fully-qualified key is not normalized/lowercased, but `targetAgentId` is always lowercase via `normalizeAgentId()`. This causes false mismatch rejections for mixed-case keys. - **Inconsistent error handling** — the cross-agent mismatch check uses `throw new Error(...)` while the other security checks in the same function use `return jsonResult({ status: "forbidden", ... })`. This may produce different error surfaces depending on caller handling. <h3>Confidence Score: 2/5</h3> - This PR has a blocking test compilation issue and a logic bug in the security validation that need to be fixed before merging. - Score of 2 reflects: (1) the test file imports a non-existent module (`openclaw-tools.js` instead of `clawdbot-tools.js`), meaning tests will fail at compile time and provide no coverage; (2) the cross-agent mismatch validation has a case-sensitivity bug where mixed-case fully-qualified keys are incorrectly rejected; and (3) inconsistent error handling (`throw` vs `jsonResult`) for the security check. The core feature logic in the production code is sound, but the issues prevent confident merging. - Both files need attention: `src/agents/openclaw-tools.subagents.sessions-spawn-reuses-session-key.test.ts` (broken import), `src/agents/tools/sessions-spawn-tool.ts` (case-sensitivity bug and error handling inconsistency) _{Last reviewed commit: 4a4be48} <!-- greptile_other_comments_section --> _{(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!} **Context used:** - Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8)) - Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13)) <!-- /greptile_comment -->