coding-os 0.3.2__py3-none-any.whl

core/hooks/block-protected-files.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# PreToolUse hook: Block direct edits to protected files.
+# Protected:
+#   - changes.log (use make log-write)
+#   - Governance files: agent rules/, hooks/, CLAUDE.md, AGENTS.md,
+#     infrastructure/scripts/ — never edit as side-effect of another task.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+# Fail-closed: a protected-file gate that cannot read the path must DENY,
+# not silently allow when jq is absent (observability-eye I8).
+cos_require_parser block-protected-files
+
+INPUT="$(cos_read_stdin_bounded 2)"
+FILE_PATH=$(printf '%s' "$INPUT" | cos_json_field tool_input.file_path)
+
+# Block direct edits to changes.log
+if [[ "$FILE_PATH" == *"changes.log"* ]]; then
+  echo "BLOCKED: Do not edit changes.log directly. Use 'make log-write TYPE=<type> MSG=\"title\" WHAT=\"impact\" FILES=\"files\"'." >&2
+  exit 2
+fi
+
+# Scrumban task status changes go through `cos task-move` / `cos task-done`,
+# never a hand-edit of a task file — validate-task-frontmatter.sh guards that.
+
+# Block edits to governance/workflow files unless explicitly tasked.
+# These define HOW we work — changing them as a side-effect of another task
+# can silently break workflow for all future sessions.
+#
+# Exception: paths inside templates/.../scaffold/ are SCAFFOLD TEMPLATES, not
+# runtime state. They need to be writable so coding-os itself can ship updates
+# to the scaffold (e.g. adding rag-config.yaml under .coding-os/ scaffold).
+# BUT: scaffold/docs/governance/ is the canonical home of governance docs
+# that propagate to every future consumer project require the
+# same template-update / governance / docs-update keyword guard the
+# meta-repo's own governance dir uses. Other scaffold paths still pass.
+if [[ "$FILE_PATH" == *"/scaffold/docs/governance/"* ]]; then
+  AGENT_DIR="${COS_AGENT_DIR:-${COS_STATE_DIR:-.coding-os}/${COS_AGENT:-unknown}}"
+  # Panel-aware lookup — task marker lives in $COS_PANEL_DIR
+  # since the per-panel split. Falls through cleanly when COS_PANEL_DIR
+  # is unset (older hook caller).
+  TASK_FILE="${COS_PANEL_DIR:-$AGENT_DIR}/.task-current"
+  TASK_NAME=""
+  if [ -f "$TASK_FILE" ]; then
+    TASK_VALUE=$(cat "$TASK_FILE" 2>/dev/null)
+    # Strip ONLY the leading session-id token; keep the rest of the value.
+    # `##* ` would drop everything but the LAST word, so a multi-word marker
+    # (`<sid> docs-update TASK-NNN align-docs`) lost the governance keyword.
+    TASK_NAME="${TASK_VALUE#* }"
+  fi
+  case "$TASK_NAME" in
+    *template-update*|*docs-update*|*docs-sync*|*governance*|*claude-md-update*|*agents-md-update*)
+      exit 0
+      ;;
+    *)
+      echo "BLOCKED: Edits to src/templates/_base/scaffold/docs/governance/ propagate to every future consumer project. Open a task whose title includes one of: template-update, docs-update, governance. Active task: '${TASK_NAME:-none}'." >&2
+      exit 2
+      ;;
+  esac
+fi
+if [[ "$FILE_PATH" == *"/scaffold/"* ]]; then
+  exit 0
+fi
+
+# Data-driven adapter state protection: every adapter declares a state
+# dir (e.g. `.claude/`, `.codex/`) — we block edits under any
+# of them.  Discovery order:
+#   1. src/adapters/<id>/adapter.yaml (source of truth in the meta-repo)
+#   2. legacy hardcoded safety-net for meta-project setups that pre-date
+#      the registry (cannot regress; this list is additive).
+ADAPTER_ROOT="$(cd "$(dirname "$0")/../.." 2>/dev/null && pwd)/adapters"
+ADAPTER_STATE_GLOB=""
+if [ -d "$ADAPTER_ROOT" ]; then
+  for adir in "$ADAPTER_ROOT"/*/; do
+    [ -d "$adir" ] || continue
+    aid=$(basename "$adir")
+    ADAPTER_STATE_GLOB="${ADAPTER_STATE_GLOB}|.${aid}/rules/|.${aid}/hooks/|.${aid}/skills/"
+  done
+fi
+ADAPTER_STATE_GLOB="${ADAPTER_STATE_GLOB}|.claude/rules/|.claude/hooks/|.codex/hooks/"
+
+matched_adapter_path=0
+IFS='|' read -r -a _glob_parts <<< "$ADAPTER_STATE_GLOB"
+for _g in "${_glob_parts[@]}"; do
+  [ -z "$_g" ] && continue
+  if [[ "$FILE_PATH" == *"$_g"* ]]; then
+    matched_adapter_path=1
+    break
+  fi
+done
+
+# Protect the src/core/ skill+rule SOURCE too: it propagates to every consumer
+# via live symlinks, so it needs the same guard as its rendered .claude/ copies.
+if [[ "$matched_adapter_path" -eq 1 ]] || \
+   [[ "$FILE_PATH" == *".coding-os/"* ]] || \
+   [[ "$FILE_PATH" == *"/CLAUDE.md" ]] || \
+   [[ "$FILE_PATH" == *"/AGENTS.md" ]] || \
+   [[ "$FILE_PATH" == *"src/core/skills/"* ]] || \
+   [[ "$FILE_PATH" == *"src/core/rules/"* ]] || \
+   [[ "$FILE_PATH" == *"infrastructure/scripts/"* ]]; then
+  # Escape hatch: if the active task explicitly names governance work,
+  # allow the edit. This prevents genuine docs/governance tasks from
+  # being blocked by the safety net. The active task marker is session-
+  # scoped and set via `cos task-start` or write-state.sh.
+  # Task marker lives in the panel-private state dir (COS_PANEL_DIR per
+  # ); fall back to agent dir only when cos-env.sh hasn't been
+  # sourced. Falls through cleanly during the transition window.
+  AGENT_DIR="${COS_AGENT_DIR:-${COS_STATE_DIR:-.coding-os}/${COS_AGENT:-unknown}}"
+  TASK_FILE="${COS_PANEL_DIR:-$AGENT_DIR}/.task-current"
+  if [ -f "$TASK_FILE" ]; then
+    TASK_VALUE=$(cat "$TASK_FILE" 2>/dev/null)
+    # The task marker is "session-id value" — extract the value
+    # Strip ONLY the leading session-id token; keep the rest of the value.
+    # `##* ` would drop everything but the LAST word, so a multi-word marker
+    # (`<sid> docs-update TASK-NNN align-docs`) lost the governance keyword.
+    TASK_NAME="${TASK_VALUE#* }"
+    # Allow when the task name clearly signals governance/docs work.
+    case "$TASK_NAME" in
+      *docs-update*|*docs-sync*|*governance*|*claude-md-update*|*agents-md-update*)
+        exit 0
+        ;;
+    esac
+  fi
+  echo "BLOCKED: Governance/workflow file detected. Do not edit agent config dirs, src/core/skills/ or src/core/rules/ sources, CLAUDE.md, AGENTS.md, or infrastructure/scripts/ as a side-effect of another task. Create a dedicated task whose title includes governance or docs-update, e.g. write-state.sh ${COS_PANEL_DIR:-$AGENT_DIR}/.task-current 'docs-update-...'" >&2
+  exit 2
+fi
+
+exit 0

core/hooks/block-secrets.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# PreToolUse hook: Block commits/writes containing hardcoded secrets or sensitive files.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+# Fail-closed: a secret-scanning gate that cannot read its input must DENY,
+# not silently allow (observability-eye I8). cos_json_field falls back to
+# python3 when only jq is missing, so the gate keeps working.
+cos_require_parser block-secrets
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Fast-path: this gate fires on EVERY Bash command. The Bash leg only ever
+# blocks `git add` of a secret file, a hook-skipping `git commit`
+# (--no-verify/-n), or a `core.hooksPath` override; if the raw payload mentions
+# none AND is not a Write/Edit (whose content we must scan), there is nothing to
+# deny — bail before any jq spawn. The hooksPath token is matched in its two
+# realistic casings (the deep grep below is case-insensitive). Write/Edit
+# payloads always carry "new_string"/"content", so they never match here.
+case "$INPUT" in
+  *"git add"*|*git*commit*|*hooksPath*|*hookspath*|*new_string*|*'"content"'*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+
+# For Bash tool: block git add of sensitive files
+if [[ "$TOOL" == "Bash" ]]; then
+  cos_log_hook block-secrets fire "tool=Bash"
+  COMMAND=$(printf '%s' "$INPUT" | cos_json_field tool_input.command)
+
+  # Block git add of .env files (but allow .env.example, .env.template)
+  if echo "$COMMAND" | grep -qE 'git add.*\.env($|\s)' || echo "$COMMAND" | grep -qE 'git add\s+\.env$'; then
+    cos_log_hook block-secrets block "tool=Bash rule=env-file"
+    echo "BLOCKED: .env files must not be committed to git. Use .env.example for structure." >&2
+    exit 2
+  fi
+
+  # Block git add of credential/key files
+  if echo "$COMMAND" | grep -qE 'git add.*(credentials\.json|service-account\.json|\.pem\b|id_rsa|\.key\b)'; then
+    cos_log_hook block-secrets block "tool=Bash rule=credential-file"
+    echo "BLOCKED: Credential/key files must not be committed. Store secrets in environment variables." >&2
+    exit 2
+  fi
+
+  # Block any git-commit that skips the verify hooks (--no-verify / -n /
+  # core.hooksPath / GIT_CONFIG_* injection). Delegated to a shlex-tokenizing
+  # helper: the old bash regex ran over a quote-STRIPPED string, so a spliced
+  # `--no-ver"i"fy`, a quoted `"-n"`, or a `GIT_CONFIG_*` env prefix vanished
+  # from the scan yet bash still executed it (TASK-567). `_cos_helpers_dir`
+  # (cos-env.sh) resolves the physical `_helpers/` through the .claude/ symlink.
+  BYPASS_HELPER="$(_cos_helpers_dir)/check_git_bypass.py"
+  BYPASS_VERDICT=$(printf '%s' "$INPUT" | python3 "$BYPASS_HELPER" 2>/dev/null || echo error)
+  # Fail-closed but SCOPED: a helper crash blocks only when the raw command
+  # actually carries a commit/hooksPath/GIT_CONFIG token we could not verify.
+  if [ "$BYPASS_VERDICT" = "error" ]; then
+    case "$COMMAND" in
+      *commit*|*hooksPath*|*hookspath*|*GIT_CONFIG*) BYPASS_VERDICT='{"verdict":"block"}' ;;
+      *) BYPASS_VERDICT='{"verdict":"allow"}' ;;
+    esac
+  fi
+  if printf '%s' "$BYPASS_VERDICT" | grep -qE '"verdict": *"block"'; then
+    cos_log_hook block-secrets block "tool=Bash rule=no-verify"
+    _bs_msg=$(printf '%s' "$BYPASS_VERDICT" | cos_json_field message 2>/dev/null || echo "")
+    echo "${_bs_msg:-BLOCKED: skipping git verify hooks (--no-verify / -n / core.hooksPath). Fix the underlying issue, do not bypass.}" >&2
+    exit 2
+  fi
+fi
+
+# For Write/Edit tool: block writing secrets patterns
+if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" ]]; then
+  FILE_PATH=$(printf '%s' "$INPUT" | cos_json_field tool_input.file_path)
+  CONTENT=$(printf '%s' "$INPUT" | cos_json_field tool_input.new_string tool_input.content)
+  FILE_BASENAME="$(basename "$FILE_PATH" 2>/dev/null || echo "")"
+
+  # Skip docs + genuine test/mock files. Match path SEGMENTS / basenames, not
+  # bare substrings — `*test*` used to skip ANY path containing "test"
+  # (latest/, contest/), silently disabling secret scanning there.
+  case "$FILE_PATH" in
+    *.env.example*|*.md|*.markdown) exit 0 ;;
+    */tests/*|*/test/*|*/__tests__/*|*/__mocks__/*|*/mocks/*|*/fixtures/*) exit 0 ;;
+  esac
+  case "$FILE_BASENAME" in
+    test_*|*_test.*|*.test.*|*.spec.*|mock_*|*_mock.*|conftest.py) exit 0 ;;
+  esac
+
+  # Block live Stripe keys (sk_live_, pk_live_ with real-length values)
+  if echo "$CONTENT" | grep -qE 'sk_live_[a-zA-Z0-9]{20,}'; then
+    echo "BLOCKED: Live Stripe secret key detected. Use environment variables (os.environ['STRIPE_SECRET_KEY']) instead." >&2
+    exit 2
+  fi
+
+  # Block test Stripe keys hardcoded in non-test files
+  if [[ "$FILE_PATH" != *test* ]] && [[ "$FILE_PATH" != *fixture* ]] && [[ "$FILE_PATH" != *.env* ]]; then
+    if echo "$CONTENT" | grep -qE 'sk_test_[a-zA-Z0-9]{20,}'; then
+      echo "BLOCKED: Stripe test key should be in .env, not hardcoded. Use environment variables." >&2
+      exit 2
+    fi
+  fi
+
+  # Block private keys
+  if echo "$CONTENT" | grep -qE 'BEGIN (RSA |EC |OPENSSH |DSA )?PRIVATE KEY'; then
+    echo "BLOCKED: Private key detected in file content. Store keys in environment variables or secret manager." >&2
+    exit 2
+  fi
+
+  # Block AWS credentials
+  if echo "$CONTENT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
+    echo "BLOCKED: AWS access key ID detected. Use environment variables or IAM roles." >&2
+    exit 2
+  fi
+
+  # Block generic high-entropy secrets (API keys, tokens) in Python/TS config files
+  if [[ "$FILE_PATH" == *settings* ]] || [[ "$FILE_PATH" == *config* ]] || [[ "$FILE_PATH" == *.env* ]]; then
+    if echo "$CONTENT" | grep -qE "(SECRET_KEY|API_KEY|AUTH_TOKEN|PRIVATE_KEY)\s*=\s*['\"][a-zA-Z0-9+/=]{32,}['\"]"; then
+      echo "BLOCKED: Hardcoded secret detected in config. Use os.environ.get() or environment variables." >&2
+      exit 2
+    fi
+  fi
+
+  # Block Django SECRET_KEY hardcoded.
+  # Tighten allowlist: match the file BASENAME, not the whole path, so a path
+  # containing "development" elsewhere (e.g. /var/development-team/app/settings.py)
+  # doesn't open a hole.
+  if echo "$CONTENT" | grep -qE "SECRET_KEY\s*=\s*['\"]django-insecure-"; then
+    if [[ "$FILE_BASENAME" != *development* ]] && [[ "$FILE_BASENAME" != *local* ]]; then
+      echo "BLOCKED: Insecure Django SECRET_KEY detected outside development settings. Use environment variables." >&2
+      exit 2
+    fi
+  fi
+
+  # Block Postmark server token hardcoded
+  if echo "$CONTENT" | grep -qE 'POSTMARK_SERVER_TOKEN\s*=\s*["\047][a-f0-9-]{36}["\047]'; then
+    echo "BLOCKED: Postmark server token detected. Use environment variables." >&2
+    exit 2
+  fi
+
+  # Block GitHub Personal Access Tokens (classic + fine-grained) and OAuth tokens.
+  # Format: ghp_/gho_/ghu_/ghs_/ghr_ + 36+ alnum.
+  if echo "$CONTENT" | grep -qE 'gh[pousr]_[A-Za-z0-9]{36,}'; then
+    echo "BLOCKED: GitHub token detected (ghp_/gho_/ghu_/ghs_/ghr_). Use \$GITHUB_TOKEN env var or gh auth login." >&2
+    exit 2
+  fi
+
+  # Block OpenAI / Anthropic API keys. The discriminator is the SPECIFIC prefix
+  # (sk-ant-api##- / sk-proj- / classic sk-+40 contiguous alnum) — kebab-case
+  # slugs like `sk-product-identifier-x` lack it and no longer false-fire. The
+  # ant/proj bodies still allow base64url `-`/`_` so real keys are caught.
+  if echo "$CONTENT" | grep -qE 'sk-ant-(api|admin)[0-9]{2}-[A-Za-z0-9_-]{80,}|sk-proj-[A-Za-z0-9_-]{40,}|sk-[A-Za-z0-9]{40,}'; then
+    echo "BLOCKED: OpenAI/Anthropic API key detected. Use environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY)." >&2
+    exit 2
+  fi
+
+  # Block Slack tokens (xoxb-/xoxa-/xoxp-/xoxr-/xoxs-).
+  if echo "$CONTENT" | grep -qE 'xox[abprs]-[A-Za-z0-9-]{10,}'; then
+    echo "BLOCKED: Slack token detected. Use environment variables." >&2
+    exit 2
+  fi
+
+  # Block Google API keys (AIza...).
+  if echo "$CONTENT" | grep -qE 'AIza[A-Za-z0-9_\-]{35}'; then
+    echo "BLOCKED: Google API key detected. Use environment variables." >&2
+    exit 2
+  fi
+
+  # Block JWT tokens hardcoded in source (header.payload.signature, base64url).
+  # Skip docs/examples — already filtered above. Require 3 segments with ≥10 chars each.
+  if echo "$CONTENT" | grep -qE 'eyJ[A-Za-z0-9_\-]{10,}\.eyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}'; then
+    echo "BLOCKED: JWT token detected hardcoded in source. Issue tokens at runtime; do not commit." >&2
+    exit 2
+  fi
+
+  # Block basic-auth credentials embedded in URLs (http(s)://user:password@host).
+  # Only block when the password segment has real entropy (≥6 chars, not just "user:pass" placeholder).
+  if echo "$CONTENT" | grep -qE 'https?://[A-Za-z0-9._-]+:[^@[:space:]/"\047]{6,}@[A-Za-z0-9.-]+'; then
+    if ! echo "$CONTENT" | grep -qE 'https?://(user|username|admin|root|test|example|foo):(password|pass|secret|test|example|foo|changeme)@'; then
+      echo "BLOCKED: Basic-auth credentials embedded in URL. Use env vars or a secret manager, never inline in URLs." >&2
+      exit 2
+    fi
+  fi
+fi
+
+exit 0

core/hooks/block-shared-tree-edit.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# block-shared-tree-edit.sh — pr-mode edit isolation (companion to branch-guard).
+#
+# In COS_GIT_WORKFLOW=pr, a Write/Edit on a file inside the SHARED integration
+# checkout (the main repo, not a worktree) is BLOCKED so every code change is
+# isolated in a worktree — even work the user said not to make a board task for
+# (`cos pr open --adhoc`). Inert in trunk mode (the default), so coding-os and
+# every trunk consumer pay one env check and exit. Files inside a worktree, and
+# files outside the repo entirely (scratch, dotfiles), pass.
+# SPEC: docs/playbooks/pr-workflow.md § 5/§6.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+# Inert unless pr-mode — the common case, kept to a single comparison.
+[[ "${COS_GIT_WORKFLOW:-trunk}" == "pr" ]] || exit 0
+
+cos_require_parser block-shared-tree-edit
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+case "$TOOL" in
+  Write | Edit | MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | cos_json_field tool_input.file_path)
+[[ -z "$FILE" ]] && exit 0
+
+# Block only files inside the shared integration checkout = the main repo root
+# (parent of COS_STATE_DIR). Edits elsewhere (scratch, ~/.config) pass through.
+REPO_ROOT="$(cd -P "$(dirname "${COS_STATE_DIR}")" 2>/dev/null && pwd -P)" || REPO_ROOT=""
+[[ -z "$REPO_ROOT" || "$REPO_ROOT" == "." ]] && exit 0
+
+FILE_ABS="$FILE"
+case "$FILE" in
+  /*) ;;
+  *) FILE_ABS="$(pwd)/$FILE" ;;
+esac
+# Resolve symlinks AND `..` in the parent path so the worktree / REPO_ROOT
+# classification below tests the REAL path (Rule 5: /tmp ↔ /private/tmp). The
+# file may not exist yet (new file), so resolve its dirname, not the file itself.
+FILE_DIR="$(cd -P "$(dirname "$FILE_ABS")" 2>/dev/null && pwd -P)" || FILE_DIR=""
+if [[ -n "$FILE_DIR" ]]; then
+  FILE_ABS="$FILE_DIR/$(basename "$FILE_ABS")"
+elif command -v python3 >/dev/null 2>&1; then
+  # Parent dir doesn't exist yet (new nested file): collapse `..` lexically via
+  # os.path.realpath so a `..`-spoof can't keep a literal worktrees/ segment and
+  # slip through the worktree-allow below — matches the python sibling
+  # _is_worktree_path (review finding 4).
+  FILE_ABS="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$FILE_ABS" 2>/dev/null || printf '%s' "$FILE_ABS")"
+fi
+
+# A file under a worktree root IS the isolation target — allow. Classify the
+# RESOLVED path so a `..`-traversal spoof that escapes the worktree can't pass.
+case "$FILE_ABS" in
+  *"/.coding-os/worktrees/"*) exit 0 ;;
+esac
+if [[ -n "${COS_WORKTREE_ROOT:-}" && "$FILE_ABS" == "${COS_WORKTREE_ROOT}"/* ]]; then
+  exit 0
+fi
+
+if [[ "$FILE_ABS" == "${REPO_ROOT}/"* ]]; then
+  cos_log_hook block-shared-tree-edit block "rule=pr-shared-tree-edit"
+  bash "$(dirname "$0")/../scripts/log-write.sh" \
+    --type "hook-block" --msg "block-shared-tree-edit" --what "$(basename "$FILE")" 2>/dev/null || true
+  echo "BLOCKED (pr-mode): editing a file in the shared integration checkout." >&2
+  echo "  Every change must be isolated in a worktree, never the shared tree." >&2
+  echo "  To fix: 'cos pr open' (or 'cos pr open --adhoc' for no-task work)," >&2
+  echo "  then edit inside the worktree." >&2
+  echo "  See docs/playbooks/pr-workflow.md § 5/§6." >&2
+  exit 2
+fi
+exit 0

core/hooks/block-uv-heredoc.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# PreToolUse Bash hook: block `uv run ... <<` heredoc patterns.
+#
+# Source of truth: CLAUDE.md Critical Rule #9 — "Always use Python for
+# multi-step verification scripts. Bash heredoc inside `$(...)` with
+# `uv run` hangs. Write to a Python file and invoke via
+# subprocess.run(..., timeout=N). See src/scripts/verify_phase_c_e2e.py."
+#
+# This hook matches three forms observed to hang or truncate silently:
+#   1. `uv run python - <<'EOF' ... EOF`     (stdin-piped Python)
+#   2. `uv run python -c "$(cat <<'EOF' ...` (heredoc inside command-sub)
+#   3. `output=$(uv run python - <<EOF ...)` (capture + stdin-piped)
+#
+# Escape hatch: touch $COS_AGENT_DIR/.uv-heredoc-override for one-shot bypass.
+# Use sparingly — the Python-file pattern is almost always cleaner.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+# Fail-closed: a heredoc-deadlock gate that cannot read the command must DENY,
+# not silently allow when jq is absent (observability-eye I8). cos_json_field
+# falls back to python3, so the gate keeps working when only jq is missing.
+cos_require_parser block-uv-heredoc
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Fast-path: the only thing this gate blocks is `uv run … <<heredoc`. If the
+# raw payload lacks either "uv" or a "<<" heredoc operator there is nothing to
+# deny — bail before any jq spawn (this hook fires on EVERY Bash command).
+case "$INPUT" in
+  *uv*) ;;
+  *) exit 0 ;;
+esac
+case "$INPUT" in
+  *'<<'*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+if [[ "$TOOL" != "Bash" ]]; then
+  exit 0
+fi
+
+CMD=$(printf '%s' "$INPUT" | cos_json_field tool_input.command)
+[[ -z "$CMD" ]] && exit 0
+
+COS_STATE_DIR="${COS_STATE_DIR:-.coding-os}"
+cos_log_hook block-uv-heredoc fire "tool=Bash"
+
+# One-shot override (consumed on use). Unified registry checked first;
+# legacy $COS_AGENT_DIR/.uv-heredoc-override still honoured.
+if cos_one_shot_override uv-heredoc 2>/dev/null; then
+  cos_log_hook block-uv-heredoc bypass "reason=override"
+  exit 0
+fi
+
+# Detect `uv run` followed (within reasonable distance) by heredoc operator.
+# We accept `<<`, `<<-`, `<<'EOF'`, `<<"EOF"`, `<<EOF` variants.
+if echo "$CMD" | grep -qE 'uv[[:space:]]+run[^|&;]*<<'; then
+  cos_log_hook block-uv-heredoc block "rule=uv-run-heredoc"
+  echo "BLOCKED: \`uv run\` with heredoc is known to hang silently." >&2
+  echo "  CLAUDE.md Critical Rule #9 — always use a real Python file:" >&2
+  echo "" >&2
+  echo "    # write the script" >&2
+  echo "    cat > src/scripts/my_check.py <<'PY'" >&2
+  echo "    ..." >&2
+  echo "    PY" >&2
+  echo "" >&2
+  echo "    # then invoke via subprocess-friendly single-quoted path" >&2
+  echo "    uv run --extra rag python src/scripts/my_check.py" >&2
+  echo "" >&2
+  echo "  Reference: src/scripts/verify_phase_c_e2e.py" >&2
+  echo "  One-shot override: touch $COS_AGENT_DIR/.uv-heredoc-override" >&2
+  exit 2
+fi
+
+exit 0

core/hooks/branch-guard.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# branch-guard.sh — enforce trunk-based git integrity.
+#
+# PreToolUse:Bash hook. In trunk mode (default) it BLOCKs commands that
+# either (a) create a branch / worktree or (b) rewrite shared HEAD —
+# both classes can clobber a peer session's commits or scatter work
+# across phantom branches. The coding-os workflow commits directly to
+# main (see src/core/rules/git-workflow.md). COS_GIT_WORKFLOW=pr switches to a
+# positive pr-mode policy (consumer-only): agents/* branches + worktrees pass,
+# but the shared checkout and protected branches stay guarded — NOT a bypass.
+#
+# The actual parsing lives in _helpers/branch_guard_check.py — it
+# handles whitespace normalization, `git -C` / `git -c` global options,
+# nested `sh -c "..."` / `bash -c "..."`, command-segment splitting,
+# and `shlex` quoting (so literal `git reset HEAD~1` inside an `echo`
+# or `grep` arg does NOT trigger). This script is a thin wrapper:
+# fast-skip when "git" isn't in the command, otherwise dispatch to the
+# helper and act on its JSON verdict.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+# Fail-closed: a branch/HEAD-move guard that cannot read the command must DENY
+# (observability-eye I8). python3 fallback keeps it working without jq.
+cos_require_parser branch-guard
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Fast-path: every branch/HEAD-move this guard blocks is a `git` command. If
+# the raw payload has no "git" substring at all there is nothing to deny —
+# bail before any jq spawn (this gate fires on EVERY Bash command).
+case "$INPUT" in
+  *git*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+if [[ "$TOOL" != "Bash" ]]; then
+  exit 0
+fi
+
+# pr-mode is NOT a guard-kill. The command flows into branch_guard_check.py,
+# which applies a positive pr-mode policy: allow agents/* branch + worktree-add,
+# but still BLOCK HEAD-rewrites/commits on the shared integration checkout and
+# pushes to protected branches. SPEC: docs/playbooks/pr-workflow.md § 5.
+
+COMMAND=$(printf '%s' "$INPUT" | cos_json_field tool_input.command)
+[[ -z "$COMMAND" ]] && exit 0
+
+# Fast-skip: no "git" substring → no risk; skip the python startup cost.
+if [[ "$COMMAND" != *git* ]]; then
+  exit 0
+fi
+
+cos_log_hook branch-guard fire "tool=Bash"
+
+# Resolve the helper through the file's physical location — works through
+# the .claude/hooks/ symlinks that consumer projects install.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="${_dir}/${_src}"
+done
+HOOKS_PHYS_DIR="$(cd -P "$(dirname "$_src")" && pwd)"
+unset _src _dir
+HELPER="${HOOKS_PHYS_DIR}/_helpers/branch_guard_check.py"
+
+if [[ ! -f "$HELPER" ]]; then
+  # Fail-CLOSED: we are past the fast-skip, so the command IS git-related.
+  # A missing helper (dangling symlink / broken install) means we cannot
+  # verify it — deny rather than silently allow (observability-eye I8/A2).
+  cos_say error hook.branch_guard "branch-guard helper missing — failing closed on git command" 2>/dev/null || true
+  cos_log_hook branch-guard block "rule=helper-missing"
+  echo "BLOCKED: branch-guard helper missing ($HELPER) — cannot verify this git command; failing closed." >&2
+  echo "  Restore src/core/hooks/_helpers/branch_guard_check.py (fail-closed: pr-mode does not bypass this guard)." >&2
+  exit 2
+fi
+
+# Run the helper, capturing BOTH stdout (verdict) and stderr (crash detail).
+# We are past the fast-skip, so the command IS git-related: a guard that
+# cannot evaluate it must NOT silently allow (the old `2>/dev/null || allow`
+# was a fail-OPEN security inversion — the guard silently stopped guarding,
+# crash recorded nowhere). On helper failure we fail CLOSED and surface the
+# crash to the eye. No non-git blast radius: non-git Bash exited at the fast-skip.
+HELPER_ERR=$(mktemp)
+HELPER_RC=0
+VERDICT_JSON=$(printf '%s' "$INPUT" | python3 "$HELPER" 2>"$HELPER_ERR") || HELPER_RC=$?
+HELPER_STDERR=$(cat "$HELPER_ERR" 2>/dev/null || true); rm -f "$HELPER_ERR"
+
+if [[ "$HELPER_RC" -ne 0 || -z "$VERDICT_JSON" ]]; then
+  cos_say error hook.branch_guard "branch-guard helper failed (rc=${HELPER_RC}) — failing closed on git command" detail="${HELPER_STDERR:0:200}" 2>/dev/null || true
+  cos_log_hook branch-guard block "rule=helper-crash rc=${HELPER_RC}" || true
+  echo "BLOCKED: branch-guard helper failed (rc=${HELPER_RC}) — cannot verify this git command; failing closed." >&2
+  echo "  Fix src/core/hooks/_helpers/branch_guard_check.py (fail-closed: pr-mode does not bypass this guard)." >&2
+  [[ -n "$HELPER_STDERR" ]] && echo "  helper stderr: ${HELPER_STDERR}" >&2
+  exit 2
+fi
+
+VERDICT=$(echo "$VERDICT_JSON" | jq -r '.verdict // "block"' 2>/dev/null || echo "block")
+
+if [[ "$VERDICT" != "block" ]]; then
+  cos_log_hook branch-guard ok || true
+  exit 0
+fi
+
+REASON=$(echo "$VERDICT_JSON" | jq -r '.reason // "branch-guard-block"' 2>/dev/null)
+MESSAGE=$(echo "$VERDICT_JSON" | jq -r '.message // ""' 2>/dev/null)
+
+cos_log_hook branch-guard block "rule=${REASON}"
+bash "$(dirname "$0")/../scripts/log-write.sh" \
+  --type "hook-block" --msg "branch-guard" --what "$REASON" 2>/dev/null || true
+
+echo "WHY: trunk-based git keeps history linear and the blast radius reviewable — src/core/ edits reach every consumer via live symlinks." >&2
+if [[ -n "$MESSAGE" ]]; then
+  printf '%s\n' "$MESSAGE" >&2
+else
+  echo "BLOCKED: coding-os trunk-based git workflow forbids this command." >&2
+  echo "  See src/core/rules/git-workflow.md (pr-mode applies a positive policy, not a bypass)." >&2
+fi
+exit 2

core/hooks/capture-observation.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# PostToolUse hook: fire-and-forget observation recording.
+#
+# Spawns capture.py in background for Write/Edit tools only. Must return
+# in <1ms — all work happens in a background process. If capture.py
+# itself fails (DB path broken, schema stale, import error), its stderr
+# is redirected to $COS_STATE_DIR/.capture-errors.log so the Stop hook
+# (check-capture-worked.sh) can surface the silent failure at session
+# end instead of us losing observations invisibly for an entire session.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null || echo "")
+
+COS_STATE_DIR="${COS_STATE_DIR:-.coding-os}"
+
+# Heartbeat: prove the hook fires at all. If `cos hooks-log` shows no
+# entries from this hook, Claude Code is not delivering the PostToolUse
+# Write|Edit event (typically because .claude/settings.json changed
+# mid-session — reload to pick up new hook config).
+cos_log_hook capture-observation fire "tool=${TOOL_NAME}"
+
+# Only capture Write, Edit, MultiEdit tool calls (skip Read, Glob, Grep, Bash).
+# MultiEdit is the batched variant — Claude SDK emits it for most real agent
+# edits, so excluding it produced ~0 observations (capture.py CAPTURE_TOOLS
+# already includes MultiEdit; the shell filter was the stale layer).
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Resolve through the symlink before reaching ../thinking_os: $0 is the
+# .claude/hooks/ symlink, so naive "$(dirname "$0")/../thinking_os" points
+# at the non-existent .claude/thinking_os/ and capture.py was NEVER found —
+# the hook logged "fire" then silently exited every time (the real
+# root cause of observations=2). Sibling files like cos-env.sh work only
+# because they ARE symlinked into .claude/hooks/; ../thinking_os/ is not.
+_src="${BASH_SOURCE[0]:-$0}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+HOOK_REAL_DIR="$(cd -P "$(dirname "$_src")" && pwd)"
+unset _src _dir
+CAPTURE_PY="${HOOK_REAL_DIR}/../thinking_os/capture.py"
+if [ ! -f "$CAPTURE_PY" ]; then
+  cos_log_hook capture-observation skip "reason=capture_py_missing path=${CAPTURE_PY}" 2>/dev/null || true
+  exit 0
+fi
+
+# Ensure state dir exists for the error log (best-effort).
+mkdir -p "$COS_STATE_DIR" 2>/dev/null || true
+ERROR_LOG="$COS_STATE_DIR/.capture-errors.log"
+
+# Run capture SYNCHRONOUSLY with embedding skipped. A backgrounded
+# `(...) &` was reaped by the agent hook lifecycle before capture.py's
+# INSERT+commit, so observations never persisted (6 inserts in
+# 17 days despite the hook firing constantly). capture.py is ~one python
+# startup under COS_CAPTURE_SKIP_EMBED; the FTS5 trigger indexes the row
+# on INSERT so keyword recall works without the embedding. Real failures
+# append a traceback to $ERROR_LOG for check-capture-worked.sh at Stop.
+echo "$INPUT" | COS_CAPTURE_SKIP_EMBED=1 python3 "$CAPTURE_PY" 2>>"$ERROR_LOG" || true
+
+# Visible signal — Claude Code does NOT render PostToolUse `systemMessage`
+# directly in chat UI; route through the per-turn activity log so
+# session-context.sh aggregates + emits on the next UserPromptSubmit
+# (which IS rendered, mirroring the caveman pattern). systemMessage
+# stays for future agent renderers + SDK consumers.
+cos_record_activity memory "+obs" 2>/dev/null || true
+printf '%s' '{"systemMessage":"[memory] +obs captured"}'
+
+exit 0