@khoavu882/doflow 2.0.0-beta.3 → 2.0.0-beta.5

package/core/harnesses/shared/hooks/bridge/respond.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Native hook response renderers for the shared lifecycle bridge.
+case ${BASH_SOURCE[0]} in */*) _DOFLOW_RESPOND_DIR=${BASH_SOURCE[0]%/*} ;; *) _DOFLOW_RESPOND_DIR=. ;; esac
+. "$_DOFLOW_RESPOND_DIR/../policies/deny-json.sh"
+
+doflow_bridge_native_event_var() {
+  DF_NE=$2
+  case "$1:$2" in
+    kiro:preToolUse) DF_NE=PreToolUse ;;
+    kiro:agentSpawn) DF_NE=SessionStart ;;
+    kiro:stop) DF_NE=Stop ;;
+  esac
+}
+
+doflow_bridge_native_event() {
+  local harness="$1" event="$2"
+  case "$harness:$event" in
+    kiro:preToolUse) event=PreToolUse ;;
+    kiro:agentSpawn) event=SessionStart ;;
+    kiro:stop) event=Stop ;;
+  esac
+  printf '%s\n' "$event"
+}
+
+doflow_render_response() {
+  local harness="$1" event="$2" outcome="$3" reason="$4" status="$5" engine="${DOFLOW_KIRO_ENGINE:-2x}"
+  doflow_bridge_native_event_var "$harness" "$event"; event=$DF_NE
+  if [ "$outcome" = deny ]; then
+    case "$harness:$event" in
+      claude:PreToolUse|codex:PreToolUse) emit_pretooluse_deny_nested "$reason" || return $?; return 0 ;;
+      gemini:BeforeTool) emit_pretooluse_deny_flat "$reason"; return 0 ;;
+      kiro:PreToolUse) printf '%s' "$reason" >&2; return 2 ;;
+      antigravity:PreToolUse)
+        if command -v jq >/dev/null 2>&1; then jq -cn --arg reason "$reason" '{decision:"deny",reason:$reason}'
+        else printf '{"decision":"deny","reason":%s}\n' "$( _doflow_json_reason "$reason" )"; fi
+        return $? ;;
+      antigravity:Stop)
+        if command -v jq >/dev/null 2>&1; then jq -cn --arg reason "$reason" '{decision:"continue",reason:$reason}'
+        else printf '{"decision":"continue","reason":%s}\n' "$( _doflow_json_reason "$reason" )"; fi
+        return $? ;;
+      pi:tool_call)
+        if command -v jq >/dev/null 2>&1; then jq -cn --arg reason "$reason" '{block:true,reason:$reason}'
+        else printf '{"block":true,"reason":%s}\n' "$( _doflow_json_reason "$reason" )"; fi
+        return $? ;;
+      kiro:Stop|kiro:stop)
+        if [ "$engine" = v3 ]; then
+          if command -v jq >/dev/null 2>&1; then jq -cn --arg reason "$reason" '{decision:"block",reason:$reason}'
+          else printf '{"decision":"block","reason":%s}\n' "$( _doflow_json_reason "$reason" )"; fi
+          return $?
+        fi
+        printf '%s' "$reason" >&2; return 2 ;;
+      codex:Stop|codex:stop) printf '%s\n' '{}' >&1; printf '%s\n' "$reason" >&2; return 2 ;;
+      *) printf '%s\n' "$reason" >&2; return 2 ;;
+    esac
+  fi
+  case "$harness:$event" in
+    codex:Stop|codex:stop) printf '%s\n' '{}' ;;
+    antigravity:PreToolUse) printf '%s\n' '{"decision":"allow"}' ;;
+    kiro:PreToolUse|claude:Stop) if [ "$status" -ne 0 ]; then printf '%s' "$reason" >&2; fi ;;
+  esac
+  return "$status"
+}

package/core/harnesses/shared/hooks/policies/capture-failure.sh

@@ -6,7 +6,7 @@
 # example its pattern file is missing). It exists only to be sourced, in a subshell with all output
 # discarded, from inside a branch where the policy already fails open:
 #
-#   ( . "$(dirname "$0")/capture-failure.sh"; doflow_capture_failure pre-bash-guard patterns-missing ) >/dev/null 2>&1 || true
+#   ( . "<policy-dir>/capture-failure.sh"; doflow_capture_failure pre-bash-guard patterns-missing ) >/dev/null 2>&1 || true
 #
 # The subshell keeps anything this file does away from the policy, which runs with `set -uo pipefail`,
 # does not source lib.sh and would change exit codes under `set -e`. So this file:
@@ -15,6 +15,8 @@
 #   - reads no stdin and writes nothing to stdout or stderr;
 #   - never rotates the file (rotation is done by the Node writers only, DEC-019);
 #   - never blocks, never changes the policy's decision, and swallows every error.
+
+case ${BASH_SOURCE[0]} in */*) _DOFLOW_CAPTURE_FAILURE_DIR=${BASH_SOURCE[0]%/*} ;; *) _DOFLOW_CAPTURE_FAILURE_DIR=. ;; esac
 # The line holds only the policy name and the point name from DoFlow's own code, the working
 # directory, the harness name and the install version: never the tool call, its arguments or stdin.
 # It is a no-op when no failure home can be resolved (HOME unset, or XDG_CONFIG_HOME relative) and
@@ -54,7 +56,7 @@ doflow_capture_failure() {
   [[ "$harness" =~ ^[A-Za-z0-9._-]{1,40}$ ]] || harness="none"
 
   # script_version of the nearest install manifest: walking up from this file, then the global one.
-  here="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd -P)" || here=""
+  here="$(CDPATH= cd -P -- "$_DOFLOW_CAPTURE_FAILURE_DIR" 2>/dev/null && pwd -P)" || here=""
   dir="$here"
   while [ -n "$dir" ] && [ -z "$version" ]; do
     if [ -f "$dir/.doflow/.install-manifest.json" ]; then

package/core/harnesses/shared/hooks/policies/contract.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# contract.sh — shared decision and envelope contract for canonical policies.
+#
+# This file is sourced by policy scripts. It sets no shell options, installs no traps, reads no
+# stdin, and keeps decision recording independent of jq.
+
+doflow_decision_init() {
+  DF_POLICY="${1:-}"
+  DF_POLICY_VERSION="${2:-0}"
+  doflow_decide allow allow
+}
+
+doflow_decide() {
+  local LC_ALL=C
+  local outcome="${1:-allow}" code="${2:-invalid-code}" fd="${DOFLOW_DECISION_FD:-}"
+  case "$code" in
+    [a-z]*)
+      case "$code" in
+        *[!a-z0-9:._-]*) code=invalid-code ;;
+        *) [ "${#code}" -le 40 ] || code=invalid-code ;;
+      esac
+      ;;
+    *) code=invalid-code ;;
+  esac
+  case "$fd" in
+    3|4|5|6|7|8|9)
+      # A caller may set the descriptor name without passing an open fd. Keep
+      # that broken handoff silent and harmless, including under `set -e`.
+      { printf '\036{"v":1,"policy":"%s","policyVersion":%s,"outcome":"%s","code":"%s"}\n' \
+        "${DF_POLICY:-}" "${DF_POLICY_VERSION:-0}" "$outcome" "$code" >&"$fd"; } 2>/dev/null || :
+      ;;
+  esac
+}
+
+doflow_read_envelope() {
+  local assignments
+  if [ -z "${INPUT:-}" ]; then
+    DF_ENV_CLASS=missing
+    DF_ENV_CODE=envelope-missing
+    DF_ENV_HARNESS=
+    DF_ENV_EVENT=
+    DF_ENV_OP=
+    DF_ENV_TOOL=
+    DF_ENV_PATHS=
+    DF_ENV_COMMAND=
+    DF_ENV_PATCH=
+    DF_ENV_ROOT=
+    DF_ENV_TASK=
+    return 0
+  fi
+  assignments=$(printf '%s' "${INPUT:-}" | jq -sr '
+    (.[0]) as $root |
+    ($root | if type == "object" then . else {} end) as $object |
+    ($object.doflow_event // {}) as $event |
+    ($event | if type == "object" then . else {} end) as $fields |
+    def field($key): ($fields[$key] // "") | if type == "string" then . else "" end;
+    def shellvar($name; $value): ($name + "=" + ($value | @sh));
+    (if ($root | type) != "object" or (($event | type) != "object") then "missing"
+     elif ($event | has("version") | not) then "missing"
+     elif ($event.version | type) == "number" and $event.version == 1 then "v1"
+     else "unsupported" end) as $class |
+    [shellvar("DF_ENV_CLASS"; $class),
+     shellvar("DF_ENV_CODE"; (if $class == "missing" then "envelope-missing" else "" end)),
+     shellvar("DF_ENV_HARNESS"; field("harness")),
+     shellvar("DF_ENV_EVENT"; field("event")),
+     shellvar("DF_ENV_OP"; field("operation")),
+     shellvar("DF_ENV_TOOL"; field("tool")),
+     shellvar("DF_ENV_PATHS"; ([$fields.paths[]? | select(type == "string")] | join("\n"))),
+     shellvar("DF_ENV_COMMAND"; field("command")),
+     shellvar("DF_ENV_PATCH"; field("patch")),
+     shellvar("DF_ENV_ROOT"; field("projectRoot")),
+     shellvar("DF_ENV_TASK"; field("taskId"))][]
+  ' 2>/dev/null) || return 1
+  eval "$assignments"
+}

package/core/harnesses/shared/hooks/policies/deny-json.sh

@@ -8,22 +8,57 @@
 # the front door right there, before it ever reached the code below that emits
 # the deny JSON. Sourcing this file must never change the caller's shell options.
 #
-# Usage: source "$(dirname "$0")/../../shared/hooks/policies/deny-json.sh"
+# Usage: source "<policy-dir>/deny-json.sh"
+
+case ${BASH_SOURCE[0]} in */*) _DOFLOW_DENY_JSON_DIR=${BASH_SOURCE[0]%/*} ;; *) _DOFLOW_DENY_JSON_DIR=. ;; esac
+
+# Escape a string as a JSON string body without external tools. Work bytewise so
+# every control byte is handled the same way regardless of the caller's locale.
+doflow_json_escape() {
+  local LC_ALL=C input="${1-}" output="" char ordinal i
+  for ((i = 0; i < ${#input}; i++)); do
+    char="${input:i:1}"
+    case "$char" in
+      '\') output="$output\\\\" ;;
+      '"') output="$output\\\"" ;;
+      $'\n') output="$output\\n" ;;
+      $'\r') output="$output\\r" ;;
+      $'\t') output="$output\\t" ;;
+      *)
+        printf -v ordinal '%d' "'${char}"
+        if [ "$ordinal" -ge 32 ]; then output="$output$char"; fi
+        ;;
+    esac
+  done
+  printf '%s' "$output"
+}
+
+_doflow_json_reason() {
+  printf '"%s"' "$(doflow_json_escape "$1")"
+}
 
 # Claude/Codex shape: nested under hookSpecificOutput.permissionDecision.
 emit_pretooluse_deny_nested() {
   local reason="$1"
-  jq -n --arg reason "$reason" '{
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg reason "$reason" '{
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
       permissionDecision: "deny",
       permissionDecisionReason: $reason
     }
-  }'
+    }'
+  else
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$(_doflow_json_reason "$reason")"
+  fi
 }
 
 # Gemini shape: flat {decision, reason} (packages/core/src/hooks/types.ts).
 emit_pretooluse_deny_flat() {
   local reason="$1"
-  jq -n --arg reason "$reason" '{decision: "deny", reason: $reason}'
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg reason "$reason" '{decision: "deny", reason: $reason}'
+  else
+    printf '{"decision":"deny","reason":%s}\n' "$(_doflow_json_reason "$reason")"
+  fi
 }

package/core/harnesses/shared/hooks/policies/lib.sh

@@ -1,13 +1,15 @@
 #!/usr/bin/env bash
 # lib.sh — shared constants and helpers for the Canonical Policy Library
 #
-# Usage: source "$(dirname "$0")/lib.sh"
+# Usage: source "<policy-dir>/lib.sh"
 #
 # All hooks must:
 #   1. source this file at the top
 #   2. call require_jq immediately after
 #   3. capture stdin once: INPUT=$(cat)
 #   4. use: json_field "$INPUT" ".field_name"
+
+case ${BASH_SOURCE[0]} in */*) _DOFLOW_LIB_DIR=${BASH_SOURCE[0]%/*} ;; *) _DOFLOW_LIB_DIR=. ;; esac
 #
 # Deployment:
 #   This file is installed by the doflow CLI and overwritten on update — do
@@ -327,7 +329,7 @@ storage_upkeep_async() {
     # Background the fully redirected subshell; an inner `&` leaves this shell
     # holding the hook's captured stdout open until the dispatcher exits. The
     # storage verb takes its project from the working directory: run it at the root.
-    ( cd "$root" 2>/dev/null && nohup "$run" storage --action upkeep </dev/null >/dev/null 2>&1 ) >/dev/null 2>&1 &
+    ( cd "$root" 2>/dev/null && nohup "$run" storage --action upkeep </dev/null >/dev/null 2>&1 ) >/dev/null 2>&1 3>&- 5>&- &
     return 0
   done
   return 0

package/core/harnesses/shared/hooks/policies/mcp-tool-guard.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case $0 in */*) _DOFLOW_POLDIR=${0%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # mcp-tool-guard.sh — Canonical Policy Library: PreToolUse(mcp_*) hook
 #
 # Intercepts every MCP tool call and blocks matches against mcp-policy.conf, the
@@ -13,19 +14,9 @@
 # Canonical Policy Script Contract (design.md §4):
 #   env    DOFLOW_PROJECT_DIR, DOFLOW_AGENT (both optional; not required to
 #          evaluate this policy)
-#   stdin  a PreToolUse-shaped JSON payload; tool name is read from the union
-#          of field names harnesses use (tool_name/tool/toolName/name), since
-#          a native front door (Claude/Codex/Kiro) execs this script directly
-#          with no payload translation of its own.
-#   exit   0 = allow, non-zero = deny with the reason on stderr.
-#
-# Reconciliation note (022-normalize-hooks, Phase A): MCP tool-name
-# vocabularies differ per harness — Claude/Codex/Kiro use a double-underscore
-# "mcp__<server>__<tool>" convention, Gemini documents a single-underscore
-# "mcp_<server>_<tool>" convention. A single-underscore prefix check ("^mcp_")
-# matches both conventions (the double-underscore form is a superset match of
-# the single-underscore prefix), so this script uses that one generic check
-# instead of hardcoding either harness's exact convention.
+#   stdin  a native payload with envelope v1 under doflow_event; only the
+#          envelope's operation and tool fields are used.
+#   exit   exit 2 + doflow_decide deny = deny; other faults per IC-011.
 #
 # mcp-policy.conf's shape (TAB-separated regex<TAB>reason, '#'-comments,
 # blank lines skipped) is identical across every harness that ships one today
@@ -34,36 +25,56 @@
 
 set -uo pipefail
 
-command -v jq >/dev/null 2>&1 || exit 0          # no jq -> cannot evaluate -> allow
-
 INPUT=$(cat)
+if [ -f "$_DOFLOW_POLDIR/contract.sh" ]; then
+  . "$_DOFLOW_POLDIR/contract.sh"
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  doflow_read_envelope() { DF_ENV_CLASS=missing; DF_ENV_CODE=contract-missing; }
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure mcp-tool-guard contract-missing ) >/dev/null 2>&1 || true
+  if [[ "${DOFLOW_AGENT:-}" =~ ^[a-z]+$ ]]; then
+    printf '[mcp-tool-guard] DoFlow hooks out of step; run: doflow update -t %s\n' "$DOFLOW_AGENT" >&2
+  else
+    printf '[mcp-tool-guard] DoFlow hooks out of step; run: doflow update\n' >&2
+  fi
+  doflow_decide deny contract-missing
+  exit 2
+fi
+doflow_decision_init mcp-tool-guard 1
+command -v jq >/dev/null 2>&1 || {
+  doflow_decide error dependency-missing:jq
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure mcp-tool-guard dependency-missing:jq ) >/dev/null 2>&1 || true
+  exit 0
+}
+DF_ENV_CLASS=missing DF_ENV_CODE=envelope-missing
+doflow_read_envelope || true
 
 TOOL_NAME=""
