@neurcode-ai/cli 0.16.4 → 0.16.6

package/dist/commands/session-hook.js

@@ -22,6 +22,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSessionForHook = resolveSessionForHook;
 exports.normalizeHookFilePathForRepo = normalizeHookFilePathForRepo;
 exports.hookFilePathCandidates = hookFilePathCandidates;
+exports.evaluateNoActiveSessionWrite = evaluateNoActiveSessionWrite;
 exports.shouldKeepSessionActiveForPendingApproval = shouldKeepSessionActiveForPendingApproval;
 exports.sessionHookCommand = sessionHookCommand;
 const child_process_1 = require("child_process");
@@ -41,6 +42,7 @@ const diff_parser_1 = require("@neurcode-ai/diff-parser");
 const structural_understanding_1 = require("../utils/structural-understanding");
 const consequence_nudges_1 = require("../utils/consequence-nudges");
 const agent_guard_supervisor_1 = require("../utils/agent-guard-supervisor");
+const local_repo_brain_1 = require("../utils/local-repo-brain");
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /** Read the full hook JSON from stdin, or return {} on any error. */
 function readHookInput() {
@@ -145,6 +147,41 @@ function sessionAlreadyEmittedNudge(session, nudgeKey) {
         typeof event.detail === 'object' &&
         event.detail['nudgeKey'] === nudgeKey);
 }
