@kontourai/flow-agents 3.4.2 → 3.4.3

package/evals/integration/test_dual_emit_flow_step.sh

@@ -34,7 +34,7 @@ cleanup() { rm -rf "$TMP"; }
 trap cleanup EXIT
 
 WRITER="workflow-sidecar"
-SESSION_ROOT="$TMP/.flow-agents"
+SESSION_ROOT="$TMP/.kontourai/flow-agents"
 
 echo "── P-a resolver unit checks ──"
 
@@ -269,11 +269,25 @@ fi
 
 DUAL_DIR="$SESSION_ROOT/dual-emit-test"
 
-flow_agents_node "$WRITER" advance-state "$DUAL_DIR" \
-  --status in_progress --phase verification \
-  --summary "Testing declared-only verify claims." --next-action "Record evidence." \
-  --flow-definition builder.build \
-  --timestamp "2026-06-26T00:00:30Z" >/dev/null 2>&1
+advance_builder_to_verify() {
+  local session_dir="$1"
+  flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation selected-work \
+    --summary "Selected the fixture Work Item." --timestamp "2026-06-26T00:00:10Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation pickup-probe-readiness \
+      --summary "Pickup readiness is established." --timestamp "2026-06-26T00:00:20Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation probe-decisions-or-accepted-gaps \
+      --summary "Probe decisions are recorded." --timestamp "2026-06-26T00:00:30Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation implementation-plan \
+      --summary "Implementation plan is recorded." --timestamp "2026-06-26T00:00:40Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation implementation-scope \
+      --summary "Implementation scope is recorded." --timestamp "2026-06-26T00:00:50Z" >/dev/null 2>&1
+}
+
+if advance_builder_to_verify "$DUAL_DIR"; then
+  _pass "canonical Builder Flow advances through required gates to verify"
+else
+  _fail "canonical Builder Flow did not reach verify"
+fi
 
 # Verify current.json carries the flow keys
 if node -e "
@@ -328,8 +342,26 @@ fi
 echo ""
 echo "── P-d declared-only: policy-kind check maps to builder.verify.policy-compliance ──"
 
-# Record a policy check with the same flow context
-if flow_agents_node "$WRITER" record-evidence "$DUAL_DIR" \
+# Use a separate canonical run because the failing tests evidence above legitimately
+# routes its run back to execute before this independent producer assertion.
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$SESSION_ROOT" \
+  --task-slug dual-emit-policy \
+  --flow-id builder.build \
+  --title "Declared Policy Test" \
+  --summary "Test declared-only policy emit for ADR 0016 P-d." \
+  --criterion "Policy passes" \
+  --timestamp "2026-06-26T00:01:30Z" >/dev/null 2>&1 \
+  && advance_builder_to_verify "$SESSION_ROOT/dual-emit-policy"; then
+  _pass "policy fixture canonical Builder Flow reaches verify"
+else
+  _fail "policy fixture canonical Builder Flow did not reach verify"
+fi
+
+POLICY_DIR="$SESSION_ROOT/dual-emit-policy"
+POLICY_BUNDLE="$POLICY_DIR/trust.bundle"
+
+if flow_agents_node "$WRITER" record-evidence "$POLICY_DIR" \
   --verdict pass \
   --check-json '{"id":"policy-check","kind":"policy","status":"pass","summary":"Policy compliance passed"}' \
   --timestamp "2026-06-26T00:02:00Z" >"$TMP/policy-evidence.out" 2>"$TMP/policy-evidence.err"; then
@@ -340,7 +372,7 @@ fi
 
 if node -e "
 const fs = require('fs');
-const bundle = JSON.parse(fs.readFileSync('${BUNDLE}', 'utf8'));
+const bundle = JSON.parse(fs.readFileSync('${POLICY_BUNDLE}', 'utf8'));
 const claims = bundle.claims;
 // Declared claim for policy kind should be builder.verify.policy-compliance
 const policyDeclared = claims.find(c => c.claimType === 'builder.verify.policy-compliance');

package/evals/integration/test_flowdef_session_activation.sh

@@ -43,29 +43,35 @@ WRITER="workflow-sidecar"
 echo ""
 echo "=== 1. ensure-session --flow-id builder.build activates FlowDefinition-driven path ==="
 
