[PLUGIN] claude-hot-limit — pacing guard for agent/workflow fan-out

[kiki830621]

New Plugin: claude-hot-limit

致敬「最燙的 bucket」。守住 Workflow/Agent fan-out 的啟動節奏，防止 back-to-back 暴衝撞上 Anthropic 的 acceleration-limit / short-burst 節流（429 / 529 "Server is temporarily limiting requests · not your usage limit"）。

起源：一次連開 4 個 workflow（每個 16 並發）→ 燒 ~4M token 換 0 產出。根因是觸發 server 端 acceleration limit（'sharp increase in usage'）。純 skill 提醒擋不住熱頭上的自己（『知道 batched 對卻還是連開』），所以核心是會真的 block 的 hook。

Components

• pacing-guard (PreToolUse hook, hooks/pacing-guard.py + hooks/hooks.json)
  • Burst guard：滾動窗口（預設 600s）內 Workflow/Agent 啟動數 ≥ 上限（預設 3）→ permissionDecision: deny
  • Min-gap：兩發 < 最小間隔（預設 20s）→ 自動 sleep（防 short-burst）
  • fail-open、flock 序列化、$CLAUDE_PLUGIN_DATA 跨 session 帳本
  • override：CLAUDE_HOT_LIMIT_OFF=1 或 $CLAUDE_PLUGIN_DATA/disabled 旗標
• pacing-playbook (skill)：設計期反 burst 引導 + 決策檢查表
• Agents: none / MCP: none

Status

• Directory structure
• plugin.json manifest
• pacing-guard hook + hooks.json
• pacing-playbook SKILL.md
• README / CLAUDE.md / CHANGELOG
• marketplace.json registered (39 plugins)
• 8/8 local RED/GREEN hook tests pass
• Committed + pushed (main: 549404f)
• Installed (claude-hot-limit@psychquant-claude-plugins)

Roadmap / TODO

• Dogfood：實跑後微調 WINDOW/MAX/MIN_GAP 預設值
• 評估用 PostToolUse / PostToolBatch 追蹤 concurrency 與完成（目前只看啟動率）
• 可選：per-session ledger 切換（目前 global，對 account 級節流較準）
• 可選：若 retry-after 被 surface，hook 讀秒數做精確 cooldown
• 觀察 hook 對正常多 agent 工作的摩擦，必要時調 deny→ask

誠實邊界

不繞 server-side 節流、不管 main-loop 自身 API 節奏；只管你發出的 fan-out 啟動節奏（acceleration-limit 的觸發源）。