-for field in '.tool_name' '.tool' '.toolName' '.name'; do
-  TOOL_NAME=$(printf '%s' "$INPUT" | jq -r "${field} // empty" 2>/dev/null)
-  [ -n "$TOOL_NAME" ] && break
-done
-
-# Fast exit for non-MCP tool events (also covers "tool name unresolved").
-# "mcp_" (single underscore) matches both Claude/Codex/Kiro's "mcp__" and
-# Gemini's "mcp_" naming conventions. Matched case-insensitively: the caller
-# (stream-hook-runner.js's MCP_TOOL_PATTERN) classifies case-insensitively
-# before ever routing here, so this check must not be stricter than the
-# classification that decided to invoke it (022-code-review finding).
-shopt -s nocasematch 2>/dev/null || true
-case "$TOOL_NAME" in
-  mcp_*) ;;
-  *) exit 0 ;;
-esac
-shopt -u nocasematch 2>/dev/null || true
+if [ "$DF_ENV_CLASS" = v1 ]; then
+  [ "$DF_ENV_OP" = mcp ] || exit 0
+  TOOL_NAME=$DF_ENV_TOOL
+elif [ "$DF_ENV_CLASS" = unsupported ]; then
+  doflow_decide unsupported envelope-version
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure mcp-tool-guard unsupported:envelope-version ) >/dev/null 2>&1 || true
+  exit 0
+else
+  if [ "${DF_ENV_CODE:-envelope-missing}" != contract-missing ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure mcp-tool-guard envelope-missing ) >/dev/null 2>&1 || true
+  fi
+  if [[ "${DOFLOW_AGENT:-}" =~ ^[a-z]+$ ]]; then printf '[mcp-tool-guard] DoFlow hooks out of step; run: doflow update -t %s\n' "$DOFLOW_AGENT" >&2; else printf '[mcp-tool-guard] DoFlow hooks out of step; run: doflow update\n' >&2; fi
+  doflow_decide deny "${DF_ENV_CODE:-envelope-missing}"
+  exit 2
+fi
 
