How Pi is built —
and why its author
tore everything else down first.

// pi-agent/docs/hooks.md — the event carries its own result type
interface HookEvent<TType extends string, TResult = void> {
  type: TType;
  readonly [HookResult]?: TResult;   // phantom — no result map needed
}

// a tool_call handler can transform input, or block execution
interface ToolCallEvent extends HookEvent<"tool_call", { block?: boolean; reason?: string }> {
  type: "tool_call"; toolName: string; input: Record<string, unknown>;
}

pi.on("tool_call", async (event, ctx) => {
  if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
    if (!await ctx.ui.confirm("Dangerous!", "Allow rm -rf?"))
      return { block: true, reason: "Blocked by user" };  // veto
  }
});

// pi-agent — the loop is a mechanism; ALL policy is injected
interface AgentLoopConfig {
  model: Model<any>;
  convertToLlm:        (m: AgentMessage[]) => Message[];   // history → provider
  transformContext?:   (m, signal) => Promise<AgentMessage[]>; // compaction / RAG
  beforeToolCall?:     (ctx, signal) => Promise<Result>;        // permission gate
  afterToolCall?:      (ctx, signal) => Promise<Result>;        // post-process
  getSteeringMessages?:() => Promise<AgentMessage[]>;          // mid-run input
  shouldStopAfterTurn?:(ctx) => boolean;                       // stop policy
  prepareNextTurn?:    (ctx) => TurnUpdate;                    // swap model/thinking
}
// the loop itself: "just loops until the agent says it's done."

// core/tools/read.ts — the IO backend is an injected interface
export interface ReadOperations {
  readFile: (absolutePath: string) => Promise<Buffer>;
  access:   (absolutePath: string) => Promise<void>;
}

export function createReadToolDefinition(cwd: string, opts?: ReadToolOptions) {
  const ops = opts?.operations ?? defaultReadOperations;  // ← swap for SSH / sandbox
  return {
    name: "read", label: "read",
    parameters: Type.Object({ path: Type.String() }),  // TypeBox = types + validation
    async execute(id, { path }, signal, onUpdate, ctx) {
      const buf = await ops.readFile(resolve(cwd, path));
      return { content: [{ type: "text", text: buf.toString() }] };
    },
  };
}

// ~/.pi/agent/extensions/greet.ts — a whole extension is one factory
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "greet", label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({ name: Type.String() }),
    async execute(id, { name }) {
      return { content: [{ type: "text", text: `Hello, ${name}!` }], details: {} };
    },
  });
}
// drop the file in, hit /reload, the model can call it. No build, no restart.