@kontourai/flow-agents 3.4.1 → 3.4.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [3.4.2](https://github.com/kontourai/flow-agents/compare/v3.4.1...v3.4.2) (2026-07-10)
+
+
+### Fixes
+
+* enforce canonical Builder entry action ([#536](https://github.com/kontourai/flow-agents/issues/536)) ([bab5dfe](https://github.com/kontourai/flow-agents/commit/bab5dfe419a42b137dcb79bd276edf3268c5fb23))
+
 ## [3.4.1](https://github.com/kontourai/flow-agents/compare/v3.4.0...v3.4.1) (2026-07-10)
 
 

package/agents/dev.json

@@ -53,6 +53,11 @@
         "matcher": "*",
         "timeout_ms": 3000
       },
+      {
+        "command": "node ~/.flow-agents/scripts/hooks/run-hook.js pre:workflow-entry workflow-steering.js standard,strict",
+        "matcher": "*",
+        "timeout_ms": 5000
+      },
       {
         "command": "node ~/.flow-agents/scripts/hooks/run-hook.js pre:config-protection config-protection.js standard,strict",
         "matcher": "fs_write",

package/build/src/builder-flow-runtime.d.ts

@@ -12,5 +12,6 @@ export interface BuilderFlowSessionResult {
 }
 export declare function startBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function syncBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
+export declare function recoverBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function syncBuilderFlowSessionIfPresent(sessionDir: string): Promise<BuilderFlowSessionResult | null>;
 export {};

package/build/src/builder-flow-runtime.js

@@ -5,8 +5,8 @@ import { expectationsForGate, openGates, readJson, runDir, sha256File, } from "@
 import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, evaluateBuilderBuildRun, loadBuilderBuildRun, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export async function startBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
-    const sidecarState = readSidecarState(context);
-    const subject = workflowSubject(sidecarState);
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
     let run;
     try {
         run = await loadBuilderBuildRun({
@@ -36,6 +36,32 @@ export async function syncBuilderFlowSession(input) {
     });
     return syncAndProject(context, run);
 }
+export async function recoverBuilderFlowSession(input) {
+    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) {
     let context;
     try {
@@ -78,8 +104,9 @@ async function syncAndProject(context, initial) {
             }
         }
     }
-    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,
@@ -95,6 +122,7 @@ function resolveSessionContext(sessionDirInput) {
     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");
@@ -103,6 +131,7 @@ function resolveSessionContext(sessionDirInput) {
     if (!fs.existsSync(stateFile)) {
         throw new BuilderBuildRunInputError("sessionDir", "must contain state.json");
     }
+    assertSafeFile(stateFile, sessionDir, "state.json");
     return {
         sessionDir,
         artifactRoot,
@@ -112,18 +141,21 @@ function resolveSessionContext(sessionDirInput) {
         bundleFile: path.join(sessionDir, "trust.bundle"),
     };
 }
-function readSidecarState(context) {
-    const value = JSON.parse(fs.readFileSync(context.stateFile, "utf8"));
+function readSidecarSnapshot(context) {
+    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) {
-    const refs = Array.isArray(state.work_item_refs)
-        ? state.work_item_refs.filter((value) => 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];
@@ -174,8 +206,7 @@ function workflowSubjectRef(claim) {
 function manifestEvidence(manifest) {
     return Array.isArray(manifest.evidence) ? manifest.evidence.filter(isRecord) : [];
 }
-function projectFlowRun(context, run) {
-    const sidecar = readSidecarState(context);
+function projectFlowRun(context, run, sidecar) {
     const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
     const gates = openGates(definition, run.state);
     const complete = run.state.status === "completed";
@@ -227,25 +258,150 @@ function projectFlowRun(context, run) {
         next_action: nextAction,
     };
 }
-function writeProjection(context, projection) {
-    fs.writeFileSync(context.stateFile, `${JSON.stringify(projection, null, 2)}\n`);
-    const pointerFiles = [path.join(context.artifactRoot, "current.json")];
+function writeProjection(context, projection, expectedStateRaw, operation) {
+    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, projection, expectedStateRaw, operation) {
+    const targets = [];
+    const writes = [];
+    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 = [];
+    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 = 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, prepared, operation) {
+    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, root, field) {
+    if (!pathExistsNoFollow(file))
+        return { file, raw: null, root, field };
+    return readProjectionTarget(file, root, field);
+}
+function readProjectionTarget(file, root, field) {
+    assertSafeFile(file, root, field);
+    return { file, raw: fs.readFileSync(file, "utf8"), root, field };
+}
+function parseProjectionTarget(target) {
+    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, root, field) {
+    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) {
+    try {
+        fs.lstatSync(candidate);
+        return true;
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function assertSafeFile(file, root, field) {
+    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, root, field) {
+    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, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function writeExistingFileNoFollow(file, content) {
+    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);
     }
 }
 function stepAction(stepId) {

package/build/src/cli/builder-run.js

@@ -1,20 +1,29 @@
 import { flagString, parseArgs } from "../lib/args.js";
-import { startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import { recoverBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
 export async function main(argv) {
     const parsed = parseArgs(argv);
     const action = parsed.positionals[0];
     const sessionDir = flagString(parsed.flags, "session-dir");
+    const validRecoveryArguments = parsed.positionals.length === 1
+        && Object.keys(parsed.flags).length === 1
+        && typeof parsed.flags["session-dir"] === "string";
+    if (action === "recover" && !validRecoveryArguments) {
+        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+        return 64;
+    }
     if (!sessionDir) {
         console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
         return 64;
     }
-    if (action !== "start" && action !== "sync") {
-        console.error("Usage: flow-agents builder-run <start|sync> --session-dir <path>");
+    if (action !== "start" && action !== "sync" && action !== "recover") {
+        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
         return 64;
     }
     const result = action === "start"
         ? await startBuilderFlowSession({ sessionDir })
-        : await syncBuilderFlowSession({ sessionDir });
+        : action === "sync"
+            ? await syncBuilderFlowSession({ sessionDir })
+            : await recoverBuilderFlowSession({ sessionDir });
     console.log(JSON.stringify({
         run_id: result.run.runId,
         definition_id: result.run.definitionId,

package/build/src/cli/workflow-sidecar.js

@@ -1692,12 +1692,16 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
     // existing state.json's created_at when present; stamp only on true first-creation.
     // updated_at still reflects "now" on every call — that field is intentionally mutable.
     const retainedWorkItemRefs = workItemRefs.length > 0 ? workItemRefs : (Array.isArray(existingState.work_item_refs) ? existingState.work_item_refs : []);
+    const nextActionSummary = typeof nextAction === "string" ? nextAction : String(nextAction.summary ?? summary);
+    const nextActionPayload = typeof nextAction === "string"
+        ? { status: "continue", summary: nextAction || summary }
+        : { status: "continue", ...nextAction, summary: nextActionSummary };
     writeJson(path.join(dir, "state.json"), {
         ...sidecarBase(slug), status: initialLifecycle?.status ?? "planned", phase: initialLifecycle?.phase ?? "planning", created_at: existingState.created_at || timestamp, updated_at: timestamp,
         ...(branch ? { branch } : {}),
         ...(retainedWorkItemRefs.length > 0 ? { work_item_refs: retainedWorkItemRefs } : {}),
         artifact_paths: relArtifacts(dir),
-        next_action: { status: "continue", summary: nextAction || summary },
+        next_action: nextActionPayload,
     });
     writeJson(path.join(dir, "acceptance.json"), {
         ...sidecarBase(slug), source_request: sourceRequest,
@@ -1705,7 +1709,7 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
         goal_fit: { status: "pending", summary: "Goal fit has not been verified yet." },
     });
     writeJson(path.join(dir, "handoff.json"), {
-        ...sidecarBase(slug), summary, current_state_ref: "state.json", next_steps: nextAction ? [nextAction] : [], blockers: [], warnings: [],
+        ...sidecarBase(slug), summary, current_state_ref: "state.json", next_steps: nextActionSummary ? [nextActionSummary] : [], blockers: [], warnings: [],
     });
 }
 /** Read a `--*-json` flag's value as a file path (or `-` for stdin), mirroring
@@ -1964,9 +1968,16 @@ function ensureSession(p) {
     if (!fs.existsSync(path.join(dir, "state.json")) || !fs.existsSync(path.join(dir, "acceptance.json")) || !fs.existsSync(path.join(dir, "handoff.json"))) {
         const phaseMap = entry.flowId ? resolvePhaseMap(entry.flowId, findRepoRootFromDir(dir)) : null;
         const initialPhase = Object.entries(phaseMap ?? {}).find(([, step]) => step === entry.firstStep)?.[0];
+        const startCommand = `flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}`;
         const nextAction = entry.flowId
             ? entry.flowId === "builder.build"
-                ? `Start the canonical Flow run with \`flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}\`; activate \`pull-work\` for work item ${JSON.stringify(workItem.ref)}, and satisfy the declared gate before advancing.`
+                ? {
+                    status: "continue",
+                    summary: `Start the canonical Flow run; activate \`pull-work\` for work item ${JSON.stringify(workItem.ref)}, and satisfy the declared gate before advancing.`,
+                    skills: ["pull-work"],
+                    command: startCommand,
+                    enforcement: "before_tool_use",
+                }
                 : `Continue at Flow step ${JSON.stringify(entry.stepId)} for work item ${JSON.stringify(workItem.ref)}; satisfy its declared gate before advancing.`
             : opt(p, "next-action", "Continue.");
         initSidecars(dir, slug, opt(p, "source-request"), opt(p, "summary"), nextAction, timestamp, md, [workItem.ref], initialPhase ? { status: "new", phase: initialPhase } : undefined);

package/build/src/tools/build-universal-bundles.js

@@ -363,6 +363,7 @@ function exportClaudeSettings() {
     hooks.UserPromptSubmit.push({ hooks: [shellHook(claudePolicy("UserPromptSubmit", "workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
     hooks.PostToolUse.push({ hooks: [shellHook(claudePolicy("PostToolUse", "quality-gate.js"), 30, "Running Flow Agents hook policy")] });
     hooks.PostToolUse.push({ hooks: [shellHook(claudePolicy("PostToolUse", "evidence-capture.js"), 30, "Capturing Flow Agents command evidence")] });
+    hooks.PreToolUse.push({ hooks: [shellHook(claudePolicy("PreToolUse", "workflow-steering.js"), 30, "Enforcing Flow Agents projected action")] });
     hooks.PreToolUse.push({ hooks: [shellHook(claudePolicy("PreToolUse", "config-protection.js"), 30, "Running Flow Agents hook policy")] });
     return `${JSON.stringify({
         statusLine: { type: "command", command: 'bash -lc \'root="${CLAUDE_PROJECT_DIR:-$(pwd)}"; node "$root/scripts/statusline/flow-agents-statusline.js"\'' },
@@ -380,6 +381,7 @@ function exportCodexHooks() {
     hooks.SessionStart.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
     hooks.UserPromptSubmit.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
     hooks.PostToolUse.push({ hooks: [shellHook(codexPolicy("evidence-capture.js"), 30, "Capturing Flow Agents command evidence")] });
+    hooks.PreToolUse.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Enforcing Flow Agents projected action")] });
     return `${JSON.stringify({ hooks }, null, 2)}\n`;
 }
 function copySharedContent(targetRoot, targetName, token) {

package/context/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/docs/spec/builder-flow-runtime.md

@@ -35,6 +35,12 @@ workflow sidecar. Start the canonical run with:
 flow-agents builder-run start --session-dir .kontourai/flow-agents/<slug>
 ```
 
+The initial sidecar projects this as `next_action.command` with
+`enforcement: "before_tool_use"`. Runtime adapters deny unrelated tool calls until
+the projected command runs. Starting the canonical run replaces that bootstrap
+action with the ordinary Flow-step projection; later actions remain advisory while
+the agent performs their declared skills and operations.
+
 `start` requires exactly one `state.work_item_refs` entry and uses that stable Work
 Item reference as the Flow run subject. It is idempotent for an existing canonical
 run. A direct primitive session without a Builder Flow stamp remains independent and
@@ -51,6 +57,28 @@ Synchronization is digest-idempotent. The same trust bundle is not attached twic
 Inspection loads the run without evaluating it, so invalid evidence is rejected
 before Flow mutation.
 
+## Recovery
+
+Recover an interrupted canonical Builder session with:
+
+```bash
+flow-agents builder-run recover --session-dir .kontourai/flow-agents/<slug>
+```
+
+`recover` derives the Flow run id from the session directory slug; callers cannot
+select a run id or step. It requires exactly one non-empty
+`state.work_item_refs` entry, loads the existing run through Flow's canonical load
+API, and verifies that the ref matches persisted `state.subject` and, when present,
+`state.params.subject`. A missing, foreign, or corrupt run fails closed and is not
+created or repaired.
+
+Recovery is load/validate/project only. It computes the complete projection before
+updating `state.json`, the matching global `current.json`, and matching per-actor
+current pointers. It does not inspect or attach `trust.bundle`, evaluate gates, or
+write any file in `.kontourai/flow/runs/<slug>/`; the complete Flow run tree remains
+byte-identical. Use `sync`, not `recover`, to attach recorded evidence and evaluate
+the current gate.
+
 ## Trust Binding
 
 Claims relevant to the current gate must carry

package/docs/spec/runtime-hook-surface.md

@@ -123,16 +123,16 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 
 **Canonical script**: `scripts/hooks/workflow-steering.js`
 
-**Canonical trigger event**: `userPromptSubmit` and `agentSpawn`/`SessionStart` (active-goal re-grounding), `postToolUse` (after `InvokeSubagents` tool calls)
+**Canonical trigger event**: `userPromptSubmit` and `agentSpawn`/`SessionStart` (active-goal re-grounding), `postToolUse` (after `InvokeSubagents` tool calls), and `preToolUse` when the projected `next_action` explicitly declares `enforcement: "before_tool_use"`
 
 **Inputs consumed**:
 - `.kontourai/flow-agents/<slug>/state.json` — current workflow phase and status
 - `.kontourai/flow-agents/<slug>/critique.json` — open critique findings
 - `docs/context-map.md` — structure hint for repo navigation
 
-**Decision contract**: Non-blocking. Always exits 0. Appends steering text to the agent's context via `additionalContext` in the hook response. Does not block any action. It re-grounds the active workflow goal (status, phase, recorded next step) at the start of every user turn — not only for flagged/blocked states — and on `SessionStart`, which fires after context compaction and on resume. This is the mechanism that keeps an in-flight goal alive across context loss instead of relying on the model voluntarily re-reading the sidecar.
+**Decision contract**: Advisory by default. It appends steering text to the agent's context via `additionalContext` and re-grounds the active workflow goal (status, phase, recorded next step) at the start of every user turn — not only for flagged/blocked states — and on `SessionStart`, which fires after context compaction and on resume. A structured `next_action` may explicitly declare a non-empty `command` with `enforcement: "before_tool_use"`; at `PreToolUse`, the canonical script then exits 2 for every unrelated call and includes the exact projected command in the denial reason. The exact projected command is allowed. This narrow bootstrap policy keeps workflow authority in the projected state instead of relying on the model voluntarily following prompt text; ordinary Flow-step projections remain advisory.
 
-**Degradation when host lacks trigger**: If the host has no `userPromptSubmit`-equivalent hook, workflow steering is silent. The agent receives no ambient phase reminders at turn start. This is a capability loss, not a blocking failure. Log the gap in the adapter's conformance declaration as `userPromptSubmit: no native equivalent — steering context injection unavailable`.
+**Degradation when host lacks trigger**: If the host has no `userPromptSubmit`-equivalent hook, workflow steering is silent and the agent receives no ambient phase reminders at turn start. If the host has no block-capable `preToolUse` equivalent, explicit projected-action enforcement degrades to the same advisory command guidance. These are capability losses, not reasons to invent a second lifecycle authority. Record each missing capability in the adapter's conformance declaration.
 
 **Codex live hook influence caveat**: Codex hook influence on live sessions is limited — the agent may not honor all injected context. The hook influence behavioral cases in `evals/fixtures/hook-influence/cases.json` document which behaviors are expected (`agent_must_do`) versus which may only be soft guidance. Adapters on similar runtimes should apply the same classification.
 
@@ -550,7 +550,7 @@ For structured `run()` responses (native import form), the return value is:
 | config-protection | Fail-closed (exit 2 on protected file) | Yes — hook runtime errors exit 0 | Yes (preToolUse) |
 | quality-gate | Fail-open (exit 0 always) | Yes | No |
 | stop-goal-fit | Engine default warn (fail-open); blocks in `FLOW_AGENTS_GOAL_FIT_MODE=block` (shipped L2 default) | Yes — hook runtime errors exit 0 | Yes (stop, block mode) |
-| workflow-steering | Fail-open (exit 0 always) | Yes | No |
+| workflow-steering | Advisory; exit 2 only for an explicit `before_tool_use` projected command | Yes — hook runtime and malformed-state errors exit 0 | Yes (preToolUse, explicit projection only) |
 | evidence-capture | Fail-open (exit 0 always) | Yes — capture errors never block or corrupt the log | No |
 
 **Telemetry**: Always fail-open. Hook runtime errors in telemetry scripts must never block agent work.

package/docs/workflow-usage-guide.md

@@ -591,6 +591,18 @@ Start a newly selected session with `flow-agents builder-run start --session-dir
 [`docs/spec/builder-flow-runtime.md`](spec/builder-flow-runtime.md) for the ownership,
 trust-binding, route-back, and artifact-root contract.
 
+If the same Builder slice is interrupted and its sidecar/current pointers may be
+stale, restore the projection from the existing canonical Flow run with:
+
+```bash
+flow-agents builder-run recover --session-dir .kontourai/flow-agents/<slug>
+```
+
+The session slug is the run identity; recovery accepts no caller-selected run or
+step. It validates the sole Work Item binding and updates only the sidecar/current
+projection, leaving the entire Flow run byte-identical. Recovery never attaches or
+evaluates `trust.bundle`; use `builder-run sync` for that separate operation.
+
 When a session resumes (after context compaction, an agent restart, or a cross-session
 handoff), the workflow-steering hook emits a `RESUME:` block on `SessionStart` that
 gives the resuming agent immediate situational awareness without blocking or auto-deciding.

package/evals/integration/test_builder_entry_enforcement.sh

@@ -68,7 +68,10 @@ if (state.status !== 'new' || state.phase !== 'pickup') process.exit(1);
 if (JSON.stringify(state.work_item_refs) !== JSON.stringify(['local:local-request'])) process.exit(1);
 if (workItem.id !== 'local-request' || workItem.title !== 'Local request') process.exit(1);
 if (workItem.source_provider?.kind !== 'local' || workItem.source_provider?.path !== 'work-item.json') process.exit(1);
-if (!state.next_action?.summary?.includes('builder-run start') || !state.next_action?.summary?.includes('`pull-work`')) process.exit(1);
+if (state.next_action?.command !== 'flow-agents builder-run start --session-dir .kontourai/flow-agents/local-request') process.exit(1);
+if (state.next_action?.enforcement !== 'before_tool_use') process.exit(1);
+if (JSON.stringify(state.next_action?.skills) !== JSON.stringify(['pull-work'])) process.exit(1);
+if (!state.next_action?.summary?.includes('`pull-work`')) process.exit(1);
 NODE
   then
     pass "providerless request creates a local Work Item and starts at pull-work"

package/evals/integration/test_bundle_install.sh

@@ -592,13 +592,14 @@ function hasWorkflowSteering(file, ...eventNames) {
 }
 for (const file of process.argv.slice(2)) {
   if (!hasWorkflowSteering(file, "UserPromptSubmit", "userPromptSubmit")) throw new Error(`missing prompt-submit workflow steering: ${file}`);
+  if (!hasWorkflowSteering(file, "PreToolUse", "preToolUse")) throw new Error(`missing pre-tool workflow entry enforcement: ${file}`);
 }
 console.log("ok");
 NODE
 then
-  _pass "installed bundles wire prompt-submit workflow steering across Claude Code, Codex, and Kiro"
+  _pass "installed bundles wire prompt-submit steering and pre-tool entry enforcement across Claude Code, Codex, and Kiro"
 else
-  _fail "installed bundles do not wire prompt-submit workflow steering consistently"
+  _fail "installed bundles do not wire workflow steering consistently"
 fi
 
 if [[ -f "$OPENCODE_DEST/.opencode/plugins/flow-agents.js" ]]   && node - "$OPENCODE_DEST/.opencode/plugins/flow-agents.js" <<'NODE'