Context Navigation

← Previous Changeset
Next Changeset →

Changeset 3775519

Timestamp:

10/30/2026 02:56:36 PM (4 days ago)

Author:

arkenon

Message:

Release 1.3.4: dynamic tool loading, system abilities, post terms

Location:

agent-mod

Files:

: 364 added
: 15 edited

Legend:

: Unmodified
: Added
: Removed

agent-mod/trunk/agent-mod.php

r3770241	r3775519
7	7	* Requires at least: 7.0
8	8	* Requires PHP: 7.4
9		* Version: 1.3.3
	9	* Version: 1.3.4
10	10	* Author: Kadim Gültekin
11	11	* Author URI: https://profiles.wordpress.org/arkenon/

agent-mod/trunk/includes/App.php

-              r3761762
+              r3775519
 use AgentMod\Services\AbilityRegistrarService;
 use AgentMod\Services\AskUserAbilityService;
+use AgentMod\Services\FindAbilitiesAbilityService;
 use AgentMod\Common\DI;
 use AgentMod\Presentation\ControllerInit;
 …
                 NavigationAbilityService::class,
                 AskUserAbilityService::class,
+                FindAbilitiesAbilityService::class,
                 LibraryService::class,
                 SettingsService::class,

agent-mod/trunk/includes/Common/Constants.php

-              r3770241
+              r3775519
         /**
+         * Category of AgentMod's system abilities: the tools that are part of how
+         * the agent works (ask-user, present-plan, request-approval,
+         * find-abilities) rather than site capabilities. AgentMod alone decides
+         * when they are offered, so they are never part of an ability selection.
+         *
+         * @since 1.3.4
+         */
+        public const SYSTEM_ABILITY_CATEGORY = 'agent-mod-system';
+        /**
+         * Default tool loading strategy: 'dynamic' sends a small tool set and lets
+         * the agent load the rest through agent-mod/find-abilities; 'all' sends
+         * every allowed ability on every request.
+         *
+         * @since 1.3.4
+         */
+        public const AI_TOOL_LOADING = 'dynamic';
+        /**
+         * Allowed-ability count up to which dynamic loading still sends every
+         * ability: a small set costs less than the extra find round trip.
+         * Filterable via `agent_mod_dynamic_tools_threshold`.
+         *
+         * @since 1.3.4
+         */
+        public const AI_DYNAMIC_TOOLS_THRESHOLD = 15;
+        /**
+         * Most abilities one agent-mod/find-abilities call returns (and loads).
+         *
+         * @since 1.3.4
+         */
+        public const AI_FIND_ABILITIES_LIMIT = 8;
+        /**
          * HTTP timeout (seconds) for requests to AI provider APIs.
+         *
 …
         /**
          * How many of the most recent tool-result messages are re-sent verbatim on
          * each iteration of the tool-calling loop; older ones are elided to stubs.
          * Filterable via `agent_mod_history_keep_tool_results`.
+         * How many of the most recent tool-result messages are always re-sent
+         * verbatim, even once the history has been compacted. Filterable via
+         * `agent_mod_history_keep_tool_results`.
+         *
          * @since 1.1.5
          */
+        public const AI_HISTORY_KEEP_TOOL_RESULTS = 4;
+        public const AI_HISTORY_KEEP_TOOL_RESULTS = 6;
+        /**
+         * Estimated history size (tokens) at which the tool-calling loop starts
+         * eliding old tool results. Below it the history is sent whole. Filterable
+         * via `agent_mod_history_compact_trigger_tokens`.
+         *
+         * @since 1.3.4
+         */
+        public const AI_HISTORY_COMPACT_TRIGGER_TOKENS = 80000;
+        /**
+         * Estimated history size (tokens) a compaction elides down to. The gap to
+         * the trigger keeps compactions rare, so the sent prefix stays stable (and
+         * cacheable) between them. Filterable via
+         * `agent_mod_history_compact_target_tokens`.
+         *
+         * @since 1.3.4
+         */
+        public const AI_HISTORY_COMPACT_TARGET_TOKENS = 40000;
         /**
 …
                         ),
                         __(
                                 'When a tool can answer the user accurately, call it before responding. Base your answers on tool results rather than guessing.',
+                                'When a tool can answer the user accurately, call it before responding, unless the answer is already given in the site context or earlier in the conversation. Base your answers on tool results rather than guessing.',
                                 'agent-mod'
                         ),

agent-mod/trunk/includes/Presentation/Admin/Controllers/SettingsController.php

-              r3761762
+              r3775519
                                 'fields'        => [
+                                        [
+                                                'fieldType'   => 'select',
+                                                'name'        => 'ability_source',
+                                                'fieldLabel'  => __('Ability Source', 'agent-mod'),
+                                                'fieldHelpText'        => __('Choose whether to allow all abilities or only selected ones.', 'agent-mod'),
+                                                'options'     => 'All Abilities : all, Selected Abilities : selected',
+                                                'default'     => 'all',
+                                        ],
+                                        [
+                                                'fieldType'    => 'select',
+                                                'multiple'     => true,
+                                                'name'         => 'allowed_abilities',
+                                                'fieldLabel'   => __('Allowed Abilities', 'agent-mod'),
+                                                'className'    => 'agent-mod-wp-core-ui-select-multiple',
+                                                'fieldHelpText' => __('Select the abilities to allow. Used only when Ability Source is set to Selected Abilities.', 'agent-mod'),
+                                                'options'      => $this->getAbilityOptions(),
+                                                'default'      => [],
+                                                'dependencies' => [
+                                                        'relation'   => 'and',
+                                                        'conditions' => [
+                                                                [
+                                                                        'field'    => 'ability_source',
+                                                                        'operator' => '==',
+                                                                        'value'    => 'selected',
+                                                                ],
+                                                'fieldType'     => 'select',
+                                                'name'          => 'tool_loading',
+                                                'fieldLabel'    => __('Tool Loading', 'agent-mod'),
+                                                'fieldHelpText' => __('Dynamic (recommended): the agent starts with a few tools and loads the abilities it needs by searching for them, which keeps every request small. All: every ability is sent with every request; costs far more tokens on sites with many abilities.', 'agent-mod'),
+                                                'options'       => [
+                                                        [
+                                                                'label' => __('Dynamic (recommended)', 'agent-mod'),
+                                                                'value' => 'dynamic',
+                                                        ],
+                                                        [
+                                                                'label' => __('All abilities', 'agent-mod'),
+                                                                'value' => 'all',
                                                         ],
                                                 ],
+                                                'default'       => Constants::AI_TOOL_LOADING,
                                         ],
                                 ],
 …
                 );
+        }
-        /**
-         * Get allowed abilities options for the settings field.
+         *
-         * @return array<int, array<string, string>>
-         * @since 1.0.0
-         */
-        private function getAbilityOptions(): array
+        {
-                $options = [];
-                $abilities = wp_get_abilities();
-                foreach ($abilities as $ability) {
-                        $options[] = [
-                                'label' => $ability->get_label(),
-                                'value' => $ability->get_name(),
-                        ];
+                }
-                return $options;
+        }
+}

agent-mod/trunk/includes/Services/AI/AIClientAdapter.php

