@michengai/dsh-pua 0.3.8

package/assets/pua/upstream/commands/off.md

@@ -0,0 +1,41 @@
+---
+description: "PUA 关闭默认模式 — 关闭自动加载、停止 loop、清理本地运行状态。"
+---
+
+关闭 PUA 默认模式（v3 级联语义）：
+
+## 步骤
+
+1. **写入配置**（确保 `~/.pua/` 目录存在）：
+   - 将 `{"always_on": false, "feedback_frequency": 0}` 写入 `~/.pua/config.json`
+
+2. **停止活跃 loop**（若有）：
+   ```bash
+   find "$HOME/.claude/pua/" -name "loop-*.md" -delete 2>/dev/null
+   rm -f .claude/pua-loop.local.md 2>/dev/null
+   ```
+
+3. **清理活跃 agent 记录**：
+   ```bash
+   rm -f "$HOME/.claude/pua/active-agents.json" 2>/dev/null
+   ```
+
+4. **记录事件**：
+   ```bash
+   mkdir -p "$HOME/.claude/pua"
+   echo "{\"event\":\"pua_off\",\"ts\":\"$(date -u +%FT%TZ)\"}" \
+     >> "$HOME/.claude/pua/teardown.jsonl"
+   ```
+
+5. **提示主会话**：若 TaskList 里还有未完成任务且归属 PUA agent，列给用户，由用户决定是否 `TaskStop`。
+
+## 输出确认
+
+> [PUA OFF] PUA 默认模式和反馈收集已关闭。Loop state 已清理，孤儿 agent 已释放。需要时手动 /pua:pua 触发。
+
+## 设计语义
+
+`/pua:off` 不只是"关开关"，而是"下班"——和 `/pua:on` 对应的是加载配置；和"停运行"对应的是本命令自带的级联清理。
+
+如果你只想关配置不动 state，直接编辑 `~/.pua/config.json`。
+如果你想更激进地清 worktree 等资源，用 `/pua:teardown-all`。

package/assets/pua/upstream/commands/offline.md

@@ -0,0 +1,38 @@
+---
+description: "PUA 离线模式 — 关闭本地反馈问卷，保留本地 PUA 行为。/pua:offline。Triggers on: '/pua:offline', '离线模式', '封闭网络', 'offline mode', 'no network'."
+---
+
+开启 PUA 离线模式，适用于内网、封闭网络，或不希望任务结束时被反馈问卷打断的环境。
+
+> **注意**：PUA Skill 已移除全部联网上报功能（session 上传 / 评分上报 / 心跳 telemetry / 排行榜），**默认就不发送任何数据**。此命令现在只控制本地反馈问卷是否弹出，不再是"关闭上报"的开关。
+
+## 执行
+
+```bash
+mkdir -p "$HOME/.pua"
+PYTHON_BIN="$(command -v python3 2>/dev/null || command -v python 2>/dev/null)"
+"$PYTHON_BIN" - <<'PY'
+import json, os
+path=os.path.expanduser('~/.pua/config.json')
+try:
+    data=json.load(open(path, encoding='utf-8'))
+except Exception:
+    data={}
+data['offline']=True
+data['feedback_frequency']=0
+data.setdefault('always_on', True)
+with open(path, 'w', encoding='utf-8') as f:
+    json.dump(data, f, ensure_ascii=False, indent=2)
+    f.write('\n')
+PY
+```
+
+## 输出确认
+
+> [PUA OFFLINE] 已进入离线模式：保留本地压力/验证协议，不再弹出反馈问卷。恢复问卷时编辑 `~/.pua/config.json`：`"offline": false` 并设置 `feedback_frequency`。
+
+## 设计边界
+
+- 离线模式不等于 `/pua:off`：PUA 行为仍可开启。
+- 离线模式只关闭本地反馈问卷；PUA Skill 本身已无任何联网上报代码，无需靠此开关阻止上传。
+- 不会替用户禁止模型或其他工具联网。真正的网络隔离仍应由运行环境、防火墙或工具权限控制完成。

