@kontourai/flow-agents 0.1.1 → 0.2.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

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * Utterance Check Hook — ADR 0003 §9 / survey integration.
+ *
+ * Optionally inspects agent output text for evidence coverage using
+ * @kontourai/survey's surveyAgentUtterance. Injects badge guidance into the
+ * agent context when concerning statements (unsupported/disputed/rejected) are
+ * found.
+ *
+ * Activation is driven by per-repo policy in context/settings/flow-agents-settings.json:
+ *
+ *   {
+ *     "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"
+ *     }
+ *   }
+ *
+ * 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
+ *
+ * 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
+ *   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';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+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
+// ---------------------------------------------------------------------------
+
+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.
+ */
+function findPackageRoot(startDir) {
+  let dir = path.resolve(startDir || __dirname);
+  for (let depth = 0; depth < 10; depth++) {
+    if (
+      fs.existsSync(path.join(dir, 'package.json')) &&
+      fs.existsSync(path.join(dir, 'build', 'src', 'cli.js'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Fallback: assume hooks dir is scripts/hooks/, so root is two levels up.
+  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
+ * - Stop: stop_reason or agent_message field (varies by harness)
+ * - Fallback: returns null (hook passes through)
+ */
+function extractUtteranceText(input) {
+  if (!input || typeof input !== 'object') return null;
+
+  // PostToolUse: agent output is in tool_response or tool_output
+  const resp = input.tool_response || input.tool_output;
+  if (typeof resp === 'string' && resp.trim()) return resp.trim();
+
+  // Stop: some harnesses expose agent message content
+  const agentMsg = input.agent_message || input.message;
+  if (typeof agentMsg === 'string' && agentMsg.trim()) return agentMsg.trim();
+
+  // Stop with content array (Claude Code format)
+  if (Array.isArray(input.content)) {
+    const texts = input.content
+      .filter(b => b && b.type === 'text' && typeof b.text === 'string')
+      .map(b => String(b.text).trim())
+      .filter(Boolean);
+    if (texts.length > 0) return texts.join('\n\n');
+  }
+
+  return null;
+}
+
+function safeOneLineExcerpt(text, max = 120) {
+  const s = String(text || '').replace(/\s+/g, ' ').trim();
+  return s.length > max ? `${s.slice(0, max - 3)}...` : s;
+}
+
+// ---------------------------------------------------------------------------
+// Hook runner
+// ---------------------------------------------------------------------------
+
+function run(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;
+
+  // Truncate very long utterances before passing to CLI.
+  const utterance = utteranceText.length > MAX_UTTERANCE_CHARS
+    ? utteranceText.slice(0, MAX_UTTERANCE_CHARS)
+    : utteranceText;
+
+  const packageRoot = findPackageRoot(__dirname);
+  const cliPath = path.join(packageRoot, 'build', 'src', 'cli.js');
+
+  if (!fs.existsSync(cliPath)) {
+    process.stderr.write(
+      `[UtteranceCheck] CLI not found at ${cliPath}. Run npm run build in the flow-agents checkout.\n`
+    );
+    return rawInput;
+  }
+
+  const cliArgs = ['utterance-check', 'check', '--utterance', utterance];
+
+  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: repoRoot,
+    env: { ...process.env },
+  });
+
+  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(`[UtteranceCheck] CLI execution failed (failing open): ${detail}\n`);
+    return rawInput;
+  }
+
+  // Parse the JSON report from stdout.
+  let report = null;
+  try { report = JSON.parse(String(result.stdout || '').trim()); } catch { /* pass through */ }
+
+  if (result.stderr) {
+    process.stderr.write(String(result.stderr));
+  }
+
+  if (!report) return rawInput;
+
+  // If survey is not configured, pass through silently.
+  if (report.status === 'not_configured') return rawInput;
+
+  // Build guidance text from the badge report.
+  const statements = Array.isArray(report.statements) ? report.statements : [];
+  const concerning = statements.filter(s =>
+    s && (s.badge === 'unsupported' || s.badge === 'disputed' || s.badge === 'rejected')
+  );
+
+  if (concerning.length === 0) return rawInput;
+
+  const lines = [
+    `UTTERANCE CHECK: ${concerning.length} statement(s) in this response lack evidence coverage.`,
+    `Summary: ${report.summary || 'unknown'}`,
+    ...concerning.slice(0, 4).map(s =>
+      `  - [${s.badge}] "${safeOneLineExcerpt(s.excerpt)}"`
+    ),
+    'Evidence note: unsupported = no matching claim in the trust bundle; disputed = conflicting evidence; rejected = claim was rejected.',
+    'Cite sources, note gaps, or run survey-utterance-check to record coverage.',
+  ];
+
+  // For PostToolUse: append guidance to the raw input as additional context.
+  // For Stop: report to stderr (non-blocking warning) unless strict mode.
+  const event = input.hook_event_name || '';
+  const guidance = '\n\n---\n' + lines.join('\n') + '\n---';
+
+  if (policy.mode === 'strict' && result.status === 2) {
+    return {
+      stdout: rawInput,
+      stderr: lines.join('\n'),
+      exitCode: 2,
+    };
+  }
+
+  if (event === 'PostToolUse') {
+    return rawInput + guidance;
+  }
+
+  process.stderr.write(`[UtteranceCheck] ${lines.join('\n')}\n`);
+  return rawInput;
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+  });
+  process.stdin.on('end', () => {
+    const output = run(data);
+    if (output && typeof output === 'object') {
+      if (output.stderr) process.stderr.write(output.stderr.endsWith('\n') ? output.stderr : `${output.stderr}\n`);
+      process.stdout.write(String(output.stdout ?? data));
+      process.exit(Number.isInteger(output.exitCode) ? output.exitCode : 0);
+    }
+    process.stdout.write(String(output));
+  });
+}
+
+module.exports = { run, extractUtteranceText, findPackageRoot, findRepoRoot, loadRepoConfig, resolvePolicy };

package/scripts/telemetry/lib/config.sh

@@ -6,7 +6,11 @@ TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}
 
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../../.." && pwd)/.telemetry}"
+# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
+# two levels up. Three levels escaped into the workspace's PARENT directory
+# (caught by live acceptance smoke 2026-06-11: events landed in /tmp/.telemetry
+# instead of the installed workspace).
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"