Architecture

title: Architettura description: “Come funzionano internamente il gestore hook, il caricamento della configurazione e la valutazione delle policy” icon: sitemap

Questo documento spiega come failproofai funziona internamente: come il sistema di hook intercetta le chiamate agli strumenti dell’agente, come viene caricata e unita la configurazione, come vengono valutate le policy e come il dashboard monitora l’attività dell’agente.

Panoramica

failproofai ha due sottosistemi indipendenti:

Gestore hook - Un veloce sottoprocesso CLI che Claude Code richiama per ogni chiamata allo strumento dell’agente. Valuta le policy e restituisce una decisione.
Agent Monitor (Dashboard) - Un’applicazione web Next.js per monitorare le sessioni dell’agente e gestire le policy.

Entrambi i sottosistemi condividono i file di configurazione in ~/.failproofai/ e nella directory .failproofai/ del progetto, ma vengono eseguiti come processi separati e comunicano solo attraverso il filesystem.

Gestore hook

Integrazione con Claude Code

Quando esegui failproofai policies --install, vengono scritte voci come questa in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}

Claude Code quindi richiama failproofai --hook PreToolUse come sottoprocesso prima di ogni chiamata allo strumento, passando un payload JSON su stdin.

Formato del payload

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
  "cwd": "/home/user/myproject",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "sudo apt install nodejs" }
}

Per gli eventi PostToolUse, il payload contiene anche tool_result con l’output dello strumento. Il gestore applica un limite di 1 MB per stdin. I payload che superano questo limite vengono scartati e tutte le policy consentono implicitamente.

Formato della risposta

Nega (PreToolUse):

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
  }
}

Nega (PostToolUse):

{
  "hookSpecificOutput": {
    "additionalContext": "Blocked by failproofai because: API key detected in output"
  }
}

Istruisci (qualsiasi evento eccetto Stop):

{
  "hookSpecificOutput": {
    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
  }
}

Istruisci evento Stop:

Codice di uscita: 2
Motivo scritto su stderr (non stdout)

Consenti:

Codice di uscita: 0
stdout vuoto

Consenti con messaggio: allow(message) consente a una policy di inviare un contesto informativo a Claude anche quando l’operazione è consentita. Il gestore hook scrive il seguente JSON su stdout (non un file di configurazione — questa è la risposta del gestore a Claude Code, proprio come le risposte deny e instruct precedenti):

// Written to stdout by the hook handler process
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}

Codice di uscita: 0 (l’operazione è consentita)
Quando più policy restituiscono allow con un messaggio, i loro messaggi vengono uniti con interruzioni di riga in una singola stringa additionalContext
Se nessuna policy fornisce un messaggio, stdout è vuoto (come prima)

Pipeline di elaborazione

src/hooks/handler.ts implementa la pipeline completa:

stdin JSON
  → parse payload (max 1 MB)
  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
  → readMergedHooksConfig(cwd)    ← merges project + local + global config
  → register enabled builtin policies with resolved params
  → load custom policies from customPoliciesPath (if set)
  → register custom policies into policy registry
  → evaluate all policies (builtins first, then custom)
      → first deny short-circuits
      → instruct decisions accumulate
      → allow messages accumulate
  → write JSON decision to stdout
  → persist event to ~/.failproofai/hook-activity.jsonl
  → exit

L’intero processo viene eseguito in meno di 100ms per payload tipici senza chiamate LLM.

Caricamento della configurazione

src/hooks/hooks-config.ts implementa il caricamento della configurazione in tre ambiti.

