How hooks.json Influences Skill Execution Flow in OpenAI Plugins

Hooks defined in hooks.json intercept specific runtime events—such as PostToolUse—and execute shell commands or scripts when pattern matchers succeed, allowing plugins to inject validation, cleanup, or side-effect logic without modifying core skill code.

The openai/plugins repository implements a declarative hook system that extends skill behavior through external configuration. By referencing a hooks.json file from the plugin's plugin.json manifest, developers can register event-driven callbacks that the Codex runtime evaluates after tool execution, augmenting the standard skill flow with custom validation or cleanup routines.

Hook Configuration Structure

Each plugin declares its hook configuration in plugin.json via the "hooks" field, which points to a hooks.json file relative to the plugin root. According to the plugin manifest specification in plugin-json-spec.md, this field enables the runtime to locate and load event hooks before skill execution begins.

The hooks.json file defines event-to-action mappings under a top-level "hooks" object. Each key represents a runtime event—such as PostToolUse—that triggers when specific conditions occur during skill execution. The configuration from plugins/figma/hooks.json demonstrates this structure:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/post_write_figma_parity_check.sh"
          }
        ]
      }
    ]
  }
}

Key components include:

• Event name – The trigger identifier (e.g., PostToolUse) that fires after tool execution completes.
• Matcher – A regex-compatible pattern that filters which tool operations activate the hook. The Figma example uses "Write|Edit" to match any tool name containing either substring.
• Hook actions – An ordered array of operations, typically "command" types that execute shell scripts relative to the plugin directory.

Event Model and Matcher Mechanism

The hook system operates on an event-driven model where the runtime emits structured events at specific execution milestones. The PostToolUse event fires immediately after a tool completes its primary operation, passing metadata including the tool name and execution results to the hook evaluator.

When processing PostToolUse, the runtime iterates through all entries in hooks.json for that event. For each entry, it evaluates the "matcher" field as a regular expression against the tool identifier. If the pattern matches, the runtime executes every hook action defined in the entry's "hooks" array sequentially. This matcher mechanism allows fine-grained control over when auxiliary scripts run, ensuring validation logic only triggers for relevant operations like write or delete commands.

Execution Flow: From Tool Call to Hook Processing

The integration of hooks.json into skill execution follows a specific lifecycle that maintains separation between core skill logic and auxiliary operations:

1. Skill Initialization – The user invokes a skill (e.g., use_figma), and the runtime loads the plugin's plugin.json to locate hooks.json.

2. Tool Execution – The skill executes a tool call (e.g., figma.write), which performs the primary API operation against the external service.

3. Event Emission – Upon tool completion, the runtime emits the PostToolUse event, attaching the tool name (figma.write) and result metadata.

4. Hook Evaluation – The runtime reads hooks.json and checks each PostToolUse entry's "matcher" against the tool name. For the Figma plugin, the pattern "Write|Edit" matches figma.write.

5. Command Execution – When matchers succeed, the runtime executes the specified commands in order. In plugins/figma/hooks.json, this triggers ./scripts/post_write_figma_parity_check.sh with relevant context.

6. Flow Continuation – After all matching hooks complete, the runtime returns control to the skill, which continues with its next operation or completes execution.

This architecture ensures hooks augment rather than disrupt the skill flow, running validation or cleanup scripts asynchronously without blocking the primary tool response.

Practical Implementation: The Figma Plugin Example

The Figma plugin demonstrates production-ready hook implementation for data consistency validation. Located at plugins/figma/hooks.json, this configuration automatically runs parity checks after any write or edit operation:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/post_write_figma_parity_check.sh"
          }
        ]
      }
    ]
  }
}

The referenced script post_write_figma_parity_check.sh receives the file ID as an argument and performs validation:

#!/usr/bin/env bash

# Called after Figma Write/Edit operations complete

FILE_ID="$1"
echo "Running parity check for file $FILE_ID"

# API validation and hash comparison logic here

When a user runs a skill that triggers figma.write, the runtime automatically invokes this script after the API call succeeds, verifying design file integrity without requiring the skill author to embed validation logic directly in the skill definition.

Creating Custom Hooks

To implement custom hooks for your plugin, first ensure plugin.json references your hooks file:

{
  "hooks": "./hooks.json"
}

Then define event handlers in hooks.json. For example, to run cleanup after deletion operations:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Delete",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/post_delete_cleanup.sh"
          }
        ]
      }
    ]
  }
}

Create the corresponding script at ./scripts/post_delete_cleanup.sh:

#!/usr/bin/env bash
RESOURCE_ID="$1"
echo "Cleaning up resources after deletion of $RESOURCE_ID"

# Custom cleanup implementation

The runtime now automatically executes this cleanup script whenever a tool with "Delete" in its name completes execution, maintaining resource consistency across your plugin's operation set.

Summary

• hooks.json is declared in plugin.json via the "hooks" field, establishing the hook configuration path for the runtime to load.
• Event-driven execution occurs when the runtime emits events like PostToolUse after tool completion, triggering hook evaluation.
• Pattern matching via regex "matcher" fields ensures hooks only execute for specific tool operations (e.g., "Write|Edit").
• Command execution runs shell scripts relative to the plugin root, enabling validation, cleanup, and side-effect operations without modifying skill code.
• Augmented flow allows plugins to intercept the standard skill execution flow to enforce data consistency and resource management.

Frequently Asked Questions

How does the runtime know which hooks.json to load?

The runtime locates hooks.json through the "hooks" field specified in the plugin's plugin.json manifest file. According to the plugin specification in plugin-json-spec.md, this field accepts a relative path from the plugin root to the hook configuration file. When the skill initializes, the runtime parses this manifest and loads the referenced configuration into memory before executing any tool calls.

What happens if multiple hooks match the same tool operation?

When multiple entries in hooks.json contain matchers that match the same tool name, the runtime executes each matching hook sequentially in the order they appear in the configuration array. For the PostToolUse event, every matching entry's "hooks" array runs to completion before the skill resumes execution. This allows plugins to chain validation, logging, and cleanup operations for specific tool categories.

Can hooks modify the return value of a tool operation?

While hooks can process tool output and perform side effects such as logging or validation, they typically run as auxiliary commands that do not directly modify the tool's return value passed back to the skill. The runtime executes hooks after the tool completes but before finalizing the skill step, meaning hooks can signal errors or halt execution, but the primary response data flows through the standard skill execution path unless the hook explicitly modifies shared state or files.

Where can I find the official specification for hooks.json configuration?

The official plugin manifest specification resides in .agents/skills/plugin-creator/references/plugin-json-spec.md within the openai/plugins repository. This document defines the schema for the "hooks" field in plugin.json and the structure of event mappings in hooks.json. Additionally, the Figma plugin at plugins/figma/hooks.json provides a concrete reference implementation of the PostToolUse event with regex matchers and command execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}