@kontourai/flow-agents 3.12.0 → 3.12.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [3.12.1](https://github.com/kontourai/flow-agents/compare/v3.12.0...v3.12.1) (2026-07-13)
+
+
+### Fixes
+
+* bind gate-action requirements to gates ([#608](https://github.com/kontourai/flow-agents/issues/608)) ([b1e9ad1](https://github.com/kontourai/flow-agents/commit/b1e9ad1a03ba1b88e09d6ace156e33c010bc6848))
+
 ## [3.12.0](https://github.com/kontourai/flow-agents/compare/v3.11.0...v3.12.0) (2026-07-13)
 
 

package/build/src/builder-gate-action-envelope.d.ts

@@ -35,7 +35,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "2.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +47,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;

package/build/src/builder-gate-action-envelope.js

@@ -70,7 +70,7 @@ function deriveFlowRequirements(input, action) {
         const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
             .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
         return expectationsForGate(gate, input.run.config)
-            .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
     });
     if (requirements.length > MAX_REQUIREMENTS)
         throw new Error("Builder gate-action envelope requirements exceed the supported bound");
@@ -91,7 +91,7 @@ function assembleGateActionEnvelope(input, loaded, derived) {
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
         .map((binding) => binding.artifact);
     const envelope = {
-        schema_version: "1.0",
+        schema_version: "2.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -215,7 +215,7 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         ],
     };
 }
-function requirementFromExpectation(expectation, satisfied, acceptedException) {
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
     const record = expectation;
     const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
     if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -223,6 +223,7 @@ function requirementFromExpectation(expectation, satisfied, acceptedException) {
     }
     return {
         id: record.id,
+        gate_id: gateId,
         required: record.required === true,
         description: record.description,
         claim_type: claim.claimType,

package/build/src/continuation-validation.js

@@ -18,12 +18,42 @@ export function validateSnapshot(value) {
     return structuredClone(value);
 }
 function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
+    if (value.gate !== undefined)
+        validateGateRequirementBindings(value);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
+function validateGateRequirementBindings(value) {
+    if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+    }
+    const activeGates = new Set(value.flow.gate_ids);
+    const acceptedGates = new Set();
+    for (const exception of value.gate.accepted_exceptions) {
+        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+            || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+        }
+        acceptedGates.add(exception.gate_id);
+    }
+    const gatesWithRequirements = new Set();
+    for (const requirement of value.gate.requirements) {
+        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+        }
+        gatesWithRequirements.add(requirement.gate_id);
+        if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+            && requirement.status !== "satisfied") {
+            throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+        }
+    }
+    if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+        throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+    }
+}
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
         throw new Error("continuation adapter must return status completed or wait");

package/dist/base/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "type": "module"
 }

package/dist/base/build/src/builder-gate-action-envelope.d.ts

@@ -35,7 +35,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "2.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +47,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;

package/dist/base/build/src/builder-gate-action-envelope.js

@@ -70,7 +70,7 @@ function deriveFlowRequirements(input, action) {
         const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
             .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
         return expectationsForGate(gate, input.run.config)
-            .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
     });
     if (requirements.length > MAX_REQUIREMENTS)
         throw new Error("Builder gate-action envelope requirements exceed the supported bound");
@@ -91,7 +91,7 @@ function assembleGateActionEnvelope(input, loaded, derived) {
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
         .map((binding) => binding.artifact);
     const envelope = {
-        schema_version: "1.0",
+        schema_version: "2.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -215,7 +215,7 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         ],
     };
 }
-function requirementFromExpectation(expectation, satisfied, acceptedException) {
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
     const record = expectation;
     const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
     if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -223,6 +223,7 @@ function requirementFromExpectation(expectation, satisfied, acceptedException) {
     }
     return {
         id: record.id,
+        gate_id: gateId,
         required: record.required === true,
         description: record.description,
         claim_type: claim.claimType,

package/dist/base/build/src/continuation-validation.js

@@ -18,12 +18,42 @@ export function validateSnapshot(value) {
     return structuredClone(value);
 }
 function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
+    if (value.gate !== undefined)
+        validateGateRequirementBindings(value);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
+function validateGateRequirementBindings(value) {
+    if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+    }
+    const activeGates = new Set(value.flow.gate_ids);
+    const acceptedGates = new Set();
+    for (const exception of value.gate.accepted_exceptions) {
+        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+            || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+        }
+        acceptedGates.add(exception.gate_id);
+    }
+    const gatesWithRequirements = new Set();
+    for (const requirement of value.gate.requirements) {
+        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+        }
+        gatesWithRequirements.add(requirement.gate_id);
+        if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+            && requirement.status !== "satisfied") {
+            throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+        }
+    }
+    if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+        throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+    }
+}
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
         throw new Error("continuation adapter must return status completed or wait");

