~/.pi/agent/extensions/
└── my-extension.ts

~/.pi/agent/extensions/
└── my-extension/
    ├── index.ts
    ├── tools.ts
    └── utils.ts

~/.pi/agent/extensions/
└── my-extension/
    ├── package.json
    ├── node_modules/
    └── src/
        └── index.ts

// ~/.pi/agent/extensions/hello-tool.ts

import { Type } from "@sinclair/typebox";
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "hello",
    label: "Hello",
    description: "Greet someone by name",
    parameters: Type.Object({
      name: Type.String({ description: "Name to greet" }),
    }),
    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}!` }],
        details: { greeted: params.name },
      };
    },
  });
}

import { Type } from "@sinclair/typebox";

export default function (pi: ExtensionAPI) {

pi.registerTool({
  name: "hello",           // Nombre interno
  label: "Hello",          // Etiqueta para la UI
  description: "...",      // Descripción para el LLM
  parameters: Type.Object({...}), // Schema de parámetros
  async execute(...) {...},       // Implementación
});

# Guarda el archivo y recarga
# En Pi:
/reload

# Ahora pide:
> Saluda a María

// ~/.pi/agent/extensions/block-destructive.ts

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash") {
      const command = event.input.command || "";

      // Bloquear comandos peligrosos
      if (command.includes("rm -rf") || command.includes("DROP TABLE")) {
        const ok = await ctx.ui.confirm(
          "⚠️ Comando destructivo",
          `Se intentó ejecutar:\n${command}\n\n¿Permitir?`
        );

        if (!ok) {
          ctx.ui.notify("Comando bloqueado", "warning");
          return { block: true, reason: "Comando destructivo bloqueado" };
        }
      }
    }
  });
}

Pi inicia
  │
  ├─► session_start
  │
  ├─► Usuario envía prompt
  │     ├─► before_agent_start (puede inyectar contexto)
  │     ├─► agent_start
  │     │     │
  │     │     ┌── turn (se repite por cada respuesta + tools) ──┐
  │     │     │  ├─► turn_start                                  │
  │     │     │  ├─► context (puede modificar mensajes)         │
  │     │     │  │                                               │
  │     │     │  │  LLM responde, puede llamar tools:           │
  │     │     │  │    ├─► tool_call ← PUEDES BLOQUEAR          │
  │     │     │  │    ├─► tool_result (puede modificar)         │
  │     │     │  │                                               │
  │     │     │  └─► turn_end                                    │
  │     │     └──────────────────────────────────────────────────┘
  │     │                                                        │
  │     └─► agent_end
  │
  └─► session_shutdown (al salir)

// ~/.pi/agent/extensions/notify-done.ts

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

function notify(title: string, body: string) {
  // OSC 777: funciona en Ghostty, iTerm2, WezTerm
  process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
}

export default function (pi: ExtensionAPI) {
  pi.on("agent_end", async () => {
    notify("Pi", "✅ Listo para input");
  });
}

> Necesito una extensión que me pida confirmación antes de hacer
  commit si hay tests que fallan. El comando es npm test.

Pi: [Lee la estructura de extensiones, crea el archivo]

  He creado ~/.pi/agent/extensions/test-before-commit.ts
  Ejecuta /reload para activarla.

> /reload

Pi: Extensión cargada. ¿Quieres que la pruebe haciendo un commit
  con tests fallando?

> Sí, prueba

Pi: [Ejecuta commit, la extensión intercepta, ejecuta tests,
  tests fallan, pide confirmación]

  ✅ La extensión funciona correctamente. Bloqueó el commit porque
  los tests fallaron.

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("deploy", {
    description: "Deploy al staging environment",
    handler: async (args, ctx) => {
      const env = args || "staging";

      ctx.ui.notify(`🚀 Deploying to ${env}...`, "info");

      const result = await pi.exec("bash", [
        "-c", `./scripts/deploy.sh ${env}`
      ]);

      ctx.ui.notify(
        result.code === 0 ? "✅ Deploy exitoso" : "❌ Deploy falló",
        result.code === 0 ? "success" : "error"
      );
    },
  });
}

// Confirmar sí/no
const ok = await ctx.ui.confirm("Título", "¿Estás seguro?");

// Seleccionar de una lista
const choice = await ctx.ui.select("Elige opción", [
  "Opción A",
  "Opción B",
  "Opción C",
]);

// Input libre
const answer = await ctx.ui.input("¿Nombre del proyecto?");

// Notificación
ctx.ui.notify("Operación completada", "success");

// Status en el footer
ctx.ui.setStatus("my-ext", "Procesando...");

// Versión 1: Solo loguea
export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event) => {
    console.log(`[debug] ${event.toolName}:`, event.input);
  });
}

> Crea una extensión en ~/.pi/agent/extensions/ que registre
  un tool llamado "db-query" que acepte un parámetro "sql" y
  ejecute el query usando nuestro cliente de base de datos
  en src/db/client.ts

// ❌ Demasiado amplio
if (event.toolName === "bash") return { block: true };

// ✅ Específico
if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
  return { block: true, reason: "Comando destructivo" };
}