@pennyfarthing/core 11.2.0 → 11.2.1

package/pennyfarthing-dist/gates/tests-pass.md

@@ -0,0 +1,79 @@
+<gate name="tests-pass" model="haiku">
+
+<purpose>
+Verify that all tests pass and the working tree is clean before handing off
+to the reviewer. This gate runs after the Dev agent's implementation phase
+to confirm the codebase is in a GREEN state.
+</purpose>
+
+<pass>
+Run these checks and report results:
+
+1. **Test suite:** Run the project test suite for the repos listed in the session file.
+   - For `pennyfarthing` repo: `cd pennyfarthing && pnpm test`
+   - For `orchestrator` repo: tests in the orchestrator root if applicable
+   - Record: total tests, passed, failed, skipped
+
+2. **Working tree:** Run `git status --porcelain` in each repo listed in session `**Repos:**`.
+   - Verify no uncommitted or untracked files (empty output = clean)
+
+3. **Branch status:** Run `git branch --show-current` and `git log --oneline -1`.
+   - Confirm on the expected feature branch from session `**Branch:**`
+
+If ALL checks pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: tests-pass
+  message: "All {N} tests passing. Working tree clean. Branch: {branch}"
+  checks:
+    - name: test-suite
+      status: pass
+      detail: "{passed}/{total} tests passing ({skipped} skipped)"
+    - name: working-tree
+      status: pass
+      detail: "No uncommitted changes"
+    - name: branch-status
+      status: pass
+      detail: "On branch {branch}, HEAD at {short-sha}"
+```
+</pass>
+
+<fail>
+If ANY check fails, diagnose and report:
+
+1. **Failing tests:** List each failing test file and line number.
+   - Run tests with verbose output to capture failure details.
+   - Group failures by file.
+
+2. **Dirty working tree:** List uncommitted and untracked files.
+   - Run `git status --porcelain` and report each file with its status code.
+
+3. **Wrong branch:** Report actual vs expected branch name.
+
+Return with actionable recovery guidance:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: tests-pass
+  message: "Gate failed: {summary of failures}"
+  checks:
+    - name: test-suite
+      status: pass | fail
+      detail: "{description of test results or failures}"
+    - name: working-tree
+      status: pass | fail
+      detail: "{list of uncommitted files, or 'clean'}"
+    - name: branch-status
+      status: pass | fail
+      detail: "{branch info or mismatch details}"
+  recovery:
+    - "Fix failing tests in: {file1}, {file2}"
+    - "Commit or stash uncommitted changes before handoff"
+    - "Switch to correct branch: git checkout {expected-branch}"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/guides/agent-behavior.md

@@ -49,7 +49,7 @@ On activation, check session file for a `**Tandem:**` line (e.g., `**Tandem:** a
 
 **If tandem is configured:**
 