-              r3770241
+              r3775519
         /**
+         * Run-scoped ability catalog (dynamic tool loading).
+         *
+         * @var AbilityCatalog
+         * @since 1.3.4
+         */
+        private AbilityCatalog $catalog;
+        /**
          * Constructor (PHP-DI autowired).
+         *
 …
          * @param HistoryCompactor      $historyCompactor In-loop history compactor.
          * @param AskUserAbilityService $askUser          Ask-user ability service.
+         * @param AbilityCatalog        $catalog          Run-scoped ability catalog.
+         *
          * @since 1.0.0
 …
                 HttpTimeoutManager $httpTimeouts,
                 HistoryCompactor $historyCompactor,
+                AskUserAbilityService $askUser
+                AskUserAbilityService $askUser,
+                AbilityCatalog $catalog
         ) {
                 $this->toolCallRepairs  = $toolCallRepairs;
 …
                 $this->historyCompactor = $historyCompactor;
                 $this->askUser          = $askUser;
+                $this->catalog          = $catalog;
+        }
 …
          *                                           confirmation gate entirely.
          * @param bool        $webSearchEnabled  Whether to enable the provider's native web search tool.
+         * @param WP_Ability[]|null $tools       Tools sent at the start under dynamic tool loading (see
+         *                                       AbilityResolver::selectTools()); null sends every ability.
+         *
          * @return AgentResponse
 …
                 string $requestId = '',
                 array $autoApprovedAbilities = [],
+                bool $webSearchEnabled = false
+                bool $webSearchEnabled = false,
+                ?array $tools = null
         ): AgentResponse {
                 if (! function_exists('wp_ai_client_prompt')) {
 …
                 $this->toolCallRepairs->register();
                 $this->httpTimeouts->register();
+                $this->catalog->scope($abilities);
                 try {
 …
                                 $requestId,
                                 $autoApprovedAbilities,
+                                $webSearchEnabled
+                                $webSearchEnabled,
+                                [],
+                                $tools
                         );
                 } finally {
                         $this->toolCallRepairs->unregister();
                         $this->httpTimeouts->unregister();
+                        $this->catalog->clear();
                         // Progress and stop flags are only meaningful while the request is
 …
          * @param string      $decision              'approve', 'decline' or 'answer'.
          * @param array<string, mixed> $answerPayload Function response for the ask-user call ('answer' only).
+         * @param WP_Ability[]|null $tools       Tools sent at the start under dynamic tool loading; null sends every ability.
+         *
          * @return AgentResponse
 …
                 array $executedCalls,
                 string $decision,
+                array $answerPayload = []
+                array $answerPayload = [],
+                ?array $tools = null
         ): AgentResponse {
                 if (! function_exists('wp_ai_client_prompt')) {
 …
                 $this->toolCallRepairs->register();
                 $this->httpTimeouts->register();
+                $this->catalog->scope($abilities);
                 try {
 …
                                 $autoApprovedAbilities,
                                 $webSearchEnabled,
+                                $executedCalls
+                                $executedCalls,
+                                $tools
                         );
                 } finally {
                         $this->toolCallRepairs->unregister();
                         $this->httpTimeouts->unregister();
+                        $this->catalog->clear();
                         if ('' !== $requestId) {
 …
          *                                                           confirmation chain; seeds the executed
          *                                                           list so responses report the whole chain.
+         * @param WP_Ability[]|null $tools Tools sent at the start under dynamic tool loading; null sends every ability.
+         *
          * @return AgentResponse
 …
                 array $autoApprovedAbilities = [],
                 bool $webSearchEnabled = false,
+                array $initialToolCalls = []
+                array $initialToolCalls = [],
+                ?array $tools = null
         ): AgentResponse {
                 $resolver   = new WP_AI_Client_Ability_Function_Resolver(...$abilities);
 …
                 $tokenUsage = [];
                 $callCounts = [];
+                // History index of the latest result of each read call signature, and
+                // the index below which the compactor has elided results in this run.
+                $readIndexes = [];
+                $watermark   = 0;
                 for ($i = 0; $i < $maxToolCalls; $i++) {
 …
                         // The provider gets a compacted copy; $history itself stays intact
                         // for the AgentResponse / confirmation-resume flow.
+                        $compacted = $this->historyCompactor->compact($history, $watermark);
+                        // A read whose result was elided may run again: blocking it would
+                        // leave the model with neither the data nor a way to get it back.
+                        $this->forgetElidedReads($callCounts, $readIndexes, $watermark);
                         $builder = wp_ai_client_prompt()
                                 ->with_history(...$this->historyCompactor->compact($history))
+                                ->with_history(...$compacted)
                                 ->using_system_instruction($systemInstruction);
 …
+                        }
+                        if (! empty($abilities)) {
+                                $builder->using_abilities(...$abilities);
+                        $sentTools = null === $tools ? $abilities : $this->withLoadedTools($tools, $abilities, $history);
+                        if (! empty($sentTools)) {
+                                $builder->using_abilities(...$sentTools);
+                        }
 …
                         $resultMessage = $this->executeAbilities($resolver, $message, $callCounts);
+                        $history[]     = $resultMessage;
+                        foreach ($requestedCalls as $call) {
+                                if (! $this->isWriteAbility((string) $call['name'])) {
+                                        $readIndexes[$this->readSignature((string) $call['name'], $call['args'])] = count($history);
+                                }
+                        }
+                        $history[] = $resultMessage;
                         $this->logToolFailures($resultMessage);
 …
                 $finalBuilder = wp_ai_client_prompt()
                         ->with_history(...$this->historyCompactor->compact($history))
+                        ->with_history(...$this->historyCompactor->compact($history, $watermark))
                         ->using_system_instruction($systemInstruction);
 …
                         $this->extractStopReason($finalResult)
                 );
+        }
+        /**
+         * Appends the abilities loaded during the run to the initial tool set.
+         *
+         * Loaded abilities (find-abilities matches and abilities the model called)
+         * go after the initial set, in the order they were loaded, and stay for the
+         * rest of the run. The tool block therefore only ever grows at its end,
+         * which keeps the provider's cached prompt prefix as long as possible.
+         * Only abilities of the run's allowed set are added.
+         *
+         * @param WP_Ability[] $tools     Initial tool set.
+         * @param WP_Ability[] $abilities Abilities allowed in the run.
+         * @param Message[]    $history   Wire-format history of the run.
+         *
+         * @return WP_Ability[]
+         * @since 1.3.4
+         */
+        private function withLoadedTools(array $tools, array $abilities, array $history): array
+        {
+                $allowed = [];
+                foreach ($abilities as $ability) {
+                        if ($ability instanceof WP_Ability) {
+                                $allowed[$ability->get_name()] = $ability;
+                        }
+                }
+                $sent = [];
+                foreach ($tools as $tool) {
+                        if ($tool instanceof WP_Ability) {
+                                $sent[$tool->get_name()] = $tool;
+                        }
+                }
+                foreach ($this->catalog->loadedNames($history) as $name) {
+                        if (! isset($sent[$name]) && isset($allowed[$name])) {
+                                $sent[$name] = $allowed[$name];
+                        }
+                }
+                return array_values($sent);
+        }
 …
                         $digest = (string) wp_json_encode($responses[$index]->getResponse(), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+                        $calls[$index]['result'] = $isAnswer ? $digest : mb_substr($digest, 0, $digestLength);
+                        if ($isAnswer) {
+                                $calls[$index]['result'] = $digest;
+                                continue;
+                        }
+                        // A configuration the agent writes code against (e.g. a field
+                        // configuration) keeps the larger summary budget, so a follow-up
+                        // message can still use it instead of asking the user to paste it.
+                        if ($this->historyCompactor->isStickyTool((string) ($call['name'] ?? ''))) {
+                                $calls[$index]['result'] = mb_substr($digest, 0, max($digestLength, Constants::AI_LIST_RESULT_SUMMARY_LENGTH));
+                                continue;
+                        }
+                        // A nested result too long for the digest keeps its skeleton
+                        // rather than its first few hundred characters.
+                        $structureSummary = mb_strlen($digest) > $digestLength
+                                ? $this->historyCompactor->summarizeStructure($responses[$index]->getResponse())
+                                : null;
+                        $calls[$index]['result'] = $structureSummary ?? mb_substr($digest, 0, $digestLength);
+                }
 …
+                }
                 $signature = $abilityName . '|' . md5((string) wp_json_encode($this->normalizeArgs($functionCall->getArgs() ?? [])));
