Apply hooks and rules

Rules contribute normalized instructions to the prompt. Hooks execute code at named lifecycle events. Use rules for guidance that does not need side effects; use a hook only when an event must inspect, transform, or reject runtime data.

How are rules discovered and classified?

Rule providers scan project and user roots, parse frontmatter, normalize identifiers, then deduplicate by precedence. Classification separates ordinary rulebook entries, always-apply guidance, and time-to-self-reflect material. The rule:// handler resolves the final normalized item rather than reading an arbitrary path.

What determines hook execution order?

A hook module exports handlers for supported events. Discovery determines the module set, and registration order determines sequential mutation when more than one handler sees the same payload. A thrown error follows the event’s propagation contract; it is not converted into a successful empty result.

How do I test the hook boundary?

Exercise each of these separately:

1. Discovery, so the module set is the one you expect.
2. The exact event, with a representative payload.
3. Mutation ordering, with more than one handler registered.
4. Cancellation.
5. A handler that throws.

Interface calls made by hooks require an interactive host, so a headless integration must not assume a modal interface exists.

Run the test in a disposable project root and name the exact event under test. A rule changes model input but has no direct execution authority; a hook executes in the xcsh process and may reject or mutate its event payload. After the focused run, disable rules or hooks and repeat the same prompt to attribute the difference. Remove the test file and confirm discovery no longer lists its identifier.