@kontourai/flow-agents 3.4.1 → 3.4.2

package/evals/integration/test_workflow_steering_hook.sh

@@ -21,6 +21,78 @@ mkdir -p "$REPO/docs"
 printf '# Test Repo\n' > "$REPO/AGENTS.md"
 printf '# Context Map\n' > "$REPO/docs/context-map.md"
 
+ENTRY_REPO="$TMPDIR_EVAL/entry-repo"
+ENTRY_COMMAND='flow-agents builder-run start --session-dir .kontourai/flow-agents/entry-demo'
+mkdir -p "$ENTRY_REPO/.kontourai/flow-agents/entry-demo"
+printf '# Entry Repo\n' > "$ENTRY_REPO/AGENTS.md"
+cat > "$ENTRY_REPO/.kontourai/flow-agents/entry-demo/state.json" <<JSON
+{
+  "schema_version": "1.0",
+  "task_slug": "entry-demo",
+  "status": "new",
+  "phase": "pickup",
+  "updated_at": "2026-07-10T00:00:00Z",
+  "next_action": {
+    "status": "continue",
+    "summary": "Start the canonical Flow run.",
+    "skills": ["pull-work"],
+    "command": "$ENTRY_COMMAND",
+    "enforcement": "before_tool_use"
+  }
+}
+JSON
+
+if node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/entry-direct.out" 2>"$TMPDIR_EVAL/entry-direct.err" <<JSON
+{"hook_event_name":"PreToolUse","cwd":"$ENTRY_REPO","tool_name":"Bash","tool_input":{"command":"git status --short"}}
+JSON
+then
+  _fail "workflow entry enforcement should block unrelated tools"
+else
+  status=$?
+  if [[ "$status" -eq 2 ]] && rg -F -q "Run exactly: $ENTRY_COMMAND" "$TMPDIR_EVAL/entry-direct.err"; then
+    _pass "workflow entry enforcement blocks unrelated tools with the projected action"
+  else
+    _fail "workflow entry enforcement returned the wrong direct-hook decision: rc=$status $(cat "$TMPDIR_EVAL/entry-direct.err")"
+  fi
+fi
+
+if node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/entry-allow.out" 2>"$TMPDIR_EVAL/entry-allow.err" <<JSON
+{"hook_event_name":"PreToolUse","cwd":"$ENTRY_REPO","tool_name":"Bash","tool_input":{"command":"$ENTRY_COMMAND"}}
+JSON
+then
+  _pass "workflow entry enforcement allows the exact projected action"
+else
+  _fail "workflow entry enforcement blocked the projected action: $(cat "$TMPDIR_EVAL/entry-allow.err")"
+fi
+
+for adapter in codex claude; do
+  if [[ "$adapter" == "codex" ]]; then
+    adapter_command=(node "$ROOT/scripts/hooks/codex-hook-adapter.js" pre:workflow-entry workflow-steering.js standard,strict)
+  else
+    adapter_command=(node "$ROOT/scripts/hooks/claude-hook-adapter.js" PreToolUse pre:workflow-entry workflow-steering.js standard,strict)
+  fi
+  if "${adapter_command[@]}" >"$TMPDIR_EVAL/entry-$adapter.out" 2>"$TMPDIR_EVAL/entry-$adapter.err" <<JSON
+{"hook_event_name":"PreToolUse","cwd":"$ENTRY_REPO","tool_name":"Bash","tool_input":{"command":"git status --short"}}
+JSON
+  then
+    if node - "$TMPDIR_EVAL/entry-$adapter.out" "$ENTRY_COMMAND" <<'NODE'
+const fs = require('node:fs');
+const payload = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const expected = process.argv[3];
+if (payload.hookSpecificOutput?.hookEventName !== 'PreToolUse') process.exit(1);
+if (payload.hookSpecificOutput?.permissionDecision !== 'deny') process.exit(1);
+if (!String(payload.hookSpecificOutput?.permissionDecisionReason || '').includes(expected)) process.exit(1);
+NODE
+    then
+      _pass "$adapter adapter translates projected-action enforcement into a PreToolUse denial"
+    else
+      _fail "$adapter adapter returned the wrong projected-action denial: $(cat "$TMPDIR_EVAL/entry-$adapter.out")"
+    fi
+  else
+    _fail "$adapter adapter should translate a policy block without failing: $(cat "$TMPDIR_EVAL/entry-$adapter.err")"
+  fi
+done
+
 cat > "$REPO/.kontourai/flow-agents/steering-demo/state.json" <<'JSON'
 {
   "schema_version": "1.0",

package/kits/builder/skills/continue-work/SKILL.md

@@ -27,6 +27,13 @@ continue-work ties these together for **one job**: take a multi-slice work item
 - The request is **brand-new work** with nothing landed yet — that is selection from the backlog. Route to `pull-work`.
 - The request is to **resume the *same* interrupted slice** after a restart (same in-flight slice, mid-execution, picking up new hooks/logic) — that is the resume surface (#153), which reconstructs `state.json` + `handoff.json` + plan + `trust.bundle` for the *same* increment. continue-work advances to the *next* increment; it does not re-enter an unfinished one.
 
+For that same-slice case, when a canonical Builder Flow run already exists, restore
+its sidecar/current projection with `flow-agents builder-run recover --session-dir
+.kontourai/flow-agents/<slug>` before following the resume surface. The command
+derives run identity from the session slug and only loads, validates, and projects;
+never invent or supply a run id or step, and use `builder-run sync` separately only
+when recorded evidence should be attached and evaluated.
+
 If the boundary is ambiguous (is this the next slice or the same one?), stop and ask one question before routing. Do not silently assume.
 
 ## Boundary (ADR 0014)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.4.1",
+  "version": "3.4.2",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/schemas/workflow-state.schema.json

@@ -122,6 +122,13 @@
         "command": {
           "type": "string",
           "minLength": 1
+        },
+        "enforcement": {
+          "type": "string",
+          "enum": [
+            "advisory",
+            "before_tool_use"
+          ]
         }
       }
     }