+                $signature = $this->readSignature($abilityName, $functionCall->getArgs());
                 $seen      = $callCounts[$signature] ?? 0;
 …
         /**
+         * Builds the repeat-guard signature of a read call.
+         *
+         * @param string $abilityName Ability name.
+         * @param mixed  $args        Call arguments.
+         *
+         * @return string
+         * @since 1.3.4
+         */
+        private function readSignature(string $abilityName, $args): string
+        {
+                return $abilityName . '|' . md5((string) wp_json_encode($this->normalizeArgs($args ?? [])));
+        }
+        /**
+         * Resets the repeat-guard count of reads whose latest result was elided.
+         *
+         * The guard exists to stop a model re-fetching data it still has. Once the
+         * compactor has elided that data, a repeat is the only way to get it back,
+         * so the signature starts counting from zero again.
+         *
+         * @param array<string, int> $callCounts  Per-run counts of read call signatures.
+         * @param array<string, int> $readIndexes History index of the latest result per signature.
+         * @param int                $watermark   History index below which results are elided.
+         *
+         * @return void
+         * @since 1.3.4
+         */
+        private function forgetElidedReads(array &$callCounts, array &$readIndexes, int $watermark): void
+        {
+                foreach ($readIndexes as $signature => $index) {
+                        if ($index < $watermark) {
+                                unset($callCounts[$signature], $readIndexes[$signature]);
+                        }
+                }
+        }
+        /**
          * Normalizes call arguments for signature comparison (recursively sorted keys).
+         *

agent-mod/trunk/includes/Services/AI/AIOrchestratorService.php

-              r3761762
+              r3775519
         /**
+         * Ability catalog (category index for dynamic tool loading).
+         *
+         * @var AbilityCatalog
+         * @since 1.3.4
+         */
+        private AbilityCatalog $abilityCatalog;
+        /**
          * Constructor (PHP-DI autowired).
+         *
 …
          * @param AIClientAdapter   $clientAdapter     WP AI Client adapter.
          * @param ConfirmationStore $confirmationStore Pending write-action store.
+         * @param AbilityCatalog    $abilityCatalog    Ability catalog.
+         *
          * @since 1.0.0
 …
                 KnowledgeResolver $knowledgeResolver,
                 AIClientAdapter $clientAdapter,
+                ConfirmationStore $confirmationStore
+                ConfirmationStore $confirmationStore,
+                AbilityCatalog $abilityCatalog
         ) {
                 $this->promptBuilder     = $promptBuilder;
 …
                 $this->clientAdapter     = $clientAdapter;
                 $this->confirmationStore = $confirmationStore;
+                $this->abilityCatalog    = $abilityCatalog;
+        }
 …
                 $siteContext = $agent->autoIncludeSiteContext ? $this->knowledgeResolver->getSiteContext() : [];
+                $systemInstruction = $this->promptBuilder->buildSystemInstruction($agent, $siteContext);
+                $abilities = $this->abilityResolver->resolve($agent);
+                // Before the tools are selected, and stored with the agent so a paused
+                // run resumes with the same tool list.
+                $agent->preloadedAbilities = $this->recentToolNames($history);
+                $toolset = $this->resolveToolset($agent);
+                $systemInstruction = $this->promptBuilder->buildSystemInstruction($agent, $siteContext, $toolset['catalog']);
                 $messages   = $this->mapHistoryToMessages($history);
 …
                         $systemInstruction,
                         $messages,
                         $abilities,
+                        $toolset['abilities'],
                         $agent->provider,
                         $agent->model,
 …
                         $requestId,
                         $autoApprovedAbilities,
+                        $agent->webSearchEnabled
+                        $agent->webSearchEnabled,
+                        $toolset['tools']
                 );
 …
                 $siteContext = $agent->autoIncludeSiteContext ? $this->knowledgeResolver->getSiteContext() : [];
+                $systemInstruction = $this->promptBuilder->buildSystemInstruction($agent, $siteContext);
+                $abilities         = $this->abilityResolver->resolve($agent);
+                $toolset = $this->resolveToolset($agent);
+                $systemInstruction = $this->promptBuilder->buildSystemInstruction($agent, $siteContext, $toolset['catalog']);
                 $response = $this->clientAdapter->resume(
                         $systemInstruction,
                         $messages,
                         $abilities,
+                        $toolset['abilities'],
                         $agent->provider,
                         $agent->model,
 …
                         $executedCalls,
                         $decision,
+                        $answerPayload
+                        $answerPayload,
+                        $toolset['tools']
                 );
 …
                 return $response;
+        }
+        /**
+         * Resolves the abilities of a run and the tools sent up front.
+         *
+         * @param AgentConfig $agent The agent configuration.
+         *
+         * @return array{abilities: \WP_Ability[], tools: \WP_Ability[]|null, catalog: array<string, array{label: string, count: int}>}
+         *         catalog is empty when every ability is sent as a tool.
+         * @since 1.3.4
+         */
+        private function resolveToolset(AgentConfig $agent): array
+        {
+                $abilities = $this->abilityResolver->resolve($agent);
+                $toolset   = $this->abilityResolver->selectTools($agent, $abilities);
+                $toolset['catalog'] = null === $toolset['tools'] ? [] : $this->abilityCatalog->categoryIndex($abilities);
+                return $toolset;
+        }
+        /**
+         * Ability names the agent used in the recent turns of the conversation.
+         *
+         * Covers the same turns whose tool digests are replayed to the model
+         * (agent_mod_history_tool_digest_turns), so the tools behind the results the
+         * model reads are loaded too. The history comes from the client; the names
+         * are only used after being intersected with the allowed abilities.
+         *
+         * @param array<int, array<string, mixed>> $history Prior turns.
+         *
+         * @return string[]
+         * @since 1.3.4
+         */
+        private function recentToolNames(array $history): array
+        {
+                /** This filter is documented in AIOrchestratorService::mapHistoryToMessages(). */
+                $turns = max(0, (int) apply_filters('agent_mod_history_tool_digest_turns', 6));
+                $toolTurns = array_filter($history, static function ($turn): bool {
+                        return is_array($turn) && ! empty($turn['toolCalls']) && is_array($turn['toolCalls']);
+                });
+                $names = [];
+                foreach ($turns > 0 ? array_slice($toolTurns, -$turns) : [] as $turn) {
+                        foreach ($turn['toolCalls'] as $call) {
+                                $name = is_array($call) ? sanitize_text_field((string) ($call['name'] ?? '')) : '';
+                                if ('' !== $name && AbilityCatalog::FIND !== $name) {
+                                        $names[] = $name;
+                                }
+                        }
+                }
+                return array_slice(array_values(array_unique($names)), 0, 20);
+        }

agent-mod/trunk/includes/Services/AI/AbilityResolver.php

-              r3770241
+              r3775519
 use WP_Ability;
+use AgentMod\Common\Constants;
 use AgentMod\Services\AI\DTO\AgentConfig;
 use AgentMod\Services\AskUserAbilityService;
+use AgentMod\Services\SettingsService;
 defined('ABSPATH') || exit;
 …
 class AbilityResolver
