@kontourai/flow-agents 2.3.0 → 2.4.0

package/scripts/git-status.sh

@@ -32,11 +32,11 @@ if [ "$WORKTREE_COUNT" -gt 1 ]; then
   echo "=== Active Worktrees ($WORKTREE_COUNT) ==="
   git worktree list
   echo ""
-  echo "⚠️  Multiple worktrees active — check .flow-agents/ for in-progress tasks before modifying shared files"
+  echo "⚠️  Multiple worktrees active — check .kontourai/flow-agents/ for in-progress tasks before modifying shared files"
 fi
 
 # List existing TODOs for awareness
-TODO_DIR=".flow-agents"
+TODO_DIR=".kontourai/flow-agents"
 if [ -d "$TODO_DIR" ]; then
   TODO_COUNT=$(find "$TODO_DIR" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
   if [ "$TODO_COUNT" -gt 0 ]; then

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

@@ -54,7 +54,7 @@ function canonicalEvent(cliEvent, payload) {
   return mapping[event] || event;
 }
 
-function claudeSuccessOutput(event) {
+function claudeSuccessOutput(event, conflict) {
   if (event === 'SessionStart') {
     return {
       continue: true,
@@ -71,6 +71,26 @@ function claudeSuccessOutput(event) {
   if (event === 'Stop' || event === 'SubagentStop' || event === 'SessionEnd') {
     return { continue: true, suppressOutput: true };
   }
+  // Mid-turn conflict injection (issue #320, AC4): fold a detected liveness conflict into the
+  // real hookSpecificOutput.additionalContext channel on PostToolUse/PostToolUseFailure,
+  // matching the precedent claude-hook-adapter.js:70-79 already establishes for policy hooks.
+  // Guarded on a well-formed `conflict` shape so a malformed value degrades to the unchanged
+  // fixed no-conflict output below, never a thrown error (AC8, fail-open).
+  if (
+    (event === 'PostToolUse' || event === 'PostToolUseFailure') &&
+    conflict &&
+    typeof conflict.actor === 'string' &&
+    typeof conflict.lastAt === 'string'
+  ) {
+    return {
+      continue: true,
+      suppressOutput: false,
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: `[LIVENESS CONFLICT] actor "${conflict.actor}" claimed this subject at "${conflict.lastAt}" — run \`liveness verdict\` and coordinate.`,
+      },
+    };
+  }
   return { continue: true, suppressOutput: true };
 }
 
@@ -79,9 +99,23 @@ async function main() {
   const raw = await readStdinRaw();
   const payload = parseJson(raw);
   const hookEvent = payload.hook_event_name || eventArg;
+  const canonical = canonicalEvent(eventArg, payload);
   const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
 
-  const result = spawnSync('bash', [telemetryScript, canonicalEvent(eventArg, payload), agentName], {
+  let conflict;
+  if (canonical === 'postToolUse') {
+    try {
+      const heartbeatResult = require('./lib/liveness-heartbeat').maybeEmitHeartbeat({
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      conflict = heartbeatResult && heartbeatResult.conflict;
+    } catch (err) {
+      process.stderr.write(`[ClaudeTelemetryHook] liveness heartbeat error: ${err.message}\n`);
+    }
+  }
+
+  const result = spawnSync('bash', [telemetryScript, canonical, agentName], {
     input: raw,
     encoding: 'utf8',
     cwd: process.cwd(),
@@ -106,7 +140,7 @@ async function main() {
     process.stderr.write(`[ClaudeTelemetryHook] failed open: ${detail}\n`);
   }
 
-  process.stdout.write(`${JSON.stringify(claudeSuccessOutput(hookEvent))}\n`);
+  process.stdout.write(`${JSON.stringify(claudeSuccessOutput(hookEvent, conflict))}\n`);
 }
 
 main().catch(err => {

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

@@ -38,7 +38,7 @@ function hookEventName(raw) {
   }
 }
 
-function codexSuccessOutput(event) {
+function codexSuccessOutput(event, conflict) {
   if (event === 'SessionStart') {
     return {
       continue: true,
@@ -48,6 +48,27 @@ function codexSuccessOutput(event) {
       },
     };
   }
+  // Mid-turn conflict injection (issue #320, AC4): fold a detected liveness conflict into the
+  // real hookSpecificOutput.additionalContext channel on PostToolUse, matching the precedent
+  // codex-hook-adapter.js:69-77 already establishes for policy hooks. Guarded on a well-formed
+  // `conflict` shape so a malformed value degrades to the unchanged fixed no-conflict output
+  // below, never a thrown error (AC8, fail-open). Subject to the "Codex live hook influence"
+  // caveat (docs/spec/runtime-hook-surface.md §2.1): the wrapper still emits this; effectiveness
+  // is a separate, already-tracked residual.
+  if (
+    event === 'PostToolUse' &&
+    conflict &&
+    typeof conflict.actor === 'string' &&
+    typeof conflict.lastAt === 'string'
+  ) {
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: `[LIVENESS CONFLICT] actor "${conflict.actor}" claimed this subject at "${conflict.lastAt}" — run \`liveness verdict\` and coordinate.`,
+      },
+    };
+  }
   if (event === 'UserPromptSubmit' || event === 'Stop') {
     return { continue: true };
   }
@@ -60,6 +81,19 @@ async function main() {
   const event = hookEventName(raw);
   const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
 
+  let conflict;
+  if (eventType === 'PostToolUse') {
+    try {
+      const heartbeatResult = require('./lib/liveness-heartbeat').maybeEmitHeartbeat({
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      conflict = heartbeatResult && heartbeatResult.conflict;
+    } catch (err) {
+      process.stderr.write(`[CodexTelemetryHook] liveness heartbeat error: ${err.message}\n`);
+    }
+  }
+
   const result = spawnSync('bash', [telemetryScript, eventType, agentName], {
     input: raw,
     encoding: 'utf8',
@@ -85,7 +119,7 @@ async function main() {
     process.stderr.write(`[CodexTelemetryHook] failed open: ${detail}\n`);
   }
 
-  const output = codexSuccessOutput(event);
+  const output = codexSuccessOutput(event, conflict);
   if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
 }
 

package/scripts/hooks/config-protection.js

@@ -15,12 +15,12 @@
  *     export FLOW_AGENTS_GOAL_FIT_MODE=off for the next bash -lc hook invocation.
  *   - .claude/settings.json / settings.local.json — where an agent could add an
  *     env block or delete the Stop hook entry entirely.
- *   - .flow-agents/current.json — where an agent could forge active_flow_id /
+ *   - .kontourai/flow-agents/current.json — where an agent could forge active_flow_id /
  *     active_step_id to route the gate to a fake permissive FlowDefinition.
- *   - .flow-agents/<slug>/state.json — where an agent could forge phase=planning
+ *   - .kontourai/flow-agents/<slug>/state.json — where an agent could forge phase=planning
  *     to downgrade from FULL_BLOCK to HARD_BLOCK (R5a: MEDIUM finding fix).
  *     SAFE: the CLI writes state.json via writeState → writeJson → fs.writeFileSync.
- *   - .flow-agents/<slug>/trust.bundle — where an agent could forge claims.
+ *   - .kontourai/flow-agents/<slug>/trust.bundle — where an agent could forge claims.
  *     SAFE: the CLI writes trust.bundle via writeTrustBundle → writeJson → fs.writeFileSync.
  *   (Verified: ensureSession / advanceState / writeCurrent / writeState /
  *    writeTrustBundle all use writeJson which calls fs.writeFileSync directly —
@@ -78,7 +78,7 @@ const PROTECTED_FILES = new Set([
 // These files need PATH context (not just basename) to avoid over-matching
 // common file names in unrelated projects.
 //
-// R5a adds .flow-agents/<slug>/state.json and .flow-agents/<slug>/trust.bundle.
+// R5a adds flow-agents runtime state and trust.bundle paths.
 //
 // checkProtectedPathPattern(filePath) → { name, reason } | null
 // ---------------------------------------------------------------------------
@@ -86,8 +86,9 @@ const PROTECTED_FILES = new Set([
 /**
  * Check whether a Write/Edit tool file path targets a gate kill-switch file
  * that requires path-level matching (.claude/settings.json,
- * .flow-agents/current.json, .flow-agents/<slug>/state.json,
- * .flow-agents/<slug>/trust.bundle).
+ * .kontourai/flow-agents/current.json, .kontourai/flow-agents/<slug>/state.json,
+ * .kontourai/flow-agents/<slug>/trust.bundle, and deprecated runtime-shaped
+ * .flow-agents equivalents).
  *
  * Returns { name, reason } when blocked, null when allowed.
  *
@@ -119,35 +120,45 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
-  // .flow-agents/current.json — an agent could forge active_flow_id / active_step_id
+  // .kontourai/flow-agents/current.json — an agent could forge active_flow_id / active_step_id
   // to route the gate to a permissive or empty-expects FlowDefinition.
   // SAFE: the workflow CLI writes current.json via fs (writeJson → fs.writeFileSync),
   // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
-  if (/(?:^|\/)\.flow-agents\/current\.json$/.test(norm)) {
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$/.test(norm)) {
     return {
-      name: '.flow-agents/current.json',
+      name: '.kontourai/flow-agents/current.json',
       reason: 'an agent could forge active_flow_id/active_step_id to route the gate to a permissive FlowDefinition',
     };
   }
 
-  // .flow-agents/<slug>/state.json — an agent could forge phase=planning to
+  // .kontourai/flow-agents/.goal-fit-block-streak.json controls soft-block
+  // release counting. An agent could force early advisory-gate release by
+  // writing a high count.
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$/.test(norm)) {
+    return {
+      name: '.kontourai/flow-agents/.goal-fit-block-streak.json',
+      reason: 'an agent could manipulate goal-fit block streak state to force early soft-block release',
+    };
+  }
+
+  // .kontourai/flow-agents/<slug>/state.json — an agent could forge phase=planning to
   // downgrade the block regime (FULL_BLOCK → HARD_BLOCK) and weaken gate checks.
   // SAFE: the CLI writes state.json via writeState → writeJson → fs.writeFileSync,
   // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
-  if (/(?:^|\/)\.flow-agents\/[^/]+\/state\.json$/.test(norm)) {
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$/.test(norm)) {
     return {
-      name: '.flow-agents/<slug>/state.json',
+      name: '.kontourai/flow-agents/<slug>/state.json',
       reason: 'an agent could forge phase=planning to downgrade the block regime and weaken gate enforcement',
     };
   }
 
-  // .flow-agents/<slug>/trust.bundle — an agent could forge claims (e.g. status=verified
+  // .kontourai/flow-agents/<slug>/trust.bundle — an agent could forge claims (e.g. status=verified
   // or impactLevel=low) to suppress gate blocks or make disputed evidence appear accepted.
   // SAFE: the CLI writes trust.bundle via writeTrustBundle → writeJson → fs.writeFileSync,
   // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
-  if (/(?:^|\/)\.flow-agents\/[^/]+\/trust\.bundle$/.test(norm)) {
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$/.test(norm)) {
     return {
-      name: '.flow-agents/<slug>/trust.bundle',
+      name: '.kontourai/flow-agents/<slug>/trust.bundle',
       reason: 'an agent could forge trust claims (verified status, impact level) to bypass gate integrity checks',
     };
   }
@@ -371,14 +382,14 @@ function checkCommandForBypass(command) {
 // When the agent uses a Bash tool (tool_input.command), detect redirects that
 // write to protected paths via shell redirect operators (> >>) or `tee`.
 //
-// R5a extends coverage to .flow-agents/<slug>/state.json and trust.bundle.
+// R5a extends coverage to flow-agents runtime state and trust.bundle.
 //
 // HONEST — INCOMPLETE COVERAGE: this catches the obvious forms only:
 //   - `cmd > ~/.bashrc`                        ✓ caught (> redirect operator)
 //   - `cmd >> .claude/settings.json`           ✓ caught (>> redirect operator)
-//   - `tee .flow-agents/current.json`          ✓ caught (tee command)
-//   - `cmd > .flow-agents/s/state.json`        ✓ caught (> redirect operator)
-//   - `tee .flow-agents/s/trust.bundle`        ✓ caught (tee command)
+//   - `tee .kontourai/flow-agents/current.json`   ✓ caught (tee command)
+//   - `cmd > .kontourai/flow-agents/s/state.json` ✓ caught (> redirect operator)
+//   - `tee .kontourai/flow-agents/s/trust.bundle` ✓ caught (tee command)
 //   - `sed -i ... .bashrc`                     ✗ NOT caught (in-place edit)
 //   - `interpreted-lang -c "open(...,'w')"     ✗ NOT caught (see interpreter check)
 //   - `/dev/fd` tricks, process substitution   ✗ NOT caught
@@ -391,10 +402,13 @@ function checkCommandForBypass(command) {
 /**
  * Regex that matches a normalized (forward-slash) path ending with a protected
  * kill-switch file: shell profiles, .claude/settings*.json,
- * .flow-agents/current.json, .flow-agents/<slug>/state.json,
- * .flow-agents/<slug>/trust.bundle.
+ * .kontourai/flow-agents/current.json,
+ * .kontourai/flow-agents/.goal-fit-block-streak.json,
+ * .kontourai/flow-agents/<slug>/state.json,
+ * .kontourai/flow-agents/<slug>/trust.bundle, and deprecated runtime-shaped
+ * .flow-agents equivalents.
  */
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)\.flow-agents\/current\.json$|(?:^|\/)\.flow-agents\/[^/]+\/state\.json$|(?:^|\/)\.flow-agents\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches
@@ -592,6 +606,61 @@ function checkCopyMoveToProtected(command) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Sanctioned remedies for blocked writes.
+//
+// AC7: for sidecar/gate kill-switch paths the block message MUST name the
+// sanctioned `npm run workflow:sidecar -- <command>` writer (or a human maintainer
+// for host-owned files) and MUST NEVER advise disabling the config-protection hook.
+// ---------------------------------------------------------------------------
+const READ_ONLY_TOOL_NAMES = new Set(['read', 'glob', 'grep', 'ls', 'notebookread', 'websearch', 'webfetch']);
+
+// WS8 (AC15): the remedy table (SHELL_PROFILE_REMEDY, SANCTIONED_REMEDIES, remedyFor,
+// REMEDY_COMMAND_CANDIDATES) was extracted verbatim to ./lib/config-protection-remedies.js
+// so it has an independently testable surface and this file is smaller. remedyForCommand
+// stays here because it depends on this file's tokenizer (splitSegments/tokenize/
+// checkProtectedPathPattern/PROTECTED_FILES). Behavior-preserving — no message text or
+// matching data changed.
+const { SHELL_PROFILE_REMEDY, remedyFor, REMEDY_COMMAND_CANDIDATES } = require('./lib/config-protection-remedies.js');
+
+/**
+ * Recover the sanctioned remedy for a blocked Bash command.
+ *
+ * Pass 1: exact path-pattern match on individual tokens -- handles shell
+ * redirects / tee / cp where the protected path is its own clean token
+ * (a bare redirect target, or a cp/mv destination argument).
+ *
+ * Pass 2: substring match against the raw command text -- handles
+ * interpreter-write commands where the protected path sits inside a quoted
+ * string followed by punctuation, so no token ends at the basename and
+ * Pass 1's dollar-anchored regex never matches. Any blocked command that
+ * references a path with a SANCTIONED_REMEDIES entry gets that entry's
+ * remedy instead of falling through to the generic (and often factually
+ * wrong) shell-profile advice.
+ *
+ * Never returns advice to disable the hook.
+ */
+function remedyForCommand(command) {
+  if (typeof command !== 'string') return SHELL_PROFILE_REMEDY;
+
+  const segments = splitSegments(command);
+  for (const seg of segments) {
+    for (const tok of tokenize(seg)) {
+      const match = checkProtectedPathPattern(tok);
+      if (match) return remedyFor(match.name);
+      if (PROTECTED_FILES.has(path.basename(tok))) return SHELL_PROFILE_REMEDY;
+    }
+  }
+
+  for (const candidate of REMEDY_COMMAND_CANDIDATES) {
+    if (candidate.needles.some((needle) => command.includes(needle))) {
+      return remedyFor(candidate.name);
+    }
+  }
+
+  return SHELL_PROFILE_REMEDY;
+}
+
 function run(inputOrRaw, options = {}) {
   if (options.truncated) {
     return {
@@ -604,8 +673,11 @@ function run(inputOrRaw, options = {}) {
   try {
     input = typeof inputOrRaw === 'string' ? JSON.parse(inputOrRaw) : inputOrRaw;
   } catch { return { exitCode: 0 }; }
+  const toolName = String(input?.tool_name || '').trim().toLowerCase();
   const filePath = input?.tool_input?.path || input?.tool_input?.file_path || '';
-  if (filePath) {
+  // Read-only tools never mutate a file, so path-based protection must not block them.
+  // (Bash is NOT read-only and stays fully covered by the command-based checks below.)
+  if (filePath && !READ_ONLY_TOOL_NAMES.has(toolName)) {
     const basename = path.basename(filePath);
     if (PROTECTED_FILES.has(basename)) {
       return {
@@ -623,7 +695,7 @@ function run(inputOrRaw, options = {}) {
         exitCode: 2,
         stderr: `BLOCKED: Writing to ${pathMatch.name} is not allowed. ` +
           `This file is protected because ${pathMatch.reason}. ` +
-          'If this is a legitimate change, disable the config-protection hook temporarily and document the reason.',
+          remedyFor(pathMatch.name),
       };
     }
   }
@@ -648,8 +720,8 @@ function run(inputOrRaw, options = {}) {
         exitCode: 2,
         stderr: `BLOCKED: Detected ${redirect} targeting a protected gate kill-switch file. ` +
           'Writing to shell profiles or Claude/flow-agents config files via shell redirect could ' +
-          'disable or tamper with the gate. If this is a legitimate operation, ' +
-          'disable the config-protection hook temporarily and document the reason. ' +
+          'disable or tamper with the gate. Do not disable this hook. ' +
+          remedyForCommand(command) + ' ' +
           'NOTE: This check has incomplete coverage (sed -i and similar forms are not caught).',
       };
     }
@@ -663,8 +735,8 @@ function run(inputOrRaw, options = {}) {
         exitCode: 2,
         stderr: `BLOCKED: Detected ${interpWrite} in a Bash command. ` +
           'Interpreter invocations (node -e, py3 -c, sed -i, perl -e) that reference ' +
-          'protected gate files could tamper with the gate. If this is a legitimate operation, ' +
-          'disable the config-protection hook temporarily and document the reason. ' +
+          'protected gate files could tamper with the gate. Do not disable this hook. ' +
+          remedyForCommand(command) + ' ' +
           'NOTE: This check has INCOMPLETE COVERAGE — runtime path construction evades it.',
       };
     }
@@ -677,8 +749,8 @@ function run(inputOrRaw, options = {}) {
         exitCode: 2,
         stderr: `BLOCKED: Detected ${copyMove} in a Bash command. ` +
           'Writing to delivery/trust.bundle or delivery/trust.checkpoint.json via cp/mv/install ' +
-          'could forge the CI trust anchor. The legitimate write path is the publishDelivery CLI ' +
-          '(fs.copyFileSync -- not the Write/Edit tool or bash cp). ' +
+          'could forge the CI trust anchor. Do not disable this hook. ' +
+          remedyForCommand(command) + ' ' +
           'NOTE: This check covers cp/mv/install only -- other copy tools may evade it.',
       };
     }

package/scripts/hooks/evidence-capture.js

@@ -9,7 +9,7 @@
  * against this captured truth: a check claiming a command passed while the log
  * shows it FAILED is a caught false-completion.
  *
- * Records to `.flow-agents/<slug>/command-log.jsonl`, one JSON object per line:
+ * Records to `.kontourai/flow-agents/<slug>/command-log.jsonl`, one JSON object per line:
  *   {
  *     "command":        "<the command string the agent ran>",
  *     "observedResult": "pass" | "fail",   // deterministically inferred
@@ -168,7 +168,7 @@ function readJsonFile(file) {
   try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
 }
 
-// Newest-mtime state.json under .flow-agents/<slug>/, mirroring how
+// Newest-mtime state.json under .kontourai/flow-agents/<slug>/, mirroring how
 // workflow-steering.js and stop-goal-fit.js locate the active artifact dir.
 function latestStateDir(flowAgentsDir) {
   let best = null;
@@ -194,7 +194,7 @@ function latestStateDir(flowAgentsDir) {
 
 /**
  * Resolve the active artifact directory the same way the other hooks do:
- * prefer .flow-agents/current.json (active_slug / artifact_dir), then fall back
+ * prefer .kontourai/flow-agents/current.json (active_slug / artifact_dir), then fall back
  * to the newest-mtime state.json directory.
  */
 function resolveArtifactDir(root) {