@moretea-labs/forge 1.5.0-rc.1

package/assets/hooks/post-bash.sh

@@ -0,0 +1,215 @@
+#!/bin/bash
+# Post-Bash Hook — PostToolUse on Bash
+# Reminds to rewrite (not patch) when tests fail.
+
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/workflow-state.sh"
+
+post_bash_set_tool_output_from_stdin() {
+  local parsed tmp
+
+  hook_read_stdin_once
+  [[ -n "${HOOK_STDIN_JSON:-}" ]] || return 1
+
+  if command -v jq >/dev/null 2>&1; then
+    if printf '%s' "$HOOK_STDIN_JSON" | jq -e 'has("tool_output") and .tool_output != null' >/dev/null 2>&1; then
+      IFS= read -r -d '' parsed < <(printf '%s' "$HOOK_STDIN_JSON" | jq -j '.tool_output' 2>/dev/null; printf '\0')
+      TOOL_OUTPUT="$parsed"
+      return 0
+    fi
+  fi
+
+  command -v bun >/dev/null 2>&1 || return 1
+  tmp="$(mktemp "${TMPDIR:-/tmp}/post-bash-tool-output.XXXXXX")" || return 1
+  if JSON_INPUT="$HOOK_STDIN_JSON" bun -e '
+    const raw = process.env.JSON_INPUT ?? "";
+    const value = JSON.parse(raw).tool_output;
+    if (value == null) process.exit(1);
+    if (typeof value === "object") process.stdout.write(JSON.stringify(value));
+    else process.stdout.write(String(value));
+  ' > "$tmp" 2>/dev/null; then
+    IFS= read -r -d '' parsed < <(cat "$tmp"; printf '\0')
+    TOOL_OUTPUT="$parsed"
+    rm -f "$tmp"
+    return 0
+  fi
+  rm -f "$tmp"
+  return 1
+}
+
+TOOL_OUTPUT="${1:-${TOOL_OUTPUT:-}}"
+EXIT_CODE="${2:-${EXIT_CODE:-}}"
+COMMAND_TEXT="$(hook_json_get '.tool_input.command' '')"
+
+if [[ -z "$TOOL_OUTPUT" ]]; then
+  post_bash_set_tool_output_from_stdin || TOOL_OUTPUT="$(hook_json_get '.tool_output' '')"
+fi
+if [[ -z "$EXIT_CODE" ]]; then
+  EXIT_CODE="$(hook_json_get '.exit_code' '')"
+fi
+
+post_bash_output_line_count() {
+  local output="$1"
+  if [[ -z "$output" ]]; then
+    printf '0'
+    return
+  fi
+  printf '%s' "$output" | awk 'END { print NR }'
+}
+
+post_bash_output_byte_count() {
+  local output="$1"
+  printf '%s' "$output" | wc -c | tr -d '[:space:]'
+}
+
+post_bash_sha256() {
+  local output="$1"
+  if command -v shasum >/dev/null 2>&1; then
+    printf '%s' "$output" | shasum -a 256 | awk '{ print $1 }'
+    return
+  fi
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$output" | sha256sum | awk '{ print $1 }'
+    return
+  fi
+  printf ''
+}
+
+post_bash_failure_signal() {
+  local output="$1"
+  [[ -n "$output" ]] || return 1
+  printf '%s\n' "$output" | grep -qEi "(^|[[:space:]])(FAIL|FAILED|failed)([[:space:]:,]|$)|Traceback|panic:|fatal:|error.*test"
+}
+
+post_bash_exit_failed() {
+  local exit_code="$1"
+  [[ -n "$exit_code" && "$exit_code" != "0" ]]
+}
+
+post_bash_broad_command() {
+  local command_text="$1"
+  local trimmed
+  trimmed="$(printf '%s' "$command_text" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
+
+  [[ -n "$trimmed" ]] || return 1
+
+  if printf '%s\n' "$trimmed" | grep -qE '(^|[;&|][[:space:]]*)find[[:space:]]+\./?([[:space:]]|$)'; then
+    return 0
+  fi
+  if printf '%s\n' "$trimmed" | grep -qE '(^|[;&|][[:space:]]*)ls[[:space:]]+-[^;&|]*R'; then
+    return 0
+  fi
+  if printf '%s\n' "$trimmed" | grep -qE '^[[:space:]]*rg([[:space:]]+-[-A-Za-z0-9_=]+)*[[:space:]]+[^[:space:]]+[[:space:]]*$'; then
+    return 0
+  fi
+  if printf '%s\n' "$trimmed" | grep -qE '^[[:space:]]*grep[[:space:]]+-[A-Za-z]*[Rr][A-Za-z]*([[:space:]]+-[-A-Za-z0-9_=]+)*[[:space:]]+[^[:space:]]+[[:space:]]*$'; then
+    return 0
+  fi
+  if printf '%s\n' "$trimmed" | grep -qE '(^|[;&|][[:space:]]*)cat[[:space:]]+([^;&|]*[*?][^;&|]*|\.(/)?([[:space:]]|$)|[^;&|]*[[:space:]][^;&|]*[[:space:]][^;&|]*)'; then
+    return 0
+  fi
+
+  return 1
+}
+
+broad_command=false
+recommended_next_tool=""
+if post_bash_broad_command "$COMMAND_TEXT"; then
+  broad_command=true
+  recommended_next_tool="codegraph_context"
+fi
+output_line_count="$(post_bash_output_line_count "$TOOL_OUTPUT")"
+raw_output_bytes="$(post_bash_output_byte_count "$TOOL_OUTPUT")"
+failure_signal=false
+if post_bash_failure_signal "$TOOL_OUTPUT"; then
+  failure_signal=true
+fi
+rtk_available=false
+if command -v rtk >/dev/null 2>&1; then
+  rtk_available=true
+fi
+
+LONG_OUTPUT_LINES=200
+LONG_OUTPUT_BYTES=32768
+verbosity_class="inline"
+suggested_runner="inline"
+raw_output_path=""
+raw_output_sha256=""
+
+if post_bash_exit_failed "$EXIT_CODE"; then
+  verbosity_class="failure"
+  suggested_runner="raw"
+elif (( output_line_count >= LONG_OUTPUT_LINES || raw_output_bytes >= LONG_OUTPUT_BYTES )); then
+  verbosity_class="long"
+  if [[ "$broad_command" == "true" && "$rtk_available" == "true" ]]; then
+    suggested_runner="rtk"
+  else
+    suggested_runner="raw"
+  fi
+fi
+
+if [[ "$verbosity_class" != "inline" ]]; then
+  output_dir="$(workflow_runs_dir)/bash-output"
+  mkdir -p "$output_dir"
+  raw_output_sha256="$(post_bash_sha256 "$TOOL_OUTPUT")"
+  raw_output_path="${output_dir}/post-bash-$(date '+%Y%m%dT%H%M%S')-$$-${raw_output_sha256:0:12}.log"
+  printf '%s' "$TOOL_OUTPUT" > "$raw_output_path"
+fi
+
+if [[ "$EXIT_CODE" != "0" ]]; then
+  if [[ "$failure_signal" == "true" ]]; then
+    echo "[PostBash] Tests failed. Reminder: failure = rewrite module, not patching."
+  fi
+fi
+
+checks_file="$(workflow_checks_file)"
+post_bash_checks_file="$(dirname "$checks_file")/post-bash-latest.json"
+target_checks_file="$post_bash_checks_file"
+
+mkdir -p "$(dirname "$target_checks_file")"
+if [[ -n "$raw_output_path" ]]; then
+  raw_output_path_json="\"$(hook_json_escape "$raw_output_path")\""
+else
+  raw_output_path_json="null"
+fi
+if [[ -n "$raw_output_sha256" ]]; then
+  raw_output_sha256_json="\"$(hook_json_escape "$raw_output_sha256")\""
+else
+  raw_output_sha256_json="null"
+fi
+cat > "$target_checks_file" <<EOF_CHECKS
+{
+  "source": "post-bash",
+  "command": "$(hook_json_escape "$COMMAND_TEXT")",
+  "exit_code": ${EXIT_CODE:-0},
+  "status": "$([[ "${EXIT_CODE:-0}" = "0" ]] && echo pass || echo fail)",
+  "broad_command": ${broad_command},
+  "output_line_count": ${output_line_count:-0},
+  "verbosity_class": "$(hook_json_escape "$verbosity_class")",
+  "suggested_runner": "$(hook_json_escape "$suggested_runner")",
+  "raw_output_path": ${raw_output_path_json},
+  "raw_output_bytes": ${raw_output_bytes:-0},
+  "raw_output_sha256": ${raw_output_sha256_json},
+  "failure_signal": ${failure_signal},
+  "rtk_available": ${rtk_available},
+  "recommended_next_tool": "$(hook_json_escape "$recommended_next_tool")",
+  "generated_at": "$(date '+%Y-%m-%dT%H:%M:%S%z')"
+}
+EOF_CHECKS
+
+if [[ -f "$checks_file" ]]; then
+  echo "[ChecksFile] Preserved ${checks_file}; updated ${target_checks_file}."
+else
+  echo "[ChecksFile] Updated ${target_checks_file}; ${checks_file} remains reserved for forge-run-trace.v1."
+fi
+
+# Aggregated advisory (route-registry keeps one PostToolUse bash entry; the
+# dispatcher-level aggregation lives here). Only speaks on release commands.
+if [[ -x "$SCRIPT_DIR/changelog-guard.sh" ]]; then
+  TOOL_COMMAND="$COMMAND_TEXT" bash "$SCRIPT_DIR/changelog-guard.sh" </dev/null || true
+fi

