Exclude unavailable native agent tools

Author: chubes4

.github/workflows/README.md

@@ -18,7 +18,7 @@ The target repository grants `contents: write`, `pull-requests: write`, and `iss
 
 Docs Agent consumes the reusable WP Codebox workflow and helper implementation at accepted immutable revision `a6fe2d208e990a8d04104aa74aacbb8d1539fbc1` and passes `wp_codebox_release_ref: v0.12.29` only for released packaged runtime assets. The release tag resolves to immutable revision `bc982947ec33c78160125026e16d357b7ece3ea1`, distinct from both the workflow producer revision and the fixed Docs Agent package revision. WP Codebox materializes the declared native runtime closure, executes the selected package, applies bounded workspace changes, runs verification, and publishes approved host changes. The released assets are `01-wp-codebox.zip` and `02-wp-codebox-workspace-0.12.29.tgz`; the private package-recovery manifest is intentionally not a reviewer asset.
 
-The hosted Agents API component is pinned to `89dd23903489882cfcf14a0d293daf939ad4e1a5`, the minimal immutable revision that makes native `enabled_tools` available to the chat runtime and enforces anchor-independent `require_tool_use` rules. The runtime-capability fixture verifies this selection in both the hosted runtime closure and native importer CI so bootstrap cannot finish after a prose-only zero-tool turn.
+The hosted Agents API component is pinned to `21a8b9b7845e6b89f82bdf34e62f739220184ec7`. It includes the native `enabled_tools` and anchor-independent `require_tool_use` capabilities introduced at `89dd23903489882cfcf14a0d293daf939ad4e1a5`, and omits enabled tool names that have neither an installed ability nor a trusted runtime overlay. The runtime-capability fixture verifies this selection in both the hosted runtime closure and native importer CI so bootstrap cannot finish after a prose-only zero-tool turn or spend its run on unavailable host tools.
 
 Provider artifacts retain only allowlisted review artifacts, controlled workflow envelopes, and canonical runtime-source and seed provenance. WP Codebox v0.12.24 uploads a reviewer-safe workflow-result projection: public control, verification, publication, output-projection, access, failure, artifact-declaration, and canonical transcript-provenance fields remain, while raw `runtime_result`, `outputs.engine_data`, model/provider/tool payloads, source content, private paths, and secrets are excluded. Before persistence or upload, it sanitizes private runtime paths from nested values, object keys, diagnostics, and command arguments. WP Codebox captures one trusted canonical `codebox-transcript` through a pre-sanitization reviewer-evidence descriptor, validates its artifact-root containment, schema, digest, and size, then emits the compact reviewer transcript as a `wp-codebox/reviewer-agent-transcript/v1` projection. Before apply-back, it compares the seed identity with the host workspace identity; rejected patches preserve the expected and actual identities plus patch and changed-file evidence for upload. Its pre-redaction trusted apply input preserves machine-applicable patch bytes in a private channel that is removed before durable artifact sanitization, as fixed in [WP Codebox #1842](https://github.com/Automattic/wp-codebox/pull/1842). The canonical transcript remains the bounded tool-observability surface. Lifecycle and downstream failures retain runtime evidence in their internal normalized failed result even when artifact preparation cannot complete. Diagnostic messages that name runtime classes remain reviewable, while PHP-shaped runtime source remains blocked. See [WP Codebox #1767](https://github.com/Automattic/wp-codebox/issues/1767), [WP Codebox #1814](https://github.com/Automattic/wp-codebox/issues/1814), [WP Codebox #1815](https://github.com/Automattic/wp-codebox/pull/1815), and [WP Codebox #1823](https://github.com/Automattic/wp-codebox/pull/1823). Successful canonical reviewer-evidence reference: [run `29350690551`](https://github.com/Automattic/build-with-wordpress/actions/runs/29350690551). The [hosted failure `29468956857`](https://github.com/Automattic/agents-api/actions/runs/29468956857) executed WP Codebox v0.12.20, published [Agents API #430](https://github.com/Automattic/agents-api/pull/430), then failed during upload preparation; it motivated #1814/#1815 and is not a successful v0.12.24 reviewer-safe workflow-result run.
 

.github/workflows/maintain-docs.yml

@@ -297,7 +297,7 @@ jobs:
             --argjson artifactDeclarations "$artifact_declarations" \
             '{schema:"docs-agent/runner-recipe/v1",targetRepository:$targetRepository,prompt:$prompt,docsAgent:{externalPackageSource:{repository:$repository,revision:$revision,path:$packagePath,digest:$packageDigest},agentSlug:$agentSlug},runner:{contextRepositories:$contextRepositories,bootstrapContract:$bootstrapContract,sourceDelta:$sourceDelta,validationDependencies:$validationDependencies,verificationCommands:$verificationCommands,driftChecks:$driftChecks,writablePaths:$writablePaths,baseRef:$baseRef,docsBranch:$docsBranch,successRequiresPr:$successRequiresPr},artifacts:{expected:($artifactDeclarations|map(.name)),declarations:$artifactDeclarations}}')"
           external_package_source="$(jq -cn --arg repository "Automattic/docs-agent" --arg revision "$DOCS_AGENT_PACKAGE_REVISION" --arg path "$package_path" --arg digest "$package_digest" '{repository:$repository,revision:$revision,path:$path,digest:$digest}')"
-          runtime_sources='[{"version":1,"role":"component","repository":"Automattic/agents-api","revision":"89dd23903489882cfcf14a0d293daf939ad4e1a5","path":".","metadata":{"slug":"agents-api","loadAs":"mu-plugin","pluginFile":"agents-api.php"}},{"version":1,"role":"provider_plugin","source":{"type":"https_zip","url":"https://downloads.wordpress.org/plugin/ai-provider-for-openai.1.0.3.zip","sha256":"48f3c0c714b3164cda79d320829830d5a0ea1116e0b19653da8af898a22d3bb6","archive_root":"ai-provider-for-openai"},"metadata":{"slug":"ai-provider-for-openai","pluginFile":"plugin.php","activate":true,"providers":["openai"]}},{"version":1,"role":"bundled_library","repository":"WordPress/php-ai-client","revision":"631704201d15ffeff7091ad3bc7156db74054956","path":".","metadata":{"library":"php-ai-client","strategy":"wordpress-scoped-bundle"}}]'
+          runtime_sources='[{"version":1,"role":"component","repository":"Automattic/agents-api","revision":"21a8b9b7845e6b89f82bdf34e62f739220184ec7","path":".","metadata":{"slug":"agents-api","loadAs":"mu-plugin","pluginFile":"agents-api.php"}},{"version":1,"role":"provider_plugin","source":{"type":"https_zip","url":"https://downloads.wordpress.org/plugin/ai-provider-for-openai.1.0.3.zip","sha256":"48f3c0c714b3164cda79d320829830d5a0ea1116e0b19653da8af898a22d3bb6","archive_root":"ai-provider-for-openai"},"metadata":{"slug":"ai-provider-for-openai","pluginFile":"plugin.php","activate":true,"providers":["openai"]}},{"version":1,"role":"bundled_library","repository":"WordPress/php-ai-client","revision":"631704201d15ffeff7091ad3bc7156db74054956","path":".","metadata":{"library":"php-ai-client","strategy":"wordpress-scoped-bundle"}}]'
 
           runner_workspace="$(jq -cn \
             --arg repo "$GITHUB_REPOSITORY_NAME" \

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           repository: Automattic/agents-api
-          ref: 89dd23903489882cfcf14a0d293daf939ad4e1a5
+          ref: 21a8b9b7845e6b89f82bdf34e62f739220184ec7
           path: agents-api
           token: ${{ github.token }}
           persist-credentials: false

README.md

@@ -279,4 +279,4 @@ AGENTS_API_DIR=/path/to/agents-api php tests/native-agent-import.php
 
 It imports every native package through `wp_agent_import_runtime_bundles()`, verifies registration and no-change-capable tool rules, and invokes the default native chat handler far enough to resolve each registered agent. It intentionally fails when `AGENTS_API_DIR` is unavailable rather than treating an unexecuted importer as a passing test. It does not execute a model turn because the packages intentionally leave provider/model selection to the caller.
 
-The `Docs Agent Tests` GitHub Actions workflow runs on pull requests and pushes. It fetches Docs Agent history so it can run the immutable native package source validator, then runs the structural package validator, explicit Agents API runtime-capability contract, docs-link repair smoke test, and native importer integration test against `Automattic/agents-api` at `89dd23903489882cfcf14a0d293daf939ad4e1a5`, the minimal immutable revision from [Agents API #384](https://github.com/Automattic/agents-api/pull/384) that resolves native `enabled_tools` and enforces anchor-independent `require_tool_use` completion gates.
+The `Docs Agent Tests` GitHub Actions workflow runs on pull requests and pushes. It fetches Docs Agent history so it can run the immutable native package source validator, then runs the structural package validator, explicit Agents API runtime-capability contract, docs-link repair smoke test, and native importer integration test against `Automattic/agents-api` at `21a8b9b7845e6b89f82bdf34e62f739220184ec7`. That revision includes the native `enabled_tools` and anchor-independent `require_tool_use` capabilities introduced by [Agents API #384](https://github.com/Automattic/agents-api/pull/384), and omits enabled tool names that have neither an installed ability nor a trusted runtime overlay.

tests/agents-api-runtime-capability.fixture.json

@@ -1,10 +1,11 @@
 {
   "schema": "docs-agent/agents-api-runtime-capability/v1",
   "repository": "Automattic/agents-api",
-  "revision": "89dd23903489882cfcf14a0d293daf939ad4e1a5",
+  "revision": "21a8b9b7845e6b89f82bdf34e62f739220184ec7",
   "capability_commit": "89dd23903489882cfcf14a0d293daf939ad4e1a5",
   "capabilities": [
     "native agent_config.enabled_tools are resolved into tool declarations",
-    "require_tool_use completion rules block a zero-tool first turn without an anchor"
+    "require_tool_use completion rules block a zero-tool first turn without an anchor",
+    "enabled tool names without an installed ability or trusted runtime overlay are omitted"
   ]
 }

tests/validate-agents-api-runtime-contract.php

@@ -19,8 +19,9 @@
 $assert( 'docs-agent/agents-api-runtime-capability/v1' === ( $fixture['schema'] ?? null ), 'Agents API runtime capability fixture schema mismatch.' );
 $revision = $fixture['revision'] ?? null;
 $assert( is_string( $revision ) && preg_match( '/^[0-9a-f]{40}$/', $revision ) === 1, 'Agents API runtime capability fixture must declare an immutable revision.' );
-$assert( $revision === ( $fixture['capability_commit'] ?? null ), 'Docs Agent must pin the minimal immutable revision that introduced the required native tool capability.' );
-$assert( is_array( $fixture['capabilities'] ?? null ) && 2 === count( $fixture['capabilities'] ), 'Agents API runtime capability fixture must identify both required native tool capabilities.' );
+$capability_commit = $fixture['capability_commit'] ?? null;
+$assert( is_string( $capability_commit ) && preg_match( '/^[0-9a-f]{40}$/', $capability_commit ) === 1, 'Agents API runtime capability fixture must retain the immutable capability introduction commit.' );
+$assert( is_array( $fixture['capabilities'] ?? null ) && 3 === count( $fixture['capabilities'] ), 'Agents API runtime capability fixture must identify every required native tool capability.' );
 
 $runtime_source = array(
 	'version'    => 1,
@@ -43,6 +44,8 @@
 if ( is_string( $agents_api_dir ) && is_dir( $agents_api_dir ) ) {
 	$checked_out_revision = trim( (string) shell_exec( 'git -C ' . escapeshellarg( $agents_api_dir ) . ' rev-parse HEAD' ) );
 	$assert( $revision === $checked_out_revision, 'The checked-out Agents API runtime must match the immutable capability revision.' );
+	exec( 'git -C ' . escapeshellarg( $agents_api_dir ) . ' merge-base --is-ancestor ' . escapeshellarg( $capability_commit ) . ' HEAD', $output, $status );
+	$assert( 0 === $status, 'The checked-out Agents API runtime must retain the original native tool capabilities.' );
 }
 
 fwrite( STDOUT, "Agents API runtime capability contract passed.\n" );