principles-disciple 1.167.1 → 1.168.0

package/dist/core/rule-host.d.ts

@@ -30,12 +30,31 @@ export interface RuleHostOptions {
     /** Workspace directory for SQLite access. Required for RuleHost to load active code_tool_hook activations. */
     workspaceDir?: string;
 }
+export interface RuleHostObservedDecision extends RuleHostResult {
+    readonly activationId: string;
+}
+export interface RuleHostEvaluationReport {
+    readonly liveDecision: RuleHostResult | undefined;
+    readonly shadowDecisions: readonly RuleHostObservedDecision[];
+}
 export declare class RuleHost {
     private readonly stateDir;
-    private readonly logger;
+    private logger;
     private readonly workspaceDir;
     private readonly implementationSources;
+    private activationFingerprint;
+    private cachedImplementations;
+    private sqliteConnection;
     constructor(stateDir: string, logger?: RuleHostLogger, options?: RuleHostOptions);
+    /**
+     * Update the logger sink on a cached RuleHost instance.
+     *
+     * WorkspaceContext caches the RuleHost singleton, but each gate call may
+     * pass a request-level logger. Without this update, warn/unhealthy logs
+     * would forever go to the first logger sink, making the new path hard to
+     * debug.
+     */
+    updateLogger(logger: RuleHostLogger): void;
     /**
      * Evaluate the input against all active code implementations.
      *
@@ -46,6 +65,8 @@ export declare class RuleHost {
      *   - { decision: 'requireApproval', ... } when any implementation returns requireApproval
      */
     evaluate(input: RuleHostInput): RuleHostResult | undefined;
+    dispose(): void;
+    evaluateDetailed(input: RuleHostInput): RuleHostEvaluationReport;
     /**
      * Load active code implementations from the SQLite activations table.
      *

package/dist/core/rule-host.js

@@ -48,11 +48,25 @@ export class RuleHost {
     logger;
     workspaceDir;
     implementationSources = new Map();
+    activationFingerprint = null;
+    cachedImplementations = [];
+    sqliteConnection = null;
     constructor(stateDir, logger = console, options) {
         this.stateDir = stateDir;
         this.logger = logger;
         this.workspaceDir = options?.workspaceDir ?? null;
     }
+    /**
+     * Update the logger sink on a cached RuleHost instance.
+     *
+     * WorkspaceContext caches the RuleHost singleton, but each gate call may
+     * pass a request-level logger. Without this update, warn/unhealthy logs
+     * would forever go to the first logger sink, making the new path hard to
+     * debug.
+     */
+    updateLogger(logger) {
+        this.logger = logger;
+    }
     /**
      * Evaluate the input against all active code implementations.
      *
@@ -63,9 +77,36 @@ export class RuleHost {
      *   - { decision: 'requireApproval', ... } when any implementation returns requireApproval
      */
     evaluate(input) {
+        return this.evaluateDetailed(input).liveDecision;
+    }
+    dispose() {
+        this.sqliteConnection?.close();
+        this.sqliteConnection = null;
+        this.cachedImplementations = [];
+        this.activationFingerprint = null;
+        this.implementationSources.clear();
+    }
+    evaluateDetailed(input) {
         try {
-            const activeImpls = this._loadActiveCodeImplementations();
-            return mergeDecisions(activeImpls, input, {
+            const activeImpls = this._loadActiveCodeImplementations(input.context?.version === 2);
+            const liveImpls = activeImpls.filter((impl) => impl.activationMode === 'live');
+            const shadowImpls = activeImpls.filter((impl) => impl.activationMode === 'shadow');
+            const shadowDecisions = [];
+            for (const impl of shadowImpls) {
+                try {
+                    const result = impl.evaluate(input);
+                    shadowDecisions.push({ ...result, activationId: impl.activationId });
+                }
+                catch (evalError) {
+                    const reason = `evaluation failed: ${String(evalError)}`;
+                    this.logger.warn?.(`[RuleHost] Shadow implementation ${impl.implId} ${reason}`);
+                    const source = this.implementationSources.get(impl.implId);
+                    if (source) {
+                        this._recordUnhealthy(source.activationId, source.artifactId, source.ruleId, reason, 'Fix the RuleCode runtime error or return shape, then re-activate the rule');
+                    }
+                }
+            }
+            const liveDecision = mergeDecisions(liveImpls, input, {
                 warn: this.logger.warn,
                 onImplementationUnhealthy: (impl, reason) => {
                     const source = this.implementationSources.get(impl.implId);
@@ -76,11 +117,12 @@ export class RuleHost {
                     this._recordUnhealthy(source.activationId, source.artifactId, source.ruleId, reason, 'Fix the RuleCode runtime error or return shape, then re-activate the rule');
                 },
             });
+            return { liveDecision, shadowDecisions };
         }
         catch (hostError) {
             // Conservative degradation: log and return undefined (D-08)
             this.logger.warn?.(`[RuleHost] Host evaluation failed, degrading conservatively: ${String(hostError)}`);
-            return undefined;
+            return { liveDecision: undefined, shadowDecisions: [] };
         }
     }
     /**
@@ -93,12 +135,12 @@ export class RuleHost {
      * Source: activations table (code_tool_hook channel, deactivated_at IS NULL)
      *   → JOIN pi_artifacts for content_json → extract implementationCode → compile
      */
-    _loadActiveCodeImplementations() {
+    _loadActiveCodeImplementations(supportsContextV2) {
         if (!this.workspaceDir) {
             return [];
         }
         try {
-            return this._loadFromActivationsTable(this.workspaceDir);
+            return this._loadFromActivationsTable(this.workspaceDir, supportsContextV2);
         }
         catch (activationError) {
             this.logger.warn?.(`[RuleHost] Failed to load code_tool_hook activations: ${String(activationError)}`);
@@ -120,13 +162,13 @@ export class RuleHost {
      *
      * All data from SQLite is treated as unknown and validated before use.
      */
-    _loadFromActivationsTable(workspaceDir) {
-        this.implementationSources.clear();
-        const sqliteConn = new SqliteConnection(workspaceDir);
-        try {
+    _loadFromActivationsTable(workspaceDir, supportsContextV2) {
+        const sqliteConn = this.sqliteConnection ?? new SqliteConnection(workspaceDir);
+        this.sqliteConnection = sqliteConn;
+        {
             const db = sqliteConn.getDb();
             const rows = db.prepare(`
-        SELECT a.activation_id, a.artifact_id, a.target_ref,
+        SELECT a.activation_id, a.artifact_id, a.target_ref, a.action,
                p.content_json, p.source_rule_id
         FROM activations a
         JOIN pi_artifacts p ON a.artifact_id = p.artifact_id
@@ -137,6 +179,20 @@ export class RuleHost {
                 this.logger.warn?.('[RuleHost] Activations table query returned non-array, skipping');
                 return [];
             }
+            const fingerprintParts = [supportsContextV2 ? 'context-v2' : 'context-v1'];
+            for (const row of rows) {
+                if (!row || typeof row !== 'object' || Array.isArray(row))
+                    continue;
+                const record = row;
+                fingerprintParts.push([
+                    record['activation_id'], record['artifact_id'], record['target_ref'], record['action'], record['content_json'], record['source_rule_id'],
+                ].map((value) => typeof value === 'string' ? value : '').join('\u0001'));
+            }
+            const fingerprint = fingerprintParts.join('\u0002');
+            if (fingerprint === this.activationFingerprint) {
+                return [...this.cachedImplementations];
+            }
+            this.implementationSources.clear();
             // PRI-436: Group active rows by target_ref to detect duplicates.
             // At most one active activation per rule (target_ref) is allowed.
             // Duplicate groups are skipped entirely (zero executions) and emit
@@ -199,10 +255,35 @@ export class RuleHost {
                 const artifactId = typeof r['artifact_id'] === 'string' ? r['artifact_id'] : '';
                 const contentJson = typeof r['content_json'] === 'string' ? r['content_json'] : '';
                 const sourceRuleId = typeof r['source_rule_id'] === 'string' ? r['source_rule_id'] : null;
+                const action = typeof r['action'] === 'string' ? r['action'] : '';
                 if (!activationId || !artifactId || !contentJson) {
                     this.logger.warn?.(`[RuleHost] Activation row missing required fields, skipping`);
                     continue;
                 }
+                const activationMode = action === 'code_tool_hook_shadow_activate'
+                    ? 'shadow'
+                    : action === 'code_tool_hook_live_activate'
+                        ? 'live'
+                        : null;
+                if (!activationMode) {
+                    this.logger.warn?.(`[RuleHost] Activation ${activationId}: unsupported action ${action || '(missing)'}, skipping. ` +
+                        'nextAction=deactivate and recreate the activation through RuleHostWriter');
+                    continue;
+                }
+                if (activationMode === 'shadow') {
+                    // CodeRabbit PR #1121: shadow activations are observation-only and do
+                    // NOT enter mergeDecisions (no block / requireApproval). Historical
+                    // owner-approved records persisted with action=code_tool_hook_shadow_activate
+                    // (before RuleHostWriter was fixed to write code_tool_hook_live_activate)
+                    // silently lost execution after the dual-mode change. Surface a
+                    // structured reason + nextAction so the degradation is observable
+                    // (rc-9-no-silent-fallback), not silent. Fires once per fingerprint
+                    // change (cached), not per evaluation.
+                    this.logger.warn?.(`[RuleHost] Activation ${activationId}: loaded in shadow (observation-only) mode; ` +
+                        'it will NOT block or require approval (shadowDecisions only). ' +
+                        `nextAction=run \`pd runtime activation promote --activation-id ${activationId} --confirm\` to enable live blocking, ` +
+                        'or leave as-is for shadow observation.');
+                }
                 try {
                     const content = JSON.parse(contentJson);
                     if (!content || typeof content !== 'object' || Array.isArray(content)) {
@@ -210,6 +291,18 @@ export class RuleHost {
                         continue;
                     }
                     const contentObj = content;
+                    if (Object.hasOwn(contentObj, 'requiresContextVersion')) {
+                        if (contentObj['requiresContextVersion'] !== 2) {
+                            this.logger.warn?.(`[RuleHost] Activation ${activationId}: unsupported context version; skipping. ` +
+                                'nextAction=regenerate the rule artifact with requiresContextVersion: 2 or omit the field for v1');
+                            continue;
+                        }
+                        if (!supportsContextV2) {
+                            this.logger.warn?.(`[RuleHost] Activation ${activationId}: suspended because rulecode_context_v2 is disabled or unavailable; skipping. ` +
+                                'nextAction=enable rulecode_context_v2 with valid config or deactivate this activation');
+                            continue;
+                        }
+                    }
                     const implementationCode = contentObj['implementationCode'];
                     if (typeof implementationCode !== 'string' || implementationCode.length === 0) {
                         this.logger.warn?.(`[RuleHost] Activation ${activationId}: no implementationCode in artifact, skipping`);
@@ -244,6 +337,8 @@ export class RuleHost {
                         implId,
                         ruleId,
                         meta,
+                        activationId,
+                        activationMode,
                         evaluate: (input) => {
                             const frozenHelpers = createRuleHostHelpers(input);
                             // PRI-437: Execute inside vm context with timeout boundary.
@@ -269,16 +364,10 @@ export class RuleHost {
                     this._recordUnhealthy(activationId, artifactId, sourceRuleId ?? artifactId, reason, 'Fix the RuleCode syntax/compilation error, then re-activate the rule');
                 }
             }
+            this.activationFingerprint = fingerprint;
+            this.cachedImplementations = loaded;
             return loaded;
         }
-        finally {
-            try {
-                sqliteConn.close();
-            }
-            catch {
-                // best-effort cleanup
-            }
-        }
     }
     /**
      * PRI-437: Record an unhealthy activation state to EventLog.

package/dist/core/workspace-context.d.ts

@@ -8,6 +8,8 @@ import type { TrajectoryDatabase } from './trajectory.js';
 import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
 import { type PrincipleSubtree, type LedgerPrinciple, type PrincipleValueMetrics } from './principle-tree-ledger.js';
 import type { Principle as ActivePrinciple } from './evolution-types.js';
+import { RuleHost } from './rule-host.js';
+import type { RuleHostLogger } from './rule-host.js';
 interface PrincipleTreeLedgerAccessor {
     getPrincipleSubtree(_principleId: string): PrincipleSubtree | undefined;
     updatePrinciple(_principleId: string, updates: Partial<LedgerPrinciple>): LedgerPrinciple;
@@ -30,6 +32,7 @@ export declare class WorkspaceContext {
     private _trajectory?;
     private _principleTreeLedger?;
     private _principleLifecycle?;
+    private _ruleHost?;
     private constructor();
     /**
      * Governance configuration for this workspace.
@@ -55,6 +58,7 @@ export declare class WorkspaceContext {
      * Trajectory database for analytics and sample curation.
      */
     get trajectory(): TrajectoryDatabase;
+    getRuleHost(logger: RuleHostLogger): RuleHost;
     /**
      * Locked ledger access for principle tree reads and metric writes in this workspace.
      */

package/dist/core/workspace-context.js

@@ -9,6 +9,7 @@ import { EvolutionReducerImpl } from './evolution-reducer.js';
 import { TrajectoryRegistry } from './trajectory.js';
 import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
 import { getPrincipleSubtree, updatePrinciple, updatePrincipleValueMetrics, } from './principle-tree-ledger.js';
+import { RuleHost } from './rule-host.js';
 /**
  * WorkspaceContext - Centralized management of workspace-specific paths and services.
  * Implements a cached singleton pattern per workspace directory.
@@ -26,6 +27,7 @@ export class WorkspaceContext {
     _trajectory;
     _principleTreeLedger;
     _principleLifecycle;
+    _ruleHost;
     constructor(workspaceDir, stateDir) {
         this.workspaceDir = workspaceDir;
         this.stateDir = stateDir;
@@ -84,6 +86,15 @@ export class WorkspaceContext {
         }
         return this._trajectory;
     }
+    getRuleHost(logger) {
+        if (!this._ruleHost) {
+            this._ruleHost = new RuleHost(this.stateDir, logger, { workspaceDir: this.workspaceDir });
+        }
+        else {
+            this._ruleHost.updateLogger(logger);
+        }
+        return this._ruleHost;
+    }
     /**
      * Locked ledger access for principle tree reads and metric writes in this workspace.
      */
@@ -214,6 +225,8 @@ export class WorkspaceContext {
      * Resets internal caches for services and paths.
      */
     invalidate() {
+        this._ruleHost?.dispose();
+        this._ruleHost = undefined;
         this._config = undefined;
         this._eventLog = undefined;
         this._dictionary = undefined;

package/dist/hooks/gate.js

@@ -8,11 +8,9 @@
  * 1. Early Return: Skip if not write/bash/agent tool or no workspace
  * 2. Rule Host: Dynamic principle-based evaluation (sole gate)
  */
-import { normalizePath } from '../utils/io.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { recordGateBlockAndReturn } from './gate-block-helper.js';
-import { RuleHost } from '../core/rule-host.js';
-import { validateCorrectionProposal, validateProposedPathBounds, computeFeatureFlagsFromConfig, UNAVAILABLE_RULE_CONTEXT } from '@principles/core/runtime-v2';
+import { buildRuleHostAction, validateCorrectionProposal, validateProposedPathBounds, computeFeatureFlagsFromConfig, UNAVAILABLE_RULE_CONTEXT } from '@principles/core/runtime-v2';
 import { AGENT_TOOLS, BASH_TOOLS_SET, WRITE_TOOLS } from '../constants/tools.js';
 import { getSession, hasRecentThinking } from '../core/session-tracker.js';
 import { getEvolutionEngine } from '../core/evolution-engine.js';
@@ -30,41 +28,27 @@ export function handleBeforeToolCall(event, ctx) {
         return;
     }
     const wctx = WorkspaceContext.fromHookContext(ctx);
-    // 2. Resolve the target file path
-    let filePath = event.params?.file_path || event.params?.path || event.params?.file || event.params?.target;
-    // Heuristic for bash mutation detection
-    if (isBash && !filePath) {
-        const command = String(event.params?.command || event.params?.args || '');
-        const mutationMatch = /(?:>|>>|sed\s+-i|rm|mv|mkdir|touch|cp)\s+(?:-[a-zA-Z]+\s+)*([^\s;&|<>]+)/.exec(command);
-        if (mutationMatch) {
-            filePath = mutationMatch[1];
-        }
-        else {
-            // Bash command without a clear file target — let it through to Rule Host
-            filePath = command;
-        }
-    }
-    // Write tools without a file path must still go through RuleHost evaluation.
-    // Use a synthetic path so RuleHost can evaluate and potentially block.
-    if (!filePath && isWriteTool) {
-        filePath = `<tool:${event.toolName}>`;
-    }
-    if (typeof filePath !== 'string')
+    // 2. Use the same action builder as Golden Trace replay. This is the single
+    // path extraction + normalization contract for production and evaluation.
+    const action = buildRuleHostAction(event.toolName, event.params ?? {}, ctx.workspaceDir, {
+        isBashTool: isBash,
+        isWriteTool,
+    });
+    const relPath = action.normalizedPath;
+    // buildRuleHostAction returns null when no path can be extracted (e.g. bash
+    // command with no file target and no clear mutation operator). Mirror the
+    // legacy guard: no path → no gate evaluation, let the tool through.
+    if (relPath === null)
         return;
-    const relPath = normalizePath(filePath, ctx.workspaceDir);
     // 3. Rule Host Evaluation — sole gate
     try {
-        const ruleHost = new RuleHost(wctx.stateDir, logger, { workspaceDir: ctx.workspaceDir });
+        const ruleHost = wctx.getRuleHost(logger);
         // PRI-483 Phase 4: assemble RuleContextV2 when `rulecode_context_v2` flag is ON.
         // flag OFF → undefined (v1 zero-change, no trajectory access).
         // flag ON  → RuleContextV2 (available or unavailable). Never throws (ERR-024).
         const ruleContext = _buildRuleContextIfEnabled(wctx, relPath, ctx.sessionId, logger);
         const hostInput = {
-            action: {
-                toolName: event.toolName,
-                normalizedPath: relPath,
-                paramsSummary: _extractParamsSummary(event.params ?? {}),
-            },
+            action,
             workspace: {
                 isRiskPath: false, // Rule Host determines risk dynamically
                 // DEPRECATED (PRI-286): planStatus/hasPlanFile are legacy compatibility fields.
@@ -88,7 +72,27 @@ export function handleBeforeToolCall(event, ctx) {
             },
             context: ruleContext,
         };
-        const hostResult = ruleHost.evaluate(hostInput);
+        const report = typeof ruleHost.evaluateDetailed === 'function'
+            ? ruleHost.evaluateDetailed(hostInput)
+            : { liveDecision: ruleHost.evaluate(hostInput), shadowDecisions: [] };
+        const hostResult = report.liveDecision;
+        for (const shadowDecision of report.shadowDecisions) {
+            try {
+                const eventLog = EventLogService.get(wctx.stateDir, logger);
+                eventLog.recordRuleHostEvaluated({
+                    toolName: event.toolName,
+                    filePath: relPath,
+                    matched: shadowDecision.matched,
+                    decision: shadowDecision.decision,
+                    ruleId: shadowDecision.ruleId,
+                    activationId: shadowDecision.activationId,
+                    activationMode: 'shadow',
+                });
+            }
+            catch (evErr) {
+                logger?.warn?.(`[PD_GATE] Failed to record shadow rulehost_evaluated: ${String(evErr)}`);
+            }
+        }
         // Always emit rulehost_evaluated
         try {
             const eventLog = EventLogService.get(wctx.stateDir, logger);
@@ -98,6 +102,7 @@ export function handleBeforeToolCall(event, ctx) {
                 matched: hostResult?.matched ?? false,
                 decision: hostResult?.decision ?? 'allow',
                 ruleId: hostResult?.ruleId,
+                activationMode: 'live',
             });
         }
         catch (evErr) {
@@ -321,25 +326,6 @@ export function handleBeforeToolCall(event, ctx) {
 // ---------------------------------------------------------------------------
 // Private helpers
 // ---------------------------------------------------------------------------
-function _extractParamsSummary(params) {
-    const summary = {};
-    // NOTE: Do NOT redact here — this feeds into RuleHost.evaluate() which
-    // may match against paramsSummary.command. Redaction happens at
-    // EventLog.record() before persistence.
-    if (params.file_path)
-        summary.file_path = params.file_path;
-    if (params.path)
-        summary.path = params.path;
-    if (params.command)
-        summary.command = params.command;
-    if (params.args)
-        summary.args = params.args;
-    if (params.old_string)
-        summary.old_string = params.old_string;
-    if (params.new_string)
-        summary.new_string = params.new_string;
-    return summary;
-}
 function _getCurrentGfi(sessionId) {
     if (!sessionId)
         return 0;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.167.1",
+  "version": "1.168.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.167.1",
+  "version": "1.168.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/index.js",