How hooks work

The hook supervisor is the part of Pathrule that makes AI sessions feel like the assistant already knew about your team's conventions. It runs locally, reads from a cache, and delivers the right slice of memories, rules, and skills before the assistant takes its first action.

This page is a user facing model of the mechanics. It is not a deep dive into the runtime internals.

What is a hook

A hook is a small script your AI client invokes at well defined moments in a turn. Pathrule uses the delivery and enforcement events each client actually exposes.

• UserPromptSubmit scopes an upcoming turn on clients whose prompt event accepts context.
• SessionStart supplies a one-shot bootstrap on clients whose prompt event cannot carry context.
• PreToolUse supplies context or a strict-rule decision before an action when the client accepts it.
• PostToolUse records outcomes and compensates with path-scoped context on clients whose pre-tool event accepts decisions but not context.

When you attach a workspace, Studio handles the agents it runs natively. Pathrule CLI registers hook profiles for Cursor and GitHub Copilot, and can wire standalone Claude Code and Codex. Windsurf has no equivalent Pathrule hook profile, so its generated companion file supplies the session bootstrap and MCP supplies deeper context on demand.

Client delivery profiles

What the hook does

The hook supervisor does four things in order.

1. Resolve the path. It maps the working directory to a workspace node.
2. Read the cache. The local cache holds a precomputed index of memories, rules, and skills for that path.
3. Shape the slice. It picks a depth that fits the intent. A UI tweak gets a minimal payload. A bug fix or refactor gets a focused one. Discovery prompts unlock a deeper one.
4. Return the payload. The text comes back to the client as system context for the upcoming action.

The whole flow is local. There is no network round trip in the hot path.

What you see

The assistant's context surface (the one your editor exposes) gains a Pathrule section. It lists:

• The path the hook resolved to, plus the paths the work is most likely in, a route the assistant is asked to open before it searches. Pathrule records whether it did, so the routing is measured rather than assumed.
• The matching rules with their priority.
• The memories and skills most relevant to your prompt, delivered as full bodies the assistant can act on directly. Less certain matches still come through as titles with ids you can read in full if you want.
• The skills attached to this scope.

If the hook had nothing relevant for the current path, it returns a small empty marker so the assistant knows Pathrule was consulted and chose silence.

When the hook is not enough

Hooks are designed for the common case. The assistant can always reach for the MCP tools when it needs more.

• For discovery prompts ("list everything we know about billing"), the assistant calls pathrule_get_context directly.
• For full memory bodies, the assistant calls pathrule_read_memory with the id surfaced in the hook.
• For writes (the user asks to save a convention or a rule), the assistant uses the corresponding write tool.

The hook is the fast path. MCP is the deep path. Both share the same source of truth.

Path scope keeps it small

The hook returns a slice that is shaped by the working directory.

• A change in apps/web/dashboard does not pull in rules about database migrations.
• A change in services/billing/webhooks pulls in the billing rules and the webhook replay skill, not the marketing site conventions.
• A discovery prompt at the repo root pulls in a workspace overview, not every body.

Path scope is the main reason teams report large drops in context tokens after moving from a global CLAUDE.md style file to Pathrule.

When nothing appears

If you open a session and the Pathrule section is empty, run the doctor.

pathrule doctor

It checks:

• The workspace attachment for the current directory.
• The local cache freshness.
• The MCP server status.
• The hook registration in your AI client config.

The output reports any step that needs attention with a one line fix suggestion.

What to read next

• MCP overview for the tool surface that backs the deep path.
• Core concepts for the data model the hook reads from.
• CLI install for installing the runtime that hosts the hook supervisor.