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

package/core/harnesses/pi/extensions/doflow-guard.js

@@ -0,0 +1,159 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// C.3's renderer replaces this relative source-tree path for each install scope.
+const BRIDGE = new URL('../../shared/hooks/bridge/bridge.sh', import.meta.url);
+const ROUTES = [
+  { tools: ['edit', 'write'], policy: 'pre-implementation-gate' },
+  { tools: ['bash'], policy: 'pre-bash-guard' },
+];
+const LIMIT = 1024 * 1024;
+const TIMEOUT_MS = 5000;
+const ERROR_REASON = (policy) => `[${policy}] DoFlow policy error; details: doflow-run failure list`;
+
+function route(toolName) {
+  for (const row of ROUTES) {
+    if (row.tools.includes(toolName)) return row.policy;
+  }
+  return typeof toolName === 'string' && toolName.startsWith('mcp__') ? 'mcp-tool-guard' : undefined;
+}
+
+function captureFailure(policy, point) {
+  const script = new URL('../policies/capture-failure.sh', BRIDGE);
+  try {
+    const child = spawn('bash', ['-c', '. "$1"; doflow_capture_failure "$2" "$3"', 'doflow-capture', fileURLToPath(script), policy, point], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+  } catch {
+    // Failure capture must never change Pi's tool-call decision.
+  }
+}
+
+function bridgeCall(policy, payload, ctx) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      const env = { ...process.env };
+      delete env.DOFLOW_PROJECT_DIR;
+      child = spawn('bash', [fileURLToPath(BRIDGE), 'pi', 'tool_call', policy], {
+        cwd: ctx.cwd,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: true,
+      });
+    } catch (error) {
+      reject(Object.assign(error, { failurePoint: 'bridge-spawn' }));
+      return;
+    }
+
+    const stdout = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    let timedOut = false;
+    let overflow = false;
+    let aborted = false;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      ctx.signal?.removeEventListener('abort', onAbort);
+      if (error) reject(error);
+      else resolve(result);
+    };
+    const kill = () => {
+      try {
+        if (child.pid && process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        try { child.kill('SIGKILL'); } catch {}
+      }
+    };
+    const fail = (point) => {
+      overflow = point === 'bridge-output-limit';
+      kill();
+      finish(Object.assign(new Error(point), { failurePoint: point }));
+    };
+    const onAbort = () => {
+      aborted = true;
+      kill();
+      finish(null, undefined);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, TIMEOUT_MS);
+    if (ctx.signal?.aborted) onAbort();
+    else ctx.signal?.addEventListener('abort', onAbort, { once: true });
+
+    child.on('error', (error) => finish(Object.assign(error, { failurePoint: 'bridge-spawn' })));
+    child.stdout.on('data', (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > LIMIT) return fail('bridge-output-limit');
+      stdout.push(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes > LIMIT) return fail('bridge-output-limit');
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      if (aborted) return finish(null, undefined);
+      if (timedOut) return finish(Object.assign(new Error('bridge timed out'), { failurePoint: 'bridge-timeout' }));
+      if (overflow) return finish(Object.assign(new Error('bridge output exceeded limit'), { failurePoint: 'bridge-output-limit' }));
+      if (code !== 0) return finish(Object.assign(new Error(`bridge exited ${code}`), { failurePoint: 'bridge-spawn' }));
+      const output = Buffer.concat(stdout).toString('utf8');
+      if (!output.trim()) return finish(null, undefined);
+      if (output.trim().split(/\r?\n/).length !== 1) {
+        return finish(Object.assign(new Error('bridge answer must be one JSON line'), { failurePoint: 'bridge-spawn' }));
+      }
+      try {
+        const answer = JSON.parse(output);
+        if (!answer || typeof answer !== 'object' || Array.isArray(answer) || answer.block !== true || typeof answer.reason !== 'string') {
+          throw new Error('invalid bridge answer');
+        }
+        finish(null, { block: true, reason: answer.reason });
+      } catch {
+        finish(Object.assign(new Error('invalid bridge answer'), { failurePoint: 'bridge-spawn' }));
+      }
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(payload);
+  });
+}
+
+export default function (pi) {
+  pi.on('tool_call', async (event, ctx) => {
+    let policy = 'unknown';
+    let profile = process.env.DOFLOW_FAULT_PROFILE || 'compat-1';
+    try {
+      policy = route(event.toolName);
+      if (!policy) return undefined;
+      profile = process.env.DOFLOW_FAULT_PROFILE || 'compat-1';
+      if (profile !== 'compat-1' && profile !== 'strict-1') captureFailure(policy, 'fault-profile-unknown');
+      if (!existsSync(BRIDGE)) {
+        captureFailure(policy, 'bridge-missing');
+        return { block: true, reason: '[doflow] shared hooks lack the bridge; run: doflow update -t pi' };
+      }
+      const payload = JSON.stringify({
+        type: event.type,
+        toolName: event.toolName,
+        toolCallId: event.toolCallId,
+        parentToolCallId: event.parentToolCallId,
+        input: event.input,
+        cwd: ctx.cwd,
+        sessionId: ctx.sessionManager?.getSessionId?.() ?? null,
+      });
+      if (Buffer.byteLength(payload) > LIMIT) throw Object.assign(new Error('bridge input exceeded limit'), { failurePoint: 'bridge-input-limit' });
+      return await bridgeCall(policy, payload, ctx);
+    } catch (error) {
+      const point = error?.failurePoint || 'bridge-spawn';
+      captureFailure(policy, point === 'bridge-timeout' || point === 'bridge-missing' ? point : 'bridge-spawn');
+      if (profile === 'strict-1') return { block: true, reason: ERROR_REASON(policy) };
+      return undefined;
+    }
+  });
+}

