pi-steering-hooks

Deterministic tool-call guardrails for pi. Enforce rules with before-tool hooks instead of prompts — zero token cost, 100% reliability.

Prompt-based rules ("never force push") work most of the time. Steering hooks work every time. They intercept tool calls before execution and block violations deterministically, with an override escape hatch for when the agent has a good reason.

Inspired by Strands Agents: Steering Accuracy Beats Prompts.

Install

pi install @samfp/pi-steering-hooks

Default Rules

Rule	Tool	What it blocks
no-force-push	bash	git push --force (destructive history rewrite)
no-hard-reset	bash	git reset --hard (discards uncommitted work)
no-rm-rf-slash	bash	rm -rf / (catastrophic, no override allowed)
conventional-commits	bash	Non-conventional git commit -m messages
no-long-running-commands	bash	Dev servers and watchers that block the agent

Override Mechanism

When a rule fires, the agent can retry with an override comment:

git push --force origin main  # steering-override: no-force-push — deploying hotfix to unblock prod

The override is allowed through but logged to the session for audit. Rules with noOverride: true (like no-rm-rf-slash) cannot be overridden.

Custom Rules

Create steering.json in your project root or ~/.pi/agent/:

{
  "disable": ["conventional-commits"],
  "rules": [
    {
      "name": "no-git-push",
      "tool": "bash",
      "field": "command",
      "pattern": "\\bgit\\s+push\\b",
      "reason": "Use `cr` instead of `git push`."
    },
    {
      "name": "aws-requires-profile",
      "tool": "bash",
      "field": "command",
      "pattern": "\\baws\\s+[a-z]",
      "unless": "(--profile|AWS_PROFILE=|\\baws\\s+(sts\\s+get-caller-identity|configure)\\b)",
      "reason": "Always use --profile or AWS_PROFILE with aws CLI commands."
    },
    {
      "name": "no-write-env-files",
      "tool": "write",
      "field": "path",
      "pattern": "\\.env",
      "reason": "Don't overwrite .env files — they may contain secrets.",
      "noOverride": true
    }
  ]
}

Rule Format

Field	Type	Description
name	string	Unique rule identifier
tool	"bash" | "write" | "edit"	Which tool to intercept
field	"command" | "path" | "content"	Which input field to test
pattern	string	Regex — if it matches, the rule fires (violation)
requires	string?	Additional regex that must also match (AND condition)
unless	string?	Regex exemption — if this matches, rule doesn't fire
reason	string	Message shown to the agent when blocked
noOverride	boolean?	If true, no override escape hatch

Config Locations

Checked in order (first found wins):

1. ./steering.json (project root)
2. ~/.pi/agent/steering.json (global)

How It Works

1. Extension registers a tool_call hook
2. On every bash/write/edit call, rules are evaluated against the tool input
3. If a rule matches: block the call and return the reason to the agent
4. Agent sees the block message and adjusts its approach
5. If the agent has a legitimate reason, it can retry with # steering-override: rule-name — reason
6. Overrides are logged via appendEntry for audit

No tokens spent on rule enforcement. No prompt drift. No "oops, the model forgot the rule this time."

License

MIT