@kontourai/flow-agents 0.1.2 → 0.3.0

package/scripts/hooks/opencode-hook-adapter.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * opencode hook adapter for canonical Flow Agents hooks.
+ *
+ * opencode plugins receive events via the plugin function's hook registry.
+ * This adapter is called by the generated .opencode/plugins/flow-agents.js
+ * plugin when it shells out to execute policy checks. The adapter normalizes
+ * opencode event payloads into the shared hook runner contract and returns
+ * results as JSON for the plugin to interpret.
+ *
+ * Canonical hook scripts: exit 0 passes, exit 2 blocks, stderr/stdout
+ * carries human-readable guidance. This adapter translates that contract
+ * into JSON the plugin can act on.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) truncated = true;
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function parseEvent(raw, fallback) {
+  try {
+    return JSON.parse(raw || '{}').hook_event_name || fallback || '';
+  } catch {
+    return fallback || '';
+  }
+}
+
+function messageFrom(result) {
+  const stderr = String(result.stderr || '').trim();
+  const stdout = String(result.stdout || '').trim();
+  return stderr || stdout || 'Blocked by Flow Agents hook policy.';
+}
+
+function guidanceFromStdout(rawInput, stdout) {
+  const text = String(stdout || '');
+  if (!text.trim()) return '';
+  const guidance = text.startsWith(rawInput) ? text.slice(rawInput.length) : text;
+  return guidance.trim();
+}
+
+function successOutput(event, additionalContext = '') {
+  const context = String(additionalContext || '').trim();
+  return {
+    allow: true,
+    context: context || undefined,
+    event,
+  };
+}
+
+function blockedOutput(event, reason) {
+  return {
+    allow: false,
+    reason,
+    event,
+  };
+}
+
+async function main() {
+  const [, , eventArg = 'unknown', hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+  const event = parseEvent(raw, eventArg);
+
+  if (!hookId || !relScriptPath) {
+    process.stdout.write(`${JSON.stringify(successOutput(event))}\n`);
+    return;
+  }
+
+  const runHookPath = path.resolve(__dirname, 'run-hook.js');
+  const result = spawnSync(process.execPath, [runHookPath, hookId, relScriptPath, profilesCsv || ''], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      SA_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0',
+      SA_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN),
+      FLOW_AGENTS_HOOK_RUNTIME: 'opencode',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_OPENCODE_HOOK_TIMEOUT_MS || 30000),
+  });
+
+  if (result.status === 2) {
+    process.stdout.write(`${JSON.stringify(blockedOutput(event, messageFrom(result)))}\n`);
+    return;
+  }
+
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[OpencodeHook] ${hookId} failed open: ${detail}\n`);
+    process.stdout.write(`${JSON.stringify(successOutput(event))}\n`);
+    return;
+  }
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.stdout.write(`${JSON.stringify(successOutput(event, guidanceFromStdout(raw, result.stdout)))}\n`);
+}
+
+main().catch(err => {
+  process.stderr.write(`[OpencodeHook] adapter error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/opencode-telemetry-hook.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * opencode telemetry hook wrapper.
+ *
+ * Called by the generated .opencode/plugins/flow-agents.js plugin when it
+ * shells out for telemetry recording. This wrapper adapts opencode plugin
+ * event payloads to the canonical Flow Agents telemetry script and stays
+ * fail-open so telemetry cannot block work.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+const DEFAULT_FULL_REDACT = 'hook.raw_input,turn.prompt_text,tool.input,tool.output';
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        raw += chunk.slice(0, MAX_STDIN - raw.length);
+      }
+    });
+    process.stdin.on('end', () => resolve(raw));
+    process.stdin.on('error', () => resolve(raw));
+  });
+}
+
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function canonicalEvent(cliEvent, payload) {
+  const event = cliEvent || payload.hook_event_name || 'unknown';
+  const mapping = {
+    'session.created': 'agentSpawn',
+    'session.idle': 'stop',
+    'session.error': 'stop',
+    'session.compacted': 'stop',
+    'tool.execute.before': 'preToolUse',
+    'tool.execute.after': 'postToolUse',
+    'permission.asked': 'permissionRequest',
+    'permission.replied': 'permissionRequest',
+    'file.edited': 'postToolUse',
+    'message.updated': 'postToolUse',
+    'command.executed': 'postToolUse',
+    'input': 'userPromptSubmit',
+    agentSpawn: 'agentSpawn',
+    userPromptSubmit: 'userPromptSubmit',
+    preToolUse: 'preToolUse',
+    postToolUse: 'postToolUse',
+    stop: 'stop',
+  };
+  return mapping[event] || event;
+}
+
+async function main() {
+  const [, , eventArg = 'unknown', agentName = 'dev'] = process.argv;
+  const raw = await readStdinRaw();
+  const payload = parseJson(raw);
+  const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
+
+  const result = spawnSync('bash', [telemetryScript, canonicalEvent(eventArg, payload), agentName], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      FLOW_AGENTS_TELEMETRY_RUNTIME: 'opencode',
+      FLOW_AGENTS_TELEMETRY_FOREGROUND: process.env.FLOW_AGENTS_OPENCODE_TELEMETRY_FOREGROUND || 'false',
+      TELEMETRY_CHANNELS: process.env.FLOW_AGENTS_OPENCODE_TELEMETRY_CHANNELS || 'full,analytics',
+      TELEMETRY_CHANNEL_FULL_REDACT: process.env.TELEMETRY_CHANNEL_FULL_REDACT || DEFAULT_FULL_REDACT,
+      TELEMETRY_CHANNEL_ANALYTICS_REDACT:
+        process.env.TELEMETRY_CHANNEL_ANALYTICS_REDACT ||
+        'tool.input,tool.output,turn.prompt_text,delegation.targets.query,context.cwd,hook.raw_input',
+      TELEMETRY_CHANNEL_FULL_ENDPOINT_URL: process.env.TELEMETRY_CHANNEL_FULL_ENDPOINT_URL || '',
+      TELEMETRY_USAGE_TRACKING: process.env.TELEMETRY_USAGE_TRACKING || 'true',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_OPENCODE_TELEMETRY_TIMEOUT_MS || 30000),
+  });
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[OpencodeTelemetryHook] failed open: ${detail}\n`);
+  }
+  // opencode plugin calls this as a subprocess; just exit 0 for success
+}
+
+main().catch(err => {
+  process.stderr.write(`[OpencodeTelemetryHook] wrapper error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/pi-hook-adapter.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * pi hook adapter for canonical Flow Agents hooks.
+ *
+ * The pi coding agent runs extensions that can shell out to run policy checks.
+ * This adapter is called by the generated .pi/extensions/flow-agents.ts
+ * extension when it needs to evaluate a policy decision. It normalizes
+ * pi event payloads into the shared hook runner contract and returns results
+ * as JSON for the extension to interpret.
+ *
+ * Canonical hook scripts: exit 0 passes, exit 2 blocks, stderr/stdout
+ * carries human-readable guidance. This adapter translates that contract
+ * into JSON the pi extension can act on.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) truncated = true;
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function parseEvent(raw, fallback) {
+  try {
+    return JSON.parse(raw || '{}').hook_event_name || fallback || '';
+  } catch {
+    return fallback || '';
+  }
+}
+
+function messageFrom(result) {
+  const stderr = String(result.stderr || '').trim();
+  const stdout = String(result.stdout || '').trim();
+  return stderr || stdout || 'Blocked by Flow Agents hook policy.';
+}
+
+function guidanceFromStdout(rawInput, stdout) {
+  const text = String(stdout || '');
+  if (!text.trim()) return '';
+  const guidance = text.startsWith(rawInput) ? text.slice(rawInput.length) : text;
+  return guidance.trim();
+}
+
+function successOutput(event, additionalContext = '') {
+  const context = String(additionalContext || '').trim();
+  return {
+    allow: true,
+    context: context || undefined,
+    event,
+  };
+}
+
+function blockedOutput(event, reason) {
+  return {
+    allow: false,
+    reason,
+    event,
+  };
+}
+
+async function main() {
+  const [, , eventArg = 'unknown', hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+  const event = parseEvent(raw, eventArg);
+
+  if (!hookId || !relScriptPath) {
+    process.stdout.write(`${JSON.stringify(successOutput(event))}\n`);
+    return;
+  }
+
+  const runHookPath = path.resolve(__dirname, 'run-hook.js');
+  const result = spawnSync(process.execPath, [runHookPath, hookId, relScriptPath, profilesCsv || ''], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      SA_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0',
+      SA_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN),
+      FLOW_AGENTS_HOOK_RUNTIME: 'pi',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_PI_HOOK_TIMEOUT_MS || 30000),
+  });
+
+  if (result.status === 2) {
+    process.stdout.write(`${JSON.stringify(blockedOutput(event, messageFrom(result)))}\n`);
+    return;
+  }
+
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[PiHook] ${hookId} failed open: ${detail}\n`);
+    process.stdout.write(`${JSON.stringify(successOutput(event))}\n`);
+    return;
+  }
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.stdout.write(`${JSON.stringify(successOutput(event, guidanceFromStdout(raw, result.stdout)))}\n`);
+}
+
+main().catch(err => {
+  process.stderr.write(`[PiHook] adapter error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/pi-telemetry-hook.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * pi telemetry hook wrapper.
+ *
+ * Called by the generated .pi/extensions/flow-agents.ts extension when it
+ * shells out for telemetry recording. This wrapper adapts pi extension
+ * event payloads to the canonical Flow Agents telemetry script and stays
+ * fail-open so telemetry cannot block work.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+const DEFAULT_FULL_REDACT = 'hook.raw_input,turn.prompt_text,tool.input,tool.output';
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        raw += chunk.slice(0, MAX_STDIN - raw.length);
+      }
+    });
+    process.stdin.on('end', () => resolve(raw));
+    process.stdin.on('error', () => resolve(raw));
+  });
+}
+
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function canonicalEvent(cliEvent, payload) {
+  const event = cliEvent || payload.hook_event_name || 'unknown';
+  const mapping = {
+    session_start: 'agentSpawn',
+    session_shutdown: 'stop',
+    session_before_compact: 'stop',
+    before_agent_start: 'agentSpawn',
+    agent_start: 'agentSpawn',
+    agent_end: 'stop',
+    turn_start: 'userPromptSubmit',
+    turn_end: 'stop',
+    tool_call: 'preToolUse',
+    tool_result: 'postToolUse',
+    tool_execution_start: 'preToolUse',
+    tool_execution_end: 'postToolUse',
+    input: 'userPromptSubmit',
+    user_bash: 'preToolUse',
+    message_start: 'agentSpawn',
+    message_end: 'stop',
+    agentSpawn: 'agentSpawn',
+    userPromptSubmit: 'userPromptSubmit',
+    preToolUse: 'preToolUse',
+    postToolUse: 'postToolUse',
+    stop: 'stop',
+  };
+  return mapping[event] || event;
+}
+
+async function main() {
+  const [, , eventArg = 'unknown', agentName = 'dev'] = process.argv;
+  const raw = await readStdinRaw();
+  const payload = parseJson(raw);
+  const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
+
+  const result = spawnSync('bash', [telemetryScript, canonicalEvent(eventArg, payload), agentName], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      FLOW_AGENTS_TELEMETRY_RUNTIME: 'pi',
+      FLOW_AGENTS_TELEMETRY_FOREGROUND: process.env.FLOW_AGENTS_PI_TELEMETRY_FOREGROUND || 'false',
+      TELEMETRY_CHANNELS: process.env.FLOW_AGENTS_PI_TELEMETRY_CHANNELS || 'full,analytics',
+      TELEMETRY_CHANNEL_FULL_REDACT: process.env.TELEMETRY_CHANNEL_FULL_REDACT || DEFAULT_FULL_REDACT,
+      TELEMETRY_CHANNEL_ANALYTICS_REDACT:
+        process.env.TELEMETRY_CHANNEL_ANALYTICS_REDACT ||
+        'tool.input,tool.output,turn.prompt_text,delegation.targets.query,context.cwd,hook.raw_input',
+      TELEMETRY_CHANNEL_FULL_ENDPOINT_URL: process.env.TELEMETRY_CHANNEL_FULL_ENDPOINT_URL || '',
+      TELEMETRY_USAGE_TRACKING: process.env.TELEMETRY_USAGE_TRACKING || 'true',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_PI_TELEMETRY_TIMEOUT_MS || 30000),
+  });
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[PiTelemetryHook] failed open: ${detail}\n`);
+  }
+  // pi extension calls this as a subprocess; just exit 0 for success
+}
+
+main().catch(err => {
+  process.stderr.write(`[PiTelemetryHook] wrapper error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/run-hook.js

