@claude-flow/cli 3.32.26 → 3.32.29

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.32.2
+3.32.29

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.32.26",
+    "version": "3.32.29",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "50ea92a72651bdc95634f7588d56a5870963168eef5226f66ed14af3b47c8d9a",
@@ -8,6 +8,6 @@
       "statusline.cjs": "d2a0eac56d1267d8dbed2d70b09feb592299469196ec4b215909f2b052144882"
     }
   },
-  "signature": "R9ITW6i0ujl7PmaSQBlyAvZJDUQ3Gt14hxgqv1hXbrueOKWTVQc7FTWlNOAUhTqqsDxKPFnx7zzbXwJnbPWSAg==",
+  "signature": "jF/krskPhEF+3m0rkY3my1qEuLZec5hzo3YoV7xUl8/7xZqlpTctkB9QlYACViu2GCK3AGkWS7BRf5xR6WK7Aw==",
   "algorithm": "ed25519"
 }

package/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generation": 2,
-  "generatedAt": "2026-07-28T19:25:02.626Z",
-  "gitSha": "80634fa0",
+  "generation": 3,
+  "generatedAt": "2026-07-29T04:47:25.187Z",
+  "gitSha": "39bc5fd9",
   "catalog": {
     "agents": 164,
-    "tools": 388,
+    "tools": 395,
     "skills": 34
   },
   "benchmark": null

package/dist/src/commands/index.d.ts

@@ -33,6 +33,7 @@ export declare function getProvidersCommand(): Promise<Command | undefined>;
 export declare function getPluginsCommand(): Promise<Command | undefined>;
 export declare function getDeploymentCommand(): Promise<Command | undefined>;
 export declare function getClaimsCommand(): Promise<Command | undefined>;
+export declare function getPolicyCommand(): Promise<Command | undefined>;
 export declare function getEmbeddingsCommand(): Promise<Command | undefined>;
 export declare function getCompletionsCommand(): Promise<Command | undefined>;
 export declare function getAnalyzeCommand(): Promise<Command | undefined>;

package/dist/src/commands/index.js

