Plugin hooks

​

Codex-format hooks

​

Where they come from

• The project is not trusted.
• The workspace is not a local or worktree workspace, for example an SSH, Docker, devcontainer, or Coder workspace.
• The workspace is a multi-project workspace.
• The chat is a /side chat.

​

Trust a hook

1. Open Settings → Plugins and select Hooks on the plugin. You can also run Review Plugin Hooks… from the command palette.
2. Read each hook. If Xum cut a long input, select Show full input first. Trust stays off until you do.
3. Select Trust. Select Turn off to stop a hook.

• The definition changes. The hook shows changed, needs review and does not run until you trust it again.
• The hook moves to another place in its file, for example to another group. It then shows needs review.
• You turn the hook off.
• You uninstall the plugin. A reinstall under the same name starts with no trusted hooks.

​

Events and handlers

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "guard",
            "tool": "check_command",
            "input": { "command": "${tool_input.command}", "cwd": "${cwd}" },
            "timeout": 5
          }
        ]
      }
    ]
  }
}

​

Matchers

• "*", "", null, or no matcher matches every tool.
• A list of names (letters, digits, _, and |, for example Bash|Edit) matches a whole name, not a substring.
• Any other value is a regex. Codex uses the Rust regex dialect. Xum compiles it as a JavaScript RegExp.
• A leading flag group of i, m, and s (for example (?i) or (?is)) becomes RegExp flags.
• Xum translates (?P<name>...) to a JavaScript named group, and the \A and \z anchors to lookarounds that mean the start and end of the name, as in Rust. A group name must follow Rust’s rule and compile in JavaScript (letters, numbers, and _, at most 128 characters). A name used twice is refused.
• Xum refuses other Rust syntax that JavaScript reads in a different way or rejects. Examples are inline flags after the start, negated flags ((?-i)), the x, U, u, and R flags, \pL, \p{...}, \x{...}, \b{start}, \<, \>, nested or POSIX classes ([[:alpha:]]), and &&, --, or ~~ in a class.

​

Timeouts

​

Event fields

​

Tool names and the Bash contract

​

Outputs Xum honors

​

What fails open

• The hook times out, errors, or returns an MCP error.
• The server or tool is missing, disabled, or not running.
• The output is malformed: invalid JSON, a wrong type, or a value outside an enum. A deny or block in the same output is ignored too.
• The output has an unknown field. Xum then ignores the hook’s other output, with two exceptions: on PreToolUse, PostToolUse, and UserPromptSubmit an explicit deny or block still applies, and a PreToolUse rewrite (updatedInput) makes Xum deny the call, because the hook allowed only its rewrite. On Stop, an unknown field voids the whole output, a block included. On every event, Xum still shows a systemMessage to you.
• The result text is over 1 MiB (1,048,576 characters).

​

Size limits

​

Known gaps

• PostToolUse sees the MCP result after Xum’s transform, not the raw MCP response. Xum removes protocol _meta, cuts large text, and converts binary content to Xum’s { type: "content", value: [...] } shape.
• UserPromptSubmit has no turn_id and no model.
• Only bash and MCP tools have Codex names. Hooks match file edits, task, and other tools by their Xum names.

​

Xum-native hooks

{
  "extensions": { "mux": { "hooks": { "tools": ["bash"] } } }
}

({
  "tool.execute.before": (input) => {
    if (input.toolName === "bash" && input.args.script.includes("--force")) {
      return { deny: "Force flags are blocked." };
    }
  },
});

• settingsOmitted: true: the settings JSON is over 64 KiB (65,536 UTF-8 bytes). The hook gets settings: {}.
• resultOmitted: true: the tool result is over 256 KiB (262,144 characters) as JSON, or Xum cannot serialize it as JSON. tool.execute.after gets no result.