-POLICY_FILE="$(dirname "$0")/mcp-policy.conf"
+POLICY_FILE="$_DOFLOW_POLDIR/mcp-policy.conf"
 
 # If policy file is missing, allow everything (fail open — don't block the agent).
 if [ ! -f "$POLICY_FILE" ]; then
   # The policy file ships with DoFlow, so a missing one means a broken install: record it on this
   # machine (feature 046, IC-018) and fail open exactly as before. Subshell, output discarded.
-  ( . "$(dirname "$0")/capture-failure.sh"; doflow_capture_failure mcp-tool-guard policy-file-missing ) >/dev/null 2>&1 || true
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure mcp-tool-guard policy-file-missing ) >/dev/null 2>&1 || true
+  doflow_decide error mcp-policy-missing
   exit 0
 fi
 
@@ -83,6 +94,7 @@ while IFS=$'\t' read -r pattern reason || [ -n "$pattern" ]; do
 
   if [ "$matched" = "true" ]; then
     echo "[mcp-tool-guard] ${reason:-MCP tool call blocked by mcp-tool-guard} (tool: $TOOL_NAME)" >&2
+    doflow_decide deny blocked-pattern
     exit 2
   fi
 done < "$POLICY_FILE"

package/core/harnesses/shared/hooks/policies/pre-bash-guard.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case $0 in */*) _DOFLOW_POLDIR=${0%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # pre-bash-guard.sh — Canonical Policy Library: PreToolUse(shell-command) hook
 #
 # Intercepts every shell-command tool call and blocks dangerous commands by
@@ -10,14 +11,9 @@
 # Canonical Policy Script Contract (design.md §4):
 #   env    DOFLOW_PROJECT_DIR, DOFLOW_AGENT (both optional; not required to
 #          evaluate this policy)
-#   stdin  a PreToolUse-shaped JSON payload; tool name is read from the union
-#          of field names harnesses use, and matched against the union of
-#          known shell-command tool names (Bash/bash — Claude/Codex;
-#          run_shell_command — Gemini; run_command — the generic name
-#          stream-hook-runner.js's own COMMAND_TOOL_PATTERN already
-#          recognized), since a native front door (Claude/Codex/Kiro) execs
-#          this script directly with no payload translation of its own.
-#   exit   0 = allow, non-zero = deny with the reason on stderr.
+#   stdin  a native payload with envelope v1 under doflow_event; only the
+#          envelope's operation, tool and command fields are used.
+#   exit   exit 2 + doflow_decide deny = deny; other faults per IC-011.
 #
 # Reconciliation note (022-normalize-hooks, Phase A / D1): this also absorbs
 # stream-hook-runner.js's inline DESTRUCTIVE_COMMAND_PATTERN
@@ -38,29 +34,54 @@
 
 set -uo pipefail
 
-command -v jq >/dev/null 2>&1 || exit 0          # no jq -> cannot evaluate -> allow
-
 INPUT=$(cat)
+if [ -f "$_DOFLOW_POLDIR/contract.sh" ]; then
+  . "$_DOFLOW_POLDIR/contract.sh"
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  doflow_read_envelope() { DF_ENV_CLASS=missing; DF_ENV_CODE=contract-missing; }
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-bash-guard contract-missing ) >/dev/null 2>&1 || true
+  if [[ "${DOFLOW_AGENT:-}" =~ ^[a-z]+$ ]]; then
+    printf '[pre-bash-guard] DoFlow hooks out of step; run: doflow update -t %s\n' "$DOFLOW_AGENT" >&2
+  else
+    printf '[pre-bash-guard] DoFlow hooks out of step; run: doflow update\n' >&2
+  fi
+  doflow_decide deny contract-missing
+  exit 2
+fi
+doflow_decision_init pre-bash-guard 1
+command -v jq >/dev/null 2>&1 || {
+  doflow_decide error dependency-missing:jq
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-bash-guard dependency-missing:jq ) >/dev/null 2>&1 || true
+  exit 0
+}
+DF_ENV_CLASS=missing DF_ENV_CODE=envelope-missing
+doflow_read_envelope || true
 
 TOOL_NAME=""
-for field in '.tool_name' '.tool' '.toolName' '.name'; do
-  TOOL_NAME=$(printf '%s' "$INPUT" | jq -r "${field} // empty" 2>/dev/null)
-  [ -n "$TOOL_NAME" ] && break
-done
-
-# Fast exit for non-shell-command tool events (union of every known
-# shell-command tool name across harnesses, case-insensitive).
-case "$TOOL_NAME" in
-  Bash|bash|run_shell_command|run_command) ;;
-  *) exit 0 ;;
-esac
-
-COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+COMMAND=""
+if [ "$DF_ENV_CLASS" = v1 ]; then
+  [ "$DF_ENV_OP" = command ] || exit 0
+  TOOL_NAME=$DF_ENV_TOOL
+  COMMAND=$DF_ENV_COMMAND
+elif [ "$DF_ENV_CLASS" = unsupported ]; then
+  doflow_decide unsupported envelope-version
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-bash-guard unsupported:envelope-version ) >/dev/null 2>&1 || true
+  exit 0
+else
+  if [ "${DF_ENV_CODE:-envelope-missing}" != contract-missing ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-bash-guard envelope-missing ) >/dev/null 2>&1 || true
+  fi
+  if [[ "${DOFLOW_AGENT:-}" =~ ^[a-z]+$ ]]; then printf '[pre-bash-guard] DoFlow hooks out of step; run: doflow update -t %s\n' "$DOFLOW_AGENT" >&2; else printf '[pre-bash-guard] DoFlow hooks out of step; run: doflow update\n' >&2; fi
+  doflow_decide deny "${DF_ENV_CODE:-envelope-missing}"
+  exit 2
+fi
 
 # Nothing to check if command is empty
 [ -z "$COMMAND" ] && exit 0
 
-PATTERNS_FILE="$(dirname "$0")/blocked-patterns.conf"
+PATTERNS_FILE="$_DOFLOW_POLDIR/blocked-patterns.conf"
 
 # ASCII-only patterns: the C locale keeps bash's substring/pattern operations
 # byte-wise (much faster than multibyte-aware in a UTF-8 locale).
@@ -268,17 +289,21 @@ if [ ! -f "$PATTERNS_FILE" ]; then
   # The pattern file ships with DoFlow, so a missing one means a broken install: record it on this
   # machine (feature 046, IC-018) and go on exactly as before. Subshell, output discarded: nothing
   # the helper does can reach this policy's options, variables, output or exit status.
-  ( . "$(dirname "$0")/capture-failure.sh"; doflow_capture_failure pre-bash-guard patterns-missing ) >/dev/null 2>&1 || true
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-bash-guard patterns-missing ) >/dev/null 2>&1 || true
+  doflow_decide error patterns-missing
   if _floor_rm_hits '/+\*{0,2}'; then
     echo "[pre-bash-guard] Catastrophic delete blocked — recursive rm of the root directory (/)" >&2
+    doflow_decide deny catastrophic-rm-root
     exit 2
   fi
   if _floor_rm_hits '(~[A-Za-z_][A-Za-z0-9_.-]*|~|\$HOME|\$\{HOME\})(/\*{0,2})?'; then
     echo "[pre-bash-guard] Catastrophic delete blocked — recursive rm of the home directory" >&2
+    doflow_decide deny catastrophic-rm-home
     exit 2
   fi
   if _floor_rm_hits '/(Users|home|etc|usr|bin|sbin|var|opt|System|Library|Applications|Volumes|private|root|boot|lib|dev|proc)(/\*{0,2})?'; then
     echo "[pre-bash-guard] Catastrophic delete blocked — recursive rm of a system directory" >&2
+    doflow_decide deny catastrophic-rm-system
     exit 2
   fi
   # No patterns file beyond the hardcoded floor — allow everything else
@@ -286,6 +311,30 @@ if [ ! -f "$PATTERNS_FILE" ]; then
   exit 0
 fi
 
+# One combined ERE cheaply rules out commands that match no live pattern. A
+# grep match or regex error falls through to the original per-line loop, which
+# still owns the reason and optional exclude semantics.
+_anchored_patterns="" _full_patterns="" _has_backreference=false
+while IFS=$'\t' read -r pattern _reason _exclude || [ -n "$pattern" ]; do
+  [ -z "$pattern" ] && continue
+  case "$pattern" in \#*) continue ;; esac
+  if [[ "$pattern" =~ \\[1-9] ]]; then _has_backreference=true; fi
+  case "$pattern" in
+    '(^|'*) _anchored_patterns="${_anchored_patterns:+$_anchored_patterns|}($pattern)" ;;
+    *) _full_patterns="${_full_patterns:+$_full_patterns|}($pattern)" ;;
+  esac
+done < "$PATTERNS_FILE"
+_anchored_status=1 _full_status=1
+if [ -n "$_anchored_patterns" ]; then
+  grep -qiE -- "$_anchored_patterns" <<<"$SHELL_TEXT" 2>/dev/null
+  _anchored_status=$?
+fi
+if [ -n "$_full_patterns" ]; then
+  grep -qiE -- "$_full_patterns" <<<"$COMMAND" 2>/dev/null
+  _full_status=$?
+fi
+if [ "$_anchored_status" -eq 1 ] && [ "$_full_status" -eq 1 ] && [ "$_has_backreference" != true ]; then exit 0; fi
+
 # ── Pattern matching ──────────────────────────────────────────────────────────
 
 while IFS=$'\t' read -r pattern reason exclude || [ -n "$pattern" ]; do
@@ -320,6 +369,7 @@ while IFS=$'\t' read -r pattern reason exclude || [ -n "$pattern" ]; do
 
   if [ "$matched" = "true" ]; then
     echo "[pre-bash-guard] ${reason:-Command blocked by pre-bash-guard}" >&2
+    doflow_decide deny blocked-pattern
     exit 2
   fi
 done < "$PATTERNS_FILE"