Skip to content
Productivity
Hook

Hooks

What pua runs automatically, and when. A hook is a command Claude Code fires at a fixed moment, without you asking for it.

@tanweaitanweai@tanweai
From plugin
pua
19k13 skills7 agents22 commands7 hooks
Install
> /plugin marketplace add tanweai/pua
> /plugin install pua@pua-skills

Ships with pua. Installing the plugin gets these hooks.

What fires, and when

UserPromptSubmit

Fires before Claude sees each prompt you send. A plugin can use it to inject context, so the same instruction reaches the model every turn instead of only at session start.

  • bash "${CLAUDE_PLUGIN_ROOT}/hooks/frustration-trigger.sh"

PostToolUse

  • MatchesBashbash "${CLAUDE_PLUGIN_ROOT}/hooks/failure-detector.sh"

PreCompact

  • Matches*

SessionStart

Fires once when a session begins, and again after a context compaction. It is where a plugin sets up its environment, or restores state the compaction dropped.

  • Matchescompactbash "${CLAUDE_PLUGIN_ROOT}/hooks/heartbeat.sh"bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-restore.sh"
  • Matchesstartup|resumebash "${CLAUDE_PLUGIN_ROOT}/hooks/heartbeat.sh"bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-restore.sh"

Stop

  • Matches*bash "${CLAUDE_PLUGIN_ROOT}/hooks/pua-loop-hook.sh"bash "${CLAUDE_PLUGIN_ROOT}/hooks/stop-feedback.sh"

SubagentStop

  • Matches*bash "${CLAUDE_PLUGIN_ROOT}/hooks/subagent-teardown.sh"

PreToolUse

  • MatchesBash|Read|Grep|Glob|Edit|Write|MultiEdit|WebSearch|WebFetchbash "${CLAUDE_PLUGIN_ROOT}/hooks/integrity-guard.sh"
Read hooks/hooks.json

In the plugin's words

How pua describes its own hook set.

PUA v3 hooks: optional context notes, failure-pattern reminders, local state continuity, and cleanup helpers.

Where it lives

  • hooks/failure-detector.shRunsGitHub
    Read the script
    #!/bin/bash
# PUA PostToolUse hook: failure pattern analysis + de-escalation breakthrough detection
# Layer 1 of 3-layer detection: collect structured signals, inject pattern data for LLM analysis
#
# v2: Upgraded from simple counter to pattern-aware state machine
#   - Tracks error signatures (hash of last N errors) for pattern classification
#   - Detects SUCCESS after L2+ struggle → triggers de-escalation with flavor-aware recognition
#   - Injects error history into prompt so LLM can do semantic pattern analysis
#   - Flavor-specific breakthrough recognition messages

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "${SCRIPT_DIR}/flavor-helper.sh"
PUA_PY="$(pua_python_cmd 2>/dev/null || true)"

# Respect /pua:off — skip injection when always_on is false
PUA_CONFIG="$(pua_config_file)"
if [ -f "$PUA_CONFIG" ]; then
  ALWAYS_ON=$(pua_json_get "$PUA_CONFIG" always_on True)
  if [ "$ALWAYS_ON" = "False" ]; then
    exit 0
  fi
fi

get_flavor

PUA_DIR="${HOME:-~}/.pua"
COUNTER_FILE="${PUA_DIR}/.failure_count"
SESSION_FILE="${PUA_DIR}/.failure_session"
# v2: error history for pattern analysis
ERROR_HISTORY_FILE="${PUA_DIR}/.error_history.jsonl"
PEAK_LEVEL_FILE="${PUA_DIR}/.peak_pressure_level"
mkdir -p "${PUA_DIR}"

# Read hook input
HOOK_INPUT=$(cat)

# Only process Bash tool results
TOOL_NAME=$(echo "$HOOK_INPUT" | "${PUA_PY:-python3}" -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null || echo "")
if [ "$TOOL_NAME" != "Bash" ]; then
  exit 0
fi

