@pennyfarthing/core 7.4.0 → 7.4.1

package/pennyfarthing-dist/scripts/core/README.md

@@ -0,0 +1,26 @@
+# Core Scripts
+
+Essential scripts required for all Pennyfarthing operations.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `run.sh` | Bootstrap script - finds PROJECT_ROOT and dispatches to other scripts |
+| `agent-session.sh` | Agent persona loading and session management |
+| `check-context.sh` | Context usage checker for monitoring token limits |
+| `prime.sh` | Context loading for agent activation |
+
+## Usage
+
+These scripts are invoked via `run.sh`:
+
+```bash
+.pennyfarthing/scripts/core/run.sh core/agent-session.sh start sm
+.pennyfarthing/scripts/core/run.sh core/check-context.sh --human
+```
+
+## Ownership
+
+- **Primary users:** All agents, all workflows
+- **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/scripts/core/agent-session.sh

@@ -0,0 +1,378 @@
+#!/usr/bin/env zsh
+# Agent session management script
+# Usage: agent-session.sh <action> [agent-name] [session-id]
+#   start "agent-name" "session-id"  - Register agent session and output persona
+#   stop "session-id"                - Remove session for given ID
+#   stop-all                         - Remove all agent sessions
+#   status                           - Output for Claude Code statusLine (reads JSON from stdin)
+#
+# Session files stored in .session/agents/<session-id> for multi-session support
+
+# Agents directory for multi-session support
+AGENTS_DIR="$PROJECT_ROOT/.session/agents"
+
+# Check if character_voice preference is enabled
+# Returns 0 (true) if enabled or not set, 1 (false) if explicitly disabled
+is_character_voice_enabled() {
+  local prefs_file=""
+
+  # Check for local prefs first, then default
+  if [ -f "$PROJECT_ROOT/.claude/pennyfarthing/preferences.local.yaml" ]; then
+    prefs_file="$PROJECT_ROOT/.claude/pennyfarthing/preferences.local.yaml"
+  elif [ -f "$PROJECT_ROOT/.claude/pennyfarthing/preferences.yaml" ]; then
+    prefs_file="$PROJECT_ROOT/.claude/pennyfarthing/preferences.yaml"
+  else
+    # No preferences file = default to enabled
+    return 0
+  fi
+
+  # Read character_voice setting (default to true if not set)
+  local voice=$(yq '.character_voice' "$prefs_file" 2>/dev/null)
+  # If null/empty, default to enabled
+  if [ -z "$voice" ] || [ "$voice" = "null" ]; then
+    return 0
+  fi
+  # If explicitly false, return disabled
+  if [ "$voice" = "false" ]; then
+    return 1
+  fi
+  return 0
+}
+
+# Get agent file path for a session
+get_agent_file() {
+    local session_id="$1"
+    echo "$AGENTS_DIR/$session_id"
+}
+
+# Check if theme version matches current Pennyfarthing version
+# Only warns on major/minor mismatch, not patch
+# Arguments: theme_file, theme_name
+check_theme_version() {
+  local theme_file="$1"
+  local theme_name="$2"
+
+  # Only check custom themes (in .claude/pennyfarthing/themes/)
+  if [[ ! "$theme_file" == *".claude/pennyfarthing/themes/"* ]]; then
+    return 0
+  fi
+
+  # Get theme's pennyfarthing_version
+  local theme_version=$(yq '.theme.pennyfarthing_version // ""' "$theme_file" 2>/dev/null)
+  if [ -z "$theme_version" ] || [ "$theme_version" = "null" ] || [ "$theme_version" = "" ]; then
+    # No version in theme - skip warning (legacy custom theme)
+    return 0
+  fi
+
+  # Get current version from VERSION file
+  local version_file="$PROJECT_ROOT/VERSION"
+  if [ ! -f "$version_file" ]; then
+    # No VERSION file - skip warning
+    return 0
+  fi
+  local current_version=$(cat "$version_file" 2>/dev/null | tr -d '[:space:]')
+  if [ -z "$current_version" ]; then
+    return 0
+  fi
+
+  # Extract major.minor from both versions
+  local theme_major_minor=$(echo "$theme_version" | cut -d. -f1,2)
+  local current_major_minor=$(echo "$current_version" | cut -d. -f1,2)
+
+  # Compare major.minor only
+  if [ "$theme_major_minor" != "$current_major_minor" ]; then
+    echo "" >&2
+    echo "Warning: Theme '${theme_name}' was created with Pennyfarthing ${theme_version}" >&2
+    echo "         Current version: ${current_version} - agent roles may have changed." >&2
+    echo "         Run '/theme-maker --update ${theme_name}' to review." >&2
+    echo "" >&2
+  fi
+
+  return 0
+}
+
+# Function to output persona for an agent
+output_persona() {
+  local agent_name="$1"
+  local config_file=""
+  local theme=""
+  local theme_file=""
+
+  # Check for config files in priority order:
+  # 1. .pennyfarthing/config.local.yaml (agent-writable, dogfooding-friendly)
+  # 2. .claude/persona-config.yaml (project default)
+  if [ -f "$PROJECT_ROOT/.pennyfarthing/config.local.yaml" ]; then
+    config_file="$PROJECT_ROOT/.pennyfarthing/config.local.yaml"
+  elif [ -f "$PROJECT_ROOT/.claude/persona-config.yaml" ]; then
+    config_file="$PROJECT_ROOT/.claude/persona-config.yaml"
+  else
+    echo "<!-- No persona config found -->" >&2
+    return 1
+  fi
+
+  # Get theme from config
+  theme=$(yq '.theme' "$config_file" 2>/dev/null)
+  if [ -z "$theme" ] || [ "$theme" = "null" ]; then
+    echo "<!-- No theme configured -->" >&2
+    return 1
+  fi
+
+  # Find theme file - single source of truth: .pennyfarthing/personas/themes/
+  theme_file="$PROJECT_ROOT/.pennyfarthing/personas/themes/${theme}.yaml"
+  if [ ! -f "$theme_file" ]; then
+    echo "<!-- Theme file not found: ${theme_file} -->" >&2
+    return 1
+  fi
+
+  # Check theme version compatibility (warns on major/minor mismatch)
+  check_theme_version "$theme_file" "$theme"
+
+  # Extract agent persona
+  local persona=$(yq ".agents.${agent_name}" "$theme_file" 2>/dev/null)
+  if [ -z "$persona" ] || [ "$persona" = "null" ]; then
+    echo "<!-- No persona found for agent: ${agent_name} -->" >&2
+    return 1
+  fi
+
+  # Output persona in a format Claude can use
+  echo ""
+  echo "<persona agent=\"${agent_name}\" theme=\"${theme}\">"
+  echo "Character: $(yq ".agents.${agent_name}.character" "$theme_file")"
+  echo "Style: $(yq ".agents.${agent_name}.style" "$theme_file")"
+  echo "Role: $(yq ".agents.${agent_name}.role" "$theme_file")"
+
+  # Optional fields
+  local trait=$(yq ".agents.${agent_name}.trait // \"\"" "$theme_file")
+  [ -n "$trait" ] && [ "$trait" != "null" ] && [ "$trait" != "" ] && echo "Trait: $trait"
+
+  local quirk=$(yq ".agents.${agent_name}.quirk // \"\"" "$theme_file")
+  [ -n "$quirk" ] && [ "$quirk" != "null" ] && [ "$quirk" != "" ] && echo "Quirk: $quirk"
+
+  local motto=$(yq ".agents.${agent_name}.motto // \"\"" "$theme_file")
+  [ -n "$motto" ] && [ "$motto" != "null" ] && [ "$motto" != "" ] && echo "Motto: $motto"
+
+  local quote=$(yq ".agents.${agent_name}.quote // \"\"" "$theme_file")
+  [ -n "$quote" ] && [ "$quote" != "null" ] && [ "$quote" != "" ] && echo "Quote: $quote"
+
+  # Helper info
+  local helper_name=$(yq ".agents.${agent_name}.helper.name // \"\"" "$theme_file")
+  local helper_style=$(yq ".agents.${agent_name}.helper.style // \"\"" "$theme_file")
+  if [ -n "$helper_name" ] && [ "$helper_name" != "null" ] && [ "$helper_name" != "" ]; then
+    echo "Helper: ${helper_name} - ${helper_style}"
+  fi
+
+  echo "</persona>"
+
+  # Output portrait path if available (for Claude to read with Read tool)
+  local portrait_path=$(node "$PROJECT_ROOT/scripts/resolve-portrait.mjs" "$theme" "$agent_name" 2>/dev/null)
+  if [ -n "$portrait_path" ] && [ -f "$portrait_path" ]; then
+    echo ""
+    echo "<portrait>$portrait_path</portrait>"
+  fi
+
+  # Output user title if defined
+  local user_title=$(yq ".theme.user_title // \"\"" "$theme_file" 2>/dev/null)
+  if [ -n "$user_title" ] && [ "$user_title" != "null" ] && [ "$user_title" != "" ]; then
+    echo ""
+    echo "<user-title>Address the user as: ${user_title}</user-title>"
+  fi
+
+  # Output crew manifest so agents know other characters
+  echo ""
+  echo "<crew theme=\"${theme}\">"
+  echo "When handing off to other agents, address them by character name:"
+  for role in sm tea dev reviewer architect pm tech-writer ux-designer devops orchestrator; do
+    local char=$(yq ".agents.${role}.character // \"\"" "$theme_file" 2>/dev/null)
+    if [ -n "$char" ] && [ "$char" != "null" ] && [ "$char" != "" ]; then
+      printf "  %-12s %s\n" "${role}:" "$char"
+    fi
+  done
+  echo "</crew>"
+}
+
+case "$1" in
+  start)
+    if [ -z "$2" ]; then
+      echo "Usage: agent-session.sh start \"agent-name\" [session-id]" >&2
+      exit 1
+    fi
+    # Use provided session ID, fall back to SESSION_ID env var, then generate one
+    session_id="${3:-$SESSION_ID}"
+    if [ -z "$session_id" ]; then
+      # Generate a session ID if not provided (for fresh sessions)
+      session_id=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || date +%s)
+    fi
+    mkdir -p "$AGENTS_DIR"
+
+    # Clean up old session files (older than 7 days) to prevent accumulation
+    find "$AGENTS_DIR" -type f -mtime +7 -delete 2>/dev/null || true
+
+    AGENT_FILE=$(get_agent_file "$session_id")
+    echo "$2" > "$AGENT_FILE"
+    echo "Session: $session_id -> $2"
+
+    # Output persona on start (unless character_voice is disabled)
+    if is_character_voice_enabled; then
+      output_persona "$2"
+    fi
+
+    # Auto-prime context after persona (reduces cold-start overhead)
+    # Pass agent name so prime can load agent-specific sidecar
+    if [[ -f "$PROJECT_ROOT/.pennyfarthing/scripts/prime.sh" ]]; then
+      "$PROJECT_ROOT/.pennyfarthing/scripts/prime.sh" --quiet --agent "$2"
+    fi
+    ;;
+  stop)
+    # Use provided session ID, fall back to SESSION_ID env var
+    session_id="${2:-$SESSION_ID}"
+    if [ -z "$session_id" ]; then
+      echo "Usage: agent-session.sh stop [session-id]" >&2
+      exit 1
+    fi
+
+    # Get current agent for this session
+    AGENT_FILE=$(get_agent_file "$session_id")
+    CURRENT_AGENT=""
+    if [ -f "$AGENT_FILE" ]; then
+      CURRENT_AGENT=$(cat "$AGENT_FILE")
+    fi
+
+    # Validate handoff was spawned (Story 31-16: Enforce handoff subagent spawning)
+    # Only check for agents that require handoff (tea, dev, reviewer)
+    if [[ "$CURRENT_AGENT" =~ ^(tea|dev|reviewer)$ ]]; then
+      # Find active session file
+      SESSION_DIR="$PROJECT_ROOT/.session"
+      ACTIVE_SESSION=$(find "$SESSION_DIR" -maxdepth 1 -name "*-session.md" -type f ! -name "context-*" 2>/dev/null | head -1)
+
+      if [ -n "$ACTIVE_SESSION" ] && [ -f "$ACTIVE_SESSION" ]; then
+        # Map agent to expected assessment section
+        case "$CURRENT_AGENT" in
+          tea) EXPECTED_SECTION="TEA Assessment" ;;
+          dev) EXPECTED_SECTION="Dev Assessment" ;;
+          reviewer) EXPECTED_SECTION="Reviewer Assessment" ;;
+        esac
+
+        # Check if assessment exists
+        HAS_ASSESSMENT=$(grep -q "## $EXPECTED_SECTION" "$ACTIVE_SESSION" 2>/dev/null && echo "yes" || echo "no")
+
+        # Check if handoff was recorded in Handoff History table
+        # Table format: | From | To | Phase | Gate | Timestamp |
+        # Agent must appear in "From" column (first data column) to indicate they completed handoff
+        HAS_HANDOFF="no"
+
+        # Check for agent in "From" column (starts with "| agent |")
+        # Case-insensitive match for the agent name at start of row
+        if grep -Ei "^\| *$CURRENT_AGENT *\|" "$ACTIVE_SESSION" 2>/dev/null; then
+          HAS_HANDOFF="yes"
+        fi
+
+        # Also check for CYCLIST:HANDOFF marker (handoff output)
+        if [ "$HAS_HANDOFF" = "no" ] && grep -q "CYCLIST:HANDOFF" "$ACTIVE_SESSION" 2>/dev/null; then
+          HAS_HANDOFF="yes"
+        fi
+
+        # Warn if assessment exists but handoff is missing
+        if [ "$HAS_ASSESSMENT" = "yes" ] && [ "$HAS_HANDOFF" = "no" ]; then
+          echo "" >&2
+          echo "WARNING: Handoff subagent was not spawned!" >&2
+          echo "" >&2
+          echo "  Agent: $CURRENT_AGENT" >&2
+          echo "  Assessment: Found ($EXPECTED_SECTION)" >&2
+          echo "  Handoff: NOT FOUND" >&2
+          echo "" >&2
+          echo "  You MUST spawn handoff before stopping:" >&2
+          echo "" >&2
+          echo "    Task tool:" >&2
+          echo "      subagent_type: \"handoff\"" >&2
+          echo "      prompt: |" >&2
+          echo "        STORY_ID: {story-id}" >&2
+          echo "        WORKFLOW: {workflow}" >&2
+          echo "        CURRENT_PHASE: {phase}" >&2
+          echo "        ..." >&2
+          echo "" >&2
+          echo "  Session: $(basename "$ACTIVE_SESSION")" >&2
+          echo "" >&2
+          # Exit non-zero to signal incomplete handoff
+          exit 1
+        fi
+      fi
+    fi
+
+    # Clear the agent file for this session
+    rm -f "$AGENT_FILE" 2>/dev/null
+    echo "Agent session closed: $session_id"
+    ;;
+  stop-all)
+    rm -rf "$AGENTS_DIR" 2>/dev/null
+    echo "All agent sessions closed."
+    ;;
+  status)
+    # Read JSON from stdin (Claude Code statusLine passes context)
+    input=$(cat)
+
+    # Get session ID from input
+    session_id=""
+    if command -v jq &>/dev/null && [ -n "$input" ]; then
+      session_id=$(echo "$input" | jq -r '.session_id // empty' 2>/dev/null)
+    fi
+
+    # Get agent name for this session
+    if [ -n "$session_id" ]; then
+      AGENT_FILE=$(get_agent_file "$session_id")
+      if [ -f "$AGENT_FILE" ]; then
+        AGENT=$(cat "$AGENT_FILE")
+      else
+        AGENT=""
+      fi
+    else
+      AGENT=""
+    fi
+
+    # Output just the agent name (statusline.sh handles the rest)
+    echo "$AGENT"
+    ;;
+  list)
+    # List all active agent sessions
+    if [ -d "$AGENTS_DIR" ]; then
+      for f in "$AGENTS_DIR"/*; do
+        [ -f "$f" ] && echo "$(basename "$f"): $(cat "$f")"
+      done
+    else
+      echo "No active sessions"
+    fi
+    ;;
+  refresh)
+    # Re-output persona for current agent (after theme change)
+    # Usage: agent-session.sh refresh [session-id]
+    session_id="${2:-$SESSION_ID}"
+    if [ -z "$session_id" ]; then
+      echo "Usage: agent-session.sh refresh [session-id]" >&2
+      exit 1
+    fi
+
+    AGENT_FILE=$(get_agent_file "$session_id")
+    if [ ! -f "$AGENT_FILE" ]; then
+      echo "No active session: $session_id" >&2
+      exit 1
+    fi
+
+    CURRENT_AGENT=$(cat "$AGENT_FILE")
+    echo "Refreshing persona for: $CURRENT_AGENT"
+
+    if is_character_voice_enabled; then
+      output_persona "$CURRENT_AGENT"
+    else
+      echo "Character voice disabled - no persona to refresh"
+    fi
+    ;;
+  *)
+    echo "Usage: agent-session.sh <start|stop|stop-all|status|list|refresh> [args]" >&2
+    echo "  start \"agent\" \"session-id\"  - Register agent for session" >&2
+    echo "  stop \"session-id\"            - Remove agent for session" >&2
+    echo "  stop-all                      - Remove all agent sessions" >&2
+    echo "  status                        - Get agent for session (reads JSON stdin)" >&2
+    echo "  list                          - List all active sessions" >&2
+    echo "  refresh \"session-id\"         - Re-output persona after theme change" >&2
+    exit 1
+    ;;
+esac

package/pennyfarthing-dist/scripts/core/check-context.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env zsh
+# check-context.sh - Check current Claude Code context usage
+# Returns: percentage and recommendation for handoff
+#
+# Usage:
+#   ./check-context.sh                    # Output env vars (most recent transcript)
+#   ./check-context.sh --human            # Human-readable output
+#   ./check-context.sh --session <id>     # Check specific session transcript
+#   SESSION_ID=<id> ./check-context.sh    # Alternative: session via env var
+#   eval $(./check-context.sh)            # Load vars into shell
+
+# Parse command line arguments
+HUMAN_MODE=false
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --human)
+            HUMAN_MODE=true
+            shift
+            ;;
+        --session)
+            SESSION_ID="$2"
+            shift 2
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Derive Claude project path from current directory
+# Claude Code stores transcripts at ~/.claude/projects/<path-with-dashes>
+# The path format is: -Users-name-Projects-project (leading dash, all slashes become dashes)
+PROJECT_DIR="${PROJECT_ROOT:-$(pwd)}"
+CLAUDE_PROJECT_PATH="$HOME/.claude/projects/$(echo "$PROJECT_DIR" | tr '/' '-')"
+
+# Default thresholds (can be overridden by settings.local.json)
+DEFAULT_IMMINENT_THRESHOLD=65
+DEFAULT_WARNING_THRESHOLD=60
+DEFAULT_CRITICAL_THRESHOLD=85
+DEFAULT_MAX_TOKENS=200000
+
+# Load thresholds and permission_mode from .pennyfarthing/config.local.yaml (preferred) or settings.local.json (fallback)
+PENNYFARTHING_CONFIG="${CLAUDE_PROJECT_DIR:-$PROJECT_DIR}/.pennyfarthing/config.local.yaml"
+SETTINGS_FILE="${CLAUDE_PROJECT_DIR:-$PROJECT_DIR}/.claude/settings.local.json"
+CONFIG=$(python3 -c "
+import json
+import sys
+
+imminent_threshold = $DEFAULT_IMMINENT_THRESHOLD
+warning_threshold = $DEFAULT_WARNING_THRESHOLD
+critical_threshold = $DEFAULT_CRITICAL_THRESHOLD
+max_tokens = $DEFAULT_MAX_TOKENS
+permission_mode = 'manual'  # Default to manual
+
+# First try .pennyfarthing/config.local.yaml (preferred location)
+try:
+    import yaml
+    with open('$PENNYFARTHING_CONFIG', 'r') as f:
+        config = yaml.safe_load(f)
+        if config:
+            if 'context_budget' in config:
+                cb = config['context_budget']
+                imminent_threshold = cb.get('imminent_threshold', imminent_threshold)
+                warning_threshold = cb.get('warning_threshold', warning_threshold)
+                critical_threshold = cb.get('critical_threshold', critical_threshold)
+                max_tokens = cb.get('max_tokens', max_tokens)
+            # Read permission_mode from workflow section
+            if 'workflow' in config and 'permission_mode' in config['workflow']:
+                permission_mode = config['workflow']['permission_mode']
+except:
+    # Fallback to settings.local.json (legacy location)
+    try:
+        with open('$SETTINGS_FILE', 'r') as f:
+            settings = json.load(f)
+            if 'context_budget' in settings:
+                cb = settings['context_budget']
+                imminent_threshold = cb.get('imminent_threshold', imminent_threshold)
+                warning_threshold = cb.get('warning_threshold', warning_threshold)
+                critical_threshold = cb.get('critical_threshold', critical_threshold)
+                max_tokens = cb.get('max_tokens', max_tokens)
+            if 'workflow' in settings and 'permission_mode' in settings['workflow']:
+                permission_mode = settings['workflow']['permission_mode']
+    except:
+        pass
+
+print(f'IMMINENT_THRESHOLD={imminent_threshold}')
+print(f'WARNING_THRESHOLD={warning_threshold}')
+print(f'CRITICAL_THRESHOLD={critical_threshold}')
+print(f'MAX_TOKENS={max_tokens}')
+print(f'PERMISSION_MODE={permission_mode}')
+" 2>/dev/null)
+
+# Apply config or use defaults
+eval "$CONFIG" 2>/dev/null || {
+    IMMINENT_THRESHOLD=$DEFAULT_IMMINENT_THRESHOLD
+    WARNING_THRESHOLD=$DEFAULT_WARNING_THRESHOLD
+    CRITICAL_THRESHOLD=$DEFAULT_CRITICAL_THRESHOLD
+    MAX_TOKENS=$DEFAULT_MAX_TOKENS
+}
+
+# Find transcript - either specific session or most recent
+if [ -n "$SESSION_ID" ]; then
+    # Session-specific: look for transcript with matching session ID
+    TRANSCRIPT="$CLAUDE_PROJECT_PATH/${SESSION_ID}.jsonl"
+    if [ ! -f "$TRANSCRIPT" ]; then
+        if [ "$HUMAN_MODE" = "true" ]; then
+            echo "⚠️  Context: unknown (session transcript not found: $SESSION_ID)"
+        else
+            echo "CONTEXT_ERROR=session_not_found"
+            echo "CONTEXT_SESSION=$SESSION_ID"
+        fi
+        exit 1
+    fi
+else
+    # Default: find most recent transcript (current session)
+    TRANSCRIPT=$(ls -t "$CLAUDE_PROJECT_PATH"/*.jsonl 2>/dev/null | grep -v "agent-" | head -1)
+    if [ -z "$TRANSCRIPT" ]; then
+        if [ "$HUMAN_MODE" = "true" ]; then
+            echo "⚠️  Context: unknown (no transcript found)"
+        else
+            echo "CONTEXT_ERROR=no_transcript"
+        fi
+        exit 1
+    fi
+fi
+
+# Parse transcript for baseline (first turn) and current (last turn) usage data
+# Baseline = system prompt overhead, cached per session
+# Usable = current - baseline (what the user's conversation has consumed)
+RESULT=$(python3 -c "
+import sys
+import json
+
+warning_threshold = $WARNING_THRESHOLD
+max_tokens = $MAX_TOKENS
+permission_mode = '$PERMISSION_MODE'
+tirepump_threshold = 60  # Threshold for TirePump auto-handoff
+
+with open('$TRANSCRIPT', 'r') as f:
+    lines = f.readlines()
+
+# Find first and last lines with usage data
+first_total = None
+last_total = None
+
+for line in lines:
+    try:
+        data = json.loads(line.strip())
+        if 'message' in data and 'usage' in data['message']:
+            usage = data['message']['usage']
+            input_t = usage.get('input_tokens', 0)
+            cache_read = usage.get('cache_read_input_tokens', 0)
+            cache_create = usage.get('cache_creation_input_tokens', 0)
+            total = cache_read + cache_create + input_t
+
+            if first_total is None:
+                first_total = total
+            last_total = total
+    except:
+        continue
+
+if last_total is not None:
+    # Baseline is first turn's total (system prompt + tools + CLAUDE.md etc)
+    baseline = first_total if first_total is not None else 0
+
+    # Usable tokens = what user's conversation has consumed
+    usable_tokens = last_total - baseline
+
+    # Available capacity = max minus baseline overhead
+    available_capacity = max_tokens - baseline
+
+    # Usable percent = conversation usage as % of available capacity
+    usable_pct = (usable_tokens / available_capacity * 100) if available_capacity > 0 else 0
+
+    # Total percent (for backwards compatibility)
+    total_pct = (last_total / max_tokens) * 100
+
+    # Output all values
+    print(f'CONTEXT_TOKENS={last_total}')
+    print(f'CONTEXT_PERCENT={total_pct:.0f}')
+    print(f'CONTEXT_BASELINE={baseline}')
+    print(f'CONTEXT_USABLE_TOKENS={usable_tokens}')
+    print(f'CONTEXT_USABLE_PERCENT={usable_pct:.0f}')
+    print(f'CONTEXT_AVAILABLE={available_capacity}')
+    print(f'PERMISSION_MODE={permission_mode}')
+
+    # Use usable percent for status decisions (more accurate for user)
+    if usable_pct > warning_threshold:
+        print('CONTEXT_STATUS=HIGH')
+        print('HANDOFF_MODE=auto')
+    else:
+        print('CONTEXT_STATUS=OK')
+        print('HANDOFF_MODE=ask')
+
+    # TirePump: Use CONTEXT_CLEAR (clear + load next agent) when:
+    # 1. permission_mode is 'turbo' (auto-handoff enabled)
+    # 2. context > 60% (tirepump_threshold)
+    # This enables continuous autonomous runs without manual intervention
+    use_tirepump = permission_mode == 'turbo' and usable_pct > tirepump_threshold
+    print(f'USE_TIREPUMP={str(use_tirepump).lower()}')
+
+    # Cyclist detection: Check if CYCLIST env var is set to '1'
+    # Markers should only be emitted when running inside Cyclist
+    import os
+    is_cyclist = os.environ.get('CYCLIST', '') == '1'
+    print(f'IS_CYCLIST={str(is_cyclist).lower()}')
+" 2>/dev/null)
+
+if [ "$HUMAN_MODE" = "true" ]; then
+    eval "$RESULT"
+    if [ "$USE_TIREPUMP" = "true" ]; then
+        echo "🔄 Context: ${CONTEXT_USABLE_PERCENT}% used (${CONTEXT_USABLE_TOKENS} of ${CONTEXT_AVAILABLE} available) - TIREPUMP (clear + next agent)"
+    elif [ "$CONTEXT_STATUS" = "HIGH" ]; then
+        echo "⚠️  Context: ${CONTEXT_USABLE_PERCENT}% used (${CONTEXT_USABLE_TOKENS} of ${CONTEXT_AVAILABLE} available) - AUTO-HANDOFF"
+    else
+        echo "✅ Context: ${CONTEXT_USABLE_PERCENT}% used (${CONTEXT_USABLE_TOKENS} of ${CONTEXT_AVAILABLE} available)"
+    fi
+    echo "   Overhead: ${CONTEXT_BASELINE} tokens (system prompt + tools)"
+    echo "   Mode: ${PERMISSION_MODE}"
+
+    # Output warning messages at configurable thresholds (use usable percent)
+    if [ -n "$CONTEXT_USABLE_PERCENT" ]; then
+        if [ "$CONTEXT_USABLE_PERCENT" -ge "$CRITICAL_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING: Critical (${CONTEXT_USABLE_PERCENT}%) - checkpoint and handoff recommended"
+        elif [ "$CONTEXT_USABLE_PERCENT" -ge "$WARNING_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING: High (${CONTEXT_USABLE_PERCENT}%) - consider handoff soon"
+        fi
+    fi
+else
+    echo "$RESULT"
+
+    # Also output warnings in non-human mode for scripting (use usable percent)
+    eval "$RESULT" 2>/dev/null || true
+    if [ -n "$CONTEXT_USABLE_PERCENT" ]; then
+        if [ "$CONTEXT_USABLE_PERCENT" -ge "$CRITICAL_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING=Critical"
+            echo "CONTEXT_RECOMMENDATION=checkpoint and handoff recommended"
+        elif [ "$CONTEXT_USABLE_PERCENT" -ge "$WARNING_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING=High"
+            echo "CONTEXT_RECOMMENDATION=consider handoff soon"
+        fi
+    fi
+fi