add

Add a handrail Rule

A Rule is one markdown file: a YAML frontmatter Matcher and a prose message. The filename is the rule's identity. You write the file, handrail validates it.

1. Resolve the binary

HANDRAIL=$(command -v handrail || echo "${XDG_DATA_HOME:-$HOME/.local/share}/handrail/bin/handrail")

If it does not exist, the SessionStart bootstrap has not run yet: tell the user to start a new session, or to install with brew install svyatov/tap/handrail. Do not hand-write harness config as a workaround.

2. Ask for what the description does not settle

Only ask about what you cannot infer. Most descriptions settle everything but the tier.

• What the rule catches: which event, which tool kind, which field values.
• Action: block denies the call with the message as the reason; warn lets it proceed and injects the message. Default to warn unless the user says never, or the action is destructive.
• Tier: see step 4.

3. Write the Matcher

---
event: PreToolUse
kind: shell
action: block
conditions:
  - field: command
    starts_with: git push --force
---
Never force-push. Rewrite history locally and open a pull request instead.

Events: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, Stop. event: is required. block is only enforceable on PreToolUse, UserPromptSubmit, and Stop; elsewhere it degrades to a warn, and sync and doctor report where. Codex also degrades a UserPromptSubmit block to a warn.

Kinds (optional; omit to match every kind) and the fields each carries:

kind	Fields
shell	command
file_edit	path, content
file_read	path
mcp	server, tool
other	none

UserPromptSubmit carries prompt. A condition against a field the event does not carry never matches, in either polarity, so narrow with event: and kind: rather than relying on a field being absent. Only PreToolUse and PostToolUse carry a kind at all: a kind: on any other event never matches.