codebyplan 1.5.1 → 1.9.0

package/templates/hooks/cbp-statusline.sh

@@ -0,0 +1,347 @@
+#!/bin/bash
+# @hook: NOT-A-HOOK (statusLine renderer, invoked by settings.json statusLine.command)
+# Claude Code Status Line - All fields visible
+# Purpose: Renders up to 6 structured lines of Claude Code status from stdin JSON.
+#          Not a PreToolUse/PostToolUse/Notification hook — do NOT register in hooks[].
+# Shows: Identity | Context | Cost | Rate Limits | Repo/PR | Worktree
+#
+# --------------------------------------------------------------------------
+# ENV-VAR TOGGLES — set to 1 to suppress a render section
+#   CBP_STATUSLINE_HIDE_IDENTITY=1    suppress line 1 (model, effort, session, agent)
+#   CBP_STATUSLINE_HIDE_CONTEXT=1     suppress line 2 (context bar, tokens, cache)
+#   CBP_STATUSLINE_HIDE_COST=1        suppress line 3 (cost, duration, lines)
+#   CBP_STATUSLINE_HIDE_RATE_LIMITS=1 suppress line 4 (5h / 7d rate limits)
+#   CBP_STATUSLINE_HIDE_REPO_PR=1     suppress line 5 (repo host/owner/name, PR)
+#   CBP_STATUSLINE_HIDE_WORKTREE=1    suppress line 6 (worktree name/branch/path)
+#   CBP_STATUSLINE_NO_COLOR=1         strip all ANSI colour codes (also honoured by $NO_COLOR)
+# --------------------------------------------------------------------------
+
+INPUT=$(cat)
+
+# ---- One jq invocation captures all ~40 fields --------------------------------
+eval "$(echo "$INPUT" | jq -r '
+  @sh "MODEL_ID=\(.model.id // "")",
+  @sh "MODEL_NAME=\(.model.display_name // "")",
+  @sh "CWD=\(.cwd // "")",
+  @sh "WS_CURRENT_DIR=\(.workspace.current_dir // "")",
+  @sh "WS_PROJECT_DIR=\(.workspace.project_dir // "")",
+  @sh "WS_ADDED_DIRS_LEN=\((.workspace.added_dirs // []) | length)",
+  @sh "WS_GIT_WORKTREE=\(.workspace.git_worktree // "")",
+  @sh "WS_REPO_HOST=\(.workspace.repo.host // "")",
+  @sh "WS_REPO_OWNER=\(.workspace.repo.owner // "")",
+  @sh "WS_REPO_NAME=\(.workspace.repo.name // "")",
+  @sh "COST=\(.cost.total_cost_usd // 0)",
+  @sh "DURATION=\(.cost.total_duration_ms // 0)",
+  @sh "API_DURATION=\(.cost.total_api_duration_ms // 0)",
+  @sh "LINES_ADD=\(.cost.total_lines_added // 0)",
+  @sh "LINES_DEL=\(.cost.total_lines_removed // 0)",
+  @sh "CTX_TOT_IN=\(.context_window.total_input_tokens // 0)",
+  @sh "CTX_TOT_OUT=\(.context_window.total_output_tokens // 0)",
+  @sh "CTX_SIZE=\(.context_window.context_window_size // 200000)",
+  @sh "CTX_PCT=\(.context_window.used_percentage // 0)",
+  @sh "CTX_REM=\(.context_window.remaining_percentage // 100)",
+  @sh "CUR_IN=\(.context_window.current_usage.input_tokens // 0)",
+  @sh "CUR_OUT=\(.context_window.current_usage.output_tokens // 0)",
+  @sh "CACHE_CREATE=\(.context_window.current_usage.cache_creation_input_tokens // 0)",
+  @sh "CACHE_READ=\(.context_window.current_usage.cache_read_input_tokens // 0)",
+  @sh "EXCEEDS_200K=\(.exceeds_200k_tokens // false)",
+  @sh "EFFORT=\(.effort.level // "")",
+  @sh "THINKING=\(.thinking.enabled // false)",
+  @sh "RATE_5H_PCT=\(.rate_limits.five_hour.used_percentage // "")",
+  @sh "RATE_5H_RESETS=\(.rate_limits.five_hour.resets_at // 0)",
+  @sh "RATE_7D_PCT=\(.rate_limits.seven_day.used_percentage // "")",
+  @sh "RATE_7D_RESETS=\(.rate_limits.seven_day.resets_at // 0)",
+  # Note: RATE_*_PCT use `// ""` (not `// 0`) so the `[ -n "$RATE_*_PCT" ]` absence gate
+  # below distinguishes "API said 0% used" from "rate_limits object absent". Do not
+  # change to `// 0` — it would silently suppress the rate-limit line on subscriber
+  # accounts at 0% usage at session start.
+  @sh "SESSION_ID=\(.session_id // "")",
+  @sh "SESSION_NAME=\(.session_name // "")",
+  @sh "TRANSCRIPT_PATH=\(.transcript_path // "")",
+  @sh "VERSION=\(.version // "")",
+  @sh "OUTPUT_STYLE=\(.output_style.name // "")",
+  @sh "VIM_MODE=\(.vim.mode // "")",
+  @sh "AGENT_NAME=\(.agent.name // "")",
+  @sh "PR_NUMBER=\(.pr.number // "")",
+  @sh "PR_URL=\(.pr.url // "")",
+  @sh "PR_REVIEW_STATE=\(.pr.review_state // "")",
+  @sh "WT_NAME=\(.worktree.name // "")",
+  @sh "WT_PATH=\(.worktree.path // "")",
+  @sh "WT_BRANCH=\(.worktree.branch // "")",
+  @sh "WT_ORIG_CWD=\(.worktree.original_cwd // "")",
+  @sh "WT_ORIG_BRANCH=\(.worktree.original_branch // "")"
+')"
+
+# ---- Colour setup ------------------------------------------------------------
+# Strip colours when NO_COLOR or CBP_STATUSLINE_NO_COLOR is set
+if [ -n "${NO_COLOR:-}" ] || [ "${CBP_STATUSLINE_NO_COLOR:-0}" = "1" ]; then
+  RST=''; DIM=''; BOLD=''; GREEN=''; YELLOW=''; RED=''; CYAN=''; MAGENTA=''; BLUE=''
+else
+  RST='\033[0m'
+  DIM='\033[2m'
+  BOLD='\033[1m'
+  GREEN='\033[32m'
+  YELLOW='\033[33m'
+  RED='\033[31m'
+  CYAN='\033[36m'
+  MAGENTA='\033[35m'
+  BLUE='\033[34m'
+fi
+
+# ---- Float-safe percentage comparison ----------------------------------------
+# Usage: awk_gte VALUE THRESHOLD   (returns 0 = true, 1 = false)
+awk_gte() { awk -v v="$1" -v t="$2" 'BEGIN{exit !(v+0 >= t+0)}'; }
+
+# ---- Token/size formatter (K / M) -------------------------------------------
+fmt_k() {
+  local val=$1
+  if [ "$val" -ge 1000000 ] 2>/dev/null; then
+    printf "%.1fM" "$(echo "$val / 1000000" | bc -l)"
+  elif [ "$val" -ge 1000 ] 2>/dev/null; then
+    printf "%.1fK" "$(echo "$val / 1000" | bc -l)"
+  else
+    printf "%d" "$val"
+  fi
+}
+
+# ---- Duration formatter (ms → Xh Xm Xs) ------------------------------------
+fmt_dur() {
+  local ms=$1
+  local secs=$(( ms / 1000 ))
+  if [ "$secs" -ge 3600 ]; then
+    printf "%dh%dm" $(( secs / 3600 )) $(( (secs % 3600) / 60 ))
+  elif [ "$secs" -ge 60 ]; then
+    printf "%dm%ds" $(( secs / 60 )) $(( secs % 60 ))
+  else
+    printf "%ds" "$secs"
+  fi
+}
+
+# ---- Relative-time formatter (epoch → "now" / Xm / Xh / Xd) ----------------
+# Callers should gate on `epoch != 0` upstream (the absence sentinel from the
+# `// 0` jq fallback). Passing epoch=0 here yields "now" by the delta<=0 branch.
+fmt_rel_time() {
+  local epoch=$1
+  local now
+  now=$(date +%s)
+  local delta=$(( epoch - now ))
+  if [ "$delta" -le 0 ]; then
+    printf "now"
+  elif [ "$delta" -ge 86400 ]; then
+    printf "%dd" $(( delta / 86400 ))
+  elif [ "$delta" -ge 3600 ]; then
+    printf "%dh" $(( delta / 3600 ))
+  else
+    printf "%dm" $(( delta / 60 ))
+  fi
+}
+
+# ============================================================
+# LINE 1 — Identity
+# ============================================================
+if [ "${CBP_STATUSLINE_HIDE_IDENTITY:-0}" != "1" ]; then
+  L1=""
+
+  # Prefix: wt > session > agent (pick first present)
+  if [ -n "$WT_NAME" ]; then
+    L1="${DIM}wt:${RST}${MAGENTA}${WT_NAME}${RST} "
+  elif [ -n "$SESSION_NAME" ]; then
+    L1="${DIM}session:${RST}${MAGENTA}${SESSION_NAME}${RST} "
+  elif [ -n "$AGENT_NAME" ]; then
+    L1="${DIM}agent:${RST}${MAGENTA}${AGENT_NAME}${RST} "
+  fi
+
+  # Model (display_name + id in parens when id differs or both present)
+  if [ -n "$MODEL_NAME" ] && [ -n "$MODEL_ID" ] && [ "$MODEL_NAME" != "$MODEL_ID" ]; then
+    L1="${L1}${BOLD}${CYAN}${MODEL_NAME}${RST} ${DIM}(${MODEL_ID})${RST}"
+  elif [ -n "$MODEL_NAME" ]; then
+    L1="${L1}${BOLD}${CYAN}${MODEL_NAME}${RST}"
+  elif [ -n "$MODEL_ID" ]; then
+    L1="${L1}${BOLD}${CYAN}${MODEL_ID}${RST}"
+  fi
+
+  # Effort level (when present)
+  if [ -n "$EFFORT" ]; then
+    L1="${L1} ${DIM}effort:${RST}${EFFORT}"
+  fi
+
+  # Thinking (only when explicitly true)
+  if [ "$THINKING" = "true" ]; then
+    L1="${L1} ${YELLOW}thinking:on${RST}"
+  fi
+
+  # Output style (when present and not "default")
+  if [ -n "$OUTPUT_STYLE" ] && [ "$OUTPUT_STYLE" != "default" ]; then
+    L1="${L1} ${DIM}style:${RST}${OUTPUT_STYLE}"
+  fi
+
+  # Version
+  if [ -n "$VERSION" ]; then
+    L1="${L1} ${DIM}v:${VERSION}${RST}"
+  fi
+
+  # Vim mode
+  if [ -n "$VIM_MODE" ]; then
+    L1="${L1} ${DIM}[${VIM_MODE}]${RST}"
+  fi
+
+  # Session id (short 8-char prefix — distinguishes parallel sessions)
+  if [ -n "$SESSION_ID" ]; then
+    L1="${L1} ${DIM}sid:${SESSION_ID:0:8}${RST}"
+  fi
+
+  # Transcript file (basename only — full path would blow out the line)
+  if [ -n "$TRANSCRIPT_PATH" ]; then
+    L1="${L1} ${DIM}log:$(basename "$TRANSCRIPT_PATH")${RST}"
+  fi
+
+  # Only print when we have actual content
+  if [ -n "$L1" ]; then
+    printf "%b\n" "$L1"
+  fi
+fi
+
+# ============================================================
+# LINE 2 — Context window
+# ============================================================
+if [ "${CBP_STATUSLINE_HIDE_CONTEXT:-0}" != "1" ]; then
+  # Context bar colour by usage
+  if awk_gte "$CTX_PCT" 75; then
+    BAR_COLOR="$RED"
+  elif awk_gte "$CTX_PCT" 50; then
+    BAR_COLOR="$YELLOW"
+  else
+    BAR_COLOR="$GREEN"
+  fi
+
+  # 20-char progress bar (ceiling division so 99% shows 20/20, not 19/20)
+  FILLED=$(( (CTX_PCT + 4) / 5 ))
+  [ "$FILLED" -gt 20 ] && FILLED=20
+  EMPTY=$(( 20 - FILLED ))
+  BAR=""
+  for ((i=0; i<FILLED; i++)); do BAR+="▓"; done
+  for ((i=0; i<EMPTY; i++)); do BAR+="░"; done
+
+  CTX_SIZE_F=$(fmt_k "$CTX_SIZE")
+  CUR_IN_F=$(fmt_k "$CUR_IN")
+  CUR_OUT_F=$(fmt_k "$CUR_OUT")
+  CACHE_CR_F=$(fmt_k "$CACHE_CREATE")
+  CACHE_RD_F=$(fmt_k "$CACHE_READ")
+
+  L2="${BAR_COLOR}${BAR}${RST} ${BAR_COLOR}${CTX_PCT}%${RST}${DIM}/${CTX_SIZE_F}${RST}"
+  L2="${L2} ${DIM}in:${RST}${BLUE}${CUR_IN_F}${RST} ${DIM}out:${RST}${MAGENTA}${CUR_OUT_F}${RST} ${DIM}cache_cr:${RST}${CACHE_CR_F} ${DIM}cache_rd:${RST}${CACHE_RD_F}"
+
+  if [ "$EXCEEDS_200K" = "true" ]; then
+    L2="${L2} ${YELLOW}⚠ 200k+${RST}"
+  fi
+
+  printf "%b\n" "$L2"
+fi
+
+# ============================================================
+# LINE 3 — Cost
+# ============================================================
+if [ "${CBP_STATUSLINE_HIDE_COST:-0}" != "1" ]; then
+  COST_F=$(printf '$%.4f' "$COST")
+  DUR_F=$(fmt_dur "$DURATION")
+  API_DUR_F=$(fmt_dur "$API_DURATION")
+
+  L3="${GREEN}${COST_F}${RST} ${DIM}dur:${RST}${DUR_F} ${DIM}api:${RST}${API_DUR_F} ${GREEN}+${LINES_ADD}${RST} ${RED}-${LINES_DEL}${RST} ${DIM}lines${RST}"
+  printf "%b\n" "$L3"
+fi
+
+# ============================================================
+# LINE 4 — Rate limits
+# ============================================================
+if [ "${CBP_STATUSLINE_HIDE_RATE_LIMITS:-0}" != "1" ]; then
+  # Emit this line only when at least one window has resets_at != 0
+  HAVE_RATE=0
+  [ -n "$RATE_5H_PCT" ] && [ "$RATE_5H_RESETS" != "0" ] && HAVE_RATE=1
+  [ -n "$RATE_7D_PCT" ] && [ "$RATE_7D_RESETS" != "0" ] && HAVE_RATE=1
+
+  if [ "$HAVE_RATE" = "1" ]; then
+    L4=""
+
+    if [ -n "$RATE_5H_PCT" ] && [ "$RATE_5H_RESETS" != "0" ]; then
+      if awk_gte "$RATE_5H_PCT" 80; then
+        C5="$RED"
+      elif awk_gte "$RATE_5H_PCT" 60; then
+        C5="$YELLOW"
+      else
+        C5="$GREEN"
+      fi
+      REL5=$(fmt_rel_time "$RATE_5H_RESETS")
+      L4="${DIM}5h:${RST}${C5}${RATE_5H_PCT}%${RST} ${DIM}(resets in ${REL5})${RST}"
+    fi
+
+    if [ -n "$RATE_7D_PCT" ] && [ "$RATE_7D_RESETS" != "0" ]; then
+      if awk_gte "$RATE_7D_PCT" 80; then
+        C7="$RED"
+      elif awk_gte "$RATE_7D_PCT" 60; then
+        C7="$YELLOW"
+      else
+        C7="$GREEN"
+      fi
+      REL7=$(fmt_rel_time "$RATE_7D_RESETS")
+      SEG7="${DIM}7d:${RST}${C7}${RATE_7D_PCT}%${RST} ${DIM}(resets in ${REL7})${RST}"
+      if [ -n "$L4" ]; then
+        L4="${L4} ${DIM}|${RST} ${SEG7}"
+      else
+        L4="$SEG7"
+      fi
+    fi
+
+    printf "%b\n" "$L4"
+  fi
+fi
+
+# ============================================================
+# LINE 5 — Repo / PR
+# ============================================================
+if [ "${CBP_STATUSLINE_HIDE_REPO_PR:-0}" != "1" ]; then
+  L5=""
+
+  # Repo segment (host/owner/name when host is present)
+  if [ -n "$WS_REPO_HOST" ]; then
+    L5="${DIM}${WS_REPO_HOST}/${WS_REPO_OWNER}/${WS_REPO_NAME}${RST}"
+  fi
+
+  # PR segment
+  if [ -n "$PR_NUMBER" ]; then
+    PR_SEG="${DIM}PR${RST} ${CYAN}#${PR_NUMBER}${RST}"
+    if [ -n "$PR_REVIEW_STATE" ]; then
+      PR_SEG="${PR_SEG} ${DIM}${PR_REVIEW_STATE}${RST}"
+    fi
+    if [ -n "$PR_URL" ]; then
+      PR_SEG="${PR_SEG} ${BLUE}${PR_URL}${RST}"
+    fi
+    if [ -n "$L5" ]; then
+      L5="${L5} ${DIM}|${RST} ${PR_SEG}"
+    else
+      L5="$PR_SEG"
+    fi
+  fi
+
+  if [ -n "$L5" ]; then
+    printf "%b\n" "$L5"
+  fi
+fi
+
+# ============================================================
+# LINE 6 — Worktree
+# ============================================================
+if [ "${CBP_STATUSLINE_HIDE_WORKTREE:-0}" != "1" ]; then
+  if [ -n "$WT_NAME" ]; then
+    L6="${MAGENTA}${WT_NAME}${RST} ${DIM}@${RST} ${CYAN}${WT_BRANCH}${RST}"
+    if [ -n "$WT_ORIG_BRANCH" ] && [ "$WT_ORIG_BRANCH" != "$WT_BRANCH" ]; then
+      L6="${L6} ${DIM}(was: ${WT_ORIG_BRANCH})${RST}"
+    fi
+    # Truncate path if longer than 60 chars
+    WT_PATH_DISP="$WT_PATH"
+    if [ "${#WT_PATH}" -gt 60 ]; then
+      WT_PATH_DISP="...${WT_PATH: -57}"
+    fi
+    L6="${L6} ${DIM}${WT_PATH_DISP}${RST}"
+    printf "%b\n" "$L6"
+  fi
+fi