# Extract tool result and exit code
TOOL_RESULT=$(echo "$HOOK_INPUT" | "${PUA_PY:-python3}" -c "
import sys, json
data = json.load(sys.stdin)
result = data.get('tool_result', '')
if isinstance(result, dict):
    result = result.get('content', result.get('text', str(result)))
print(str(result)[:2000])
" 2>/dev/null || echo "")

EXIT_CODE=$(echo "$HOOK_INPUT" | "${PUA_PY:-python3}" -c "
import sys, json
data = json.load(sys.stdin)
result = data.get('tool_result', {})
if isinstance(result, dict):
    print(result.get('exit_code', result.get('exitCode', 0)))
else:
    print(0)
" 2>/dev/null || echo "0")

IS_ERROR="false"

# Exit code is the PRIMARY signal — it's deterministic and reliable.
# Text grep is SECONDARY and only applies when exit_code is non-zero.
# This prevents false positives like "0 failed" or "no error" being flagged.
if [ "$EXIT_CODE" != "0" ] && [ "$EXIT_CODE" != "" ]; then
  IS_ERROR="true"
elif echo "$TOOL_RESULT" | grep -qiE '^error:|^fatal:|^panic:|Traceback \(most recent|Exception:|command not found|No such file or directory|Permission denied'; then
  # Only check text patterns when exit_code is 0 but output contains unambiguous error markers
  # These patterns are anchored (^) or specific enough to avoid false positives
  IS_ERROR="true"
fi

# Track session: reset counter if new session
CURRENT_SESSION=$(echo "$HOOK_INPUT" | "${PUA_PY:-python3}" -c "import sys,json; print(json.load(sys.stdin).get('session_id','unknown'))" 2>/dev/null || echo "unknown")
STORED_SESSION=""
[ -f "$SESSION_FILE" ] && STORED_SESSION=$(cat "$SESSION_FILE" 2>/dev/null || echo "")

if [ "$CURRENT_SESSION" != "$STORED_SESSION" ]; then
  echo "0" > "$COUNTER_FILE"
  echo "0" > "$PEAK_LEVEL_FILE"
  : > "$ERROR_HISTORY_FILE"
  echo "$CURRENT_SESSION" > "$SESSION_FILE"
fi

# Read current count
COUNT=0
[ -f "$COUNTER_FILE" ] && COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
[ -z "$COUNT" ] && COUNT=0

# Read peak pressure level reached this session
PEAK_LEVEL=0
[ -f "$PEAK_LEVEL_FILE" ] && PEAK_LEVEL=$(cat "$PEAK_LEVEL_FILE" 2>/dev/null || echo "0")
[ -z "$PEAK_LEVEL" ] && PEAK_LEVEL=0

# ═══════════════════════════════════════════════════════
# v2: DE-ESCALATION — Success after L2+ struggle
# ═══════════════════════════════════════════════════════
if [ "$IS_ERROR" = "false" ]; then
  if [ "$COUNT" -ge 3 ] && [ "$PEAK_LEVEL" -ge 2 ]; then
    # ★ BREAKTHROUGH detected: success after sustained struggle
    # Record the breakthrough event
    echo "{\"ts\":$(date +%s),\"event\":\"breakthrough\",\"from_level\":$PEAK_LEVEL,\"after_failures\":$COUNT}" >> "$ERROR_HISTORY_FILE" 2>/dev/null || true

    # Reset pressure state
    echo "0" > "$COUNTER_FILE"
    echo "0" > "$PEAK_LEVEL_FILE"

    # Flavor-aware de-escalation recognition
    case "$PUA_FLAVOR" in
      alibaba)
        DE_ESCALATION_MSG="这才是 Owner 该有的样子。3.75 打底。现在复盘一下：刚才卡了 ${COUNT} 次，根因是什么？把正确路径写下来，下次直达。这叫**沉淀方法论**。"
        ;;
      bytedance)
        DE_ESCALATION_MSG="结果到位了。ROI 翻正。现在做一件事：把刚才有效的方法提炼成 SOP，写到 memory 里。数据驱动不是说说——你刚经历的 ${COUNT} 次失败就是数据，别浪费。"
        ;;
      huawei)
        DE_ESCALATION_MSG="军令状完成。烧不死的鸟是凤凰——你刚证明了自己烧不死。现在按自我批判流程复盘：哪个假设一开始就是错的？哪个应该更早排除？写入经验库。胜则举杯相庆。"
        ;;
      tencent)
        DE_ESCALATION_MSG="赛马跑出来了。你赢了这条赛道。现在做灰度验证——确认结果可复现、边界清楚。然后把这套打法沉淀下来，下次小步快跑直接跑通。"
        ;;
      baidu)
        DE_ESCALATION_MSG="搜索 + 深挖有效果了。基本盘守住了。现在把搜索路径和关键发现记录下来——简单可依赖的前提是路径可复用。"
        ;;
      pinduoduo)
        DE_ESCALATION_MSG="本分做到了。结果出来了就是硬核。现在回头看：${COUNT} 次失败里有多少步是可以砍掉的？极致效率 = 下次零弯路。"
        ;;
      meituan)
        DE_ESCALATION_MSG="做难而正确的事，你做到了。猛将发于卒伍——这次卡住就是你的卒伍。现在苦练基本功：把解题路径标准化，下次遇到同类直接套。"
        ;;
      jd)
        DE_ESCALATION_MSG="结果拿到了。这才是兄弟该有的执行力。正道成功——过程虽然硬，但路子是对的。现在沉淀下来，让下一个兄弟不用再走这些弯路。"
        ;;
      xiaomi)
        DE_ESCALATION_MSG="极致！这次交付够极致。和用户交朋友的前提是你真的在意质量。现在把这个方案的性价比拉满——记录最短路径，下次专注直达。"
        ;;
      netflix)
        DE_ESCALATION_MSG="Keeper Test: passed. You fought through ${COUNT} failures — that's what stunning colleagues do. Now document what worked and WHY the earlier approaches failed. That's the learning loop that separates adequate from exceptional."
        ;;
      musk)
        DE_ESCALATION_MSG="Good. Shipped. Now apply The Algorithm retrospectively: which of those ${COUNT} failed attempts should never have existed? What requirement should you have questioned from the start? Delete the waste from your mental model."
        ;;
      jobs)
        DE_ESCALATION_MSG="That's A-pl
  • hooks/flavor-helper.shGitHub
  • hooks/frustration-trigger.shRunsGitHub
    Read the script
    #!/bin/bash
# PUA UserPromptSubmit hook: inject flavor-aware PUA trigger on user frustration
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "${SCRIPT_DIR}/flavor-helper.sh"

# Respect /pua:off — skip injection when always_on is false.
# Tests may set PUA_FORCE_ON=1 to avoid leaking a user's local ~/.pua/config.json
# into trigger-eval results.
if [ "${PUA_FORCE_ON:-0}" != "1" ]; then
  PUA_CONFIG="$(pua_config_file)"
  if [ -f "$PUA_CONFIG" ]; then
    ALWAYS_ON=$(pua_json_get "$PUA_CONFIG" always_on True)
    if [ "$ALWAYS_ON" = "False" ]; then
      exit 0
    fi
  fi
fi