[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
[2] {cwd}/.failproofai/policies-config.local.json  ← local
[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)

Logica di unione:

enabledPolicies - unione deduplicate tra tutti e tre i file
policyParams - per chiave di policy, il primo file che la definisce vince completamente
customPoliciesPath - il primo file che la definisce vince
llm - il primo file che la definisce vince

Il dashboard web utilizza readHooksConfig() (solo globale) per la lettura e la scrittura, poiché non viene richiamato con un cwd di progetto.

Valutazione delle policy

src/hooks/policy-evaluator.ts esegue le policy in ordine. Per ogni policy:

Cerca lo schema params della policy (se ne ha uno).
Leggi policyParams[policy.name] dalla configurazione unita.
Unisci i valori forniti dall’utente sui valori predefiniti dello schema per produrre ctx.params.
Chiama policy.fn(ctx) con il contesto risolto.
Se il risultato è deny, fermarti immediatamente e restituisci quella decisione.
Se il risultato è instruct, accumula il messaggio e continua.
Se il risultato è allow, continua alla policy successiva.

Dopo l’esecuzione di tutte le policy:

Se è stata restituita una qualsiasi deny, emetti la risposta deny.
Se sono state raccolte risposte instruct, emetti una singola risposta instruct con tutti i messaggi uniti.
Altrimenti, emetti una risposta allow (stdout vuoto, exit 0).

Policy integrate

src/hooks/builtin-policies.ts definisce tutte le 39 policy integrate come oggetti BuiltinPolicyDefinition:

interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}

Le policy che accettano params dichiarano uno PolicyParamsSchema con tipi e valori predefiniti per ogni parametro. Il valutatore di policy inietta i valori risolti in ctx.params prima di chiamare fn. Le funzioni di policy leggono ctx.params senza protezioni null perché i valori predefiniti vengono sempre applicati prima. La corrispondenza dei pattern all’interno delle policy utilizza token di comando analizzati (argv), non la corrispondenza di stringhe grezze. Questo previene il bypass tramite iniezione di operatori shell (ad es. un pattern per sudo systemctl status * non può essere bypassato aggiungendo ; rm -rf / al comando).

Policy personalizzate

src/hooks/custom-hooks-registry.ts implementa un registro supportato da globalThis:

const REGISTRY_KEY = "__failproofai_custom_hooks__";

export const customPolicies = {
  add(hook: CustomHook): void { ... }
};

export function getCustomHooks(): CustomHook[] { ... }
export function clearCustomHooks(): void { ... }  // used in tests

src/hooks/custom-hooks-loader.ts carica il file di policy dell’utente:

Leggi customPoliciesPath dalla configurazione; salta se assente.
Risolvi al percorso assoluto; controlla che il file esista.
Riscrivi tutti gli import from "failproofai" al percorso dist effettivo in modo che customPolicies si risolva nello stesso registro globalThis.
Riscrivi ricorsivamente gli import locali transitivi per assicurare la compatibilità ESM.
Scrivi file .mjs temporanei e esegui l’import del file di entry.
Chiama getCustomHooks() per recuperare gli hook registrati.
Pulisci tutti i file temp in un blocco finally.

In caso di errore (file non trovato, errore di sintassi, fallimento dell’import), l’errore viene registrato in ~/.failproofai/hook.log e il caricatore restituisce un array vuoto. Le policy integrate non sono interessate. Le policy personalizzate vengono valutate dopo tutte le policy integrate. Una policy personalizzata deny interrompe ancora ulteriormente le policy personalizzate (ma a quel punto tutte le policy integrate sono già state eseguite).

Registrazione dell’attività

Dopo ogni evento hook, il gestore aggiunge una riga JSONL a ~/.failproofai/hook-activity.jsonl:

{
  "timestamp": "2026-04-06T12:34:56.789Z",
  "sessionId": "abc123",
  "eventType": "PreToolUse",
  "toolName": "Bash",
  "policyName": "block-sudo",
  "decision": "deny",
  "reason": "sudo command blocked by failproofai",
  "durationMs": 12
}

Una riga per ogni policy che ha preso una decisione non allow. Le decisioni allow non vengono registrate (per mantenere il file piccolo).

Architettura del dashboard

Il dashboard è un’applicazione Next.js 16 che utilizza App Router con React Server Components e Server Actions.