-MAIN_AROOT="$TMP/main-aroot"
+MAIN_AROOT="$TMP/main-project/.kontourai/flow-agents"
 SLUG="activation-test"
 SESSION_DIR="$MAIN_AROOT/$SLUG"
 mkdir -p "$MAIN_AROOT"
 
-flow_agents_node "$WRITER" ensure-session \
+if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$MAIN_AROOT" \
   --task-slug "$SLUG" \
   --title "Step 1 activation test" \
   --summary "Test that --flow-id builder.build activates the FlowDefinition-driven path." \
   --criterion "All gates produce declared claims" \
   --flow-id builder.build \
-  --timestamp "2026-06-01T00:00:00Z" >/dev/null 2>&1
+  --timestamp "2026-06-01T00:00:00Z" >/dev/null 2>&1; then
+  _pass "ensure-session starts the canonical Builder Flow from a canonical artifact root"
+else
+  _fail "ensure-session failed to start the canonical Builder Flow"
+fi
 
 node -e "
 const fs = require('fs');
 const c = JSON.parse(fs.readFileSync('$MAIN_AROOT/current.json', 'utf8'));
+const flow = JSON.parse(fs.readFileSync('$TMP/main-project/.kontourai/flow/runs/$SLUG/state.json', 'utf8'));
 if (c.active_flow_id !== 'builder.build') throw new Error('expected active_flow_id=builder.build, got ' + c.active_flow_id);
 if (!c.active_step_id) throw new Error('expected active_step_id to be set (first step default), got ' + c.active_step_id);
+if (flow.status !== 'active' || flow.current_step !== 'pull-work') throw new Error('canonical Flow did not start at pull-work: ' + JSON.stringify(flow));
 console.log('current.json: active_flow_id=' + c.active_flow_id + ' active_step_id=' + c.active_step_id);
 " 2>&1 \
-  && _pass "ensure-session --flow-id builder.build writes active_flow_id + default active_step_id to current.json" \
-  || _fail "ensure-session --flow-id builder.build did NOT write active_flow_id to current.json"
+  && _pass "ensure-session writes current projection and a canonical Flow run at pull-work" \
+  || _fail "ensure-session did not create and project the canonical Flow run"
 
 # ─── TEST 2: advance-state sets active_step_id via phase_map ─────────────────
 echo ""

package/evals/integration/test_install_merge.sh

@@ -47,6 +47,30 @@ else
 fi
 echo ""
 
+# The 3.4.2 bootstrap hook is intentionally absent from new bundles, but its
+# marker remains an ownership tombstone so upgrades remove the retired denial.
+if node - "$ROOT_DIR/scripts/install-merge.js" <<'NODE'
+const { mergeSettings, isManagedHookGroup } = require(process.argv[2]);
+const retired = { hooks: [{ type: "command", command: "old-flow-agents-entry", statusMessage: "Enforcing Flow Agents projected action" }] };
+const user = { hooks: [{ type: "command", command: "user-pretool" }] };
+const current = { hooks: [{ type: "command", command: "new-flow-agents", statusMessage: "Running Flow Agents hook policy" }] };
+if (!isManagedHookGroup(retired)) throw new Error("retired hook marker is no longer recognized as managed");
+const merged = mergeSettings(
+  { hooks: { PreToolUse: [retired, user] } },
+  { hooks: { UserPromptSubmit: [current] } },
+);
+const text = JSON.stringify(merged);
+if (text.includes("old-flow-agents-entry")) throw new Error("retired bootstrap hook survived upgrade");
+if (!text.includes("user-pretool")) throw new Error("user-owned PreToolUse hook was removed");
+if (!text.includes("new-flow-agents")) throw new Error("current managed hook was not installed");
+NODE
+then
+  _pass "upgrade removes the retired 3.4.2 bootstrap hook while preserving user hooks"
+else
+  _fail "upgrade did not cleanly replace the retired 3.4.2 bootstrap hook"
+fi
+echo ""
+
 # ─── Scenario 1: Seeded user config ──────────────────────────────────────────
 echo "--- Scenario 1: Seeded user config (user keys + non-FA hook survive) ---"
 

package/evals/integration/test_phase_map_and_gate_claim.sh