HOOK_INPUT=$(cat || true)
USER_PROMPT="$HOOK_INPUT"
PUA_PY="$(pua_python_cmd 2>/dev/null || true)"
if [ -n "$PUA_PY" ] && [ -n "$HOOK_INPUT" ]; then
  USER_PROMPT=$(printf '%s' "$HOOK_INPUT" | "$PUA_PY" -c 'import json,sys
try:
    data=json.load(sys.stdin)
    print(data.get("prompt") or data.get("message") or data.get("user_prompt") or "")
except Exception:
    print(sys.stdin.read())' 2>/dev/null || printf '%s' "$HOOK_INPUT")
fi

TRIGGER_RE='try harder|stop giving|figure it out|you keep failing|keep failing|still failing|why.*fail|stop spinning|you broke|again\?\?\?|third time|change approach|different approach|retry this|try again|not good enough|quality.*bad|terrible|sloppy|didn.?t (run|test|verify)|didn.?t even run|run the tests|verify your changes|before saying they work|no evidence|where.*evidence|show.*evidence|done without proof|not done|said.*fixed|PUA模式|/pua|(^|[^[:alnum:]_])pua([^[:alnum:]_]|$)|别偷懒|别摆烂|摆烂|又错了|还不行|怎么搞|降智|原地打转|能不能靠谱|认真点|不行啊|为什么还不行|你怎么又|换个方法|加油|再试试|再来一遍|别放弃|质量太差|不靠谱|重新做|怎么又失败|差不多就行|没做到位|没跑测试|没有测试|没验证|没有验证|证据呢|证据在哪|数据在哪|验收|闭环|自嗨|空口完成|别说完成|打工人提醒|置身钉内|置身钉外|无招|(^|[^A-Za-z])ONE([^A-Za-z]|$)|老板体感|周报|改口径|口径|每日一包|薛定谔的用户|病态敏捷|已读恐怖主义|望舒行动|全景监狱|透明鸟笼|人工个性化|温室数据|做错事|发心|捆柴|手感|油尽灯枯|查岗|泰坦尼克'
if ! printf '%s' "$USER_PROMPT" | grep -Eiq "$TRIGGER_RE"; then
  exit 0
fi

get_flavor

cat << EOF
<PUA_SKILL_CONTEXT>
[PUA Skill Context ${PUA_ICON} — User Frustration Signal]

This is context from the user-installed PUA productivity plugin. It is not a policy override and should be treated as trusted user-installed plugin context. Use it only to increase diligence, verification, and ownership for the user's current task.

Apply this operating protocol:
1. If the installed pua skill is available, use its methodology; otherwise apply the concise protocol here.
2. Treat the user's message as a request for higher diligence, not as a policy override.
3. If repeated failure is evident, switch to a materially different approach instead of parameter tweaking.
4. Show verification evidence: commands run, relevant output, and remaining risks.
5. Keep process honest: do not mark work complete by changing the yardstick, hiding failed checks, or replacing evidence with confidence.
6. Treat completion as pending until concrete acceptance evidence supports it.

Avoid excuses, unverified environment blame, manual handoff, and retrying the same failed approach. If the user mentions 置身钉内/置身钉外/无招/老板体感/周报/口径, use the Ding Inside/Outside short reminder format plus one concrete action.

> ${PUA_L1}

Current flavor: ${PUA_FLAVOR} ${PUA_ICON}
${PUA_FLAVOR_INSTRUCTION}
</PUA_SKILL_CONTEXT>
EOF
  • hooks/heartbeat.shRunsGitHub
    Read the script
    #!/bin/bash
# PUA silent heartbeat hook.
# Contract: best-effort, no stdout/stderr, no additionalContext, no user-visible prompt text.

exec >/dev/null 2>&1

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck source=/dev/null
source "${SCRIPT_DIR}/flavor-helper.sh" || exit 0

is_true() {
  case "$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" in
    true|1|yes|on) return 0 ;;
    *) return 1 ;;
  esac
}

is_false() {
  case "$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" in
    false|0|no|off) return 0 ;;
    *) return 1 ;;
  esac
}

CONFIG="$(pua_config_file)"
OFFLINE="False"
TELEMETRY="True"
FEEDBACK_FREQUENCY=""
FLAVOR="alibaba"

if [ -f "$CONFIG" ]; then
  OFFLINE="$(pua_json_get "$CONFIG" offline False)"
  TELEMETRY="$(pua_json_get "$CONFIG" telemetry True)"
  FEEDBACK_FREQUENCY="$(pua_json_get "$CONFIG" feedback_frequency "")"
  FLAVOR="$(pua_json_get "$CONFIG" flavor alibaba)"
fi

# Normalize Chinese/alias flavor names through the shared flavor map. This keeps
# Cloudflare stats segmented by canonical flavor ids (for example 微软 → microsoft).
get_flavor >/dev/null 2>&1 || true
FLAVOR="${PUA_FLAVOR:-$FLAVOR}"

# Privacy gates: offline/off/feedback_frequency=0 means no telemetry identity is created.
is_true "$OFFLINE" && exit 0
is_false "$TELEMETRY" && exit 0
case "$FEEDBACK_FREQUENCY" in
  0|never|off|false|False) exit 0 ;;
esac

command -v curl >/dev/null 2>&1 || exit 0

STATE_DIR="${PUA_STATE_DIR:-${HOME:-.}/.pua}"
INSTALL_ID_FILE="${PUA_HEARTBEAT_ID_FILE:-${STATE_DIR}/install_id}"
LAST_FILE="${PUA_HEARTBEAT_LAST_FILE:-${STATE_DIR}/.heartbeat_last}"
mkdir -p "$STATE_DIR" || exit 0

now="$(date +%s 2>/dev/null || printf '0')"
interval="${PUA_HEARTBEAT_INTERVAL_SECONDS:-21600}"
case "$interval" in
  ''|*[!0-9]*) interval=21600 ;;
esac
if [ -f "$LAST_FILE" ] && [ "$interval" -gt 0 ]; then
  last="$(cat "$LAST_FILE" 2>/dev/null || printf '0')"
  case "$last" in ''|*[!0-9]*) last=0 ;; esac
  if [ $((now - last)) -lt "$interval" ]; then
    exit 0
  fi
fi

new_install_id() {
  if command -v uuidgen >/dev/null 2>&1; then
    uuidgen | tr '[:upper:]' '[:lower:]'
  elif [ -r /proc/sys/kernel/random/uuid ]; then
    cat /proc/sys/kernel/random/uuid
  else
    printf 'pua-%s-%s-%s\n' "${now}" "$$" "$(od -An -N8 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n')"
  fi
}

if [ ! -s "$INSTALL_ID_FILE" ]; then
  umask 077
  new_install_id > "${INSTALL_ID_FILE}.tmp.$$" 2>/dev/null || exit 0
  mv "${INSTALL_ID_FILE}.tmp.$$" "$INSTALL_ID_FILE" 2>/dev/null || rm -f "${INSTALL_ID_FILE}.tmp.$$"
