@kontourai/flow-agents 3.4.2 → 3.5.0

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

@@ -363,7 +363,6 @@ 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"\'' },
@@ -381,7 +380,6 @@ 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/contracts/assignment-provider-contract.md

@@ -138,8 +138,10 @@ detect an incompatible future shape before parsing fields it does not understand
 {
   "schema_version": "1.0",
   "role": "AssignmentClaimRecord",
-  "subject_id": "kontourai/flow-agents#290",
+  "subject_id": "kontourai-flow-agents-290",
   "actor": { "runtime": "claude-code", "session_id": "...", "host": "...", "human": null },
+  "actor_key": "claude-code:...:host",
+  "work_item_ref": "kontourai/flow-agents#290",
   "claimed_at": "2026-07-02T00:00:00Z",
   "ttl_seconds": 1800,
   "branch": "agent/<actor>/<slug>",
@@ -152,9 +154,10 @@ detect an incompatible future shape before parsing fields it does not understand
 | --- | --- | --- |
 | `schema_version` | yes | Version of this record shape, `"1.0"`. |
 | `role` | yes | Constant `"AssignmentClaimRecord"`, for readers scanning mixed content (e.g. a GitHub comment thread) for this record type. |
-| `subject_id` | yes | The claimed work item, in `owner/repo#id` form — the same string `workItemSlug` derives the deterministic session slug from. |
+| `subject_id` | yes | The provider subject key. The local-file provider uses the deterministic session slug; provider-backed records may use their native subject identifier. |
 | `actor` | yes | `{ runtime, session_id, host, human? }` — the exact struct `actor-identity.js` defines. `human` is set (non-null) only for a human assignee; its presence, not a username heuristic, gates the human-held join state. |
 | `actor_key` | no (additive, #291) | The canonical `resolveActor(env).actor` string for the claiming actor — the same flat/bare token `liveness whoami`, `liveness claim --actor`, per-actor `current.json`, and pull-work's `--self-actor` all use. When present, `computeEffectiveState` compares against THIS (not a re-serialization of `actor`) for both self-recognition and the liveness join, because `serializeActor(actor)` and `resolveActor(env).actor` diverge for an explicit-override actor (a bare token vs. a `explicit-override:<value>:<host>` triple) while agreeing for a derived actor. Absent on any pre-#291 record or fixture — `computeEffectiveState` falls back to `serializeActor(actor)` in that case, reproducing pre-#291 behavior exactly. |
+| `work_item_ref` | no (additive, #541) | Exact Work Item reference acquired by Builder `ensure-session`. This preserves identity beyond the local provider's lossy filesystem slug and allows an interrupted acquisition to retry safely. Older records and ordinary assignment-provider claims omit it and cannot automatically satisfy `builder.pull-work.selected`. |
 | `claimed_at` | yes | ISO-8601 timestamp the claim was recorded. Mirrors the liveness stream's own claim-event field so a reader compares freshness with one mental model across both layers, even though the two are stored in different media. |
 | `ttl_seconds` | yes | Same field name/semantics as the liveness stream's `ttlSeconds` (default `1800`). |
 | `branch` | yes | The branch this actor is working on, per the `agent/<actor>/<slug>` convention. |

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

@@ -28,18 +28,30 @@ expectations, and Builder Kit's structured action map.
 
 ## Entry And Synchronization
 
-A Builder session must first be created at the Flow Definition's entry step by the
-workflow sidecar. Start the canonical run with:
+A Builder session is created at the Flow Definition's entry step by the workflow
+sidecar. If automatic startup reports a failure, retry the canonical operation with:
 
 ```bash
 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.
+`ensure-session --flow-id builder.build` starts or loads this canonical run before
+returning. When the local assignment provider durably assigns the exact Work Item
+to the resolved workflow actor, `ensure-session` rereads that record and produces
+the declared `builder.pull-work.selected` claim through the normal Surface trust
+bundle path. Flow evaluates that subject-bound evidence and advances to
+`design-probe`; Flow Agents does not write a transition or gate outcome directly.
+Skipped ownership, unresolved actors, precomputed state, and non-local providers do
+not produce selection evidence and remain at `pull-work`.
+
+The command remains the explicit recovery path if Flow startup fails after sidecar
+creation; the failure is returned to the caller and no substitute run state is
+invented. Runtime hooks keep projected actions advisory while the agent performs
+their declared skills and operations.
+
+Sidecars written by 3.4.2 may still contain `next_action.enforcement`. The 1.0
+schema accepts that deprecated field for artifact compatibility, but current
+runtime steering ignores it and does not install a PreToolUse bootstrap hook.
 
 `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

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), and `preToolUse` when the projected `next_action` explicitly declares `enforcement: "before_tool_use"`
+**Canonical trigger event**: `userPromptSubmit` and `agentSpawn`/`SessionStart` (active-goal re-grounding), `postToolUse` (after `InvokeSubagents` tool calls)
 
 **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**: 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.
+**Decision contract**: Non-blocking. Always exits 0. Appends steering text to the agent's context via `additionalContext`. 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. Canonical Builder run creation is part of session orchestration rather than a model-mediated hook action.
 
-**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.
+**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.
 
 **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 | 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) |
+| workflow-steering | Fail-open (exit 0 always) | Yes | No |
 | 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/evals/integration/test_assignment_provider_local_file.sh

@@ -69,6 +69,60 @@ node "$CLI" assignment-provider status \
 [[ "$(json_query "$TMPDIR_EVAL/status-a.json" "assignment.assignee")" == "claude-code:eval-actor-a-session:eval-host" ]] && pass "status reports actor A as assignee" || fail "status reports actor A as assignee"
 [[ "$(json_query "$TMPDIR_EVAL/status-a.json" "assignment.record.claimed_at")" == "$CLAIMED_AT" ]] && pass "status claimed_at matches claim's claimed_at" || fail "status claimed_at matches claim's claimed_at"
 
+# A generic same-actor refresh must preserve exact Builder provenance that an interrupted
+# ensure-session recorded, even though the assignment-provider CLI does not accept that field.
+PROVENANCE_SUBJECT="builder-provenance"
+node "$CLI" assignment-provider claim \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --actor-json "$ACTOR_A" \
+  --branch "$BRANCH_A" \
+  --artifact-dir "$ARTIFACT_DIR_A" \
+  --ttl-seconds 1800 \
+  > "$TMPDIR_EVAL/provenance-claim.json"
+PROVENANCE_FILE="$(node - "$ARTIFACT_ROOT/assignment" "$PROVENANCE_SUBJECT" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const [dir, subject] = process.argv.slice(2);
+for (const name of fs.readdirSync(dir)) {
+  if (!name.endsWith('.json')) continue;
+  const file = path.join(dir, name);
+  if (JSON.parse(fs.readFileSync(file, 'utf8')).subject_id === subject) {
+    process.stdout.write(file);
+    process.exit(0);
+  }
+}
+process.exit(1);
+NODE
+)"
+node - "$PROVENANCE_FILE" <<'NODE'
+const fs = require('node:fs');
+const file = process.argv[2];
+const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+record.work_item_ref = 'kontourai/flow-agents#9001';
+fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+NODE
+node "$CLI" assignment-provider claim \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --actor-json "$ACTOR_A" \
+  --branch "$BRANCH_A" \
+  --artifact-dir "$ARTIFACT_DIR_A" \
+  --ttl-seconds 1800 \
+  > "$TMPDIR_EVAL/provenance-refresh.json"
+[[ "$(json_query "$TMPDIR_EVAL/provenance-refresh.json" "record.work_item_ref")" == "$SUBJECT_ID" ]] && pass "same-actor refresh preserves exact Work Item provenance" || fail "same-actor refresh preserves exact Work Item provenance"
+node "$CLI" assignment-provider supersede \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --from-actor-json "$ACTOR_A" --to-actor-json "$ACTOR_B" \
+  --reason "provenance handoff" >"$TMPDIR_EVAL/provenance-supersede.json"
+[[ "$(json_query "$TMPDIR_EVAL/provenance-supersede.json" "record.work_item_ref")" == "$SUBJECT_ID" ]] && pass "generic supersede preserves exact Work Item provenance" || fail "generic supersede preserves exact Work Item provenance"
+node "$CLI" assignment-provider release \
+  --provider local-file --artifact-root "$ARTIFACT_ROOT" \
+  --subject-id "$PROVENANCE_SUBJECT" \
+  --actor-json "$ACTOR_B" \
+  --reason "provenance fixture cleanup" >/dev/null
+
 # 3. supersede A -> B updates the actor and records an audit trail entry.
 node "$CLI" assignment-provider supersede \
   --provider local-file --artifact-root "$ARTIFACT_ROOT" --subject-id "$SUBJECT_ID" \