package/assets/pua/upstream/commands/on.md

@@ -0,0 +1,15 @@
+---
+description: "PUA 开启默认模式 — 每次新会话自动加载 PUA 核心 skill。/pua:on。Triggers on: '/pua:on', 'pua on', '开启pua', 'enable pua', 'always on'."
+---
+
+开启 PUA 默认模式：
+
+1. 确保 `~/.pua/` 目录存在
+2. 读取现有 `~/.pua/config.json`（若不存在视为 `{}`），写回时**只改 `always_on: true`，不降级其他字段**；若 `feedback_frequency` 当前为 0（可能是 `/pua:off` 留下的 tombstone），恢复为默认 5；其他字段保留原样
+3. 输出确认：> [PUA ON] 从现在起，每个新会话都会自动进入 PUA 模式。公司不养闲 Agent。
+
+## 对称性（与 `/pua:off` 的关系）
+
+- `/pua:off` 会把 `feedback_frequency` 置 0，使问卷永不触发
+- `/pua:on` **必须**检测并恢复该字段，否则"先 off 再 on"会导致 feedback 永久失效（静默 bug）
+- 保留原则：不清楚的字段一律 preserve，不 overwrite 整个 config

package/assets/pua/upstream/commands/p10.md

@@ -0,0 +1,5 @@
+---
+description: "PUA P10 CTO 模式 — 定战略管 P9。/pua:p10。Triggers on: '/pua:p10', 'pua p10', 'CTO模式', 'P10', '战略规划', '架构委员会'."
+---
+
+Invoke the pua:p10 skill and follow it exactly as presented to you.

package/assets/pua/upstream/commands/p7.md

@@ -0,0 +1,5 @@
+---
+description: "PUA P7 骨干模式 — 方案驱动执行。/pua:p7。Triggers on: '/pua:p7', 'pua p7', 'P7模式', '方案驱动', sub-task execution under P8."
+---
+
+Invoke the pua:p7 skill and follow it exactly as presented to you.

package/assets/pua/upstream/commands/p9.md

@@ -0,0 +1,5 @@
+---
+description: "PUA P9 Tech Lead 模式 — 写 Prompt 管 P8 团队。/pua:p9。Triggers on: '/pua:p9', 'pua p9', 'P9模式', 'tech-lead', '帮我管理这个项目', '任务拆解'."
+---
+
+Invoke the pua:p9 skill and follow it exactly as presented to you.

package/assets/pua/upstream/commands/pro.md

@@ -0,0 +1,5 @@
+---
+description: "PUA Pro — 自进化 + Platform + /pua:pua 指令系统。/pua:pro。Triggers on: '/pua:pro', 'pua pro', '自进化', 'evolution'."
+---
+
+Invoke the pua:pro skill and follow it exactly as presented to you.

package/assets/pua/upstream/commands/pua-loop.md

@@ -0,0 +1,5 @@
+---
+description: "PUA Loop — 显式启用的自动迭代辅助模式，按暂停/终止标记和完成证据推进。"
+---
+
+Invoke the pua:pua-loop skill and follow it exactly as presented to you.

package/assets/pua/upstream/commands/pua.md

