#13990: feat: add subagent_progress tool for sub-agent progress reporting

## Problem Sub-agents run silently for minutes or hours with zero visibility into their progress. The parent agent only learns about the outcome at completion via the announce flow. For long-running tasks (building projects, research, complex deployments), users have no way to know if work is progressing or stuck. ## Solution A new `subagent_progress` tool that sub-agents can call at major milestones to report progress back to the parent session. ### Usage (from sub-agent) ``` subagent_progress({ message: 'Built 6/12 workers', percent: 50 }) ``` ### How it works 1. Sub-agent calls `subagent_progress` with a message and optional percentage 2. Tool validates the caller is a sub-agent session (rejects main/cron sessions) 3. Looks up the parent session via `findSubagentRunByChildKey()` in the subagent registry 4. Injects a progress event into the parent session via `callGateway({ method: 'agent' })` 5. Parent agent decides whether to relay the update to the user ### Changes - **New:** `src/agents/tools/subagent-progress-tool.ts` — The tool implementation - **New:** `src/agents/tools/subagent-progress-tool.test.ts` — 5 unit tests - **Modified:** `src/agents/subagent-registry.ts` — Added `findSubagentRunByChildKey()` helper - **Modified:** `src/agents/openclaw-tools.ts` — Registered the tool in the factory - **Modified:** `src/agents/subagent-announce.ts` — Updated sub-agent system prompt to mention progress reporting ### Testing - 5 new tests: tool creation, parameter schema, rejection of main/cron/empty sessions - All 32 existing agent/session/subagent tests pass (zero regressions) - Live-tested on production OpenClaw instance: spawned a test sub-agent that sent 3 progress updates (0%, 50%, 90%), all received successfully by parent session ### Design decisions - **Not in DEFAULT_SUBAGENT_TOOL_DENY** — available to sub-agents by default - **Self-gating** — tool checks `isSubagentSessionKey()` internally, returns error for non-subagent callers - **Uses existing announce pattern** — injects via `callGateway({ method: 'agent' })` with `deliver: true`, consistent with how completion announces work - **Registry lookup** — uses the subagent registry to find the parent session key, with fallback to session key pattern derivation ### Motivation This was built to solve a real workflow problem: when orchestrating multi-agent tasks (e.g., building a full-stack application via sub-agent), the parent agent had no visibility during execution. The only options were polling via cron or waiting blindly. This tool enables sub-agents to proactively report, making multi-agent orchestration more transparent and reliable. <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR adds a new `subagent_progress` agent tool and wires it into the standard tool factory, plus a small registry helper (`findSubagentRunByChildKey`) and a sub-agent system prompt update encouraging milestone-based progress updates. The tool is designed to be callable only from sub-agent sessions; it looks up the parent session via the sub-agent registry and injects an internal `agent` event into the parent session for the main agent to optionally relay to the user. Main issue spotted is in the tool’s fallback parent-session derivation: it hardcodes `:main`, which can break routing when `session.mainKey` is configured to something else (or when requester sessions aren’t on the default main key). <h3>Confidence Score: 4/5</h3> - Mostly safe to merge after fixing the fallback parent-session key derivation. - The change is localized (new tool + registry helper + prompt update) and follows existing gateway-injection patterns, but the hardcoded `:main` fallback can misroute/drops progress updates in configurations with a non-default session mainKey. - src/agents/tools/subagent-progress-tool.ts <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->