Overlay trusted runtime tool declarations (#425)

* Overlay trusted runtime tool declarations

* Harden runtime tool overlay boundary

Author: chubes4

docs/runtime-and-tools.md

@@ -214,6 +214,65 @@ Important options:
 
 When mediated tool execution consults `completion_policy`, complete decisions stop the loop and record `completion_policy_stop` in `events[]`. Incomplete decisions with an empty message preserve the existing continue behavior. Incomplete decisions with a non-empty message append a normalized `user` text continuation message, record a `completion_policy_continue` lifecycle event in `events[]`, and emit the same event through `on_event`; the event metadata includes `tool_name`, `turn`, `message`, and caller-owned policy `context`. Agents API does not persist these diagnostics beyond the returned transcript/result surfaces.
 
+### Trusted chat runtime tool overlays
+
+The native `agents/chat` handler accepts runtime-local overlays only through the
+server-side `agents_api_runtime_tool_declarations` filter. Public REST,
+JSON-RPC, and chat request `client_context` fields cannot declare or select
+runtime tools; those transport fields are stripped before dispatch.
+
+Each map key and declaration `name` must be the same canonical id already listed
+in the imported agent's `enabled_tools` allowlist. The declaration is normalized
+by `WP_Agent_Tool_Declaration::normalizeForConversationRequest()`. It can replace
+only the model-facing `description`, `parameters`, and runtime execution metadata
+for that allowlisted tool, including `runtime.executor_target`. It cannot change
+the imported declaration's ability binding, capability, mandatory flag, modes,
+categories, visibility, parameter bindings, defaults, or policy behavior.
+
+The filter runs after agent selection and final session/run context resolution.
+Its exact signature is:
+
+```php
+apply_filters(
+	'agents_api_runtime_tool_declarations',
+	array $declarations,
+	?WP_Agent $agent,
+	array $runtime_context // agent, agent_slug, session_id, run_id
+): array
+```
+
+An explicit `runtime.executor_target` must be registered through
+`agents_api_tool_executors` in that exact `$runtime_context`. The selected
+registry is frozen for execution; an unavailable target fails closed and never
+falls back to the default ability executor. Duplicate canonical ids, aliases,
+malformed entries, undeclared tools, and unregistered targets reject the chat request with
+`agents_chat_invalid_runtime_tool_declaration`.
+
+```php
+add_filter(
+	'agents_api_runtime_tool_declarations',
+	static function ( array $declarations, ?WP_Agent $agent, array $runtime_context ): array {
+		if ( ! $agent instanceof WP_Agent || 'example-agent' !== $runtime_context['agent_slug'] ) {
+			return $declarations;
+		}
+
+		$declarations['example/write_file'] = array(
+			'name'        => 'example/write_file',
+			'source'      => 'example',
+			'description' => 'Write a file in the isolated runtime.',
+			'parameters'  => array( 'type' => 'object', 'properties' => array( 'path' => array( 'type' => 'string' ) ) ),
+			'executor'    => 'host',
+			'scope'       => 'run',
+			'runtime'     => array( 'executor_target' => 'example/isolated-runtime' ),
+		);
+
+		return $declarations;
+	},
+	10,
+	3
+);
+```
+
 ### Minimal caller-managed loop
 
 ```php

src/Channels/register-agents-chat-ability.php

@@ -435,35 +435,33 @@ function agents_chat_input_schema(): array {
 						'type'        => 'boolean',
 						'description' => 'Whether this turn is an explicit agent-to-agent delegation call.',
 					),
-					'runtime_tools'             => array(
-						'type'                 => 'object',
-						'description'          => 'Explicit runtime-local tool declarations supplied by a trusted caller for this turn.',
-						'additionalProperties' => array( 'type' => 'object' ),
-					),
-					'runtime_tool_declarations' => array(
-						'type'                 => 'object',
-						'description'          => 'Alias for explicit runtime-local tool declarations supplied by a trusted caller for this turn.',
-						'additionalProperties' => array( 'type' => 'object' ),
-					),
-					'tool_declarations'         => array(
-						'type'                 => 'object',
-						'description'          => 'Transport-level tool declarations supplied by a trusted caller for this turn.',
-						'additionalProperties' => array( 'type' => 'object' ),
-					),
-					'runtime_tool_callback'     => array(
-						'type'        => 'string',
-						'description' => 'Runtime-local callback identifier for executing runtime tool calls in trusted in-process callers.',
-					),
-					'runtime_tool_timeout'      => array(
-						'type'        => 'integer',
-						'description' => 'Runtime-local tool timeout in seconds.',
-					),
 				),
 			),
 		),
 	);
 }
 
+/**
+ * Remove transport-controlled runtime declaration fields from client context.
+ *
+ * Runtime declaration overlays are server-only and arrive through
+ * `agents_api_runtime_tool_declarations`, never a public request envelope.
+ *
+ * @param array<string,mixed> $client_context Client context from a transport.
+ * @return array<string,mixed> Client context without runtime declaration fields.
+ */
+function agents_chat_strip_runtime_tool_declaration_fields( array $client_context ): array {
+	unset(
+		$client_context['runtime_tools'],
+		$client_context['runtime_tool_declarations'],
+		$client_context['tool_declarations'],
+		$client_context['runtime_tool_callback'],
+		$client_context['runtime_tool_timeout']
+	);
+
+	return $client_context;
+}
+
 /**
  * Canonical execution principal schema for agents/chat.
  *

src/Channels/register-agents-chat-jsonrpc-route.php

@@ -319,7 +319,7 @@ function agents_chat_jsonrpc_input_from_params( array $params, string $agent, ar
 	$session_id = \AgentsAPI\AI\agents_api_scalar_to_string( $params['sessionId'] ?? null );
 	$run_id     = \AgentsAPI\AI\agents_api_scalar_to_string( $params['id'] ?? null );
 
-	$client_context = agents_chat_jsonrpc_client_context( $message );
+	$client_context = agents_chat_strip_runtime_tool_declaration_fields( agents_chat_jsonrpc_client_context( $message ) );
 	$client_context = array_merge(
 		$client_context,
 		array(
@@ -354,7 +354,16 @@ function agents_chat_jsonrpc_input_from_params( array $params, string $agent, ar
 	/** @var mixed $filtered Hosts may return invalid values from this filter. */
 	$filtered = apply_filters( 'agents_chat_jsonrpc_input', $input, $params, $agent );
 
-	return is_array( $filtered ) ? \AgentsAPI\AI\agents_api_string_keyed_array( $filtered ) : $input;
+	if ( ! is_array( $filtered ) ) {
+		return $input;
+	}
+
+	$input = \AgentsAPI\AI\agents_api_string_keyed_array( $filtered );
+	if ( is_array( $input['client_context'] ?? null ) ) {
+		$input['client_context'] = agents_chat_strip_runtime_tool_declaration_fields( \AgentsAPI\AI\agents_api_string_keyed_array( $input['client_context'] ) );
+	}
+
+	return $input;
 }
 
 /**

src/Channels/register-default-agents-chat-handler.php

@@ -41,6 +41,7 @@
 use AgentsAPI\AI\WP_Agent_Message;
 use AgentsAPI\AI\Tools\WP_Agent_Ability_Tool_Executor;
 use AgentsAPI\AI\Tools\WP_Agent_Tool_Declaration;
+use AgentsAPI\AI\Tools\WP_Agent_Tool_Executor_Registry;
 use AgentsAPI\Core\Database\Chat\WP_Agent_Conversation_Sessions;
 use AgentsAPI\Core\Database\Chat\WP_Agent_Conversation_Store;
 use AgentsAPI\Core\Workspace\WP_Agent_Workspace_Scope;
@@ -125,10 +126,9 @@ public static function execute( array $input ) {
 			);
 		}
 
-		$system_prompt     = self::resolve_system_prompt( $config );
-		$tool_declarations = self::resolve_tool_declarations( $config );
-		$max_turns         = self::resolve_max_turns( $input, $config );
-		$tool_call_rules   = self::resolve_tool_call_rules( $config );
+		$system_prompt   = self::resolve_system_prompt( $config );
+		$max_turns       = self::resolve_max_turns( $input, $config );
+		$tool_call_rules = self::resolve_tool_call_rules( $config );
 
 		$store      = WP_Agent_Conversation_Sessions::get_store( $input );
 		$session_id = is_string( $input['session_id'] ?? null ) ? trim( $input['session_id'] ) : '';
@@ -150,15 +150,39 @@ public static function execute( array $input ) {
 			$session_id = self::generate_session_id();
 		}
 
+		$runtime_context = array(
+			'agent'      => $agent,
+			'agent_slug' => $agent_slug,
+			'session_id' => $session_id,
+			'run_id'     => is_string( $input['run_id'] ?? null ) ? trim( $input['run_id'] ) : '',
+		);
+		$executor_registry = WP_Agent_Tool_Executor_Registry::fromFilters( $runtime_context );
+		$tool_declarations = self::resolve_tool_declarations( $config, self::runtime_tool_declarations( $agent, $runtime_context ), $executor_registry );
+		if ( is_wp_error( $tool_declarations ) ) {
+			return $tool_declarations;
+		}
+		$tool_declarations = ( new \WP_Agent_Tool_Policy() )->resolve(
+			$tool_declarations,
+			array(
+				'agent_config' => $config,
+				'allow_only'   => is_array( $input['allow_only'] ?? null ) ? $input['allow_only'] : array(),
+				'tool_policy'  => is_array( $input['tool_policy'] ?? null ) ? $input['tool_policy'] : array(),
+				'principal'    => $input['principal'] ?? null,
+			)
+		);
+
 		$messages[] = WP_Agent_Message::text( 'user', $message );
 		$messages   = WP_Agent_Message::normalize_many( $messages );
 
 		$loop_options = array(
 			'system_prompt' => $system_prompt,
 			'max_turns'     => $max_turns,
 			'context'       => array(
-				'session_id' => $session_id,
-				'agent_slug' => $agent_slug,
+				'session_id'             => $session_id,
+				'agent_slug'             => $agent_slug,
+				'run_id'                 => $runtime_context['run_id'],
+				'principal'              => $input['principal'] ?? null,
+				'tool_executor_registry' => $executor_registry,
 			),
 		);
 		if ( ! empty( $tool_declarations ) ) {
@@ -268,14 +292,24 @@ private static function resolve_system_prompt( array $config ): string {
 	 * model-facing name is the ability name; {@see WP_Agent_Ability_Tool_Executor}
 	 * dispatches it back through the Abilities API.
 	 *
+	 * Runtime overlays come only from the server-side
+	 * `agents_api_runtime_tool_declarations` filter after the agent, generated
+	 * session id, and run id are resolved. Each entry must name an existing
+	 * canonical enabled tool. Overlays can replace only model-facing description,
+	 * parameters, and runtime execution metadata.
+	 *
 	 * @param array<string,mixed> $config Agent default config.
-	 * @return array<string,array<string,mixed>> Declarations keyed by tool name.
+	 * @param array<mixed>        $overlays Server-provided declaration overlays.
+	 * @param WP_Agent_Tool_Executor_Registry $executor_registry Frozen registry for this run.
+	 * @return array<string,array<mixed>>|\WP_Error Declarations, or an invalid overlay error.
 	 */
-	private static function resolve_tool_declarations( array $config ): array {
-		$names = array();
-		foreach ( array( 'enabled_tools', 'tools', 'abilities', 'tool_names' ) as $key ) {
-			if ( is_array( $config[ $key ] ?? null ) ) {
-				$names = array_merge( $names, $config[ $key ] );
+	private static function resolve_tool_declarations( array $config, array $overlays = array(), ?WP_Agent_Tool_Executor_Registry $executor_registry = null ) {
+		$names = is_array( $config['enabled_tools'] ?? null ) ? $config['enabled_tools'] : array();
+		if ( empty( $names ) ) {
+			foreach ( array( 'tools', 'abilities', 'tool_names' ) as $key ) {
+				if ( is_array( $config[ $key ] ?? null ) ) {
+					$names = array_merge( $names, $config[ $key ] );
+				}
 			}
 		}
 
@@ -313,9 +347,79 @@ private static function resolve_tool_declarations( array $config ): array {
 			);
 		}
 
+		if ( array() === $overlays ) {
+			return $declarations;
+		}
+		$executor_registry = $executor_registry ?? new WP_Agent_Tool_Executor_Registry();
+		$seen_names        = array();
+		$seen_aliases      = array();
+		foreach ( $overlays as $map_name => $overlay ) {
+			if ( ! is_string( $map_name ) || ! is_array( $overlay ) ) {
+				return self::runtime_tool_declaration_error( 'declaration' );
+			}
+
+			try {
+				$normalized = WP_Agent_Tool_Declaration::normalizeForConversationRequest( $overlay );
+			} catch ( \InvalidArgumentException $error ) {
+				return self::runtime_tool_declaration_error( $error->getMessage() );
+			}
+
+			$name = $normalized['name'] ?? '';
+			if ( ! is_string( $name ) || $map_name !== $name || ! isset( $declarations[ $name ] ) || isset( $seen_names[ $name ] ) ) {
+				return self::runtime_tool_declaration_error( 'name' );
+			}
+			$seen_names[ $name ] = true;
+
+			$alias = $normalized['provider_safe_name'] ?? WP_Agent_Tool_Declaration::providerSafeName( $name );
+			if ( ! is_string( $alias ) || isset( $seen_aliases[ $alias ] ) ) {
+				return self::runtime_tool_declaration_error( 'provider_safe_name' );
+			}
+			$seen_aliases[ $alias ] = true;
+
+			$target_id      = WP_Agent_Tool_Executor_Registry::targetIdFromDeclaration( $normalized );
+			$runtime        = is_array( $normalized['runtime'] ?? null ) ? $normalized['runtime'] : array();
+			$declares_target = array_key_exists( WP_Agent_Tool_Executor_Registry::RUNTIME_EXECUTOR_TARGET, $runtime );
+			if ( $declares_target && ( '' === $target_id || null === $executor_registry->executorForTarget( $target_id ) ) ) {
+				return self::runtime_tool_declaration_error( 'executor_target' );
+			}
+
+			// Imported declaration policy, bindings, and ability identity remain immutable.
+			foreach ( array( 'description', 'parameters', 'runtime' ) as $field ) {
+				if ( array_key_exists( $field, $normalized ) ) {
+					$declarations[ $name ][ $field ] = $normalized[ $field ];
+				}
+			}
+		}
+
 		return $declarations;
 	}
 
+	/**
+	 * Collect server-only runtime tool declaration overlays for this run.
+	 *
+	 * @param \WP_Agent|null     $agent           Selected agent, or null for agent-less turns.
+	 * @param array<string,mixed> $runtime_context Final server-generated run context.
+	 * @return array<mixed> Declaration overlay map supplied by server code.
+	 */
+	private static function runtime_tool_declarations( ?\WP_Agent $agent, array $runtime_context ): array {
+		$overlays = apply_filters( 'agents_api_runtime_tool_declarations', array(), $agent, $runtime_context );
+		return is_array( $overlays ) ? $overlays : array( '__invalid__' => $overlays );
+	}
+
+	/**
+	 * Build the public error returned for a rejected trusted-runtime overlay.
+	 *
+	 * @param string $reason Machine-readable validation reason.
+	 * @return \WP_Error
+	 */
+	private static function runtime_tool_declaration_error( string $reason ): \WP_Error {
+		return new \WP_Error(
+			'agents_chat_invalid_runtime_tool_declaration',
+			'Runtime tool declarations must be a canonical, allowlisted map supplied by the server runtime.',
+			array( 'status' => 400, 'reason' => $reason )
+		);
+	}
+
 	/**
 	 * Resolve declarative deterministic tool-call rules from the agent config.
 	 *

src/Channels/register-frontend-chat-rest-route.php

@@ -121,6 +121,7 @@ function agents_frontend_chat_rest_input( \WP_REST_Request $request ) {
 
 	$client_context = $request->get_param( 'client_context' );
 	$client_context = is_array( $client_context ) ? \AgentsAPI\AI\agents_api_string_keyed_array( $client_context ) : array();
+	$client_context = agents_chat_strip_runtime_tool_declaration_fields( $client_context );
 	$session_id     = $request->get_param( 'session_id' );
 	$client_name    = \AgentsAPI\AI\agents_api_scalar_to_string( $client_context['client_name'] ?? null );
 	$client_context = array_merge(
@@ -158,6 +159,9 @@ function agents_frontend_chat_rest_input( \WP_REST_Request $request ) {
 		return $cache[ $request ];
 	}
 	$input = \AgentsAPI\AI\agents_api_string_keyed_array( $filtered_input );
+	if ( is_array( $input['client_context'] ?? null ) ) {
+		$input['client_context'] = agents_chat_strip_runtime_tool_declaration_fields( \AgentsAPI\AI\agents_api_string_keyed_array( $input['client_context'] ) );
+	}
 
 	if ( '' === \AgentsAPI\AI\agents_api_scalar_to_string( $input['agent'] ?? null ) || '' === trim( \AgentsAPI\AI\agents_api_scalar_to_string( $input['message'] ?? null ) ) ) {
 		$cache[ $request ] = new \WP_Error(
@@ -182,6 +186,7 @@ function agents_frontend_chat_rest_input( \WP_REST_Request $request ) {
 function agents_frontend_chat_rest_scope( \WP_REST_Request $request ): array {
 	$client_context            = $request->get_param( 'client_context' );
 	$client_context            = is_array( $client_context ) ? \AgentsAPI\AI\agents_api_string_keyed_array( $client_context ) : array();
+	$client_context            = agents_chat_strip_runtime_tool_declaration_fields( $client_context );
 	$scope                     = \AgentsAPI\AI\Auth\agents_access_request_scope(
 		array(
 			'workspace_id' => $request->get_param( 'workspace_id' ),

src/Tools/class-wp-agent-tool-execution-core.php

@@ -105,6 +105,10 @@ public function prepareWP_Agent_Tool_Call( string $tool_name, array $tool_parame
 	public function executePreparedTool( array $tool_call, array $tool_definition, WP_Agent_Tool_Executor $executor, array $context = array() ): array {
 		$tool_call = WP_Agent_Tool_Call::normalize( $tool_call );
 		$executor  = $this->resolveExecutorForTool( $tool_definition, $executor, $context );
+		if ( null === $executor ) {
+			$tool_name = is_string( $tool_call['tool_name'] ?? null ) ? $tool_call['tool_name'] : '';
+			return WP_Agent_Tool_Result::error( $tool_name, 'Tool execution target is unavailable.', array( 'error_type' => 'executor_target_unavailable' ) );
+		}
 		try {
 			$result = $executor->executeWP_Agent_Tool_Call( $tool_call, $tool_definition, $context );
 		} catch ( \Throwable $throwable ) {
@@ -177,19 +181,22 @@ public function executeTool( string $tool_name, array $tool_parameters, array $a
 	 * @param array<mixed>           $tool_definition  Tool declaration selected for the call.
 	 * @param WP_Agent_Tool_Executor $default_executor Caller-provided default executor.
 	 * @param array<mixed>           $context          Host runtime context for this invocation.
-	 * @return WP_Agent_Tool_Executor Executor to dispatch the tool call to.
+	 * @return WP_Agent_Tool_Executor|null Executor to dispatch the tool call, or null when a declared target is unavailable.
 	 */
-	private function resolveExecutorForTool( array $tool_definition, WP_Agent_Tool_Executor $default_executor, array $context ): WP_Agent_Tool_Executor {
+	private function resolveExecutorForTool( array $tool_definition, WP_Agent_Tool_Executor $default_executor, array $context ): ?WP_Agent_Tool_Executor {
 		// Skip registry resolution entirely when the tool names no target, so the
 		// common ability-backed path never builds or consults a registry.
 		if ( '' === WP_Agent_Tool_Executor_Registry::targetIdFromDeclaration( $tool_definition ) ) {
 			return $default_executor;
 		}
 
-		if ( null === $this->executor_registry ) {
+		$frozen_registry = $context['tool_executor_registry'] ?? null;
+		if ( $frozen_registry instanceof WP_Agent_Tool_Executor_Registry ) {
+			$this->executor_registry = $frozen_registry;
+		} elseif ( null === $this->executor_registry ) {
 			$this->executor_registry = WP_Agent_Tool_Executor_Registry::fromFilters( $context );
 		}
 
-		return $this->executor_registry->resolveForTool( $tool_definition, $default_executor );
+		return $this->executor_registry->executorForTarget( WP_Agent_Tool_Executor_Registry::targetIdFromDeclaration( $tool_definition ) );
 	}
 }