@kontourai/flow-agents 3.4.0 → 3.4.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Fixes
+
+* resolve packaged Flow definitions in consumer repos ([#532](https://github.com/kontourai/flow-agents/issues/532)) ([3eb4a2e](https://github.com/kontourai/flow-agents/commit/3eb4a2e42d49a9c31b16ef62484cf5b0a001c7a1))
+
 ## [3.4.0](https://github.com/kontourai/flow-agents/compare/v3.3.0...v3.4.0) (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/lib/flow-resolver.d.ts

@@ -20,8 +20,8 @@
  *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a runtime artifact directory
  *  - The resolved path escapes the expected root (belt-and-suspenders)
  *
- * When the override is unsafe, it is ignored and the resolver uses the
- * canonical repoRoot/kits/ source for legitimate flows.
+ * An unsafe explicit override fails closed. Package fallback applies only to
+ * canonical lookup when no override was supplied.
  */
 export declare function resolveFlowFilePath(kitId: string, flowName: string, flowId: string, repoRoot: string, allowOverride?: boolean): string | null;
 /** A single gate expectation from a FlowDefinition expects[] entry. */

package/build/src/lib/flow-resolver.js

@@ -54,6 +54,35 @@ function isAgentWritableDir(resolvedDir) {
         return false;
     }
 }
+function installedPackageRoot() {
+    let directory = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (fs.existsSync(path.join(directory, "package.json")) && fs.existsSync(path.join(directory, "kits"))) {
+            return directory;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+function packagedFlowFile(kitId, flowName, consumerRoot) {
+    const packageRoot = installedPackageRoot();
+    if (!packageRoot || path.resolve(packageRoot) === path.resolve(consumerRoot))
+        return null;
+    const kitsRoot = path.resolve(packageRoot, "kits");
+    const candidate = path.resolve(kitsRoot, kitId, "flows", `${flowName}.flow.json`);
+    if (!candidate.startsWith(kitsRoot + path.sep))
+        return null;
+    try {
+        const realKitsRoot = fs.realpathSync.native(kitsRoot);
+        const realCandidate = fs.realpathSync.native(candidate);
+        return realCandidate.startsWith(realKitsRoot + path.sep) ? realCandidate : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Build and validate the FlowDefinition file path.
  *
@@ -62,8 +91,8 @@ function isAgentWritableDir(resolvedDir) {
  *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a runtime artifact directory
  *  - The resolved path escapes the expected root (belt-and-suspenders)
  *
- * When the override is unsafe, it is ignored and the resolver uses the
- * canonical repoRoot/kits/ source for legitimate flows.
+ * An unsafe explicit override fails closed. Package fallback applies only to
+ * canonical lookup when no override was supplied.
  */
 export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOverride = true) {
     // Primary defense: reject any slug containing traversal chars or non-identifier chars.
@@ -72,13 +101,11 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOver
     const override = allowOverride ? process.env["FLOW_AGENTS_FLOW_DEFS_DIR"] : undefined;
     let expectedRoot;
     let flowFilePath;
+    let canonicalLookup = false;
     if (override) {
         const resolvedOverride = path.resolve(override);
         if (isAgentWritableDir(resolvedOverride)) {
-            // Override targets an agent-writable runtime path; ignore it and use
-            // the canonical kit root. The session will resolve the real kit flow.
-            expectedRoot = path.resolve(repoRoot, "kits");
-            flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+            return null;
         }
         else {
             expectedRoot = resolvedOverride;
@@ -90,6 +117,7 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOver
     else {
         expectedRoot = path.resolve(repoRoot, "kits");
         flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+        canonicalLookup = true;
     }
     // Belt-and-suspenders: confirm the resolved path stays within the expected root.
     // After slug validation this is theoretically unreachable, but defense-in-depth
@@ -110,6 +138,11 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOver
         return realPath;
     }
     catch {
+        if (canonicalLookup) {
+            const packaged = packagedFlowFile(kitId, flowName, repoRoot);
+            if (packaged)
+                return packaged;
+        }
         return resolvedPath;
     }
 }

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