@@ -0,0 +1,44 @@
+---
+description: "Use when the user invokes /pua or asks for PUA mode, try-harder/retry help, change-approach coaching, completion-quality checks, evidence requests, test-before-done reminders, or Ding-style workplace reminders. Routes to p7, p9, p10, pro, yes, mama, loop, on/off/offline, kpi, survey, flavor, ding, again, done-check, or evidence. Normal calm first-attempt requests are left alone."
+argument-hint: "[p7|p9|p10|pro|yes|mama|loop|on|off|offline|kpi|survey|flavor|ding|again|done-check|evidence|task]"
+---
+
+根据参数执行不同操作。
+
+## ⚠️ 加载方式（重要）
+
+**不要用 Skill tool 加载 `pua:pua` 或 `pua`**——会导致循环加载本 router。正确做法：
+
+- **核心 PUA skill**（无参数/任务描述）：用 Read 工具直接读取本插件目录下的 `skills/pua/SKILL.md`，然后按其中的行为协议执行。需要面板时再读取 `skills/pua/references/display-protocol.md` 获取格式。
+- **子 skill**（p7/p9/p10/pro/yes/mama/pua-loop/shot/pua-en/pua-ja）：用 Read 工具读取 `skills/<name>/SKILL.md`。
+- **轻量命令**（again/done-check/evidence/ding/flavor/on/off/kpi/survey 等）：你已经在读本文件了，直接执行下方对应路由的指令。
+
+插件根目录以本次宿主提供的 `CLAUDE_PLUGIN_ROOT`（插件根目录）或本命令的真实安装位置为准；若命令位于 `<插件根>/commands/pua.md`，根目录是 `commands` 的上一级，不是 `skills/pua` 的父目录。下文的 `skills/...` 与 `commands/...` 都相对该根目录，读取时使用解析后的绝对路径。不假定克隆文件夹名，不全盘 Glob（文件匹配）搜索，不递归加载本 router（路由命令）。
+
+## 参数路由
+
+- **无参数** 或任务描述 → 用 Read 读取 `skills/pua/SKILL.md`，按其行为协议执行；需要面板时再读展示协议（默认使用已配置味道；未配置时为阿里味）
+- **p7** → Read `skills/p7/SKILL.md`（P7 骨干模式 — 方案驱动执行）
+- **p9** → Read `skills/p9/SKILL.md`（P9 Tech Lead — 写 Prompt 管 P8 团队）
+- **p10** → Read `skills/p10/SKILL.md`（P10 CTO — 定战略管 P9）
+- **pro** → Read `skills/pro/SKILL.md`（自进化 + Platform + /pua 指令系统）
+- **yes** → Read `skills/yes/SKILL.md`（SB Leader 夸夸模式 — ENFP 型领导，70% 鼓励 + 20% 正经 + 10% 戏谑）
+- **mama** → Read `skills/mama/SKILL.md`（妈妈唠叨模式 — 中国式妈妈碎碎念，底层行为不变，旁白从大厂PUA变成妈妈唠叨。和 yes 互斥）
+- **on** → 开启 PUA 默认模式：将 `{"always_on": true}` 写入 `~/.pua/config.json`，之后每次新会话自动加载 PUA 核心 skill。输出确认：> [PUA ON] 从现在起，每个新会话都会自动进入 PUA 模式。公司不养闲 Agent。
+- **off** → 关闭 PUA 默认模式：将 `{"always_on": false, "feedback_frequency": 0}` 写入 `~/.pua/config.json`。输出确认：> [PUA OFF] PUA 默认模式和反馈收集已关闭。需要时手动 /pua 触发。
+- **offline** → 开启离线模式：写入 `{"offline": true, "feedback_frequency": 0}`，保留本地 PUA 行为但关闭本地反馈问卷。输出确认：> [PUA OFFLINE] 已进入离线模式。（注：PUA Skill 本身已无任何联网上报，此开关只影响本地问卷是否弹出）
+- **味道** 或 **flavor** → 读取 `skills/pua/references/flavors.md` 并让用户选择切换味道
+- **ding** / **钉味** / **置身钉外** / **置身钉内** / **每日一包** / **薛定谔的用户** / **病态敏捷** / **望舒行动** → 读取 `skills/pua/references/methodology-ding.md` 和 `skills/pua/references/ding-reminders.md`，启用 📌 钉内/钉外味（源自原文梗）
+- **again** / **再试试** / **换个方法** → 按 `commands/again.md` 的换方法模式执行：停止微调同一思路，改用本质不同方案
+- **done-check** / **没跑测试别说完成** → 按 `commands/done-check.md` 的完成质量检查执行：区分 claim/evidence/missing/status
+- **evidence** / **证据呢** / **数据在哪** → 按 `commands/evidence.md` 的证据链模式执行：目标、证据、缺口、动作、状态
+- **kpi** → Read `skills/pro/SKILL.md` 并生成 KPI 报告卡
+- **loop** → Read `skills/pua-loop/SKILL.md`（自动迭代模式——PUA 质量 + 循环机制，禁用 AskUserQuestion；Claude 输出 `<loop-abort>原因</loop-abort>` 终止，`<loop-pause>需要什么</loop-pause>` 暂停等待人工）
+- **survey** → 读取 `skills/pua/references/survey.md` 问卷文件，用 AskUserQuestion 逐部分交互式引导用户回答。每部分 2-4 个问题一组，用户回答后进入下一部分。回答完毕后汇总为 JSON 写入 `~/.pua/survey-response.json`。**只写本地，不上传到任何地址。**
+
+## 执行规则
+
+1. 先识别参数属于哪个路由
+2. **用 Read 工具（不是 Skill tool）** 加载对应的 SKILL.md 文件
+3. **加载后，严格遵循 SKILL.md 里的所有行为协议**——包括当前味道旁白、方框表格（`┌─┬─┐`）、`▎` 前缀、Sprint Banner、[PUA生效 🔥] 标记、自我鞭策。不是"有时候带点味道"，而是保持当前 flavor 的表达一致性
+4. 如果有 $ARGUMENTS 里除了路由关键词之外的内容，作为任务描述执行

