feat: configurable exposure policy for direct, indirect and disabled tools

Introduces ExposurePolicy (option lit_mcp_exposure) deciding per ability
whether it is a direct MCP tool, only reachable via mcp-adapter's
execute-ability meta-tool, or disabled entirely (not registered with the
Abilities API at all). Ability::isDirect() remains the default when no
override applies. lit/guide can never be disabled or made indirect;
lit/media-preview and lit/media-download (image/embedded-resource results)
can never be made indirect, only direct or disabled.

AbilityRegistrar and ServerRegistrar take an optional ExposurePolicy and
use it to filter registered abilities / compute the direct tool list.
IntegrationRegistry::directAbilityNames() is removed (superseded by
ExposurePolicy::directNames()). InstructionsBuilder now also takes the
policy and lists the currently direct tools by name (lit-<name>), noting
the rest are reachable via mcp-adapter-execute-ability as lit/<name>.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7

src/Abilities/AbilityRegistrar.php

@@ -18,7 +18,7 @@ final class AbilityRegistrar
 {
     public const CATEGORY = 'lit-mcp';
 
-    public function __construct(private IntegrationRegistry $registry)
+    public function __construct(private IntegrationRegistry $registry, private ?ExposurePolicy $policy = null)
     {
     }
 
@@ -38,7 +38,8 @@ final class AbilityRegistrar
 
     public function registerAbilities(): void
     {
-        foreach ($this->registry->abilities() as $ability) {
+        $policy = $this->policy ?? new ExposurePolicy();
+        foreach ($policy->enabled($this->registry->abilities()) as $ability) {
             wp_register_ability($ability->name(), $this->argsFor($ability));
         }
     }

src/Abilities/ExposurePolicy.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Abilities;
+
+/**
+ * Decides per ability whether it is a direct MCP tool, only reachable through the
+ * adapter's meta-tools, or disabled (spec §4.3). Ability::isDirect() is the default.
+ */
+final class ExposurePolicy
+{
+    public const OPTION = 'lit_mcp_exposure';
+    public const DIRECT = 'direct';
+    public const INDIRECT = 'indirect';
+    public const DISABLED = 'disabled';
+    public const MODES = [self::DIRECT, self::INDIRECT, self::DISABLED];
+
+    /**
+     * Image/embedded-resource results only work for direct tools (ruling Q6 / task 6
+     * dispatch): lit/media-preview (ImageContent) and lit/media-download (embedded
+     * resource) can be direct or disabled, but never indirect.
+     */
+    public const DIRECT_ONLY = ['lit/media-preview', 'lit/media-download'];
+
+    /** Entry point for every conversation – must always stay a direct tool. */
+    public const REQUIRED = ['lit/guide'];
+
+    /** @param array<string, string> $overrides Ability name => mode. */
+    public function __construct(private array $overrides = [])
+    {
+    }
+
+    public static function fromOption(): self
+    {
+        return new self(self::sanitize(get_option(self::OPTION, [])));
+    }
+
+    public function mode(Ability $ability): string
+    {
+        $mode = $this->overrides[$ability->name()] ?? null;
+
+        return is_string($mode) && self::isAllowed($ability->name(), $mode) ? $mode : $this->defaultMode($ability);
+    }
+
+    public function defaultMode(Ability $ability): string
+    {
+        return $ability->isDirect() ? self::DIRECT : self::INDIRECT;
+    }
+
+    /**
+     * @param list<Ability> $abilities
+     * @return list<Ability>
+     */
+    public function enabled(array $abilities): array
+    {
+        return array_values(array_filter(
+            $abilities,
+            fn (Ability $ability): bool => $this->mode($ability) !== self::DISABLED
+        ));
+    }
+
+    /**
+     * @param list<Ability> $abilities
+     * @return list<string>
+     */
+    public function directNames(array $abilities): array
+    {
+        $names = [];
+        foreach ($abilities as $ability) {
+            if ($this->mode($ability) === self::DIRECT) {
+                $names[] = $ability->name();
+            }
+        }
+
+        return $names;
+    }
+
+    public static function isAllowed(string $name, string $mode): bool
+    {
+        if (! in_array($mode, self::MODES, true)) {
+            return false;
+        }
+
+        if (in_array($name, self::REQUIRED, true)) {
+            return $mode === self::DIRECT;
+        }
+
+        if (in_array($name, self::DIRECT_ONLY, true)) {
+            return $mode !== self::INDIRECT;
+        }
+
+        return true;
+    }
+
+    /**
+     * Settings API sanitize callback for the option.
+     *
+     * @return array<string, string>
+     */
+    public static function sanitize(mixed $input): array
+    {
+        if (! is_array($input)) {
+            return [];
+        }
+
+        $clean = [];
+        foreach ($input as $name => $mode) {
+            if (
+                is_string($name)
+                && is_string($mode)
+                && preg_match('#^[a-z0-9-]+/[a-z0-9-]+$#', $name) === 1
+                && self::isAllowed($name, $mode)
+            ) {
+                $clean[$name] = $mode;
+            }
+        }
+        ksort($clean);
+
+        return $clean;
+    }
+}