@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/core/harnesses/codex/hooks/lib.sh

@@ -0,0 +1,335 @@
+#!/usr/bin/env bash
+# lib.sh — shared constants and helpers for session lifecycle hooks
+#
+# Usage: source "$(dirname "$0")/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"
+#
+# Deployment:
+#   This file is installed by the doflow CLI and overwritten on update — do
+#   not edit an installed copy directly.
+
+set -euo pipefail
+
+# ── State directories ────────────────────────────────────────────────────────
+
+# XDG-compliant, agent-agnostic store shared by Claude Code, Codex, Gemini, etc.
+DOFLOW_HOME="${XDG_CONFIG_HOME:-$HOME/.config}/doflow"
+STATE_DIR="$DOFLOW_HOME/session-env"
+SESSION_DIR="$STATE_DIR/sessions"
+PROJECTS_DIR="$STATE_DIR/projects"
+# shellcheck disable=SC2034  # used by session-start.sh and session-end.sh which source this file
+SESSIONS_LOG="$DOFLOW_HOME/sessions.log"
+
+# Identifies which agent is running. Override via env var for non-Claude agents.
+export DOFLOW_AGENT="${DOFLOW_AGENT:-unknown}"
+
+# ── canonicalize_path ────────────────────────────────────────────────────────
+
+# Print an absolute, symlink-resolved form of $1 when it exists; otherwise
+# print $1 unchanged. Replaces `realpath -e "$1" 2>/dev/null || echo "$1"`,
+# which silently falls back to an uncanonicalized path on stock macOS (BSD
+# realpath has no -e flag). Uses only primitives present on every target
+# (cd, pwd -P, dirname, basename) — no GNU-only flag, no assumed Homebrew
+# coreutils.
+#
+# Hardening notes:
+#   - `CDPATH=` resets CDPATH for the internal `cd` so a user's exported
+#     CDPATH can't redirect it to an unrelated directory of the same name
+#     (and can't make `cd` echo a stray "found via CDPATH" line to stdout).
+#   - `--` guards `dirname`/`basename`/`cd` against a path that begins with
+#     `-` being parsed as an option.
+#   - if the internal `cd` fails for any reason, `||` falls through to the
+#     uncanonicalized-path branch instead of aborting under this file's
+#     `set -e` (matching the old `realpath ... || echo "$1"` degrade path).
+#   - a root-level parent directory ("/") is special-cased so the result
+#     never gets a leading `//`, which POSIX leaves undefined and which
+#     Cygwin/MSYS2 (a DoFlow target platform) interprets as a UNC path.
+canonicalize_path() {
+  local path="$1" dir base
+  if [[ -e "$path" ]] \
+    && dir=$(CDPATH= cd -P -- "$(dirname -- "$path")" 2>/dev/null && pwd -P); then
+    base=$(basename -- "$path")
+    if [[ "$dir" == "/" ]]; then
+      printf '/%s\n' "$base"
+    else
+      printf '%s/%s\n' "$dir" "$base"
+    fi
+  else
+    printf '%s\n' "$path"
+  fi
+}
+
+# ── with_file_lock ───────────────────────────────────────────────────────────
+
+# Internal: break in on $1 (a lock directory) if it looks abandoned — its
+# recorded owner PID is no longer alive, or it's older than 5x the caller's
+# timeout (floored at 30s so short test timeouts don't make legitimately-held
+# locks look stale). Best-effort: mkdir-based locking has no kernel-enforced
+# ownership the way flock did, so a PID can in principle be reused by an
+# unrelated process — the age check is the backstop for that race. The
+# guarded section this protects (session-log trimming) tolerates a rare
+# double-run; this is a soft safety net against a lock leaking forever after
+# its owner is SIGKILLed, not a hard mutual-exclusion guarantee.
+_with_file_lock_break_if_stale() {
+  local lockfile="$1"
+  local timeout_seconds="$2"
+
+  local owner_pid=""
+  [ -f "$lockfile/pid" ] && owner_pid=$(cat "$lockfile/pid" 2>/dev/null || true)
+  local owner_dead=0
+  if [ -n "$owner_pid" ] && ! kill -0 "$owner_pid" 2>/dev/null; then
+    owner_dead=1
+  fi
+
+  local too_old=0
+  local mtime
+  mtime=$(stat -f %m "$lockfile" 2>/dev/null || stat -c %Y "$lockfile" 2>/dev/null || echo "")
+  if [ -n "$mtime" ]; then
+    local max_age=$((timeout_seconds * 5))
+    [ "$max_age" -lt 30 ] && max_age=30
+    if [ $(($(date +%s) - mtime)) -gt "$max_age" ]; then
+      too_old=1
+    fi
+  fi
+
+  if [ "$owner_dead" -eq 1 ] || [ "$too_old" -eq 1 ]; then
+    rm -rf "$lockfile" 2>/dev/null || true
+  fi
+}
+
+# Acquire a lock via atomic `mkdir` (atomic on every filesystem DoFlow runs
+# on, including NTFS via MSYS2) — replaces `flock -x -w 5 200`, which is
+# util-linux-only and confirmed absent entirely on macOS.
+#
+# Usage: call to acquire, run the guarded section in the same shell/subshell,
+# then call again with "release" to release. The lock is also released
+# automatically on exit (normal or error) via an EXIT trap, so a crashed or
+# early-exiting guarded section never leaves the lock held.
+#
+#   if with_file_lock "$LOCK_FILE" 5; then
+#     ...guarded section...
+#     with_file_lock "$LOCK_FILE" release
+#   fi
+#
+# Returns 1 (without acquiring the lock) if timeout_seconds elapses first.
+# A lock whose owner process is gone, or that has sat far longer than the
+# caller's own timeout, is treated as abandoned and broken into rather than
+# waited out (see _with_file_lock_break_if_stale) — a `flock`-held lock was
+# always released by the kernel on process death; a bare `mkdir` lock is not,
+# so this replaces that guarantee instead of silently dropping it.
+#
+# Any EXIT trap the caller already had installed (e.g. its own temp-file
+# cleanup) is preserved: it still runs at real process exit (after this
+# lock's own cleanup), and is still armed as the active EXIT trap after an
+# explicit "release" call — acquiring/releasing this lock never discards it.
+with_file_lock() {
+  local lockfile="$1"
+  local arg="$2"
+
+  if [ "$arg" = "release" ]; then
+    rm -f "$lockfile/pid" 2>/dev/null || true
+    rmdir "$lockfile" 2>/dev/null || true
+    if [ -n "${_DOFLOW_LOCK_PREV_TRAP:-}" ]; then
+      eval "$_DOFLOW_LOCK_PREV_TRAP"
+    else
+      trap - EXIT
+    fi
+    unset _DOFLOW_LOCK_PREV_TRAP
+    return 0
+  fi
+
+  local timeout_seconds="$arg"
+  local waited=0
+  while ! mkdir "$lockfile" 2>/dev/null; do
+    _with_file_lock_break_if_stale "$lockfile" "$timeout_seconds"
+    if [ "$waited" -ge "$timeout_seconds" ]; then
+      return 1
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+  echo "$$" >"$lockfile/pid" 2>/dev/null || true
+
+  # Capture the caller's existing EXIT trap (if any) so releasing this lock
+  # can restore it verbatim, and so real process exit runs both this lock's
+  # cleanup and the caller's original cleanup rather than only the latest
+  # one registered.
+  _DOFLOW_LOCK_PREV_TRAP=$(trap -p EXIT)
+  local prev_cmd=""
+  if [ -n "$_DOFLOW_LOCK_PREV_TRAP" ]; then
+    local prev_body="${_DOFLOW_LOCK_PREV_TRAP#trap -- }"
+    prev_body="${prev_body% EXIT}"
+    eval "prev_cmd=$prev_body"
+  fi
+  # shellcheck disable=SC2064  # intentional immediate expansion of $lockfile/$prev_cmd
+  trap "rm -f '$lockfile/pid' 2>/dev/null; rmdir '$lockfile' 2>/dev/null; $prev_cmd" EXIT
+  return 0
+}
+
+# ── run_with_timeout ─────────────────────────────────────────────────────────
+
+# Run <command...> and terminate it if it exceeds <seconds>. Replaces bare
+# GNU `timeout` calls, which are not installed by default on stock macOS
+# without Homebrew coreutils. When neither a verified-GNU `timeout` nor
+# `gtimeout` (the Homebrew coreutils name) is on PATH, runs the command
+# directly with no enforced budget — a soft safety net, not a correctness
+# requirement.
+#
+# `timeout` is not trusted just because something by that name is on PATH:
+# on Git Bash/MSYS2, PATH can resolve it to Windows' native
+# `System32\timeout.exe`, whose syntax (`timeout /T n`) is incompatible —
+# invoking it the GNU way would fail the command outright instead of just
+# running it unbounded. `timeout --version` is a cheap, side-effect-free way
+# to confirm it's the GNU coreutils build before trusting it (Windows'
+# timeout.exe doesn't understand --version and errors).
+#
+# Usage: run_with_timeout <seconds> -- <command...>
+run_with_timeout() {
+  local seconds="$1"
+  shift
+  if [ "${1:-}" = "--" ]; then
+    shift
+  fi
+
+  if command -v timeout &>/dev/null && timeout --version &>/dev/null; then
+    timeout "$seconds" "$@"
+  elif command -v gtimeout &>/dev/null; then
+    gtimeout "$seconds" "$@"
+  else
+    "$@"
+  fi
+}
+
+# ── cwd_hash ─────────────────────────────────────────────────────────────────
+
+# Derive a stable 16-char hash of an absolute directory path.
+# Used to namespace per-project state (compact summaries, warnings).
+#
+# For a path that is (or resolves to) an existing directory — the case this
+# function exists for — fully resolves it, including a symlink at the path's
+# own leaf component, via `(cd "$1" && pwd -P)`, so equivalent directories
+# always hash identically. Callers that ever pass a non-directory or
+# nonexistent path fall back to the general-purpose canonicalize_path, which
+# — being usable by any file or missing path, not just directories — only
+# resolves symlinks in the parent chain, not the leaf itself.
+#
+# Hash fallback chain: sha256sum -> shasum -a 256 -> cksum (last resort).
+# The cksum branch is normalized via printf '%016x' to the same 16-char
+# hex contract every other branch provides — raw cksum output is a decimal
+# CRC, not hex, and not guaranteed to be 16 characters. Collision risk from
+# the cksum fallback is acceptable here — this is only a cache-key
+# namespace, not security-relevant.
+cwd_hash() {
+  local canonical
+  if [ -d "$1" ]; then
+    canonical=$(cd "$1" && pwd -P)
+  else
+    canonical=$(canonicalize_path "$1")
+  fi
+  if command -v sha256sum &>/dev/null; then
+    echo "$canonical" | sha256sum | cut -c1-16
+  elif command -v shasum &>/dev/null; then
+    echo "$canonical" | shasum -a 256 | cut -c1-16
+  else
+    printf '%016x\n' "$(echo "$canonical" | cksum | cut -d' ' -f1)"
+  fi
+}
+
+# ── Git state helpers ────────────────────────────────────────────────────────
+#
+# Thin wrappers around `git -C <cwd> ...` with the project's standard 1s
+# timeout. Each echoes git's own output (or nothing/0 on failure) and leaves
+# stderr suppressed -- callers keep their own `|| echo <fallback>` around a
+# call for a script-specific default, exactly as the inline git calls these
+# replace did (022-hooks-remaining-duplication). Kept in this per-harness
+# copy rather than moved to the canonical lib.sh's sourcing path: this
+# script's own with_file_lock/other APIs have not been reconciled with the
+# canonical copy, so repointing the `source` line is a separate, larger
+# change this refactor does not make.
+
+is_git_worktree() {
+  run_with_timeout 1 -- git -C "$1" rev-parse --is-inside-work-tree &>/dev/null
+}
+
+git_branch_of() {
+  run_with_timeout 1 -- git -C "$1" branch --show-current 2>/dev/null
+}
+
+git_short_sha_of() {
+  run_with_timeout 1 -- git -C "$1" rev-parse --short HEAD 2>/dev/null
+}
+
+git_uncommitted_count_of() {
+  run_with_timeout 1 -- git -C "$1" status --porcelain 2>/dev/null | wc -l | tr -d ' '
+}
+
+has_uncommitted_changes() {
+  run_with_timeout 1 -- git -C "$1" status --porcelain 2>/dev/null | grep -q .
+}
+
+# ── Directory helpers ─────────────────────────────────────────────────────────
+
+# Create and return the session-scoped state directory for a given session_id.
+# Safe to call multiple times (mkdir -p is idempotent).
+ensure_session_dir() {
+  local session_id="$1"
+  mkdir -p "$SESSION_DIR/$session_id"
+  echo "$SESSION_DIR/$session_id"
+}
+
+# Create and return the project-scoped state directory for a given cwd.
+# Shared across all sessions in the same directory.
+ensure_project_dir() {
+  local cwd="$1"
+  local hash
+  hash=$(cwd_hash "$cwd")
+  mkdir -p "$PROJECTS_DIR/$hash"
+  echo "$PROJECTS_DIR/$hash"
+}
+
+# ── JSON helpers ──────────────────────────────────────────────────────────────
+
+# Extract a field from a JSON string.
+# Usage: json_field "$INPUT" ".field_name"
+# Returns empty string if field is null or jq fails.
+json_field() {
+  local json="$1"
+  local query="$2"
+  echo "$json" | jq -r "$query // empty" 2>/dev/null || echo ""
+}
+
+# ── Dependency guard ──────────────────────────────────────────────────────────
+
+# Verify jq is available at runtime. If absent, emit a diagnostic to stderr
+# and exit 0 (never block the harness — degraded operation is preferable to failure).
+require_jq() {
+  if ! command -v jq &>/dev/null; then
+    echo "[hooks] jq not found — install jq to enable session lifecycle hooks (apt install jq / brew install jq)" >&2
+    exit 0
+  fi
+}
+
+# ── Session role ──────────────────────────────────────────────────────────────
+
+# Print `main` or `worker` for this session, read from DOFLOW_SESSION_ROLE (matched
+# case-insensitively). Unset or empty is `main`; a value that is neither `main` nor
+# `worker` is `worker` and writes one line to stderr. A worker never writes or claims the
+# project's compact summary or warning. Always returns 0. bash 3.2 safe (no ${var,,}).
+doflow_session_role() {
+  local role
+  role=$(printf '%s' "${DOFLOW_SESSION_ROLE:-}" | tr '[:upper:]' '[:lower:]') || role=""
+  case "$role" in
+    ""|main) printf 'main\n' ;;
+    worker) printf 'worker\n' ;;
+    *)
+      echo "[doflow] unknown DOFLOW_SESSION_ROLE; treating session as worker" >&2
+      printf 'worker\n'
+      ;;
+  esac
+  return 0
+}