package/core/harnesses/shared/hooks/ENVELOPE_MIGRATION.md

@@ -1,16 +1,17 @@
 # The normalized hook envelope, and each front door's share of the migration
 
+Every shipped bridge places envelope version 1 under `doflow_event`, beside the native fields. Policies read v1 fields only when `version` is the JSON number `1`; any other version is unsupported and is evaluated as such (IC-034, DEC-030).
+
 `policies/pre-implementation-gate.sh` prefers one normalized event over every native payload
 shape (review R7):
 
 ```json
-{"doflow_event": {"operation": "edit", "paths": ["src/a.js"], "projectRoot": "/repo", "taskId": "001-auth"}}
+{"doflow_event": {"version": 1, "harness": "claude", "event": "PreToolUse", "operation": "edit", "paths": ["src/a.js"], "projectRoot": "/repo", "taskId": "001-auth"}}
 ```
 
-A front door that sends this envelope needs none of the policy's legacy union parsing — the four
-tool-name spellings, five file-path field names, and Codex `apply_patch` diff extraction exist
-only for front doors still forwarding raw native payloads. Each adapter that adopts the envelope
-retires its share of that union; when the last one does, the union decoder is deleted.
+The envelope is the only policy input contract. A caller outside a shipped bridge must either
+send a v1 envelope itself or pipe its native payload through
+`bash .doflow/shared/hooks/bridge/bridge.sh <harness> <event> <policy>`.
 
 ## Which native event each front door decodes
 
@@ -24,16 +25,31 @@ tool's official docs (cross-checked against tool source where docs were incomple
 | Gemini CLI | `BeforeTool` | also offers `BeforeToolSelection` (pre-selection restriction), which the gate does not use |
 | GitHub Copilot | `preToolUse` | camelCase event names; `permissionRequest` is CLI-only, not fired in the cloud agent |
 | OpenCode | `tool.execute.before` | a pluggable hook method, not a sub-event of the generic `event` hook |
-| Pi | `tool_execution_start` | Pi's 36-event surface also exposes `tool_call`; the execution-start event is the gate's anchor |
+| Pi | `tool_call` | The live-observed `cli-extension` pre-implementation gate row blocks. Project-interactive and user-interactive rows remain unknown; interactive loading and project-trust behavior were not observed. `tool_execution_start` is observation-only |
 | Antigravity | `PreToolUse` | 5-event surface, `hooks.json` + stdin/stdout JSON contract |
 
+Pi 1.1.0 declares 41 `on()` overloads in its shipped extension types. `tool_call` is the enforcement event; `tool_execution_start` is not a gate.
+
 `operation` is `"edit"` for anything that writes source; a decoder maps its native create/replace/
 patch tool vocabulary down to that one word. Non-edit operations may be sent (the policy allows
 them through), but sending nothing for a non-edit tool is equally correct and cheaper.
 
-## Rules that hold on both paths
-
-- The envelope, when present, **outranks** any native fields beside it.
+## Version and mixed-install rules
+
+- A missing envelope or version, empty or non-object input, or a missing `contract.sh` is out of
+  step. The gate, bash guard and MCP guard deny with `DoFlow hooks out of step; run: doflow update
+  -t <harness>`; Stop and context policies exit silently, except the prompt hook emits its `{}`
+  no-op. Other envelope versions are unsupported and policies evaluate nothing.
+- If a door cannot load `bridge/bridge.sh`, it renders its fixed native out-of-step response. The
+  Pi extension blocks with the fixed native out-of-step reason; a present bridge that fails to spawn or answer follows
+  the configured bridge-fault behavior.
+
+Other current bridge behavior: Codex Stop crash stderr is suppressed (DEC-037). Stop-check
+enforcement is answered from Stop coverage rows (DEC-038). Strict-1 never fault-blocks Stop, though
+a real Stop deny still blocks (DEC-039). Bridge capture uses no temporary file, so an unwritable
+`TMPDIR` does not turn a gate deny into an allow; background jobs do not hold Stop or SessionStart
+open; strict-1 renders native denies without `jq`. `doflow update -t codex -f` re-merges edited
+Codex `hooks.json` while keeping user entries (DEC-040).
 - Root resolution: `DOFLOW_PROJECT_DIR` beats the envelope's `projectRoot` beats git discovery.
