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

package/core/harnesses/shared/hooks/policies/pre-implementation-gate.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case $0 in */*) _DOFLOW_POLDIR=${0%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # pre-implementation-gate.sh — Canonical Policy Library: PreToolUse(Edit|Write|...)
 # backstop for the doflow implement gate. The HARD half of the one enforced
 # gate (the other half is the prompt-level do-prereqs.sh inside
@@ -21,7 +22,7 @@
 #   - edit target is under agent-docs/ -> allow (editing the artifacts themselves)
 #   - edit target outside the repo     -> allow
 # It reads files with jq and lists checkouts with one git call; it never runs
-# the DoFlow runtime. Self-contained + fail-open: any uncertainty -> allow (exit 0).
+# the DoFlow runtime. Missing or malformed v1 input is denied as out of step; other faults follow IC-011.
 #
 # Canonical Policy Script Contract (design.md §4):
 #   env    DOFLOW_PROJECT_DIR (repo root, if the front door sets it),
@@ -30,17 +31,9 @@
 #          (each already read by the harness-specific dispatcher this policy
 #          replaces — kept so an unmodified front door still resolves its own
 #          harness's do-paths.sh resolver)
-#   stdin  a PreToolUse-shaped JSON payload for an edit tool. Every harness's
-#          own field names differ (Claude/Gemini: tool_name/tool_input.file_path;
-#          Codex: tool_name=apply_patch with a unified diff in
-#          tool_input.command; Kiro: field names undocumented) — this script
-#          reads the union of known shapes rather than assuming one, 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. A front door
-#          translates this into whatever JSON/exit-code shape its harness
-#          natively expects — this script never speaks a harness-specific
-#          decision shape.
+#   stdin  a native payload encoded as envelope v1 by the lifecycle bridge.
+#   exit   exit 2 + doflow_decide deny = deny; other faults per IC-011. A front
+#          door translates this into its native response shape.
 #
 # Reconciliation note (022-normalize-hooks, Phase A): claude/gemini/codex/kiro
 # each shipped a separately-adapted copy of this gate; antigravity's copy
@@ -58,74 +51,71 @@
 
 set -uo pipefail
 
-command -v jq >/dev/null 2>&1 || exit 0          # no jq -> cannot evaluate -> allow
-
 INPUT=$(cat)
-
-# ── Normalized envelope (preferred; review R7) ────────────────────────────────
-# A host adapter that has already decoded its native event sends
-#   {"doflow_event": {"operation": "edit", "paths": [..], "projectRoot": "..", "taskId": ".."}}
-# and this policy consumes it verbatim. The union decoder below remains the
-# fallback for front doors that still forward raw native payloads; per-harness
-# knowledge belongs in those adapters, and each one that starts sending the
-# envelope retires its share of the union.
-ENVELOPE_ROOT=""
-ENVELOPE_TASK=""
-ENVELOPE_OP=$(printf '%s' "$INPUT" | jq -r '.doflow_event.operation // empty' 2>/dev/null)
-if [ -n "$ENVELOPE_OP" ]; then
-  [ "$ENVELOPE_OP" = "edit" ] || exit 0          # only edits are gated
-  FILES=$(printf '%s' "$INPUT" | jq -r '.doflow_event.paths[]? // empty' 2>/dev/null | sed '/^$/d' | sort -u)
-  [ -n "$FILES" ] || exit 0
-  ENVELOPE_ROOT=$(printf '%s' "$INPUT" | jq -r '.doflow_event.projectRoot // empty' 2>/dev/null)
-  ENVELOPE_TASK=$(printf '%s' "$INPUT" | jq -r '.doflow_event.taskId // empty' 2>/dev/null)
+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-implementation-gate contract-missing ) >/dev/null 2>&1 || true
+  if [[ "${DOFLOW_AGENT:-}" =~ ^[a-z]+$ ]]; then
+    printf '[pre-implementation-gate] DoFlow hooks out of step; run: doflow update -t %s\n' "$DOFLOW_AGENT" >&2
+  else
+    printf '[pre-implementation-gate] DoFlow hooks out of step; run: doflow update\n' >&2
+  fi
+  doflow_decide deny contract-missing
+  exit 2
+fi
+doflow_decision_init pre-implementation-gate 1
+command -v jq >/dev/null 2>&1 || {
+  doflow_decide error dependency-missing:jq
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-implementation-gate dependency-missing:jq ) >/dev/null 2>&1 || true
+  exit 0
+}
 
-# ── Tool name (union of every known field name across harnesses; LEGACY decoder) ──
-tool=""
-for field in '.tool_name' '.tool' '.toolName' '.name'; do
-  tool=$(printf '%s' "$INPUT" | jq -r "${field} // empty" 2>/dev/null)
-  [ -n "$tool" ] && break
-done
-
-is_patch_tool=false
-case "$tool" in
-  Edit|Write|MultiEdit|edit_file|write_file|create_file|replace_file|replace) ;;
-  write_to_file|replace_file_content|multi_replace_file_content) ;;
-  apply_patch) is_patch_tool=true ;;
-  *) exit 0 ;;
-esac
-
-# ── Candidate files to gate ────────────────────────────────────────────────────
-# Normal edit tools: one file, from the union of field names harnesses use.
-# apply_patch (Codex): the tool has no file_path field at all — the paths are
-# embedded in a unified diff under tool_input.command.
-FILES=""
-if [ "$is_patch_tool" = true ]; then
-  PATCH=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
-  [ -n "$PATCH" ] || exit 0
-  # "#" (not the original codex script's "|") is the sed delimiter here: BSD
-  # sed (macOS, no GNU coreutils) misparses "s|...(Add|Update|Delete)...|...|"
-  # because it splits on every unescaped "|", including the ones meant as ERE
-  # alternation inside the pattern — a portability bug in the source script
-  # this reconciliation fixes rather than ports, since it silently broke
-  # apply_patch parsing under this exact invocation on any non-GNU-sed host.
-  FILES=$(printf '%s\n' "$PATCH" | sed -nE \
+# Parse v1 apply_patch paths using the shared parser.
+parse_patch_paths() {
+  printf '%s\n' "$1" | sed -nE \
     -e 's#^\*\*\* (Add|Update|Delete) File: (.+)$#\2#p' \
     -e 's#^\+\+\+ (a/|b/)?(.+)$#\2#p' \
-    | sed '/^\/dev\/null$/d' | sort -u)
-  [ -n "$FILES" ] || exit 0
+    | sed '/^\/dev\/null$/d' | sort -u
+}
+
+DF_ENV_CLASS=missing DF_ENV_CODE=envelope-missing
+doflow_read_envelope || true
+
+# ── Envelope v1 ───────────────────────────────────────────────────────────────
+ENVELOPE_ROOT=""
+ENVELOPE_TASK=""
+if [ "$DF_ENV_CLASS" = v1 ]; then
+  ENVELOPE_OP=$DF_ENV_OP
+  [ "$ENVELOPE_OP" = "edit" ] || exit 0          # only edits are gated
+  FILES=$DF_ENV_PATHS
+  ENVELOPE_ROOT=$DF_ENV_ROOT
+  ENVELOPE_TASK=$DF_ENV_TASK
+  if [ -z "$FILES" ] && [ -z "$DF_ENV_PATCH" ]; then
+    doflow_decide unsupported edit-without-target
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-implementation-gate edit-without-target ) >/dev/null 2>&1 || true
+    exit 0
+  fi
+  if [ -z "$FILES" ] && [ -n "$DF_ENV_PATCH" ]; then
+    FILES=$(parse_patch_paths "$DF_ENV_PATCH")
+    [ -n "$FILES" ] || exit 0
+  fi
+elif [ "$DF_ENV_CLASS" = unsupported ]; then
+  doflow_decide unsupported envelope-version
+  ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-implementation-gate unsupported:envelope-version ) >/dev/null 2>&1 || true
+  exit 0
 else
-  file=""
-  for field in '.tool_input.file_path' '.tool_input.path' '.tool_input.target' '.file_path' '.path'; do
-    file=$(printf '%s' "$INPUT" | jq -r "${field} // empty" 2>/dev/null)
-    [ -n "$file" ] && break
-  done
-  [ -n "$file" ] || exit 0
-  FILES="$file"
+  if [ "${DF_ENV_CODE:-envelope-missing}" != contract-missing ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure pre-implementation-gate envelope-missing ) >/dev/null 2>&1 || true
+  fi
+  if [[ "${DOFLOW_AGENT:-}" =~ ^[a-z]+$ ]]; then printf '[pre-implementation-gate] DoFlow hooks out of step; run: doflow update -t %s\n' "$DOFLOW_AGENT" >&2; else printf '[pre-implementation-gate] DoFlow hooks out of step; run: doflow update\n' >&2; fi
+  doflow_decide deny "${DF_ENV_CODE:-envelope-missing}"
+  exit 2
 fi
 
-fi  # end legacy union decoder
-
 # ── Resolve repo root ───────────────────────────────────────────────────────
 # DOFLOW_PROJECT_DIR (explicit) beats the envelope's projectRoot beats git discovery.
 ROOT="${DOFLOW_PROJECT_DIR:-$ENVELOPE_ROOT}"
@@ -384,13 +374,14 @@ PLANNED=false
 # plan.md all exist. Classes that cannot be a feature skip this check.
 if [ "$exempt" = false ] && [ -n "$FEATURE_ROOT" ] && [ "$PLANNED" = false ]; then
   echo "[pre-implementation-gate] doflow gate: feature $feature_dir is missing requirement.md, design.md, or plan.md — run /do-brainstorm, /do-design, then /do-plan before editing source. (Edits under agent-docs/ are always allowed; skip the flow by removing the feature dir.)" >&2
+  doflow_decide deny missing-artifacts
   exit 2
 fi
 
 # ── Readiness ────────────────────────────────────────────────────────────────
 # The workflow registry the installed runtime reads: beside this policy in an
 # install, the source tree's own, the project's install, the global install.
-POLICY_DIR=$(cd -P "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd) || POLICY_DIR=""
+POLICY_DIR=$_DOFLOW_POLDIR
 REGISTRY=""
 for candidate in \
   "${POLICY_DIR:+$POLICY_DIR/../../../runtime/core/registry/workflows.json}" \
@@ -480,16 +471,19 @@ gate="doflow gate readiness-before-implementation: task '$task_id'"
 rest="Next: $next, then gather what it lists until it reports READY. Nothing was changed."
 if [ -z "$FOUND" ]; then
   printf "%s has no readiness record for the '%s' template. %s\n" "$gate" "$STAGE_TEMPLATE" "$rest" >&2
+  doflow_decide deny readiness-missing
   exit 2
 fi
 if [ "$record_state" != READY ]; then
   printf "%s was last evaluated %s at %s against the '%s' template, not READY. %s\n" \
     "$gate" "$record_state" "$record_at" "$STAGE_TEMPLATE" "$rest" >&2
+  doflow_decide deny readiness-not-ready
   exit 2
 fi
 if [ "$record_class" != "$STAGE_TEMPLATE" ]; then
   printf "%s has a READY record for the '%s' template, and this stage needs '%s'. %s\n" \
     "$gate" "$record_class" "$STAGE_TEMPLATE" "$rest" >&2
+  doflow_decide deny readiness-wrong-template
   exit 2
 fi
 

package/core/harnesses/shared/hooks/policies/session-context.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case $0 in */*) _DOFLOW_POLDIR=${0%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # session-context.sh — Canonical Policy Library: SessionStart guard policy
 #
 # Fires when a harness starts a new session. Captures git state into a
@@ -11,24 +12,53 @@
 # Canonical Policy Script Contract (design.md §4):
 #   env    DOFLOW_PROJECT_DIR, DOFLOW_AGENT (both optional here; DOFLOW_AGENT
 #          only affects the "last_agent" field recorded in meta.json)
-#   stdin  the harness's native SessionStart JSON payload — must expose at
-#          least ".session_id" and ".cwd"
+#   stdin  envelope v1 from the native SessionStart payload, including
+#          the session_id and cwd fields used by this policy.
 #   exit   this policy never denies — it always exits 0 (side-effect only)
 #
 # Depends on lib.sh (require_jq, json_field, ensure_session_dir,
 # ensure_project_dir, cwd_hash, run_with_timeout, $SESSIONS_LOG) being
 # discoverable next to this script when it runs — a front door invoking this
 # canonical script is responsible for making lib.sh resolvable via
-# "$(dirname "$0")/lib.sh", exactly as every harness's own SessionStart script
+# the sibling lib.sh, exactly as every harness's own SessionStart script
 # already required before this policy moved to a shared location.
 
 set -euo pipefail
 # shellcheck source=lib.sh
-source "$(dirname "$0")/lib.sh"
-require_jq
-
+source "$_DOFLOW_POLDIR/lib.sh"
 INPUT=$(cat)
-SESSION_ID=$(json_field "$INPUT" ".session_id")
+POLICY_DIR=$_DOFLOW_POLDIR
+if [ -f "$POLICY_DIR/contract.sh" ]; then
+  # shellcheck source=contract.sh
+  source "$POLICY_DIR/contract.sh"
+  doflow_decision_init session-context 1
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure session-context contract-missing ) >/dev/null 2>&1 || true
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  doflow_decide error dependency-missing:jq
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure session-context dependency-missing:jq ) >/dev/null 2>&1 || true
+fi
+require_jq
+SESSION_ID="" ENVELOPE_CLASS=missing
+{ IFS= read -r -d '' ENVELOPE_CLASS; IFS= read -r -d '' SESSION_ID; } < <(
+  printf '%s' "$INPUT" | jq -j 'if ((. | type) != "object") or ((.doflow_event | type) != "object") or ((.doflow_event | has("version")) | not) then "missing" elif ((.doflow_event.version | type) == "number") and .doflow_event.version == 1 then "v1" else "unsupported" end, "\u0000", (.session_id // "" | if type == "string" then rtrimstr("\n") else tojson end), "\u0000"' 2>/dev/null
+) || true
+ENVELOPE_CLASS=${ENVELOPE_CLASS:-missing}
+if [ ! -f "$POLICY_DIR/contract.sh" ]; then ENVELOPE_CLASS=missing; fi
+if [ "$ENVELOPE_CLASS" = unsupported ] || [ "$ENVELOPE_CLASS" = missing ]; then
+  code=envelope-version
+  [ "$ENVELOPE_CLASS" = missing ] && code=envelope-missing
+  [ -f "$POLICY_DIR/contract.sh" ] || code=contract-missing
+  doflow_decide unsupported "$code"
+  if [ -f "$POLICY_DIR/contract.sh" ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure session-context "$code" ) >/dev/null 2>&1 || true
+  fi
+  exit 0
+fi
 CWD=$(json_field "$INPUT" ".cwd")
 
 # Guard: if we can't determine the session, nothing to do