package/dist/base/docs/migrations.md

@@ -6,6 +6,11 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
+  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  is no legacy envelope fallback; adapters that validate or project the public
+  envelope must require version 2.0 and the new binding.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/dist/base/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/AGENTS.md" && ! -L "$DEST/AGENTS.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.12.0" --install-record "$DEST/.flow-agents/install.json" --runtime "base" || true
+  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.12.1" --install-record "$DEST/.flow-agents/install.json" --runtime "base" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/claude-code/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "type": "module"
 }

package/dist/claude-code/build/src/builder-gate-action-envelope.d.ts

@@ -35,7 +35,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "2.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +47,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;

package/dist/claude-code/build/src/builder-gate-action-envelope.js

@@ -70,7 +70,7 @@ function deriveFlowRequirements(input, action) {
         const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
             .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
         return expectationsForGate(gate, input.run.config)
-            .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
     });
     if (requirements.length > MAX_REQUIREMENTS)
         throw new Error("Builder gate-action envelope requirements exceed the supported bound");
@@ -91,7 +91,7 @@ function assembleGateActionEnvelope(input, loaded, derived) {
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
         .map((binding) => binding.artifact);
     const envelope = {
-        schema_version: "1.0",
+        schema_version: "2.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -215,7 +215,7 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         ],
     };
 }
-function requirementFromExpectation(expectation, satisfied, acceptedException) {
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
     const record = expectation;
     const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
     if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -223,6 +223,7 @@ function requirementFromExpectation(expectation, satisfied, acceptedException) {
     }
     return {
         id: record.id,
+        gate_id: gateId,
         required: record.required === true,
         description: record.description,
         claim_type: claim.claimType,

package/dist/claude-code/build/src/continuation-validation.js

@@ -18,12 +18,42 @@ export function validateSnapshot(value) {
     return structuredClone(value);
 }
 function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
+    if (value.gate !== undefined)
+        validateGateRequirementBindings(value);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
+function validateGateRequirementBindings(value) {
+    if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+    }
+    const activeGates = new Set(value.flow.gate_ids);
+    const acceptedGates = new Set();
+    for (const exception of value.gate.accepted_exceptions) {
+        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+            || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+        }
+        acceptedGates.add(exception.gate_id);
+    }
+    const gatesWithRequirements = new Set();
+    for (const requirement of value.gate.requirements) {
+        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+        }
+        gatesWithRequirements.add(requirement.gate_id);
+        if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+            && requirement.status !== "satisfied") {
+            throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+        }
+    }
+    if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+        throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+    }
+}
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
         throw new Error("continuation adapter must return status completed or wait");

package/dist/claude-code/docs/migrations.md

@@ -6,6 +6,11 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
+  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  is no legacy envelope fallback; adapters that validate or project the public
+  envelope must require version 2.0 and the new binding.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/dist/claude-code/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/CLAUDE.md" && ! -L "$DEST/CLAUDE.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --config "$DEST/.claude/settings.json" --managed-hooks "$SRC/.claude/settings.json" --version "3.12.0" --install-record "$DEST/.flow-agents/install.json" --runtime "claude-code" || true
+  node "$DEST/scripts/install-merge.js" --config "$DEST/.claude/settings.json" --managed-hooks "$SRC/.claude/settings.json" --version "3.12.1" --install-record "$DEST/.flow-agents/install.json" --runtime "claude-code" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/codex/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "type": "module"
 }

package/dist/codex/build/src/builder-gate-action-envelope.d.ts

@@ -35,7 +35,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "2.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +47,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;

package/dist/codex/build/src/builder-gate-action-envelope.js