-- The policy remains a pure file-existence gate (FR-012): the envelope changes how it hears about
-  an edit, never what it decides, and it must never consult readiness or evidence state.
+- The pre-implementation gate checks required artifacts and reads run and readiness records; it
+  does not consult evidence state.

package/core/harnesses/shared/hooks/adapters/antigravity.js

@@ -1,8 +1,8 @@
 'use strict';
 
 /**
- * Antigravity payload/decision adapter for the Cross-Harness Hook Runner (design.md C2's
- * Payload Adapter / Decision Adapter seam, D2).
+ * Antigravity native decision renderer for the Cross-Harness Hook Runner's
+ * Decision Adapter seam, D2). The shared bridge owns native payload decoding.
  *
  * Antigravity's own native contracts — evidenced by core/harnesses/antigravity/hooks/*.sh (the
  * shims src/adapters/antigravity/index.js actually projects today) and
@@ -19,67 +19,24 @@
  *                vocabulary than PreToolUse's allow/deny/ask/force_ask, not an oversight.
  *
  * SessionStart and PostToolUse have no dedicated Antigravity-native shim in
- * src/adapters/antigravity/index.js's live projection; core/.antigravity-plugin/hooks.json (a
- * separate, read-only-to-this-task artifact) documents both routed directly to the *Gemini*
- * session-start.sh / post-edit-lint.sh scripts, which read the Claude/Gemini-style
- * session_id/cwd/tool_name/tool_input field names, not the toolCall envelope above — this
- * adapter honors that evidence for those two events rather than guessing at a toolCall shape
- * with no corroborating source. No Phase A canonical policy owns PostToolUse today (only
+ * src/adapters/antigravity/index.js's live projection. No Phase A canonical policy owns PostToolUse today (only
  * session-context, pre-implementation-gate, mcp-tool-guard, stop-check, pre-bash-guard exist),
  * so its native shape is an ack passthrough either way.
  */
 