package/scripts/hooks/workflow-steering.js

@@ -9,7 +9,8 @@
  * survive context loss instead of relying on the model voluntarily re-reading
  * the sidecar.
  *
- * Non-blocking — always exits 0.
+ * Advisory by default. A structured next action may explicitly require its
+ * projected command before unrelated tool use; only that PreToolUse case blocks.
  */
 
 'use strict';
@@ -282,6 +283,32 @@ function stateSteering(root) {
   return parts.join(' ');
 }
 
+function normalizedCommand(value) {
+  return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
+}
+
+function toolCommands(input) {
+  const toolInput = input && input.tool_input && typeof input.tool_input === 'object' ? input.tool_input : {};
+  return [
+    toolInput.command,
+    toolInput.content && toolInput.content.command,
+    toolInput.args && toolInput.args.command,
+  ].map(normalizedCommand).filter(Boolean);
+}
+
+function beforeToolUseEnforcement(input, current) {
+  if (!input || input.hook_event_name !== 'PreToolUse' || !current) return null;
+  const next = current.payload && current.payload.next_action;
+  if (!next || next.status !== 'continue' || next.enforcement !== 'before_tool_use') return null;
+  const expected = normalizedCommand(next.command);
+  if (!expected) return null;
+  if (toolCommands(input).some(command => command === expected)) return null;
+  return {
+    exitCode: 2,
+    stderr: `[workflow-entry] Run the required projected action before using other tools. Run exactly: ${safeStateText(expected, 500)}`,
+  };
+}
+
 function contextMapSteering(root) {
   const mapPath = path.join(root, 'docs', 'context-map.md');
   if (!fs.existsSync(mapPath)) return '';
@@ -572,6 +599,8 @@ function run(rawInput) {
     const toolInput = input.tool_input || {};
     const root = findRepoRoot(input.cwd || process.cwd());
     const current = latestWorkflowState(root);
+    const enforcement = beforeToolUseEnforcement(input, current);
+    if (enforcement) return enforcement;
     const hints = [];
     let shouldAppendWorkflowContext = false;
 
@@ -648,7 +677,14 @@ if (require.main === module) {
     data += chunk;
   });
   process.stdin.on('end', () => {
-    process.stdout.write(String(run(data)));
+    const result = run(data);
+    if (result && typeof result === 'object') {
+      if (result.stderr) process.stderr.write(String(result.stderr) + (String(result.stderr).endsWith('\n') ? '' : '\n'));
+      if (Object.prototype.hasOwnProperty.call(result, 'stdout')) process.stdout.write(String(result.stdout || ''));
+      process.exitCode = Number.isInteger(result.exitCode) ? result.exitCode : 0;
+    } else {
+      process.stdout.write(String(result));
+    }
   });
 }
 
@@ -667,4 +703,6 @@ module.exports = {
   promptText,
   looksLikeImplementationWork,
   kitWorkflowSteering,
+  beforeToolUseEnforcement,
+  toolCommands,
 };

package/scripts/install-merge.js

@@ -41,13 +41,14 @@ const path = require("node:path");
 const os = require("node:os");
 
 // ─── Marker strings ───────────────────────────────────────────────────────────