package/core/harnesses/codex/hooks/mcp-tool-guard.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Codex front door: delegates the mcp-tool-guard decision to the Canonical Policy
+# Library, then translates it into the hookSpecificOutput.permissionDecision deny
+# contract this script's Codex/Claude originals both used — exit code alone is
+# not sufficient here, so this front door is a translator, not a bare exec
+# (unlike session-context/stop-check, which never need this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
+
+command -v jq >/dev/null 2>&1 || exit 0
+source "$(dirname "$0")/../../.doflow/shared/hooks/policies/deny-json.sh"
+
+POLICY="$(dirname "$0")/../../.doflow/shared/hooks/policies/mcp-tool-guard.sh"
+REASON=$(bash "$POLICY" 2>&1 >/dev/null)
+CODE=$?
+
+[ "$CODE" -ne 0 ] && emit_pretooluse_deny_nested "${REASON:-MCP tool call blocked by mcp-tool-guard}"
+exit 0

package/core/harnesses/codex/hooks/post-edit-lint.impl.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# post-edit-lint.impl.sh — PostToolUse(Edit|Write|apply_patch) hook, shared across harnesses
+#
+# Pure collector: appends the edited/written file_path to a session-scoped
+# list. The actual lint work happens in stop-check.sh at the end of each
+# turn, where all paths can be batched by extension in one pass.
+#
+# Multi-session safe: writes only to sessions/{session_id}/edited-files.txt.
+# Must complete in <20ms. Must never exit non-zero or produce unexpected output.
+# Emits no stdout, so this script's output has no harness-specific compatibility
+# question (unlike pre-compact.impl.sh) — every harness accepts a silent exit 0.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+TOOL_NAME=$(json_field "$INPUT" ".tool_name")
+
+# Only handle Edit/Write (Claude, Gemini) and apply_patch (Codex's edit tool name)
+[[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "apply_patch" ]] && exit 0
+
+# Guard: if we can't determine the session, nothing to do
+[[ -z "$SESSION_ID" ]] && exit 0
+
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+
+if [[ "$TOOL_NAME" == "apply_patch" ]]; then
+  # Codex's apply_patch has no tool_input.file_path — tool_input is
+  # {"command": "<raw patch text>"}, a unified-diff-style patch that can touch
+  # multiple files via "*** Add File:" / "*** Update File:" / "*** Delete File:"
+  # / "*** Move to:" headers (confirmed against codex-rs/core/prompt_with_apply_patch_instructions.md
+  # and apply_patch_tests.rs — there is no single file_path field to read).
+  PATCH=$(json_field "$INPUT" ".tool_input.command")
+  [[ -z "$PATCH" ]] && exit 0
+  echo "$PATCH" | grep -oE '^\*\*\* (Add File|Update File|Delete File|Move to): .+' \
+    | sed -E 's/^\*\*\* (Add File|Update File|Delete File|Move to): //' \
+    >> "$SESSION_PATH/edited-files.txt" || true
+  exit 0
+fi
+
+FILE_PATH=$(json_field "$INPUT" ".tool_input.file_path")
+
+# Skip if no file_path (e.g., field absent from input)
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Append path (one per line) — stop-check.sh reads this list atomically
+echo "$FILE_PATH" >> "$SESSION_PATH/edited-files.txt"
+
+exit 0