@@ -40,6 +40,7 @@ const commandLoaders = {
     plugins: () => import('./plugins.js'),
     deployment: () => import('./deployment.js'),
     claims: () => import('./claims.js'),
+    policy: () => import('./policy.js'),
     embeddings: () => import('./embeddings.js'),
     // P0 Commands
     completions: () => import('./completions.js'),
@@ -175,6 +176,7 @@ export async function getProvidersCommand() { return loadCommand('providers'); }
 export async function getPluginsCommand() { return loadCommand('plugins'); }
 export async function getDeploymentCommand() { return loadCommand('deployment'); }
 export async function getClaimsCommand() { return loadCommand('claims'); }
+export async function getPolicyCommand() { return loadCommand('policy'); }
 export async function getEmbeddingsCommand() { return loadCommand('embeddings'); }
 export async function getCompletionsCommand() { return loadCommand('completions'); }
 export async function getAnalyzeCommand() { return loadCommand('analyze'); }
@@ -230,14 +232,14 @@ export const commandsByCategory = {
  * Use this for help display and full command listings.
  */
 export async function getCommandsByCategory() {
-    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, ruvectorCmd, hiveMindCmd, configCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd,] = await Promise.all([
+    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, ruvectorCmd, hiveMindCmd, configCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, policyCmd,] = await Promise.all([
         loadCommand('daemon'), loadCommand('doctor'), loadCommand('embeddings'), loadCommand('neural'),
         loadCommand('performance'), loadCommand('security'), loadCommand('ruvector'), loadCommand('hive-mind'),
         loadCommand('config'), loadCommand('completions'), loadCommand('migrate'), loadCommand('workflow'),
         loadCommand('analyze'), loadCommand('route'), loadCommand('progress'), loadCommand('providers'),
         loadCommand('plugins'), loadCommand('deployment'), loadCommand('claims'), loadCommand('issues'),
         loadCommand('update'), loadCommand('process'), loadCommand('guidance'), loadCommand('appliance'),
-        loadCommand('cleanup'), loadCommand('autopilot'),
+        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('policy'),
     ]);
     return {
         primary: [
@@ -246,7 +248,7 @@ export async function getCommandsByCategory() {
             mcpCommand, hooksCommand,
         ],
         advanced: [
-            neuralCmd, securityCmd, performanceCmd, embeddingsCmd,
+            neuralCmd, securityCmd, policyCmd, performanceCmd, embeddingsCmd,
             hiveMindCmd, ruvectorCmd, guidanceCmd, autopilotCmd,
         ].filter(Boolean),
         utility: [

package/dist/src/commands/memory.js

@@ -86,12 +86,23 @@ const storeCommand = {
             description: 'Scan the value for injection payloads before persisting (dream-cycle #2752 MemPoison gate)',
             type: 'boolean',
         },
+        {
+            // ADR-323 — typed memory provenance. Distinguishes who/what produced
+            // this entry so shared-namespace retrieval can filter by trust level
+            // instead of conflating a user's stated claim with an agent's own
+            // output or a raw tool/system observation.
+            name: 'provenance',
+            description: 'Who/what produced this value: user_claim | agent_output | system_observation | tool_result | unknown (default: unknown) — ADR-323',
+            type: 'string',
+            choices: ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'],
+        },
         DB_PATH_OPTION
     ],
     examples: [
         { command: 'claude-flow memory store -k "api/auth" -v "JWT implementation"', description: 'Store text' },
         { command: 'claude-flow memory store -k "pattern/singleton" --vector', description: 'Store vector' },
-        { command: 'claude-flow memory store -k "pattern" -v "new" --no-upsert', description: 'Strict insert (fail if key exists)' }
+        { command: 'claude-flow memory store -k "pattern" -v "new" --no-upsert', description: 'Strict insert (fail if key exists)' },
+        { command: 'claude-flow memory store -k "user/goal" -v "ship by Friday" --provenance user_claim', description: 'Store with typed provenance (ADR-323)' }
     ],
     action: async (ctx) => {
         const key = ctx.flags.key;
@@ -114,6 +125,10 @@ const storeCommand = {
         // regardless of the parser gap: only an explicit `--no-upsert` (which
         // arrives as `false`) turns it off.
         const upsert = ctx.flags.upsert !== false;
+        // ADR-323: leave undefined (not 'unknown') when omitted so storeEntry's
+        // own default applies uniformly across the CLI, MCP tool, and direct
+        // callers — one place decides the default, not three.
+        const provenance = ctx.flags.provenance;
         if (!key) {
             output.printError('Key is required. Use --key or -k');
             return { success: false, exitCode: 1 };
@@ -174,6 +189,7 @@ const storeCommand = {
                 tags,
                 ttl,
                 upsert,
+                provenanceType: provenance,
                 dbPath
             });
             if (!result.success) {
@@ -193,12 +209,13 @@ const storeCommand = {
                     { property: 'TTL', val: ttl ? `${ttl}s` : 'None' },
                     { property: 'Tags', val: tags.length > 0 ? tags.join(', ') : 'None' },
                     { property: 'Vector', val: result.embedding ? `Yes (${result.embedding.dimensions}-dim)` : 'No' },
+                    { property: 'Provenance', val: provenance || 'unknown' },
                     { property: 'ID', val: result.id.substring(0, 20) }
                 ]
             });
             output.writeln();
             output.printSuccess('Data stored successfully');
-            return { success: true, data: { ...storeData, id: result.id, embedding: result.embedding } };
+            return { success: true, data: { ...storeData, id: result.id, embedding: result.embedding, provenanceType: provenance || 'unknown' } };
         }
         catch (error) {
             output.printError(`Failed to store: ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -361,6 +378,15 @@ const searchCommand = {
             choices: ['auto', 'mixed', 'episodic', 'semantic', 'procedural'],
             default: 'mixed',
         },
+        {
+            // ADR-323 — restrict results to entries with a matching provenance
+            // type (e.g. exclude user_claim when retrieving for fact-checking,
+            // per MemSyco-Bench's memory-induced sycophancy finding). Enforced
+            // across semantic, keyword, hybrid, and SmartRetrieval paths.
+            name: 'provenance-filter',
+            description: 'Comma-separated provenance types to restrict results to: user_claim,agent_output,system_observation,tool_result,unknown — ADR-323',
+            type: 'string',
+        },
         DB_PATH_OPTION
     ],
     examples: [
@@ -369,11 +395,18 @@ const searchCommand = {
         { command: 'claude-flow memory search -q "test" --build-hnsw', description: 'Build HNSW index and search' },
         { command: 'claude-flow memory search -q "auth patterns" --smart', description: 'SmartRetrieval with RRF + MMR' },
         { command: 'claude-flow memory search -q "when did we last touch auth" --intent auto', description: 'SCM-routed retrieval (dream-cycle #2760)' },
+        { command: 'claude-flow memory search -q "deploy plan" --provenance-filter agent_output,tool_result', description: 'Only trust agent/tool-sourced entries (ADR-323)' },
     ],
     action: async (ctx) => {
         const query = ctx.flags.query || ctx.args[0];
         let namespace = ctx.flags.namespace || 'all';
         const limit = ctx.flags.limit || 10;
+        // Matches the --build-hnsw / buildHnsw dual-check convention already used
+        // below: the parser doesn't consistently camelCase every hyphenated flag.
+        const provenanceFilterRaw = (ctx.flags['provenance-filter'] || ctx.flags.provenanceFilter);
+        const provenanceFilter = provenanceFilterRaw
+            ? provenanceFilterRaw.split(',').map(s => s.trim()).filter(Boolean)
+            : undefined;
         // #2790 fix — `||` discards an explicit `--threshold 0` (falsy) and
         // silently uses the fallback; that made `--threshold 0` return
         // FEWER results than `--threshold 0.01` (non-monotonic). Nullish
@@ -456,8 +489,13 @@ const searchCommand = {
                     limit: 5000,
                     includeContent: true,
                     dbPath: dbPathSearch,
+                    provenanceFilter,
                 });
-                if (list.success) {
+                if (!list.success) {
+                    output.printError(list.error || 'Keyword search failed');
+                    return { success: false, exitCode: 1 };
+                }
+                else {
                     const q = query.toLowerCase();
                     keywordResults = list.entries
                         .filter((e) => {
@@ -473,6 +511,7 @@ const searchCommand = {
                             score: inKey ? 1.0 : 0.7,
                             namespace: e.namespace,
                             preview: c.slice(0, 200),
+                            provenanceType: e.provenanceType,
                         };
                     })
                         .sort((a, b) => b.score - a.score)
@@ -526,6 +565,7 @@ const searchCommand = {
                         limit: req.limit || limit * 3,
                         threshold: req.threshold ?? threshold,
                         dbPath: dbPathSearch,
+                        provenanceFilter,
                     });
                     return {
                         results: r.results.map(e => ({
@@ -534,6 +574,7 @@ const searchCommand = {
                             content: e.content,
                             score: e.score,
                             namespace: e.namespace,
+                            provenanceType: e.provenanceType,
                         })),
                     };
                 };
@@ -548,6 +589,7 @@ const searchCommand = {
                     score: r.score,
                     namespace: r.namespace,
                     preview: r.content,
+                    provenanceType: r.provenanceType,
                 }));
                 searchTimeMs = smartResult.stats.durationMs;
                 smartStats = smartResult.stats;
@@ -559,7 +601,8 @@ const searchCommand = {
                     namespace,
                     limit,
                     threshold,
-                    dbPath: dbPathSearch
+                    dbPath: dbPathSearch,
+                    provenanceFilter
                 });
                 if (!searchResult.success) {
                     output.printError(searchResult.error || 'Search failed');
@@ -569,7 +612,8 @@ const searchCommand = {
                     key: r.key,
                     score: r.score,
                     namespace: r.namespace,
-                    preview: r.content
+                    preview: r.content,
+                    provenanceType: r.provenanceType,
                 }));
                 searchTimeMs = searchResult.searchTime;
             }

package/dist/src/commands/metaharness.js

@@ -40,6 +40,7 @@ import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { runFlywheelWorker } from '../services/harness-flywheel-runtime.js';
 import { listFlywheelReceipts, promoteFlywheelCandidate, readFlywheelTransactionState, verifyFlywheelLedger, } from '../services/flywheel-transaction.js';
+import { evaluatePolicyRequest } from '../services/policy-runtime.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Subcommand → plugin script filename
 const SUBCOMMANDS = {
@@ -99,6 +100,8 @@ async function dispatchFlywheel(operation, positional, flags) {
                 proposer: String(flywheelFlag(flags, 'proposer', 'auto')),
                 receiptPrivateKeyPem: privateKeyPath ? readFileSync(resolve(privateKeyPath), 'utf8') : undefined,
                 receiptPublicKeyPem: publicKeyPath ? readFileSync(resolve(publicKeyPath), 'utf8') : undefined,
+                maxConcurrency: Number(flywheelFlag(flags, 'maxConcurrency', 2)),
+                evaluationTimeoutMs: Number(flywheelFlag(flags, 'timeoutMs', 120_000)),
             });
         }
     }
@@ -124,11 +127,28 @@ async function dispatchFlywheel(operation, positional, flags) {
             data = { success: false, reason: 'promote requires <receipt-id> and --public-key <PEM path>' };
         }
         else {
-            const publicKey = readFileSync(resolve(publicKeyPath), 'utf8');
-            data = await promoteFlywheelCandidate(projectRoot, receiptId, {
-                confirm: flywheelFlag(flags, 'confirm', false) === true,
-                trustedPublicKeys: new Set([publicKey]),
-            });
+            const policy = await evaluatePolicyRequest({
+                identity: { id: process.env.CLAUDE_FLOW_PRINCIPAL_ID ?? 'metaharness-local', type: 'agent', roles: ['optimizer'] },
+                action: {
+                    type: 'metaharness.candidate.promote',
+                    resource: receiptId,
+                    environment: 'production',
+                    destructive: true,
+                },
+                context: {
+                    approvalIds: String(flywheelFlag(flags, 'approvalId', '')).split(',').filter(Boolean),
+                },
+            }, projectRoot);
+            if (policy.enforcedOutcome !== 'allowed') {
+                data = { success: false, reason: `policy-${policy.enforcedOutcome}:${policy.reason}`, policyReceiptId: policy.receiptId };
+            }
+            else {
+                const publicKey = readFileSync(resolve(publicKeyPath), 'utf8');
+                data = await promoteFlywheelCandidate(projectRoot, receiptId, {
+                    confirm: flywheelFlag(flags, 'confirm', false) === true,
+                    trustedPublicKeys: new Set([publicKey]),
+                });
+            }
         }
     }
     else {

package/dist/src/commands/policy.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from '../types.js';
+export declare const policyCommand: Command;
+export default policyCommand;
+//# sourceMappingURL=policy.d.ts.map

package/dist/src/commands/policy.js

@@ -0,0 +1,107 @@
+import { output } from '../output.js';
+import { autoMigratePolicyStateIfNeeded, evaluatePolicyRequest, loadPolicyState, revokePolicyApproval, setPolicyBudget, setPolicyMode, upsertPolicyRule, verifyPolicyLedger, } from '../services/policy-runtime.js';
+function argJson(value, label) {
+    if (!value)
+        throw new Error(`${label} requires a JSON argument`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${label} must be valid JSON`);
+    }
+}
+function print(data) {
+    output.writeln(JSON.stringify(data, null, 2));
+    return { success: true, exitCode: 0, data };
+}
+function requireInteractiveAdministrator() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error('policy administration requires an interactive local terminal');
+    }
+}
+export const policyCommand = {
+    name: 'policy',
+    description: 'Agentic policy engine — evaluate actions, manage rules/approvals, and verify the decision ledger (ADR-324)',
+    options: [
+        { name: 'mode', type: 'string', description: 'Policy mode: legacy | observe | enforce' },
+        { name: 'project-root', type: 'string', description: 'Project root containing .claude-flow/policy' },
+    ],
+    async action(context) {
+        const args = context.args ?? [];
+        const flags = context.flags ?? {};
+        const root = String(flags.projectRoot ?? process.cwd());
+        const operation = args[0] ?? 'status';
+        try {
+            if (operation === 'init' || operation === 'migrate') {
+                if (flags.mode || args[1])
+                    requireInteractiveAdministrator();
+                const migration = await autoMigratePolicyStateIfNeeded(root);
+                const mode = String(flags.mode ?? args[1] ?? '');
+                if (mode) {
+                    if (!['legacy', 'observe', 'enforce'].includes(mode))
+                        throw new Error('mode must be legacy, observe, or enforce');
+                    await setPolicyMode(mode, root);
+                }
+                return print({ ...migration, state: loadPolicyState(root) });
+            }
+            if (operation === 'status') {
+                const state = loadPolicyState(root);
+                return print({
+                    version: state.version,
+                    mode: state.mode,
+                    migratedFrom: state.migratedFrom,
+                    rules: state.rules.length,
+                    budgets: state.budgets.length,
+                    approvals: state.approvals.length,
+                    receipts: state.receipts.length,
+                    ledger: await verifyPolicyLedger(root),
+                });
+            }
+            if (operation === 'evaluate') {
+                return print(await evaluatePolicyRequest(argJson(args[1], 'evaluate'), root));
+            }
+            if (operation === 'rule' && args[1] === 'add') {
+                requireInteractiveAdministrator();
+                const rule = argJson(args[2], 'rule add');
+                await upsertPolicyRule(rule, root);
+                return print({ success: true, ruleId: rule.id });
+            }
+            if (operation === 'budget' && args[1] === 'set') {
+                requireInteractiveAdministrator();
+                const budget = argJson(args[2], 'budget set');
+                await setPolicyBudget(budget, root);
+                return print({ success: true, budgetId: budget.id });
+            }
+            if (operation === 'approve') {
+                throw new Error('approval issuance requires an authenticated human identity adapter; '
+                    + 'the local TTY is not an identity credential');
+            }
+            if (operation === 'revoke') {
+                requireInteractiveAdministrator();
+                if (!args[1])
+                    throw new Error('revoke requires an approval id');
+                return print({ success: await revokePolicyApproval(args[1], root), approvalId: args[1] });
+            }
+            if (operation === 'audit') {
+                const state = loadPolicyState(root);
+                return print({ receipts: state.receipts });
+            }
+            if (operation === 'verify')
+                return print(await verifyPolicyLedger(root));
+            throw new Error(`unknown policy operation: ${operation}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            output.printError(message);
+            return { success: false, exitCode: 1, data: { error: message } };
+        }
+    },
+    examples: [
+        { command: 'ruflo policy status', description: 'Show policy mode and ledger health' },
+        { command: 'ruflo policy init --mode observe', description: 'Migrate an existing install without blocking legacy actions' },
+        { command: 'ruflo policy budget set \'{"id":"daily-model","action":"model.call","maxCostUsd":10,"periodMs":86400000}\'', description: 'Set an atomic policy budget ceiling' },
+        { command: 'ruflo policy evaluate \'{"identity":{"id":"agent-1","type":"agent"},"action":{"type":"deploy","environment":"production"}}\'', description: 'Evaluate an action and write a decision receipt' },
+    ],
+};
+export default policyCommand;
+//# sourceMappingURL=policy.js.map

package/dist/src/index.js

@@ -120,6 +120,24 @@ export class CLI {
             // stamp read + string compare (sub-ms), and the copy runs at most once per
             // version bump. Best-effort + silent — never blocks or fails a command.
             if (commandPath[0] !== 'init' && commandPath[0] !== 'update') {
+                // ADR-324: existing installations acquire a versioned policy state on
+                // first use. Migration is additive and starts in legacy mode, so older
+                // AgentDB, MCP, hooks, and swarm workflows keep their exact behavior.
+                try {
+                    const { autoMigratePolicyStateIfNeeded } = await import('./services/policy-runtime.js');
+                    const migration = await autoMigratePolicyStateIfNeeded(process.cwd());
+                    if (migration.migrated && this.output.isVerbose()) {
+                        this.output.printDebug(`Initialized agentic policy compatibility state (${migration.mode})`);
+                    }
+                }
+                catch (error) {
+                    // Legacy compatibility requires startup to remain available if the
+                    // policy state cannot be initialized. Enforce-mode actions still
+                    // fail at their authoritative dispatcher when state is unreadable.
+                    if (this.output.isVerbose()) {
+                        this.output.printDebug(`Policy compatibility migration skipped: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
                 try {
                     const { autoRefreshHelpersIfStale } = await import('./init/helper-refresh.js');
                     // alsoRefreshGlobal:true — refresh ~/.claude/helpers too, not just

package/dist/src/mcp-client.js

@@ -21,6 +21,8 @@ import { analyzeTools } from './mcp-tools/analyze-tools.js';
 import { progressTools } from './mcp-tools/progress-tools.js';
 import { embeddingsTools } from './mcp-tools/embeddings-tools.js';
 import { claimsTools } from './mcp-tools/claims-tools.js';
+import { policyTools } from './mcp-tools/policy-tools.js';
+import { authorizeMcpTool, classifyMcpTool } from './services/policy-runtime.js';
 import { securityTools } from './mcp-tools/security-tools.js';
 import { transferTools } from './mcp-tools/transfer-tools.js';
 // V2 Compatibility tools
@@ -47,7 +49,7 @@ import { wasmAgentTools } from './mcp-tools/wasm-agent-tools.js';
 // the local WASM-sandboxed `wasm_agent_*` (rvagent) tools. Lives in the
 // `ruflo-agent` plugin.
 import { managedAgentTools } from './mcp-tools/managed-agent-tools.js';
-import { guidanceTools } from './mcp-tools/guidance-tools.js';
+import { configureGuidanceToolProvider, guidanceTools, } from './mcp-tools/guidance-tools.js';
 import { autopilotTools } from './mcp-tools/autopilot-tools.js';
 // ADR-150 — MetaHarness MCP tools (score / genome / mcp-scan / threat-model / oia-audit)
 import { metaharnessTools } from './mcp-tools/metaharness-tools.js';
@@ -127,6 +129,10 @@ registerTools([
     ...progressTools,
     ...embeddingsTools,
     ...claimsTools,
+    // Remote MCP exposes evaluation/status only. Administrative mutation is a
+    // local CLI bootstrap/recovery operation until the server has authenticated
+    // human identity propagation.
+    ...policyTools.filter((tool) => ['policy_evaluate', 'policy_status'].includes(tool.name)),
     ...securityTools,
     ...transferTools,
     // V2 Compatibility tools
@@ -167,6 +173,15 @@ registerTools([
     // ADR-164 Phase 4 §5.1.8 — http_fetch (1 tool, secure-by-default HTTP probe)
     ...httpFetchTools,
 ]);
+// The capability brain consumes the completed live registry. This is injected
+// after registration to keep guidance honest and avoid a registry import cycle.
+configureGuidanceToolProvider(() => Array.from(TOOL_REGISTRY.values()).map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    category: tool.category,
+    tags: tool.tags,
+    version: tool.version,
+})));
 /**
  * MCP Client Error
  */
@@ -211,6 +226,15 @@ export async function callMCPTool(toolName, input = {}, context) {
         throw new MCPClientError(`MCP tool not found: ${toolName}`, toolName);
     }
     try {
+        // ADR-324: one policy chokepoint for every local CLI/MCP invocation.
+        // Policy administration is not exempt: authorization calls the engine
+        // directly, so there is no recursive MCP dispatch. In enforce mode an
+        // administrator must explicitly allow policy.* actions or use the local
+        // CLI bootstrap path.
+        const decision = await authorizeMcpTool(toolName, input, context, classifyMcpTool(toolName));
+        if (decision.enforcedOutcome !== 'allowed') {
+            throw new Error(`policy-${decision.enforcedOutcome}:${decision.reason}; receipt=${decision.receiptId}`);
+        }
         // Call the tool handler
         const result = await tool.handler(input, context);
         // ADR-146 P2: scan every tool result for indirect-injection before it

package/dist/src/mcp-tools/capability-brain.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Ruflo capability brain.
+ *
+ * This module is deliberately data-only: it describes the complete MCP surface
+ * without importing the MCP registry. The registry injects its live tool list
+ * into guidance-tools after registration, which avoids a circular dependency
+ * and prevents documentation from being mistaken for runtime availability.
+ */
+export type CapabilityMaturity = 'stable' | 'experimental' | 'compatibility';
+export type CapabilityAuthority = 'advisory' | 'capability-plane' | 'control-plane';
+export type CapabilityRisk = 'read-only' | 'reversible' | 'privileged';
+export type AvailabilityState = boolean | 'unknown';
+export type CapabilityRiskFlag = 'read' | 'local-write' | 'memory-poisoning' | 'process-exec' | 'network' | 'credential-pii' | 'spend' | 'concurrency' | 'destructive' | 'approval' | 'promotion';
+export interface CapabilityToolMetadata {
+    name: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    version?: string;
+}
+export interface CapabilityHealth {
+    /** Present in this running MCP server's registry. */
+    registered: boolean;
+    /** Requires an operator/provider configuration check. */
+    configured: AvailabilityState;
+    /** Requires a non-mutating dependency probe. */
+    reachable: AvailabilityState;
+    /** Requires a service-specific health check. */
+    healthy: AvailabilityState;
+    /** Requires a policy evaluation for the current subject and action. */
+    authorized: AvailabilityState;
+}
+export interface CapabilityDomainDefinition {
+    id: string;
+    name: string;
+    description: string;
+    prefixes: string[];
+    exactTools?: string[];
+    taskSignals: string[];
+    commands: string[];
+    skills: string[];
+    agents: string[];
+    maturity: CapabilityMaturity;
+    authority: CapabilityAuthority;
+    risk: CapabilityRisk;
+    optionalRuntime?: boolean;
+    packageOwners?: string[];
+    pluginOwners?: string[];
+    availabilityMode?: 'always-local' | 'conditional-registration' | 'registered-degraded' | 'configured-remote' | 'policy-filtered';
+    /**
+     * Conservative union of effects possible anywhere in this domain.
+     * Individual tool descriptors may narrow or expand this reviewed profile.
+     */
+    riskFlags?: CapabilityRiskFlag[];
+    loopPhases?: Array<'discover' | 'recall' | 'authorize-claim' | 'route-plan' | 'branch-propose' | 'execute' | 'validate-critique' | 'commit-validated' | 'observe' | 'publish'>;
+    useWhen: string;
+    verifyBeforeUse: string[];
+}
+export interface CapabilityDomain extends CapabilityDomainDefinition {
+    packageOwners: string[];
+    pluginOwners: string[];
+    availabilityMode: NonNullable<CapabilityDomainDefinition['availabilityMode']>;
+    riskFlags: NonNullable<CapabilityDomainDefinition['riskFlags']>;
+    loopPhases: NonNullable<CapabilityDomainDefinition['loopPhases']>;
+    tools: Array<CapabilityToolMetadata & {
+        domain: string;
+        packageOwner: string;
+        pluginOwner?: string;
+        availabilityMode: NonNullable<CapabilityDomainDefinition['availabilityMode']>;
+        authority: CapabilityAuthority;
+        risk: CapabilityRisk;
+        riskFlags: NonNullable<CapabilityDomainDefinition['riskFlags']>;
+        loopPhases: NonNullable<CapabilityDomainDefinition['loopPhases']>;
+    }>;
+    health: CapabilityHealth;
+}
+export interface CapabilityBrain {
+    schemaVersion: 'ruflo.capability-brain/v1';
+    generatedAt: string;
+    truthModel: {
+        catalogued: string;
+        registered: string;
+        configured: string;
+        reachable: string;
+        healthy: string;
+        authorized: string;
+    };
+    domains: CapabilityDomain[];
+    cliCommands: string[];
+    implementationLoop: ImplementationLoopStep[];
+    coverage: {
+        registeredToolCount: number;
+        classifiedToolCount: number;
+        coveragePercent: number;
+        fallbackClassifiedTools: string[];
+        duplicateToolNames: string[];
+    };
+}
+/** Top-level commands from the CLI command loader. Kept as a checked manifest. */
+export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "announcements"];
+export interface ImplementationLoopStep {
+    id: string;
+    name: string;
+    purpose: string;
+    preferredTools: string[];
+    requiredEvidence: string;
+    mutation: 'none' | 'workspace' | 'external';
+}
+export declare const IMPLEMENTATION_LOOP: readonly ImplementationLoopStep[];
+/**
+ * Domain order is significant: narrow/specialized matches precede broad
+ * compatibility prefixes. Every registered tool is eventually classified by
+ * the final runtime-services domain, but fallback classifications are reported.
+ */
+export declare const CAPABILITY_DOMAINS: readonly CapabilityDomainDefinition[];
+export declare function classifyCapabilityTool(tool: CapabilityToolMetadata): CapabilityDomainDefinition;
+export declare function buildCapabilityBrain(registeredTools: readonly CapabilityToolMetadata[], now?: Date): CapabilityBrain;
+export interface CapabilityRecommendation {
+    task: string;
+    domains: Array<{
+        id: string;
+        name: string;
+        score: number;
+        registeredTools: string[];
+        health: CapabilityHealth;
+        authority: CapabilityAuthority;
+        risk: CapabilityRisk;
+        verifyBeforeUse: string[];
+    }>;
+    implementationLoop: ImplementationLoopStep[];
+    guardrails: string[];
+}
+export declare function recommendCapabilities(brain: CapabilityBrain, task: string): CapabilityRecommendation;
+//# sourceMappingURL=capability-brain.d.ts.map