@animalabs/agent-framework 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -32,6 +32,7 @@
     "typecheck": "tsc --noEmit",
     "pretest": "mkdir -p dist/test/fixtures && cp test/fixtures/*.mjs dist/test/fixtures/",
     "test": "node --test --test-force-exit dist/test/*.test.js",
+    "version": "node scripts/release-changelog.mjs && git add CHANGELOG.md",
     "prepublishOnly": "npm run build"
   },
   "keywords": [

package/src/agent.ts

@@ -67,7 +67,7 @@ export class Agent {
   /** Refusal auto-rewind policy (see AgentConfig.refusalHandling). */
   readonly refusalHandling: AgentConfig['refusalHandling'];
   /** Prose delivery mode (see AgentConfig.proseRouting). Default 'locus'. */
-  readonly proseRouting: 'locus' | 'explicit';
+  readonly proseRouting: 'locus' | 'explicit' | 'hybrid';
   /** Prompt-cache TTL forwarded to the provider (see AgentConfig.cacheTtl). */
   readonly cacheTtl: NonNullable<AgentConfig['cacheTtl']>;
   /** Emit prompt-cache markers on requests (see AgentConfig.promptCaching). */

package/src/framework.ts

@@ -62,7 +62,7 @@ import { computeGrant, CapabilityGrant, expandAdvertisementShorthand } from './m
 import { maskNegotiatedCapabilities } from './mcpl/capability-mask.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler, type McplPushEvent } from './mcpl/push-handler.js';
-import { parseProsePrefix } from './mcpl/prose-grammar.js';
+import { parseProsePrefix, parseHybridProsePrefix } from './mcpl/prose-grammar.js';
 import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry, type ChannelToolOrigin } from './mcpl/channel-registry.js';
@@ -126,6 +126,9 @@ const SILENCING_TOOLS = new Set([
   'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
 ]);
 
+/** World-surface publication names that outrank hybrid prose envelopes. */
+const HYBRID_PUBLICATION_TOOLS = new Set(['say', 'whisper']);
+
 /**
  * True when an injected message is real conversational input — something the
  * agent might actually be replying to — rather than ambient machinery.
@@ -225,11 +228,18 @@ const isAddressedMessage = (
 // envelopes can never disagree on what is a prefix.
 
 /** One-time primer appended when an agent's proseRouting mode changes. */
-function proseModePrimer(mode: 'explicit' | 'locus'): string {
+function proseModePrimer(mode: 'explicit' | 'hybrid' | 'locus'): string {
   if (mode === 'locus') {
     return '[prose-routing] Mode change: your plain text auto-routes to the ' +
       'conversational locus again. `>>` destination prefixes are no longer needed.';
   }
+  if (mode === 'hybrid') {
+    return '[prose-routing] Hybrid routing enabled: unprefixed text still lands in the ' +
+      'current conversational locus. A leading `>>>destination` envelope instead routes ' +
+      'that prose to one uniquely resolved authorized Discord or Eidoverse channel. The ' +
+      'envelope remains in your memory but recipients see only its body; delivery or failure ' +
+      'is reported back to you.';
+  }
   // Deliberately terse: a short event-style notice is classifier-safe from
   // the user role (ablation D, 2026-07-24), while the full grammar as a user
   // message drew a deterministic reasoning_extraction refusal (ablation A/B).
@@ -329,7 +339,7 @@ function validateUtilityArgs(
 }
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
-import { EventGate } from './gate/event-gate.js';
+import { EventGate, formatShadowWarning } from './gate/event-gate.js';
 import { UsageTracker, type PersistedUsageState } from './usage/usage-tracker.js';
 import type { SessionUsageSnapshot, UsageUpdatedEvent } from './usage/types.js';
 import type { McplServerConnection } from './mcpl/server-connection.js';
@@ -684,6 +694,8 @@ export class AgentFramework {
   /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
    *  Cleared at every non-restart turn start; survives context restarts. */
   private proseTargetPins: Map<string, string> = new Map();
+  /** Hybrid router is fail-closed after a malformed/unresolved envelope until a new valid target. */
+  private proseHybridSuppressed: Set<string> = new Set();
   /** Agents whose current turn requested `!` continuation — re-woken when the
    *  turn completes instead of pausing until the next external event. */
   private proseContinuations: Set<string> = new Set();
@@ -1968,12 +1980,14 @@ export class AgentFramework {
   /**
    * Add or replace (upsert) a gate policy at runtime. Validated and persisted
    * to gate.json; hot-applied in memory. Throws if no gate is configured or the
-   * policy is invalid. `position: 'prepend'` puts a wake rule ahead of broad
-   * defer/debounce rules (first match wins).
+   * policy is invalid. Placement: `'prepend'` puts a rule ahead of EVERYTHING
+   * (including addressed-message wake rules — see EventGate.lintShadows);
+   * `{before: name}` / `{after: name}` anchor it against a specific rule,
+   * which is usually what a sampler or debounce actually wants.
    */
   addGatePolicy(
     rawPolicy: unknown,
-    options?: { position?: 'append' | 'prepend' },
+    options?: { position?: 'append' | 'prepend' | { before: string } | { after: string } },
   ): import('./gate/types.js').GatePolicy {
     if (!this.eventGate) {
       throw new Error('No EventGate configured (FrameworkConfig.gate is unset).');
@@ -2350,9 +2364,17 @@ export class AgentFramework {
       description:
         'Add or replace a wake rule (a gate.json policy) at runtime — no need to ' +
         'hand-edit the file. The rule is validated and hot-applied immediately. ' +
-        'A rule with the same `name` replaces the existing one in place. Use ' +
-        '`position: "prepend"` to put a wake rule ahead of broad defer/debounce ' +
-        'rules (first match wins). Two common shapes:\n' +
+        'A rule with the same `name` replaces the existing one in place (add a ' +
+        'position to move it). ⚠️ ORDERING IS SEMANTICS: first match wins, and a ' +
+        'matched rule CONSUMES the event — a broad rule placed early makes every ' +
+        'later rule unreachable for its scope, including your addressed-message ' +
+        '(DM/mention) wake rules. Prefer `insertBefore`/`insertAfter` to place a ' +
+        'rule relative to a specific existing rule; use `position: "prepend"` only ' +
+        'when the rule really must beat EVERYTHING. For "additionally wake me ' +
+        'every Nth event / at most N per hour" governors, set `passthrough: true` ' +
+        'so non-firing matches fall through to your normal rules instead of ' +
+        'swallowing them. The result includes a before/after probe table and any ' +
+        'shadow warnings — READ THEM before ending the turn. Two common shapes:\n' +
         '• Watch a FILE/workspace path: match on `mount` + `pathGlob`, e.g. ' +
         '`{ name: "watch-notes", match: { scope: ["workspace:modified"], mount: "project", pathGlob: "notes/*.md" }, behavior: "always" }`.\n' +
         '• Watch a CHANNEL: match on `source` + `channel` (and/or `tagsAny: ["chat:ambient"]`), ' +
@@ -2420,7 +2442,30 @@ export class AgentFramework {
           position: {
             type: 'string',
             enum: ['append', 'prepend'],
-            description: 'Where to insert a NEW rule (ignored when replacing by name). Default "append".',
+            description:
+              'Coarse placement. "append" (default) adds at the end; "prepend" puts the rule ' +
+              'ahead of EVERYTHING — including addressed-message wake rules — so prefer ' +
+              'insertBefore/insertAfter unless the rule really must beat every other rule. ' +
+              'When replacing an existing name, giving any placement MOVES the rule there; ' +
+              'omit all placement fields to update it in place.',
+          },
+          insertBefore: {
+            type: 'string',
+            description:
+              'Insert the rule immediately BEFORE the named existing rule (error if absent). ' +
+              'The safe way to order against a specific catch-all, e.g. insertBefore: "discord-ambient".',
+          },
+          insertAfter: {
+            type: 'string',
+            description: 'Insert the rule immediately AFTER the named existing rule (error if absent).',
+          },
+          passthrough: {
+            type: 'boolean',
+            description:
+              'Observer semantics for rateLimit/passiveSample rules: when the rule matches but ' +
+              'does not fire (below N, bucket empty), the event FALLS THROUGH to later rules ' +
+              'instead of being consumed. Use for "additionally wake me every Nth event" ' +
+              'governors so they never swallow DM/mention wakes.',
           },
           resets: {
             type: 'array',
@@ -5110,6 +5155,97 @@ export class AgentFramework {
     }
   }
 
+  /** Locus-preserving explicit publication. Source remains byte-identical in Chronicle. */
+  private async deliverHybridProse(
+    agent: Agent,
+    rawText: string,
+    locus: string | null,
+    allowLocus: boolean,
+  ): Promise<void> {
+    const lines = rawText.split('\n');
+    const envelopes: string[] = [];
+    let current: string[] = [];
+    for (const line of lines) {
+      if (line.trimStart().startsWith('>>>') && current.length > 0) {
+        envelopes.push(current.join('\n'));
+        current = [];
+      }
+      current.push(line);
+    }
+    if (current.length > 0) envelopes.push(current.join('\n'));
+
+    for (const envelope of envelopes) {
+      if (!envelope.trim()) continue;
+      const normalized = envelope.replace(/^\s+(?=>>>)/, '');
+      const attempted = normalized.startsWith('>>>');
+      const parsed = parseHybridProsePrefix(normalized);
+      if (parsed.continueTurn) this.proseContinuations.add(agent.name);
+      if (parsed.kind === 'private') {
+        this.proseTargetPins.delete(agent.name);
+        this.proseHybridSuppressed.add(agent.name);
+        console.error(`[prose] ${agent.name}: >>>skip_reply — ${parsed.body.length} chars kept in context (not sent)`);
+        continue;
+      }
+      if (parsed.kind === 'target') {
+        const resolved = this.channelRegistry!.resolveProseTarget(parsed.target!);
+        if ('error' in resolved) {
+          this.proseTargetPins.delete(agent.name);
+          this.proseHybridSuppressed.add(agent.name);
+          this.bounceProse(agent, parsed.body, resolved.error, resolved.candidates, '>>>');
+          continue;
+        }
+        let body = parsed.body;
+        const usedClipboard = body.includes('{{unsent}}');
+        if (usedClipboard) body = body.replaceAll('{{unsent}}', this.proseClipboards.get(agent.name) ?? '');
+        this.proseTargetPins.set(agent.name, resolved.channelId);
+        this.proseHybridSuppressed.delete(agent.name);
+        if (!body.trim()) {
+          console.error(`[prose] ${agent.name}: >>>${parsed.target} established target; empty body — nothing sent yet`);
+          continue;
+        }
+        try {
+          const outcome = await this.channelRegistry!.routeSpeech(agent.name, body, resolved.channelId);
+          this.recordProseDelivery(agent.name, outcome);
+          if (outcome?.delivered) {
+            this.proseBounceStreaks.delete(agent.name);
+            if (usedClipboard) this.proseClipboards.delete(agent.name);
+          } else {
+            this.proseTargetPins.delete(agent.name);
+            this.proseHybridSuppressed.add(agent.name);
+            this.bounceProse(agent, parsed.body, `delivery to ${resolved.channelId} was not confirmed`, undefined, '>>>');
+          }
+        } catch (err) {
+          this.proseTargetPins.delete(agent.name);
+          this.proseHybridSuppressed.add(agent.name);
+          this.bounceProse(agent, parsed.body, `delivery to ${resolved.channelId} failed: ${err instanceof Error ? err.message : String(err)}`, undefined, '>>>');
+        }
+        continue;
+      }
+      if (attempted) {
+        this.proseTargetPins.delete(agent.name);
+        this.proseHybridSuppressed.add(agent.name);
+        this.bounceProse(agent, normalized, 'malformed >>> routing envelope: destination is missing', undefined, '>>>');
+        continue;
+      }
+      if (this.proseHybridSuppressed.has(agent.name)) {
+        this.recordProseSuppression(agent.name, 1);
+        continue;
+      }
+      const sticky = this.proseTargetPins.get(agent.name);
+      if (!allowLocus && !sticky) {
+        this.recordProseSuppression(agent.name, 1);
+        continue;
+      }
+      const target = sticky ?? locus;
+      try {
+        const outcome = await this.channelRegistry!.routeSpeech(agent.name, envelope, target);
+        this.recordProseDelivery(agent.name, outcome);
+      } catch (err) {
+        console.error('hybrid locus delivery failed:', err);
+      }
+    }
+  }
+
   private async deliverProseEnvelope(agent: Agent, rawText: string): Promise<void> {
     const name = agent.name;
     const parsed = parseProsePrefix(rawText);
@@ -5169,7 +5305,7 @@ export class AgentFramework {
   /** Cap on consecutive bounce-triggered wakes (notices still append after). */
   private static readonly PROSE_BOUNCE_WAKE_CAP = 2;
 
-  private bounceProse(agent: Agent, text: string, reason: string, candidates?: string[]): void {
+  private bounceProse(agent: Agent, text: string, reason: string, candidates?: string[], prefix: '>>' | '>>>' = '>>'): void {
     const name = agent.name;
     this.proseClipboards.set(name, text);
     const streak = (this.proseBounceStreaks.get(name) ?? 0) + 1;
@@ -5178,8 +5314,9 @@ export class AgentFramework {
     const notice =
       `[prose-routing] Your text (${text.length} chars) was not delivered — ${reason}.${cand} ` +
       'The text is retained; nothing is lost. To deliver it unchanged, reply with a ' +
-      'destination plus the token {{unsent}}, e.g. ">>#channel {{unsent}}" or ">>@person {{unsent}}". ' +
-      '">>skip_reply {{unsent}}" keeps it in context only. The prose_help tool shows the full syntax.';
+      `destination plus the token {{unsent}}, e.g. "${prefix}#channel {{unsent}}" or "${prefix}@person {{unsent}}". ` +
+      `"${prefix}skip_reply {{unsent}}" keeps it in context only.` +
+      (prefix === '>>' ? ' The prose_help tool shows the full syntax.' : '');
     try {
       // Through framework.addMessage, NOT the context manager directly: while
       // the turn is still streaming this defers the notice to the next tool
@@ -5381,6 +5518,8 @@ export class AgentFramework {
       this.turnEngagedChannels.delete(agent.name);
       this.turnProseDeliveries.delete(agent.name);
       this.turnProseSuppressed.delete(agent.name);
+      this.proseHybridSuppressed.delete(agent.name);
+      if (agent.proseRouting === 'hybrid') this.proseTargetPins.delete(agent.name);
       if (agent.proseRouting === 'explicit') {
         // Explicit prose routing: there is no locus. The model names every
         // destination in-band (`>>` prefixes); the only turn state is the
@@ -5649,7 +5788,7 @@ export class AgentFramework {
     });
     const proseStream = this.channelRegistry
       ? new ProseStreamRouter({
-          mode: agent.proseRouting === 'explicit' ? 'explicit' : 'locus',
+          mode: agent.proseRouting === 'explicit' ? 'explicit' : agent.proseRouting === 'hybrid' ? 'hybrid' : 'locus',
           initialTarget: typingChannel,
           resolve: (spec) => {
             const r = this.channelRegistry!.resolveProseTarget(spec);
@@ -5776,9 +5915,18 @@ export class AgentFramework {
               const rawXml = rawText && /^<(antml:)?function_calls>/.test(rawText)
                 ? rawText
                 : undefined;
+              // Persist THIS round's text only. `roundPreamble` (membrane
+              // ≥0.5.79) is the per-round delta; the legacy `preamble` is
+              // CUMULATIVE in XML mode — persisting it per round stored each
+              // round's text N times and re-persisted injected
+              // <function_results> as the agent's own words (the Evander
+              // 2026-08-08 scaffold-leak pyramid: r1 ×3, r2 ×2).
+              const roundText =
+                (event.context as { roundPreamble?: string }).roundPreamble ??
+                event.context.preamble;
               assistantBlocks = [];
-              if (event.context.preamble) {
-                assistantBlocks.push({ type: 'text', text: event.context.preamble });
+              if (roundText) {
+                assistantBlocks.push({ type: 'text', text: roundText });
               }
               for (const c of event.calls) {
                 assistantBlocks.push({
@@ -5820,14 +5968,28 @@ export class AgentFramework {
               const hasSameRoundPrivateThink =
                 roundToolNames.includes('think') &&
                 requestSnapshot.sameRoundThinkTextPolicy === 'private';
-              if (roundToolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)))) {
+              if (roundToolNames.some((n) =>
+                SILENCING_TOOLS.has(bareToolName(n)) ||
+                (agent.proseRouting === 'hybrid' && HYBRID_PUBLICATION_TOOLS.has(bareToolName(n)))
+              )) {
                 turnSilenced = true;
               }
               if (roundContent && roundContent.length > 0) {
                 liveProseRouting = true;
                 const roundSegments = splitProseSegments(assistantBlocks);
                 if (roundSegments.length > 0) {
-                  if (agent.proseRouting === 'explicit') {
+                  if (agent.proseRouting === 'hybrid') {
+                    if (turnSilenced) {
+                      this.recordProseSuppression(agent.name, roundSegments.length);
+                    } else if (!hasSameRoundPrivateThink) {
+                      const locus = resolveTurnLocus();
+                      for (const seg of roundSegments) {
+                        turnSpeechChain = turnSpeechChain
+                          .then(() => this.deliverHybridProse(agent, seg, locus, true))
+                          .catch((err) => console.error('mid-turn hybrid prose delivery failed:', err));
+                      }
+                    }
+                  } else if (agent.proseRouting === 'explicit') {
                     // Explicit mode: every segment through the prose gateway.
                     // Silencing does not apply — unprefixed prose bounces and
                     // prefixed prose is deliberate; think-privacy still holds.
@@ -6157,7 +6319,15 @@ export class AgentFramework {
                 .join('\n')
                 .trim();
               if (speechText) {
-                if (agent.proseRouting === 'explicit') {
+                if (agent.proseRouting === 'hybrid') {
+                  const locus = resolveTurnLocus();
+                  console.error(`[prose] ${agent.name}: text-only turn -> hybrid prose gateway`);
+                  try {
+                    await this.deliverHybridProse(agent, speechText, locus, true);
+                  } catch (err) {
+                    console.error('text-only hybrid prose delivery failed:', err);
+                  }
+                } else if (agent.proseRouting === 'explicit') {
                   console.error(`[prose] ${agent.name}: text-only turn -> prose gateway`);
                   try {
                     await this.deliverProse(agent, speechText);
@@ -6204,7 +6374,10 @@ export class AgentFramework {
                 .filter((n): n is string => typeof n === 'string');
               const silenced = liveProseRouting
                 ? turnSilenced
-                : turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)));
+                : turnSilenced || toolNames.some((n) =>
+                  SILENCING_TOOLS.has(bareToolName(n)) ||
+                  (agent.proseRouting === 'hybrid' && HYBRID_PUBLICATION_TOOLS.has(bareToolName(n)))
+                );
 
               const segments = splitProseSegments(liveProseRouting ? terminalContent : response.content);
 
@@ -6213,7 +6386,20 @@ export class AgentFramework {
               // the chain may still be flushing earlier rounds' posts.
               await turnSpeechChain;
 
-              if (agent.proseRouting === 'explicit') {
+              if (agent.proseRouting === 'hybrid') {
+                if (silenced && segments.length > 0) {
+                  this.recordProseSuppression(agent.name, segments.length);
+                } else if (segments.length > 0) {
+                  const locus = resolveTurnLocus();
+                  for (const seg of segments) {
+                    try {
+                      await this.deliverHybridProse(agent, seg, locus, true);
+                    } catch (err) {
+                      console.error('trailing hybrid prose delivery failed:', err);
+                    }
+                  }
+                }
+              } else if (agent.proseRouting === 'explicit') {
                 if (segments.length > 0) {
                   console.error(
                     `[prose] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> ${segments.length} trailing segment(s) via prose gateway`,
@@ -7075,6 +7261,9 @@ export class AgentFramework {
     const blocks: ContentBlock[] = toolResults.map(tc => ({
       type: 'tool_result' as const,
       toolUseId: tc.id,
+      // Persisted so XML replay can reconstruct the legacy <tool_name>
+      // element byte-identically to the live injection.
+      toolName: tc.name,
       content: spilled.get(tc.id)!.text,
       isError: tc.result.isError,
     }));
@@ -7334,7 +7523,7 @@ export class AgentFramework {
   /**
    * Effective tool-result inline cap for an agent, with provenance. Desired
    * value: resident's durable agent_settings value → residence
-   * FrameworkConfig.toolResultInlineMaxChars → house default (5000).
+   * FrameworkConfig.toolResultInlineMaxChars → house default (24000).
    * Effective value: min(desired, strategy bound) for EVERY source — the
    * strategy's per-message safety limit is a ceiling, not a suggestion
    * (Sol's #94 ruling: a durable preference must not be a durable path for
@@ -9960,6 +10149,7 @@ export class AgentFramework {
       // range/shape checks.
       const input = (call.input ?? {}) as {
         name?: unknown; match?: unknown; resets?: unknown; position?: unknown;
+        insertBefore?: unknown; insertAfter?: unknown; passthrough?: unknown;
         behavior?: unknown; debounceMs?: unknown; rateLimit?: unknown; passiveSample?: unknown;
       };
       const behaviorSources = [
@@ -9990,17 +10180,72 @@ export class AgentFramework {
         : input.passiveSample !== undefined ? { passive_sample: input.passiveSample }
         : input.behavior;
 
-      const position = input.position === 'prepend' ? 'prepend' : 'append';
+      // Placement: at most one of position / insertBefore / insertAfter.
+      // With none given, a replaced rule stays where it was and a new rule
+      // appends (addPolicy's contract).
+      const placementSources = [
+        input.position !== undefined ? 'position' : null,
+        input.insertBefore !== undefined ? 'insertBefore' : null,
+        input.insertAfter !== undefined ? 'insertAfter' : null,
+      ].filter((s): s is string => s !== null);
+      if (placementSources.length > 1) {
+        finish({
+          success: false,
+          error: `wake_add_rule: give at most one placement, got [${placementSources.join(', ')}].`,
+          isError: true,
+        });
+        return;
+      }
+      let position: 'append' | 'prepend' | { before: string } | { after: string } | undefined;
+      if (typeof input.insertBefore === 'string' && input.insertBefore) {
+        position = { before: input.insertBefore };
+      } else if (typeof input.insertAfter === 'string' && input.insertAfter) {
+        position = { after: input.insertAfter };
+      } else if (input.position === 'prepend' || input.position === 'append') {
+        position = input.position;
+      }
+
       const rawPolicy = {
         name: input.name,
         match: input.match ?? {},
         behavior,
+        ...(input.passthrough !== undefined ? { passthrough: input.passthrough } : {}),
         ...(input.resets !== undefined ? { resets: input.resets } : {}),
       };
-      const policy = this.addGatePolicy(rawPolicy, { position });
+
+      // Before/after probe table + shadow lint: the moment a rule changes the
+      // evaluation order is the moment its real semantics must be legible
+      // (af#105 — a prepended catch-all sampler silently disabled the
+      // addressed-message wakes for 12h before anyone could see why).
+      const before = new Map(
+        this.eventGate!.probeTable().map((r) => [r.probe, r]),
+      );
+      const policy = this.addGatePolicy(rawPolicy, position ? { position } : undefined);
+      const after = this.eventGate!.probeTable();
+      const probes = after.map((r) => {
+        const prev = before.get(r.probe);
+        const changed = !!prev && (prev.policy !== r.policy || prev.wouldWake !== r.wouldWake);
+        return {
+          probe: r.probe,
+          rule: r.policy ?? '(default)',
+          behavior: r.behavior,
+          wouldWake: r.wouldWake,
+          ...(changed ? { changed: true, was: `${prev!.policy ?? '(default)'} (wouldWake=${prev!.wouldWake})` } : {}),
+        };
+      });
+      const shadowWarnings = this.eventGate!.lintShadows()
+        .map((w) => formatShadowWarning(w));
       finish({
         success: true,
-        data: { added: policy.name, policies: this.getGatePolicyNames() },
+        data: {
+          added: policy.name,
+          policies: this.getGatePolicyNames(),
+          ...(shadowWarnings.length > 0 ? { shadowWarnings } : {}),
+          probes,
+          ...(probes.some((p) => 'changed' in p)
+            ? {}
+            : { note: 'No canonical probe changed its winning rule — the new rule affects none of the common chat/heartbeat shapes, or only channel/path-specific events the probes do not model.' }),
+        },
       });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);