app/
  layout.tsx                  ← Root layout (theme, telemetry, nav)
  projects/page.tsx           ← Server component: list all Claude projects
  project/[name]/page.tsx     ← Server component: list sessions in a project
  project/[name]/session/
    [sessionId]/page.tsx      ← Server component: render session viewer
  policies/page.tsx           ← Client component: policy management + activity log
  actions/
    get-hooks-config.ts       ← Read config + policy list
    update-hooks-config.ts    ← Toggle policy on/off
    update-policy-params.ts   ← Update policy parameters
    get-hook-activity.ts      ← Paginate/search activity log
    install-hooks-web.ts      ← Install/remove hooks from the browser
  api/
    download/[project]/[session]/route.ts   ← Per-CLI session export (JSONL or JSON)

Flusso di dati:

I componenti della pagina chiamano lib/projects.ts e lib/log-entries.ts per leggere i dati di progetto/sessione direttamente dal filesystem (nessun livello API per le letture).
La pagina Policies utilizza Server Actions per tutte le mutazioni (attiva/disattiva, aggiornamento params, installa/rimuovi).
Il visualizzatore di sessione analizza il formato di trascrizione JSONL di Claude e renderizza una timeline di messaggi e chiamate allo strumento.

Decisioni di progettazione chiave:

Nessun database - tutto lo stato persistente è in file ordinari (~/.failproofai/, ~/.claude/projects/).
Server Actions per mutazioni - nessuna API REST necessaria per operazioni CRUD.
React Server Components per pagine di lettura - caricamento iniziale più veloce, nessun bundle client per il recupero dati.
Componenti client solo dove è necessaria l’interattività (attiva/disattiva policy, ricerca attività, visualizzatore log).

Layout dei file

failproofai/
├── bin/
│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
├── src/hooks/
│   ├── handler.ts                # Hook event pipeline
│   ├── builtin-policies.ts       # 39 policy definitions
│   ├── policy-evaluator.ts       # Policy execution engine
│   ├── policy-registry.ts        # Policy registration and lookup
│   ├── policy-types.ts           # TypeScript interfaces
│   ├── hooks-config.ts           # Multi-scope config loading
│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
│   ├── manager.ts                # install / remove / list operations
│   ├── install-prompt.ts         # Interactive policy selection prompt
│   ├── hook-logger.ts            # Logging to hook.log
│   ├── hook-activity-store.ts    # Persist activity to hook-activity.jsonl
│   └── llm-client.ts             # LLM API client (for AI-powered policies)
├── app/                          # Next.js dashboard (pages + server actions)
├── lib/                          # Shared utilities
│   ├── projects.ts               # Enumerate Claude projects from filesystem
│   ├── log-entries.ts            # Parse Claude transcript JSONL format
│   ├── paths.ts                  # Resolve system paths
│   └── ...
├── components/                   # Shared React UI components
├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
├── examples/                     # Example custom hook files
└── __tests__/                    # Unit and E2E tests

Per iniziare

Concetti chiave

CLI

Strumenti

Avanzato

Esempi

title: Architettura description: “Come funzionano internamente il gestore hook, il caricamento della configurazione e la valutazione delle policy” icon: sitemap

Panoramica

Gestore hook

Integrazione con Claude Code

Formato del payload

Formato della risposta

Pipeline di elaborazione

Caricamento della configurazione

Valutazione delle policy

Policy integrate

Policy personalizzate

Registrazione dell’attività

Architettura del dashboard

Layout dei file

​title: Architettura description: “Come funzionano internamente il gestore hook, il caricamento della configurazione e la valutazione delle policy” icon: sitemap

​Panoramica

​Gestore hook

​Integrazione con Claude Code

​Formato del payload

​Formato della risposta

​Pipeline di elaborazione

​Caricamento della configurazione

​Valutazione delle policy

​Policy integrate

​Policy personalizzate

​Registrazione dell’attività

​Architettura del dashboard

​Layout dei file

title: Architettura description: “Come funzionano internamente il gestore hook, il caricamento della configurazione e la valutazione delle policy” icon: sitemap

Panoramica

Gestore hook

Integrazione con Claude Code

Formato del payload

Formato della risposta

Pipeline di elaborazione

Caricamento della configurazione

Valutazione delle policy

Policy integrate

Policy personalizzate

Registrazione dell’attività

Architettura del dashboard

Layout dei file