@@ -19,6 +19,7 @@ const { spawnSync } = require('child_process');
 const { isHookEnabled } = require('./lib/hook-flags');
 
 const MAX_STDIN = 1024 * 1024;
+const CONTRACT_VERSION = '1.0';
 
 function readStdinRaw() {
   return new Promise(resolve => {
@@ -130,6 +131,13 @@ async function main() {
   process.exit(Number.isInteger(result.status) ? result.status : 0);
 }
 
+// Additive: --contract-version prints the engine contract version and exits.
+// Backward-compatible: existing callers never pass this flag.
+if (process.argv.includes('--contract-version')) {
+  process.stdout.write(JSON.stringify({ contract_version: CONTRACT_VERSION, runner: 'run-hook.js' }) + '\n');
+  process.exit(0);
+}
+
 main().catch(err => {
   process.stderr.write(`[Hook] run-hook error: ${err.message}\n`);
   process.exit(0);

package/scripts/hooks/utterance-check.js

@@ -7,19 +7,31 @@
  * agent context when concerning statements (unsupported/disputed/rejected) are
  * found.
  *
- * Disabled by default. Enable with:
- *   FLOW_AGENTS_UTTERANCE_CHECK_ENABLED=true
+ * Activation is driven by per-repo policy in context/settings/flow-agents-settings.json:
  *
- * Hook category: PostToolUse / Stop (non-blocking, always exits 0).
+ *   {
+ *     "schema_version": "1.0",
+ *     "utteranceCheck": {
+ *       "enabled": true,
+ *       "mode": "report",         // "report" (default) or "strict"
+ *       "extractor": "reference", // "reference" (default) or "anthropic"
+ *       "bundlePath": "path/to/trust.bundle.json",
+ *       "model": "claude-haiku-4-5",
+ *       "agentId": "my-agent"
+ *     }
+ *   }
  *
- * Strict mode (blocks Stop when concerning badges present):
- *   FLOW_AGENTS_UTTERANCE_CHECK_STRICT=true
+ * Environment variable override (force-on / force-off):
+ *   FLOW_AGENTS_UTTERANCE_CHECK_ENABLED=true   — force on regardless of config
+ *   FLOW_AGENTS_UTTERANCE_CHECK_ENABLED=false  — force off regardless of config
  *
- * Bundle path (optional trust bundle for claim resolution):
+ * Other env vars still accepted as overrides (take precedence over config):
+ *   FLOW_AGENTS_UTTERANCE_CHECK_STRICT=true
  *   FLOW_AGENTS_UTTERANCE_CHECK_BUNDLE_PATH=/path/to/bundle.json
- *
- * Agent ID (for provenance):
  *   FLOW_AGENTS_UTTERANCE_CHECK_AGENT_ID=my-agent
+ *   FLOW_AGENTS_UTTERANCE_CHECK_EXTRACTOR=anthropic
+ *
+ * Hook category: PostToolUse / Stop (non-blocking in report mode, always fails open).
  */
 
 'use strict';
@@ -33,6 +45,8 @@ const CLI_TIMEOUT_MS = 30000;
 // Maximum utterance text to pass to the CLI to keep stdin under MAX_STDIN.
 const MAX_UTTERANCE_CHARS = 8192;
 
+const SETTINGS_REL_PATH = path.join('context', 'settings', 'flow-agents-settings.json');
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -41,6 +55,24 @@ function parseJson(raw) {
   try { return JSON.parse(raw || '{}'); } catch { return {}; }
 }
 
+/**
+ * Walk up from startDir to find the repo root.
+ * Identified by having .git or AGENTS.md present.
+ */
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const root = path.parse(dir).root;
+  for (let depth = 0; depth < 40; depth++) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'AGENTS.md'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir || dir === root) break;
+    dir = parent;
+  }
+  return path.resolve(startDir || process.cwd());
+}
+
 /**
  * Walk up from startDir to find the flow-agents package root.
  * Identified by having both package.json and build/src/cli.js present.
@@ -62,6 +94,76 @@ function findPackageRoot(startDir) {
   return path.resolve(__dirname, '..', '..');
 }
 
+/**
+ * Load per-repo utteranceCheck policy from context/settings/flow-agents-settings.json.
+ * Returns the utteranceCheck object (may be empty/undefined) or null if not found.
+ */
+function loadRepoConfig(repoRoot) {
+  const settingsPath = path.join(repoRoot, SETTINGS_REL_PATH);
+  try {
+    if (!fs.existsSync(settingsPath)) return null;
+    const raw = fs.readFileSync(settingsPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed.utteranceCheck === 'object' ? parsed.utteranceCheck : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve effective hook policy, merging repo config with env var overrides.
+ * Priority (highest first): env var overrides > repo config > built-in defaults.
+ */
+function resolvePolicy(repoRoot) {
+  const repoConfig = loadRepoConfig(repoRoot) || {};
+
+  // Env var override: FLOW_AGENTS_UTTERANCE_CHECK_ENABLED forces on/off.
+  const envEnabled = process.env.FLOW_AGENTS_UTTERANCE_CHECK_ENABLED;
+  let enabled;
+  if (envEnabled === 'true') {
+    enabled = true;
+  } else if (envEnabled === 'false') {
+    enabled = false;
+  } else {
+    // Primary switch is the repo config; default is disabled.
+    enabled = repoConfig.enabled === true;
+  }
+
+  if (!enabled) return { enabled: false };
+
+  // mode: repo config → default "report"
+  let mode = repoConfig.mode === 'strict' ? 'strict' : 'report';
+  // Env var override for strict
+  if (String(process.env.FLOW_AGENTS_UTTERANCE_CHECK_STRICT || '').toLowerCase() === 'true') {
+    mode = 'strict';
+  }
+
+  // extractor: repo config → default "reference"
+  let extractor = repoConfig.extractor === 'anthropic' ? 'anthropic' : 'reference';
+  // Env var override for extractor
+  const envExtractor = process.env.FLOW_AGENTS_UTTERANCE_CHECK_EXTRACTOR;
+  if (envExtractor === 'anthropic') extractor = 'anthropic';
+  else if (envExtractor === 'reference') extractor = 'reference';
+
+  // bundlePath: env var override > repo config
+  let bundlePath = process.env.FLOW_AGENTS_UTTERANCE_CHECK_BUNDLE_PATH || repoConfig.bundlePath || '';
+  // Resolve repo-relative bundle paths
+  if (bundlePath && !path.isAbsolute(bundlePath)) {
+    bundlePath = path.join(repoRoot, bundlePath);
+  }
+
+  // agentId: env var override > repo config
+  const agentId =
+    process.env.FLOW_AGENTS_UTTERANCE_CHECK_AGENT_ID ||
+    repoConfig.agentId ||
+    'flow-agents-hook';
+
+  // model: repo config only (no env var for now)
+  const model = repoConfig.model || '';
+
+  return { enabled, mode, extractor, bundlePath, agentId, model };
+}
+
 /**
  * Extract agent utterance text from the hook event input.
  * - PostToolUse: tool_response or tool_output field
@@ -101,12 +203,15 @@ function safeOneLineExcerpt(text, max = 120) {
 // ---------------------------------------------------------------------------
 
 function run(rawInput) {
-  const enabled = String(process.env.FLOW_AGENTS_UTTERANCE_CHECK_ENABLED || '').toLowerCase() === 'true';
-  if (!enabled) return rawInput;
-
   let input;
   try { input = JSON.parse(rawInput || '{}'); } catch { return rawInput; }
 
+  // Resolve repo root from hook input (Claude Code passes cwd in event).
+  const repoRoot = findRepoRoot(input.cwd || process.cwd());
+  const policy = resolvePolicy(repoRoot);
+
+  if (!policy.enabled) return rawInput;
+
   const utteranceText = extractUtteranceText(input);
   if (!utteranceText) return rawInput;
 
@@ -127,19 +232,16 @@ function run(rawInput) {
 
   const cliArgs = ['utterance-check', 'check', '--utterance', utterance];
 
-  const bundlePath = process.env.FLOW_AGENTS_UTTERANCE_CHECK_BUNDLE_PATH;
-  if (bundlePath) cliArgs.push('--bundle-path', bundlePath);
-
-  const agentId = process.env.FLOW_AGENTS_UTTERANCE_CHECK_AGENT_ID || 'flow-agents-hook';
-  cliArgs.push('--agent-id', agentId);
-
-  const strict = String(process.env.FLOW_AGENTS_UTTERANCE_CHECK_STRICT || '').toLowerCase() === 'true';
-  if (strict) cliArgs.push('--strict');
+  if (policy.bundlePath) cliArgs.push('--bundle-path', policy.bundlePath);
+  cliArgs.push('--agent-id', policy.agentId);
+  if (policy.extractor === 'anthropic') cliArgs.push('--extractor', 'anthropic');
+  if (policy.model) cliArgs.push('--model', policy.model);
+  if (policy.mode === 'strict') cliArgs.push('--strict');
 
   const result = spawnSync(process.execPath, [cliPath, ...cliArgs], {
     encoding: 'utf8',
     timeout: CLI_TIMEOUT_MS,
-    cwd: packageRoot,
+    cwd: repoRoot,
     env: { ...process.env },
   });
 
@@ -189,7 +291,7 @@ function run(rawInput) {
   const event = input.hook_event_name || '';
   const guidance = '\n\n---\n' + lines.join('\n') + '\n---';
 
-  if (strict && result.status === 2) {
+  if (policy.mode === 'strict' && result.status === 2) {
     return {
       stdout: rawInput,
       stderr: lines.join('\n'),
@@ -222,4 +324,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { run, extractUtteranceText, findPackageRoot };
+module.exports = { run, extractUtteranceText, findPackageRoot, findRepoRoot, loadRepoConfig, resolvePolicy };