package/templates/hooks/cbp-subagent-statusline.sh

@@ -0,0 +1,182 @@
+#!/bin/bash
+# Portability: bash 3.2+ (macOS default /bin/bash). UTF-8 multibyte chars in
+# user-controlled fields are byte-iterated under 3.2 (over-counts visible width
+# for non-ASCII content); acceptable safe-direction approximation.
+# @hook: NOT-A-HOOK (subagentStatusLine renderer, invoked by settings.json subagentStatusLine.command)
+# Claude Code Subagent Status Line — one JSON line per active subagent
+# Purpose: Renders one row per running subagent. Output protocol per upstream docs:
+#   {"id": "<task_id>", "content": "<rendered_body>"}
+#   - Omitted tasks keep their default Claude Code rendering
+#   - Empty content strings hide the row
+# NOT a PreToolUse/PostToolUse/Notification hook — do NOT register in hooks[].
+#
+# ENV-VAR TOGGLES — set to 1 to suppress a column / color
+#   CBP_SUBAGENT_STATUSLINE_HIDE_DESCRIPTION=1   omit DESCRIPTION segment
+#   CBP_SUBAGENT_STATUSLINE_HIDE_TOKENS=1        omit tokens:N segment
+#   CBP_SUBAGENT_STATUSLINE_NO_COLOR=1           strip all ANSI codes (also honoured by $NO_COLOR)
+
+INPUT=$(cat)
+
+# One jq pass for base fields (cwd, session_id, columns)
+eval "$(echo "$INPUT" | jq -r '
+  @sh "CWD=\(.cwd // "")",
+  @sh "SESSION_ID=\(.session_id // "")",
+  @sh "COLUMNS=\(.columns // 0)"
+')"
+
+# ---- Colour setup ----------------------------------------------------------
+# Only the colours referenced by the render block below are defined here.
+if [ -n "${NO_COLOR:-}" ] || [ "${CBP_SUBAGENT_STATUSLINE_NO_COLOR:-0}" = "1" ]; then
+  RST=''; DIM=''; BOLD=''; GREEN=''; RED=''; BLUE=''
+else
+  RST='\033[0m'
+  DIM='\033[2m'
+  BOLD='\033[1m'
+  GREEN='\033[32m'
+  RED='\033[31m'
+  BLUE='\033[34m'
+fi
+
+# ---- Token/size formatter K / M (verbatim from cbp-statusline.sh L96-105) ---
+fmt_k() {
+  local val=$1
+  if [ "$val" -ge 1000000 ] 2>/dev/null; then
+    printf "%.1fM" "$(echo "$val / 1000000" | bc -l)"
+  elif [ "$val" -ge 1000 ] 2>/dev/null; then
+    printf "%.1fK" "$(echo "$val / 1000" | bc -l)"
+  else
+    printf "%d" "$val"
+  fi
+}
+
+# ---- Age formatter: epoch seconds → "Xs" / "XmYs" / "XhYm" -----------------
+# NEW helper — cannot reuse fmt_dur (which divides by 1000 for ms input).
+# startTime is a Unix epoch in seconds, same as rate_limits.*.resets_at.
+fmt_age_secs() {
+  local start=$1
+  local now
+  now=$(date +%s)
+  local delta=$(( now - start ))
+  [ "$delta" -lt 0 ] && delta=0
+  if [ "$delta" -ge 3600 ]; then
+    printf "%dh%dm" $(( delta / 3600 )) $(( (delta % 3600) / 60 ))
+  elif [ "$delta" -ge 60 ]; then
+    printf "%dm%ds" $(( delta / 60 )) $(( delta % 60 ))
+  else
+    printf "%ds" "$delta"
+  fi
+}
+
+# ---- Strip ANSI codes for visible-length measurement (column truncation) ----
+strip_ansi() {
+  printf '%s' "$1" | sed $'s/\033\\[[0-9;]*m//g'
+}
+
+# ---- JSON-string-escape a bash variable (embed in {"id":..., "content":...}) -
+json_escape() {
+  printf '%s' "$1" | jq -Rs '.'
+}
+
+# ---- Per-task render: one jq TSV emission, looped in bash ------------------
+# Single jq pass for tasks[] (locked decision #3 — two jq calls total).
+echo "$INPUT" | jq -r '
+  .tasks // [] | .[] | [
+    .id // "",
+    .name // "",
+    .type // "",
+    .status // "",
+    .description // "",
+    (.startTime // 0 | tostring),
+    (.tokenCount // 0 | tostring)
+  ] | @tsv
+' | while IFS=$'\t' read -r T_ID T_NAME T_TYPE T_STATUS T_DESC T_START T_TOKENS; do
+  # Skip blank rows (empty tasks[] → no output)
+  [ -z "$T_ID" ] && continue
+
+  # Status icon + colour
+  case "$T_STATUS" in
+    running)   ICON="${GREEN}●${RST}" ;;
+    pending)   ICON="${DIM}○${RST}" ;;
+    completed) ICON="${BLUE}✓${RST}" ;;
+    failed)    ICON="${RED}✗${RST}" ;;
+    *)         ICON="${DIM}•${RST}" ;;
+  esac
+
+  # Build content segments
+  ROW="${ICON} ${BOLD}${T_NAME}${RST}"
+  [ -n "$T_TYPE" ] && ROW="${ROW} ${DIM}(${T_TYPE})${RST}"
+
+  if [ "${CBP_SUBAGENT_STATUSLINE_HIDE_DESCRIPTION:-0}" != "1" ] && [ -n "$T_DESC" ]; then
+    ROW="${ROW} ${DIM}—${RST} ${T_DESC}"
+  fi
+
+  if [ "${CBP_SUBAGENT_STATUSLINE_HIDE_TOKENS:-0}" != "1" ] && [ "$T_TOKENS" -gt 0 ] 2>/dev/null; then
+    TOKENS_F=$(fmt_k "$T_TOKENS")
+    ROW="${ROW} ${DIM}·${RST} ${DIM}tokens:${RST}${TOKENS_F}"
+  fi
+
+  if [ "$T_START" -gt 0 ] 2>/dev/null; then
+    AGE_F=$(fmt_age_secs "$T_START")
+    ROW="${ROW} ${DIM}·${RST} ${DIM}age:${RST}${AGE_F}"
+  fi
+
+  # Apply printf to interpret escape sequences, then truncate to $COLUMNS
+  RENDERED=$(printf '%b' "$ROW")
+  if [ "$COLUMNS" -gt 0 ] 2>/dev/null; then
+    # ANSI-aware iterative truncation: walk RENDERED char-by-char treating
+    # \033[...letter escape sequences as zero-width and ordinary chars as
+    # one-width. Stop when the visible counter reaches COLUMNS - 3, then
+    # append RST + ellipsis. Correct under any ANSI-density distribution,
+    # unlike a single OVERHEAD-add formula which assumes uniform spread.
+    # Pure bash (no awk/perl subprocess); byte-based slicing means non-ASCII
+    # multi-byte UTF-8 in user-controlled descriptions counts as multiple
+    # visible units — acceptable approximation for the ASCII-dominant case.
+    TARGET=$(( COLUMNS - 3 ))
+    [ "$TARGET" -lt 0 ] && TARGET=0
+    RAW_LEN=${#RENDERED}
+    vis=0
+    i=0
+    in_esc=0
+    while [ $i -lt $RAW_LEN ] && [ $vis -lt $TARGET ]; do
+      ch="${RENDERED:$i:1}"
+      if [ "$in_esc" = "1" ]; then
+        case "$ch" in
+          [a-zA-Z]) in_esc=0 ;;
+        esac
+      elif [ "$ch" = $'\033' ]; then
+        in_esc=1
+      else
+        vis=$(( vis + 1 ))
+      fi
+      i=$(( i + 1 ))
+    done
+    # Post-loop drain: every rendered row ends with a trailing ${RST} from the
+    # last segment. Without this drain, a row whose visible content fits within
+    # COLUMNS still has `i < RAW_LEN` (pointing inside the trailing reset),
+    # which would spuriously trigger truncation. Walk past any in-progress
+    # escape and any further escape sequences until we hit a real visible byte
+    # or end-of-string.
+    while [ $i -lt $RAW_LEN ]; do
+      ch="${RENDERED:$i:1}"
+      if [ "$in_esc" = "1" ]; then
+        case "$ch" in
+          [a-zA-Z]) in_esc=0 ;;
+        esac
+        i=$(( i + 1 ))
+      elif [ "$ch" = $'\033' ]; then
+        in_esc=1
+        i=$(( i + 1 ))
+      else
+        break
+      fi
+    done
+    if [ $i -lt $RAW_LEN ]; then
+      # printf '%b' converts the literal-text RST (`\033[0m`) into an actual
+      # ESC byte sequence, matching the byte semantics of RENDERED's prefix.
+      RENDERED="${RENDERED:0:$i}$(printf '%b' "$RST")..."
+    fi
+  fi
+
+  # Emit one JSON line per task (upstream protocol: JSON-per-line)
+  printf '{"id":%s,"content":%s}\n' "$(json_escape "$T_ID")" "$(json_escape "$RENDERED")"
+done