package/core/harnesses/codex/hooks/post-edit-lint.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Codex adapter: post-edit-lint.impl.sh writes no stdout (session-file collector only),
+# so there is no output-format compatibility question here, unlike pre-compact.sh.
+set -euo pipefail
+export DOFLOW_AGENT=codex
+exec bash "$(dirname "$0")/post-edit-lint.impl.sh"

package/core/harnesses/codex/hooks/pre-bash-guard.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Codex front door: delegates the pre-bash-guard decision to the Canonical Policy
+# Library, then translates it into the hookSpecificOutput.permissionDecision deny
+# contract this script's Codex/Claude originals both used — exit code alone is
+# not sufficient here, so this front door is a translator, not a bare exec
+# (unlike session-context/stop-check, which never need this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
+
+command -v jq >/dev/null 2>&1 || exit 0
+source "$(dirname "$0")/../../.doflow/shared/hooks/policies/deny-json.sh"
+
+POLICY="$(dirname "$0")/../../.doflow/shared/hooks/policies/pre-bash-guard.sh"
+REASON=$(bash "$POLICY" 2>&1 >/dev/null)
+CODE=$?
+
+[ "$CODE" -ne 0 ] && emit_pretooluse_deny_nested "${REASON:-Command blocked by pre-bash-guard}"
+exit 0