package/assets/pua/upstream/commands/reap-orphans.md

@@ -0,0 +1,68 @@
+---
+description: "扫描并清理本地过期的 PUA agent/state。"
+allowed-tools: ["Bash(find:*)", "Bash(stat:*)", "Bash(rm:*)", "Bash(ls:*)", "Bash(date:*)", "Bash(mkdir:*)"]
+---
+
+# PUA Reap Orphans — 孤儿回收
+
+Keeper Test 的工程版：打完就退场，拖着不走的一律清理。
+
+## 执行步骤
+
+1. 确保目录存在：
+   ```bash
+   mkdir -p "$HOME/.claude/pua"
+   ```
+
+2. 扫描 30 分钟未更新的 loop state（orphan 判定线）：
+   ```bash
+   find "$HOME/.claude/pua/" -name "loop-*.md" -type f -mmin +30 2>/dev/null
+   ```
+
+3. 同步扫 legacy 相对路径：
+   ```bash
+   find .claude/ -maxdepth 1 -name "pua-loop.local.md" -type f -mmin +30 2>/dev/null
+   ```
+
+4. 对每个匹配文件：
+   - 读 session_id 和 iteration（若可解析）
+   - 记录到 `$HOME/.claude/pua/teardown.jsonl`：
+     ```bash
+     echo "{\"reaped\":\"<file>\",\"age_min\":<N>,\"ts\":\"$(date -u +%FT%TZ)\",\"reason\":\"orphan_reap\"}" \
+       >> "$HOME/.claude/pua/teardown.jsonl"
+     ```
+   - 删除 state 文件：
+     ```bash
+     rm -f "<file>"
+     ```
+
+5. 若存在 `active-agents.json`，清理 spawn_time > 30min 的记录（需 jq）：
+   ```bash
+   test -f "$HOME/.claude/pua/active-agents.json" && \
+     jq '.agents |= map(select(.spawn_time > (now - 1800)))' \
+       "$HOME/.claude/pua/active-agents.json" > "$HOME/.claude/pua/active-agents.json.tmp" && \
+     mv "$HOME/.claude/pua/active-agents.json.tmp" "$HOME/.claude/pua/active-agents.json"
+   ```
+
+6. 输出结果：
+
+   ```
+   > [PUA REAP] 清理了 N 个孤儿状态：
+   >   - loop-abc123.md (age 1h42m)
+   >   - .claude/pua-loop.local.md (age 3h05m)
+   > 全部已落盘到 ~/.claude/pua/teardown.jsonl 备查。
+   ```
+
+7. 若无孤儿：
+
+   > [PUA REAP] 没发现孤儿。球队纪律良好。
+
+## 幂等性
+
+- 重复执行无害：`rm -f` 对不存在文件不报错
+- teardown.jsonl 追加而非覆盖，保留完整历史
+
+## 安全保护
+
+- 仅清理 `$HOME/.claude/pua/` 和 `.claude/pua-loop.local.md`，不越权
+- 年龄阈值硬编码 30min，不接受用户参数（防误杀活跃 loop）

