Beispiele

Hooks für Claude Code und das Agents SDK einrichten

Sofort einsetzbare Beispiele für häufige Szenarien. Jedes zeigt, wie man es installiert und was zu erwarten ist.

---

​

Hooks für Claude Code einrichten

Failproof AI integriert sich in Claude Code über dessen Hooks-System. Wenn Sie failproofai policies --install ausführen, registriert es Hook-Befehle in der settings.json von Claude Code, die bei jedem Tool-Aufruf ausgelöst werden.

1. failproofai installieren

   npm install -g failproofai
   
2. Alle integrierten Richtlinien aktivieren

   failproofai policies --install
   
3. Hooks-Registrierung überprüfen

   cat ~/.claude/settings.json | grep failproofai
   

   Sie sollten Hook-Einträge für PreToolUse, PostToolUse, Notification und Stop-Ereignisse sehen.

4. Claude Code starten

   claude
   

   Richtlinien werden nun automatisch bei jedem Tool-Aufruf ausgeführt. Bitten Sie Claude, sudo rm -rf / auszuführen – der Befehl wird blockiert.

---

​

Hooks für das Agents SDK einrichten

Wenn Sie mit dem Agents SDK entwickeln, können Sie dasselbe Hook-System programmatisch nutzen.

1. failproofai im Projekt installieren

   npm install failproofai
   
2. Hooks im Agent konfigurieren

   Übergeben Sie Hook-Befehle beim Erstellen Ihres Agent-Prozesses. Die Hooks werden genauso ausgelöst wie in Claude Code – über stdin/stdout JSON:

   failproofai --hook PreToolUse   # wird vor jedem Tool aufgerufen
   failproofai --hook PostToolUse  # wird nach jedem Tool aufgerufen
   
3. Eine benutzerdefinierte Richtlinie für den Agent schreiben

   import { customPolicies, allow, deny } from "failproofai";
   
   customPolicies.add({
     name: "limit-to-project-dir",
     description: "Keep the agent inside the project directory",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       const path = String(ctx.toolInput?.file_path ?? "");
       if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
         return deny("Agent is restricted to the project directory");
       }
       return allow();
     },
   });
   
4. Die benutzerdefinierte Richtlinie installieren

   failproofai policies --install --custom ./my-agent-policies.js
   

---

​

Destruktive Befehle blockieren

Das häufigste Setup – verhindert, dass Agenten irreversible Schäden anrichten.

failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh

Was das bewirkt:

• block-sudo – blockiert alle sudo-Befehle
• block-rm-rf – blockiert das rekursive Löschen von Dateien
• block-force-push – blockiert git push --force
• block-curl-pipe-sh – blockiert das Weiterleiten von Remote-Skripten an die Shell

---

​

Geheimnis-Lecks verhindern

Verhindert, dass Agenten Anmeldedaten in der Tool-Ausgabe sehen oder weitergeben.

failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens

Diese werden bei PostToolUse ausgelöst – nachdem ein Tool ausgeführt wurde, bereinigen sie die Ausgabe, bevor der Agent sie zu sehen bekommt.

---

​

Slack-Benachrichtigungen erhalten, wenn Agenten Aufmerksamkeit benötigen

Verwenden Sie den Notification-Hook, um Leerlauf-Benachrichtigungen an Slack weiterzuleiten.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Alert Slack when the agent is waiting for input",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Agent is waiting");
    const project = ctx.session?.cwd ?? "unknown";

    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${message}*\nProject: \`${project}\``,
        }),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      // den Agent niemals blockieren, wenn Slack nicht erreichbar ist
    }

    return allow();
  },
});

Installieren:

SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

---

​

Agenten auf einem Branch halten

Verhindert, dass Agenten Branches wechseln oder auf geschützte Branches pushen.

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Prevent the agent from checking out other branches",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
      return deny("Stay on the current branch. Create a new branch with -b if needed.");
    }
    return allow();
  },
});

---

​

Tests vor Commits verlangen

Erinnert Agenten daran, vor einem Commit Tests auszuführen.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Remind the agent to run tests before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+commit/.test(cmd)) {
      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
    }
    return allow();
  },
});

---

​

Ein Produktions-Repository absichern

Committen Sie eine projektweite Konfiguration, damit alle Entwickler in Ihrem Team dieselben Richtlinien erhalten.

Erstellen Sie .failproofai/policies-config.json in Ihrem Repository:

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-force-push",
    "block-push-master",
    "block-env-files",
    "sanitize-api-keys",
    "sanitize-jwt"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "production"]
    }
  }
}

Dann committen:

git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"

Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Regeln automatisch.

---

​

Einen teamweiten Qualitätsstandard mit Konventionsrichtlinien aufbauen

Das wirkungsvollste Setup: Committen Sie .failproofai/policies/ in Ihr Repository mit auf Ihr Projekt zugeschnittenen Richtlinien. Jedes Teammitglied erhält sie automatisch – keine Installationsbefehle, keine Konfigurationsänderungen.

1. Verzeichnis erstellen und Richtlinien hinzufügen

   mkdir -p .failproofai/policies
   

   // .failproofai/policies/team-policies.mjs
   import { customPolicies, allow, deny, instruct } from "failproofai";
   
   // Enforce your team's preferred package manager
   // (or enable the built-in prefer-package-manager policy instead)
   customPolicies.add({
     name: "enforce-bun",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       if (ctx.toolName !== "Bash") return allow();
       const cmd = String(ctx.toolInput?.command ?? "");
       if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
       return allow();
     },
   });
   
   // Remind the agent to run tests before committing
   customPolicies.add({
     name: "test-before-commit",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       if (ctx.toolName !== "Bash") return allow();
       if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
         return instruct("Run tests before committing.");
       }
       return allow();
     },
   });
   
2. In Git committen

   git add .failproofai/policies/
   git commit -m "Add team quality policies"
   
3. Kontinuierlich verbessern

   Wenn Ihr Team auf neue Fehlerquellen stößt, fügen Sie Richtlinien hinzu und pushen Sie. Alle erhalten das Update beim nächsten git pull. Diese Richtlinien werden zu einem lebendigen Qualitätsstandard, der mit Ihrem Team wächst.

---

​

Weitere Beispiele

Das Verzeichnis examples/ im Repository enthält:

Datei	Inhalt
policies-basic.js	Einstiegsrichtlinien – Produktions-Writes blockieren, Force-Push, weitergeleitete Skripte
policies-notification.js	Slack-Benachrichtigungen bei Leerlauf und Sitzungsende
policies-advanced/index.js	Transitive Imports, asynchrone Hooks, PostToolUse-Ausgabebereinigung, Stop-Event-Behandlung