package/core/harnesses/codex/hooks/pre-compact.impl.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# pre-compact.impl.sh — PreCompact hook (Codex-specific output shape)
+#
+# Codex's PreCompact output schema (codex-rs/hooks/src/schema.rs::PreCompactCommandOutputWire)
+# flattens only HookUniversalOutputWire (continue/stopReason/suppressOutput/systemMessage) and
+# rejects unknown fields — there is no additionalContext-style field for PreCompact, and the
+# output MUST be valid JSON, unlike Claude's PreCompact hook, which reads a plain string as
+# custom_instructions. This script gathers the same git-state context Claude's pre-compact.sh
+# does, but emits it as a JSON systemMessage instead — the closest available field, though
+# systemMessage's exact downstream effect on compaction content is not confirmed (Claude's
+# custom_instructions is fed directly to the compaction LLM call; Codex's docs do not state that
+# systemMessage receives the same treatment). Treat this as best-effort context surfacing, not a
+# guaranteed compaction-summary injection, until verified against a live Codex session.
+#
+# Must never exit non-zero or block (PreCompact hooks do not support a block decision in Codex).
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+CWD=$(json_field "$INPUT" ".cwd")
+
+BRANCH=""
+SHA=""
+UNCOMMITTED=0
+
+if [[ -n "$CWD" ]] && is_git_worktree "$CWD"; then
+  BRANCH=$(git_branch_of "$CWD" || echo "")
+  SHA=$(git_short_sha_of "$CWD" || echo "")
+  UNCOMMITTED=$(git_uncommitted_count_of "$CWD" || echo "0")
+  RECENT=$(run_with_timeout 1 -- git -C "$CWD" log --format="%h %s" -2 2>/dev/null | paste -sd ' | ' - || echo "")
+
+  MSG=$(printf 'Include in compact summary:\n- git branch: %s sha: %s\n- recent commits: %s\n- uncommitted files: %s\n- cwd: %s\nPreserve: decisions made, files modified, open questions, planned next steps.' \
+    "${BRANCH:-unknown}" "${SHA:-unknown}" "${RECENT:-none}" "$UNCOMMITTED" "${CWD:-unknown}")
+else
+  MSG=$(printf 'Include in compact summary:\n- cwd: %s (not a git repository)\nPreserve: decisions made, files modified, open questions, planned next steps.' \
+    "${CWD:-unknown}")
+fi
+
+# Hard-cap at 490 chars, matching Claude's script, before JSON-encoding.
+MSG="${MSG:0:490}"
+
+jq -n --arg systemMessage "$MSG" '{systemMessage: $systemMessage}'
+exit 0