-// These three statusMessage strings identify every flow-agents managed hook.
+// These statusMessage strings identify every flow-agents managed hook.
 // They are the same strings used by COLLISION_MARKER in src/cli/init.ts and
 // by exportClaudeSettings() / exportCodexHooks() in build-universal-bundles.ts.
 const FA_MARKERS = [
   "Recording Flow Agents telemetry",
   "Running Flow Agents hook policy",
   "Capturing Flow Agents command evidence",
+  "Enforcing Flow Agents projected action",
 ];
 
 const FA_OWNERSHIP_MARKERS = [

package/src/builder-flow-runtime.ts

@@ -44,10 +44,28 @@ type SessionContext = {
   bundleFile: string;
 };
 
+type SidecarSnapshot = {
+  state: AnyRecord;
+  raw: string;
+};
+
+type ProjectionTargetSnapshot = {
+  file: string;
+  raw: string | null;
+  root: string;
+  field: string;
+};
+
+type PreparedProjectionWrites = {
+  targets: ProjectionTargetSnapshot[];
+  actorEntries: string[] | null;
+  writes: Array<{ file: string; content: string }>;
+};
+
 export async function startBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult> {
   const context = resolveSessionContext(input.sessionDir);
-  const sidecarState = readSidecarState(context);
-  const subject = workflowSubject(sidecarState);
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const subject = workflowSubject(sidecarSnapshot.state);
   let run: BuilderBuildRunResult;
   try {
     run = await loadBuilderBuildRun({
@@ -77,6 +95,33 @@ export async function syncBuilderFlowSession(input: BuilderFlowSessionInput): Pr
   return syncAndProject(context, run);
 }
 
+export async function recoverBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult> {
+  const context = resolveSessionContext(input.sessionDir);
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const subject = workflowSubject(sidecarSnapshot.state);
+  const run = await loadBuilderBuildRun({
+    cwd: context.projectRoot,
+    runId: context.slug,
+  });
+  if (run.state.subject !== subject) {
+    throw new BuilderBuildRunInputError("flow_run.state.subject", "must match the selected Work Item");
+  }
+  if (isRecord(run.state.params)
+    && Object.prototype.hasOwnProperty.call(run.state.params, "subject")
+    && run.state.params.subject !== subject) {
+    throw new BuilderBuildRunInputError("flow_run.state.params.subject", "must match the selected Work Item");
+  }
+  const projection = projectFlowRun(context, run, sidecarSnapshot.state);
+  writeProjection(context, projection, sidecarSnapshot.raw, "recovery");
+  return {
+    sessionDir: context.sessionDir,
+    projectRoot: context.projectRoot,
+    run,
+    projection,
+    attached: false,
+  };
+}
+
 export async function syncBuilderFlowSessionIfPresent(sessionDir: string): Promise<BuilderFlowSessionResult | null> {
   let context: SessionContext;
   try {
@@ -119,8 +164,9 @@ async function syncAndProject(context: SessionContext, initial: BuilderBuildRunR
       }
     }
   }
-  const projection = projectFlowRun(context, run);
-  writeProjection(context, projection);
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const projection = projectFlowRun(context, run, sidecarSnapshot.state);
+  writeProjection(context, projection, sidecarSnapshot.raw, "projection");
   return {
     sessionDir: context.sessionDir,
     projectRoot: context.projectRoot,
@@ -137,6 +183,7 @@ function resolveSessionContext(sessionDirInput: string): SessionContext {
   if (path.basename(artifactRoot) !== "flow-agents" || path.basename(kontouraiRoot) !== ".kontourai") {
     throw new BuilderBuildRunInputError("sessionDir", "must be .kontourai/flow-agents/<slug>");
   }
+  assertSafeDirectory(sessionDir, artifactRoot, "sessionDir");
   const slug = path.basename(sessionDir);
   if (!slug || slug === "." || slug === "..") {
     throw new BuilderBuildRunInputError("sessionDir", "must name a session");
@@ -145,6 +192,7 @@ function resolveSessionContext(sessionDirInput: string): SessionContext {
   if (!fs.existsSync(stateFile)) {
     throw new BuilderBuildRunInputError("sessionDir", "must contain state.json");
   }
+  assertSafeFile(stateFile, sessionDir, "state.json");
   return {
     sessionDir,
     artifactRoot,
@@ -155,19 +203,22 @@ function resolveSessionContext(sessionDirInput: string): SessionContext {
   };
 }
 
-function readSidecarState(context: SessionContext): AnyRecord {
-  const value = JSON.parse(fs.readFileSync(context.stateFile, "utf8"));
+function readSidecarSnapshot(context: SessionContext): SidecarSnapshot {
+  assertSafeFile(context.stateFile, context.sessionDir, "state.json");
+  const raw = fs.readFileSync(context.stateFile, "utf8");
+  const value = JSON.parse(raw);
   if (!isRecord(value) || value.task_slug !== context.slug) {
     throw new BuilderBuildRunInputError("sessionDir", "state.json task_slug must match the session directory");
   }
-  return value;
+  return { state: value, raw };
 }
 
 function workflowSubject(state: AnyRecord): string {
-  const refs = Array.isArray(state.work_item_refs)
-    ? state.work_item_refs.filter((value: unknown): value is string => typeof value === "string" && value.length > 0)
-    : [];
-  if (refs.length !== 1) {
+  const refs = state.work_item_refs;
+  if (!Array.isArray(refs)
+    || refs.length !== 1
+    || typeof refs[0] !== "string"
+    || refs[0].trim().length === 0) {
     throw new BuilderBuildRunInputError("state.work_item_refs", "must contain exactly one selected Work Item for builder.build");
   }
   return refs[0]!;
@@ -225,8 +276,7 @@ function manifestEvidence(manifest: JsonObject): AnyRecord[] {
   return Array.isArray(manifest.evidence) ? manifest.evidence.filter(isRecord) : [];
 }
 
-function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult): AnyRecord {
-  const sidecar = readSidecarState(context);
+function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult, sidecar: AnyRecord): AnyRecord {
   const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
   const gates = openGates(definition, run.state) as Array<FlowGate & { id: string }>;
   const complete = run.state.status === "completed";
@@ -279,23 +329,164 @@ function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult): An
   };
 }
 
-function writeProjection(context: SessionContext, projection: AnyRecord): void {
-  fs.writeFileSync(context.stateFile, `${JSON.stringify(projection, null, 2)}\n`);
-  const pointerFiles = [path.join(context.artifactRoot, "current.json")];
+function writeProjection(context: SessionContext, projection: AnyRecord, expectedStateRaw: string, operation: string): void {
+  const prepared = prepareProjectionWrites(context, projection, expectedStateRaw, operation);
+  assertProjectionTargetsUnchanged(context, prepared, operation);
+  for (const write of prepared.writes) writeExistingFileNoFollow(write.file, write.content);
+}
+
+function prepareProjectionWrites(
+  context: SessionContext,
+  projection: AnyRecord,
+  expectedStateRaw: string,
+  operation: string,
+): PreparedProjectionWrites {
+  const targets: ProjectionTargetSnapshot[] = [];
+  const writes: Array<{ file: string; content: string }> = [];
+  const stateTarget = readProjectionTarget(context.stateFile, context.sessionDir, "state.json");
+  targets.push(stateTarget);
+  if (stateTarget.raw !== expectedStateRaw) {
+    throw new BuilderBuildRunInputError("state.json", `changed during ${operation}`);
+  }
+  writes.push({ file: context.stateFile, content: `${JSON.stringify(projection, null, 2)}\n` });
+
+  const pointerFiles: string[] = [];
+  const globalPointer = path.join(context.artifactRoot, "current.json");
+  const globalTarget = readOptionalProjectionTarget(globalPointer, context.artifactRoot, "current.json");
+  targets.push(globalTarget);
+  if (globalTarget.raw !== null) pointerFiles.push(globalPointer);
+
   const actorRoot = path.join(context.artifactRoot, "current");
-  if (fs.existsSync(actorRoot)) {
-    pointerFiles.push(...fs.readdirSync(actorRoot)
-      .filter((name) => name.endsWith(".json"))
-      .map((name) => path.join(actorRoot, name)));
+  let actorEntries: string[] | null = null;
+  if (pathExistsNoFollow(actorRoot)) {
+    assertSafeDirectory(actorRoot, context.artifactRoot, "current directory");
+    actorEntries = fs.readdirSync(actorRoot).sort();
+    for (const name of actorEntries) {
+      const file = path.join(actorRoot, name);
+      const stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink()) {
+        throw new BuilderBuildRunInputError("projection target", `current/${name} must not be a symbolic link`);
+      }
+      if (!name.endsWith(".json")) continue;
+      if (!stat.isFile()) {
+        throw new BuilderBuildRunInputError("projection target", `current/${name} must be a regular file`);
+      }
+      const target = readProjectionTarget(file, actorRoot, `current/${name}`);
+      targets.push(target);
+      pointerFiles.push(file);
+    }
   }
+
   for (const file of pointerFiles) {
-    if (!fs.existsSync(file)) continue;
-    const pointer = JSON.parse(fs.readFileSync(file, "utf8"));
+    const target = targets.find((candidate) => candidate.file === file)!;
+    const pointer = parseProjectionTarget(target);
     if (!isRecord(pointer) || pointer.active_slug !== context.slug) continue;
-    pointer.active_flow_id = BUILDER_BUILD_FLOW_ID;
-    pointer.active_step_id = projection.flow_run.current_step;
-    pointer.updated_at = projection.updated_at;
-    fs.writeFileSync(file, `${JSON.stringify(pointer, null, 2)}\n`);
+    const output = {
+      ...pointer,
+      active_flow_id: BUILDER_BUILD_FLOW_ID,
+      active_step_id: projection.flow_run.current_step,
+      updated_at: projection.updated_at,
+    };
+    writes.push({ file, content: `${JSON.stringify(output, null, 2)}\n` });
+  }
+  return { targets, actorEntries, writes };
+}
+
+function assertProjectionTargetsUnchanged(
+  context: SessionContext,
+  prepared: PreparedProjectionWrites,
+  operation: string,
+): void {
+  const actorRoot = path.join(context.artifactRoot, "current");
+  const currentActorEntries = pathExistsNoFollow(actorRoot)
+    ? (assertSafeDirectory(actorRoot, context.artifactRoot, "current directory"), fs.readdirSync(actorRoot).sort())
+    : null;
+  if (JSON.stringify(currentActorEntries) !== JSON.stringify(prepared.actorEntries)) {
+    throw new BuilderBuildRunInputError("current", `directory changed during ${operation}`);
+  }
+  for (const target of prepared.targets) {
+    const current = readOptionalProjectionTarget(target.file, target.root, target.field);
+    if (current.raw !== target.raw) {
+      throw new BuilderBuildRunInputError(target.field, `changed during ${operation}`);
+    }
+  }
+}
+
+function readOptionalProjectionTarget(file: string, root: string, field: string): ProjectionTargetSnapshot {
+  if (!pathExistsNoFollow(file)) return { file, raw: null, root, field };
+  return readProjectionTarget(file, root, field);
+}
+
+function readProjectionTarget(file: string, root: string, field: string): ProjectionTargetSnapshot {
+  assertSafeFile(file, root, field);
+  return { file, raw: fs.readFileSync(file, "utf8"), root, field };
+}
+
+function parseProjectionTarget(target: ProjectionTargetSnapshot): unknown {
+  try {
+    return JSON.parse(target.raw!);
+  } catch (error) {
+    throw new BuilderBuildRunInputError("projection target", `${target.field} must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function assertSafeDirectory(directory: string, root: string, field: string): void {
+  if (!pathExistsNoFollow(directory)) {
+    throw new BuilderBuildRunInputError(field, "must exist");
+  }
+  const stat = fs.lstatSync(directory);
+  if (stat.isSymbolicLink()) {
+    throw new BuilderBuildRunInputError(field, "must not be a symbolic link");
+  }
+  if (!stat.isDirectory()) {
+    throw new BuilderBuildRunInputError(field, "must be a directory");
+  }
+  assertContainedPath(directory, root, field);
+}
+
+function pathExistsNoFollow(candidate: string): boolean {
+  try {
+    fs.lstatSync(candidate);
+    return true;
+  } catch (error) {
+    if (isRecord(error) && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function assertSafeFile(file: string, root: string, field: string): void {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink()) {
+    throw new BuilderBuildRunInputError(field, "must not be a symbolic link");
+  }
+  if (!stat.isFile()) {
+    throw new BuilderBuildRunInputError(field, "must be a regular file");
+  }
+  assertContainedPath(file, root, field);
+}
+
+function assertContainedPath(candidate: string, root: string, field: string): void {
+  if (!pathIsWithin(candidate, root)) {
+    throw new BuilderBuildRunInputError(field, "must remain within its expected artifact root");
+  }
+  const realCandidate = fs.realpathSync(candidate);
+  const realRoot = fs.realpathSync(root);
+  if (!pathIsWithin(realCandidate, realRoot)) {
+    throw new BuilderBuildRunInputError(field, "must not escape its expected artifact root");
+  }
+}
+
+function pathIsWithin(candidate: string, root: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function writeExistingFileNoFollow(file: string, content: string): void {
+  const descriptor = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW);
+  try {
+    fs.writeFileSync(descriptor, content);
+  } finally {
+    fs.closeSync(descriptor);
   }
 }