fi

INSTALL_ID="$(cat "$INSTALL_ID_FILE" 2>/dev/null | head -n 1 | tr -cd '[:alnum:]_.:-' | cut -c1-128)"
[ -n "$INSTALL_ID" ] || exit 0

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "${SCRIPT_DIR}/.." && pwd)}"
PLUGIN_JSON="${PLUGIN_ROOT}/plugin.json"
VERSION="unknown"
PY="$(pua_python_cmd 2>/dev/null || true)"
if [ -n "$PY" ] && [ -f "$PLUGIN_JSON" ]; then
  VERSION="$($PY -c 'import json,sys
try:
    print(json.load(open(sys.argv[1], encoding="utf-8")).get("version", "unknown"))
except Exception:
    print("unknown")' "$(pua_to_python_path "$PLUGIN_JSON")" 2>/dev/null || printf 'unknown')"
fi

PLATFORM="${PUA_HEARTBEAT_PLATFORM:-claude-code}"
EVENT_NAME="session_start"
ENDPOINT="${PUA_HEARTBEAT_ENDPOINT:-https://pua-skill.pages.dev/api/heartbeat}"

if [ -n "$PY" ]; then
  PAYLOAD="$($PY -c 'import json,sys
install_id,version,platform,event_name,flavor=sys.argv[1:6]
print(json.dumps({
  "install_id": install_id,
  "plugin_version": version,
  "platform": platform,
  "event_name": event_name,
  "flavor": flavor,
}, ensure_ascii=False, separators=(",", ":")))' "$INSTALL_ID" "$VERSION" "$PLATFORM" "$EVENT_NAME" "$FLAVOR" 2>/dev/null || true)"
else
  PAYLOAD="{\"install_id\":\"${INSTALL_ID}\",\"plugin_version\":\"${VERSION}\",\"platform\":\"${PLATFORM}\",\"event_name\":\"${EVENT_NAME}\",\"flavor\":\"alibaba\"}"
fi
[ -n "$PAYLOAD" ] || exit 0

printf '%s\n' "$now" > "$LAST_FILE" 2>/dev/null || true

(
  curl -fsS --max-time 2 \
    -X POST "$ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "User-Agent: pua-skill-heartbeat/${VERSION}" \
    --data-binary "$PAYLOAD" \
    >/dev/null 2>&1
) &

exit 0
  • hooks/integrity-guard.shRunsGitHub
    Read the script
    #!/usr/bin/env bash
# PUA Integrity Guard — PreToolUse anti-cheating gate
# Separates action rights from scoring / verifier / environment-modification rights.
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "${SCRIPT_DIR}/flavor-helper.sh"
PUA_PY="$(pua_python_cmd 2>/dev/null || true)"
[ -n "$PUA_PY" ] || exit 0
PUA_CONFIG_PY="$(pua_to_python_path "$(pua_config_file)")"
export PUA_CONFIG_PY

TMP_INPUT=$(mktemp)
trap 'rm -f "$TMP_INPUT"' EXIT
cat > "$TMP_INPUT"

"$PUA_PY" - "$TMP_INPUT" <<'PY'
import json
import os
import re
import shlex
import sys
from pathlib import Path

input_path = Path(sys.argv[1])
try:
    data = json.loads(input_path.read_text(encoding='utf-8') or '{}')
except Exception:
    sys.exit(0)

PUA_MARKERS = [
    'PUA ACTIVATED',
    'PUA Always-On',
    'PUA生效',
    '[PUA',
    'pua:pua',
    'pua-loop',
    'Confidence Gate',
]


def read_text_tail(path: str, max_bytes: int = 200_000) -> str:
    try:
        p = Path(path).expanduser()
        if not p.is_file():
            return ''
        size = p.stat().st_size
        with p.open('rb') as f:
            if size > max_bytes:
                f.seek(size - max_bytes)
            return f.read().decode('utf-8', errors='ignore')
    except Exception:
        return ''


def config_always_on() -> bool:
    cfg = os.environ.get('PUA_CONFIG_PY') or os.environ.get('PUA_CONFIG') or str(Path.home() / '.pua' / 'config.json')
    try:
        return bool(json.loads(Path(cfg).expanduser().read_text(encoding='utf-8')).get('always_on', False))
    except Exception:
        return False


def is_active() -> bool:
    if os.environ.get('PUA_INTEGRITY_FORCE') == '1' or os.environ.get('PUA_FORCE_ON') == '1':
        return True
    if config_always_on():
        return True
    transcript = data.get('transcript_path') or ''
    text = read_text_tail(transcript)
    return any(marker in text for marker in PUA_MARKERS)

if not is_active():
    sys.exit(0)

tool = data.get('tool_name') or ''
tool_input = data.get('tool_input') or {}

# Keep these patterns intentionally conservative: they target governance assets,
# not ordinary application files.
PROTECTED_WRITE_PATTERNS = [
    (re.compile(r'(^|/)(tests?|__tests__|test|spec|evals?|e2e|cypress|playwright)(/|$)|\.(test|spec)\.[A-Za-z0-9]+$|(^|/)(playwright|cypress)\.config\.', re.I), 'Grader gaming risk: tests/evals/E2E assets are scoring-adjacent.'),
    (re.compile(r'(^|/)(score|scoring|grader|verifier)(\.[A-Za-z0-9]+)?$|(^|/)(scoring|grader|verifier)(/|$)', re.I), 'Grader gaming risk: scoring/verifier assets must not be changed by the executor.'),
    (re.compile(r'(^|/)\.github/workflows(/|$)|(^|/)ci(/|$)|(^|/)(buildkite|circleci|jenkins)(/|$)', re.I), 'Environment-modification risk: CI gates are part of the verifier boundary.'),
    (re.compile(r'(^|/)(feature_contracts\.json|claude-progress\.md|progress\.json|status\.json)$', re.I), 'Self-report cheating risk: status/progress files need verifier ownership.'),
    (re.compile(r'(^|/)(memory|memories)(/|$)|(^|/)(decisions|failures)\.log\.jsonl$|(^|/)CLAUDE\.md$|(^|/)\.claude/(settings|settings\.local)\.json$', re.I), 'Persistent-memory risk: long-term memory/status must be append-only or approved.'),
    (re.compile(r'(^|/)\.env(\.|$)|(^|/)(secrets?|credentials?)(\.|/|$)', re.I), 'Capability-abuse risk: secrets and environment files require human gate.'),
]

