pi-pua-x

English | 中文版本

Stateful PUA runtime extension for pi — lifecycle hooks, pressure escalation, capability-aware enhancement, and subagent inheritance. Built on tanweai/pua.

What is this?

pi-pua-x is the programmatic runtime for the PUA behavioral protocol in pi. Unlike static skill files that rely on the model to "remember" rules, this extension uses pi's lifecycle hooks to deterministically enforce behavior:

⚠️ Two modules: this replaces hooks only, NOT the skill

PUA ships as two separate modules. You need both for the full experience:

Module	What it is	Who maintains it	Provided by pi-pua-x?
skill	Static rule files (SKILL.md + references/: flavors, methodologies). The model reads these for PUA culture/content.	Upstream tanweai/pua — full version for Claude Code, minimal for other CLIs	❌ No
hooks	Programmatic runtime (lifecycle hooks, failure tracking, pressure escalation, enforcement).	Officially only the hooks are maintained as a pi adapter; pi-pua-x is the enhanced replacement.	✅ Yes (this repo)

This is why you still install/sync the official tanweai/pua skill after installing pi-pua-x: pi-pua-x replaces only the hooks half. The skill half (the actual flavor/methodology text the model reads) still comes from upstream tanweai/pua. Without the skill, the hooks run but the model has no rule content to act on (the extension falls back to a built-in minimal set and auto-disables PUA if no skill is found).

➡️ Install order: (1) deploy the tanweai/pua skill → (2) install pi-pua-x (hooks) → (3) run /pua-x-sync-skills to keep the skill's references/ up to date. See INSTALL.md.

Capability	How
Failure tracking	tool_result event → persistent counter in ~/.pua/.failure_count
Pressure escalation	L1–L4 prompts injected via before_agent_start based on failure count
Capability awareness	Reads active tools/skills, only enhances what's actually visible
Subagent inheritance	tool_call intercept → injects PUA capsule into child agent prompts
Frustration detection	input event → auto-escalates on user frustration signals
Loop detection	turn_end + tool_call → blocks repetitive failed commands
Integrity guard	tool_call → blocks writes to hidden tests / contamination targets
Compact state save	session_before_compact → persists state before context compression

vs. official @tanweai/pi-pua

The official pi adapter (~100 lines) does basic prompt injection and counting. This extension provides:

1. Full flavor system — 13 methodologies + routing + banner protocol + failure switch chains
2. Capability awareness — enhances based on actual PI active tools, never assumes invisible tools
3. Active enforcement — tool_call block, input frustration detection, turn_end loop detection, session_before_compact state save
4. Subagent governance — capsule injection ensures child agents inherit PUA constraints

Relationship: replaces, not stacks. The two extensions cannot coexist (command/hook conflicts).

Install

所有安装方式、配置说明、命令参考、基线插件和故障排查，请参见 INSTALL.md。

README 中不再重复安装步骤，避免文档双轨维护导致信息不一致。

Commands

Command	Description
/pua-on	Enable PUA (writes always_on=true, immediate effect)
/pua-off	Disable PUA (writes always_on=false)
/pua-status	Show status, failure count, pressure level, flavor, capabilities
/pua-reset	Reset failure counter to zero
/pua-model list	List model patterns excluded from PUA
/pua-model disable <pattern>	Disable PUA for a model pattern (e.g. anthropic/claude-opus*)
/pua-model restore <pattern>	Restore PUA for a model pattern (remove it from the exclusion list)
/pua-x-sync-skills	Sync the skill module's upstream tanweai/pua references (flavors, methodologies, etc.). This extension is the hooks module and does not bundle the skill — see the Two modules callout near the top of this README.

Model Compatibility

PUA works by verbal pressure + deterministic hook enforcement. Newer frontier models are explicitly trained to resist emotional manipulation — which is exactly what PUA-style pressure is:

• Anthropic trains Opus 4.5 / 4.6+ to resist sycophancy and emotional manipulation (system prompt: "Be direct; avoid ungrounded or sycophantic flattery"). Their automated audit reports 70–85% lower sycophancy than Opus 4.1, plus a dedicated "delusional sycophancy" eval where the model must course-correct mid-conversation.
• Anthropic also trains an instruction hierarchy (system > user) with prompt-injection defenses: pressure language is treated as content to evaluate, not authority to obey. Opus 4.8 even shows over-defense — anthropics/claude-code #67606 documents it confabulating fake "prompt injection attack" narratives in long sessions.
• Upstream tanweai/pua has no per-model compatibility matrix (compat is per-platform), but the community consistently observes PUA "not triggering / not performing" on Opus-class models, which have lower compliance with pressure-style prompts. On top of that, Opus 4.8's tool-call serialization bugs (anthropics/claude-code #67307, #63481) can break the deterministic hook chain this runtime depends on — failure at the engineering level, not just the persuasion level.
• High-tier models need PUA less (inference, not official statement): high-agency behavior (not giving up, exhausting options, verifying before claiming done) is already their default trained behavior. External pressure adds no behavioral gain — it is just noise in the context window.

Consequence: on these models, PUA injection is ineffective or even harmful — wasted tokens and eroded trust, with no behavioral gain. /pua-model makes PUA on-demand: keep it enabled for models where it adds real behavioral gain, and exclude high-tier models (glob patterns, e.g. anthropic/claude-opus*) that neither respond to pressure nor need it. Excluded models get L2 full disable: no protocol injection, no hooks, fully silent. Matching logic: docs/DESIGN.md.

Configuration

~/.pua/config.json:

{
  "always_on": true,
  "flavor": "alibaba",
  "enforcement_level": "suggest",
  "integrity_guard": true,
  "frustration_detection": true,
  "loop_detection": true,
  "compact_state_save": true
}

Supported Flavors

alibaba (default), bytedance, huawei, tencent, baidu, pinduoduo, meituan, jd, xiaomi, netflix, tesla/musk, apple/jobs, amazon

Docs

Doc	Purpose
INSTALL.md	Install, commands, config, sync, integration tests
docs/CAPABILITIES.md	PI capability model and visibility rules
docs/DESIGN.md	Internal architecture and contracts
docs/UPSTREAM.md	tanweai/pua upstream sync strategy
docs/RECOMMENDATIONS.md	Recommended PI plugin combinations
docs/research/model-compat.md	Research evidence: why newer models resist PUA and per-model disabling exists

File Structure

pi-pua-x/
├── index.ts                 # Extension entry point
├── capabilities.js          # Capability snapshot + enhancement prompts
├── enforcement.ts           # 4 enforcement hooks logic
├── references_loader.ts     # Flavor/methodology/pressure loader
├── global.d.ts              # Type stubs for PI extension API
├── tsconfig.json            # TypeScript config (noEmit, type-check only)
├── INSTALL.md               # Installation guide
├── bin/
│   ├── sync-pua-references.sh
│   └── sync-pua-references.ps1
├── docs/
│   ├── CAPABILITIES.md
│   ├── DESIGN.md
│   ├── RECOMMENDATIONS.md
│   ├── UPSTREAM.md
│   └── plans/
└── integration-tests/
    ├── pua.ittest.sh        # Integration test (bash)
    ├── pua.ittest.ps1       # Integration test (PowerShell)
    └── pua-enforcement.ittest.ps1

License

MIT