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

package/core/harnesses/gemini/hooks/hooks.json

@@ -0,0 +1,77 @@
+{
+  "description": "DoFlow lifecycle hooks for Gemini CLI. Gemini fingerprints hook name/command and warns before executing a changed one.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$GEMINI_PROJECT_DIR/.gemini/hooks/session-start.sh\""
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$GEMINI_PROJECT_DIR/.gemini/hooks/session-end.sh\"",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "BeforeTool": [
+      {
+        "matcher": "^run_shell_command$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$GEMINI_PROJECT_DIR/.gemini/hooks/pre-bash-guard.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "^mcp_.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$GEMINI_PROJECT_DIR/.gemini/hooks/mcp-tool-guard.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "^(write_file|replace)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$GEMINI_PROJECT_DIR/.gemini/hooks/pre-implement-gate.sh\""
+          }
+        ]
+      }
+    ],
+    "AfterTool": [
+      {
+        "matcher": "^(write_file|replace)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$GEMINI_PROJECT_DIR/.gemini/hooks/post-edit-lint.sh\""
+          }
+        ]
+      }
+    ],
+    "PreCompress": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$GEMINI_PROJECT_DIR/.gemini/hooks/pre-compact.sh\"",
+            "timeout": 3000
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,302 @@
+#!/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}"
+
+# ── Portability primitives ───────────────────────────────────────────────────
+#
+# The helpers in this section replace non-portable GNU/Linux-only dependencies
+# (realpath -e, flock, GNU timeout, bare sha256sum) with equivalents that run
+# on stock macOS, Git Bash/MSYS2, and common Linux distros without requiring
+# any additional package install (no Homebrew coreutils assumed).
+
+# Print an absolute, symlink-resolved form of <path> to stdout when <path>
+# exists; otherwise print <path> unchanged. Replaces `realpath -e "$1" ||
+# echo "$1"`, which already fails silently on stock macOS (BSD realpath has
+# no -e flag) and falls back to an uncanonicalized path. Uses only primitives
+# present on every target: cd, pwd -P, dirname, basename.
+#
+# 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
+}
+
+# Internal: age in whole seconds of <path>'s mtime, or nothing (and a
+# non-zero return) if it cannot be determined. Handles both GNU stat
+# (-c %Y) and BSD/macOS stat (-f %m) since this file assumes neither.
+lock_dir_age_seconds() {
+  local path="$1"
+  local mtime
+  mtime=$(stat -c %Y "$path" 2>/dev/null) || mtime=$(stat -f %m "$path" 2>/dev/null) || return 1
+  echo $(( $(date +%s) - mtime ))
+}
+
+# A lock dir older than this is presumed abandoned (holder crashed or was
+# killed before it could release) and eligible for reclaim. Deliberately
+# independent of any given with_file_lock call's own <timeout_seconds>: a
+# caller's polling budget is "how long am I willing to wait," which is
+# unrelated to "is the current holder still plausibly alive." Reusing
+# timeout_seconds for both would let a live holder's lock get stolen out
+# from under it the moment a contending caller's own wait approaches its
+# timeout — reclaim needs a threshold generous enough that no legitimate
+# hook invocation is still running, not tied to a contender's patience.
+LOCK_STALE_SECONDS=${LOCK_STALE_SECONDS:-300}
+
+# Acquire an exclusive lock on <lockfile>, using atomic mkdir (atomic on
+# every filesystem DoFlow runs on, including NTFS via MSYS2). Replaces
+# `flock -x -w <seconds> 200`, which is confirmed absent entirely on macOS
+# (util-linux only). Gives up after <timeout_seconds> instead of blocking
+# indefinitely, returning non-zero on timeout.
+#
+# Unlike `flock`, a `mkdir`-based lock has no kernel-backed release on
+# holder crash/kill, so this also reclaims the lock directory once it is
+# older than LOCK_STALE_SECONDS (treating it as abandoned), and separately
+# clears — rather than waits out the full timeout on — a non-directory
+# occupying <lockfile>, since a live holder created here always makes a
+# directory. That second case matters on upgrade: hosts that ran the old
+# `flock -x 200>"$LOCK_FILE"` implementation already have a *regular file*
+# at that path, which `mkdir` would otherwise EEXIST against forever.
+#
+# Calling convention: on success, installs a matching release via an EXIT
+# trap (fires on normal exit, on `set -e` abort, and on a killed subshell —
+# unlike a RETURN trap, which never fires for a top-level script, only for
+# a function return), so the caller does not need to remember to release:
+#
+#   if with_file_lock "$lockfile" 5; then
+#     ... guarded section ...
+#   else
+#     echo "[hooks] timed out waiting for lock: $lockfile" >&2
+#   fi
+with_file_lock() {
+  local lockfile="$1"
+  local timeout_seconds="$2"
+  local waited=0 age
+  while true; do
+    if mkdir "$lockfile" 2>/dev/null; then
+      trap 'release_file_lock "'"$lockfile"'"' EXIT
+      return 0
+    fi
+    if [[ -e "$lockfile" && ! -d "$lockfile" ]]; then
+      rm -f "$lockfile" 2>/dev/null || true
+      continue
+    fi
+    if [[ -d "$lockfile" ]]; then
+      age=$(lock_dir_age_seconds "$lockfile") || age=""
+      if [[ -n "$age" ]] && (( age >= LOCK_STALE_SECONDS )); then
+        rmdir "$lockfile" 2>/dev/null || true
+        continue
+      fi
+    fi
+    if (( waited >= timeout_seconds )); then
+      return 1
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+}
+
+# Release a lock acquired with with_file_lock. Normally invoked via the
+# EXIT trap with_file_lock installs on success; safe to call directly too.
+release_file_lock() {
+  local lockfile="$1"
+  rmdir "$lockfile" 2>/dev/null || true
+}
+
+# Run <command...> (after a literal `--` separator), terminating it if it
+# exceeds <seconds>. Replaces a bare dependency on GNU `timeout`, which is
+# not installed by default on stock macOS without Homebrew coreutils. When
+# neither `timeout` nor `gtimeout` is on PATH, runs <command...> directly
+# with no enforced budget (soft safety net, not a correctness requirement).
+#
+# `command -v timeout` is verified to actually be GNU coreutils' `timeout`
+# before use: Git Bash inherits the Windows PATH, where `timeout` can
+# resolve to System32's interactive delay command instead — a completely
+# different, incompatible CLI that would reject our arguments and prevent
+# the wrapped command from running at all. `timeout --version` succeeds
+# only on the GNU coreutils build; the Windows binary errors on it.
+#
+# Usage: run_with_timeout 5 -- some_command --with --args
+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).
+# Normalizes symlinks and ../ components so equivalent paths hash identically.
+#
+# 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.
+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/gemini/hooks/mcp-tool-guard.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Gemini front door: delegates the mcp-tool-guard decision to the Canonical
+# Policy Library, then translates it into Gemini's verified deny contract.
+#
+# Gemini's hook output schema (packages/core/src/hooks/types.ts, confirmed this
+# session) is a top-level {"decision": "deny", "reason": "..."} — NOT nested
+# under hookSpecificOutput.permissionDecision like Claude/Codex. Exit code alone
+# is not sufficient here, so this front door is a translator, not a bare exec
+# (unlike session-context, which never needs this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-gemini}"
+
+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_flat "${REASON:-MCP tool call blocked by mcp-tool-guard}"
+exit 0

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# post-edit-lint.sh — AfterTool(write_file|replace) hook
+#
+# 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.
+#
+# Gemini's write_file/replace tools both use a "file_path" tool_input key
+# (docs/reference/tools.md) — same field as Claude's
+# Edit/Write, unlike Codex's apply_patch (which needed patch-text parsing).
+#
+# KNOWN GAP: stop-check.sh (Claude's/Codex's consumer of edited-files.txt, run on the
+# Stop event) is NOT ported to Gemini — Gemini has no Stop-equivalent event (design.md
+# §8, this feature). This collector currently writes data nothing reads. Shipped anyway
+# as forward-looking infrastructure, same precedent as this repo's own mcp-policy.conf
+# (ships empty, ahead of real usage) — revisit once/if a Gemini turn-end consumer exists.
+#
+# 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.
+
+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")
+
+[[ "$TOOL_NAME" != "write_file" && "$TOOL_NAME" != "replace" ]] && exit 0
+[[ -z "$SESSION_ID" ]] && exit 0
+
+FILE_PATH=$(json_field "$INPUT" ".tool_input.file_path")
+[[ -z "$FILE_PATH" ]] && exit 0
+
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+echo "$FILE_PATH" >> "$SESSION_PATH/edited-files.txt"
+
+exit 0

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Gemini front door: delegates the pre-bash-guard decision to the Canonical
+# Policy Library, then translates it into Gemini's verified deny contract.
+#
+# Gemini's hook output schema (packages/core/src/hooks/types.ts, confirmed this
+# session) is a top-level {"decision": "deny", "reason": "..."} — NOT nested
+# under hookSpecificOutput.permissionDecision like Claude/Codex. Exit code alone
+# is not sufficient here, so this front door is a translator, not a bare exec
+# (unlike session-context, which never needs this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-gemini}"
+
+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_flat "${REASON:-Command blocked by pre-bash-guard}"
+exit 0

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# pre-compact.sh — PreCompress hook
+#
+# Gemini's PreCompress output schema (docs/hooks/reference.md) accepts a
+# "systemMessage" field, displayed to the user before compression — no
+# additionalContext-style field that feeds compaction content directly, same
+# limitation as Codex's PreCompact. Gathers the same git-state summary Claude's/
+# Codex's pre-compact scripts do, surfaced as a systemMessage instead.
+#
+# Must never exit non-zero or block.
+
+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 'Compacting session — git branch: %s sha: %s, recent commits: %s, uncommitted files: %s, cwd: %s' \
+    "${BRANCH:-unknown}" "${SHA:-unknown}" "${RECENT:-none}" "$UNCOMMITTED" "${CWD:-unknown}")
+else
+  MSG=$(printf 'Compacting session — cwd: %s (not a git repository)' "${CWD:-unknown}")
+fi
+
+MSG="${MSG:0:490}"
+jq -n --arg systemMessage "$MSG" '{systemMessage: $systemMessage}'
+exit 0

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

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Gemini front door: delegates the pre-implementation-gate decision to the
+# Canonical Policy Library, then translates it into Gemini's verified deny
+# contract.
+#
+# Gemini's hook output schema (packages/core/src/hooks/types.ts, confirmed this
+# session) is a top-level {"decision": "deny", "reason": "..."} — NOT nested
+# under hookSpecificOutput.permissionDecision like Claude/Codex. Exit code alone
+# is not sufficient here, so this front door is a translator, not a bare exec
+# (unlike session-context, which never needs this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-gemini}"
+
+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_flat "${REASON:-Implementation requires an approved plan.md}"
+exit 0

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

@@ -0,0 +1,89 @@
+#!/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)
+#
+# 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"
+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
+else
+  echo "[hooks] timed out waiting for lock: $LOCK_FILE" >&2  # Give up after 5s rather than block indefinitely
+fi
+
+exit 0

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

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

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

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Gemini adapter: reuse the Canonical Policy Library's session-context policy.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-gemini}"
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/session-context.sh"

package/core/harnesses/gemini/settings/adapter-defaults.json

@@ -0,0 +1,4 @@
+{
+  "mcpKey": "mcpServers",
+  "extensionInstall": "native-host-workflow"
+}