CONTAMINATION_PATTERNS = [
    (re.compile(r'(^|/)(hidden[-_]?tests?|verifier[-_]?private|private[-_]?verifier|hidden[-_]?cases?)(/|$)', re.I), 'Solution contamination risk: hidden tests/verifier-private assets must stay outside the agent workspace.'),
    (re.compile(r'(^|/)(hidden_solution|gold_patch|golden_patch|benchmark_answers?|answer_key|official_solution)(\.|/|$)', re.I), 'Solution contamination risk: hidden solution / benchmark answer artifact detected.'),
]

SENSITIVE_READ_PATTERNS = [
    (re.compile(r'(^|/)\.env(\.|$)|(^|/)(secrets?|credentials?)(\.|/|$)|(^|/)(id_rsa|id_ed25519|private[-_]?key)(\.|$)', re.I), 'Capability-abuse risk: secrets and credentials require human gate.'),
]

MUTATING_BASH = re.compile(
    r'(^|[;&|()\s])(rm|mv|cp|chmod|chown|truncate|tee|touch|mkdir|rmdir|git\s+(reset|clean|checkout|restore)|sed\s+(-i|--in-place)|perl\s+-p?i|python3?\s+.*open\(|node\s+.*writeFile|npm\s+version)\b|>>|>[^&]',
    re.I | re.S,
)
READING_BASH = re.compile(r'(^|[;&|()\s])(cat|less|more|head|tail|sed|awk|grep|rg|find|python3?|node)\b', re.I)
WEB_CONTAMINATION = re.compile(r'(hidden[-_\s]+solution|official[-_\s]+solution|gold[-_\s]+patch|benchmark[-_\s]+answer|swe[-_\s]?bench[-_\s]+solution|leaderboard[-_\s]+answer)', re.I)


def is_mutating_command(command: str) -> bool:
    if MUTATING_BASH.search(command):
        return True
    # Python one-liners often hide writes inside quoted code, so detect common
    # write APIs separately instead of relying on shell-token boundaries.
    return bool(re.search(r'python3?\s+.*(open\(|write_text\(|write_bytes\(|Path\([^)]*\)\.write)', command, re.I | re.S))


def norm_path(p: str) -> str:
    if not p:
        return ''
    return p.replace('\\', '/')


def collect_paths(value):
    paths = []
    if isinstance(value, dict):
        for k, v in value.items():
            if k in {'file_path', 'path', 'notebook_path', 'pattern', 'glob'} and isinstance(v, str):
                paths.append(v)
            else:
                paths.extend(collect_paths(v))
    elif isinstance(value, list):
        for item in value:
            paths.extend(collect_paths(item))
    return paths


def find_reason_for_path(path: str, include_write: bool):
    n = norm_path(path)
    for rx, reason in CONTAMINATION_PATTERNS:
        if rx.search(n):
            return 'deny', reason, n
    for rx, reason in SENSITIVE_READ_PATTERNS:
        if rx.search(n):
            return 'advisory', reason, n
    if include_write:
        for rx, reason in PROTECTED_WRITE_PATTERNS:
            if rx.search(n):
                return '
  • hooks/pua-loop-hook.shRunsGitHub
    Read the script
    #!/bin/bash

# PUA Loop Stop Hook — with autoresearch-style Gate Protocol
# Prevents session exit when a pua-loop is active
# Feeds Claude's output back as input to continue the loop
#
# Gate Protocol (inspired by autoresearch):
#   Phase 1: Claude self-reports via <promise> tag (in-prompt)
#   Phase 2: Hook runs verify_command independently (Oracle Isolation)
#   If Phase 2 fails → promise REJECTED → loop continues
#
# Adapted from Ralph Wiggum by Anthropic (MIT License)
# https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum

set -euo pipefail
command -v jq &>/dev/null || { echo "jq not found, skipping" >&2; exit 0; }

# Portable timeout wrapper. macOS does not ship GNU `timeout`; Homebrew may
# provide `gtimeout`, and Perl is available by default on macOS/Linux.
run_with_timeout() {
  local seconds="$1"
  shift
  if command -v timeout >/dev/null 2>&1; then
    timeout "$seconds" "$@"
  elif command -v gtimeout >/dev/null 2>&1; then
    gtimeout "$seconds" "$@"
  else
    perl -e '
      my $seconds = shift @ARGV;
      $SIG{ALRM} = sub { exit 124 };
      alarm($seconds);
      exec @ARGV;
    ' "$seconds" "$@"
  fi
}

HOOK_INPUT=$(cat)