package/core/harnesses/codex/hooks/pre-compact.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Codex adapter: pre-compact.impl.sh is Codex-specific, NOT a shared/impl-reuse of Claude's
+# script — Codex's PreCompact output schema (PreCompactCommandOutputWire) only accepts the
+# universal fields (continue/stopReason/suppressOutput/systemMessage) as JSON, with unknown
+# fields rejected; it has no additionalContext-equivalent and Claude's plain-string output would
+# not parse. See pre-compact.impl.sh for the adapted implementation.
+set -euo pipefail
+export DOFLOW_AGENT=codex
+exec bash "$(dirname "$0")/pre-compact.impl.sh"

package/core/harnesses/codex/hooks/pre-implement-gate.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Codex front door: delegates the pre-implementation-gate decision to the
+# Canonical Policy Library, then translates it into the
+# hookSpecificOutput.permissionDecision deny contract this script's Codex/Claude
+# originals both used — exit code alone is not sufficient here, so this front
+# door is a translator, not a bare exec (unlike session-context/stop-check,
+# which never need this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
+
+command -v jq >/dev/null 2>&1 || exit 0
+source "$(dirname "$0")/../../.doflow/shared/hooks/policies/deny-json.sh"
+
+POLICY="$(dirname "$0")/../../.doflow/shared/hooks/policies/pre-implementation-gate.sh"
+REASON=$(bash "$POLICY" 2>&1 >/dev/null)
+CODE=$?
+
+[ "$CODE" -ne 0 ] && emit_pretooluse_deny_nested "${REASON:-Implementation requires an approved plan.md}"
+exit 0