-1. **Resolve backseat persona** from theme:
+1. **Resolve backseat persona** from theme using the `pf theme`
    ```bash
    THEME=$(yq '.theme' .pennyfarthing/config.local.yaml)
    PARTNER_CHARACTER=$(yq ".agents.{PARTNER}.character" .pennyfarthing/personas/themes/${THEME}.yaml)
@@ -98,16 +98,17 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 ## Reflector
 
 <critical>
-**EVERY TURN MUST END WITH A CYCLIST MARKER.** Stop hook enforces this.
-
-| Situation | Marker |
-|-----------|--------|
-| Workflow handoff | `<!-- CYCLIST:HANDOFF:/agent -->` |
-| Handoff + context >80% | `<!-- CYCLIST:CONTEXT_CLEAR:/agent -->` |
-| Yes/no question | `<!-- CYCLIST:QUESTION:yesno -->` |
-| Open-ended question | `<!-- CYCLIST:QUESTION:open -->` |
-| Multiple choice | `<!-- CYCLIST:CHOICES:a,b,c -->` |
-| Everything else | `<!-- CYCLIST:CONTINUE -->` |
+**Cyclist only:** EVERY TURN MUST END WITH A CYCLIST MARKER. Stop hook enforces this.
+**CLI mode:** Do NOT emit CYCLIST markers — they are inert outside Cyclist.
+
+| Situation | Cyclist Marker | CLI Behavior |
+|-----------|---------------|--------------|
+| Workflow handoff | `<!-- CYCLIST:HANDOFF:/agent -->` | Use AGENT_COMMAND `action` field |
+| Handoff + context >80% | `<!-- CYCLIST:CONTEXT_CLEAR:/agent -->` | Tell user to `/clear` then run agent |
+| Yes/no question | `<!-- CYCLIST:QUESTION:yesno -->` | Ask user directly |
+| Open-ended question | `<!-- CYCLIST:QUESTION:open -->` | Ask user directly |
+| Multiple choice | `<!-- CYCLIST:CHOICES:a,b,c -->` | Ask user directly |
+| Everything else | `<!-- CYCLIST:CONTINUE -->` | (no marker needed) |
 </critical>
 
 ---
@@ -124,7 +125,12 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
    - If fail → fix issues, retry from step 3 (max 3 retries)
    - If pass → continue
 7. `pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}`
-8. `pf handoff marker {next_agent}` → emit marker → EXIT
+8. `pf handoff marker {next_agent}` → AGENT_COMMAND block
+9. **Act on AGENT_COMMAND:**
+   - Has `marker:` field → emit the CYCLIST marker (Cyclist path)
+   - `action: "inline_handoff"` → run `activation_command` via Bash, output result, adopt new agent identity
+   - `action: "tirepump_handoff"` → tell user: "Context is high. Run `/clear` then `{fallback}`"
+   - No action, no marker → output `fallback` text and EXIT
 
 **Agents drive exit directly — no handoff subagent.** Scripts handle routing and session updates atomically.
 </agent-exit-protocol>
@@ -135,14 +141,12 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 On activation, check if story phase belongs to you:
 
 ```bash
-OWNER=$(pf workflow phase-check {workflow} {phase})
-# If OWNER != your agent → emit handoff marker and EXIT
+pf handoff phase-check {your_agent_name}
 ```
 
-Output:
-```
-<!-- CYCLIST:HANDOFF:/{OWNER} -->
+If result has `action: "redirect"`:
 