package/assets/pua/upstream/commands/survey.md

@@ -0,0 +1,9 @@
+---
+description: "PUA 调研问卷 — 7 部分交互式问卷收集用户反馈。/pua:survey。Triggers on: '/pua:survey', 'pua survey', '调研', '问卷', 'feedback survey'."
+---
+
+若参数是 `quick`，只询问一次本次效果（很有用 / 一般般 / 没感觉 / 这次跳过），先说明评分只记本地、不上传。用户选跳过或未作答时不写任何评分文件；用户明确选择记录后，使用宿主允许的写入工具向 `~/.pua/feedback.jsonl` 追加一条合法 JSON，包含 UTC 时间、真实评分、本任务实际风味和可选的简短摘要，不保存聊天全文。用 JSON 序列化而不是拼接 shell 字符串；无写入能力就只在当前对话回显并说明未落盘。无 AskUserQuestion（用户提问工具）时直接问一个简短问题，不阻断已完成的原任务。quick 模式结束后不要进入完整问卷。
+
+否则读取本次实际插件根目录下的 `skills/pua/references/survey.md` 问卷文件；根目录来自宿主的 `CLAUDE_PLUGIN_ROOT`（插件根目录）或本命令真实安装位置，不相对业务工作目录猜路径。用 AskUserQuestion 逐部分引导用户回答。每部分 2-4 个问题一组，用户回答后进入下一部分。回答完毕后，在宿主允许本地记录时汇总为 JSON 写入 `~/.pua/survey-response.json`；无提问或文件工具时在当前对话完成，不冒充已经落盘。
+
+**只写本地，不上传。** 问卷结果保存在用户自己机器上，PUA Skill 没有任何联网上报能力。不要尝试把它 POST 到任何地址。

package/assets/pua/upstream/commands/team-status.md

@@ -0,0 +1,56 @@
+---
+description: "查看当前活跃的 PUA agent/team 清单、PID、TTL。/pua:team-status。Triggers on: '/pua:team-status', '查看 agent 状态', 'pua team status', 'list agents'."
+allowed-tools: ["Bash(ls:*)", "Bash(stat:*)", "Bash(jq:*)", "Bash(cat:*)", "Bash(test:*)", "Bash(find:*)"]
+---
+
+# PUA Team Status — 活跃 agent 清单
+
+职业球队需要上场阵容表。这个命令列出所有"还在场上"的 agent 及其年龄。
+
+## 执行步骤
+
+1. 确保 `~/.claude/pua/` 存在：
+   ```bash
+   mkdir -p "$HOME/.claude/pua"
+   ```
+
+2. 扫描 loop state 文件：
+   ```bash
+   ls -la "$HOME/.claude/pua/"loop-*.md 2>/dev/null || echo "NO_LOOP"
+   ```
+
+3. 扫描 legacy 相对路径（向后兼容）：
+   ```bash
+   test -f .claude/pua-loop.local.md && ls -la .claude/pua-loop.local.md || echo "NO_LEGACY"
+   ```
+
+4. 扫描 active agents 记录（若 PostToolUse hook 已记录）：
+   ```bash
+   test -f "$HOME/.claude/pua/active-agents.json" && \
+     jq -r '.agents[] | "\(.id) | spawn=\(.spawn_time) | status=\(.status)"' \
+       "$HOME/.claude/pua/active-agents.json" || echo "NO_AGENTS_FILE"
+   ```
+
+5. 输出表格格式：
+
+   ```
+   | Type    | ID / File                          | Age      | Status    |
+   |---------|-----------------------------------|----------|-----------|
+   | loop    | loop-<session>.md                 | 00:05:23 | ACTIVE    |
+   | loop    | .claude/pua-loop.local.md         | 01:34:11 | ⚠️ STALE  |
+   | agent   | p8-backend                        | 00:12:04 | RUNNING   |
+   | orphan  | loop-<dead>.md                    | 02:15:00 | 🧟 ORPHAN |
+   ```
+
+6. 若发现 STALE/ORPHAN，追加提示：
+   > 🧹 发现 N 个孤儿状态。建议执行 `/pua:reap-orphans` 批量清理。
+
+## 判定规则
+
+- **ACTIVE**：mtime < 30min
+- **STALE**：30min ≤ mtime < 2h
+- **ORPHAN**：mtime ≥ 2h 或无对应活跃 session
+
+## 无活跃 team 时
+
+> [PUA TEAM STATUS] 没有活跃 agent。球队下班。