@@ -70,7 +70,7 @@ function deriveFlowRequirements(input, action) {
         const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
             .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
         return expectationsForGate(gate, input.run.config)
-            .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
     });
     if (requirements.length > MAX_REQUIREMENTS)
         throw new Error("Builder gate-action envelope requirements exceed the supported bound");
@@ -91,7 +91,7 @@ function assembleGateActionEnvelope(input, loaded, derived) {
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
         .map((binding) => binding.artifact);
     const envelope = {
-        schema_version: "1.0",
+        schema_version: "2.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -215,7 +215,7 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         ],
     };
 }
-function requirementFromExpectation(expectation, satisfied, acceptedException) {
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
     const record = expectation;
     const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
     if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -223,6 +223,7 @@ function requirementFromExpectation(expectation, satisfied, acceptedException) {
     }
     return {
         id: record.id,
+        gate_id: gateId,
         required: record.required === true,
         description: record.description,
         claim_type: claim.claimType,

package/dist/codex/build/src/continuation-validation.js

@@ -18,12 +18,42 @@ export function validateSnapshot(value) {
     return structuredClone(value);
 }
 function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
+    if (value.gate !== undefined)
+        validateGateRequirementBindings(value);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
+function validateGateRequirementBindings(value) {
+    if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+    }
+    const activeGates = new Set(value.flow.gate_ids);
+    const acceptedGates = new Set();
+    for (const exception of value.gate.accepted_exceptions) {
+        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+            || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+        }
+        acceptedGates.add(exception.gate_id);
+    }
+    const gatesWithRequirements = new Set();
+    for (const requirement of value.gate.requirements) {
+        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+        }
+        gatesWithRequirements.add(requirement.gate_id);
+        if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+            && requirement.status !== "satisfied") {
+            throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+        }
+    }
+    if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+        throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+    }
+}
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
         throw new Error("continuation adapter must return status completed or wait");

package/dist/codex/docs/migrations.md

@@ -6,6 +6,11 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
+  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  is no legacy envelope fallback; adapters that validate or project the public
+  envelope must require version 2.0 and the new binding.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/dist/codex/install.sh

@@ -60,7 +60,7 @@ SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 mkdir -p "$DEST"
 rsync -a --exclude='/AGENTS.md' --exclude='/CLAUDE.md' --exclude=".codex/hooks.json" "$SRC"/ "$DEST"/
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --config "$DEST/.codex/hooks.json" --managed-hooks "$SRC/.codex/hooks.json" --version "3.12.0" --install-record "$DEST/.flow-agents/install.json" --runtime "codex" || true
+  node "$DEST/scripts/install-merge.js" --config "$DEST/.codex/hooks.json" --managed-hooks "$SRC/.codex/hooks.json" --version "3.12.1" --install-record "$DEST/.flow-agents/install.json" --runtime "codex" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/kiro/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "type": "module"
 }

package/dist/kiro/build/src/builder-gate-action-envelope.d.ts

@@ -35,7 +35,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "2.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +47,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;

package/dist/kiro/build/src/builder-gate-action-envelope.js

@@ -70,7 +70,7 @@ function deriveFlowRequirements(input, action) {
         const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
             .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
         return expectationsForGate(gate, input.run.config)
-            .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
     });
     if (requirements.length > MAX_REQUIREMENTS)
         throw new Error("Builder gate-action envelope requirements exceed the supported bound");
@@ -91,7 +91,7 @@ function assembleGateActionEnvelope(input, loaded, derived) {
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
         .map((binding) => binding.artifact);
     const envelope = {
-        schema_version: "1.0",
+        schema_version: "2.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -215,7 +215,7 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         ],
     };
 }
