钩子

快速开始

mkdir -p ~/.matcha/hooks

~/.matcha/hooks/session-start.json：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "echo 'Matcha session started in '$(pwd)" }
        ]
      }
    ]
  }
}

开始或重启会话。打开 /hooks，确认钩子列在 **Global** 下。

钩子从哪里加载

所有来源会合并：

在你信任该文件夹之前，项目钩子会被跳过。/hooks-trust（或启动时 --trust）写入 ~/.matcha/trusted_folders.toml。该授权同时覆盖 **钩子、MCP 和 LSP**，并向下级联到子目录。

/hooks-untrust 撤销它。~/.matcha/hooks/ 里的全局钩子从不需要条目。

Claude 风格的 matcher 名如 Bash 仍匹配 Matcha CLI 的 run_terminal_command。Cursor 的 camelCase 事件名映射到同一事件（preToolUse → PreToolUse）。

你会实际用到的事件

PreToolUse 可以拒绝。Stop / SubagentStop 可以拦住结束，并把原因回传给助手（每轮最多续 8 次）。其他事件只观察。钩子失败时 **失败放行**：崩溃或超时不会拦住工具。只有明确的 {"decision":"deny","reason":"…"}（或 PreToolUse 退出码 2）才会拦住。

matcher 是对真实工具名的正则。MCP 工具显示为 server__tool（例如 linear__save_issue），不是内部的 use_tool 分发器。

拦截式 shell 守卫

~/.matcha/hooks/safe-shell.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bin/safe-shell.sh", "timeout": 5 }
        ]
      }
    ]
  }
}

bin/safe-shell.sh（与 JSON 同级，需可执行）：

#!/bin/sh
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.toolInput.command // empty')
if echo "$CMD" | grep -qE '(rm -rf /|mkfs)'; then
  echo '{"decision": "deny", "reason": "Blocked potentially destructive command"}'
  exit 2
fi
echo '{"decision": "allow"}'

事件以 JSON 经 stdin 到达。常见字段包括 hookEventName、sessionId、cwd、workspaceRoot、toolName 和 toolInput。

在 TUI 里管理

/hooks

打开扩展模态框的 **Hooks** 标签页。分页器斜杠菜单 **不** 列出 /hooks-list、/hooks-add、/hooks-remove、/hooks-trust 或 /hooks-untrust；这些 shell 命令仍然可用，模态框覆盖同样的工作。

从 shell 会话（或 ACP）也可以运行：

/hooks-list
/hooks-add ~/.matcha/hooks
/hooks-remove ~/.matcha/hooks
/hooks-trust
/hooks-untrust

你应该看到