-const { FILE_PATH_ARG_FIELDS, COMMAND_ARG_FIELDS, firstArgField } = require('./arg-fields');
-
-function toCanonical(event, payload) {
-  const safePayload = payload && typeof payload === 'object' ? payload : {};
-
-  switch (event) {
-    case 'SessionStart':
-      return { session_id: safePayload.session_id || '', cwd: safePayload.cwd || '' };
-
-    case 'PreToolUse': {
-      const toolCall = safePayload.toolCall || {};
-      const args = toolCall.args || {};
-      return {
-        tool_name: toolCall.name || '',
-        tool_input: {
-          file_path: firstArgField(args, FILE_PATH_ARG_FIELDS),
-          command: firstArgField(args, COMMAND_ARG_FIELDS),
-        },
-      };
-    }
-
-    case 'PostToolUse':
-      // No Phase A policy consumes this event — canonical shape kept for symmetry only.
-      return {
-        tool_name: safePayload.tool_name || '',
-        session_id: safePayload.session_id || '',
-        tool_input: { file_path: (safePayload.tool_input && safePayload.tool_input.file_path) || '' },
-      };
-
-    case 'Stop':
-      return {
-        session_id: safePayload.session_id || '',
-        transcript_path: safePayload.transcriptPath || safePayload.transcript_path || '',
-      };
-
-    case 'PreInvocation':
-      // No Phase A policy — ack only (injectSteps handled entirely in toNative).
-      return {};
-
-    default:
-      return safePayload;
-  }
-}
-
 function toNative(event, decision) {
   const safeDecision = decision || { decision: 'allow' };
+  const blocked = safeDecision.effect === 'block' || safeDecision.decision === 'deny';
+  const reason = safeDecision.outcome === 'deny'
+    ? safeDecision.reason
+    : safeDecision.effect === 'block'
+      ? `[${safeDecision.policy}] DoFlow policy error; details: doflow-run failure list`
+      : safeDecision.reason;
 
   switch (event) {
     case 'PreToolUse':
-      if (safeDecision.decision === 'deny') {
-        return { decision: 'deny', reason: safeDecision.reason };
+      if (blocked) {
+        return { decision: 'deny', reason };
       }
       return { decision: 'allow' };
 
@@ -88,8 +45,8 @@ function toNative(event, decision) {
       return {};
 
     case 'Stop':
-      if (safeDecision.decision === 'deny') {
-        return { decision: 'continue', reason: safeDecision.reason };
+      if (blocked) {
+        return { decision: 'continue', reason };
       }
       // Silence (no positive field) lets the session stop, per Antigravity's own documented
       // Stop contract — not the allow/deny vocabulary PreToolUse uses.
@@ -108,4 +65,4 @@ function toNative(event, decision) {
   }
 }
 
-module.exports = { toCanonical, toNative };
+module.exports = { toNative };

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

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Shared lifecycle bridge. Sourcing defines functions only; it sets no shell options or traps.
+case ${BASH_SOURCE[0]} in */*) _DOFLOW_BRIDGE_DIR=${BASH_SOURCE[0]%/*} ;; *) _DOFLOW_BRIDGE_DIR=. ;; esac
+
+doflow_bridge_failure() {
+  local policy="$1" point="$2"
+  ( . "$_DOFLOW_BRIDGE_DIR/../policies/capture-failure.sh"; doflow_capture_failure "$policy" "$point" ) >/dev/null 2>&1 || true
+}
+
+doflow_bridge_classify() {
+  local code="$1" record="$2" outcome="" decision_code="" version=0 reason="$3"
+  if [ -n "$record" ]; then
+    outcome="${record#*\"outcome\":\"}"; outcome="${outcome%%\"*}"
+    decision_code="${record#*\"code\":\"}"; decision_code="${decision_code%%\"*}"
+    version="${record#*\"policyVersion\":}"; version="${version%%,*}"
+    case "$version" in ''|*[^0-9]*) version=0;; esac
+  fi
+  DF_BRIDGE_OUTCOME=error; DF_BRIDGE_CODE=exit-"$code"; DF_BRIDGE_VERSION="$version"; DF_BRIDGE_REASON="$DF_BRIDGE_CODE"; DF_BRIDGE_POINT="eval-error:exit-$code"
+  if [ "$code" -eq 2 ] 2>/dev/null; then
+    if [ "$outcome" = deny ]; then DF_BRIDGE_OUTCOME=deny; DF_BRIDGE_CODE="$decision_code"; DF_BRIDGE_REASON="$reason"; DF_BRIDGE_POINT=""
+    else DF_BRIDGE_CODE=exit-2-unmarked; DF_BRIDGE_REASON=exit-2-unmarked; DF_BRIDGE_POINT=eval-error:exit-2-unmarked; fi
+  elif [ "$code" -eq 0 ] 2>/dev/null; then
+    case "$outcome" in
+      allow|advisory|error|unsupported) DF_BRIDGE_OUTCOME="$outcome"; DF_BRIDGE_CODE="$decision_code"; DF_BRIDGE_REASON="$decision_code"; DF_BRIDGE_POINT="" ;;
+      deny) DF_BRIDGE_OUTCOME=allow; DF_BRIDGE_CODE=decision-mismatch; DF_BRIDGE_REASON=decision-mismatch; DF_BRIDGE_POINT=decision-mismatch ;;
+      *) DF_BRIDGE_OUTCOME=allow; DF_BRIDGE_CODE=allow; DF_BRIDGE_REASON=allow; DF_BRIDGE_POINT=""; DF_BRIDGE_VERSION=0 ;;
+    esac
+  elif [ "$code" -ge 129 ] && [ "$code" -le 255 ] && [ "$code" -ne 255 ] 2>/dev/null; then
+    local sig=""
+    sig="$(kill -l "$((code - 128))" 2>/dev/null)" || sig=""
+    sig="${sig#SIG}"
+    case "$sig" in ''|*[!A-Za-z0-9_-]*) return;; esac
+    DF_BRIDGE_OUTCOME=error; DF_BRIDGE_CODE=signal-"$sig"; DF_BRIDGE_REASON="$DF_BRIDGE_CODE"; DF_BRIDGE_POINT="eval-error:signal-$sig"
+  fi
+}
+
+doflow_bridge_effect() {
+  local harness="$1" event="$2" policy="$3" outcome="$4" profile="${DOFLOW_FAULT_PROFILE:-compat-1}" block=0
+  doflow_bridge_native_event_var "$harness" "$event"; event=$DF_NE
+  if [ "$profile" != compat-1 ] && [ "$profile" != strict-1 ]; then
+    profile=compat-1; doflow_bridge_failure "$policy" fault-profile-unknown
+  fi
+  DF_BRIDGE_PROFILE="$profile"
+  case "$policy" in pre-implementation-gate|pre-bash-guard|mcp-tool-guard|stop-check) block=1;; esac
+  DF_BRIDGE_EFFECT=proceed
+  if [ "$outcome" = deny ]; then DF_BRIDGE_EFFECT=block
+  elif [ "$profile" = strict-1 ] && [ "$block" -eq 1 ] && [ "$policy" != stop-check ] && { [ "$outcome" = error ] || [ "$outcome" = unsupported ] || [ "$DF_BRIDGE_CODE" = bridge-spawn ] || [ "$DF_BRIDGE_CODE" = envelope-encode ]; }; then DF_BRIDGE_EFFECT=block
+  elif [ "$outcome" = error ] && [ "$DF_BRIDGE_CODE" != bridge-spawn ] && [ -n "$DF_BRIDGE_POINT" ] && [ "$profile" = compat-1 ]; then
+    case "$harness:$event" in
+      claude:PreToolUse|codex:PreToolUse|gemini:BeforeTool|pi:tool_call) DF_BRIDGE_EFFECT=block ;;
+      antigravity:PreToolUse|antigravity:Stop) case "$DF_BRIDGE_CODE" in signal-*) DF_BRIDGE_EFFECT=proceed;; *) DF_BRIDGE_EFFECT=block;; esac ;;
+      kiro:PreToolUse) [ "$DF_BRIDGE_CODE" = exit-2-unmarked ] && DF_BRIDGE_EFFECT=block ;;
+      claude:Stop) [ "$DF_BRIDGE_CODE" = exit-2-unmarked ] && DF_BRIDGE_EFFECT=block ;;
+      codex:Stop|codex:stop|kiro:Stop|kiro:stop) [ "$DF_BRIDGE_CODE" = exit-2-unmarked ] && DF_BRIDGE_EFFECT=block || DF_BRIDGE_EFFECT=proceed ;;
+    esac
+  fi
+}
+
+doflow_bridge_drops_tool_streams() {
+  case "$1" in
+    pre-implementation-gate|pre-bash-guard|mcp-tool-guard) ;;
+    *) return 1 ;;
+  esac
+  case "$2:$3" in
+    claude:PreToolUse|codex:PreToolUse|gemini:BeforeTool|kiro:PreToolUse|antigravity:PreToolUse|antigravity:Stop|pi:tool_call) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+doflow_bridge_drops_tool_stderr() {
+  case "$1:$2:$3" in
+    pre-implementation-gate:kiro:PreToolUse|pre-bash-guard:kiro:PreToolUse|mcp-tool-guard:kiro:PreToolUse) return 1 ;;
+  esac
+  doflow_bridge_drops_tool_streams "$1" "$2" "$3"
+}
+
+doflow_bridge() {
+  local harness="${1:-}" event="${2:-}" policy="${3:-}" response_event="" emit="native" payload="" encoded="" policy_path="" captured="" err="" code=0 policy_code=0 record="" reason="" decision_reason="" stdout="" status=0 decision="" line="" spawn_failed=0 encode_failed=0
+  . "$_DOFLOW_BRIDGE_DIR/respond.sh"
+  doflow_bridge_native_event_var "$harness" "$event"; response_event=$DF_NE
+  if [ "${4:-}" = --emit ]; then emit="${5:-native}"; fi
+  payload="$(cat)"
+  if command -v jq >/dev/null 2>&1; then
+    encoded="$(printf '%s\n' "$payload" | DOFLOW_TASK_ID="${DOFLOW_TASK_ID:-}" DOFLOW_RUN_ID="${DOFLOW_RUN_ID:-}" DOFLOW_ATTEMPT="${DOFLOW_ATTEMPT:-}" DOFLOW_SESSION_ROLE="${DOFLOW_SESSION_ROLE:-}" jq -c --arg harness "$harness" --arg event "$event" --arg policy "$policy" --arg mode encode -f "$_DOFLOW_BRIDGE_DIR/envelope.jq" 2>/dev/null)" && {
+      case "$encoded" in \{*) payload="$encoded" ;; *) encode_failed=1 ;; esac
+    } || { encode_failed=1; }
+    if [ "$encode_failed" -eq 1 ]; then
+      encoded="$(jq -cn --arg harness "$harness" --arg event "$event" --arg policy "$policy" --arg mode minimal -f "$_DOFLOW_BRIDGE_DIR/envelope.jq" 2>/dev/null)" || encoded=""
+      case "$encoded" in \{*) payload="$encoded" ;; *) payload="{\"doflow_event\":{\"version\":1,\"harness\":\"$harness\",\"event\":\"$event\",\"operation\":\"tool\"}}" ;; esac
+      doflow_bridge_failure "$policy" envelope-encode
+    fi
+  else
+    doflow_bridge_failure "$policy" dependency-missing:jq
+  fi
+  case "$policy" in
+    pre-implementation-gate|pre-bash-guard|mcp-tool-guard|stop-check|session-context|user-prompt-submit|subagent-audit) ;;
+    *) spawn_failed=1 ;;
+  esac
+  policy_path="$_DOFLOW_BRIDGE_DIR/../policies/$policy.sh"
+  if [ "$spawn_failed" -eq 1 ] || [ ! -f "$policy_path" ]; then
+    code=127; err=""; spawn_failed=1
+  else
+    if [ "$emit" = decision ] || doflow_bridge_drops_tool_streams "$policy" "$harness" "$response_event" || { [ "$harness" = kiro ] && [ "$response_event" = Stop ]; }; then exec 5>/dev/null; else exec 5>&1; fi
+    captured="$( {
+      if DOFLOW_AGENT="${DOFLOW_AGENT:-$harness}" DOFLOW_DECISION_FD=3 bash "$policy_path" 2>&1 3>&1 1>&5 5>&- <<<"$payload"; then policy_code=0; else policy_code=$?; fi
+      printf '\037%s' "$policy_code"
+    } )"
+    exec 5>&-
+    code="${captured##*$'\037'}"
+    captured="${captured%$'\037'*}"
+  fi
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      *$'\036'*)
+        local prefix="${line%%$'\036'*}"
+        record="${line#*$'\036'}"
+        [ -z "$prefix" ] || err="$err$prefix"$'\n'
+        ;;
+      *) err="$err$line"$'\n' ;;
+    esac
+  done < <(printf '%s' "$captured")
+  reason="${err%$'\n'}"
+  doflow_bridge_classify "$code" "$record" "$reason"
+  if [ "$encode_failed" -eq 1 ] && [ "$DF_BRIDGE_OUTCOME" != deny ]; then DF_BRIDGE_CODE=envelope-encode; DF_BRIDGE_POINT=envelope-encode; fi
+  if [ "$spawn_failed" -eq 1 ]; then DF_BRIDGE_OUTCOME=error; DF_BRIDGE_CODE=bridge-spawn; DF_BRIDGE_REASON=bridge-spawn; DF_BRIDGE_VERSION=0; DF_BRIDGE_POINT=bridge-spawn; fi
+  if [ -n "$DF_BRIDGE_POINT" ] && [ "$DF_BRIDGE_POINT" != decision-mismatch ] && [ "$DF_BRIDGE_POINT" != eval-error:signal-TERM ] && [ "$DF_BRIDGE_POINT" != eval-error:signal-INT ] && [ "$DF_BRIDGE_POINT" != eval-error:signal-PIPE ]; then doflow_bridge_failure "$policy" "$DF_BRIDGE_POINT"; fi
+  doflow_bridge_effect "$harness" "$event" "$policy" "$DF_BRIDGE_OUTCOME"
+  if [ "$DF_BRIDGE_EFFECT" = block ] && [ "$DF_BRIDGE_OUTCOME" != deny ]; then reason="[$policy] DoFlow policy error; details: doflow-run failure list"; fi
+  if [ "$DF_BRIDGE_OUTCOME" != deny ] && [ "$DF_BRIDGE_EFFECT" = proceed ]; then
+    case "$harness:$response_event:$DF_BRIDGE_OUTCOME" in
+      kiro:PreToolUse:error|claude:Stop:error)
+        case "$DF_BRIDGE_CODE" in
+          exit-*|signal-*)
+            reason="[$policy] DoFlow policy error; details: doflow-run failure list"
+            if [ "$harness:$response_event" = claude:Stop ]; then reason="$reason"$'\n'; fi
+            ;;
+        esac
+        ;;
+      *) reason="$DF_BRIDGE_CODE" ;;
+    esac
+  fi
+  decision_reason="$DF_BRIDGE_CODE"
+  if [ "$DF_BRIDGE_OUTCOME" = deny ]; then decision_reason="$reason"; fi
+  if [ "$emit" = decision ] || [ -n "${DOFLOW_BRIDGE_TRACE:-}" ]; then
+    decision="$(jq -cn --arg harness "$harness" --arg event "$event" --arg policy "$policy" --arg outcome "$DF_BRIDGE_OUTCOME" --arg code "$DF_BRIDGE_CODE" --arg reason "$decision_reason" --arg profile "$DF_BRIDGE_PROFILE" --arg effect "$DF_BRIDGE_EFFECT" --argjson version "$DF_BRIDGE_VERSION" '{v:1,harness:$harness,event:$event,policy:$policy,policyVersion:$version,outcome:$outcome,code:$code,reason:$reason,faultProfile:$profile,effect:$effect}')"
+  fi
+  if [ -n "${DOFLOW_BRIDGE_TRACE:-}" ]; then printf '%s\n' "$decision" >>"$DOFLOW_BRIDGE_TRACE" 2>/dev/null || true; fi
+  if [ "$emit" = decision ]; then
+    printf '%s\n' "$decision"
+    return 0
+  fi
+  if [ "$DF_BRIDGE_EFFECT" = block ]; then
+    status=2
+  else
+    status=0
+    if [ "$DF_BRIDGE_OUTCOME" = error ]; then
+      case "$policy:$harness:$response_event" in
+        session-context:*:*|user-prompt-submit:*:*|subagent-audit:*:*|*:kiro:PreToolUse|*:claude:Stop) status="$code" ;;
+      esac
+    fi
+  fi
+  if [ "$spawn_failed" -eq 1 ] && [ "$DF_BRIDGE_EFFECT" = proceed ]; then status=0; fi
+  if [ "$DF_BRIDGE_EFFECT" = block ]; then
+    doflow_render_response "$harness" "$event" deny "$reason" "$status"
+    local render_status=$?
+    return "$render_status"
+  fi
+  case "$policy:$DF_BRIDGE_OUTCOME:$harness:$response_event:$DF_BRIDGE_CODE" in
+    session-context:error:*:*:*|user-prompt-submit:error:*:*:*|subagent-audit:error:*:*:*|session-context:unsupported:*:*:*|user-prompt-submit:unsupported:*:*:*|subagent-audit:unsupported:*:*:*) ;;
+    *:error:codex:Stop:exit-*|*:error:codex:Stop:signal-*|*:error:codex:stop:exit-*|*:error:codex:stop:signal-*|*:error:kiro:PreToolUse:exit-*|*:error:kiro:PreToolUse:signal-*|*:error:kiro:Stop:exit-*|*:error:kiro:Stop:signal-*|*:error:claude:Stop:exit-*|*:error:claude:Stop:signal-*) ;;
+    *)
+      if ! doflow_bridge_drops_tool_stderr "$policy" "$harness" "$response_event" && [ -n "$err" ]; then printf '%s' "$err" >&2; fi
+      ;;
+  esac
+  doflow_render_response "$harness" "$event" "$DF_BRIDGE_OUTCOME" "$reason" "$status"
+  local render_status=$?
+  return "$render_status"
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  . "$_DOFLOW_BRIDGE_DIR/respond.sh"
+  doflow_bridge "${1:-}" "${2:-}" "${3:-}" "${4:-}" "${5:-}"
+  exit $?
+fi

package/core/harnesses/shared/hooks/bridge/envelope.jq

@@ -0,0 +1,60 @@
+def nonempty($v): if ($v | type) == "string" and $v != "" then $v else null end;
+def put($o; $k; $v): if $v == null then $o else $o + {($k): $v} end;
+def event_name($fallback): if (.hook_event_name | type) == "string" then .hook_event_name else $fallback end;
+def path_values($obj; $keys): first([$keys[] as $k | $obj[$k] | select(type == "string" and length > 0)][]) // null | if . == null then null else [.] end;
+def string_value($obj; $keys): first([$keys[] as $k | $obj[$k] | select(type == "string") ][]) // null;
+def session_identity($s): {session: nonempty($s)};
+def correlation($id;$parent): {toolCallId:nonempty($id),parentToolCallId:nonempty($parent)};
+def event_operation($e):
+  if $e == "SessionStart" or $e == "agentSpawn" then "session-start"
+  elif $e == "SessionEnd" then "session-end"
+  elif $e == "UserPromptSubmit" then "prompt"
+  elif $e == "Stop" or $e == "stop" then "stop"
+  elif $e == "SubagentStart" then "subagent-start"
+  elif $e == "SubagentStop" then "subagent-stop"
+  elif $e == "PreCompact" or $e == "PreCompress" then "compact"
+  elif $e == "PostToolUse" or $e == "AfterTool" then "post-tool"
+  else "tool" end;
+def canonical_tool($name; $harness):
+  if ($name | type) != "string" then {operation:"tool"}
+  elif (($harness == "claude" or $harness == "codex" or $harness == "kiro") and ($name | test("^mcp__"))) or (($harness == "gemini" or $harness == "antigravity") and ($name | test("^mcp_"))) or ($harness == "pi" and ($name | test("^mcp__"))) then {operation:"mcp",tool:$name}
+  elif (($harness == "claude" or $harness == "codex" or $harness == "kiro") and (["Edit","Write","MultiEdit","apply_patch"] | index($name)) != null) or ($harness == "gemini" and (["write_file","replace"] | index($name)) != null) or ($harness == "antigravity" and (["write_to_file","replace_file_content","multi_replace_file_content","edit_file","write_file","create_file","replace_file","replace","Edit","Write","MultiEdit","apply_patch"] | index($name)) != null) or ($harness == "pi" and (["edit","write"] | index($name)) != null) then {operation:"edit",tool:$name}
+  elif (($harness == "claude" or $harness == "codex" or $harness == "kiro") and $name == "Bash") or ($harness == "gemini" and $name == "run_shell_command") or ($harness == "antigravity" and (["run_command","run_shell_command","Bash","bash"] | index($name)) != null) or ($harness == "pi" and $name == "bash") then {operation:"command",tool:$name}
+  else {operation:"tool",tool:$name} end;
+def decode_claude:
+  (canonical_tool(.tool_name // ""; "claude")) as $t |
+  if .tool_name == null then {operation: event_operation($event), identity: session_identity(.session_id)}
+  else {operation:$t.operation, tool:$t.tool, paths:(if $t.operation == "edit" then path_values(.tool_input; ["file_path"]) else null end), command:(if $t.operation == "command" then string_value(.tool_input; ["command"]) else null end), identity:session_identity(.session_id)} end;
+def decode_codex:
+  decode_claude as $d |
+  if .tool_name == "apply_patch" then $d + {patch:(string_value(.tool_input; ["command"]))} else $d end;
+def decode_gemini:
+  (canonical_tool(.tool_name // ""; "gemini")) as $t |
+  if .tool_name == null then {operation:event_operation($event),identity:session_identity(.session_id)}
+  else {operation:$t.operation,tool:$t.tool,paths:(if $t.operation == "edit" then path_values(.tool_input; ["file_path","path"]) else null end),command:(if $t.operation == "command" then string_value(.tool_input; ["command"]) else null end),identity:session_identity(.session_id)} end;
+def decode_kiro:
+  (if ((.tool_name // "") | type) == "string" and ((.tool_name // "") | startswith("mcp_")) then {operation:"mcp",tool:.tool_name}
+   elif ((.tool_name // "") | type) == "string" and ((.tool_name // "") | test("^@[^/]+/.+")) then
+     ((.tool_name | capture("^@(?<server>[^/]+)/(?<tool>.+)$")) as $m | {operation:"mcp",tool:("mcp__" + $m.server + "__" + $m.tool)})
+   else canonical_tool(.tool_name // ""; "kiro") end) as $t |
+  if .tool_name == null then {operation:event_operation($event),identity:session_identity(.session_id)}
+  else {operation:$t.operation,tool:$t.tool,paths:(if $t.operation == "edit" then path_values(.tool_input; ["file_path"]) else null end),command:(if $t.operation == "command" then string_value(.tool_input; ["command"]) else null end),identity:session_identity(.session_id)} end;
+def decode_antigravity:
+  if .toolCall == null then {operation:event_operation($event),identity:session_identity(.session_id)}
+  else (canonical_tool(.toolCall.name // ""; "antigravity")) as $t |
+    {operation:$t.operation,tool:$t.tool,paths:(if $t.operation == "edit" then path_values(.toolCall.args; ["AbsolutePath","TargetFile","Path","file_path","path"]) else null end),command:(if $t.operation == "command" then string_value(.toolCall.args; ["CommandLine","command"]) else null end),identity:session_identity(.session_id)} end;
+def decode_pi:
+  (canonical_tool(.toolName // ""; "pi")) as $t |
+  {operation:$t.operation,tool:$t.tool,paths:(if $t.operation == "edit" then path_values(.input; ["path"]) else null end),command:(if $t.operation == "command" then string_value(.input; ["command"]) else null end),identity:session_identity(.sessionId),correlation:(correlation(.toolCallId;.parentToolCallId))};
+if ($ARGS.named.mode // "encode") == "minimal" then {doflow_event:{version:(1),harness:$harness,event:(event_name($event)),operation:event_operation($event)}} elif type != "object" then . else
+  . as $native |
+  ($ENV.DOFLOW_TASK_ID | nonempty(.)) as $task |
+  ($ENV.DOFLOW_RUN_ID | nonempty(.)) as $run |
+  ($ENV.DOFLOW_ATTEMPT | try tonumber catch null) as $attempt |
+  (if $ENV.DOFLOW_SESSION_ROLE == "main" or $ENV.DOFLOW_SESSION_ROLE == "worker" then $ENV.DOFLOW_SESSION_ROLE else null end) as $role |
+  (if $harness == "claude" then decode_claude elif $harness == "codex" then decode_codex elif $harness == "gemini" then decode_gemini elif $harness == "kiro" then decode_kiro elif $harness == "antigravity" then decode_antigravity elif $harness == "pi" then decode_pi else {operation:"tool"} end) as $d |
+  ({version:1,harness:$harness,event:(event_name($event)),operation:$d.operation,tool:$d.tool,paths:$d.paths,command:$d.command,patch:$d.patch,taskId:$task,
+    identity:($d.identity + {run:$run,attempt:$attempt,role:$role} | with_entries(select(.value != null)) | if length > 0 then . else null end),
+    correlation:(($d.correlation // {}) | with_entries(select(.value != null)) | if length > 0 then . else null end) } | with_entries(select(.value != null))) as $envelope |
+  $native + {doflow_event:$envelope}
+end

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"
+}