package/core/harnesses/codex/hooks/session-end.impl.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# session-end.sh — SessionEnd hook
+#
+# Runs when Claude Code closes a session. Responsibilities:
+#   1. Append END marker to sessions.log
+#   2. Write uncommitted-warning.txt if the working tree is dirty
+#   3. Delete the session-scoped state directory (cleanup)
+#   4. Trim sessions.log to last 500 lines (lock-guarded for parallel safety,
+#      via lib.sh's portable with_file_lock — no flock dependency)
+#
+# Multi-session safe: with_file_lock prevents concurrent sessions from
+# corrupting the log trim. Session directory deletion is per session_id so
+# sessions don't interfere.
+# Must never exit non-zero or block (SessionEnd is fire-and-forget).
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+CWD=$(json_field "$INPUT" ".cwd")
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# ── 1. Log session end ────────────────────────────────────────────────────────
+
+mkdir -p "$(dirname "$SESSIONS_LOG")"
+echo "$TIMESTAMP END ${SESSION_ID:-unknown} ${CWD:-unknown}" >> "$SESSIONS_LOG"
+
+# ── 2. Uncommitted-changes warning ────────────────────────────────────────────
+
+# A worker session never writes the project's warning; it is left for the main session.
+if [[ "$(doflow_session_role || echo main)" != "worker" ]] && [[ -n "$CWD" ]] && is_git_worktree "$CWD"; then
+  if has_uncommitted_changes "$CWD"; then
+    BRANCH=$(git_branch_of "$CWD" || echo "unknown")
+    PROJECT_DIR=$(ensure_project_dir "$CWD")
+    echo "Session ${SESSION_ID:-unknown} ended with uncommitted changes on branch ${BRANCH}" \
+      > "$PROJECT_DIR/uncommitted-warning.txt"
+  fi
+fi
+
+# ── 2b. Update meta.json last_active ─────────────────────────────────────────
+
+if [[ -n "$CWD" ]]; then
+  PROJECT_DIR=$(ensure_project_dir "$CWD")
+  if [[ -f "$PROJECT_DIR/meta.json" ]]; then
+    META_TMP=$(mktemp "$PROJECT_DIR/.meta.XXXXXX")
+    jq --arg ts "$TIMESTAMP" '.last_active = $ts' "$PROJECT_DIR/meta.json" \
+      > "$META_TMP" && mv "$META_TMP" "$PROJECT_DIR/meta.json" \
+      || rm -f "$META_TMP" 2>/dev/null || true
+  fi
+fi
+
+# ── 3. Delete session directory ───────────────────────────────────────────────
+
+if [[ -n "$SESSION_ID" ]]; then
+  SESSION_PATH="$SESSION_DIR/$SESSION_ID"
+  rm -rf "$SESSION_PATH" 2>/dev/null || true
+fi
+
+(
+  SHARED_POLICY_LIB="$(dirname "$0")/../../.doflow/shared/hooks/policies/lib.sh"
+  if [[ ! -f "$SHARED_POLICY_LIB" ]]; then
+    SHARED_POLICY_LIB="$(dirname "$0")/../../shared/hooks/policies/lib.sh"
+  fi
+  if [[ -f "$SHARED_POLICY_LIB" ]]; then
+    source "$SHARED_POLICY_LIB"
+    storage_upkeep_async "$CWD"
+  fi
+) >/dev/null 2>&1 || true
+
+# ── 4. Trim sessions.log (lock-guarded) ───────────────────────────────────────
+
+LOCK_FILE="${SESSIONS_LOG}.lock"
+# Give up after 5s rather than block indefinitely: if the lock is held, skip
+# the trim below and fall through to a normal exit 0 (SessionEnd is
+# fire-and-forget and must never exit non-zero or block).
+if with_file_lock "$LOCK_FILE" 5; then
+  if [[ -f "$SESSIONS_LOG" ]]; then
+    TMP=$(mktemp "${SESSIONS_LOG}.XXXXXX")
+    if tail -n 500 "$SESSIONS_LOG" > "$TMP"; then
+      mv "$TMP" "$SESSIONS_LOG" || rm -f "$TMP"
+    else
+      rm -f "$TMP"
+    fi
+  fi
+  with_file_lock "$LOCK_FILE" release
+fi
+
+exit 0

