{"id":49306175,"url":"https://github.com/samfoy/pi-steering-hooks","last_synced_at":"2026-06-20T10:02:05.011Z","repository":{"id":351591886,"uuid":"1211753666","full_name":"samfoy/pi-steering-hooks","owner":"samfoy","description":"Deterministic tool-call guardrails for pi — enforce rules with before-tool hooks instead of prompts","archived":false,"fork":false,"pushed_at":"2026-05-14T15:02:01.000Z","size":64,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-29T21:05:40.390Z","etag":null,"topics":["agent-guardrails","ai-coding-agent","developer-tools","guardrails","pi-coding-agent","safety","steering"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samfoy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T18:00:48.000Z","updated_at":"2026-05-19T02:39:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/samfoy/pi-steering-hooks","commit_stats":null,"previous_names":["samfoy/pi-steering-hooks"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/samfoy/pi-steering-hooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samfoy%2Fpi-steering-hooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samfoy%2Fpi-steering-hooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samfoy%2Fpi-steering-hooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samfoy%2Fpi-steering-hooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samfoy","download_url":"https://codeload.github.com/samfoy/pi-steering-hooks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samfoy%2Fpi-steering-hooks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34565244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-guardrails","ai-coding-agent","developer-tools","guardrails","pi-coding-agent","safety","steering"],"created_at":"2026-04-26T10:00:19.673Z","updated_at":"2026-06-20T10:02:05.006Z","avatar_url":"https://github.com/samfoy.png","language":"TypeScript","funding_links":[],"categories":["Agent Infrastructure"],"sub_categories":["Configuration \u0026 Context Management"],"readme":"# pi-steering-hooks\n\nDeterministic tool-call guardrails for [pi](https://github.com/badlogic/pi-mono). Enforce rules with before-tool hooks instead of prompts — zero token cost, 100% reliability.\n\nPrompt-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.\n\nInspired by [Strands Agents: Steering Accuracy Beats Prompts](https://strandsagents.com/blog/steering-accuracy-beats-prompts-workflows/).\n\n## Install\n\n```bash\npi install @samfp/pi-steering-hooks\n```\n\n## Default Rules\n\n| Rule | Tool | What it blocks |\n|------|------|---------------|\n| `no-force-push` | bash | `git push --force` (destructive history rewrite) |\n| `no-hard-reset` | bash | `git reset --hard` (discards uncommitted work) |\n| `no-rm-rf-slash` | bash | `rm -rf /` (catastrophic, no override allowed) |\n| `conventional-commits` | bash | Non-conventional `git commit -m` messages |\n| `no-long-running-commands` | bash | Dev servers and watchers that block the agent |\n\n## Override Mechanism\n\nWhen a rule fires, the agent can retry with an override comment:\n\n```bash\ngit push --force origin main  # steering-override: no-force-push — deploying hotfix to unblock prod\n```\n\nThe override is allowed through but logged to the session for audit. Rules with `noOverride: true` (like `no-rm-rf-slash`) cannot be overridden.\n\n## Custom Rules\n\nCreate `steering.json` in your project root or `~/.pi/agent/`:\n\n```json\n{\n  \"disable\": [\"conventional-commits\"],\n  \"rules\": [\n    {\n      \"name\": \"no-git-push\",\n      \"tool\": \"bash\",\n      \"field\": \"command\",\n      \"pattern\": \"\\\\bgit\\\\s+push\\\\b\",\n      \"reason\": \"Use `cr` instead of `git push`.\"\n    },\n    {\n      \"name\": \"aws-requires-profile\",\n      \"tool\": \"bash\",\n      \"field\": \"command\",\n      \"pattern\": \"\\\\baws\\\\s+[a-z]\",\n      \"unless\": \"(--profile|AWS_PROFILE=|\\\\baws\\\\s+(sts\\\\s+get-caller-identity|configure)\\\\b)\",\n      \"reason\": \"Always use --profile or AWS_PROFILE with aws CLI commands.\"\n    },\n    {\n      \"name\": \"no-write-env-files\",\n      \"tool\": \"write\",\n      \"field\": \"path\",\n      \"pattern\": \"\\\\.env\",\n      \"reason\": \"Don't overwrite .env files — they may contain secrets.\",\n      \"noOverride\": true\n    }\n  ]\n}\n```\n\n### Rule Format\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Unique rule identifier |\n| `tool` | `\"bash\"` \\| `\"write\"` \\| `\"edit\"` | Which tool to intercept |\n| `field` | `\"command\"` \\| `\"path\"` \\| `\"content\"` | Which input field to test |\n| `pattern` | string | Regex — if it matches, the rule fires (violation) |\n| `requires` | string? | Additional regex that must also match (AND condition) |\n| `unless` | string? | Regex exemption — if this matches, rule doesn't fire |\n| `reason` | string | Message shown to the agent when blocked |\n| `noOverride` | boolean? | If true, no override escape hatch |\n\n### Config Locations\n\nChecked in order (first found wins):\n\n1. `./steering.json` (project root)\n2. `~/.pi/agent/steering.json` (global)\n\n## How It Works\n\n1. Extension registers a `tool_call` hook\n2. On every bash/write/edit call, rules are evaluated against the tool input\n3. If a rule matches: block the call and return the reason to the agent\n4. Agent sees the block message and adjusts its approach\n5. If the agent has a legitimate reason, it can retry with `# steering-override: rule-name — reason`\n6. Overrides are logged via `appendEntry` for audit\n\nNo tokens spent on rule enforcement. No prompt drift. No \"oops, the model forgot the rule this time.\"\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamfoy%2Fpi-steering-hooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamfoy%2Fpi-steering-hooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamfoy%2Fpi-steering-hooks/lists"}