+{
+        /**
+         * Name prefix of the MCP Adapter plugin's abilities, which are never resolved.
+         *
+         * @var string
+         * @since 1.3.4
+         */
+        private const MCP_ADAPTER_PREFIX = 'mcp-adapter/';
+        /**
+         * Settings service; supplies the tool loading strategy.
+         *
+         * @var SettingsService
+         * @since 1.3.4
+         */
+        private SettingsService $settings;
+        /**
+         * Constructor (PHP-DI autowired).
+         *
+         * @param SettingsService $settings Settings service.
+         *
+         * @since 1.3.4
+         */
+        public function __construct(SettingsService $settings)
+        {
+                $this->settings = $settings;
+        }
         /**
          * Resolves the abilities available to an agent.
 …
                         ? $this->resolveSelected($agent->allowedAbilities)
                         : array_values(wp_get_abilities());
+                // System abilities are added below and in selectTools() exactly when they
+                // apply, never because they were selected or registered.
+                $abilities = array_values(array_filter($abilities, static function ($ability): bool {
+                        return ! $ability instanceof WP_Ability || self::isSelectable($ability);
+                }));
                 // Ask/Plan modes only get read-only abilities; Pro keeps final say via the filter below.
 …
         /**
+         * Whether an ability can be part of an ability selection.
+         *
+         * Two kinds of abilities never are, so selection lists should not offer them
+         * and resolve() drops them from every list:
+         *
+         *  - AgentMod's system abilities (Constants::SYSTEM_ABILITY_CATEGORY): part
+         *    of how the agent works; AgentMod offers them when they apply.
+         *  - The MCP Adapter's abilities: discover / get-info / execute are a proxy
+         *    for every other ability. execute-ability would run any of them under
+         *    its own name, past the per-name write confirmation, auto-approval and
+         *    a PRO agent's allowlist; the agent calls abilities directly anyway.
+         *
+         * @param WP_Ability $ability The ability.
+         *
+         * @return bool
+         * @since 1.3.4
+         */
+        public static function isSelectable(WP_Ability $ability): bool
+        {
+                return ! self::isSystemAbility($ability) && 0 !== strpos($ability->get_name(), self::MCP_ADAPTER_PREFIX);
+        }
+        /**
+         * Whether an ability is one of AgentMod's system abilities.
+         *
+         * @param WP_Ability $ability The ability.
+         *
+         * @return bool
+         * @since 1.3.4
+         */
+        public static function isSystemAbility(WP_Ability $ability): bool
+        {
+                return Constants::SYSTEM_ABILITY_CATEGORY === $ability->get_category();
+        }
+        /**
+         * Splits the resolved abilities into what may run and what is sent as tools.
+         *
+         * Under dynamic tool loading only a small set goes out as tool definitions:
+         * the system abilities (find-abilities, the interactive chat tools), the core abilities
+         * (agent_mod_core_abilities), the abilities the user highlighted and those
+         * preloaded from recent turns. Everything else is reached through
+         * find-abilities, which loads its matches into the tool list during the run.
+         * The executable set is the resolved set plus find-abilities, so the write
+         * gate, auto-approval and read-only rules keep working on real ability names.
+         *
+         * Small sets (up to agent_mod_dynamic_tools_threshold abilities) and the
+         * 'all' strategy send everything, as before.
+         *
+         * @param AgentConfig  $agent     The agent configuration.
+         * @param WP_Ability[] $abilities Abilities from resolve().
+         *
+         * @return array{abilities: WP_Ability[], tools: WP_Ability[]|null} tools is null when every ability is sent.
+         * @since 1.3.4
+         */
+        public function selectTools(AgentConfig $agent, array $abilities): array
+        {
+                $everything = ['abilities' => $abilities, 'tools' => null];
+                /**
+                 * Filters the tool loading strategy of a run: 'dynamic' or 'all'.
+                 *
+                 * @param string      $strategy Strategy from the settings page.
+                 * @param AgentConfig $agent    The agent configuration.
+                 *
+                 * @since 1.3.4
+                 */
+                $strategy = (string) apply_filters('agent_mod_tool_loading', $this->settings->getToolLoading(), $agent);
+                /**
+                 * Filters the ability count up to which dynamic loading still sends every ability.
+                 *
+                 * @param int $threshold Ability count.
+                 *
+                 * @since 1.3.4
+                 */
+                $threshold = (int) apply_filters('agent_mod_dynamic_tools_threshold', Constants::AI_DYNAMIC_TOOLS_THRESHOLD);
+                $find = function_exists('wp_get_ability') ? wp_get_ability(AbilityCatalog::FIND) : null;
+                if ('dynamic' !== $strategy || count($abilities) <= $threshold || ! $find instanceof WP_Ability) {
+                        return $everything;
+                }
+                /**
+                 * Filters the abilities that are always sent as tools under dynamic loading.
+                 *
+                 * Only names that are also allowed for the run are used.
+                 *
+                 * @param string[]    $names Ability names.
+                 * @param AgentConfig $agent The agent configuration.
+                 *
+                 * @since 1.3.4
+                 */
+                $core = (array) apply_filters('agent_mod_core_abilities', [], $agent);
+                $initial = array_merge($core, $agent->emphasizedAbilities, $agent->preloadedAbilities);
+                $abilities   = array_values(array_filter($abilities, static function ($ability): bool {
+                        return $ability instanceof WP_Ability;
+                }));
+                $abilities[] = $find;
+                usort($abilities, static function (WP_Ability $a, WP_Ability $b): int {
+                        return strcmp($a->get_name(), $b->get_name());
+                });
+                // Filtering the name-sorted set keeps the tool block in the same order
+                // on every request, which provider prompt caching depends on.
+                $tools = array_values(array_filter($abilities, static function (WP_Ability $ability) use ($initial): bool {
+                        return self::isSystemAbility($ability) || in_array($ability->get_name(), $initial, true);
+                }));
+                return ['abilities' => $abilities, 'tools' => $tools];
+        }
+        /**
          * Offers the interactive chat tools exactly when somebody can use them.
+         *
          * ask-user is offered on an interactive channel; present-plan only there
          * and in Plan mode; request-approval only there, in Execute mode with
          * manual approval. On such a channel they are added even when the agent
          * uses a "selected" ability list, because they are part of the chat itself
          * rather than site capabilities. Everywhere else (widgets, scheduled runs)
          * they are removed, even when "all" abilities were resolved: nobody would
          * see the questions or the review options.
+         *
          * @param WP_Ability[] $abilities Resolved abilities.
+         * manual approval. They are system abilities, so resolve() has already
+         * dropped them from the list whether or not they were selected; on an
+         * interactive channel they are added back here. Everywhere else (widgets,
+         * scheduled runs) they stay out: nobody would see the questions or the
+         * review options.
+         *
+         * @param WP_Ability[] $abilities Resolved abilities, without system abilities.
          * @param AgentConfig  $agent     The agent configuration.
+         *
 …
         private function applyInteractiveTools(array $abilities, AgentConfig $agent): array
+        {
-                $interactiveTools = [
-                        AskUserAbilityService::NAME,
-                        AskUserAbilityService::PRESENT_PLAN,
-                        AskUserAbilityService::REQUEST_APPROVAL,
-                ];
-                $abilities = array_values(array_filter($abilities, static function ($ability) use ($interactiveTools): bool {
-                        return ! ($ability instanceof WP_Ability && in_array($ability->get_name(), $interactiveTools, true));
-                }));
                 if (! $agent->interactive) {
                         return $abilities;

agent-mod/trunk/includes/Services/AI/DTO/AgentConfig.php

-              r3770241
+              r3775519
          */
         public string $approvalMode = 'manual';
+        /**
+         * Ability names loaded up front under dynamic tool loading.
+         *
+         * Set server-side by the orchestrator from the tools used in recent turns,
+         * so a follow-up message ("now do the same for the other page") does not
+         * have to search for them again. Carried on the DTO because the DTO is what
+         * the confirmation store keeps for a paused run. Names are only ever
+         * intersected with the allowed abilities, never trusted on their own.
+         *
+         * @var string[]
+         * @since 1.3.4
+         */
+        public array $preloadedAbilities = [];
         /**

agent-mod/trunk/includes/Services/AI/HistoryCompactor.php

-              r3770241
+              r3775519
  * re-uploaded verbatim on every later iteration, and screenshot attachments on
  * the user message are re-uploaded too. This service compacts the copy of the
+ * history that goes to the provider: old tool results are elided to short
+ * stubs (their call id and name are preserved — providers require a response
+ * for every outstanding call), and binary file parts are kept only on the most
+ * recent user message. The canonical history kept for persistence and the
+ * confirmation/resume flow is never modified.
+ * history that goes to the provider: binary file parts are kept only on the
+ * most recent user message, and once the history grows past a token threshold
+ * old tool results are elided to short summaries (their call id and name are
+ * preserved — providers require a response for every outstanding call). The
+ * canonical history kept for persistence and the confirmation/resume flow is
+ * never modified.
+ *
+ * Elision is threshold-based and sticky on purpose. Below the trigger nothing
+ * is elided, so the model keeps every result it fetched. When the trigger is
+ * crossed, results are elided oldest first down to a lower target and a
+ * watermark records how far it went; later iterations elide exactly the same
+ * messages until the next crossing. The sent prefix therefore stays byte-
+ * identical between compactions, which keeps provider prompt caches warm —
+ * a window sliding on every iteration would invalidate them each time.
+ *
  * @package AgentMod
 …
     /**
+     * Keys kept at every depth in the structure summary of a nested result
+     * (e.g. a field configuration tree), so its skeleton survives elision.
+     *
+     * @var string[]
+     * @since 1.3.4
+     */
+    private const STRUCTURE_KEYS = [
+        'id', 'ID', 'post_id', 'term_id', 'user_id', 'name', 'slug', 'title', 'label', 'status', 'post_type', 'taxonomy',
+        'type', 'fieldType', 'fieldLabel', 'meta_box_id', 'meta_box_title', 'section_name', 'section_title', 'menu_slug',
+        'options', 'multiple', 'required', 'default',
+    ];
+    /**
+     * Maximum length of a top-level string kept in a structure summary.
+     *
+     * @var int
+     * @since 1.3.4
+     */
+    private const STRUCTURE_STRING_LENGTH = 200;
+    /**
+     * Rough characters-per-token ratio used to estimate history size.
+     *
+     * @var int
+     * @since 1.3.4
+     */
+    private const CHARS_PER_TOKEN = 4;
+    /**
+     * Estimated token cost of one file part (image / PDF attachment).
+     *
+     * @var int
+     * @since 1.3.4
+     */
+    private const FILE_PART_TOKENS = 1500;
+    /**
      * Compacts a history for sending to the provider.
+     *
+     * @param Message[] $history Conversation history (never mutated).
+     * Pass the same $watermark variable on every iteration of one run: it
+     * records up to which history index tool results have been elided, so
+     * later calls elide the same messages and only move it on the next
+     * threshold crossing.
+     *
+     * @param Message[] $history   Conversation history (never mutated).
+     * @param int       $watermark History index below which tool results are elided; advanced in place.
+     *
      * @return Message[] Compacted copy.
      * @since 1.1.5
      */
     public function compact(array $history): array
+    public function compact(array $history, int &$watermark = 0): array
+    {
         /**
          * Filters how many of the most recent tool-result messages are re-sent
          * verbatim; older ones are elided to stubs.
+         * Filters how many of the most recent tool-result messages are always
+         * re-sent verbatim, even once the history has been compacted.
+         *
          * @param int $keep Number of tool-result messages kept verbatim.
 …
          */
         $keep = max(0, (int) apply_filters('agent_mod_history_keep_tool_results', Constants::AI_HISTORY_KEEP_TOOL_RESULTS));
+        /**
+         * Filters the estimated history size (tokens) at which old tool
+         * results start being elided.
+         *
+         * @param int $trigger Token threshold.
+         *
+         * @since 1.3.4
+         */
+        $trigger = max(0, (int) apply_filters('agent_mod_history_compact_trigger_tokens', Constants::AI_HISTORY_COMPACT_TRIGGER_TOKENS));
+        /**
+         * Filters the estimated history size (tokens) a compaction elides
+         * down to. Kept below the trigger so compactions stay rare.
+         *
+         * @param int $target Token target.
+         *
+         * @since 1.3.4
+         */
+        $target = min($trigger, max(0, (int) apply_filters('agent_mod_history_compact_target_tokens', Constants::AI_HISTORY_COMPACT_TARGET_TOKENS)));
         $toolResultIndexes = [];
 …
+        }
+        // Tool-result messages recent enough to stay verbatim. (array_slice
+        // with -0 would return the whole array, so 0 is handled explicitly.)
+        $verbatim = $keep > 0 ? array_flip(array_slice($toolResultIndexes, -$keep)) : [];
+        // The first tool-result message recent enough to always stay verbatim.
+        // (array_slice with -0 would return the whole array, so 0 is handled
+        // explicitly.)
+        $recent      = $keep > 0 ? array_slice($toolResultIndexes, -$keep) : [];
+        $firstRecent = empty($recent) ? PHP_INT_MAX : (int) reset($recent);
         // Only the most recent attachment-bearing user message keeps its files.
 …
         foreach ($history as $index => $message) {
             if (! $message instanceof Message) {
+                $compacted[] = $message;
+                continue;
+            }
+            if (in_array($index, $toolResultIndexes, true) && ! isset($verbatim[$index])) {
+                $compacted[] = $this->elideToolResults($message, $sticky[$index] ?? []);
+                $compacted[$index] = $message;
+                continue;
+            }
+            // Everything below the watermark was elided by an earlier
+            // compaction of this run and stays elided, so the prefix the
+            // provider sees does not change between compactions.
+            if ($index < $watermark && in_array($index, $toolResultIndexes, true)) {
+                $compacted[$index] = $this->elideToolResults($message, $sticky[$index] ?? []);
                 continue;
+            }
 …
                 && $index !== $lastFileIndex
             ) {
+                $compacted[] = $this->stripFiles($message);
+                continue;
+            }
+            $compacted[] = $message;
+        }
+        return $compacted;
+                $compacted[$index] = $this->stripFiles($message);
+                continue;
+            }
+            $compacted[$index] = $message;
+        }
+        $tokens = $this->estimateTokens($compacted);
+        if ($tokens < $trigger) {
+            return array_values($compacted);
+        }
+        // Over the threshold: elide the oldest results down to the target and
+        // move the watermark past the last one elided.
+        foreach ($toolResultIndexes as $index) {
+            if ($tokens <= $target || $index >= $firstRecent) {
+                break;
+            }
+            if ($index < $watermark) {
+                continue;
+            }
+            $before            = $this->estimateTokens([$compacted[$index]]);
+            $compacted[$index] = $this->elideToolResults($history[$index], $sticky[$index] ?? []);
+            $tokens           -= $before - $this->estimateTokens([$compacted[$index]]);
+            $watermark         = $index + 1;
+        }
+        return array_values($compacted);
+    }
+    /**
+     * Estimates the token size of a history.
+     *
+     * A characters / 4 heuristic over text and JSON-encoded function call and
+     * response parts; each file part counts as a fixed amount. Only used to
+     * decide when to compact, so a rough figure is enough.
+     *
+     * @param Message[] $history Conversation history.
+     *
+     * @return int Estimated tokens.
+     * @since 1.3.4
+     */
+    public function estimateTokens(array $history): int
+    {
+        $chars = 0;
+        $files = 0;
+        foreach ($history as $message) {
+            if (! $message instanceof Message) {
+                continue;
+            }
+            foreach ($message->getParts() as $part) {
+                $type = $part->getType();
+                if ($type->isFile()) {
+                    $files++;
+                } elseif ($type->isFunctionCall()) {
+                    $call   = $part->getFunctionCall();
+                    $chars += null === $call ? 0 : strlen((string) wp_json_encode($call->getArgs())) + strlen((string) $call->getName());
+                } elseif ($type->isFunctionResponse()) {
+                    $response = $part->getFunctionResponse();
+                    $chars   += null === $response ? 0 : strlen((string) wp_json_encode($response->getResponse()));
+                } else {
+                    $chars += strlen((string) $part->getText());
+                }
+            }
+        }
+        return (int) ceil($chars / self::CHARS_PER_TOKEN) + $files * self::FILE_PART_TOKENS;
+    }
+    /**
+     * Whether an ability's results are exempt from elision.
+     *
+     * By default the Pro skill fetcher, the ask-user / request-approval
+     * answers and the Native Custom Fields configuration reads: a field
+     * configuration is what the agent writes code against, and losing it
+     * mid-task sends the agent back to re-read it or to guess meta keys.
+     *
+     * @param string $abilityName Ability name.
+     *
+     * @return bool
+     * @since 1.3.4
+     */
+    public function isStickyTool(string $abilityName): bool
+    {
+        return in_array($abilityName, $this->stickyTools(), true);
+    }
+    /**
+     * Returns the ability names whose results are never elided.
+     *
+     * @return string[]
+     * @since 1.3.4
+     */
+    private function stickyTools(): array
+    {
+        /**
+         * Filters the ability names whose most recent result per argument
+         * identity is never elided from the in-loop history.
+         *
+         * @param string[] $stickyTools Ability names.
+         *
+         * @since 1.1.5
+         */
+        // The user's answers to ask-user / request-approval are their own input,
+        // so they are never elided either.
+        return (array) apply_filters(
+            'agent_mod_history_sticky_tools',
+            array_merge(
+                [
+                    'agent-mod-pro/get-skill-by-slug',
+                    'native-custom-fields/get-post-meta-fields',
+                    'native-custom-fields/get-term-meta-fields',
+                    'native-custom-fields/get-user-meta-fields',
+                    'native-custom-fields/get-options-page',
+                ],
+                AskUserAbilityService::PAUSING_TOOLS
+            )
+        );
+    }
 …
     private function resolveStickyParts(array $history, array $toolResultIndexes): array
