Pin Docs Agent native tool runtime capability

[chubes4]

Summary

• Pin hosted Docs Agent and native-import CI to Agents API 21a8b9b7845e6b89f82bdf34e62f739220184ec7.
• Preserve the native enabled_tools and anchor-independent require_tool_use baseline introduced at 89dd23903489882cfcf14a0d293daf939ad4e1a5.
• Exclude enabled tool names that have neither an installed WordPress ability nor a trusted runtime overlay.
• Add and forward a reusable max_turns input with a documentation-sized default of 32.
• Extend fixture-backed runtime capability coverage across the hosted recipe and native-import CI.

Hosted evidence

• Run 29779314074 loaded the corrected Docs Agent package but used pre-capability Agents API 78e2dd409010f98fa4d26cdd72572117384ab18d; no required docs/README.md was created.
• Run 29780248705 used Agents API 89dd23903489882cfcf14a0d293daf939ad4e1a5 with 12 turns; no required docs/README.md was created.
• Run 29781937609 used 32 turns; no required docs/README.md was created, disproving the turn ceiling as the sole root cause.
• Run 29782835627 used Agents API 21a8b9b7845e6b89f82bdf34e62f739220184ec7, omitted unavailable host tools, and still produced no accepted docs/README.md.

The strict BOOTSTRAP_REQUIRED_PATH completion contract remains unchanged. Issue #177 remains open pending a successful hosted empty-surface bootstrap.

Compatibility

• Adds the optional max_turns reusable-workflow input with a default of 32.
• Agents API no longer exposes configured tool names to the model when no installed ability or trusted runtime overlay can execute them. Consumers that relied on advertising unavailable tools will observe a smaller tool surface; executable abilities and trusted runtime overlays are unchanged.
• No package schema, runtime-source role, writable-path policy, or completion criterion changes.

How To Test

1. Clone this branch and run php tests/validate-docs-agent-packages.php.
2. Check out Agents API at 21a8b9b7845e6b89f82bdf34e62f739220184ec7, then run AGENTS_API_DIR=/path/to/agents-api php tests/validate-agents-api-runtime-contract.php and AGENTS_API_DIR=/path/to/agents-api php tests/native-agent-import.php.
3. Check out WP Codebox at a6fe2d208e990a8d04104aa74aacbb8d1539fbc1, then run WP_CODEBOX_DIR=/path/to/wp-codebox php tests/validate-wp-codebox-run-agent-task-contract.php.
4. Run php tests/validate-docs-agent-completion-contract.php, php tests/validate-external-native-package-sources.php, php tests/repair-docs-links-smoke.php, actionlint .github/workflows/*.yml, and git diff --check.
5. In Agents API, run composer test and composer phpstan.

AI assistance

• AI assistance: Yes
• Tool(s): OpenAI GPT-5.6 Sol via OpenCode
• Used for: Traced hosted package execution, implemented runtime capability and turn-budget contracts, fixed unavailable native tool exposure in Agents API, and ran deterministic and hosted verification with Chris.