-function requirementFromExpectation(expectation, satisfied, acceptedException) {
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
     const record = expectation;
     const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
     if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -223,6 +223,7 @@ function requirementFromExpectation(expectation, satisfied, acceptedException) {
     }
     return {
         id: record.id,
+        gate_id: gateId,
         required: record.required === true,
         description: record.description,
         claim_type: claim.claimType,

package/dist/kiro/build/src/continuation-validation.js

@@ -18,12 +18,42 @@ export function validateSnapshot(value) {
     return structuredClone(value);
 }
 function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
+    if (value.gate !== undefined)
+        validateGateRequirementBindings(value);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
+function validateGateRequirementBindings(value) {
+    if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+    }
+    const activeGates = new Set(value.flow.gate_ids);
+    const acceptedGates = new Set();
+    for (const exception of value.gate.accepted_exceptions) {
+        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+            || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+        }
+        acceptedGates.add(exception.gate_id);
+    }
+    const gatesWithRequirements = new Set();
+    for (const requirement of value.gate.requirements) {
+        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+        }
+        gatesWithRequirements.add(requirement.gate_id);
+        if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+            && requirement.status !== "satisfied") {
+            throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+        }
+    }
+    if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+        throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+    }
+}
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
         throw new Error("continuation adapter must return status completed or wait");

package/dist/kiro/docs/migrations.md

@@ -6,6 +6,11 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
+  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  is no legacy envelope fallback; adapters that validate or project the public
+  envelope must require version 2.0 and the new binding.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/dist/kiro/install.sh

@@ -73,7 +73,7 @@ fi
 export DEST
 find "$DEST" \( -path "$DEST/AGENTS.md" -o -path "$DEST/CLAUDE.md" \) -prune -o -type f \( -name '*.json' -o -name '*.md' -o -name '*.sh' -o -name '*.js' -o -name '*.ts' -o -name '*.yaml' -o -name '*.yml' \) -print0 | xargs -0 perl -0pi -e 's#__KIRO_PACKAGE_ROOT__#$ENV{DEST}#g'
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.12.0" --install-record "$DEST/.flow-agents/install.json" --runtime "kiro" || true
+  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.12.1" --install-record "$DEST/.flow-agents/install.json" --runtime "kiro" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/opencode/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "type": "module"
 }

package/dist/opencode/build/src/builder-gate-action-envelope.d.ts

@@ -35,7 +35,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "2.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +47,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;

package/dist/opencode/build/src/builder-gate-action-envelope.js

@@ -70,7 +70,7 @@ function deriveFlowRequirements(input, action) {
         const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
             .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
         return expectationsForGate(gate, input.run.config)
-            .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
     });
     if (requirements.length > MAX_REQUIREMENTS)
         throw new Error("Builder gate-action envelope requirements exceed the supported bound");
@@ -91,7 +91,7 @@ function assembleGateActionEnvelope(input, loaded, derived) {
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
         .map((binding) => binding.artifact);
     const envelope = {
-        schema_version: "1.0",
+        schema_version: "2.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -215,7 +215,7 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         ],
     };
 }
-function requirementFromExpectation(expectation, satisfied, acceptedException) {
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
     const record = expectation;
     const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
     if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -223,6 +223,7 @@ function requirementFromExpectation(expectation, satisfied, acceptedException) {
     }
     return {
         id: record.id,
+        gate_id: gateId,
         required: record.required === true,
         description: record.description,
         claim_type: claim.claimType,

package/dist/opencode/build/src/continuation-validation.js

@@ -18,12 +18,42 @@ export function validateSnapshot(value) {
     return structuredClone(value);
 }
 function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
+    if (value.gate !== undefined)
+        validateGateRequirementBindings(value);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
+function validateGateRequirementBindings(value) {
+    if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+    }
+    const activeGates = new Set(value.flow.gate_ids);
+    const acceptedGates = new Set();
+    for (const exception of value.gate.accepted_exceptions) {
+        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+            || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+        }
+        acceptedGates.add(exception.gate_id);
+    }
+    const gatesWithRequirements = new Set();
+    for (const requirement of value.gate.requirements) {
+        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+        }
+        gatesWithRequirements.add(requirement.gate_id);
+        if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+            && requirement.status !== "satisfied") {
+            throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+        }
+    }
+    if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+        throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+    }
+}
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
         throw new Error("continuation adapter must return status completed or wait");

package/dist/opencode/docs/migrations.md