+    {
+        /**
+         * Filters the ability names whose most recent result per argument
+         * identity is never elided from the in-loop history.
+         *
+         * @param string[] $stickyTools Ability names.
+         *
+         * @since 1.1.5
+         */
+        // The user's answers to ask-user / request-approval are their own input,
+        // so they are never elided either.
+        $stickyTools = (array) apply_filters(
+            'agent_mod_history_sticky_tools',
+            array_merge(['agent-mod-pro/get-skill-by-slug'], AskUserAbilityService::PAUSING_TOOLS)
+        );
+        $stickyTools = $this->stickyTools();
         if (empty($stickyTools)) {
 …
             // A list keeps its IDs and titles: losing them is what sent the
+            // agent back to list the same posts again and again.
+            $listSummary = $this->summarizeListResult($response->getResponse());
+            $payload = null !== $listSummary
+                ? [
+            // agent back to list the same posts again and again. A nested
+            // result (e.g. a field configuration) keeps its skeleton.
+            $listSummary      = $this->summarizeListResult($response->getResponse());
+            $structureSummary = null === $listSummary ? $this->summarizeStructure($response->getResponse()) : null;
+            if (null !== $listSummary) {
+                $payload = [
                     'elided'       => true,
                     'list_summary' => $listSummary,
                     'note'         => __('Older list result reduced to IDs and titles to save context. Reuse these IDs; do not list the same items again.', 'agent-mod'),
+                ]
+                : [
+                ];
+            } elseif (null !== $structureSummary) {
+                $payload = [
+                    'elided'            => true,
+                    'structure_summary' => $structureSummary,
+                    'note'              => __('Older result reduced to its structure (names, types, labels) to save context. If you need the omitted details, call the same tool again.', 'agent-mod'),
+                ];
+            } else {
+                $payload = [
                     'elided'  => true,
                     'summary' => mb_substr(
 …
 ,
                         Constants::AI_TOOL_RESULT_STUB_LENGTH
                     ) . '… ' . __('(older tool result elided to save context; re-call the tool only if you truly need the full data again)', 'agent-mod'),
+                    ) . '… ' . __('(older tool result elided to save context; if you need the full data, call the same tool again)', 'agent-mod'),
                 ];
+            }
             $parts[] = new MessagePart(
 …
     /**
+     * Reduces a nested tool result to its structural skeleton.
+     *
+     * Applies to results that hold nested arrays but are not ID lists, such
+     * as a Native Custom Fields configuration (sections → fields → sub-fields).
+     * Top-level scalars are kept (long strings cut short); below the top level
+     * only identifying keys (name, type, fieldType, label, options …) are kept,
+     * at any depth.
+     *
+     * @param mixed $payload Tool result.
+     *
+     * @return string|null JSON summary capped at AI_LIST_RESULT_SUMMARY_LENGTH, or null when the result has no nested structure.
+     * @since 1.3.4
+     */
+    public function summarizeStructure($payload): ?string
+    {
+        if (! is_array($payload) || empty(array_filter($payload, 'is_array'))) {
+            return null;
+        }
+        $skeleton = $this->skeleton($payload, 0);
+        if (empty($skeleton)) {
+            return null;
+        }
+        return mb_substr(
+            (string) wp_json_encode($skeleton, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
+,
+            Constants::AI_LIST_RESULT_SUMMARY_LENGTH
+        );
+    }
+    /**
+     * Recursively keeps the structural keys of a nested array.
+     *
+     * @param array<mixed> $value Array to reduce.
+     * @param int          $depth Current depth (0 = top level).
+     *
+     * @return array<mixed>
+     * @since 1.3.4
+     */
+    private function skeleton(array $value, int $depth): array
+    {
+        $keep = array_flip(self::STRUCTURE_KEYS);
+        $out  = [];
+        foreach ($value as $key => $item) {
+            if (is_array($item)) {
+                $child = $this->skeleton($item, $depth + 1);
+                if (! empty($child)) {
+                    $out[$key] = $child;
+                }
+            } elseif (0 === $depth) {
+                $out[$key] = is_string($item) ? mb_substr($item, 0, self::STRUCTURE_STRING_LENGTH) : $item;
+            } elseif (is_int($key) || isset($keep[$key])) {
+                $out[$key] = $item;
+            }
+        }
+        return $out;
+    }
+    /**
      * Whether a value is a non-empty list of items that carry an ID.
+     *

agent-mod/trunk/includes/Services/AI/KnowledgeResolver.php

r3585895	r3775519
34	34	'wp_version' => (string) get_bloginfo('version'),
35	35	'language' => (string) get_bloginfo('language'),
	36	'php_version' => PHP_VERSION,
36	37	];
37	38	}

agent-mod/trunk/includes/Services/AI/PromptBuilder.php

-              r3761762
+              r3775519
          * Builds the full system instruction for an agent.
+         *
+         * @param AgentConfig            $agent       The agent configuration.
+         * @param array<string, string>  $siteContext Site context (may be empty).
+         * @param AgentConfig                                      $agent       The agent configuration.
+         * @param array<string, string>                            $siteContext Site context (may be empty).
+         * @param array<string, array{label: string, count: int}> $toolCatalog Categories of the abilities left to
+         *                                                                      find under dynamic tool loading
+         *                                                                      (AbilityCatalog::categoryIndex()); empty
+         *                                                                      when every ability is sent as a tool.
+         *
          * @return string
          * @since 1.0.0
          */
         public function buildSystemInstruction(AgentConfig $agent, array $siteContext = []): string
+        public function buildSystemInstruction(AgentConfig $agent, array $siteContext = [], array $toolCatalog = []): string
+        {
                 $sections = [];
 …
                 $sections[] = __('Earlier tool results are summarized in the conversation history as "[Tools used this turn]" blocks. Trust those summaries: do not re-call the same read tool with the same arguments to retrieve data you already have.', 'agent-mod');
+                if (! empty($toolCatalog)) {
+                        $sections[] = $this->buildToolLoadingDirective($toolCatalog);
+                }
                 $emphasized = $this->resolveEmphasized($agent);
                 if (! empty($emphasized)) {
 …
                 return (string) apply_filters('agent_mod_system_prompt', $instruction, $agent);
+        }
+        /**
+         * Builds the directive for dynamic tool loading.
+         *
+         * Without it the model takes its short tool list for everything it can do
+         * and tells the user a task is impossible. The category list costs a few
+         * hundred tokens at most and tells the model what is worth searching for.
+         *
+         * @param array<string, array{label: string, count: int}> $toolCatalog Categories keyed by slug.
+         *
+         * @return string
+         * @since 1.3.4
+         */
+        private function buildToolLoadingDirective(array $toolCatalog): string
+        {
+                $lines = [
+                        sprintf(
+                                /* translators: %s: find-abilities ability name. */
+                                __('Only a few of your tools are loaded at the start. Whenever the loaded tools cannot do what the task needs, call %s with short English keywords first; the tools it returns are loaded for your next step. Never tell the user something cannot be done before searching for a tool. Tool categories you can search (slug: label, number of tools):', 'agent-mod'),
+                                AbilityCatalog::FIND
+                        ),
+                ];
+                foreach ($toolCatalog as $slug => $category) {
+                        $lines[] = sprintf('- %s: %s (%d)', '' !== $slug ? $slug : '-', $category['label'], $category['count']);
+                }
+                return implode("\n", $lines);
+        }
 …
                         'wp_version'       => __('WordPress version', 'agent-mod'),
                         'language'         => __('Language', 'agent-mod'),
+                        'php_version'      => __('PHP version', 'agent-mod'),
                 ];
 …
+                }
+                // Without this the model treats the block as a hint and re-fetches the
+                // same values with the site/environment info tools on every turn.
+                $lines[] = __('This site context is current and authoritative. Use it directly; do not call tools only to retrieve these values again (for example the site name, URL, WordPress or PHP version).', 'agent-mod');
                 return implode("\n", $lines);
+        }

agent-mod/trunk/includes/Services/AbilityRegistrarService.php

-              r3770241
+              r3775519
 use WP_Post;
 use WP_Query;
+use WP_Taxonomy;
+use WP_Term;
 use WP_Block_Patterns_Registry;
 use WP_Theme_JSON;
 …
+                        [
                                 'label'               => __('Get Post or Page', 'agent-mod'),
                                 'description'         => __('Returns a post raw block markup as html by post_id, plus its status and custom fields (meta). Use list-posts to find post_id first. For the same text change across many posts use preview-bulk-replace / bulk-replace-content instead of reading each post. The returned html can be modified and passed straight back to update-post as the html parameter. Navigation menus (wp_navigation, referenced by {"ref":ID} in wp:navigation blocks) have dedicated abilities: list-navigations / get-navigation / update-navigation.', 'agent-mod'),
+                                'description'         => __('Returns a post raw block markup as html by post_id, plus its status, custom fields (meta) and assigned taxonomy terms (terms, keyed by taxonomy). Use list-posts to find post_id first. For the same text change across many posts use preview-bulk-replace / bulk-replace-content instead of reading each post. The returned html can be modified and passed straight back to update-post as the html parameter. Navigation menus (wp_navigation, referenced by {"ref":ID} in wp:navigation blocks) have dedicated abilities: list-navigations / get-navigation / update-navigation.', 'agent-mod'),
                                 'category'            => self::CATEGORY,
                                 'execute_callback'    => [$this, 'executeGetPost'],
 …
                                                 'html'      => ['type' => 'string'],
                                                 'meta'      => ['type' => 'object'],
+                                                'terms'     => ['type' => 'object'],
                                                 'error'     => ['type' => 'string'],
                                         ],
 …
+                        [
                                 'label'               => __('Create Post or Page', 'agent-mod'),
                                 'description'         => __('Creates a new post/page. Provide title and optionally html and meta. The html parameter must be complete, valid serialized block markup; it is parsed with parse_blocks() and re-serialized as-is — attribute/innerHTML consistency is NOT validated server-side. Returns the new post_id for use with get-post/update-post.', 'agent-mod'),
+                                'description'         => __('Creates a new post/page. Provide title and optionally html, meta and terms (categories, tags or custom taxonomy terms; create missing terms first with create-terms). The html parameter must be complete, valid serialized block markup; it is parsed with parse_blocks() and re-serialized as-is — attribute/innerHTML consistency is NOT validated server-side. Returns the new post_id for use with get-post/update-post.', 'agent-mod'),
                                 'category'            => self::CATEGORY,
                                 'execute_callback'    => [$this, 'executeCreatePost'],
 …
                                                 ],
                                                 'meta'        => $this->metaWriteSchema(),
+                                                'terms'       => $this->termWriteSchema(),
                                         ],
                                 ],
 …
