#13303: feat(subagents): replace silent boolean with announce enum ('user'|'parent'|'skip')

Extends #8393 by @Glucksberg. Closes #12730. ## What Replaces the `silent: boolean` parameter with a more flexible `announce` enum on `sessions_spawn`, enabling orchestrator patterns where the parent agent can intercept sub-agent results before they reach the user. **New API:** ```typescript sessions_spawn({ task: "...", announce: "user" | "parent" | "skip" // default: "user" }) ``` **Config:** ```json5 { agents: { defaults: { subagents: { announce: "user" | "parent" | "skip" } } } } ``` ## Modes - **`"user"`** (default) — Current behavior. Announce posts directly to requester chat channel. - **`"skip"`** — Suppresses announce entirely. Cleanup still runs. (Replaces `silent: true` from #8393.) - **`"parent"`** — **New.** Injects the announce result as a system event into the spawning (parent) session. Parent agent wakes up and can review/filter/summarize before relaying to the user. ## Why Sub-agents currently announce directly to the user, bypassing the parent agent entirely. This makes orchestrator patterns impossible — the parent can't review, gate, or consolidate results from multiple sub-agents before surfacing them. The `"parent"` mode enables: - Orchestrator spawns 5 sub-agents → reviews all results → sends one curated summary - Quality gating — parent filters out low-quality or failed sub-agent output - Context building — parent aggregates sub-agent findings before responding ## Changes | File | What | |------|------| | `sessions-spawn-tool.ts` | Added `announce` param to tool schema | | `subagent-announce.ts` | Core `"parent"` mode: system event injection + parent wake | | `subagent-registry.ts` | `announce` field in run records | | `subagent-registry.store.ts` | Persistence for announce mode | | `types.agent-defaults.ts` | Config type | | `zod-schema.agent-defaults.ts` | Zod validation | | `subagents.md` | Docs (new param, mode examples, system event format) | | 3 test files | Tests for all three modes + cleanup behavior | ## Implementation notes **Parent mode flow:** 1. Sub-agent completes → `runSubagentAnnounceFlow` checks `announce` mode 2. `announce: "parent"` → format result as system event (status, summary, session key, stats) 3. Inject into parent session via `enqueueSystemEvent()` 4. Trigger parent wake via non-delivered agent turn 5. Cleanup (label patch, session deletion) runs normally **Design decisions:** - No backward-compat aliases (`silent`, `suppressAnnounce`) since #8393 hasn't merged — no existing users to migrate - Parent wake uses a lightweight agent turn (`deliver: false`) to process the system event promptly - `"parent"` mode sets `didAnnounce = true` after injection, so cleanup semantics match `"user"` mode ## Testing - [x] `pnpm build` ✅ - [x] `pnpm check` (oxlint) — 0 warnings, 0 errors ✅ - [x] Unit tests for all three announce modes ✅ - [x] Cleanup behavior tests ✅ - [ ] Integration test on live gateway (not tested — would appreciate help validating the `"parent"` path end-to-end) ## AI disclosure Built with AI assistance (OpenClaw + GPT-5.3 Codex + Claude Opus). Focused tests written and passing. Full build and lint validated. Co-authored-by: @Glucksberg (base implementation from #8393) <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR replaces the prior boolean-style sub-agent announce control with an explicit `announce` routing mode (`user` | `parent` | `skip`) on `sessions_spawn`, plus a matching `agents.defaults.subagents.announce` config default. Core behavior is implemented in `src/agents/subagent-announce.ts`: `user` preserves existing behavior (requester-facing announce), `skip` suppresses delivery while still allowing cleanup, and `parent` injects a system event into the parent session via `enqueueSystemEvent()` and wakes the parent agent via a non-delivered `agent` call (`deliver: false`). The announce mode is persisted on subagent run records, and tests/docs are updated to cover the new modes and persistence. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk. - I reviewed the changed implementation and surrounding integration points (tool schema wiring, announce flow, persistence load/save, and config schema). The new announce modes are consistently plumbed through `sessions_spawn` -> registry -> announce flow, and tests cover `user`, `parent`, and `skip` behaviors including cleanup semantics. - No files require special attention. <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->