package/core/harnesses/shared/hooks/policies/stop-check.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case $0 in */*) _DOFLOW_POLDIR=${0%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # stop-check.sh — Canonical Policy Library: Stop hook
 #
 # Two responsibilities:
@@ -24,14 +25,8 @@
 #
 # Canonical Policy Script Contract (design.md §4):
 #   env    DOFLOW_PROJECT_DIR, DOFLOW_AGENT (both optional here)
-#   stdin  a Stop-shaped JSON payload. session_id and transcript path field
-#          names both vary by harness (transcript_path vs. Antigravity's
-#          camelCase transcriptPath) — this script reads the union of known
-#          field names rather than assuming one, since a native front door
-#          (Claude/Codex/Kiro) execs this script directly with no payload
-#          translation of its own.
-#   exit   0 = allow the stop, non-zero = deny (block the stop) with the
-#          reason on stderr.
+#   stdin  envelope v1 from a native front door via the shared lifecycle bridge.
+#   exit   exit 2 + doflow_decide deny = deny; other faults per IC-011.
 #
 # Depends on lib.sh (require_jq, json_field, ensure_session_dir,
 # run_with_timeout) being discoverable next to this script when it runs — see
@@ -48,11 +43,41 @@
 
 set -euo pipefail
 # shellcheck source=lib.sh
-source "$(dirname "$0")/lib.sh"
-require_jq
-
+source "$_DOFLOW_POLDIR/lib.sh"
 INPUT=$(cat)
-SESSION_ID=$(json_field "$INPUT" ".session_id")
+# Decision records stay off every stream unless a bridge supplied the fd.
+POLICY_DIR=$_DOFLOW_POLDIR
+if [ -f "$POLICY_DIR/contract.sh" ]; then
+  # shellcheck source=contract.sh
+  source "$POLICY_DIR/contract.sh"
+  doflow_decision_init stop-check 1
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure stop-check contract-missing ) >/dev/null 2>&1 || true
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  doflow_decide error dependency-missing:jq
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure stop-check dependency-missing:jq ) >/dev/null 2>&1 || true
+fi
+require_jq
+SESSION_ID="" ENVELOPE_CLASS=missing
+{ IFS= read -r -d '' ENVELOPE_CLASS; IFS= read -r -d '' SESSION_ID; } < <(
+  printf '%s' "$INPUT" | jq -j 'if ((. | type) != "object") or ((.doflow_event | type) != "object") or ((.doflow_event | has("version")) | not) then "missing" elif ((.doflow_event.version | type) == "number") and .doflow_event.version == 1 then "v1" else "unsupported" end, "\u0000", (.session_id // "" | if type == "string" then rtrimstr("\n") else tojson end), "\u0000"' 2>/dev/null
+) || true
+ENVELOPE_CLASS=${ENVELOPE_CLASS:-missing}
+if [ ! -f "$POLICY_DIR/contract.sh" ]; then ENVELOPE_CLASS=missing; fi
+if [ "$ENVELOPE_CLASS" = unsupported ] || [ "$ENVELOPE_CLASS" = missing ]; then
+  code=envelope-version
+  [ "$ENVELOPE_CLASS" = missing ] && code=envelope-missing
+  [ -f "$POLICY_DIR/contract.sh" ] || code=contract-missing
+  doflow_decide unsupported "$code"
+  if [ -f "$POLICY_DIR/contract.sh" ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure stop-check "$code" ) >/dev/null 2>&1 || true
+  fi
+  exit 0
+fi
 
 TRANSCRIPT_PATH=$(json_field "$INPUT" ".transcript_path")
 [ -z "$TRANSCRIPT_PATH" ] && TRANSCRIPT_PATH=$(json_field "$INPUT" ".transcriptPath")
@@ -107,7 +132,7 @@ if [ -n "$SESSION_ID" ]; then
     # before the {} reply is invalid hook output)
     if [ ${#py_files[@]} -gt 0 ]; then
       if command -v ruff &>/dev/null; then
-        nohup ruff format "${py_files[@]}" </dev/null >/dev/null 2>&1 &
+        nohup ruff format "${py_files[@]}" </dev/null >/dev/null 2>&1 3>&- 5>&- &
         run_with_timeout 2 -- ruff check "${py_files[@]}" >&2 || true
       fi
     fi
@@ -115,7 +140,7 @@ if [ -n "$SESSION_ID" ]; then
     # JS/TS: async fix only (eslint --fix rarely needs the caller's immediate attention)
     if [ ${#js_files[@]} -gt 0 ]; then
       if command -v eslint &>/dev/null; then
-        nohup eslint --fix "${js_files[@]}" </dev/null >/dev/null 2>&1 &
+        nohup eslint --fix "${js_files[@]}" </dev/null >/dev/null 2>&1 3>&- 5>&- &
       fi
     fi
 
@@ -129,7 +154,7 @@ if [ -n "$SESSION_ID" ]; then
     # Java: async spotlessApply (slow — only if gradlew exists in cwd)
     if [ "$java_has_files" = "true" ]; then
       if [ -x "./gradlew" ]; then
-        nohup ./gradlew spotlessApply </dev/null >/dev/null 2>&1 &
+        nohup ./gradlew spotlessApply </dev/null >/dev/null 2>&1 3>&- 5>&- &
       fi
     fi
 
@@ -143,6 +168,7 @@ if [ -n "$SESSION_ID" ]; then
       if [ -n "$DOFLOW_RUN" ]; then
         leak_out="$(run_with_timeout 2 -- "$DOFLOW_RUN" leak-scan "${leak_args[@]}" 2>/dev/null || true)"
         if [ -n "$leak_out" ] && printf '%s' "$leak_out" | grep -q ':[0-9]'; then
+          doflow_decide advisory internal-identifiers-found
           printf 'doflow: internal identifiers found in shipped files (warning, not a block):\n%s\n' \
             "$leak_out" >&2
         fi
@@ -258,6 +284,7 @@ if grep -qiE -- "$STUB_PATTERN" <<<"$STUB_TEXT" 2>/dev/null; then
   fi
   [ -n "$MESSAGE_SUM" ] && [ -n "$GUARD_FILE" ] && { printf '%s\n' "$MESSAGE_SUM" > "$GUARD_FILE"; } 2>/dev/null || true
   echo "[stop-check] The last response contains an unfinished-work marker (TODO/FIXME/stub comment or a not-implemented raise/throw)." >&2
+  doflow_decide deny unfinished-work
   exit 2
 fi
 

package/core/harnesses/shared/hooks/policies/subagent-audit.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case $0 in */*) _DOFLOW_POLDIR=${0%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # subagent-audit.sh — Canonical Policy Library: SubagentStart + SubagentStop hook
 # (pure observability, no deny path)
 #
@@ -18,11 +19,40 @@
 
 set -euo pipefail
 # shellcheck source=lib.sh
-source "$(dirname "$0")/lib.sh"
-require_jq
-
+source "$_DOFLOW_POLDIR/lib.sh"
 INPUT=$(cat)
-SESSION_ID=$(json_field "$INPUT" ".session_id")
+POLICY_DIR=$_DOFLOW_POLDIR
+if [ -f "$POLICY_DIR/contract.sh" ]; then
+  # shellcheck source=contract.sh
+  source "$POLICY_DIR/contract.sh"
+  doflow_decision_init subagent-audit 1
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure subagent-audit contract-missing ) >/dev/null 2>&1 || true
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  doflow_decide error dependency-missing:jq
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure subagent-audit dependency-missing:jq ) >/dev/null 2>&1 || true
+fi
+require_jq
+SESSION_ID="" ENVELOPE_CLASS=missing
+{ IFS= read -r -d '' ENVELOPE_CLASS; IFS= read -r -d '' SESSION_ID; } < <(
+  printf '%s' "$INPUT" | jq -j 'if ((. | type) != "object") or ((.doflow_event | type) != "object") or ((.doflow_event | has("version")) | not) then "missing" elif ((.doflow_event.version | type) == "number") and .doflow_event.version == 1 then "v1" else "unsupported" end, "\u0000", (.session_id // "" | if type == "string" then rtrimstr("\n") else tojson end), "\u0000"' 2>/dev/null
+) || true
+ENVELOPE_CLASS=${ENVELOPE_CLASS:-missing}
+if [ ! -f "$POLICY_DIR/contract.sh" ]; then ENVELOPE_CLASS=missing; fi
+if [ "$ENVELOPE_CLASS" = unsupported ] || [ "$ENVELOPE_CLASS" = missing ]; then
+  code=envelope-version
+  [ "$ENVELOPE_CLASS" = missing ] && code=envelope-missing
+  [ -f "$POLICY_DIR/contract.sh" ] || code=contract-missing
+  doflow_decide unsupported "$code"
+  if [ -f "$POLICY_DIR/contract.sh" ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure subagent-audit "$code" ) >/dev/null 2>&1 || true
+  fi
+  exit 0
+fi
 
 # Guard: if we can't determine the session, nothing to do
 [[ -z "$SESSION_ID" ]] && exit 0
