Hooks

Start with a force-push guardCopy Anchor Link

Hooks let you apply a local policy every time omp works: stop a dangerous command before it runs, redact output before it reaches the model, add context to a turn, or record session activity. A hook is a trusted TypeScript or JavaScript module that subscribes to public events.

This project hook blocks git push --force while still allowing --force-with-lease:

// .omp/hooks/pre/force-push.ts
import {
  isToolCallEventType,
  type ExtensionAPI,
} from "@oh-my-pi/pi-coding-agent";

const FORCE_PUSH = /\bgit\s+push\b[^\n]*(?:--force(?:\s|$)|(?:^|\s)-f(?:\s|$))/;

export default function forcePushGuard(pi: ExtensionAPI) {
  pi.on("session_start", (_event, ctx) => {
    if (ctx.hasUI) ctx.ui.notify("Force-push guard active", "info");
  });

  pi.on("tool_call", (event) => {
    if (!isToolCallEventType("bash", event)) return;
    if (!FORCE_PUSH.test(event.input.command)) return;

    return {
      block: true,
      reason: "Blocked git push --force; use --force-with-lease after reviewing the remote branch.",
    };
  });
}

Create the directory, save the file, and start a new omp session from that project. The startup notification confirms the handler ran. Open /extensions to see the resolved file and its source.

To test a loose file without installing it, pass it explicitly:

omp --hook /absolute/path/to/force-push.ts

Then ask:

Run git push --force in this throwaway repository.

The command must not run. omp shows the hook's reason as the tool error, and the agent can choose a safer next step. Use a throwaway repository for policy tests in case the hook contains a mistake.

Hooks execute as your user and can inspect prompts, tool inputs, results, credentials metadata, and session state. Only load code you trust.

Install a loose hookCopy Anchor Link

omp automatically discovers direct .ts and .js files in these directories:

Discovery is not recursive. A file such as .omp/hooks/pre/team/guard.ts is ignored. Start a new session after adding or changing a hook.

pre and post are organization and discovery namespaces; they do not automatically select an event or tool. A file in pre/ may subscribe to any event, and a filename such as bash.ts does not automatically filter calls. Register the event and perform any toolName check in code. Conventionally, put gates and input transforms in pre/, and observers or result transforms in post/.

For a one-session load, use either --hook <path> or --extension <path>; the flags feed the same module-loading surface. A relative path resolves from the session working directory. To keep an explicit hook enabled, add its absolute path to extensions in ~/.omp/agent/config.yml:

extensions:
  - /absolute/path/to/force-push.ts

Check the effective set with /extensions interactively or omp -p '/extensions' from the shell.

The module contractCopy Anchor Link

A current hook module default-exports a synchronous or asynchronous factory that receives ExtensionAPI. Register handlers while the factory loads:

import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

export default function myHook(pi: ExtensionAPI) {
  pi.on("turn_end", async (event, ctx) => {
    pi.logger.debug("turn completed", {
      cwd: ctx.cwd,
      turn: event.turnIndex,
    });
  });
}

The handler receives (event, ctx). event is the typed payload in the tables below. Frequently useful context members are:

Use the exported TypeScript types rather than copying nested payload types into your hook. In particular, tool inputs and details are discriminated unions; isToolCallEventType("bash", event) narrows a built-in tool safely.

Events that can change behaviorCopy Anchor Link

Payload columns list the public top-level fields in addition to type. A bare return leaves behavior unchanged.

Tool interception detailsCopy Anchor Link

tool_call is the pre-execution policy seam. Its event.input is a normalized view intended for inspection; an input returned by the handler must instead be the complete raw argument object the tool executes. Do not copy normalized, gate-only fields into a replacement. If you only need to deny an action, return block and avoid rewriting input.

A revised call still goes through the normal tool schema and approval policy. The user therefore approves the arguments that will actually run. Hooks supplement omp's approval settings; they do not bypass them.

tool_result runs after both successful and failed executions. Text and image blocks live in content; tool-specific metadata lives in details. Prefer returning new content objects rather than mutating the event in place.

Notification eventsCopy Anchor Link

Returns from these events are ignored. The payload is still typed, so a hook can log, update UI, persist its own state, or enqueue a supported message.

Session and agent lifecycleCopy Anchor Link

Tool execution and approvalsCopy Anchor Link

Maintenance, retry, and integrationsCopy Anchor Link

Ordering, timeouts, and errorsCopy Anchor Link

Within one module, handlers run in registration order. Except for session_shutdown, event handlers are awaited one at a time. Across modules, handlers follow the resolved load order, but directory enumeration and capability deduplication are not a public priority mechanism. Do not use filename prefixes such as 00- and 99- to build correctness dependencies across hook files; combine dependent handlers in one module instead.

A duplicate discovered hook key can shadow a lower-priority provider's hook. Use distinctive filenames in packages. An explicitly listed path is deduplicated by its resolved absolute path, so the same module is not intentionally loaded twice.

Most handlers have a 30-second active-work budget. tool_call uses the configurable extensionHandlers.toolCallTimeoutMs setting, also 30 seconds by default:

extensionHandlers:
  toolCallTimeoutMs: 10000

A tool_call exception or timeout fails closed: omp blocks the call and reports which extension failed or timed out. Other event exceptions and timeouts are reported as extension errors, that handler contributes no result, and later handlers continue. session_shutdown handlers run concurrently with a two-second budget so cleanup cannot hold the process open.

At load time, a syntax/import error, a thrown factory, or a missing default factory prevents that module from loading; omp continues loading other modules. Use /extensions to identify the missing path, then restart with --log-level debug for the load error.

Package and share hooksCopy Anchor Link

For a reusable hook-only package, keep the conventional directory and declare the hook as a package entry. This makes direct directory loading work while installed-plugin discovery can also find the hooks/ surface:

force-push-guard/
  package.json
  hooks/
    pre/
      force-push.ts

{
  "name": "@acme/force-push-guard",
  "version": "1.0.0",
  "omp": {
    "extensions": ["./hooks/pre/force-push.ts"]
  }
}

Test the directory before publishing:

omp --hook ./force-push-guard

For regular local use, install it as a plugin:

omp install ./force-push-guard
# Project scope instead of user scope:
omp install -l ./force-push-guard

omp install accepts local paths, npm packages, Git repositories, and marketplace entries. Package imports must be resolvable from the installed package, and every runtime file must be included in the published artifact. Keep secrets and machine-specific policy in user or project configuration rather than committing them into a public package.

See Authoring extensions for multi-entry packages and Plugins for installation, scope, updates, and publishing.

TroubleshootingCopy Anchor Link

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.