+                        [
                                 'label'               => __('Update Post or Page', 'agent-mod'),
                                 'description'         => __('Updates a post. Provide post_id plus any of html, title, post_status and meta; fields left out stay unchanged. The html parameter must be complete, valid serialized block markup; it is parsed with parse_blocks() and re-serialized as-is — attribute/innerHTML consistency is NOT validated server-side. To edit a navigation menu (wp_navigation) use update-navigation instead.', 'agent-mod'),
+                                'description'         => __('Updates a post. Provide post_id plus any of html, title, post_status, meta and terms (categories, tags or custom taxonomy terms; create missing terms first with create-terms); fields left out stay unchanged. The html parameter must be complete, valid serialized block markup; it is parsed with parse_blocks() and re-serialized as-is — attribute/innerHTML consistency is NOT validated server-side. To edit a navigation menu (wp_navigation) use update-navigation instead.', 'agent-mod'),
                                 'category'            => self::CATEGORY,
                                 'execute_callback'    => [$this, 'executeUpdatePost'],
 …
                                                 ],
                                                 'meta'        => $this->metaWriteSchema(),
+                                                'terms'       => $this->termWriteSchema(),
                                         ],
                                 ],
 …
                         'html'      => $post->post_content,
                         'meta'      => $this->readPostMeta($post->ID, $input['meta_keys'] ?? null),
+                        'terms'     => $this->readPostTerms($post),
                 ];
+        }
 …
          * Execute callback for agent-mod/create-post.
+         *
          * @param mixed $input Input data (expects 'title', optional 'html', 'post_type', 'post_status', 'meta').
+         * @param mixed $input Input data (expects 'title', optional 'html', 'post_type', 'post_status', 'meta', 'terms').
+         *
          * @return array<string, mixed>
 …
+                }
+                // Term checks need no post, so they run before anything is inserted.
+                $termWrites = $this->prepareTermWrites($postType, $input['terms'] ?? null);
+                if (is_wp_error($termWrites)) {
+                        return ['success' => false, 'error' => $termWrites->get_error_message()];
+                }
                 // Meta capabilities can only be checked against an existing post, so a
+                // post with meta starts as a draft: it can be rolled back without side
+                // effects, and publish-time hooks (SEO, sharing) see the final meta.
+                $hasMeta = ! empty($input['meta']);
+                // post with meta or terms starts as a draft: it can be rolled back without
+                // side effects, and publish-time hooks (SEO, sharing) see the final data.
+                $hasMeta   = ! empty($input['meta']);
+                $deferSave = $hasMeta || ! empty($termWrites);
                 // wp_insert_post() unslashes its input; without wp_slash() the JSON
 …
                                 'post_content' => $serializedContent,
                                 'post_type'    => $postType,
                                 'post_status'  => $hasMeta ? 'draft' : $postStatus,
