Hooks 配置

蓝木偶使用 Claude Code 的 http 类型 Hook。Claude Code 会把事件完整 JSON 作为 POST body 发出，不需要额外的 stdin 桥接脚本。

完整配置

将以下 hooks 内容合并到项目的 .claude/settings.json。这与程序托盘和宠物菜单中的 复制配置 使用同一组事件。

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion|ExitPlanMode",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      },
      {
        "matcher": "*",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|elicitation_dialog|agent_needs_input",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ],
    "StopFailure": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "http", "url": "http://127.0.0.1:48291/state" }
        ]
      }
    ]
  }
}

修改后需要重启 Claude Code。

事件如何变成状态

Hook 事件	条件	宠物状态
UserPromptSubmit	用户提交任务	working
PreToolUse	AskUserQuestion 或 ExitPlanMode	question
PreToolUse	其他工具	working
PermissionRequest	等待权限确认	question
Notification	普通通知	question
Notification	内容命中 429、过载、限流等关键词	error
PostToolUse	工具调用成功	happy
PostToolUseFailure	工具调用失败	error
Stop	没有仍在运行的后台任务	done
Stop	检测到后台任务仍在运行	sneaky
StopFailure	停止过程失败	error

状态映射在宠物端完成，Hook 本身不传 state。question 还有保护规则，普通的后续 working 事件不会立刻盖掉等待用户输入的状态，详见 状态与交互。

自定义端口

默认端口为 48291。如果通过 BLUE_PUPPET_PORT 修改端口，必须同时修改 Hook URL：

http://127.0.0.1:你的端口/state

最简单的方式是先设置环境变量并启动蓝木偶，再使用程序内置的 复制配置，这样剪贴板里的 URL 会自动带上当前端口。

宠物未运行时会怎样？

HTTP 连接失败是非阻塞错误，不会打断 Claude Code 的任务，只是桌面状态不会更新。恢复蓝木偶后，后续新事件会继续驱动宠物。