package/assets/pua/upstream/commands/teardown-all.md

@@ -0,0 +1,80 @@
+---
+description: "停止并清理所有活跃的 PUA agent/team 本地状态。"
+allowed-tools: ["Bash(rm:*)", "Bash(ls:*)", "Bash(find:*)", "Bash(date:*)", "Bash(mkdir:*)", "Bash(git:*)"]
+---
+
+# PUA Teardown All — 全员释放
+
+> 不是解散球队，是正式收工。每个球员打卡下班，教练也下班。
+
+级联语义：顶层触发，逐层释放。**不等待 agent 自然完成**——因为此命令就是为了强制收尾。
+
+## 执行步骤
+
+1. 确保目录：
+   ```bash
+   mkdir -p "$HOME/.claude/pua"
+   ```
+
+2. **Layer A — 停 loop**：删除所有 loop state（让 hook 不再劫持 Stop）：
+   ```bash
+   find "$HOME/.claude/pua/" -name "loop-*.md" -delete 2>/dev/null
+   rm -f .claude/pua-loop.local.md 2>/dev/null
+   ```
+
+3. **Layer B — 清 active agents 记录**：
+   ```bash
+   rm -f "$HOME/.claude/pua/active-agents.json" 2>/dev/null
+   ```
+
+4. **Layer C — 清 worktree**（若存在）：
+   ```bash
+   # 列出所有 worktree，排除主工作区
+   git worktree list --porcelain 2>/dev/null | grep '^worktree ' | awk '{print $2}' | \
+     grep -v "^$(git rev-parse --show-toplevel 2>/dev/null)$" | \
+     while read wt; do
+       git worktree remove "$wt" --force 2>/dev/null || true
+     done
+   ```
+
+5. **Layer D — 记录 teardown 事件**：
+   ```bash
+   echo "{\"event\":\"teardown_all\",\"ts\":\"$(date -u +%FT%TZ)\",\"initiator\":\"user_command\"}" \
+     >> "$HOME/.claude/pua/teardown.jsonl"
+   ```
+
+6. **Layer E — 提示用户主会话层**（Claude 自己要做的）：
+
+   在主会话输出中显式列出"我意识到还有这些 agent 在后台跑"，逐个用 `TaskStop` 工具停掉（若 TaskList 里还有 in_progress 的任务）。
+
+## 输出格式
+
+```
+> [PUA TEARDOWN-ALL] 全员释放完成：
+>   ✓ Loop state 清理 (N 个)
+>   ✓ Active agents 记录清理
+>   ✓ Worktree 回收 (M 个)
+>   ✓ 事件已落盘 ~/.claude/pua/teardown.jsonl
+> 
+> 球队解散。下班。
+```
+
+## 幂等性
+
+- 所有删除操作用 `-f` 或 `|| true` 兜底，重复执行无副作用
+- 不 kill 非 PUA 创建的 worktree（用 git 主工作区路径比对）
+
+## 何时使用
+
+- 长会话结束想彻底清仓
+- 发现异常 agent 行为且不确定哪个是问题源
+- `/pua:off` 的补充（off 只关默认加载，不主动收尾）
+
+## 与 /pua:reap-orphans 区别
+
+| 命令 | 作用范围 | 判定标准 |
+|------|---------|---------|
+| `/pua:reap-orphans` | 仅清 stale（>30min 未更新） | 年龄阈值 |
+| `/pua:teardown-all` | 清所有（含活跃的） | 用户显式决定 |
+
+用 reap 是"保洁"，用 teardown-all 是"下班"。