package/templates/hooks/cbp-test-coverage-gate.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# @hook: PreToolUse Bash
+# Hook: PreToolUse for Bash (git commit commands)
+# Purpose: Block git commits when new source files lack test companions
+# Exit 0 = allow, Exit 2 = block (stderr sent to Claude)
+
+set -e
+
+echo "[HOOK START] test-coverage-gate"
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract command from tool input
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  echo "[HOOK END] test-coverage-gate (no command)"
+  exit 0
+fi
+
+# Only check git commit commands
+if ! echo "$COMMAND" | grep -qE 'git\s+commit'; then
+  echo "[HOOK END] test-coverage-gate (not git commit)"
+  exit 0
+fi
+
+# Get repo root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [ -z "$REPO_ROOT" ]; then
+  echo "[HOOK END] test-coverage-gate (not a git repo)"
+  exit 0
+fi
+
+# Skip merge commits — the diff inherits files from the other parent that
+# arrived without test companions; flagging them here is a false positive
+# (the coverage gap belongs to whichever upstream branch introduced them).
+# Use `git rev-parse --git-dir` to resolve the real git dir (handles worktrees,
+# where .git is a file pointing at the main repo's worktrees/<name>/ dir).
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo "")
+if [ -n "$GIT_DIR" ] && [ -f "${GIT_DIR}/MERGE_HEAD" ]; then
+  echo "[HOOK END] test-coverage-gate (merge in progress; skipping)"
+  exit 0
+fi
+
+# Get staged files (new or modified source files)
+# Only check NEW files (Added), not modifications to existing files.
+# Modified files that lack tests are a pre-existing gap — captured by
+# test-coverage tooling, not blocked at commit time.
+STAGED_SOURCE=$(git diff --cached --name-only --diff-filter=A | grep -E '\.(ts|tsx|js|jsx)$' || true)
+
+if [ -z "$STAGED_SOURCE" ]; then
+  echo "[HOOK END] test-coverage-gate (no source files staged)"
+  exit 0
+fi
+
+MISSING_TESTS=""
+CHECKED=0
+SKIPPED=0
+
+while IFS= read -r FILE; do
+  # Skip test files themselves
+  if echo "$FILE" | grep -qE '\.(test|spec)\.(ts|tsx|js|jsx)$'; then
+    continue
+  fi
+
+  # Skip infrastructure / generated / config files (generic skips — harmless if user doesn't have these dirs)
+  if echo "$FILE" | grep -qE '^\.claude/|^docs/|^supabase/|\.config\.|\.json$|\.md$|\.ya?ml$|\.sh$|\.scss$|\.css$'; then
+    continue
+  fi
+
+  # Skip type definition files
+  if echo "$FILE" | grep -qE '\.d\.ts$|/types\.ts$|/types/'; then
+    continue
+  fi
+
+  # Skip barrel exports (index.ts with only re-exports)
+  if echo "$FILE" | grep -qE '/index\.(ts|tsx)$'; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  # Skip Next.js App Router framework files — page/layout/loading/error/route/
+  # etc. are framework-convention wrappers, not logic-bearing modules. Same
+  # category as the barrel/index skip above: behavior lives in the components
+  # they delegate to, which carry their own tests.
+  if echo "$FILE" | grep -qE '/app/(.*/)?(page|layout|loading|error|global-error|not-found|template|default|route|forbidden|unauthorized)\.(tsx?|jsx?)$'; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  CHECKED=$((CHECKED + 1))
+
+  # Derive expected test file locations
+  DIR=$(dirname "$FILE")
+  BASE=$(basename "$FILE" | sed -E 's/\.(ts|tsx|js|jsx)$//')
+  EXT=$(echo "$FILE" | grep -oE '\.(ts|tsx|js|jsx)$')
+
+  # Check multiple conventions:
+  # 1. Sibling: dir/name.test.ext
+  # 2. Co-located: dir/__tests__/name.test.ext
+  # 3. Spec variant: dir/name.spec.ext
+  # 4. Co-located spec: dir/__tests__/name.spec.ext
+  FOUND=0
+  for PATTERN in \
+    "${DIR}/${BASE}.test${EXT}" \
+    "${DIR}/__tests__/${BASE}.test${EXT}" \
+    "${DIR}/${BASE}.spec${EXT}" \
+    "${DIR}/__tests__/${BASE}.spec${EXT}" \
+    "${DIR}/${BASE}.test.ts" \
+    "${DIR}/__tests__/${BASE}.test.ts" \
+    "${DIR}/${BASE}.test.tsx" \
+    "${DIR}/__tests__/${BASE}.test.tsx"; do
+    if [ -f "${REPO_ROOT}/${PATTERN}" ]; then
+      FOUND=1
+      break
+    fi
+  done
+
+  # Also check if test file is being staged in this same commit
+  if [ "$FOUND" -eq 0 ]; then
+    if echo "$STAGED_SOURCE" | grep -qE "${BASE}\.(test|spec)\.(ts|tsx|js|jsx)$"; then
+      FOUND=1
+    fi
+  fi
+
+  if [ "$FOUND" -eq 0 ]; then
+    MISSING_TESTS="${MISSING_TESTS}  - ${FILE}\n"
+  fi
+done <<< "$STAGED_SOURCE"
+
+if [ -n "$MISSING_TESTS" ]; then
+  echo "" >&2
+  echo "TEST COVERAGE GATE: Cannot commit — source files without test companions:" >&2
+  echo -e "$MISSING_TESTS" >&2
+  echo "Write tests for these files before committing." >&2
+  echo "Checked ${CHECKED} source files, skipped ${SKIPPED} (index/barrel/framework)." >&2
+  echo "" >&2
+  echo "[HOOK END] test-coverage-gate (BLOCKED)"
+  exit 2
+fi
+
+echo "[HOOK END] test-coverage-gate (${CHECKED} files checked, all have tests)"
+exit 0