@@ -8,7 +8,8 @@
 #   4. record-gate-claim at pull-work step produces builder.pull-work.selected claim (status=verified).
 #   5. A TAMPERED bundle (stored verified, evidence fail) at pull-work step BLOCKS (exit 2)
 #      with the tamper warning naming the declared claimType.
-#   6. A CLEAN record-gate-claim bundle (passing evidence → verified) is NOT blocked.
+#   6. A CLEAN record-gate-claim bundle is not reported as false completion;
+#      its still-active canonical Flow run remains blocked from stopping.
 #
 # Deterministic, no model spend, self-cleaning.
 # Usage: bash evals/integration/test_phase_map_and_gate_claim.sh
@@ -119,7 +120,7 @@ test_advance_state "learning"     "learn"
 echo ""
 echo "=== 3. ensure-session --flow-id builder.build defaults to pull-work ==="
 
-ENSURE_ROOT="$TMP/ensure-test"
+ENSURE_ROOT="$TMP/ensure-project/.kontourai/flow-agents"
 mkdir -p "$ENSURE_ROOT"
 
 flow_agents_node "workflow-sidecar" ensure-session \
@@ -144,7 +145,7 @@ node -e "
 echo ""
 echo "=== 4. record-gate-claim produces builder.pull-work.selected claim ==="
 
-CLAIM_ROOT="$TMP/gate-claim-test"
+CLAIM_ROOT="$TMP/gate-claim-project/.kontourai/flow-agents"
 mkdir -p "$CLAIM_ROOT"
 
 flow_agents_node "workflow-sidecar" ensure-session \
@@ -192,7 +193,7 @@ node -e "
 echo ""
 echo "=== 4b. composed publish-learn gate claim emits builder.pr-open.pull-request ==="
 
-COMPOSED_ROOT="$TMP/composed-gate-claim-test"
+COMPOSED_ROOT="$TMP/composed-gate-claim-project/.kontourai/flow-agents"
 mkdir -p "$COMPOSED_ROOT"
 
 flow_agents_node "workflow-sidecar" ensure-session \
@@ -200,7 +201,6 @@ flow_agents_node "workflow-sidecar" ensure-session \
   --task-slug composed-gate-claim \
   --title "Composed Gate Claim Test" \
   --summary "Test composed Builder publish/learn flow producer." \
-  --flow-id builder.build \
   --timestamp "2026-06-26T00:00:00Z" >/dev/null 2>&1
 
 flow_agents_node "workflow-sidecar" init-plan "$COMPOSED_ROOT/composed-gate-claim/composed-gate-claim--deliver.md" \
@@ -350,9 +350,9 @@ else
   _fail "tamper warning does not name claimType: $tamper_out"
 fi
 
-# ─── Clean gate-claim: passing evidence → NOT blocked ────────────────────────
+# ─── Clean gate-claim: no false completion, active Flow still blocks ─────────
 echo ""
-echo "=== 6. CLEAN record-gate-claim (passing evidence → verified) → NOT BLOCKED ==="
+echo "=== 6. CLEAN record-gate-claim remains governed by active canonical Flow ==="
 
 C_DIR="$TMP/clean-test"
 mkdir -p "$C_DIR"
@@ -400,10 +400,10 @@ clean_out="$(FLOW_AGENTS_GOAL_FIT_MODE=block FLOW_AGENTS_GOAL_FIT_BACKSTOP=skip
 clean_exit="$?"
 set -e
 
-if [ "$clean_exit" -ne 2 ]; then
-  _pass "clean builder.pull-work.selected bundle not blocked (exit $clean_exit)"
+if [ "$clean_exit" -eq 2 ] && echo "$clean_out" | grep -q 'release skipped for active Flow run "clean"'; then
+  _pass "clean claim advances to the next Flow step and active run blocks premature Stop"
 else
-  _fail "clean builder.pull-work.selected bundle false-blocked (exit 2): $clean_out"
+  _fail "clean active Flow run returned the wrong Stop decision (exit $clean_exit): $clean_out"
 fi
 
 if echo "$clean_out" | grep -q "caught false-completion"; then

package/evals/integration/test_resolvefirststep_security.sh

@@ -185,7 +185,7 @@ fi
 echo ""
 echo "=== 4. Legit --flow-id builder.build → active_step_id set (first step resolved) ==="
 
