docs(subagents): document announce timeout

[akrimm702]

Summary

• document agents.defaults.subagents.announceTimeoutMs in the sub-agent config reference
• include the option in the nested sub-agent example next to related timeout/concurrency settings
• clarify that the value is the per-call gateway agent announce timeout; transient retries can make total announce wait longer than one configured timeout

Why

Follow-up to #47558. Rechecked against current main (b0db82be15291f5ca66f434ff46f2884c4b3e133): announceTimeoutMs still exists in schema/runtime and is still not documented in docs/tools/subagents.md.

This remains intentionally tiny instead of rebasing the old broad docs branch.

Real behavior proof

• Behavior addressed: the public sub-agent docs omitted the live agents.defaults.subagents.announceTimeoutMs config key, and the old wording treated the timeout like a whole announce-step bound instead of a per-call gateway agent timeout.
• Real environment tested: local OpenClaw checkout on macOS, comparing PR docs(subagents): document announce timeout #75509 against live openclaw/openclaw main and the GitHub PR API after the branch update.
• Exact steps or command run after this patch: git fetch origin main; git diff --check origin/main...akrimm/docs/subagents-announce-timeout; git merge-tree --write-tree origin/main akrimm/docs/subagents-announce-timeout; git diff --stat origin/main...akrimm/docs/subagents-announce-timeout; git grep -n 'announceTimeoutMs' origin/main akrimm/docs/subagents-announce-timeout -- docs/tools/subagents.md src config docs.
• Evidence after fix: terminal output from maintainer fixup on PR head 6956bdfabc: git diff --check origin/main...HEAD exited 0; pnpm exec oxfmt --check --threads=1 docs/tools/subagents.md docs/gateway/config-tools.md src/config/types.agent-defaults.ts CHANGELOG.md printed All matched files use the correct format; pnpm docs:list listed the docs index successfully, including tools/subagents.md and gateway/config-tools.md. Source proof: src/agents/subagent-announce-delivery.ts defaults to 120_000, and src/config/zod-schema.agent-defaults.ts accepts positive integer announceTimeoutMs.
• Observed result after fix: the PR remains open, non-draft, conflict-free, and still relevant because the runtime/schema key exists on current main but the docs page still lacks it.
• What was not tested: rendered docs deployment was not tested; this is a docs-only correction with no runtime code path change.

Validation

• git diff --check origin/main...akrimm/docs/subagents-announce-timeout
• git merge-tree --write-tree origin/main akrimm/docs/subagents-announce-timeout
• corepack pnpm exec oxfmt --check --threads=1 docs/tools/subagents.md (prior branch validation)
• corepack pnpm dlx --config.resolution-mode=highest markdownlint-cli2 --config /tmp/openclaw-pr75509-markdownlint-cli2.jsonc docs/tools/subagents.md (prior branch validation)

[clawsweeper]

Codex review: needs maintainer review before merge.

Summary
The PR documents agents.defaults.subagents.announceTimeoutMs in sub-agent and config reference docs, updates the nested example, corrects the type comment default, and adds a changelog entry.

Reproducibility: not applicable. as a runtime bug. This is a source-verifiable docs gap: current main has the schema/runtime/test contract for announceTimeoutMs, while the relevant docs pages omit it.

Real behavior proof
Sufficient (live_output): The PR body includes after-fix terminal/live-output style validation and source comparison for this docs-only correction, which is sufficient real behavior proof for the changed surface.

Next step before merge
No automated repair lane is needed; the PR already contains the focused fix and needs ordinary maintainer review/checks/merge handling.

Security
Cleared: The diff is documentation, changelog, and a type-comment correction only; it does not alter execution paths, dependencies, workflows, permissions, package metadata, or secret handling.

Review details

Best possible solution:

Land the narrow docs-only correction after ordinary maintainer review and checks so the published sub-agent docs match the existing schema, runtime default, and retry behavior.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a runtime bug. This is a source-verifiable docs gap: current main has the schema/runtime/test contract for announceTimeoutMs, while the relevant docs pages omit it.

Is this the best way to solve the issue?

Yes. Updating the existing reference docs and stale type comment is the narrowest maintainable fix because the config option already exists and the PR wording matches the per-call timeout plus retry behavior.

What I checked:

• Current docs gap: Current main documents nearby sub-agent defaults (allowAgents, requireAgentId, runTimeoutSeconds) but does not document agents.defaults.subagents.announceTimeoutMs in the sub-agent guide or nested example. Public docs: docs/tools/subagents.md. (docs/tools/subagents.md:343, 260be33c3ea7)
• Current config reference gap: Current main's tools config reference example and bullet list include runTimeoutSeconds and archiveAfterMinutes but omit announceTimeoutMs. Public docs: docs/gateway/config-tools.md. (docs/gateway/config-tools.md:390, 260be33c3ea7)
• Schema/runtime contract: The config schema accepts announceTimeoutMs as a positive integer, runtime defaults it to 120_000, clamps configured values, and passes the resolved timeout to gateway agent announce calls. (src/agents/subagent-announce-delivery.ts:59, 260be33c3ea7)
• Test coverage supports wording: Current tests assert the 120s default, configured timeout propagation, and retry behavior after gateway timeout, which supports the PR wording that total wait can exceed one configured timeout. (src/agents/subagent-announce.timeout.test.ts:285, 260be33c3ea7)
• PR diff matches the contract: The PR head 6956bdfabcb1616615d518217c1a5b657a2f00b9 adds the missing docs entries, uses the 120000 default, describes the per-call gateway agent timeout, updates the stale type comment, and does not change runtime behavior. Public docs: docs/tools/subagents.md. (docs/tools/subagents.md:343, 6956bdfabcb1)
• Related report context: The linked broader docs report docs(subagents): 6 gaps/inaccuracies in sub-agents documentation #47558 identified the missing announceTimeoutMs documentation; this PR isolates that remaining docs correction after the broader report was closed.

Likely related people:

• steipete: Peter Steinberger authored/restored the configurable announce-timeout behavior and authored the latest PR-head fixup commit that aligns this docs change with the 120000ms runtime default. (role: recent area contributor and likely follow-up owner; confidence: high; commits: 320cf8eb3e34, b0d9d1d2dae8, 6956bdfabcb1; files: src/agents/subagent-announce-delivery.ts, src/agents/subagent-announce.timeout.test.ts, docs/tools/subagents.md)
• tyler6204: Tyler Yust appears in multiple merged sub-agent announce delivery/routing fixes, so he is a useful secondary routing candidate if runtime wording needs owner review. (role: adjacent sub-agent announce contributor; confidence: medium; commits: 41cf93efff4d, fe57bea088c7, 8d2f98fb01a6; files: src/agents/subagent-announce-delivery.ts, src/agents/subagent-announce.timeout.test.ts)

Remaining risk / open question:

• Rendered Mintlify output was not exercised in this read-only pass; the PR body reports formatter and docs-list validation after the latest head fixup.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 260be33c3ea7.

[akrimm702]

Update after re-review against current main:

• Still relevant: announceTimeoutMs is still present in schema/runtime and still absent from docs/tools/subagents.md on current main (08acf80891acc45c40e3fa5f6288b4a91b1ef37c).
• Addressed the previous review finding by documenting the value as the per-call gateway agent announce timeout and noting that transient retries can make total announce wait longer than one configured timeout.
• Kept the PR minimal: GitHub diff is still one docs file, +4/-0.

Validation:

• git diff --check origin/main...akrimm/docs/subagents-announce-timeout
• git merge-tree --write-tree origin/main akrimm/docs/subagents-announce-timeout
• corepack pnpm exec oxfmt --check --threads=1 docs/tools/subagents.md
• markdownlint-cli2 with the current repo config

Result: no reason to close this PR; it is still a small relevant docs fix. GitHub currently reports it as mergeable with pending/unstable checks.

[steipete]

Landing proof for PR #75509.

Local verification on rebased PR head 6956bdfabc:

• git diff --check
• pnpm exec oxfmt --check --threads=1 docs/tools/subagents.md docs/gateway/config-tools.md src/config/types.agent-defaults.ts CHANGELOG.md
• pnpm docs:list

GitHub verification:

• Real behavior proof: run 25688942025, success
• Workflow Sanity: run 25688903535, success (actionlint, no-tabs)
• CI: run 25688903567 has preflight, security-fast, security-scm-fast, security-dependency-audit, check-docs, and selected node/docs shards passing; broad unrelated shards remain queued after repeated polls.

Known proof gap: CI, CodeQL, CodeQL Critical Quality, and OpenGrep — PR Diff workflow runs are still queued at GitHub level. This PR is a narrow docs/config-reference correction plus a stale type-comment fix; no runtime code path changed.

Thanks @akrimm702.

[steipete]

Landed via squash after temp rebase onto main.

• Local gate: git diff --check; pnpm exec oxfmt --check --threads=1 docs/tools/subagents.md docs/gateway/config-tools.md src/config/types.agent-defaults.ts CHANGELOG.md; pnpm docs:list
• GitHub proof: Real behavior proof run 25688942025 passed; Workflow Sanity run 25688903535 passed; CI run 25688903567 had check-docs, security fast checks, and selected node/docs shards passing before merge, with broad unrelated shards still queued.
• Fixup commit on PR branch: 6956bdf
• Landed commit: 578fad4

Thanks @akrimm702.