@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/dist/pre-bash-dispatch.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Bash hooks.
+ *
+ * Consolidates check-dangerous-commands.js and validate-commit.js
+ * into a single process, reading stdin once and routing to both
+ * checks sequentially. This halves the process spawns per Bash call.
+ *
+ * -- Dispatch Order & Rationale --
+ *
+ *   1. check-dangerous-commands -- Blocks destructive shell operations
+ *      (rm -rf, git push --force, etc.). Runs first because safety
+ *      takes priority: if a command is dangerous, we must reject it
+ *      before even considering whether its commit message is valid.
+ *      Can block (exit 2).
+ *
+ *   2. validate-commit          -- Enforces conventional commit format
+ *      ({type}({scope}): {desc}) on git commit commands. Runs second
+ *      because commit format validation is only relevant for git
+ *      commit operations, a narrow subset of all Bash calls. There's
+ *      no benefit to checking format if the command was already
+ *      blocked as dangerous. Can block (exit 2).
+ *
+ * -- Short-Circuit Behavior --
+ *
+ *   If an earlier check returns a result (blocking with exit 2),
+ *   later checks are skipped entirely. The first failure is the
+ *   most relevant -- a dangerous command should be blocked regardless
+ *   of whether it also has a valid commit message.
+ *
+ * -- Adding New Checks --
+ *
+ *   1. Create a new check module exporting a function that takes
+ *      the parsed hook data and returns null (pass) or
+ *      { output: {...}, exitCode: N }.
+ *   2. require() it at the top of this file.
+ *   3. Add the call in sequence below, following the pattern:
+ *        const result = checkFoo(data);
+ *        if (result) { log; write output; exit with code; }
+ *   4. Position the check based on severity: safety-critical checks
+ *      should run earlier; format/style checks should run later.
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (dangerous command or invalid commit format)
+ */
+
+const { logHook } = require('./hook-logger');
+const { checkDangerous } = require('./check-dangerous-commands');
+const { checkCommit, enrichCommitLlm } = require('./validate-commit');
+const { checkUnmanagedCommit } = require('./enforce-pbr-workflow');
+const { checkRequirePaths, checkMirrorSync, checkLintErrors } = require('./lib/pre-commit-checks');
+// Cross-plugin sync disabled -- derivative plugins updated separately
+// const { checkCrossPluginSync } = require('./check-cross-plugin-sync');
+
+/**
+ * Core dispatch logic extracted for both stdin (main) and HTTP (handleHttp) paths.
+ *
+ * Runs all checks sequentially. Block decisions short-circuit immediately.
+ * Warnings are collected and merged into a single advisory response.
+ *
+ * @param {Object} data - Parsed hook input (same as stdin JSON)
+ * @returns {Promise<Object|null>} Hook response: { decision: 'block', reason } or { decision: 'allow', additionalContext? } or null
+ */
+async function processEvent(data) {
+  try {
+    // Dangerous commands check first -- can block
+    const dangerousResult = checkDangerous(data);
+    if (dangerousResult) {
+      logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'check-dangerous-commands' });
+      if (dangerousResult.exitCode === 2) {
+        return { decision: 'block', reason: dangerousResult.output.reason || dangerousResult.output.additionalContext || 'Dangerous command blocked' };
+      }
+    }
+
+    // Commit validation check -- can block
+    const commitResult = checkCommit(data);
+    if (commitResult) {
+      logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'validate-commit' });
+      if (commitResult.exitCode === 2) {
+        return { decision: 'block', reason: commitResult.output.reason || commitResult.output.additionalContext || 'Invalid commit format' };
+      }
+      // exitCode 0 with output = warning
+      if (commitResult.output && commitResult.output.additionalContext) {
+        // Collect as warning below
+      }
+    }
+
+    // Soft warnings for risky-but-allowed commands
+    const command = data.tool_input?.command || '';
+    const warnings = [];
+
+    // Carry forward commit warning if it was advisory (exitCode 0)
+    if (commitResult && commitResult.exitCode === 0 && commitResult.output && commitResult.output.additionalContext) {
+      warnings.push(commitResult.output.additionalContext);
+    }
+
+    if (command) {
+      // Warn about npm publish / deploy commands
+      if (/\bnpm\s+publish\b/.test(command)) {
+        warnings.push('npm publish detected -- ensure version is correct before publishing');
+      }
+
+      // Warn about touching production config files
+      if (/\b(production|prod)\b.*\.(json|ya?ml|env|conf|cfg)\b/i.test(command) ||
+          /\.(json|ya?ml|env|conf|cfg)\b.*\b(production|prod)\b/i.test(command)) {
+        warnings.push('command references production config files -- verify you are not in a live environment');
+      }
+
+      // Warn about database operations
+      if (/\b(DROP|TRUNCATE|DELETE\s+FROM|ALTER\s+TABLE)\b/i.test(command)) {
+        warnings.push('destructive database operation (DROP/TRUNCATE/DELETE/ALTER) -- verify correct database is targeted and a backup exists');
+      }
+    }
+
+    // Pre-commit quality checks -- advisory only, on git commit commands
+    if (/\bgit\s+commit\b/.test(command)) {
+      const pathResult = checkRequirePaths(data);
+      if (pathResult) warnings.push(...pathResult.warnings);
+
+      const mirrorResult = checkMirrorSync(data);
+      if (mirrorResult) warnings.push(...mirrorResult.warnings);
+
+      const lintResult = checkLintErrors(data);
+      if (lintResult) warnings.push(...lintResult.warnings);
+    }
+
+    // Unmanaged commit advisory -- warn when git commit runs without PBR skill
+    const unmanagedCommitResult = checkUnmanagedCommit(data);
+    if (unmanagedCommitResult) {
+      warnings.push(unmanagedCommitResult.output.additionalContext);
+    }
+
+    // Cross-plugin sync advisory -- disabled (derivative plugins updated separately)
+    // const syncResult = checkCrossPluginSync(data);
+    // if (syncResult) {
+    //   warnings.push(syncResult.additionalContext);
+    // }
+
+    // LLM commit semantic classification -- advisory only
+    const llmAdvisory = await enrichCommitLlm(data);
+    if (llmAdvisory) {
+      warnings.push(llmAdvisory);
+    }
+
+    if (warnings.length > 0) {
+      logHook('pre-bash-dispatch', 'PreToolUse', 'warn', { warnings: warnings.length, cmd: command.substring(0, 80) });
+      return {
+        decision: 'allow',
+        additionalContext: `[pbr] Advisory: ${warnings.join('; ')}.`
+      };
+    }
+
+    // Log pass-through so hook activity is visible in logs AND session JSONL
+    logHook('pre-bash-dispatch', 'PreToolUse', 'allow', { cmd: command.substring(0, 80) });
+    return { decision: 'allow' };
+  } catch (e) {
+    logHook('pre-bash-dispatch', 'PreToolUse', 'error', { error: e.message });
+    return null;
+  }
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ *
+ * @param {Object} reqBody - Request body from hook-server
+ * @param {Object} _cache - In-memory server cache (unused)
+ * @returns {Promise<Object|null>} Hook response or null
+ */
+async function handleHttp(reqBody, _cache) {
+  const data = reqBody.data || {};
+  try {
+    return await processEvent(data);
+  } catch (_e) {
+    logHook('pre-bash-dispatch', 'PreToolUse', 'error', { error: _e.message });
+    return null;
+  }
+}
+
+module.exports = { handleHttp, processEvent };
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+
+      const result = await processEvent(data);
+
+      if (result && result.decision === 'block') {
+        process.stdout.write(JSON.stringify(result));
+        process.exit(2);
+      }
+
+      if (result) {
+        process.stdout.write(JSON.stringify(result));
+      } else {
+        // processEvent returned null (error) -- allow through
+        process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      }
+      process.exit(0);
+    } catch (e) {
+      // Don't block on errors -- but emit valid output so Claude Code
+      // doesn't report "hook error" for silent exit
+      process.stderr.write(`[pbr] pre-bash-dispatch error: ${e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: 'allow', additionalContext: '\u26a0 [PBR] pre-bash-dispatch failed: ' + e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/pre-skill-dispatch.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Skill hooks.
+ *
+ * Consolidates enforce-context-budget.js and validate-skill-args.js
+ * into a single process, reading stdin once and routing to both
+ * checks sequentially. Budget check runs first (cheap) and
+ * short-circuits before skill argument validation.
+ *
+ * ── Dispatch Order & Rationale ──────────────────────────────────
+ *
+ *   1. enforce-context-budget — Blocks Skill invocations when context
+ *      usage exceeds the hard_stop_percent threshold. Runs first
+ *      because it is a cheap file read that can short-circuit before
+ *      argument validation.
+ *
+ *   2. validate-skill-args   — Validates skill arguments (phase
+ *      number existence, freeform text detection for /pbr:plan-phase).
+ *      Can block (exit 2) or allow (exit 0).
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (budget exceeded or invalid skill args)
+ */
+
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { checkBudget } = require('./enforce-context-budget');
+const { checkSkillArgs } = require('./validate-skill-args');
+
+/**
+ * Core dispatch logic for PreToolUse:Skill events.
+ *
+ * Step 1: Budget check (cheap, fast — short-circuits on block)
+ * Step 2: Skill argument validation
+ * Step 3: All clear
+ *
+ * @param {Object} data - Parsed hook event data
+ * @returns {Object} { decision: 'block'|'allow', reason?: string, additionalContext?: string }
+ */
+async function processEvent(data) {
+  // Step 1 — Budget check (cheap, fast)
+  const planningDir = path.join(data.cwd || process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const budgetResult = checkBudget({ toolName: 'Skill', planningDir });
+  if (budgetResult) {
+    logHook('pre-skill-dispatch', 'PreToolUse', 'blocked', { handler: 'enforce-context-budget' });
+    return budgetResult; // already { decision: 'block', reason: '...' }
+  }
+
+  // Step 2 — Skill argument validation
+  const skillResult = checkSkillArgs(data);
+  if (skillResult) {
+    if (skillResult.exitCode === 2) {
+      // Blocking result
+      logHook('pre-skill-dispatch', 'PreToolUse', 'blocked', { handler: 'validate-skill-args' });
+      return skillResult.output; // { decision: 'block', reason: '...' }
+    }
+    // Advisory result (exitCode 0 with output)
+    if (skillResult.output) {
+      logHook('pre-skill-dispatch', 'PreToolUse', 'warn', { handler: 'validate-skill-args' });
+      return skillResult.output;
+    }
+  }
+
+  // Step 3 — All clear
+  logHook('pre-skill-dispatch', 'PreToolUse', 'allow', {});
+  return { decision: 'allow' };
+}
+
+/**
+ * HTTP handler for hook-server integration.
+ *
+ * @param {Object} reqBody - HTTP request body with { data: {...} }
+ * @param {Object} _cache - Hook server cache (unused)
+ * @returns {Object|null} Hook result or null on error
+ */
+async function handleHttp(reqBody, _cache) {
+  try {
+    const data = reqBody.data || {};
+    return await processEvent(data);
+  } catch (_e) {
+    return null;
+  }
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+      const result = await processEvent(data);
+
+      if (result && result.decision === 'block') {
+        process.stdout.write(JSON.stringify(result));
+        process.exit(2);
+        return;
+      }
+
+      process.stdout.write(JSON.stringify(result || {}));
+      process.exit(0);
+    } catch (_e) {
+      process.stderr.write(`[pbr] pre-skill-dispatch error: ${_e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: 'allow', additionalContext: '[PBR] pre-skill-dispatch failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { handleHttp, processEvent };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/pre-task-dispatch.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Task hooks.
+ *
+ * Consolidates enforce-context-budget.js and validate-task.js into a
+ * single process, reading stdin once and routing to both checks
+ * sequentially. Budget check runs first (cheap) and short-circuits
+ * before expensive gate validation.
+ *
+ * ── Dispatch Order & Rationale ──────────────────────────────────
+ *
+ *   1. enforce-context-budget — Blocks Task invocations when context
+ *      usage exceeds the hard_stop_percent threshold. Runs first
+ *      because it is a cheap file read that can short-circuit before
+ *      the expensive gate cascade.
+ *
+ *   2. validate-task gates     — Full gate cascade: quick executor,
+ *      build executor, plan validation, plan executor, review planner,
+ *      review verifier, milestone complete, milestone summary, build
+ *      dependency, doc existence, non-PBR agent, checkpoint manifest,
+ *      debugger advisory, active skill integrity, user confirmation.
+ *      Can block (exit 2) or advise (exit 0).
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (budget exceeded or gate blocked)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { checkBudget } = require('./enforce-context-budget');
+const { resolveConfig } = require('./lib/local-llm/health');
+const { validateTask: llmValidateTask } = require('./lib/local-llm/operations/validate-task');
+const { checkNonPbrAgent } = require('./enforce-pbr-workflow');
+const { KNOWN_AGENTS } = require('./lib/core');
+
+// Gate modules
+const { checkQuickExecutorGate } = require('./lib/gates/quick-executor');
+const { checkBuildExecutorGate } = require('./lib/gates/build-executor');
+const { checkPlanExecutorGate } = require('./lib/gates/plan-executor');
+const { checkReviewPlannerGate } = require('./lib/gates/review-planner');
+const { checkReviewVerifierGate } = require('./lib/gates/review-verifier');
+const { checkMilestoneCompleteGate } = require('./lib/gates/milestone-complete');
+const { checkMilestoneSummaryGate } = require('./lib/gates/milestone-summary');
+const { checkBuildDependencyGate } = require('./lib/gates/build-dependency');
+const { checkPlanValidationGate } = require('./lib/gates/plan-validation');
+const { checkDebuggerAdvisory, checkCheckpointManifest, checkActiveSkillIntegrity } = require('./lib/gates/advisories');
+const { checkDocExistence } = require('./lib/gates/doc-existence');
+const { checkUserConfirmationGate } = require('./lib/gates/user-confirmation');
+
+const MAX_DESCRIPTION_LENGTH = 100;
+
+/**
+ * Load and resolve the local_llm config block from .planning/config.json.
+ */
+function loadLocalLlmConfig(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return resolveConfig(parsed.local_llm);
+  } catch (_e) {
+    return resolveConfig(undefined);
+  }
+}
+
+/**
+ * Check a parsed hook data object for Task() validation issues.
+ * Returns an array of warning strings (empty if all good).
+ */
+function checkTask(data) {
+  const warnings = [];
+  const toolInput = data.tool_input || {};
+
+  const description = toolInput.description;
+  const subagentType = toolInput.subagent_type;
+
+  if (!description || (typeof description === 'string' && !description.trim())) {
+    warnings.push('Task() called without a description. Descriptions are required for audit logging and skill enforcement. Add a short description (3-5 words), e.g.: "Build phase 3 executor".');
+  } else if (typeof description === 'string') {
+    if (description.length > MAX_DESCRIPTION_LENGTH) {
+      warnings.push(
+        `Task() description is ${description.length} chars (recommended <=100). ` +
+        'Keep descriptions to 3-5 words.'
+      );
+    }
+    if (/\bpbr:/.test(description) && !subagentType) {
+      warnings.push(
+        'Task() description contains "pbr:" but no subagent_type is set. ' +
+        'Use subagent_type: "pbr:{name}" for automatic agent loading.'
+      );
+    }
+  }
+
+  if (typeof subagentType === 'string' && subagentType.startsWith('pbr:')) {
+    const agentName = subagentType.slice(4);
+    if (!KNOWN_AGENTS.includes(agentName)) {
+      warnings.push(
+        `Unknown pbr agent type: "${subagentType}". ` +
+        `Known types: ${KNOWN_AGENTS.map(a => 'pbr:' + a).join(', ')}`
+      );
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Core dispatch logic for PreToolUse:Task events.
+ *
+ * Step 1: Budget check (cheap, fast — short-circuits on block)
+ * Step 2: Gate cascade from validate-task (expensive — all blocking gates)
+ * Step 3: Advisory warnings (non-blocking)
+ *
+ * @param {Object} data - Parsed hook event data
+ * @returns {Object} { decision: 'block'|'allow', reason?: string, additionalContext?: string }
+ */
+async function processEvent(data) {
+  // Step 1 — Budget check (cheap, fast)
+  const planningDir = path.join(data.cwd || process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const budgetResult = checkBudget({ toolName: 'Task', planningDir });
+  if (budgetResult) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'enforce-context-budget' });
+    return budgetResult; // already { decision: 'block', reason: '...' }
+  }
+
+  // Step 2 — Gate cascade (expensive, blocking checks)
+
+  // User confirmation gate
+  const userConfGate = checkUserConfirmationGate(data);
+  if (userConfGate && userConfGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'user-confirmation', reason: userConfGate.reason });
+    return { decision: 'block', reason: userConfGate.reason };
+  }
+
+  // Quick executor gate
+  const quickGate = checkQuickExecutorGate(data);
+  if (quickGate && quickGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'quick-executor', reason: quickGate.reason });
+    return { decision: 'block', reason: quickGate.reason };
+  }
+
+  // Build executor gate
+  const buildGate = checkBuildExecutorGate(data);
+  if (buildGate && buildGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'build-executor', reason: buildGate.reason });
+    return { decision: 'block', reason: buildGate.reason };
+  }
+
+  // Plan validation gate
+  const planValGate = checkPlanValidationGate(data);
+  if (planValGate && planValGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'plan-validation', reason: planValGate.reason });
+    return { decision: 'block', reason: planValGate.reason };
+  }
+
+  // Review planner gate
+  const reviewGate = checkReviewPlannerGate(data);
+  if (reviewGate && reviewGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'review-planner', reason: reviewGate.reason });
+    return { decision: 'block', reason: reviewGate.reason };
+  }
+
+  // Plan executor gate
+  const planGate = checkPlanExecutorGate(data);
+  if (planGate && planGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'plan-executor', reason: planGate.reason });
+    return { decision: 'block', reason: planGate.reason };
+  }
+
+  // Review verifier gate
+  const reviewVerifierGate = checkReviewVerifierGate(data);
+  if (reviewVerifierGate && reviewVerifierGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'review-verifier', reason: reviewVerifierGate.reason });
+    return { decision: 'block', reason: reviewVerifierGate.reason };
+  }
+
+  // Milestone complete gate
+  const milestoneGate = checkMilestoneCompleteGate(data);
+  if (milestoneGate && milestoneGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'milestone-complete', reason: milestoneGate.reason });
+    return { decision: 'block', reason: milestoneGate.reason };
+  }
+
+  // Milestone summary gate
+  const milestoneSummaryGate = checkMilestoneSummaryGate(data);
+  if (milestoneSummaryGate && milestoneSummaryGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'milestone-summary', reason: milestoneSummaryGate.reason });
+    return { decision: 'block', reason: milestoneSummaryGate.reason };
+  }
+
+  // Build dependency gate
+  const buildDepGate = checkBuildDependencyGate(data);
+  if (buildDepGate && buildDepGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'build-dependency', reason: buildDepGate.reason });
+    return { decision: 'block', reason: buildDepGate.reason };
+  }
+
+  // Doc existence gate
+  const docGate = checkDocExistence(data);
+  if (docGate && docGate.block) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'doc-existence', reason: docGate.reason });
+    return { decision: 'block', reason: docGate.reason };
+  }
+
+  // Non-PBR agent enforcement
+  const nonPbrAgentResult = checkNonPbrAgent(data);
+  if (nonPbrAgentResult && nonPbrAgentResult.exitCode === 2) {
+    logHook('pre-task-dispatch', 'PreToolUse', 'blocked', { handler: 'enforce-pbr-workflow' });
+    return nonPbrAgentResult.output;
+  }
+
+  // Step 3 — Advisory warnings (non-blocking)
+  const warnings = checkTask(data);
+  if (userConfGate && userConfGate.warning) warnings.push(userConfGate.warning);
+  const manifestWarning = checkCheckpointManifest(data);
+  if (manifestWarning) warnings.push(manifestWarning);
+  const debuggerWarning = checkDebuggerAdvisory(data);
+  if (debuggerWarning) warnings.push(debuggerWarning);
+  const activeSkillWarning = checkActiveSkillIntegrity(data);
+  if (activeSkillWarning) warnings.push(activeSkillWarning);
+  if (nonPbrAgentResult) warnings.push(nonPbrAgentResult.output.additionalContext);
+  if (planValGate && planValGate.warning) warnings.push(planValGate.warning);
+
+  // LLM task coherence check — advisory only
+  try {
+    const llmCwd = data.cwd || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const llmConfig = loadLocalLlmConfig(llmCwd);
+    const llmPlanningDir = path.join(llmCwd, '.planning');
+    const llmResult = await llmValidateTask(llmConfig, llmPlanningDir, data.tool_input || {}, data.session_id);
+    if (llmResult && !llmResult.coherent) {
+      warnings.push('LLM task coherence advisory: ' + (llmResult.issue || 'Task description may not match intended operation.') + ' (confidence: ' + (llmResult.confidence * 100).toFixed(0) + '%)');
+    }
+  } catch (_llmErr) {
+    // Never propagate LLM errors
+  }
+
+  if (warnings.length > 0) {
+    for (const warning of warnings) {
+      logHook('pre-task-dispatch', 'PreToolUse', 'warn', { warning });
+    }
+    return {
+      decision: 'allow',
+      additionalContext: 'Task() validation warnings:\n' + warnings.map(w => '- ' + w).join('\n')
+    };
+  }
+
+  // All clear
+  logHook('pre-task-dispatch', 'PreToolUse', 'allow', {});
+  return { decision: 'allow' };
+}
+
+/**
+ * HTTP handler for hook-server integration.
+ *
+ * @param {Object} reqBody - HTTP request body with { data: {...} }
+ * @param {Object} _cache - Hook server cache (unused)
+ * @returns {Object|null} Hook result or null on error
+ */
+async function handleHttp(reqBody, _cache) {
+  try {
+    const data = reqBody.data || {};
+    return await processEvent(data);
+  } catch (_e) {
+    return null;
+  }
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+      const result = await processEvent(data);
+
+      if (result && result.decision === 'block') {
+        process.stdout.write(JSON.stringify(result));
+        process.exit(2);
+        return;
+      }
+
+      process.stdout.write(JSON.stringify(result || {}));
+      process.exit(0);
+    } catch (_e) {
+      process.stderr.write(`[pbr] pre-task-dispatch error: ${_e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: 'allow', additionalContext: '[PBR] pre-task-dispatch failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { handleHttp, processEvent };
+if (require.main === module || process.argv[1] === __filename) { main(); }