+                                'post_status'  => $deferSave ? 'draft' : $postStatus,
                         ]),
                         true
 …
                 $postId = (int) $result;
                 if ($hasMeta) {
                         $metaWrites = $this->prepareMetaWrites($postId, $input['meta']);
+                if ($deferSave) {
+                        $metaWrites = $this->prepareMetaWrites($postId, $input['meta'] ?? null);
                         if (is_wp_error($metaWrites)) {
                                 wp_delete_post($postId, true);
 …
                         $this->applyMetaWrites($postId, $metaWrites);
+                        // A new post only holds the default terms (e.g. Uncategorized), so
+                        // the requested terms always replace them.
+                        $termError = $this->applyTermWrites($postId, $termWrites, false);
+                        if (is_wp_error($termError)) {
+                                wp_delete_post($postId, true);
+                                return ['success' => false, 'error' => $termError->get_error_message()];
+                        }
                         if ('draft' !== $postStatus) {
 …
          * Execute callback for agent-mod/update-post.
+         *
          * @param mixed $input Input data (expects 'post_id' plus any of 'html', 'title', 'post_status', 'meta').
+         * @param mixed $input Input data (expects 'post_id' plus any of 'html', 'title', 'post_status', 'meta', 'terms').
+         *
          * @return array<string, mixed>
 …
                 $hasStatus = ! empty($input['post_status']);
                 $hasMeta   = ! empty($input['meta']);
+                if (! $hasHtml && ! $hasTitle && ! $hasStatus && ! $hasMeta) {
+                        return ['success' => false, 'error' => __('Nothing to update: provide at least one of html, title, post_status or meta.', 'agent-mod')];
+                $hasTerms  = ! empty($input['terms']);
+                if (! $hasHtml && ! $hasTitle && ! $hasStatus && ! $hasMeta && ! $hasTerms) {
+                        return ['success' => false, 'error' => __('Nothing to update: provide at least one of html, title, post_status, meta or terms.', 'agent-mod')];
+                }
 …
+                }
+                // Meta first, so publish-time hooks fired by a status change see it.
+                $termWrites = $this->prepareTermWrites($post->post_type, $input['terms'] ?? null);
+                if (is_wp_error($termWrites)) {
+                        return ['success' => false, 'error' => $termWrites->get_error_message()];
+                }
+                // Meta and terms first, so publish-time hooks fired by a status change see them.
                 $this->applyMetaWrites($postId, $metaWrites);
+                $termError = $this->applyTermWrites($postId, $termWrites, true);
+                if (is_wp_error($termError)) {
+                        return ['success' => false, 'error' => $termError->get_error_message()];
+                }
                 if (count($updateArgs) > 1) {
 …
         /**
+         * Input schema shared by the create-post and update-post terms parameter.
+         *
+         * Term references are strings so one fixed item type works with every
+         * provider; numeric strings are read as term IDs.
+         *
+         * @return array<string, mixed>
+         * @since 1.3.4
+         */
+        private function termWriteSchema(): array
+        {
+                return [
+                        'type'        => 'array',
+                        'description' => __('Optional. Taxonomy terms (categories, tags, custom taxonomies) to assign, one item per taxonomy. Terms must already exist: create missing ones first with create-terms. Taxonomies left out keep their current terms.', 'agent-mod'),
+                        'items'       => [
+                                'type'       => 'object',
+                                'required'   => ['taxonomy', 'terms'],
+                                'properties' => [
+                                        'taxonomy' => [
+                                                'type'        => 'string',
+                                                'description' => __('Taxonomy slug, e.g. "category", "post_tag" or a custom taxonomy from list-taxonomies.', 'agent-mod'),
+                                        ],
+                                        'terms'    => [
+                                                'type'        => 'array',
+                                                'items'       => ['type' => 'string'],
+                                                'description' => __('Term IDs (as strings, e.g. "12"), slugs or names. Replaces the post\'s terms in this taxonomy; an empty list removes them all.', 'agent-mod'),
+                                        ],
+                                        'append'   => [
+                                                'type'        => 'boolean',
+                                                'description' => __('update-post only. true adds the terms and keeps the existing ones instead of replacing them. Default false.', 'agent-mod'),
+                                        ],
+                                ],
+                        ],
+                ];
+        }
+        /**
+         * Validates term write items and resolves every term reference to an ID.
+         *
+         * Nothing is written here, so callers can reject the whole request before
+         * touching the post. Missing terms are never created: wp_set_object_terms()
+         * would silently add a new term for any unknown name.
+         *
+         * @param string $postType Post type the terms are assigned to.
+         * @param mixed  $items    The 'terms' ability input.
+         *
+         * @return array<int, array{taxonomy: string, term_ids: int[], append: bool}>|WP_Error
+         * @since 1.3.4
+         */
+        private function prepareTermWrites(string $postType, $items)
+        {
+                if (empty($items)) {
+                        return [];
+                }
+                if (! is_array($items)) {
+                        return new WP_Error('invalid_terms', __('terms must be a list of {taxonomy, terms} objects.', 'agent-mod'));
+                }
+                $writes = [];
+                foreach ($items as $item) {
+                        $slug     = is_array($item) && isset($item['taxonomy']) ? sanitize_key((string) $item['taxonomy']) : '';
+                        $taxonomy = '' !== $slug ? get_taxonomy($slug) : false;
+                        if (! $taxonomy instanceof WP_Taxonomy) {
+                                return new WP_Error(
+                                        'invalid_terms',
+                                        /* translators: %s: taxonomy slug */
+                                        sprintf(__('The taxonomy "%s" is not registered on this site. Call list-taxonomies to see the available slugs.', 'agent-mod'), $slug)
+                                );
+                        }
+                        if (! is_object_in_taxonomy($postType, $taxonomy->name)) {
+                                return new WP_Error(
+                                        'invalid_terms',
+                                        /* translators: 1: taxonomy slug, 2: post type slug */
+                                        sprintf(__('The taxonomy "%1$s" is not registered for the post type "%2$s".', 'agent-mod'), $taxonomy->name, $postType)
+                                );
+                        }
+                        if (isset($writes[$taxonomy->name])) {
+                                return new WP_Error(
+                                        'invalid_terms',
+                                        /* translators: %s: taxonomy slug */
+                                        sprintf(__('The taxonomy "%s" is listed more than once. Put all of its terms in a single item.', 'agent-mod'), $taxonomy->name)
+                                );
+                        }
+                        if (! current_user_can($taxonomy->cap->assign_terms)) {
+                                return new WP_Error(
+                                        'terms_forbidden',
+                                        /* translators: %s: taxonomy slug */
+                                        sprintf(__('You are not allowed to assign terms in the "%s" taxonomy.', 'agent-mod'), $taxonomy->name)
+                                );
+                        }
+                        if (! isset($item['terms']) || ! is_array($item['terms'])) {
+                                return new WP_Error(
+                                        'invalid_terms',
+                                        /* translators: %s: taxonomy slug */
+                                        sprintf(__('The "%s" item needs a terms list (an empty list removes all of its terms).', 'agent-mod'), $taxonomy->name)
+                                );
+                        }
+                        $termIds = [];
+                        $missing = [];
+                        foreach ($item['terms'] as $reference) {
+                                if (! is_scalar($reference) || '' === trim((string) $reference)) {
+                                        continue;
+                                }
+                                $termId = $this->resolveTermReference(trim((string) $reference), $taxonomy->name);
+                                if (null === $termId) {
+                                        $missing[] = (string) $reference;
+                                        continue;
+                                }
+                                $termIds[] = $termId;
+                        }
+                        if (! empty($missing)) {
+                                return new WP_Error(
+                                        'terms_not_found',
+                                        sprintf(
+                                                /* translators: 1: comma-separated term references, 2: taxonomy slug */
+                                                __('These terms do not exist in the "%2$s" taxonomy: %1$s. Check them with list-terms, or create them first with create-terms.', 'agent-mod'),
+                                                implode(', ', $missing),
+                                                $taxonomy->name
+                                        )
+                                );
+                        }
+                        $writes[$taxonomy->name] = [
+                                'taxonomy' => $taxonomy->name,
+                                'term_ids' => array_values(array_unique($termIds)),
+                                'append'   => ! empty($item['append']),
+                        ];
+                }
+                return array_values($writes);
+        }
+        /**
+         * Resolves a term reference (ID, slug or name) to a term ID.
+         *
+         * A numeric reference is tried as an ID first, then as a slug, so numeric
+         * slugs such as a "2024" tag still resolve.
+         *
+         * @param string $reference Term ID, slug or name.
+         * @param string $taxonomy  Taxonomy slug.
+         *
+         * @return int|null Null when no term matches.
+         * @since 1.3.4
+         */
+        private function resolveTermReference(string $reference, string $taxonomy): ?int
+        {
+                if (ctype_digit($reference)) {
+                        $term = get_term((int) $reference, $taxonomy);
+                        if ($term instanceof WP_Term) {
+                                return (int) $term->term_id;
+                        }
+                }
+                $term = get_term_by('slug', sanitize_title($reference), $taxonomy);
+                if (! $term instanceof WP_Term) {
+                        $term = get_term_by('name', sanitize_text_field($reference), $taxonomy);
+                }
+                return $term instanceof WP_Term ? (int) $term->term_id : null;
+        }
+        /**
+         * Saves term writes validated by prepareTermWrites().
+         *
+         * @param int                                                              $postId      Post ID.
+         * @param array<int, array{taxonomy: string, term_ids: int[], append: bool}> $writes      Validated writes.
+         * @param bool                                                             $allowAppend Whether the items' append flag is honoured.
+         *
+         * @return WP_Error|null Null on success.
+         * @since 1.3.4
+         */
+        private function applyTermWrites(int $postId, array $writes, bool $allowAppend): ?WP_Error
+        {
+                foreach ($writes as $write) {
+                        // Integer IDs: wp_set_object_terms() reads strings as term names.
+                        $result = wp_set_object_terms($postId, $write['term_ids'], $write['taxonomy'], $allowAppend && $write['append']);
+                        if (is_wp_error($result)) {
+                                return $result;
+                        }
+                }
+                return null;
+        }
+        /**
+         * Reads the terms assigned to a post for get-post, keyed by taxonomy.
+         *
+         * Only taxonomies an editor can see (public or shown in the admin UI) are
+         * listed, which keeps internal ones such as wp_theme out of the result.
+         * Taxonomies with no terms are listed empty, so the agent also learns
+         * which taxonomies it can assign.
+         *
+         * @param WP_Post $post Post.
+         *
+         * @return array<string, array<int, array{id: int, name: string, slug: string}>>
+         * @since 1.3.4
+         */
+        private function readPostTerms(WP_Post $post): array
+        {
+                $result = [];
+                foreach (get_object_taxonomies($post->post_type, 'objects') as $taxonomy) {
+                        if (! $taxonomy->public && ! $taxonomy->show_ui) {
+                                continue;
+                        }
+                        $terms = get_the_terms($post, $taxonomy->name);
+                        $result[$taxonomy->name] = is_array($terms)
+                                ? array_map(static function (WP_Term $term): array {
+                                        return ['id' => (int) $term->term_id, 'name' => $term->name, 'slug' => $term->slug];
+                                }, $terms)
+                                : [];
+                }
+                return $result;
+        }
+        /**
          * Builds the get-post / update-post error for a missing post or a post_type mismatch.
+         *

agent-mod/trunk/includes/Services/AskUserAbilityService.php

-              r3770241
+              r3775519
 use WP_Error;
+use AgentMod\Common\Constants;
 defined('ABSPATH') || exit;
 …
          * @since 1.3.1
          */
         private const CATEGORY = 'agent-mod';
+        private const CATEGORY = Constants::SYSTEM_ABILITY_CATEGORY;
         /**
 …
                 $this->settings = $settings;
+                add_action('wp_abilities_api_categories_init', [$this, 'registerCategories']);
                 add_action('wp_abilities_api_init', [$this, 'registerAbilities']);
+        }
+        /**
+         * Registers the system ability category.
+         *
+         * Shared with agent-mod/find-abilities (FindAbilitiesAbilityService).
+         *
+         * @return void
+         * @since 1.3.4
+         */
+        public function registerCategories(): void
+        {
+                if (! function_exists('wp_register_ability_category')) {
+                        return;
+                }
+                wp_register_ability_category(
+                        Constants::SYSTEM_ABILITY_CATEGORY,
+                        [
+                                'label'       => __('AgentMod — System', 'agent-mod'),
+                                'description' => __('Tools that are part of how the AgentMod agent works, such as asking the user questions, requesting approval and finding other abilities. AgentMod offers them automatically when they apply; they are never selected per agent.', 'agent-mod'),
+                        ]
+                );
+        }

agent-mod/trunk/includes/Services/SettingsService.php

-              r3770241
+              r3775519
         /**
+         * Ability source of the settings-based (default) agent.
+         *
+         * Always 'all' since dynamic tool loading: the agent finds the abilities it
+         * needs itself, so the settings page no longer offers a selection. A saved
+         * 'selected' value from earlier versions is ignored on purpose. Agents that
+         * carry their own ability list (e.g. PRO agents) still pass it explicitly.
+         *
          * @return string
          * @since 1.1.0
 …
         public function getAbilitySource(): string
+        {
+                $saved = trim((string) ($this->getSettings()['agent_mod_abilities']['ability_source'] ?? ''));
+                $value = '' !== $saved ? $saved : 'all';
+                return (string) $value;
+        }
+        /**
+                return 'all';
+        }
+        /**
+         * Allowed abilities of the settings-based (default) agent.
+         *
+         * Always empty: see getAbilitySource(). Returning the stale saved list would
+         * let a selection the settings page no longer shows leak into agents that
+         * fall back to it.
+         *
          * @return string[]
          * @since 1.1.0
 …
         public function getAllowedAbilities(): array
+        {
+                $saved = $this->getSettings()['agent_mod_abilities']['allowed_abilities'] ?? [];
+                return is_array($saved) ? $saved : [];
+                return [];
+        }
+        /**
+         * Tool loading strategy: 'dynamic' or 'all'.
+         *
+         * @return string
+         * @since 1.3.4
+         */
+        public function getToolLoading(): string
+        {
+                $saved = (string) ($this->getSettings()['agent_mod_abilities']['tool_loading'] ?? '');
+                return in_array($saved, ['dynamic', 'all'], true) ? $saved : Constants::AI_TOOL_LOADING;
+        }

agent-mod/trunk/readme.txt

-              r3770241
+              r3775519
 Tested up to: 7.1
 Requires PHP: 7.4
 Stable tag: 1.3.3
+Stable tag: 1.3.4
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
 …
 == Changelog ==
+= 1.3.4 =
+* Added: Dynamic tool loading, the new default. Instead of sending every ability with every request, the agent starts with a few tools and loads the abilities a task needs through the new `agent-mod/find-abilities` tool; what it finds stays available for the rest of the run, and tools used in the recent messages are loaded up front. On a site with about 100 abilities, the tool definitions sent with each request drop from about 23,000 to about 1,100 tokens, so even a "hello" costs a fraction of what it did. Write confirmation, auto-approval and the read-only rule of Ask and Plan modes work exactly as before. Agents with 15 or fewer abilities still get all of them up front. The new "Tool Loading" setting (Settings > Abilities) switches back to sending every ability.
+* Changed: The "Ability Source" and "Allowed Abilities" settings are removed. The default agent can use every ability and finds the ones it needs; a selection saved in an earlier version is no longer applied.
+* Changed: AgentMod's own chat tools (`ask-user`, `present-plan`, `request-approval`, `find-abilities`) moved to a separate "AgentMod — System" ability category. They are offered automatically where they apply and are no longer part of ability selections, where selecting or leaving them out never had an effect.
+* Fixed: The MCP Adapter plugin's abilities (`discover-abilities`, `get-ability-info`, `execute-ability`) are no longer offered to the agent. `execute-ability` could run any other ability under its own name, so the confirmation dialog showed "execute-ability" instead of the actual action, and a session approval for it covered every ability.
+* Added: `create-post` and `update-post` can assign taxonomy terms (categories, tags and custom taxonomies) with the new `terms` parameter, one item per taxonomy. Terms are given by ID, slug or name and replace the post's terms in that taxonomy; an empty list removes them, and `append: true` on `update-post` adds to the existing ones. Taxonomies left out keep their terms. Missing terms are never created on the fly: the call fails and points to `create-terms`. The taxonomy, the post type and the user's permission to assign terms are checked before anything is saved, and terms are set before a post is published so publish-time hooks see them. Previously the agent could create terms but had no way to attach them to a post.
+* Improved: `get-post` returns the post's assigned terms, grouped by taxonomy, including the taxonomies that have none, so the agent can see what is assigned and which taxonomies it can use.
+* Improved: Older tool results are compacted only when the conversation grows large. Before, everything except the last four tool results was cut to a short stub on every step, even in a short run, so the agent lost data it had just fetched (for example a post type's custom field configuration) and had to ask for it or fetch it again. Now nothing is compacted until the history reaches about 80,000 tokens; it is then reduced to about 40,000, and the six most recent results are always kept in full.
+* Improved: Compaction keeps the already compacted part of the history unchanged until the next compaction, so the providers' prompt cache (OpenAI, Gemini) is reused across steps instead of being invalidated on every step.
+* Improved: A compacted nested result, such as a field configuration (sections, fields, sub-fields), keeps its structure (names, types, labels, options) instead of only its first 200 characters. The same summary is passed on to the following messages.
+* Improved: Native Custom Fields configuration reads (`get-post-meta-fields`, `get-term-meta-fields`, `get-user-meta-fields`, `get-options-page`) are never compacted, and are passed on to the following messages with a larger summary.
+* Fixed: A read-only tool whose earlier result had been compacted could not be called again, because the repeat guard counted it as an identical call. The agent then had neither the data nor a way to get it back. Such a call now runs again.
+* Fixed: With "Enable site context" on, the agent still called `get-site-info` and `get-environment-info` on every request to fetch values that were already in the site context. The site context now includes the PHP version and tells the agent to use these values directly, and the default system prompt no longer asks for a tool call when the answer is already in the site context or the conversation.
 = 1.3.3 =
 * Added: Bulk text replace in posts. `preview-bulk-replace` (read-only) shows, for up to 100 posts at once, how many matches each post has with a before / after snippet, without saving anything. `bulk-replace-content` then applies the same change on the server; changed posts get a revision when their post type supports revisions. Literal text or regular expressions, an optional limit per post (e.g. only the leading label), case-insensitive matching that handles the Turkish i / ı / İ / I, and by default only the visible text is changed, never block comments or attributes. A change that would alter the block structure skips that post. Previously a task such as "remove the 'Short bio:' label from these 12 posts" needed a get-post and an update-post per post, and ran into the full-content read limit and the tool-call limit.

Note: See TracChangeset for help on using the changeset viewer.

Plugin Directory