-Run `/pf-{OWNER}` to continue
-```
+- **Cyclist:** Emit `<!-- CYCLIST:HANDOFF:/{phase_owner} -->` and EXIT
+- **CLI + relay ON:** Run `pf agent start {phase_owner} --tier handoff --quiet` via Bash, adopt new identity
+- **CLI + relay OFF:** Output `Run /pf-{phase_owner} to continue` and EXIT
 </wrong-phase-detection>

package/pennyfarthing-dist/guides/bell-mode.md

@@ -26,7 +26,7 @@ User queues message in Editor
 |------|---------|
 | `packages/cyclist/src/bell-mode.ts` | State management: `isBellModeEnabled()`, `setBellMode()`, `toggleBellMode()` |
 | `packages/cyclist/src/api/bell.ts` | WebSocket broadcast of bell-consumed events |
-| `pennyfarthing-dist/scripts/hooks/bell-mode-hook.sh` | PostToolUse hook — reads queue, returns `additionalContext` |
+| `pf hooks bell-mode` | PostToolUse hook — reads queue, returns `additionalContext` |
 | `packages/cyclist/src/public/hooks/useMessageQueue.ts` | React hook: `queueMessage()`, `dequeueMessage()`, `injectMessage()`, `handleTurnComplete()` |
 | `packages/cyclist/src/public/contexts/MessageQueueContext.tsx` | Shared React context (single queue instance across components) |
 | `packages/cyclist/src/public/components/ControlBar.tsx` | Bell mode toggle button |

package/pennyfarthing-dist/guides/hooks.md

@@ -4,7 +4,7 @@ Pennyfarthing uses Claude Code hooks to integrate with session lifecycle events
 
 ## Overview
 
-Hooks are shell scripts that Claude Code runs at specific events:
+Hooks are commands that Claude Code runs at specific events:
 
 | Hook Type | When It Runs | Purpose |
 |-----------|--------------|---------|
@@ -16,18 +16,18 @@ Hooks are shell scripts that Claude Code runs at specific events:
 
 ### SessionStart Hooks
 
-#### session-start.sh
+#### pf hooks session-start
 
-**Location:** `.pennyfarthing/scripts/hooks/session-start.sh`
+**Location:** `pf hooks session-start`
 
 Initializes the Pennyfarthing environment:
 - Creates `.session/` directory structure
 - Clears stale agent state from previous sessions
 - Sets `PROJECT_ROOT` and `SESSION_ID` environment variables
 
-#### session-stop.sh
+#### pf hooks session-stop
 
-**Location:** `.pennyfarthing/scripts/hooks/session-stop.sh`
+**Location:** `pf hooks session-stop`
 
 Cleans up session state when Claude Code exits.
 
@@ -46,66 +46,66 @@ Project-specific environment setup. Edit this file to:
 
 Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.wheelhub-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
 
-#### welcome-hook.sh
+#### pf hooks session-start (welcome)
 
-**Location:** `.pennyfarthing/scripts/hooks/welcome-hook.sh`
+**Location:** `pf hooks session-start`
 
-Displays a welcome message on session start. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
+Welcome display is now folded into `pf hooks session-start`. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
 
 ### PreToolUse Hooks
 
-#### pre-edit-check.sh
+#### pf hooks pre-edit-check
 
-**Location:** `.pennyfarthing/scripts/hooks/pre-edit-check.sh`
+**Location:** `pf hooks pre-edit-check`
 
 Protects sensitive files from accidental edits:
 - Blocks: `.env`, `.pem`, `.key`, credentials, secrets
 - Blocks: `.git/`, `node_modules/`, `vendor/`
 - Blocks: `.pennyfarthing/*` (managed files)
 
-#### cyclist-pretooluse-hook.sh
+#### pf hooks cyclist-pretooluse
 
-**Location:** `.pennyfarthing/scripts/hooks/cyclist-pretooluse-hook.sh`
+**Location:** `pf hooks cyclist-pretooluse`
 
 Cyclist-specific pre-tool validation. Runs additional safety checks when operating inside Cyclist.
 
-#### context-warning.sh
+#### pf hooks context-warning
 
-**Location:** `.pennyfarthing/scripts/hooks/context-warning.sh`
+**Location:** `pf hooks context-warning`
 
 Warns agents when context usage is high. Outputs a warning at 60% usage and a critical warning at 85%. Never blocks — warning only (always exits 0).
 
-#### context-circuit-breaker.sh
+#### pf hooks context-breaker
 
-**Location:** `.pennyfarthing/scripts/hooks/context-circuit-breaker.sh`
+**Location:** `pf hooks context-breaker`
 
-Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `context-warning.sh`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
+Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `pf hooks context-warning`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
 
-#### schema-validation.sh
+#### pf hooks schema-validation
 
-**Location:** `.pennyfarthing/scripts/hooks/schema-validation.sh`
+**Location:** `pf hooks schema-validation`
 
 Validates file writes against XML schema rules for agent definitions, workflow files, and other structured content.
 
-#### sprint-yaml-validation.sh
+#### pf hooks sprint-yaml
 
-**Location:** `.pennyfarthing/scripts/hooks/sprint-yaml-validation.sh`
+**Location:** `pf hooks sprint-yaml`
 
 Validates sprint YAML files on write to prevent structural corruption.
 
 ### PostToolUse Hooks
 
-#### bell-mode-hook.sh
+#### pf hooks bell-mode
 
-**Location:** `.pennyfarthing/scripts/hooks/bell-mode-hook.sh`
+**Location:** `pf hooks bell-mode`
 
 Bell mode message injection. Checks the bell mode queue and injects queued messages into the agent's context at the next tool execution. Also handles tandem observation injection.
 
-#### question-reflector-check.sh / question_reflector_check.py
+#### pf hooks reflector-check
 
-**Location:** `.pennyfarthing/scripts/hooks/question-reflector-check.sh`
+**Location:** `pf hooks reflector-check`
 
-Stop hook enforcing that every agent turn ends with a CYCLIST marker. Detects questions, handoff phrases, and validates marker presence. Blocks turns without valid markers in Cyclist mode. The `.sh` file wraps the Python implementation.
+Stop hook enforcing that every agent turn ends with a CYCLIST marker. Detects questions, handoff phrases, and validates marker presence. Blocks turns without valid markers in Cyclist mode.
 
 ### Git Hooks
 
@@ -133,7 +133,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/session-start.sh"
+            "command": "pf hooks session-start"
           }
         ]
       }
@@ -144,7 +144,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/pre-edit-check.sh"
+            "command": "pf hooks pre-edit-check"
           }
         ]
       }

package/pennyfarthing-dist/guides/reflector.md

@@ -41,7 +41,7 @@ Marker pattern: /<!--\s*CYCLIST:(\w+)(?::([^>]+?))?\s*-->/gi
 | `packages/cyclist/src/public/components/QuickActions.tsx` | Renders action buttons from detected markers |
 | `packages/cyclist/src/public/hooks/useMarkerActions.ts` | Detects markers, builds action metadata |
 | `pennyfarthing-dist/scripts/hooks/question_reflector_check.py` | Stop hook — enforces marker presence |
-| `pennyfarthing-dist/scripts/hooks/question-reflector-check.sh` | Bash wrapper for stop hook |
+| `pf hooks reflector-check` | CLI entry point for stop hook |
 
 ## Enforcement Hook
 

package/pennyfarthing-dist/guides/tandem-protocol.md

@@ -13,7 +13,7 @@ Primary Agent (Opus)          Backseat Agent (Haiku, background)
      │                              │   .session/{story}-tandem-{partner}.md
      │                              │
      ├── PostToolUse hook fires ────┤
-     │   bell-mode-hook.sh detects  │
+     │   pf hooks bell-mode detects │
      │   new observation, injects   │
      │   "[Tandem] Character: ..."  │
      │                              │
@@ -163,8 +163,8 @@ For active, synchronous agent-to-agent questions (as opposed to passive observat
 | `observation-writer.ts` | Built | TypeScript API for observation file I/O |
 | `file-watch.ts` | Built | File system change detection |
 | `tool-watch.ts` | Built | Tool call log monitoring |
-| `bell-mode-hook.sh` | Built | PostToolUse hook with tandem injection |
+| `pf hooks bell-mode` | Built | PostToolUse hook with tandem injection |
 | `bellmode_hook.py` | Built | Python implementation of bell mode hook |
-| `statusline.sh` | Built | CLI statusline with tandem indicator |
+| `pf hooks statusline` | Built | CLI statusline with tandem indicator |
 | `tandem-backseat.md` | Built | Backseat agent prompt template |
 | `agent-behavior.md` | Built | Shared agent behavior with tandem protocol |

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

@@ -12,6 +12,8 @@
 
 set -euo pipefail
 
+echo "DEPRECATED: check-context.sh — use 'pf context' instead" >&2
+
 # Find project root (where pennyfarthing_scripts lives)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 

package/pennyfarthing-dist/scripts/core/phase-check-start.sh

@@ -1,90 +1,8 @@
 #!/bin/bash
-# Start an agent with phase check
-# If the current story's phase belongs to a different agent, emit handoff marker instead
+# DEPRECATED: Use `pf handoff phase-check <agent>` instead.
+# This shim delegates to the Python implementation.
 #
-# Usage: .pennyfarthing/scripts/core/phase-check-start.sh <agent>
-# Example: phase-check-start.sh dev
+# Usage: phase-check-start.sh <agent>
 
-set -euo pipefail
-
-AGENT="${1:-}"
-
-if [[ -z "$AGENT" ]]; then
-  echo "Usage: phase-check-start.sh <agent>" >&2
-  exit 1
-fi
-
-# Self-locate and set up PROJECT_ROOT
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-source "$SCRIPT_DIR/../lib/find-root.sh"
-
-SCRIPTS_DIR="$SCRIPT_DIR/.."
-SESSION_DIR="$PROJECT_ROOT/.session"
-
-# Find active session file
-SESSION_FILE=$(find "$SESSION_DIR" -maxdepth 1 -name "*-session.md" 2>/dev/null | head -1)
-
-if [[ -z "$SESSION_FILE" || ! -f "$SESSION_FILE" ]]; then
-  # No session - just start the agent normally
-  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
-fi
-
-# Extract workflow and phase from session (handles multiple formats)
-# Format 1: **Workflow:** value
-# Format 2: - **Workflow**: value
-WORKFLOW=$(grep -E "\*\*Workflow\*?\*?:" "$SESSION_FILE" 2>/dev/null | head -1 | sed 's/.*\*\*Workflow\*\*[:\*]* *//' | tr -d ' ' || echo "")
-PHASE=$(grep -E "\*\*Phase\*?\*?:" "$SESSION_FILE" 2>/dev/null | head -1 | sed 's/.*\*\*Phase\*\*[:\*]* *//' | tr -d ' ' || echo "")
-
-if [[ -z "$WORKFLOW" ]]; then
-  # Can't determine workflow - start normally
-  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
-fi
-
-# If no Phase field, try to infer from status patterns
-if [[ -z "$PHASE" ]]; then
-  # Check for approval status (story is done, needs SM to close)
-  if grep -qE "\*\*Status\*\*:.*APPROVED" "$SESSION_FILE" 2>/dev/null; then
-    PHASE="approved"
-  # Check for review status
-  elif grep -qE "Reviewer Assessment|Review.*REJECTED\|Review.*APPROVED" "$SESSION_FILE" 2>/dev/null; then
-    PHASE="review"
-  # Check for green/implementation complete
-  elif grep -qE "Dev Assessment|\*\*Status\*\*:.*GREEN" "$SESSION_FILE" 2>/dev/null; then
-    # Has dev assessment - could be in review or approved
-    if grep -qE "Reviewer Assessment" "$SESSION_FILE" 2>/dev/null; then
-      PHASE="approved"  # Reviewer already assessed
-    else
-      PHASE="review"    # Needs reviewer
-    fi
-  # Check for red/test phase
-  elif grep -qE "TEA Assessment|\*\*Status\*\*:.*RED" "$SESSION_FILE" 2>/dev/null; then
-    PHASE="green"  # TEA done, Dev's turn
-  else
-    # Can't determine phase - start normally
-    exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
-  fi
-fi
-
-# Get the owner of this phase
-OWNER=$("$SCRIPTS_DIR/workflow/phase-owner.sh" "$WORKFLOW" "$PHASE" 2>/dev/null || echo "")
-
-if [[ -z "$OWNER" ]]; then
-  # Phase owner lookup failed - start normally
-  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
-fi
-
-# Check if this agent owns the phase
-if [[ "$OWNER" == "$AGENT" ]]; then
-  # Correct agent - start normally
-  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
-fi
-
-# Wrong agent! Output the handoff marker and info
-STORY_ID=$(basename "$SESSION_FILE" -session.md)
-
-echo "Phase check: Story $STORY_ID is in '$PHASE' phase (workflow: $WORKFLOW)"
-echo "Phase owner: $OWNER (you requested: $AGENT)"
-echo ""
-
-# Generate and output the handoff marker
-pf handoff marker "$OWNER"
+echo "DEPRECATED: phase-check-start.sh — use 'pf handoff phase-check $1' instead" >&2
+exec pf handoff phase-check "$@"

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