+function reuseNudgeKey(artifactHash, finding) {
+    return [
+        'reuse',
+        artifactHash,
+        finding.changed.file,
+        finding.changed.name,
+        finding.existing.file,
+        finding.existing.name,
+        finding.matchType,
+    ].join(':');
+}
+function formatReuseNudge(finding) {
+    return finding.message;
+}
+function reuseNudgeFromArtifact(artifactHash, findings) {
+    const [finding] = findings;
+    if (!finding)
+        return null;
+    return {
+        nudgeVersion: 'reuse-v1',
+        nudgeKey: reuseNudgeKey(artifactHash, finding),
+        severity: 'medium',
+        headline: formatReuseNudge(finding),
+        consequenceClass: 'repo-reuse',
+        operatorAction: 'Review the existing helper before merging; reuse or intentionally explain the duplicate.',
+        reviewFocus: [finding.changed.file, finding.existing.file],
+        artifactHash,
+        reuseFinding: finding,
+        surfacedReuseFindings: findings.slice(0, 3),
+        provenance: 'deterministic-static',
+    };
+}
+function isReuseNudge(nudge) {
+    return nudge.nudgeVersion === 'reuse-v1';
+}
 function readWorkingDiff(repoRoot) {
     return (0, child_process_1.execFileSync)('git', ['-C', repoRoot, 'diff', '--no-ext-diff', 'HEAD'], {
         encoding: 'utf8',
@@ -167,10 +204,12 @@ async function maybeRecordConsequenceNudge(repoRoot, session) {
         });
         const nudges = (0, consequence_nudges_1.selectInFlowConsequenceNudges)(artifact, { max: 3 });
         const [nudge] = nudges;
-        if (!nudge)
+        const reuseNudge = reuseNudgeFromArtifact(artifact.artifactHash, artifact.reuseFindings);
+        const selectedNudge = nudge ?? reuseNudge;
+        if (!selectedNudge)
             return null;
         const latest = (0, governance_runtime_1.loadSession)(repoRoot, session.sessionId) || session;
-        if (sessionAlreadyEmittedNudge(latest, nudge.nudgeKey))
+        if (sessionAlreadyEmittedNudge(latest, selectedNudge.nudgeKey))
             return null;
         const artifactPath = (0, structural_understanding_1.writeStructuralUnderstanding)(repoRoot, session.sessionId, artifact);
         (0, governance_runtime_1.appendEvent)(repoRoot, session.sessionId, {
@@ -187,6 +226,8 @@ async function maybeRecordConsequenceNudge(repoRoot, session) {
                 changedFiles: artifact.changedFiles,
                 changedSymbols: artifact.changedSymbols,
                 digest: artifact.digest,
+                repoSymbolIndex: artifact.repoSymbolIndex,
+                reuseFindings: artifact.reuseFindings,
                 boundaryImpact: artifact.boundaryImpact,
                 suppressedArtifacts: artifact.suppressedArtifacts,
                 consequenceUnderstanding: {
@@ -204,103 +245,120 @@ async function maybeRecordConsequenceNudge(repoRoot, session) {
         (0, governance_runtime_1.appendEvent)(repoRoot, session.sessionId, {
             type: 'consequence_nudge',
             ts: new Date().toISOString(),
-            message: nudge.headline,
+            message: (nudge ?? reuseNudge)?.headline ?? 'Structural advisory recorded.',
             detail: {
-                nudgeVersion: nudge.nudgeVersion,
-                nudgeKey: nudge.nudgeKey,
-                severity: nudge.severity,
-                consequenceClass: nudge.consequenceClass,
-                operatorAction: nudge.operatorAction,
-                reviewFocus: nudge.reviewFocus,
-                artifactHash: nudge.artifactHash,
-                impact: nudge.impact ? {
-                    rank: nudge.impact.rank,
-                    score: nudge.impact.score,
-                    file: nudge.impact.file,
-                    symbol: nudge.impact.symbol,
-                    summary: nudge.impact.summary,
-                    findingTypes: nudge.impact.findingTypes,
-                    findingRanks: nudge.impact.findingRanks,
-                    findingCount: nudge.impact.findingCount,
-                    productionConsumerCount: nudge.impact.productionConsumerCount,
-                    testConsumerCount: nudge.impact.testConsumerCount,
-                    reachableProductionConsumerCount: nudge.impact.reachableProductionConsumerCount,
-                    externalProductionConsumerCount: nudge.impact.externalProductionConsumerCount,
-                    changedProductionConsumerCount: nudge.impact.changedProductionConsumerCount,
-                    sensitiveConsumerCount: nudge.impact.sensitiveConsumerCount,
-                    approvalRequiredConsumerCount: nudge.impact.approvalRequiredConsumerCount,
-                    runtimeGovernanceConsumerCount: nudge.impact.runtimeGovernanceConsumerCount,
-                    productionFiles: nudge.impact.productionFiles,
-                    changedProductionFiles: nudge.impact.changedProductionFiles,
-                    testFiles: nudge.impact.testFiles,
-                    sensitiveFiles: nudge.impact.sensitiveFiles,
-                    approvalRequiredFiles: nudge.impact.approvalRequiredFiles,
-                    runtimeGovernanceFiles: nudge.impact.runtimeGovernanceFiles,
-                    highFanout: nudge.impact.highFanout,
-                    architectureRelevant: nudge.impact.architectureRelevant,
-                    reasonCodes: nudge.impact.reasonCodes,
-                    provenance: nudge.impact.provenance,
-                } : null,
-                finding: {
-                    rank: nudge.finding.rank,
-                    score: nudge.finding.score,
-                    findingType: nudge.finding.findingType,
-                    file: nudge.finding.file,
-                    symbol: nudge.finding.symbol,
-                    summary: nudge.finding.summary,
-                    consumerCount: nudge.finding.consumerCount,
-                    nonTestConsumerCount: nudge.finding.nonTestConsumerCount,
-                    testConsumerCount: nudge.finding.testConsumerCount,
-                    externalConsumerCount: nudge.finding.externalConsumerCount,
-                    externalConsumerFiles: nudge.finding.externalConsumerFiles,
-                    consumerSummary: nudge.finding.consumerSummary,
-                    reasonCodes: nudge.finding.reasonCodes,
-                },
-                topImpacts: nudges
-                    .map((item) => item.impact)
-                    .filter((impact) => Boolean(impact))
-                    .map((impact) => ({
-                    rank: impact.rank,
-                    score: impact.score,
-                    file: impact.file,
-                    symbol: impact.symbol,
-                    summary: impact.summary,
-                    findingTypes: impact.findingTypes,
-                    findingCount: impact.findingCount,
-                    reachableProductionConsumerCount: impact.reachableProductionConsumerCount,
-                    externalProductionConsumerCount: impact.externalProductionConsumerCount,
-                    changedProductionConsumerCount: impact.changedProductionConsumerCount,
-                    productionFiles: impact.productionFiles,
-                    changedProductionFiles: impact.changedProductionFiles,
-                    sensitiveConsumerCount: impact.sensitiveConsumerCount,
-                    approvalRequiredConsumerCount: impact.approvalRequiredConsumerCount,
-                    runtimeGovernanceConsumerCount: impact.runtimeGovernanceConsumerCount,
-                    highFanout: impact.highFanout,
-                    architectureRelevant: impact.architectureRelevant,
-                    reasonCodes: impact.reasonCodes,
-                })),
-                topFindings: nudges.map((item) => ({
-                    nudgeKey: item.nudgeKey,
-                    severity: item.severity,
-                    consequenceClass: item.consequenceClass,
-                    operatorAction: item.operatorAction,
-                    reviewFocus: item.reviewFocus,
-                    findingType: item.finding.findingType,
-                    file: item.finding.file,
-                    symbol: item.finding.symbol,
-                    externalConsumerCount: item.finding.externalConsumerCount,
-                    externalConsumerFiles: item.finding.externalConsumerFiles,
-                    consumerSummary: item.finding.consumerSummary,
-                    reasonCodes: item.finding.reasonCodes,
-                })),
-                provenance: nudge.provenance,
+                ...(nudge
+                    ? {
+                        nudgeVersion: nudge.nudgeVersion,
+                        nudgeKey: nudge.nudgeKey,
+                        severity: nudge.severity,
+                        consequenceClass: nudge.consequenceClass,
+                        operatorAction: nudge.operatorAction,
+                        reviewFocus: nudge.reviewFocus,
+                        artifactHash: nudge.artifactHash,
+                        impact: nudge.impact ? {
+                            rank: nudge.impact.rank,
+                            score: nudge.impact.score,
+                            file: nudge.impact.file,
+                            symbol: nudge.impact.symbol,
+                            summary: nudge.impact.summary,
+                            findingTypes: nudge.impact.findingTypes,
+                            findingRanks: nudge.impact.findingRanks,
+                            findingCount: nudge.impact.findingCount,
+                            productionConsumerCount: nudge.impact.productionConsumerCount,
+                            testConsumerCount: nudge.impact.testConsumerCount,
+                            reachableProductionConsumerCount: nudge.impact.reachableProductionConsumerCount,
+                            externalProductionConsumerCount: nudge.impact.externalProductionConsumerCount,
+                            changedProductionConsumerCount: nudge.impact.changedProductionConsumerCount,
+                            sensitiveConsumerCount: nudge.impact.sensitiveConsumerCount,
+                            approvalRequiredConsumerCount: nudge.impact.approvalRequiredConsumerCount,
+                            runtimeGovernanceConsumerCount: nudge.impact.runtimeGovernanceConsumerCount,
+                            productionFiles: nudge.impact.productionFiles,
+                            changedProductionFiles: nudge.impact.changedProductionFiles,
+                            testFiles: nudge.impact.testFiles,
+                            sensitiveFiles: nudge.impact.sensitiveFiles,
+                            approvalRequiredFiles: nudge.impact.approvalRequiredFiles,
+                            runtimeGovernanceFiles: nudge.impact.runtimeGovernanceFiles,
+                            highFanout: nudge.impact.highFanout,
+                            architectureRelevant: nudge.impact.architectureRelevant,
+                            reasonCodes: nudge.impact.reasonCodes,
+                            provenance: nudge.impact.provenance,
+                        } : null,
+                        finding: {
+                            rank: nudge.finding.rank,
+                            score: nudge.finding.score,
+                            findingType: nudge.finding.findingType,
+                            file: nudge.finding.file,
+                            symbol: nudge.finding.symbol,
+                            summary: nudge.finding.summary,
+                            consumerCount: nudge.finding.consumerCount,
+                            nonTestConsumerCount: nudge.finding.nonTestConsumerCount,
+                            testConsumerCount: nudge.finding.testConsumerCount,
+                            externalConsumerCount: nudge.finding.externalConsumerCount,
+                            externalConsumerFiles: nudge.finding.externalConsumerFiles,
+                            consumerSummary: nudge.finding.consumerSummary,
+                            reasonCodes: nudge.finding.reasonCodes,
+                        },
+                        topImpacts: nudges
+                            .map((item) => item.impact)
+                            .filter((impact) => Boolean(impact))
+                            .map((impact) => ({
+                            rank: impact.rank,
+                            score: impact.score,
+                            file: impact.file,
+                            symbol: impact.symbol,
+                            summary: impact.summary,
+                            findingTypes: impact.findingTypes,
+                            findingCount: impact.findingCount,
+                            reachableProductionConsumerCount: impact.reachableProductionConsumerCount,
+                            externalProductionConsumerCount: impact.externalProductionConsumerCount,
+                            changedProductionConsumerCount: impact.changedProductionConsumerCount,
+                            productionFiles: impact.productionFiles,
+                            changedProductionFiles: impact.changedProductionFiles,
+                            sensitiveConsumerCount: impact.sensitiveConsumerCount,
+                            approvalRequiredConsumerCount: impact.approvalRequiredConsumerCount,
+                            runtimeGovernanceConsumerCount: impact.runtimeGovernanceConsumerCount,
+                            highFanout: impact.highFanout,
+                            architectureRelevant: impact.architectureRelevant,
+                            reasonCodes: impact.reasonCodes,
+                        })),
+                        topFindings: nudges.map((item) => ({
+                            nudgeKey: item.nudgeKey,
+                            severity: item.severity,
+                            consequenceClass: item.consequenceClass,
+                            operatorAction: item.operatorAction,
+                            reviewFocus: item.reviewFocus,
+                            findingType: item.finding.findingType,
+                            file: item.finding.file,
+                            symbol: item.finding.symbol,
+                            externalConsumerCount: item.finding.externalConsumerCount,
+                            externalConsumerFiles: item.finding.externalConsumerFiles,
+                            consumerSummary: item.finding.consumerSummary,
+                            reasonCodes: item.finding.reasonCodes,
+                        })),
+                        provenance: nudge.provenance,
+                    }
+                    : reuseNudge
+                        ? {
+                            nudgeVersion: reuseNudge.nudgeVersion,
+                            nudgeKey: reuseNudge.nudgeKey,
+                            severity: reuseNudge.severity,
+                            consequenceClass: reuseNudge.consequenceClass,
+                            operatorAction: reuseNudge.operatorAction,
+                            reviewFocus: reuseNudge.reviewFocus,
+                            artifactHash: reuseNudge.artifactHash,
+                            reuseFinding: reuseNudge.reuseFinding,
+                            topReuseFindings: reuseNudge.surfacedReuseFindings,
+                            provenance: reuseNudge.provenance,
+                        }
+                        : {}),
                 killSwitch: 'NEURCODE_DISABLE_CONSEQUENCE_NUDGES=1',
             },
         });
         const refreshed = (0, governance_runtime_1.loadSession)(repoRoot, session.sessionId);
         if (refreshed)
             await (0, runtime_live_1.publishRuntimeLiveStatus)(repoRoot, refreshed);
-        return nudge;
+        return nudge ?? reuseNudge;
     }
     catch (error) {
         diagnostic(`consequence nudge skipped: ${error instanceof Error ? error.message : String(error)}`);
@@ -351,15 +409,117 @@ function hookFilePathCandidates(hookInput) {
     }
     return Array.from(new Set(candidates));
 }
-function latestUnresolvedApprovalBlock(session) {
+function runtimeMode(session) {
+    return session.contract.runtimeMode === 'strict' ||
+        session.contract.runtimeMode === 'paused' ||
+        session.contract.runtimeMode === 'advisory'
+        ? session.contract.runtimeMode
+        : 'strict';
+}
+function blockContext(input) {
+    const isApproval = input.blockType === 'approval_required_boundary';
+    const isScope = input.blockType === 'scope_violation_or_task_expansion';
+    return {
+        schemaVersion: 'neurcode.runtime-block.v1',
+        blockType: input.blockType,
+        filePath: input.filePath || null,
+        message: input.message || null,
+        runtimeMode: input.runtimeMode || null,
+        operatorActionKind: isApproval
+            ? 'exact_path_approval'
+            : isScope
+                ? 'scope_amendment'
+                : input.blockType === 'profile_or_runtime_health_block'
+                    ? 'runtime_health_recovery'
+                    : 'split_tool_call',
+        operatorActionLabel: isApproval
+            ? 'Approve exact path / Deny'
+            : isScope
+                ? 'Approve task expansion / Amend scope / Deny'
+                : input.blockType === 'profile_or_runtime_health_block'
+                    ? 'Refresh or restart runtime'
+                    : 'Split into one file per tool call',
+        suggestedApprovalPath: isApproval ? input.suggestedApprovalPath || input.filePath || null : null,
+        owners: input.owners || [],
+        proposalId: input.proposalId || null,
+        nextAction: input.nextAction || (isApproval
+            ? 'Approve only the exact path for this session, or deny the write.'
+            : isScope
+                ? 'Accept the pending scope amendment or re-plan locally, then retry the write.'
+                : input.blockType === 'profile_or_runtime_health_block'
+                    ? 'Refresh the governance profile or restart the active governed session.'
+                    : 'Retry as separate single-file edits so each path can be governed.'),
+    };
+}
+const NO_ACTIVE_SESSION_SCOPE_SENTINEL = '__neurcode_no_active_session_scope__';
+function evaluateNoActiveSessionWrite(repoRoot, filePath) {
+    const profile = (0, v0_governance_1.ensureFreshGovernanceProfile)(repoRoot).profile;
+    const result = (0, governance_runtime_1.checkFileBoundary)({
+        filePath,
+        allowedGlobs: [NO_ACTIVE_SESSION_SCOPE_SENTINEL],
+        ownershipRules: profile.ownershipBoundaries,
+        sensitiveGlobs: profile.sensitiveBoundaries.map((boundary) => boundary.glob),
+        approvalRequiredGlobs: profile.approvalRequiredPaths,
+        approvedPaths: [],
+        approvalGrants: [],
+        scopeMode: 'explicit',
+        localMode: 'strict',
+    });
+    const protectedPath = result.isApprovalRequired || result.isSensitive || result.owners.length > 0;
+    const ownerNote = result.owners.length ? ` Owners: ${result.owners.join(', ')}.` : '';
+    const message = protectedPath
+        ? `⏸ Neurcode: no active governed session is running, so protected path ${filePath} cannot be checked or approved safely.${ownerNote} Start a governed session with \`neurcode session-hook start\`/agent activation, or run \`neurcode doctor --runtime\` for recovery before retrying.`
+        : `No active governed session at ${repoRoot}; ${filePath} is not a detected protected path and is allowed advisory-only.`;
+    return {
+        block: protectedPath,
+        filePath,
+        result,
+        message,
+    };
+}
+function blockTypeFromEvent(event) {
+    const detail = event.detail || {};
+    const context = detail.blockContext;
+    if (context && typeof context === 'object') {
+        const value = context.blockType;
+        if (value === 'approval_required_boundary' ||
+            value === 'scope_violation_or_task_expansion' ||
+            value === 'profile_or_runtime_health_block' ||
+            value === 'multi_file_or_tool_shape_block') {
+            return value;
+        }
+    }
+    if (detail.approvalContext)
+        return 'approval_required_boundary';
+    if (detail.profileFreshness)
+        return 'profile_or_runtime_health_block';
+    if (detail.reason === 'multi_file_tool_call_requires_split')
+        return 'multi_file_or_tool_shape_block';
+    return 'scope_violation_or_task_expansion';
+}
+function latestUnresolvedActionableBlock(session) {
     for (let i = session.events.length - 1; i >= 0; i -= 1) {
         const event = session.events[i];
+        if (event.type === 'check_ok' || event.type === 'check_warn' || event.type === 'plan_amended') {
+            return null;
+        }
         if (event.type !== 'check_block')
             continue;
-        const context = event.detail?.approvalContext;
+        const detail = event.detail;
+        const context = detail?.approvalContext;
         const blockedPath = event.filePath || context?.blockedPath || context?.suggestedApprovalPath;
         if (!blockedPath)
             continue;
+        const blockType = blockTypeFromEvent(event);
+        if (blockType !== 'approval_required_boundary') {
+            return {
+                filePath: blockedPath,
+                blockType,
+                suggestedApprovalPath: detail?.blockContext?.suggestedApprovalPath || null,
+                proposalId: detail?.blockContext?.proposalId || null,
+                message: event.message || null,
+            };
+        }
         const verdict = (0, governance_runtime_1.checkFileBoundary)({
             filePath: blockedPath,
             allowedGlobs: session.contract.allowedGlobs,
@@ -369,11 +529,14 @@ function latestUnresolvedApprovalBlock(session) {
             approvedPaths: session.contract.approvedPaths,
             approvalGrants: session.contract.approvalGrants,
             scopeMode: session.contract.scopeMode,
+            localMode: runtimeMode(session),
         });
         if (verdict.verdict === 'block' && verdict.approvalContext) {
             return {
                 filePath: blockedPath,
+                blockType: 'approval_required_boundary',
                 suggestedApprovalPath: verdict.approvalContext.suggestedApprovalPath || context?.suggestedApprovalPath || blockedPath,
+                message: event.message || null,
             };
         }
         return null;
@@ -383,6 +546,9 @@ function latestUnresolvedApprovalBlock(session) {
 function shouldKeepSessionActiveForPendingApproval(session, pendingApproval) {
     if (!pendingApproval)
         return false;
+    if (pendingApproval.blockType && pendingApproval.blockType !== 'approval_required_boundary') {
+        return true;
+    }
     const hasRecordedApproval = session.contract.approvedPaths.length > 0 ||
         (session.contract.approvalGrants ?? []).some((grant) => !grant.revokedAt) ||
         session.events.some((event) => event.type === 'approval_decision' && event.decision === 'approved');
@@ -397,6 +563,7 @@ async function recordBashCheck(repoRoot, session, args) {
         message: args.message,
         detail: {
             ...(args.approvalContext ? { approvalContext: args.approvalContext } : {}),
+            ...(args.blockContext ? { blockContext: args.blockContext } : {}),
             toolName: 'Bash',
             bash: {
                 operation: args.operation,
@@ -445,6 +612,7 @@ async function handleBashCheck(repoRoot, session, command) {
             approvedPaths: session.contract.approvedPaths,
             approvalGrants: session.contract.approvalGrants,
             scopeMode: session.contract.scopeMode,
+            localMode: runtimeMode(session),
         }),
     }));
     for (const { filePath, result } of results) {
@@ -457,13 +625,37 @@ async function handleBashCheck(repoRoot, session, command) {
             commandFingerprint: analysis.commandFingerprint,
             boundaryVerdict: result.verdict,
             approvalContext: result.approvalContext,
+            blockContext: result.blockType
+                ? blockContext({
+                    blockType: result.blockType,
+                    filePath,
+                    message: result.message,
+                    suggestedApprovalPath: result.approvalContext?.suggestedApprovalPath,
+                    owners: result.owners,
+                    runtimeMode: runtimeMode(session),
+                })
+                : undefined,
         });
     }
     const blocking = results.find(({ result }) => result.verdict === 'block');
     if (blocking) {
         const message = `⏸ Neurcode: Bash ${analysis.operation} targets ${blocking.filePath}. ` +
             blocking.result.message.replace(/^⏸ Neurcode:\s*/, '');
-        denyPreToolUse(message, blocking.result.approvalContext ? { approvalContext: blocking.result.approvalContext } : undefined);
+        denyPreToolUse(message, {
+            ...(blocking.result.approvalContext ? { approvalContext: blocking.result.approvalContext } : {}),
+            ...(blocking.result.blockType
+                ? {
+                    blockContext: blockContext({
+                        blockType: blocking.result.blockType,
+                        filePath: blocking.filePath,
+                        message,
+                        suggestedApprovalPath: blocking.result.approvalContext?.suggestedApprovalPath,
+                        owners: blocking.result.owners,
+                        runtimeMode: runtimeMode(session),
+                    }),
+                }
+                : {}),
+        });
     }
     const warning = results.find(({ result }) => result.verdict === 'warn');
     if (warning) {
@@ -710,13 +902,53 @@ async function handleCheck(cmdCwd) {
     const repoRoot = (0, v0_governance_1.resolveRepoRoot)(effectiveCwd);
     (0, hook_heartbeat_1.recordHookHeartbeat)({ repoRoot, eventType: 'check' });
     const requestedSessionId = sessionIdFromHookInput(hookInput);
+    const toolName = hookInput['tool_name'] ||
+        hookInput['toolName'] ||
+        '';
+    const toolInput = hookInput['tool_input'] ??
+        hookInput['toolInput'] ??
+        {};
     const resolution = resolveSessionForHook(repoRoot, requestedSessionId);
     const activeSession = resolution.session;
     if (!activeSession) {
-        // No active session — not governed, pass through
+        const rawPaths = hookFilePathCandidates(hookInput);
+        const bashLike = /^(bash|shell|runCommand|run_command|runInTerminal|run_in_terminal|terminal)$/i.test(toolName);
+        const bashAnalysis = bashLike
+            ? (0, bash_command_analysis_1.analyzeBashCommand)(toolInput['command'] ||
+                toolInput['cmd'] ||
+                hookInput['command'] ||
+                '')
+            : null;
+        const candidatePaths = bashAnalysis?.mutates
+            ? bashAnalysis.targetPaths
+            : rawPaths;
+        const normalizedPaths = Array.from(new Set(candidatePaths.map((path) => normalizeHookFilePathForRepo(path, repoRoot))));
+        for (const filePath of normalizedPaths) {
+            try {
+                const decision = evaluateNoActiveSessionWrite(repoRoot, filePath);
+                if (decision.block) {
+                    denyPreToolUse(decision.message, {
+                        ...(decision.result.approvalContext ? { approvalContext: decision.result.approvalContext } : {}),
+                        blockContext: blockContext({
+                            blockType: 'profile_or_runtime_health_block',
+                            filePath,
+                            message: decision.message,
+                            suggestedApprovalPath: decision.result.approvalContext?.suggestedApprovalPath,
+                            owners: decision.result.owners,
+                            runtimeMode: 'strict',
+                            nextAction: 'Start or resume a governed Neurcode session, then retry this protected path.',
+                        }),
+                    });
+                }
+            }
+            catch (error) {
+                diagnostic(`no-active-session protected-path check skipped: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const targetNote = normalizedPaths.length > 0 ? ` for ${normalizedPaths.join(', ')}` : '';
         diagnostic(requestedSessionId
-            ? `no active session ${requestedSessionId} at ${repoRoot} — edit allowed (ungoverned)`
-            : `no active session at ${repoRoot} — edit allowed (ungoverned)`);
+            ? `no active session ${requestedSessionId} at ${repoRoot} — edit allowed advisory-only${targetNote}`
+            : `no active session at ${repoRoot} — edit allowed advisory-only${targetNote}`);
         process.exit(0);
         return;
     }
@@ -728,7 +960,7 @@ async function handleCheck(cmdCwd) {
         const hasPriorBlock = session.events.some((event) => event.type === 'check_block');
         if (hasPriorBlock) {
             const pending = await (0, runtime_live_1.applyPendingRuntimeLiveApprovals)(repoRoot, session.sessionId);
-            if (pending.applied > 0 || pending.revoked > 0) {
+            if (pending.applied > 0 || pending.revoked > 0 || pending.scopeAmended > 0 || pending.scopeDenied > 0) {
                 const refreshed = (0, governance_runtime_1.loadSession)(repoRoot, session.sessionId);
                 if (refreshed)
                     session = refreshed;
@@ -739,6 +971,12 @@ async function handleCheck(cmdCwd) {
             if (pending.revoked > 0) {
                 diagnostic(`revoked ${pending.revoked} dashboard approval${pending.revoked === 1 ? '' : 's'}`);
             }
+            if (pending.scopeAmended > 0) {
+                diagnostic(`applied ${pending.scopeAmended} dashboard scope amendment${pending.scopeAmended === 1 ? '' : 's'}`);
+            }
+            if (pending.scopeDenied > 0) {
+                diagnostic(`recorded ${pending.scopeDenied} denied dashboard scope amendment${pending.scopeDenied === 1 ? '' : 's'}`);
+            }
         }
     }
     catch {
@@ -776,12 +1014,6 @@ async function handleCheck(cmdCwd) {
     // ── Extract the target file path ─────────────────────────────────────────
     // Claude Code PreToolUse payload shape:
     //   { tool_name, tool_input: { path, ... }, cwd, ... }
-    const toolName = hookInput['tool_name'] ||
-        hookInput['toolName'] ||
-        '';
-    const toolInput = hookInput['tool_input'] ??
-        hookInput['toolInput'] ??
-        {};
     if (/^(bash|shell|runCommand|run_command|runInTerminal|run_in_terminal|terminal)$/i.test(toolName)) {
         const command = toolInput['command'] ||
             toolInput['cmd'] ||
@@ -802,6 +1034,12 @@ async function handleCheck(cmdCwd) {
                 verdict: 'block',
                 message,
                 detail: {
+                    blockContext: blockContext({
+                        blockType: 'multi_file_or_tool_shape_block',
+                        filePath: rawPaths.map((path) => normalizeHookFilePathForRepo(path, repoRoot)).join(','),
+                        message,
+                        runtimeMode: runtimeMode(session),
+                    }),
                     reason: 'multi_file_tool_call_requires_split',
                     paths: rawPaths.map((path) => normalizeHookFilePathForRepo(path, repoRoot)),
                     toolName,
@@ -815,6 +1053,12 @@ async function handleCheck(cmdCwd) {
             // Recording failure must not weaken the deny.
         }
         denyPreToolUse(message, {
+            blockContext: blockContext({
+                blockType: 'multi_file_or_tool_shape_block',
+                filePath: rawPaths.map((path) => normalizeHookFilePathForRepo(path, repoRoot)).join(','),
+                message,
+                runtimeMode: runtimeMode(session),
+            }),
             reason: 'multi_file_tool_call_requires_split',
             paths: rawPaths.map((path) => normalizeHookFilePathForRepo(path, repoRoot)),
         });
@@ -864,7 +1108,15 @@ async function handleCheck(cmdCwd) {
                     filePath,
                     verdict: 'block',
                     message,
-                    detail: { profileFreshness },
+                    detail: {
+                        profileFreshness,
+                        blockContext: blockContext({
+                            blockType: 'profile_or_runtime_health_block',
+                            filePath,
+                            message,
+                            runtimeMode: runtimeMode(session),
+                        }),
+                    },
                 });
                 const refreshedSession = (0, governance_runtime_1.loadSession)(repoRoot, session.sessionId);
                 if (refreshedSession) {
@@ -874,7 +1126,15 @@ async function handleCheck(cmdCwd) {
             catch {
                 // Recording failure must not weaken the deny.
             }
-            denyPreToolUse(message, { profileFreshness });
+            denyPreToolUse(message, {
+                profileFreshness,
+                blockContext: blockContext({
+                    blockType: 'profile_or_runtime_health_block',
+                    filePath,
+                    message,
+                    runtimeMode: runtimeMode(session),
+                }),
+            });
         }
         if (staleness.status !== 'fresh') {
             const refreshedProfile = (0, v0_governance_1.ensureFreshGovernanceProfile)(repoRoot);
@@ -899,6 +1159,12 @@ async function handleCheck(cmdCwd) {
                 verdict: 'block',
                 message,
                 detail: {
+                    blockContext: blockContext({
+                        blockType: 'profile_or_runtime_health_block',
+                        filePath,
+                        message,
+                        runtimeMode: runtimeMode(session),
+                    }),
                     profileFreshness: {
                         status: 'unreadable',
                         refreshed: false,
@@ -919,7 +1185,14 @@ async function handleCheck(cmdCwd) {
         catch {
             // Recording failure must not weaken the deny.
         }
-        denyPreToolUse(message);
+        denyPreToolUse(message, {
+            blockContext: blockContext({
+                blockType: 'profile_or_runtime_health_block',
+                filePath,
+                message,
+                runtimeMode: runtimeMode(session),
+            }),
+        });
     }
     // ── Run the boundary + intent-coherence checks ───────────────────────────
     let result;
@@ -933,6 +1206,7 @@ async function handleCheck(cmdCwd) {
             approvedPaths: session.contract.approvedPaths,
             approvalGrants: session.contract.approvalGrants,
             scopeMode: session.contract.scopeMode,
+            localMode: runtimeMode(session),
         });
     }
     catch (err) {
@@ -963,19 +1237,50 @@ async function handleCheck(cmdCwd) {
         graph: session.contract.architectureGraph,
         obligations: session.contract.architectureObligations ?? [],
     });
-    if (result.verdict === 'ok' && planCoherencePolicy.action === 'block') {
+    let pendingScopeAmendmentProposalId = null;
+    if (result.verdict === 'ok' && planCoherencePolicy.action === 'block' && runtimeMode(session) !== 'strict') {
+        result = {
+            ...result,
+            verdict: 'warn',
+            blockType: 'scope_violation_or_task_expansion',
+            message: `⚠️ Neurcode: ${filePath} is not justified by the agent's stated plan. ` +
+                `${planCoherencePolicy.reason} Proceeding in ${runtimeMode(session)} mode — recorded as task expansion evidence. ` +
+                `Re-plan with neurcode_session_replan if this path should become part of the task.`,
+        };
+    }
+    else if (result.verdict === 'ok' && planCoherencePolicy.action === 'block') {
+        try {
+            const amendment = (0, governance_runtime_1.amendAgentPlan)(repoRoot, {
+                sessionId: session.sessionId,
+                addExpectedFiles: [filePath],
+                addSteps: [`Expand governed task scope to include ${filePath}`],
+                reason: `scope expansion requested for ${filePath}`,
+                source: 'unknown',
+                proposedBy: 'agent',
+                amendedAt: new Date().toISOString(),
+            });
+            pendingScopeAmendmentProposalId = amendment.proposal?.proposalId || amendment.eventId || null;
+            const amendedSession = (0, governance_runtime_1.loadSession)(repoRoot, session.sessionId);
+            if (amendedSession)
+                session = amendedSession;
+        }
+        catch (error) {
+            diagnostic(`scope amendment proposal could not be recorded: ${error instanceof Error ? error.message : String(error)}`);
+        }
         result = {
             ...result,
             verdict: 'block',
+            blockType: 'scope_violation_or_task_expansion',
             message: `⏸ Neurcode: ${filePath} is not justified by the agent's stated plan. ` +
-                `${planCoherencePolicy.reason} Re-plan or update the plan before editing this path. ` +
-                `Use neurcode_session_replan or \`neurcode session replan --add-file ${filePath}\`.`,
+                `${planCoherencePolicy.reason} Approve task expansion / amend scope, then retry this path. ` +
+                `Use neurcode_session_replan_decide${pendingScopeAmendmentProposalId ? ` for ${pendingScopeAmendmentProposalId}` : ''} or \`neurcode session replan --add-file ${filePath}\`.`,
         };
     }
     else if (result.verdict === 'ok' && architectureObligationFeedback.action === 'block') {
         result = {
             ...result,
             verdict: 'block',
+            blockType: 'scope_violation_or_task_expansion',
             message: `⏸ Neurcode: ${filePath} is blocked by ${architectureObligationFeedback.blocking.length} ` +
                 `architecture obligation${architectureObligationFeedback.blocking.length === 1 ? '' : 's'}. ` +
                 `${architectureObligationFeedback.reasons[0]} Satisfy the obligation, re-plan, or ask the human to waive it with ` +
@@ -1024,6 +1329,19 @@ async function handleCheck(cmdCwd) {
             message: result.message,
             detail: {
                 ...(result.approvalContext ? { approvalContext: result.approvalContext } : {}),
+                ...(result.blockType
+                    ? {
+                        blockContext: blockContext({
+                            blockType: result.blockType,
+                            filePath,
+                            message: result.message,
+                            suggestedApprovalPath: result.approvalContext?.suggestedApprovalPath,
+                            owners: result.owners,
+                            proposalId: pendingScopeAmendmentProposalId,
+                            runtimeMode: runtimeMode(session),
+                        }),
+                    }
+                    : {}),
                 intentCoherence,
                 planCoherence,
                 planCoherencePolicy,
@@ -1052,11 +1370,66 @@ async function handleCheck(cmdCwd) {
     const consequenceNudge = result.verdict === 'block'
         ? null
         : await maybeRecordConsequenceNudge(repoRoot, session);
+    // ── Repo brain facts (P0/P1) ─────────────────────────────────────────────
+    // Load source-free repo context for the blocked/warned path. Best-effort:
+    // if the artifact is missing the message is unchanged and recovery guidance
+    // is appended instead.
+    let repoBrainFileFacts = null;
+    let repoBrainMeta = {
+        artifactHash: null,
+        generatedAt: null,
+        status: 'missing',
+    };
+    try {
+        const brainCtx = (0, local_repo_brain_1.getRepoBrainContext)(repoRoot, [filePath]);
+        repoBrainMeta = { artifactHash: brainCtx.artifactHash, generatedAt: brainCtx.generatedAt, status: brainCtx.status };
+        repoBrainFileFacts = brainCtx.files[0] ?? null;
+    }
+    catch {
+        // Never let brain context loading break the enforcement path.
+    }
     // ── Emit hook response ────────────────────────────────────────────────────
     if (result.verdict === 'block') {
+        // Enrich deny message with source-free repo facts (P1).
+        const brainSuffix = repoBrainFileFacts
+            ? (0, local_repo_brain_1.formatRepoBrainFactsForMessage)(repoBrainFileFacts)
+            : repoBrainMeta.status === 'missing'
+                ? 'Run `neurcode brain index` for local source-free repo context.'
+                : '';
+        const enrichedMessage = brainSuffix
+            ? `${result.message} | ${brainSuffix}`
+            : result.message;
         // Include machine-readable approvalContext when the block is approval-required,
         // so the agent can surface a structured approval request to the human.
-        denyPreToolUse(result.message, result.approvalContext ? { approvalContext: result.approvalContext } : undefined);
+        denyPreToolUse(enrichedMessage, {
+            ...(result.approvalContext ? { approvalContext: result.approvalContext } : {}),
+            ...(result.blockType
+                ? {
+                    blockContext: {
+                        ...blockContext({
+                            blockType: result.blockType,
+                            filePath,
+                            message: enrichedMessage,
+                            suggestedApprovalPath: result.approvalContext?.suggestedApprovalPath,
+                            owners: result.owners,
+                            proposalId: pendingScopeAmendmentProposalId,
+                            runtimeMode: runtimeMode(session),
+                        }),
+                        ...(repoBrainFileFacts ? {
+                            repoBrainFacts: {
+                                sensitiveKinds: repoBrainFileFacts.sensitiveKinds,
+                                module: repoBrainFileFacts.module,
+                                hotspot: repoBrainFileFacts.hotspot,
+                                ownerBoundary: repoBrainFileFacts.ownerBoundary,
+                                reuseAdvisories: repoBrainFileFacts.reuseAdvisories,
+                                artifactHash: repoBrainMeta.artifactHash,
+                                generatedAt: repoBrainMeta.generatedAt,
+                            },
+                        } : { repoBrainStatus: 'missing', repoBrainRecovery: 'neurcode brain index' }),
+                    },
+                }
+                : {}),
+        });
     }
     if (result.verdict === 'warn') {
         const reason = consequenceNudge
@@ -1071,6 +1444,28 @@ async function handleCheck(cmdCwd) {
         }) + '\n');
         process.exit(0);
     }
+    if (consequenceNudge && isReuseNudge(consequenceNudge)) {
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'allow',
+                reason: consequenceNudge.headline,
+                reuseNudge: {
+                    nudgeVersion: consequenceNudge.nudgeVersion,
+                    nudgeKey: consequenceNudge.nudgeKey,
+                    severity: consequenceNudge.severity,
+                    consequenceClass: consequenceNudge.consequenceClass,
+                    operatorAction: consequenceNudge.operatorAction,
+                    reviewFocus: consequenceNudge.reviewFocus,
+                    artifactHash: consequenceNudge.artifactHash,
+                    finding: consequenceNudge.reuseFinding,
+                    surfacedFindingLimit: 3,
+                    topFindings: consequenceNudge.surfacedReuseFindings,
+                },
+            },
+        }) + '\n');
+        process.exit(0);
+    }
     if (consequenceNudge) {
         process.stdout.write(JSON.stringify({
             hookSpecificOutput: {
@@ -1168,11 +1563,17 @@ async function handleFinish(cmdCwd) {
         diagnostic(`Claude session_id ${requestedSessionId} did not match a Neurcode session; finishing active session ${session.sessionId}`);
     }
     try {
-        const pendingApproval = latestUnresolvedApprovalBlock(session);
-        if (shouldKeepSessionActiveForPendingApproval(session, pendingApproval)) {
+        const pendingActionableBlock = latestUnresolvedActionableBlock(session);
+        if (shouldKeepSessionActiveForPendingApproval(session, pendingActionableBlock)) {
+            const actionLabel = pendingActionableBlock.blockType === 'approval_required_boundary'
+                ? `exact approval of ${pendingActionableBlock.suggestedApprovalPath || pendingActionableBlock.filePath}`
+                : pendingActionableBlock.blockType === 'scope_violation_or_task_expansion'
+                    ? `scope amendment for ${pendingActionableBlock.filePath}`
+                    : pendingActionableBlock.blockType === 'profile_or_runtime_health_block'
+                        ? 'runtime/profile recovery'
+                        : 'a split single-file retry';
             process.stdout.write(JSON.stringify({
-                message: `⏸ Neurcode session ${session.sessionId} remains active; waiting for exact approval of ` +
-                    `${pendingApproval.suggestedApprovalPath}.`,
+                message: `⏸ Neurcode session ${session.sessionId} remains active; waiting for operator action: ${actionLabel}.`,
             }) + '\n');
             await (0, runtime_live_1.publishRuntimeLiveStatus)(repoRoot, session);
             try {
@@ -1185,10 +1586,20 @@ async function handleFinish(cmdCwd) {
             }
             return;
         }
-        const finished = (0, governance_runtime_1.finishSession)(repoRoot, session.sessionId, pendingApproval
+        const finished = (0, governance_runtime_1.finishSession)(repoRoot, session.sessionId, pendingActionableBlock
             ? {
-                reason: 'finished_with_unresolved_approval_blocks',
-                unresolvedApprovalBlocks: [pendingApproval],
+                reason: pendingActionableBlock.blockType === 'approval_required_boundary'
+                    ? 'finished_with_unresolved_approval_blocks'
+                    : 'finished_with_unresolved_actionable_blocks',
+                unresolvedActionableBlocks: [pendingActionableBlock],
+                ...(pendingActionableBlock.blockType === 'approval_required_boundary'
+                    ? {
+                        unresolvedApprovalBlocks: [{
+                                filePath: pendingActionableBlock.filePath,
+                                suggestedApprovalPath: pendingActionableBlock.suggestedApprovalPath || pendingActionableBlock.filePath,
+                            }],
+                    }
+                    : {}),
             }
             : undefined);
         if (!finished)
@@ -1199,11 +1610,11 @@ async function handleFinish(cmdCwd) {
         }
         const blockCount = finished.events.filter((e) => e.type === 'check_block').length;
         const warnCount = finished.events.filter((e) => e.type === 'check_warn').length;
-        const unresolvedLine = pendingApproval
-            ? `   Unresolved: 1 approval block left recorded (${pendingApproval.suggestedApprovalPath})`
+        const unresolvedLine = pendingActionableBlock
+            ? `   Unresolved: 1 ${pendingActionableBlock.blockType} left recorded (${pendingActionableBlock.suggestedApprovalPath || pendingActionableBlock.filePath})`
             : null;
         const summary = [
-            pendingApproval
+            pendingActionableBlock
                 ? `✅ Neurcode session ${finished.sessionId} complete with unresolved block evidence`
                 : `✅ Neurcode session ${finished.sessionId} complete`,
             `   Scope mode: ${finished.contract.scopeMode}`,