-LEGIT_AROOT="$TMP/legit-aroot"
+LEGIT_AROOT="$TMP/legit-project/.kontourai/flow-agents"
 mkdir -p "$LEGIT_AROOT"
 
 set +e

package/evals/integration/test_sidecar_field_preservation.sh

@@ -85,13 +85,15 @@ _assert_preserved() {
   [[ "$ok" -eq 1 ]] && _pass "persistent identity fields (${FIELDS[*]}) survive $label"
 }
 
-# ─── Seed: ensure-session with an injected actor (derived branch) and a KNOWN timestamp ──────
+# ─── Seed: standalone sidecar session with an injected actor and a KNOWN timestamp ──────────
+# This sweep tests sidecar writer preservation. Canonical Flow startup and transitions are
+# covered separately; advance-state below activates Builder FlowDefinition claim typing without
+# creating a run that would legitimately project over this fixture's synthetic phase sequence.
 SEED_TS="2026-06-20T08:00:00Z"
 if ! flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$SESSION_ROOT" \
   --task-slug "$SLUG" \
   --actor sweep-actor \
-  --flow-id builder.build \
   --title "Sidecar Field Preservation Sweep" \
   --source-request "Seed a fully-populated session for the field-preservation invariant sweep." \
   --summary "Seed session for the class-level field-preservation sweep." \

package/evals/integration/test_takeover_protocol.sh

@@ -40,7 +40,7 @@ WRITER="workflow-sidecar"
 
 TMPDIR_EVAL="$(mktemp -d)"
 trap 'rm -rf "$TMPDIR_EVAL"' EXIT
-ARTIFACT_ROOT="$TMPDIR_EVAL/artifact-root"
+ARTIFACT_ROOT="$TMPDIR_EVAL/project/.kontourai/flow-agents"
 
 errors=0
 pass() { echo "  [PASS] $1"; }

package/evals/integration/test_workflow_sidecar_writer.sh

@@ -3437,7 +3437,7 @@ fi
 # ─── #270/#298 compose layer: gate-claim accumulation, gate-claim typing survives rebuild, ──
 # compose-two/three/four-writer round-trip, waiver + artifact_refs/standard_refs round-trip,
 # runnability rejection at record time (AC1-AC6, AC8, AC10) ──────────────────────────────────
-COMPOSE_ROOT="$TMPDIR_EVAL/compose-root"
+COMPOSE_ROOT="$TMPDIR_EVAL/compose-project/.kontourai/flow-agents"
 COMPOSE_SLUG="compose-270"
 COMPOSE_DIR="$COMPOSE_ROOT/$COMPOSE_SLUG"
 mkdir -p "$COMPOSE_ROOT"
@@ -3446,13 +3446,24 @@ flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$COMPOSE_ROOT" \
   --task-slug "$COMPOSE_SLUG" \
   --actor compose-actor \
-  --flow-id builder.build \
   --title "Compose layer session" \
   --source-request "Compose-safe writer layer smoke session." \
   --summary "Seed session for compose-layer round-trip assertions." \
   --criterion "Compose layer round-trips losslessly" \
   --timestamp "2026-07-05T09:00:00Z" >"$TMPDIR_EVAL/compose-seed.out" 2>"$TMPDIR_EVAL/compose-seed.err"
 
+# This fixture exercises sidecar writer composition, not canonical run
+# transitions. Activate FlowDefinition claim typing through the standalone
+# transition primitive so preliminary generic evidence cannot advance Flow.
+flow_agents_node "$WRITER" advance-state "$COMPOSE_DIR" \
+  --actor compose-actor \
+  --status in_progress \
+  --phase pickup \
+  --summary "Compose writer fixture at pull-work." \
+  --next-action "Record composed claims." \
+  --flow-definition builder.build \
+  --timestamp "2026-07-05T09:00:30Z" >"$TMPDIR_EVAL/compose-activate.out" 2>"$TMPDIR_EVAL/compose-activate.err"
+
 _compose_claims_json() {
   cat "$COMPOSE_DIR/trust.bundle"
 }
@@ -4157,7 +4168,7 @@ fi
 # misclassified as an unstamped pre-cluster-270 gate claim on the NEXT rebuild — is now rejected
 # AT RECORD TIME instead, in a FRESH session (isolated from COMPOSE_DIR) so no rebuild landmine
 # is ever created.