package/core/harnesses/codex/hooks/session-end.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Codex adapter: reuse shared cleanup with Codex attribution.
+set -euo pipefail
+export DOFLOW_AGENT=codex
+exec bash "$(dirname "$0")/session-end.impl.sh"

package/core/harnesses/codex/hooks/session-start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Codex adapter: reuse the canonical session-context policy with Codex attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/session-context.sh"

package/core/harnesses/codex/hooks/stop-check.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Codex adapter: preserve a blocking exit while returning valid Stop JSON on success.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
+rc=0
+bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/stop-check.sh" || rc=$?
+[ "$rc" -eq 2 ] && exit 2
+printf '{}\n'

package/core/harnesses/codex/hooks/subagent-audit.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Codex front door: reuse the canonical subagent-audit policy with Codex attribution, then emit
+# the empty-JSON SubagentStop requires on success (022-hooks-remaining-duplication: claude/codex's
+# copies were byte-identical; only this trailing JSON requirement is Codex-specific).
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
+bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/subagent-audit.sh"
+printf '{}\n'

package/core/harnesses/codex/hooks/user-prompt-submit.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Codex front door: reuse the canonical context policy with the Codex output envelope.
+# The shared policy selects Codex's hookSpecificOutput shape from this attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/user-prompt-submit.sh"