package/assets/hooks/post-edit-guard.sh

@@ -0,0 +1,256 @@
+#!/bin/bash
+# Post-Edit Guard — PostToolUse on Edit|Write
+# Combines doc-drift reminders, continuous contract verification, and task handoff generation.
+
+set -euo pipefail
+export LC_ALL=C
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/workflow-state.sh"
+
+run_continuous_contract_verification() {
+  local active_plan contract_file checks_file
+
+  [[ -f "scripts/verify-contract.sh" ]] || return 0
+
+  active_plan="$(get_active_plan || true)"
+  [[ -n "$active_plan" && -f "$active_plan" ]] || return 0
+
+  contract_file="$(derive_contract_path "$active_plan" || true)"
+  [[ -n "$contract_file" && -f "$contract_file" ]] || return 0
+  checks_file="$(workflow_checks_file)"
+  mkdir -p "$(dirname "$checks_file")"
+
+  if contract_references_path "$contract_file" "$FILE_PATH"; then
+    bash "scripts/verify-contract.sh" --contract "$contract_file" --quiet --report-file "$checks_file" || true
+  fi
+}
+
+run_architecture_queue_sync() {
+  local queue_output status
+
+  [[ -x "scripts/architecture-queue.sh" ]] || return 0
+
+  if queue_output="$(bash "scripts/architecture-queue.sh" record --file "$FILE_PATH" 2>&1)"; then
+    :
+  else
+    status=$?
+    [[ -n "$queue_output" ]] && printf '%s\n' "$queue_output"
+    echo "[SyncChain] WARN: architecture-queue failed for $FILE_PATH (exit $status)"
+    return 0
+  fi
+  [[ -n "$queue_output" ]] && printf '%s\n' "$queue_output"
+
+  if printf '%s\n' "$queue_output" | grep -q '^\[ArchitectureDrift\] Request:'; then
+    if [[ -x "scripts/context-contract-sync.sh" ]]; then
+      if bash "scripts/context-contract-sync.sh" sync-latest; then
+        :
+      else
+        status=$?
+        echo "[SyncChain] WARN: context-contract-sync failed after $FILE_PATH (exit $status)"
+      fi
+    fi
+    if [[ -n "${FORGE_CLI:-}" && -f "$FORGE_CLI" ]] && command -v bun >/dev/null 2>&1; then
+      if bun "$FORGE_CLI" capability-context request --from-latest-architecture-event; then
+        :
+      else
+        status=$?
+        echo "[SyncChain] WARN: capability-context request failed after $FILE_PATH (exit $status)"
+      fi
+    elif command -v forge >/dev/null 2>&1; then
+      if forge capability-context request --from-latest-architecture-event; then
+        :
+      else
+        status=$?
+        echo "[SyncChain] WARN: capability-context request failed after $FILE_PATH (exit $status)"
+      fi
+    elif command -v bun >/dev/null 2>&1 && [[ -f "src/cli/index.ts" ]]; then
+      if bun src/cli/index.ts capability-context request --from-latest-architecture-event; then
+        :
+      else
+        status=$?
+        echo "[SyncChain] WARN: capability-context request failed after $FILE_PATH (exit $status)"
+      fi
+    fi
+  fi
+}
+
+run_brain_doc_sync() {
+  [[ -x "scripts/sync-brain-docs.sh" ]] || return 0
+  [[ -f ".ai/harness/brain-manifest.json" ]] || return 0
+
+  # Fast-path: most edits are not repo-to-brain sources. Avoid starting the JS
+  # manifest reader unless the changed repo path appears in the manifest.
+  if ! grep -Fq "\"$FILE_PATH\"" ".ai/harness/brain-manifest.json"; then
+    return 0
+  fi
+
+  if bash "scripts/sync-brain-docs.sh" --changed "$FILE_PATH"; then
+    :
+  else
+    local status=$?
+    echo "[SyncChain] WARN: brain-doc-sync failed for $FILE_PATH (exit $status)"
+  fi
+}
+
+FILE_PATH="$(hook_get_file_path "${1:-}")"
+[[ -z "$FILE_PATH" ]] && exit 0
+
+BASENAME=$(basename "$FILE_PATH")
+DIRNAME=$(dirname "$FILE_PATH")
+
+if [[ "$FILE_PATH" == deploy/* ]]; then
+  echo "[DeployAsset] Deployment operations asset changed: $FILE_PATH"
+  echo "  Confirm secrets, real env files, provider state, artifacts, logs, and scratch files remain in ignored _ops/ before committing."
+  echo "  Keep deployment SQL directly under deploy/sql/ with 4-digit ascending prefixes."
+fi
+
+if [[ "$BASENAME" == "package.json" && "$DIRNAME" =~ (^|/)packages/([^/]+) ]]; then
+  PKG_NAME="packages/${BASH_REMATCH[2]}"
+  if [[ -n "$PKG_NAME" ]]; then
+    echo "[DocDrift] $PKG_NAME/package.json changed"
+    echo "  Check: docs/packages.md exports table may need updating"
+  fi
+fi
+
+if [[ "$FILE_PATH" =~ (^|/)packages/([^/]+)/src/([^/]+)/index\.ts$ ]]; then
+  PKG="${BASH_REMATCH[2]}"
+  MODULE="${BASH_REMATCH[3]}"
+  echo "[DocDrift] New module '$MODULE' in $PKG"
+  echo "  Check: docs/packages.md and docs/architecture.md may need updating"
+fi
+
+if [[ "$FILE_PATH" =~ (^|/)apps/[^/]+/src/.+ ]]; then
+  echo "[DocDrift] App source changed: $FILE_PATH"
+  echo "  Check: docs/architecture.md source tree may need updating"
+fi
+
+if [[ "$BASENAME" == "metro.config.js" ]] || [[ "$BASENAME" == "metro.config.ts" ]]; then
+  echo "[DocDrift] Metro config changed"
+  echo "  Check: docs/guides/metro-esm-gotchas.md may need updating"
+fi
+
+if [[ "$BASENAME" == "tsconfig.json" && "$DIRNAME" =~ (^|/)(packages|apps)/ ]]; then
+  echo "[DocDrift] TypeScript config changed in $(basename "$DIRNAME")"
+  echo "  Check: docs/packages.md may need updating"
+fi
+
+if [[ "$BASENAME" == "turbo.json" ]]; then
+  echo "[DocDrift] Turborepo config changed"
+  echo "  Check: docs/architecture.md pipeline section may need updating"
+fi
+
+if [[ "$BASENAME" =~ ^wrangler.*\.toml$ ]]; then
+  echo "[DocDrift] Wrangler config changed: $BASENAME"
+  echo "  Check: docs/guides/cf-deployment.md bindings/routes may need updating"
+fi
+
+# Aggregated advisories (route-registry keeps one PostToolUse edit entry; the
+# dispatcher-level aggregation lives here).
+if [[ -f "$SCRIPT_DIR/first-principles-guard.sh" ]]; then
+  bash "$SCRIPT_DIR/first-principles-guard.sh" "$FILE_PATH" </dev/null || true
+elif [[ -f "$SCRIPT_DIR/anti-simplification.sh" ]]; then
+  bash "$SCRIPT_DIR/anti-simplification.sh" "$FILE_PATH" </dev/null || true
+fi
+
+run_architecture_queue_sync
+
+run_brain_doc_sync
+
+run_continuous_contract_verification
+
+case "$FILE_PATH" in
+  tasks/todos.md|plans/*.md|tasks/reviews/*.review.md|.ai/harness/checks/latest.json)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+active_plan="$(get_active_plan || true)"
+if [[ "$FILE_PATH" == "tasks/todos.md" && -z "$active_plan" ]] && grep -Eq '^> \*\*Status\*\*:[[:space:]]*Backlog[[:space:]]*$' tasks/todos.md; then
+  rm -f "$(workflow_task_state_file)" ".claude/.task-handoff.md"
+  echo "[TaskHandoff] Deferred-goal ledger updated; active execution remains in the plan Task Breakdown."
+  exit 0
+fi
+
+mkdir -p .claude
+
+STATE_FILE="$(workflow_task_state_file)"
+HANDOFF_FILE=".claude/.task-handoff.md"
+
+if [[ "$FILE_PATH" == "tasks/todos.md" ]] && [[ -f "tasks/todos.md" ]] && ! grep -Eq '^> \*\*Status\*\*:[[:space:]]*Backlog[[:space:]]*$' tasks/todos.md; then
+  workflow_sync_task_state_from_todo "tasks/todos.md" "$STATE_FILE"
+fi
+
+task_state="$(workflow_plan_task_state "$active_plan")"
+IFS=$'\t' read -r total_tasks done_tasks next_pending <<< "$task_state"
+done_tasks="${done_tasks:-0}"
+total_tasks="${total_tasks:-0}"
+next_pending="${next_pending:-"(none)"}"
+
+next_action="$(workflow_next_action)"
+next_stage="$(printf '%s\n' "$next_action" | cut -f1)"
+next_command="$(printf '%s\n' "$next_action" | cut -f2)"
+next_message="$(printf '%s\n' "$next_action" | cut -f3-)"
+[[ "${next_command:-}" == "-" ]] && next_command=""
+next_stage="${next_stage:-none}"
+next_message="${next_message:-(none)}"
+
+diff_stat="$(git diff --shortstat HEAD 2>/dev/null | tr -d '\n')"
+diff_stat="${diff_stat:-no uncommitted diff against HEAD}"
+
+if [[ -z "$active_plan" ]]; then
+  active_plan="(none)"
+fi
+
+plan_status="(unknown)"
+if [[ "$active_plan" != "(none)" && -f "$active_plan" ]]; then
+  plan_status="$(awk '/^\> \*\*Status\*\*:/ {sub(/^.*\> \*\*Status\*\*: */, ""); gsub(/\r/, ""); print; exit}' "$active_plan" | xargs)"
+  plan_status="${plan_status:-(unknown)}"
+fi
+
+changed_files="$(git diff --name-only HEAD 2>/dev/null | head -10)"
+changed_files="${changed_files:-(none)}"
+
+cat > "$HANDOFF_FILE" <<EOF_HANDOFF
+# Task Handoff Summary
+
+> **Generated**: $(date '+%Y-%m-%d %H:%M:%S')
+> **Progress**: ${done_tasks}/${total_tasks}
+> **Active Plan**: ${active_plan}
+
+## Plan Status
+
+- ${plan_status}
+
+## Current Task
+
+- ${next_pending}
+
+## Next Actions
+
+- Stage: ${next_stage}
+- Action: ${next_message}
+- Command: ${next_command:-(none)}
+
+## Key Artifacts
+
+\`\`\`
+${changed_files}
+\`\`\`
+
+## Working Tree Snapshot
+
+- ${diff_stat}
+EOF_HANDOFF
+
+echo "[TaskHandoff] Workflow next action is ${next_stage}. Wrote ${HANDOFF_FILE}."
+
+workflow_write_handoff "task-progress" || true
+if [[ -f "$(workflow_handoff_file)" ]]; then
+  echo "[HarnessHandoff] Refreshed $(workflow_handoff_file)."
+fi

package/assets/hooks/post-tool-observer.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Post-Tool Observer — PostToolUse (all tools)
+# Single pass per tool call: JSONL trace logging plus lightweight advisories.
+# Replaces the former split observers so the always-route costs one dispatch,
+# one stdin parse, and one library load instead of two.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/session-state.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/workflow-state.sh"
+
+mkdir -p .claude
+
+TRACE_FILE="$(workflow_trace_file)"
+SESSION_ID_FILE=".claude/.session-id"
+
+SESSION_KEY="$(session_state_resolve_key "$SESSION_ID_FILE" "${1:-}")"
+
+# --- Trace logging ---
+
+event_type="$(hook_json_get '.hook_event_name' 'PostToolUse')"
+tool_name="$(hook_get_tool_name "${1:-}")"
+file_path="$(hook_get_file_path "${1:-}")"
+exit_code="$(hook_get_exit_code "${1:-}")"
+duration_ms="$(hook_get_duration_ms "${1:-}")"
+run_id="$(hook_get_run_id "${1:-}")"
+agent_name="${CLAUDE_AGENT_NAME:-${CODEX_AGENT_NAME:-${HOOK_AGENT_NAME:-unknown}}}"
+session_source="$(hook_get_session_source "${1:-}")"
+session_source="${session_source:-${CODEX_SESSION_SOURCE:-}}"
+host="unknown"
+
+tool_name="${tool_name:-unknown}"
+file_path="${file_path:-}"
+exit_code="${exit_code:-0}"
+duration_ms="${duration_ms:-0}"
+run_id="${run_id:-unknown}"
+session_source="${session_source:-unknown}"
+
+case "$tool_name" in
+  mcp__codegraph__*|codegraph_*)
+    session_state_mark_codegraph_used "$SESSION_KEY" || true
+    ;;
+esac
+
+if [[ -n "${CODEX_SESSION_ID:-${CODEX_AGENT_NAME:-}}" ]] || [[ "$session_source" =~ [Cc]odex ]]; then
+  host="codex"
+elif [[ -n "${CLAUDE_SESSION_ID:-${CLAUDE_AGENT_NAME:-}}" ]] || [[ "$session_source" =~ [Cc]laude ]]; then
+  host="claude"
+fi
+
+# Rotate trace log when it exceeds MAX_TRACE_LINES
+MAX_TRACE_LINES=10000
+KEEP_TRACE_LINES=5000
+if [[ -f "$TRACE_FILE" ]]; then
+  line_count="$(wc -l < "$TRACE_FILE" | tr -d ' ')"
+  if [[ "$line_count" -gt "$MAX_TRACE_LINES" ]]; then
+    tmp_trace="$(mktemp)"
+    tail -n "$KEEP_TRACE_LINES" "$TRACE_FILE" > "$tmp_trace"
+    mv "$tmp_trace" "$TRACE_FILE"
+  fi
+fi
+
+# The trace file is the single tool-trace record; handoff "Commands Run"
+# reads it directly instead of a duplicate events.jsonl append per call.
+printf '{"ts":"%s","event_type":"%s","tool_name":"%s","file_path":"%s","exit_code":%s,"duration_ms":%s,"session_key":"%s","run_id":"%s","host":"%s","agent_name":"%s","session_source":"%s"}\n' \
+  "$(hook_json_escape "$(date '+%Y-%m-%dT%H:%M:%S%z')")" \
+  "$(hook_json_escape "$event_type")" \
+  "$(hook_json_escape "$tool_name")" \
+  "$(hook_json_escape "$file_path")" \
+  "$exit_code" \
+  "$duration_ms" \
+  "$(hook_json_escape "$SESSION_KEY")" \
+  "$(hook_json_escape "$run_id")" \
+  "$(hook_json_escape "$host")" \
+  "$(hook_json_escape "$agent_name")" \
+  "$(hook_json_escape "$session_source")" \
+  >> "$TRACE_FILE"
+
+# --- Codex plan-change advisory ---
+
+emit_codex_plan_change_guard() {
+  local changed_plan
+
+  if [[ "$tool_name" != "apply_patch" ]]; then
+    return 0
+  fi
+
+  changed_plan="$(has_changes_glob '^plans/plan-.*\.md$' || true)"
+  if [[ -n "$changed_plan" ]]; then
+    echo "[AnnotationGuard] ${changed_plan} has annotations. Process all notes and revise. Do not implement yet."
+  fi
+}
+
+emit_codex_plan_change_guard