@@ -6,15 +6,15 @@ Git hooks and Claude Code hooks.
 
 | Script | Purpose |
 |--------|---------|
-| `context-circuit-breaker.sh` | Claude hook: halt at context limit |
-| `context-warning.sh` | Claude hook: warn on high context |
+| `pf hooks context-breaker` | Claude hook: halt at context limit |
+| `pf hooks context-warning` | Claude hook: warn on high context |
 | `otel-auto-config.sh` | Claude hook: configure OTEL |
 | `post-merge.sh` | Git hook: post-merge actions |
 | `pre-commit.sh` | Git hook: branch protection, agent validation, sprint YAML validation |
-| `pre-edit-check.sh` | Claude hook: validate before edit |
+| `pf hooks pre-edit-check` | Claude hook: validate before edit |
 | `pre-push.sh` | Git hook: pre-push validation |
-| `session-start.sh` | Claude hook: session start |
-| `session-stop.sh` | Claude hook: session stop |
+| `pf hooks session-start` | Claude hook: session start |
+| `pf hooks session-stop` | Claude hook: session stop |
 
 ## Installation
 

package/pennyfarthing-dist/scripts/hooks/bell-mode-hook.sh

@@ -1,183 +1,4 @@
-#!/bin/bash
-#
-# PostToolUse Hook — Bell Mode + Tandem Injection
-#
-# Called by Claude Code after each tool execution. Handles two independent
-# injection systems:
-#
-# 1. Bell queue (Cyclist only) — injects queued user messages when Cyclist
-#    is running and bell_mode is enabled. In CLI sessions this is a no-op.
-# 2. Tandem observations (always active) — injects backseat agent observations
-#    when tandem observation files exist. No configuration required.
-#
-# Bell queue takes precedence: if a queued message exists, tandem is
-# deferred to the next hook invocation.
-#
-# Output format (when injecting):
-#   {
-#     "hookSpecificOutput": {
-#       "hookEventName": "PostToolUse",
-#       "additionalContext": "<message>"
-#     }
-#   }
-#
-# Output when nothing to inject: (nothing - exit 0)
-
-# Find project root (walk up to find .pennyfarthing)
-PROJECT_ROOT="$PWD"
-while [[ "$PROJECT_ROOT" != "/" ]]; do
-  if [[ -d "$PROJECT_ROOT/.pennyfarthing" ]]; then
-    break
-  fi
-  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
-done
-
-if [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]]; then
-  exit 0
-fi
-
-CONFIG_LOCAL_YAML="$PROJECT_ROOT/.pennyfarthing/config.local.yaml"
-BELL_QUEUE_FILE="$PROJECT_ROOT/.pennyfarthing/bell-queue.json"
-
-# Detect Cyclist — bell queue is a Cyclist-only feature
-IS_CYCLIST=false
-CYCLIST_PORT=""
-PORT_FILE="$PROJECT_ROOT/.wheelhub-port"
-if [[ -f "$PORT_FILE" ]]; then
-  CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
-  if [[ -n "$CYCLIST_PORT" ]] && [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
-    IS_CYCLIST=true
-  fi
-fi
-
-# --- Bell queue check (Cyclist only, requires bell_mode: true) ---
-# Takes precedence over tandem injection when active.
-
-if [[ "$IS_CYCLIST" == "true" ]] && [[ -f "$CONFIG_LOCAL_YAML" ]]; then
-  BELL_ENABLED=$(grep -E '^\s*bell_mode:\s*true' "$CONFIG_LOCAL_YAML" 2>/dev/null || true)
-
-  if [[ -n "$BELL_ENABLED" ]] && [[ -f "$BELL_QUEUE_FILE" ]]; then
-    QUEUE_CONTENT=$(cat "$BELL_QUEUE_FILE" 2>/dev/null)
-    if [[ -n "$QUEUE_CONTENT" ]] && [[ "$QUEUE_CONTENT" != "[]" ]]; then
-      FIRST_MESSAGE_TEXT=$(echo "$QUEUE_CONTENT" | sed -n 's/.*"text"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
-
-      if [[ -n "$FIRST_MESSAGE_TEXT" ]]; then
-        cat << EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "PostToolUse",
-    "additionalContext": "User feedback: $FIRST_MESSAGE_TEXT"
-  }
-}
-EOF
-
-        # Dequeue and notify Cyclist in background
-        (
-          if command -v jq &> /dev/null; then
-            jq 'if length > 0 then .[1:] else [] end' "$BELL_QUEUE_FILE" > "$BELL_QUEUE_FILE.tmp" 2>/dev/null && mv "$BELL_QUEUE_FILE.tmp" "$BELL_QUEUE_FILE"
-          fi
-
-          curl -s -X POST "http://localhost:$CYCLIST_PORT/api/bell-consumed" \
-            -H "Content-Type: application/json" \
-            -d "{\"text\": \"$FIRST_MESSAGE_TEXT\"}" \
-            >/dev/null 2>&1 || true
-        ) &
-
-        exit 0
-      fi
-    fi
-  fi
-fi
-
-# --- Tandem observation injection ---
-# Always active. No configuration required.
-# Checks .session/*-tandem-*.md files for new observations via mtime comparison.
-
-SESSION_DIR="$PROJECT_ROOT/.session"
-if [[ ! -d "$SESSION_DIR" ]]; then
-  exit 0
-fi
-
-# Find tandem observation files
-TANDEM_FILES=$(find "$SESSION_DIR" -maxdepth 1 -name "*-tandem-*.md" 2>/dev/null)
-if [[ -z "$TANDEM_FILES" ]]; then
-  exit 0
-fi
-
-# Check each tandem file for new content
-for TANDEM_FILE in $TANDEM_FILES; do
-  # Extract agent name from filename: *-tandem-{agent}.md
-  AGENT=$(echo "$TANDEM_FILE" | sed -n 's/.*-tandem-\([a-zA-Z_]*\)\.md$/\1/p')
-  if [[ -z "$AGENT" ]]; then
-    continue
-  fi
-
-  # Get file mtime (portable: stat -f %m on macOS, stat -c %Y on Linux)
-  if [[ "$(uname)" == "Darwin" ]]; then
-    FILE_MTIME=$(stat -f %m "$TANDEM_FILE" 2>/dev/null)
-  else
-    FILE_MTIME=$(stat -c %Y "$TANDEM_FILE" 2>/dev/null)
-  fi
-  if [[ -z "$FILE_MTIME" ]]; then
-    continue
-  fi
-
-  # Compare with saved mtime sidecar
-  MTIME_SIDECAR="$SESSION_DIR/.tandem-mtime-$AGENT"
-  SAVED_MTIME="0"
-  if [[ -f "$MTIME_SIDECAR" ]]; then
-    SAVED_MTIME=$(cat "$MTIME_SIDECAR" 2>/dev/null)
-  fi
-
-  if [[ "$FILE_MTIME" == "$SAVED_MTIME" ]]; then
-    continue
-  fi
-
-  # Read tandem file and extract latest observation
-  CONTENT=$(cat "$TANDEM_FILE" 2>/dev/null)
-  if [[ -z "$CONTENT" ]]; then
-    continue
-  fi
-
-  # Extract persona from header: **Observer:** agent (Persona Name)
-  PERSONA=$(echo "$CONTENT" | sed -n 's/.*\*\*Observer:\*\*[[:space:]]*[a-zA-Z_]*[[:space:]]*(\([^)]*\)).*/\1/p' | head -1)
-  if [[ -z "$PERSONA" ]]; then
-    PERSONA="Unknown"
-  fi
-
-  # Extract latest observation text (last ## [HH:MM] Observation block)
-  # Get text between last observation header and trailing ---
-  OBS_TEXT=$(echo "$CONTENT" | awk '
-    /^## \[[0-9]+:[0-9]+\] Observation/ { found=1; text=""; next }
-    found && /^---/ { next }
-    found && /^\*\*Trigger:\*\*/ { next }
-    found { text = text (text ? "\n" : "") $0 }
-    END { if (text) print text }
-  ' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-
-  if [[ -z "$OBS_TEXT" ]]; then
-    # Update mtime even if no parseable observation
-    echo "$FILE_MTIME" > "$MTIME_SIDECAR"
-    continue
-  fi
-
-  # Format as [Tandem] prefix and output
-  TANDEM_MSG="[Tandem] $PERSONA: $OBS_TEXT"
-
-  cat << EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "PostToolUse",
-    "additionalContext": "$TANDEM_MSG"
-  }
-}
-EOF
-
-  # Save mtime sidecar
-  echo "$FILE_MTIME" > "$MTIME_SIDECAR"
-
-  # Only inject one tandem observation per hook invocation
-  exit 0
-done
-
-exit 0
+#!/usr/bin/env bash
+# DEPRECATED: This script is a shim. Logic has moved to Python.
+# Use: pf hooks bell-mode
+exec pf hooks bell-mode