-COLLISION_ROOT="$TMPDIR_EVAL/collision-root"
+COLLISION_ROOT="$TMPDIR_EVAL/collision-project/.kontourai/flow-agents"
 COLLISION_SLUG="collision-270"
 COLLISION_DIR="$COLLISION_ROOT/$COLLISION_SLUG"
 mkdir -p "$COLLISION_ROOT"
@@ -4207,7 +4218,7 @@ fi
 # (real flow, real record-gate-claim), then break resolution by pointing active_flow_id at a
 # bogus flow id that cannot resolve under kits/ (mirrors the re-reviewer's approach of pointing
 # at an unresolvable kits/ path), in an ISOLATED fixture copied from a fresh session.
-UNRESOLVABLE_ROOT="$TMPDIR_EVAL/unresolvable-root"
+UNRESOLVABLE_ROOT="$TMPDIR_EVAL/unresolvable-project/.kontourai/flow-agents"
 UNRESOLVABLE_SLUG="unresolvable-270"
 UNRESOLVABLE_DIR="$UNRESOLVABLE_ROOT/$UNRESOLVABLE_SLUG"
 mkdir -p "$UNRESOLVABLE_ROOT"
@@ -4327,7 +4338,7 @@ fi
 # label, exactly the real kontourai-flow-agents-270 wedge this closes) can NEVER be corrected:
 # every attempt to re-record that exact id — the only way to supersede/fix it — is itself
 # rejected by the guard, permanently wedging that id and blocking publish-preflight forever.
-CORRECTION_ROOT="$TMPDIR_EVAL/correction-root"
+CORRECTION_ROOT="$TMPDIR_EVAL/correction-project/.kontourai/flow-agents"
 CORRECTION_SLUG="correction-270"
 CORRECTION_DIR="$CORRECTION_ROOT/$CORRECTION_SLUG"
 mkdir -p "$CORRECTION_ROOT"
@@ -4479,7 +4490,7 @@ fi
 # check_kind so the replacement claim can be shaped to evade gateClaimShapeUnstampedId's detector
 # (which requires check_kind==="external"). This eval reproduces that exact attack end-to-end
 # against the CURRENT (narrowed) binary and asserts it now dies, with the stamp intact afterward.
-STAMPED_ROOT="$TMPDIR_EVAL/stamped-claim-root"
+STAMPED_ROOT="$TMPDIR_EVAL/stamped-claim-project/.kontourai/flow-agents"
 STAMPED_SLUG="stamped-claim-270"
 STAMPED_DIR="$STAMPED_ROOT/$STAMPED_SLUG"
 mkdir -p "$STAMPED_ROOT"

package/evals/integration/test_workflow_steering_hook.sh

@@ -21,78 +21,6 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.4.2",
+  "version": "3.4.3",
   "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

@@ -124,6 +124,7 @@
           "minLength": 1
         },
         "enforcement": {
+          "description": "Deprecated compatibility field. Runtime steering ignores this value; session orchestration owns Builder Flow startup.",
           "type": "string",
           "enum": [
             "advisory",

package/scripts/hooks/workflow-steering.js

@@ -9,8 +9,7 @@
  * survive context loss instead of relying on the model voluntarily re-reading
  * the sidecar.
  *
- * Advisory by default. A structured next action may explicitly require its
- * projected command before unrelated tool use; only that PreToolUse case blocks.
+ * Non-blocking — always exits 0.
  */
 
 'use strict';
@@ -283,32 +282,6 @@ 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 '';
@@ -599,8 +572,6 @@ 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;
 
@@ -677,14 +648,7 @@ if (require.main === module) {
     data += chunk;
   });
   process.stdin.on('end', () => {
-    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));
-    }
+    process.stdout.write(String(run(data)));
   });
 }
 
@@ -703,6 +667,4 @@ module.exports = {
   promptText,
   looksLikeImplementationWork,
   kitWorkflowSteering,
-  beforeToolUseEnforcement,
-  toolCommands,
 };

package/scripts/install-merge.js

