pi-steering-hooks — Summary

pi-steering-hooks is a minimal TypeScript extension for the pi coding agent (earendil-works/pi-mono) that registers a tool_call hook intercepting bash, write, and edit tool calls before execution, evaluating configurable regex rules to block violations deterministically — zero tokens spent, 100% reliability. It ships 5 default rules (no-force-push, no-hard-reset, no-rm-rf-slash, conventional-commits, no-long-running-commands) and supports custom rules via steering.json in the project root or ~/.pi/agent/. Each blocked call returns a reason message to the agent for self-correction; an override escape hatch allows the agent to bypass non-hard rules with a # steering-override: rule-name — reason comment, logged for audit. Inspired explicitly by Strands Agents' "Steering Accuracy Beats Prompts" blog post. Compared to seeds: pi-steering-hooks is the most minimal guardrail framework in the batch — single-tool (pi agent), 5 default rules, zero framework beyond the extension API. No seed targets the pi agent specifically.

pi-steering-hooks — Overview

Origin

Repo: samfoy/pi-steering-hooks. Created April 2026, TypeScript, MIT. 5 stars. Author: samfoy.

Target Platform

The pi agent: earendil-works/pi-mono (a coding agent with extension API). pi-steering-hooks is installable via pi install @samfp/pi-steering-hooks.

Philosophy

From README:

"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."

Explicit inspiration cited in README:

"Inspired by Strands Agents: Steering Accuracy Beats Prompts"

The core thesis: encoding behavioral rules in prompts is probabilistic (the model may forget or misapply them). Encoding them as code hooks is deterministic. The name "steering" signals this distinction — hooks steer the agent rather than instruct it.

Design Principles

• Zero token cost for enforcement
• 100% reliability (deterministic regex)
• Override escape hatch — agent can provide a reason and bypass non-critical rules (but the override is logged)
• noOverride: true for catastrophic cases (rm -rf /)
• Minimal config — steering.json with simple field format
• Gradual disclosure — 5 safe defaults that any project can use as-is

pi-steering-hooks — Architecture

Distribution

• pi extension registry: pi install @samfp/pi-steering-hooks
• npm package (underlying): TypeScript, MIT
• Repo: samfoy/pi-steering-hooks

Directory Structure (repo)

pi-steering-hooks/
  src/
    index.ts         Main extension entry point + all rule logic
  package.json
  tsconfig.json
  LICENSE
  README.md

Minimal codebase — essentially one file (src/index.ts).

Required Runtime

• Node.js (TypeScript transpiled)
• pi coding agent installed (earendil-works/pi-mono)

Extension API

Registers a tool_call hook via pi's extension API:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { isToolCallEventType } from "@earendil-works/pi-coding-agent";

Config Files

• ./steering.json (project root) — project-scoped rules
• ~/.pi/agent/steering.json — global rules

Config priority: project root wins over global (first found wins).

Target AI Tools

pi coding agent exclusively (earendil-works/pi-mono). Zero compatibility with Claude Code, Cursor, Codex, or any other agent.

Rule Matching Architecture

Each rule has:

• tool: which tool to intercept (bash, write, edit)
• field: which input field to test (command, path, content)
• pattern: regex that triggers a violation if it matches
• requires: optional AND condition
• unless: optional exemption regex
• reason: message returned to agent on block
• noOverride: optional hard block flag

pi-steering-hooks — Components

Core: One Extension File

src/index.ts — the entire framework in one TypeScript file (~200 lines).

Default Rules (5)

Rule Format

interface Rule {
  name: string;
  tool: "bash" | "write" | "edit";
  field: "command" | "path" | "content";
  pattern: string;        // Regex — match = violation
  requires?: string;      // AND condition (optional)
  unless?: string;        // Exemption regex (optional)
  reason: string;         // Block message to agent
  noOverride?: boolean;   // Hard block if true
}

Config Format (steering.json)

{
  "disable": ["conventional-commits"],
  "rules": [
    {
      "name": "no-git-push",
      "tool": "bash",
      "field": "command",
      "pattern": "\\bgit\\s+push\\b",
      "reason": "Use `cr` instead of `git push`."
    }
  ]
}

Override Mechanism

Agent retry pattern:

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

The override comment is parsed, logged via appendEntry, and the call is allowed through.

Audit Logging

Override uses appendEntry (from pi's extension API) to log the override reason. No persistent DB — relies on pi's session log.

No Dashboard, No CLI Binary, No Skills, No Subagents

pi-steering-hooks ships nothing beyond src/index.ts + steering.json config format.

pi-steering-hooks — Uniqueness & Positioning

Differs from Seeds

pi-steering-hooks targets the pi coding agent (earendil-works/pi-mono), which none of the 11 seeds supports. The closest seed in terms of design philosophy is spec-kit — both use a hook-based approach to enforce behavioral rules on AI tool calls. But spec-kit's 18 hooks enforce a spec-driven development workflow; pi-steering-hooks enforces a handful of git/filesystem safety rules. The override-with-reason mechanism (agent self-authorizes with a stated rationale) is not present in any seed framework — seeds either block absolutely or require human approval. The minimal footprint (~200 lines, no database, no dashboard) is philosophically closer to the "Markdown scaffold, zero primitives" archetype (claude-conductor) but applied to hooks rather than templates.

Positioning

Signal type: regex-based pre-tool guardrail Intervention point: before tool execution (all bash/write/edit calls) Unique features: self-authorizing override with audit, noOverride: true hard blocks, pi-agent-specific, minimal codebase Target user: pi agent users who want reliable behavioral guardrails without prompt engineering

Observable Failure Modes

• Limited to pi agent — zero value for Claude Code, Cursor, Codex teams
• Regex-only enforcement misses semantic violations (you can write a script that does git push --force via a variable)
• No human-in-the-loop approval (unlike DashClaw) — agent self-authorizes overrides
• 5 stars / 2 forks — very early adoption
• Single author — bus factor of 1

Relationship to Batch 31

pi-steering-hooks is the conceptual minimum viable guardrail framework in the batch. Where DashClaw is a full governance platform and Sponsio is a formal-methods library, pi-steering-hooks is a single TypeScript file with 5 regex rules. The design philosophy (hooks > prompts for reliability) is shared across the batch, but the implementation is the simplest possible expression of that idea.