@@ -41,6 +71,6 @@ jq -nc \
   --arg agent_type "$AGENT_TYPE" \
   --arg agent_id "$AGENT_ID" \
   '{timestamp: $ts, session_id: $session, event: $event, agent_type: $agent_type, agent_id: $agent_id}' \
-  >> "$SESSION_PATH/subagent-audit.log" 2>/dev/null || true
+  >> "$SESSION_PATH/subagent-audit.log" 2>/dev/null || doflow_decide error audit-write-failed
 
 exit 0

package/core/harnesses/shared/hooks/policies/user-prompt-submit.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case $0 in */*) _DOFLOW_POLDIR=${0%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # user-prompt-submit.sh — Canonical Policy Library: UserPromptSubmit hook
 #
 # 022-hooks-remaining-duplication: claude and codex's UserPromptSubmit policies share the same
@@ -26,22 +27,52 @@
 
 set -euo pipefail
 # shellcheck source=lib.sh
-source "$(dirname "$0")/lib.sh"
-require_jq
-
+source "$_DOFLOW_POLDIR/lib.sh"
 INPUT=$(cat)
+POLICY_DIR=$_DOFLOW_POLDIR
+if [ -f "$POLICY_DIR/contract.sh" ]; then
+  # shellcheck source=contract.sh
+  source "$POLICY_DIR/contract.sh"
+  doflow_decision_init user-prompt-submit 1
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure user-prompt-submit contract-missing ) >/dev/null 2>&1 || true
+  printf '{}'
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  doflow_decide error dependency-missing:jq
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure user-prompt-submit dependency-missing:jq ) >/dev/null 2>&1 || true
+fi
+require_jq
 # One jq pass over the payload for every field this hook reads (each pass costs about 8 ms on a
 # 20 KB prompt, and the budget is 100 ms), NUL-separated: session_id, cwd and session_title, null
 # and false read as empty as json_field does, with any NUL inside a value dropped so no field can
 # shift into the next; then `subagent` when agent_id or agent_type holds anything but null or "".
-SESSION_ID="" CWD="" PAYLOAD_TITLE="" SUBAGENT=""
-{ IFS= read -r -d '' SESSION_ID; IFS= read -r -d '' CWD; IFS= read -r -d '' PAYLOAD_TITLE; IFS= read -r -d '' SUBAGENT; } < <(
+SESSION_ID="" CWD="" PAYLOAD_TITLE="" SUBAGENT="" ENVELOPE_CLASS=missing
+{ IFS= read -r -d '' SESSION_ID; IFS= read -r -d '' CWD; IFS= read -r -d '' PAYLOAD_TITLE; IFS= read -r -d '' SUBAGENT; IFS= read -r -d '' ENVELOPE_CLASS; } < <(
   printf '%s' "$INPUT" | jq -j '. as $p
-    | [$p.session_id, $p.cwd, $p.session_title]
+    | [if ($p.session_id | type) == "string" then ($p.session_id | rtrimstr("\n")) else $p.session_id end, $p.cwd, $p.session_title]
     | map(if . == null or . == false then "" elif type == "string" then . else tojson end | split("\u0000") | join(""))
     | . + [if any($p.agent_id, $p.agent_type; . != null and . != "") then "subagent" else "" end]
+    | . + [if (($p | type) != "object") or (($p.doflow_event | type) != "object") or (($p.doflow_event | has("version")) | not) then "missing" elif (($p.doflow_event.version | type) == "number") and $p.doflow_event.version == 1 then "v1" else "unsupported" end]
     | join("\u0000") + "\u0000"' 2>/dev/null
 ) || true
+ENVELOPE_CLASS=${ENVELOPE_CLASS:-missing}
+if [ ! -f "$POLICY_DIR/contract.sh" ]; then ENVELOPE_CLASS=missing; fi
+
+if [[ "$ENVELOPE_CLASS" == unsupported || "$ENVELOPE_CLASS" == missing ]]; then
+  code=envelope-version
+  [[ "$ENVELOPE_CLASS" == missing ]] && code=envelope-missing
+  [[ -f "$POLICY_DIR/contract.sh" ]] || code=contract-missing
+  doflow_decide unsupported "$code"
+  if [[ -f "$POLICY_DIR/contract.sh" ]]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure user-prompt-submit "$code" ) >/dev/null 2>&1 || true
+  fi
+  printf '{}'
+  exit 0
+fi
 
 [[ -z "$SESSION_ID" ]] && exit 0
 
@@ -65,7 +96,7 @@ nudge_message() {
   # N5: a subagent prompt carries agent_id or agent_type (read with the other fields above).
   [[ -z "$SUBAGENT" ]] || return 0
   # N6: the policy script's physical directory, found with built-ins (a subshell costs about 4 ms).
-  case "$0" in */*) policy_dir="${0%/*}" ;; *) policy_dir="." ;; esac
+  policy_dir=$_DOFLOW_POLDIR
   here="$PWD"
   cd -P -- "$policy_dir" 2>/dev/null || return 0
   policy_dir="$PWD"
@@ -103,6 +134,7 @@ emit_envelope() {
 if [[ -f "$INJECTED_FLAG" ]]; then
   NUDGE=$(nudge_message 2>/dev/null) || NUDGE=""
   if [[ -n "$NUDGE" ]]; then
+    doflow_decide advisory prompt-nudge
     emit_envelope "$NUDGE" ""
   else
     echo "{}"
@@ -221,6 +253,7 @@ touch "$INJECTED_FLAG"
 # The nudge, when earned, follows the context after a blank line.
 NUDGE=$(nudge_message 2>/dev/null) || NUDGE=""
 if [[ -n "$NUDGE" ]]; then
+  doflow_decide advisory prompt-nudge
   CONTEXT+=$'\n\n'"$NUDGE"
 fi