@@ -48,6 +48,8 @@ const FA_MARKERS = [
   "Recording Flow Agents telemetry",
   "Running Flow Agents hook policy",
   "Capturing Flow Agents command evidence",
+  // Cleanup tombstone: 3.4.2 installed this retired PreToolUse hook. Keep the
+  // marker recognizable so upgrades remove it even though new bundles do not.
   "Enforcing Flow Agents projected action",
 ];
 

package/src/builder-flow-runtime.ts

@@ -83,16 +83,20 @@ export async function startBuilderFlowSession(input: BuilderFlowSessionInput): P
       },
     });
   }
-  return syncAndProject(context, run);
+  assertRunSubjectBinding(run, subject);
+  return syncAndProject(context, run, sidecarSnapshot);
 }
 
 export async function syncBuilderFlowSession(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,
   });
-  return syncAndProject(context, run);
+  assertRunSubjectBinding(run, subject);
+  return syncAndProject(context, run, sidecarSnapshot);
 }
 
 export async function recoverBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult> {
@@ -103,14 +107,7 @@ export async function recoverBuilderFlowSession(input: BuilderFlowSessionInput):
     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");
-  }
+  assertRunSubjectBinding(run, subject);
   const projection = projectFlowRun(context, run, sidecarSnapshot.state);
   writeProjection(context, projection, sidecarSnapshot.raw, "recovery");
   return {
@@ -134,7 +131,11 @@ export async function syncBuilderFlowSessionIfPresent(sessionDir: string): Promi
   return syncBuilderFlowSession({ sessionDir });
 }
 
-async function syncAndProject(context: SessionContext, initial: BuilderBuildRunResult): Promise<BuilderFlowSessionResult> {
+async function syncAndProject(
+  context: SessionContext,
+  initial: BuilderBuildRunResult,
+  sidecarSnapshot: SidecarSnapshot,
+): Promise<BuilderFlowSessionResult> {
   let run = initial;
   let attached = false;
   const gates = openGatesForResult(run);
@@ -164,7 +165,6 @@ async function syncAndProject(context: SessionContext, initial: BuilderBuildRunR
       }
     }
   }
-  const sidecarSnapshot = readSidecarSnapshot(context);
   const projection = projectFlowRun(context, run, sidecarSnapshot.state);
   writeProjection(context, projection, sidecarSnapshot.raw, "projection");
   return {
@@ -176,6 +176,17 @@ async function syncAndProject(context: SessionContext, initial: BuilderBuildRunR
   };
 }
 
+function assertRunSubjectBinding(run: BuilderBuildRunResult, subject: string): void {
+  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");
+  }
+}
+
 function resolveSessionContext(sessionDirInput: string): SessionContext {
   const sessionDir = path.resolve(sessionDirInput);
   const artifactRoot = path.dirname(sessionDir);

package/src/cli/builder-flow-runtime.test.mjs

@@ -172,6 +172,38 @@ test("small-model client can start and advance from projected actions without ch
   assert.equal(duplicate.run.manifest.evidence.length, advanced.run.manifest.evidence.length);
 });
 
+test("automatic start refuses a slug-bound run for another Work Item without mutation", async () => {
+  const session = makeSession("start-subject-mismatch");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const sidecar = readJson(path.join(session.sessionDir, "state.json"));
+  sidecar.work_item_refs = ["local:work-item/other"];
+  writeJson(path.join(session.sessionDir, "state.json"), sidecar);
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+  const beforeProjection = snapshotProjectionTargets(session);
+
+  await assert.rejects(
+    () => startBuilderFlowSession({ sessionDir: session.sessionDir }),
+    /flow_run\.state\.subject.*selected Work Item/,
+  );
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+});
+
+test("automatic start refuses a sidecar changed after its immutable subject snapshot", async () => {
+  const session = makeSession("start-sidecar-race");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+  const startup = startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const changed = readJson(path.join(session.sessionDir, "state.json"));
+  changed.next_action = { status: "continue", summary: "concurrent change" };
+  writeJson(path.join(session.sessionDir, "state.json"), changed);
+  const beforeProjection = snapshotProjectionTargets(session);
+
+  await assert.rejects(() => startup, /state\.json.*changed during projection/);
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+});
+
 test("wrong workflow subject is rejected before canonical Flow mutation", async () => {
   const session = makeSession("wrong-subject");
   await startBuilderFlowSession({ sessionDir: session.sessionDir });