@@ -6,6 +6,11 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
+  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  is no legacy envelope fallback; adapters that validate or project the public
+  envelope must require version 2.0 and the new binding.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/dist/opencode/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/AGENTS.md" && ! -L "$DEST/AGENTS.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --config "$DEST/opencode.json" --managed-hooks "$SRC/opencode.json" --version "3.12.0" --install-record "$DEST/.flow-agents/install.json" --runtime "opencode" || true
+  node "$DEST/scripts/install-merge.js" --config "$DEST/opencode.json" --managed-hooks "$SRC/opencode.json" --version "3.12.1" --install-record "$DEST/.flow-agents/install.json" --runtime "opencode" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/pi/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "type": "module"
 }

package/dist/pi/build/src/builder-gate-action-envelope.d.ts

@@ -35,7 +35,7 @@ export type GateActionPublicMutation = GateActionWorkflowMutation | {
     };
 };
 export type GateActionEnvelope = {
-    schema_version: "1.0";
+    schema_version: "2.0";
     flow: {
         run_id: string;
         definition_id: string;
@@ -47,6 +47,7 @@ export type GateActionEnvelope = {
     gate: {
         requirements: Array<{
             id: string;
+            gate_id: string;
             required: boolean;
             description: string;
             claim_type: string;

package/dist/pi/build/src/builder-gate-action-envelope.js

@@ -70,7 +70,7 @@ function deriveFlowRequirements(input, action) {
         const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
             .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
         return expectationsForGate(gate, input.run.config)
-            .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+            .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
     });
     if (requirements.length > MAX_REQUIREMENTS)
         throw new Error("Builder gate-action envelope requirements exceed the supported bound");
@@ -91,7 +91,7 @@ function assembleGateActionEnvelope(input, loaded, derived) {
         .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
         .map((binding) => binding.artifact);
     const envelope = {
-        schema_version: "1.0",
+        schema_version: "2.0",
         flow: {
             run_id: input.run.runId,
             definition_id: input.run.definitionId,
@@ -215,7 +215,7 @@ function workflowEvidenceMutation(expectationId, sessionArgument, packageVersion
         ],
     };
 }
-function requirementFromExpectation(expectation, satisfied, acceptedException) {
+function requirementFromExpectation(gateId, expectation, satisfied, acceptedException) {
     const record = expectation;
     const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
     if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -223,6 +223,7 @@ function requirementFromExpectation(expectation, satisfied, acceptedException) {
     }
     return {
         id: record.id,
+        gate_id: gateId,
         required: record.required === true,
         description: record.description,
         claim_type: claim.claimType,

package/dist/pi/build/src/continuation-validation.js

@@ -18,12 +18,42 @@ export function validateSnapshot(value) {
     return structuredClone(value);
 }
 function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
+    if (value.gate !== undefined)
+        validateGateRequirementBindings(value);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
+function validateGateRequirementBindings(value) {
+    if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+    }
+    const activeGates = new Set(value.flow.gate_ids);
+    const acceptedGates = new Set();
+    for (const exception of value.gate.accepted_exceptions) {
+        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+            || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+        }
+        acceptedGates.add(exception.gate_id);
+    }
+    const gatesWithRequirements = new Set();
+    for (const requirement of value.gate.requirements) {
+        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+            throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+        }
+        gatesWithRequirements.add(requirement.gate_id);
+        if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+            && requirement.status !== "satisfied") {
+            throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+        }
+    }
+    if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+        throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+    }
+}
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
         throw new Error("continuation adapter must return status completed or wait");

package/dist/pi/docs/migrations.md

@@ -6,6 +6,11 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
+  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  is no legacy envelope fallback; adapters that validate or project the public
+  envelope must require version 2.0 and the new binding.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/dist/pi/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/AGENTS.md" && ! -L "$DEST/AGENTS.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.12.0" --install-record "$DEST/.flow-agents/install.json" --runtime "pi" || true
+  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.12.1" --install-record "$DEST/.flow-agents/install.json" --runtime "pi" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/docs/migrations.md

@@ -6,6 +6,11 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
+  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  is no legacy envelope fallback; adapters that validate or project the public
+  envelope must require version 2.0 and the new binding.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "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/src/builder-gate-action-envelope.ts

@@ -53,7 +53,7 @@ export type GateActionPublicMutation =
     };
 
 export type GateActionEnvelope = {
-  schema_version: "1.0";
+  schema_version: "2.0";
   flow: {
     run_id: string;
     definition_id: string;
@@ -65,6 +65,7 @@ export type GateActionEnvelope = {
   gate: {
     requirements: Array<{
       id: string;
+      gate_id: string;
       required: boolean;
       description: string;
       claim_type: string;
@@ -222,7 +223,7 @@ function deriveFlowRequirements(input: BuilderGateActionEnvelopeInput, action: K
     const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
       .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
     return (expectationsForGate(gate, input.run.config) as FlowExpectation[])
-      .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+      .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
   });
   if (requirements.length > MAX_REQUIREMENTS) throw new Error("Builder gate-action envelope requirements exceed the supported bound");
   if (!sameSet(action.expectation_ids, requirements.map((requirement) => requirement.id))) {
@@ -243,7 +244,7 @@ function assembleGateActionEnvelope(input: BuilderGateActionEnvelopeInput, loade
     .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
     .map((binding) => binding.artifact);
   const envelope: GateActionEnvelope = {
-    schema_version: "1.0",
+    schema_version: "2.0",
     flow: {
       run_id: input.run.runId,
       definition_id: input.run.definitionId,
@@ -379,7 +380,7 @@ function workflowEvidenceMutation(expectationId: string, sessionArgument: string
   };
 }
 
-function requirementFromExpectation(expectation: FlowExpectation, satisfied: Set<string>, acceptedException: boolean): GateActionEnvelope["gate"]["requirements"][number] {
+function requirementFromExpectation(gateId: string, expectation: FlowExpectation, satisfied: Set<string>, acceptedException: boolean): GateActionEnvelope["gate"]["requirements"][number] {
   const record = expectation as unknown as AnyRecord;
   const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
   if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -387,6 +388,7 @@ function requirementFromExpectation(expectation: FlowExpectation, satisfied: Set
   }
   return {
     id: record.id,
+    gate_id: gateId,
     required: record.required === true,
     description: record.description,
     claim_type: claim.claimType,

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

@@ -372,7 +372,8 @@ test("small-model client can start and advance from projected actions without ch
   assert.ok(started.projection.next_action.command.includes(`'workflow' 'status' '--session-dir' '.kontourai/flow-agents/${session.slug}' '--json'`));
   const envelope = started.gateActionEnvelope;
   assert.equal(Object.hasOwn(started.projection.next_action, "gate_action_envelope"), false, "durable state has no duplicate envelope");
-  assert.equal(envelope.schema_version, "1.0");
+  assert.equal(envelope.schema_version, "2.0");
+  assert.equal(envelope.gate.requirements[0].gate_id, "pull-work-gate");
   assert.equal(envelope.action.implementation_allowed, false, "implementation is forbidden before builder.build/execute");
   assert.deepEqual(envelope.action.declared_evidence, ["selected-work"]);
   assert.deepEqual(envelope.action.declared_artifacts, [`<slug>--pull-work.md`, "trust.bundle#selected-work"]);
@@ -481,6 +482,7 @@ test("accepted Flow exceptions explicitly waive the current envelope requirement
   });
   const recovered = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
   assert.deepEqual(recovered.gateActionEnvelope.gate.accepted_exceptions, [{ gate_id: "pull-work-gate", exception_id: exception.id }]);
+  assert.equal(recovered.gateActionEnvelope.gate.requirements[0].gate_id, "pull-work-gate");
   assert.equal(recovered.gateActionEnvelope.gate.requirements[0].status, "accepted_exception");
   assert.deepEqual(recovered.gateActionEnvelope.stop_condition.required.unresolved_evidence_ids, []);
   assert.deepEqual(recovered.gateActionEnvelope.stop_condition.required.artifact_refs, []);
@@ -761,7 +763,7 @@ test("public workflow drive signs adapter evidence with a consumed one-time key"
   assert.deepEqual(payload.adapter_turns.map((turn) => turn.request), observedRequests);
   assert.equal(payload.adapter_turns[0].request.schema_version, "1.0");
   assert.equal(payload.adapter_turns[0].request.next_action.status, "continue");
-  assert.equal(payload.adapter_turns[0].request.gate_action_envelope.schema_version, "1.0");
+  assert.equal(payload.adapter_turns[0].request.gate_action_envelope.schema_version, "2.0");
   assert.deepEqual(payload.adapter_turns.map((turn) => turn.request), observedRequests, "the signed payload binds the unchanged envelope bytes observed by the adapter");
   assert.deepEqual(payload.adapter_turns[0].result.evidence.usage, { input_tokens: 10, output_tokens: 2 });
   const tampered = Buffer.from(JSON.stringify({ ...payload, max_turns: 2 }));

package/src/cli/continuation-driver.test.mjs

@@ -9,6 +9,7 @@ import { createHash, generateKeyPairSync, randomBytes, sign } from "node:crypto"
 
 import { MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES, MAX_CONTINUATION_TURN_RESULT_BYTES, ContinuationAdapterTimeoutError, createFileContinuationStore, runContinuationDriver, withContinuationDriverLock } from "../../build/src/continuation-driver.js";
 import { executeContinuationAdapter, executeLoadedContinuationAdapter, loadContinuationAdapterCommand, waitForContinuationBarrier } from "../../build/src/cli/continuation-adapter.js";
+import { validateSnapshot } from "../../build/src/continuation-validation.js";
 
 const require = createRequire(import.meta.url);
 const activeTurnAuthority = require("../../scripts/hooks/lib/continuation-turn-authority.js");
@@ -38,7 +39,7 @@ function snapshot(step, status = "active") {
 function envelopeSnapshot(step, { evidence = [], artifacts = [], implementationAllowed = false, status = "active" } = {}) {
   const value = snapshot(step, status);
   value.gate_action_envelope = {
-    schema_version: "1.0",
+    schema_version: "2.0",
     flow: { current_step: step, status },
     action: { implementation_allowed: implementationAllowed },
     stop_condition: { kind: "one_turn", adapter_evidence_is_gate_evidence: false },
@@ -47,6 +48,20 @@ function envelopeSnapshot(step, { evidence = [], artifacts = [], implementationA
   return value;
 }
 
+test("gate-action envelope rejects partial accepted-exception bindings", () => {
+  const partial = envelopeSnapshot("execute");
+  partial.gate_action_envelope.flow.gate_ids = ["execute-gate"];
+  partial.gate_action_envelope.gate = {
+    requirements: [
+      { id: "implemented", gate_id: "execute-gate", required: true, status: "accepted_exception" },
+      { id: "verified", gate_id: "execute-gate", required: true, status: "unresolved" },
+    ],
+    unresolved_requirement_ids: ["verified"],
+    accepted_exceptions: [{ gate_id: "execute-gate", exception_id: "exception-1" }],
+  };
+  assert.throws(() => validateSnapshot(partial), /inconsistent exception bindings/);
+});
+
 function terminalProgressSnapshot(status, { step = "learn", evidence = [], artifacts = [] } = {}) {
   const value = snapshot(step, status);
   value.progress_snapshot = {

package/src/continuation-validation.ts

@@ -16,11 +16,41 @@ export function validateSnapshot(value: ContinuationSnapshot): ContinuationSnaps
 }
 
 function validateGateActionEnvelope(value: GateActionEnvelope): void {
-  if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+  if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
     || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts)) throw new Error("continuation snapshot gate-action envelope is malformed");
+  if (value.gate !== undefined) validateGateRequirementBindings(value);
   if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536) throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
 
+function validateGateRequirementBindings(value: GateActionEnvelope): void {
+  if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
+    throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
+  }
+  const activeGates = new Set(value.flow.gate_ids);
+  const acceptedGates = new Set<string>();
+  for (const exception of value.gate.accepted_exceptions) {
+    if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+      || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
+      throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
+    }
+    acceptedGates.add(exception.gate_id);
+  }
+  const gatesWithRequirements = new Set<string>();
+  for (const requirement of value.gate.requirements) {
+    if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+      throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
+    }
+    gatesWithRequirements.add(requirement.gate_id);
+    if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
+      && requirement.status !== "satisfied") {
+      throw new Error("continuation snapshot gate-action envelope has inconsistent exception bindings");
+    }
+  }
+  if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
+    throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
+  }
+}
+
 export function validateTurnResult(value: ContinuationTurnResult): ContinuationTurnResult {
   if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait")) throw new Error("continuation adapter must return status completed or wait");
   if (value.status === "wait") validateBarrier(value.barrier);