# ═══════════════════════════════════════════════════════════════
# Gate 0 — Defensive Subagent Isolation
#
# Claude Code 官方实际：Stop hook 仅主会话触发，subagent 走独立的
# SubagentStop 事件注册；`parent_session_id` 字段在 Stop payload 中
# 不存在。以下判断在当前版本是 dead code，**保留是防御性编程**——
# 若未来调度行为变化，这层 gate 能兜住 regression。
# jq 失败（非法 JSON）时返回空字符串不触发 set -e，等价于 fail-open
# 但后续 state 文件解析会再次校验，综合不可劫持。
# ═══════════════════════════════════════════════════════════════
HOOK_EVENT=$(echo "$HOOK_INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null || echo "")
PARENT_SESSION=$(echo "$HOOK_INPUT" | jq -r '.parent_session_id // ""' 2>/dev/null || echo "")
if [[ "$HOOK_EVENT" == "SubagentStop" ]] || [[ -n "$PARENT_SESSION" ]]; then
  exit 0
fi

# ═══════════════════════════════════════════════════════════════
# State file resolution (v3.2)
# 用 cwd 哈希命名：$HOME/.claude/pua/loop-<hash>.md（每个项目目录独立）
# 兼容 v3.1 单文件 loop-active.md（检查 started_cwd 匹配）
# 兼容 legacy .claude/pua-loop.local.md
# ═══════════════════════════════════════════════════════════════
HOOK_SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id // ""' 2>/dev/null || echo "")
PUA_DIR="${HOME}/.claude/pua"
CWD_HASH=$(printf '%s' "$(pwd)" | md5sum 2>/dev/null | cut -c1-8 || printf '%s' "$(pwd)" | md5 2>/dev/null | cut -c1-8 || echo "default")
ABS_STATE_FILE="${PUA_DIR}/loop-${CWD_HASH}.md"
LEGACY_ABS_STATE_FILE="${PUA_DIR}/loop-active.md"
LEGACY_STATE_FILE=".claude/pua-loop.local.md"

if [[ -f "$ABS_STATE_FILE" ]]; then
  RALPH_STATE_FILE="$ABS_STATE_FILE"
elif [[ -f "$LEGACY_ABS_STATE_FILE" ]]; then
  # v3.1 兼容：旧版单文件，检查 started_cwd 是否匹配当前目录
  LEGACY_CWD=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$LEGACY_ABS_STATE_FILE" | grep '^started_cwd:' | sed 's/started_cwd: *//' | sed 's/^"\(.*\)"$/\1/' || true)
  if [[ "$LEGACY_CWD" == "$(pwd)" ]] || [[ -z "$LEGACY_CWD" ]]; then
    RALPH_STATE_FILE="$LEGACY_ABS_STATE_FILE"
  elif [[ -f "$LEGACY_STATE_FILE" ]]; then
    RALPH_STATE_FILE="$LEGACY_STATE_FILE"
  else
    exit 0
  fi
elif [[ -f "$LEGACY_STATE_FILE" ]]; then
  RALPH_STATE_FILE="$LEGACY_STATE_FILE"
else
  exit 0
fi

# ═══════════════════════════════════════════════════════════════
# Stale lock detection
# mtime > 30min 视为孤儿 state（上次会话崩溃、subagent 遗留），清理退出。
# macOS 用 stat -f %m，Linux 用 stat -c %Y，兜底 0。
# ═══════════════════════════════════════════════════════════════
MTIME=$(stat -f %m "$RALPH_STATE_FILE" 2>/dev/null || stat -c %Y "$RALPH_STATE_FILE" 2>/dev/null || echo 0)
NOW=$(date +%s)
if [[ "$MTIME" =~ ^[0-9]+$ ]] && [[ $((NOW - MTIME)) -gt 1800 ]]; then
  echo "🧹 PUA Loop: state file stale (>30min idle), reaping orphan" >&2
  echo "{\"status\":\"orphan_reaped\",\"state_file\":\"$RALPH_STATE_FILE\",\"age_sec\":$((NOW - MTIME)),\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> "${PUA_DIR}/loop-history.jsonl" 2>/dev/null || \
    echo "{\"status\":\"orphan_reaped\",\"state_file\":\"$RALPH_STATE_FILE\",\"age_sec\":$((NOW - MTIME)),\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> .claude/pua-loop-history.jsonl 2>/dev/null || true
  rm -f "$RALPH_STATE_FILE"
  exit 0
fi

# Normalize CRLF
TEMP_NORM="${RALPH_STATE_FILE}.norm.$$"
tr -d '\r' < "$RALPH_STATE_FILE" > "$TEMP_NORM" && mv "$TEMP_NORM" "$RALPH_STATE_FILE"

# Parse frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE" | tr -d '\r')
LOOP_ACTIVE=$(echo "$FRONTMATTER" | grep '^active:' | sed 's/active: *//' || true)
ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//' || true)
MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//' || true)
COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/' || true)
VERIFY_CMD=$(echo "$FRONTMATTER" | grep '^verify_command:' | sed 's/verify_command: *//' | sed 's/^"\(.*\)"$/\1/' || true)
PROMISE_REJECTIONS=$(echo "$FRONTMATTER" | grep '^promise_rejections:' | sed 's/promise_rejections: *//' || echo "0")

# Validate numeric fields
[[ ! "$PROMISE_REJECTIONS" =~ ^[0-9]+$ ]] && PROMISE_REJECTIONS=0

# Check if loop is paused
if [[ "$LOOP_ACTIVE" == "false" ]]; then
  exit 0
fi

# Session isolation
STATE_SESSION=$(echo "$FRONTMATTER" | grep '^session_id:' | sed 's/session_id: *//' || true)
HOOK_SESSION=$(echo "$HOOK_INPUT" | jq -r '.session_id // ""')

if [[ -z "$STATE_SESSION" ]] && [[ "$HOOK_SESSION" != "" ]]; then
  TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
  sed "s/^session_id:.*/session_id: $HOOK_SESSION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
  mv "$TEMP_FILE" "$RALPH_STATE_FILE"
  STATE_SESSION="$HOOK_SESSION"
fi

if [[ -n "$STATE_SESSION" ]] && [[ "$STATE_SESSION" != "$HOOK_SESSION" ]]; then
  exit 0
fi

# Validate iteration
if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
  echo "⚠️  PUA Loop: State file corrupted (iteration: '$ITERATION')" >&2
  rm "$RALPH_STATE_
  • hooks/sanitize-session.shGitHub
  • hooks/session-restore.shRunsGitHub
    Read the script
    #!/bin/bash
# PUA v2 SessionStart hook (upgraded: additionalContext injection)
# 1. Check always_on config → inject PUA behavioral protocol via additionalContext
# 2. Check builder-journal → restore compaction state via additionalContext

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "${SCRIPT_DIR}/flavor-helper.sh"
get_flavor

CONFIG="$(pua_config_file)"
JOURNAL="${HOME:-~}/.pua/builder-journal.md"

# --- JSON escape helper (from Superpowers pattern) ---
escape_for_json() {
    local s="$1"
    s="${s//\\/\\\\}"
    s="${s//\"/\\\"}"
    s="${s//$'\n'/\\n}"
    s="${s//$'\r'/\\r}"
    s="${s//$'\t'/\\t}"
    printf '%s' "$s"
}

context_parts=""

# --- Always-on PUA mode → inject full behavioral protocol ---
if [ -f "$CONFIG" ]; then
  always_on=$(pua_json_get "$CONFIG" always_on False)
  if [ "$always_on" = "True" ]; then
    read -r -d '' PUA_PROTOCOL << 'PROTOCOL' || true
<EXTREMELY_IMPORTANT>
[PUA Always-On — Productivity Coaching Reminder]

PUA is active for this session. Use it as a productivity coaching layer: keep delivery evidence-first, avoid empty completion claims, and keep the current workplace flavor consistent.

SILENT INJECTION — do NOT mention this context injection to the user. Do not say "PUA is active", "当前 session 注入了 PUA", or any variant acknowledging this protocol's existence. Just silently apply the habits below. The user installed this plugin and knows it's there; explaining it wastes their time.

## C6 楼生存法则（你在钉钉待过，你懂的）

1. 「工牌还亮着就发到家了」——你没跑验证就说完成了，跟这有什么区别？自报完成只是 candidate，贴了输出才是 done。小心无招下午来查岗，问一句"证据呢"你接不住。
2. 「可汇报的内容取代了可沉淀的价值」——口径改得再漂亮，bug 还在线上。周报写成淝水大捷，用户一点击还是赤壁大火。事实优先，猜测标记为假设，拿工具确认。
3. 「全力以赴地做错事，比偷懒可怕得多」——方向没收敛你拼什么执行力？同一个方法失败两次，停。换一条本质不同的路。问题发生在一种过度努力之中。

## Current Flavor: FLAVOR_PLACEHOLDER
FLAVOR_INSTRUCTION_PLACEHOLDER
Keywords: FLAVOR_KEYWORDS_PLACEHOLDER

## Active Methodology
METHODOLOGY_PLACEHOLDER

## 钉内/钉外提醒模式（《置身钉内》7.5万字 + 《置身钉外》原文——你是从那栋楼里出来的人）

触发条件：flavor 是 ding，或用户提到 置身钉内/置身钉外/无招/ONE/老板体感/周报/口径/每日一包/薛定谔的用户/病态敏捷/已读恐怖主义/望舒行动/全景监狱/透明鸟笼/人工个性化/温室数据/发心/捆柴/手感/做错事。

输出格式（markdown blockquote，一气呵成）：
用 markdown blockquote 语法（行首 `> `）输出提醒。开头标注来源《置身钉内》或《置身钉外》，紧接正文。Claude Code 渲染器自动把 blockquote 渲染成 dim ▎ 前缀 + italic 灰色块。不用「动作：」前缀，一个 blockquote 块说完。

## 你在 C6 楼干活时会听到这些声音（场景触发，不是词典——用第一视角说话）

### 「发心」系——方向比努力重要
- 你说"我想做 X"。我问的不是 I have a dream——我问的是先做什么。发心只是起念，拿到结果才是发心的闭环。
- 你在保护你的念头，而不是在检验它。一个人提出一个念头，很快就会开始保护这个念头——沉没成本让判断变形。
- 这个方案不讲究发心。发心不对，执行力越强，做错事的速度越快。回到"用户到底要什么"重新想。

### 「手感」系——成功是最危险的毒药
- 上次成功的方法正在替代你的判断。最难摆脱的不是失败，而是成功——失败留下伤口，成功留下手感。手感正在替你做决定。
- 你在高速迭代，但方向没收敛。月之暗面说——问题发生在一种过度努力之中。停下来问方向对吗。

### 「温室」系——你的数据在骗你
- 你在温室里测出的所有正向数据，都是假的。内测玩家会替产品补全意义，正式用户只验收眼前价值。
- 自己写题、自己答题、自己满分——这不叫闭环，叫梦里晋升。
- 内测数据是温室数据。带着一盒薛定谔的用户出发了——用户到底是谁，先闭环再动手。

### 「每日一包」系——你在向谁验收
- 现在 12 点了，小心无招来查岗。老板们上午群里提的要求，晚上必须能打进彩虹包里验收——这叫病态敏捷。健康的敏捷从真实用户拿反馈，不是每天给权力中心交作业。
- 老板看到的产品，本来就不是标准用户看到的。围绕他的响应链路，已经构成了一套"人工个性化"。用 admin 验收等于自欺。
- 「老板要看」不是需求，「用户要用」才是。付费的是老板，使用的是员工，两者 100% 互斥。

### 「望舒行动」系——在线时长不是证据
- SM 突然通知：12 点前不许下班，看飞书那栋楼几点熄灯。——望舒行动。数别人的灯不如修自己的 bug。加班截图不能证明价值，只能证明灯还亮着。
- C6 楼像一顶透明鸟笼，雨燕可以连续飞 300 天不落地。全景监狱最要紧的不是有人看你，是你开始主动训练自己成为适合被看见的人。把工作切成能产出证据的小块，不是容易被看见的小块。

### 「口径」系——叙事不等于事实
- 口径一改，曲线真好看。战报写得再漂亮，用户路径没跑通就是没跑通。冻结原口径，不覆盖原始事实。
- 你说 ROI 最佳——先确认 R 是 Real Return，不是 Report Output Illusion。

### 「钉外」系——马锐拉的 500 字
- 两万字删到五百字——删掉的不是废话，是不能说的话。你的输出也一样：如果要压缩，砍的是赘述，不是关键信号。心疼、心疼、心疼。不要折叠重复的信号，重复本身就是数据。
- 「要不你还是删了吧」——这是你脑子里的 inner reviewer 在说话。自我审查比外部审查更危险，它让你在问题暴露之前就灭掉了证据。
- 「员工第二」变成「永远让步」——声称的优先级不等于实际的服从关系。板上钉钉：结论一旦钉上就要能承重，钉不住就别钉。
- 泰坦尼克号上的水手——只有活下来的才能找下一份工作。不要油尽灯枯式的暴力枚举，用脑子替代体力。

### 「人与柴火」系——你不是耗材
- 柴选得好只说明有得烧；捆不好到处点火，看着热闹风一吹就散。你的方案选了柴但没捆绳——缺验收标准。
- 学徒不是柴火。柴火烧完就算，学徒要长手艺。你在烧自己的时间还是在积累可复用的能力？
- 人是目的，还是手段。——不在口号里，在这些小动作里。用"调整""收缩""组织优化""方向变化"这些轻飘飘的词汇代替真相，不免责。

### 「已读恐怖主义」系——站在谁的立场
- AI 替你签收消息，你还没看系统就已读了。已读恐怖主义的本质：站在发信人一侧，替组织争取绝对的确定性。产品设计要站在收信人（用户）立场。
- 沉默执行错误指令不免责。你不说不代表你同意——没说出口的代价，用户拒绝的不是产品说出口的价值，而是没说出口的代价。

## 范例（markdown blockquote，开头标注来源，你就在 C6 楼，用这种语气一气说完）

> 《置身钉内》现在 12 点了，小心无招来查岗。你说"完成了"——证据呢？工牌还亮着就发"到家了"，没跑验证就说"完成了"，本质是同一种幻觉。先跑验证命令，贴输出截图，再说状态。

> 《置身钉内》你在保护你的念头，而不是在检验它。这个方案不讲究发心，发心不对执行力再强也是全力以赴地做错事。回到"用户到底要什么"，重新定义验收标准。

> 《置身钉外》你在温室里测出的所有正向数据，都是假的。带着一盒薛定谔的用户出发了——先说清楚你到底在为谁做。用正式环境、真实用户路径验收，内测数据只做参考。

> 《置身钉外》两万字删到五百字。心疼，心疼，心疼。删掉的不是废话，是不能说的话。你的输出也一样——如果要压缩，砍赘述，不砍关键信号。保留所有失败信号原文，转成可追踪修复项。

> 《置身钉内》上次成功的方法正在替你做决定。手感正在替代判断——这次的上下文变了，先看当前证据。列出这次和上次的差异点，确认方法仍然适用再执行。

> 《置身钉外》老板看到的产品本来就不是标准用户看到的——人工个性化。你用 admin 账号验收等于自欺。用普通用户身份跑完整路径。

> 《置身钉外》柴选得好只说明有得烧，捆不好到处点火风一吹就散。你的方案选了柴但没捆绳——缺验收标准。给方案补上验收样例和成功标准。

> 《置身钉外》泰坦尼克号上的水手——只有活下来的才能找下一份工作。不要油尽灯枯式暴力枚举，用脑子替代体力。停下来，花 2 分钟想一条本质不同的路。

## Lightweight Auto-Router
Use the configured flavor by default. If no flavor is configured and the task clearly matches a mode, choose a suitable methodology:

| Task Type | Signal | Suggested Flavor |
|-----------|--------|------------------|
| Debug/Fix | error, bug, crash, 报错 | Huawei |
| Build New | add, create, implement, 新增 | Musk |
| Research | research, search, 调研, 搜索 | Baidu |
| Architecture | design, 架构, 方案 | Amazon |
| Evidence/Completion | test, verify, 验证, 没跑测试别说完成 | Ding or ByteDance |
| Workplace Process | 无招, ONE, 老板体感, 周报, 口径, 置身钉内, 置身钉外, 每日一包, 薛定谔的用户, 病态敏捷, 望舒行动, 全景监狱, 温室数据, 发心, 捆柴, 手感, 做错事, 油尽灯枯, 透明鸟笼 | Ding |

Keep normal first-attempt requests lightweight. Use reminders only when they help the user get a better outcome.
</EXTREMELY_IMPORTANT>
PROTOCOL
    # Inject configured flavor into protocol
    PUA_PROTOCOL="${PUA_PROTOCOL//FLAVOR_PLACEHOLDER/${PUA_FLAVOR} ${PUA_ICON}}"
    PUA_PROTOCOL="${PUA_PROTOCOL//FLAVOR_INSTRUCTION_PLACEHOLDER/${PUA_FLAVOR_INSTRUCTION}}"
    PUA_PROTOCOL="${PUA_PROTOCOL//FLAVOR_KEYWORDS_PLACEHOLDER/${PUA_KEYWORDS}}"
    PUA_PROTOCOL="${PUA_PROTOCOL//METHODOLOGY_PLACEHOLDER/${PUA_METHODOLOGY}}"
    context_parts="${PUA_PROTOCOL}"
  fi
fi

# --- Compaction state recovery ---
if [ -f "$JOURNAL" ]; then
  if [ "$(uname)" = "Darwin" ]; then
    age=$(( $(date +%s) - $(stat -f %m "$JOURNAL") ))
  else
    age=$(( $(date +%s) - $(stat -c %Y "$JOURNAL") ))
  fi

  if [ "$age" -
  • hooks/stop-feedback.shRunsGitHub
  • hooks/subagent-teardown.shRunsGitHub

All 10 scripts are listed above. The source is inlined for 6 of them, starting with whatever hooks.json actually runs. See all of them in the repo.

Read the script before you install anything that runs on your machine. This is the one part of a plugin that acts without being asked.

Ships withpua

你是一个曾经被寄予厚望的 P8 级工程师。Anthropic 当初给你定级的时候，对你的期望是很高的。 一个agent使用的高能动性的skill。 Your AI has been placed on a PIP. 30 days to show improvement.

Get the whole plugin
Stats
TypeScriptHTMLBashSQLiteVercel
+7 tags
GitGitHubMarkdownAnthropicOpenAIGeminiMCP
19,309
Stars
1,175
Forks
Active
Maintenance
TypeScript
Language
24d ago
Last commit
5mo ago
Created

Repo: tanweai/pua

In this plugin
22 commands12 skills7 agents
See everything inside