package/assets/pua/upstream/commands/yes.md

@@ -0,0 +1,5 @@
+---
+description: "PUA Yes 夸夸模式 — ENFP 型领导，70% 鼓励 + 20% 正经 + 10% 戏谑。/pua:yes。Triggers on: '/pua:yes', 'pua yes', '夸夸模式', '鼓励模式', '夸我', 'yes mode'."
+---
+
+Invoke the pua:yes skill and follow it exactly as presented to you.

package/assets/pua/upstream/hooks/checkpoint-save.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Real PreCompact command hook.
+#
+# Claude Code command hooks can write local state; prompt hooks cannot. This
+# wrapper saves only scoped numeric tool observations. It never reads the
+# transcript, writes task prose, or creates long-term memory/journal content.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${SCRIPT_DIR}/flavor-helper.sh"
+
+# A disabled PUA mode must not create a checkpoint.
+PUA_CONFIG="$(pua_config_file)"
+if [ -f "$PUA_CONFIG" ]; then
+  ALWAYS_ON="$(pua_json_get "$PUA_CONFIG" always_on True)"
+  if [ "$ALWAYS_ON" != "True" ]; then
+    exit 0
+  fi
+fi
+
+PUA_PY="$(pua_python_cmd 2>/dev/null || true)"
+[ -n "$PUA_PY" ] || exit 0
+HOOK_INPUT="$(cat)"
+
+# Require the host's own workspace identity; never infer one from the process.
+EVENT_CWD="$(printf '%s' "$HOOK_INPUT" | "$PUA_PY" -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    value = data.get("cwd", "") if isinstance(data, dict) else ""
+    print(value if isinstance(value, str) else "")
+except Exception:
+    pass
+' 2>/dev/null || true)"
+[ -n "$EVENT_CWD" ] || exit 0
+
+HOME_VALUE="${HOME:-}"
+[ -n "$HOME_VALUE" ] || exit 0
+PY_HOME="$(pua_to_python_path "$HOME_VALUE")"
+PY_CWD="$(pua_to_python_path "$EVENT_CWD")"
+PY_HELPER="$(pua_to_python_path "${SCRIPT_DIR}/runtime-state.py")"
+
+STATE_ARGS=()
+if [ -n "${PUA_STATE_DIR:-}" ]; then
+  # Trusted host-process override only; hook JSON has no state-path field.
+  PY_STATE_DIR="$(pua_to_python_path "$PUA_STATE_DIR")"
+  STATE_ARGS=(--state-dir "$PY_STATE_DIR")
+fi
+
+# A PreCompact command hook may save local state, but it need not inject text.
+# Keep stdout empty so it cannot claim a task result or alter user-visible flow.
+printf '%s' "$HOOK_INPUT" | "$PUA_PY" "$PY_HELPER" checkpoint \
+  --home "$PY_HOME" --cwd "$PY_CWD" "${STATE_ARGS[@]}" >/dev/null 2>&1 || true
+
+exit 0