failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/i18n/README.zh.md

@@ -0,0 +1,307 @@
+> **⚠️** This is an auto-generated translation. For the latest version, see the [English README](../../README.md). Community corrections welcome!
+
+[🇺🇸 English](../../README.md) | **🇨🇳 简体中文** | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) | [🇪🇸 Español](README.es.md) | [🇧🇷 Português](README.pt-br.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇷🇺 Русский](README.ru.md) | [🇮🇳 हिन्दी](README.hi.md) | [🇹🇷 Türkçe](README.tr.md) | [🇻🇳 Tiếng Việt](README.vi.md) | [🇮🇹 Italiano](README.it.md) | [🇸🇦 العربية](README.ar.md) | [🇮🇱 עברית](README.he.md)
+
+---
+
+```
+    ______      _ __                       ____   ___    ____
+   / ____/___ _(_) /___  _________  ____  / __/  /   |  /  _/
+  / /_  / __ `/ / / __ \/ ___/ __ \/ __ \/ /_   / /| |  / /
+ / __/ / /_/ / / / /_/ / /  / /_/ / /_/ / __/  / ___ |_/ /
+/_/    \__,_/_/_/ .___/_/   \____/\____/_/    /_/  |_/___/
+               /_/
+```
+
+# Failproof AI
+
+[![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://befailproof.ai)
+[![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
+[![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/exospherehost/failproofai/actions)
+[![Slack](https://img.shields.io/badge/Slack-join%20us-4A154B?style=flat-square&logo=slack)](https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ)
+
+**翻译版本**: [简体中文](docs/i18n/README.zh.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) | [Español](docs/i18n/README.es.md) | [Português](docs/i18n/README.pt-br.md) | [Deutsch](docs/i18n/README.de.md) | [Français](docs/i18n/README.fr.md) | [Русский](docs/i18n/README.ru.md) | [हिन्दी](docs/i18n/README.hi.md) | [Türkçe](docs/i18n/README.tr.md) | [Tiếng Việt](docs/i18n/README.vi.md) | [Italiano](docs/i18n/README.it.md) | [العربية](docs/i18n/README.ar.md) | [עברית](docs/i18n/README.he.md)
+
+管理策略的最简便方式，让你的 AI 智能体保持可靠、专注任务、自主运行——适用于 **Claude Code** 和 **Agents SDK**。
+
+- **30 条内置策略** - 开箱即用，覆盖常见的智能体故障模式。拦截破坏性命令、防止密钥泄露、将智能体限制在项目边界内、检测循环等。
+- **自定义策略** - 用 JavaScript 编写你自己的可靠性规则。使用 `allow`/`deny`/`instruct` API 强制执行规范、防止漂移、控制操作或与外部系统集成。
+- **简易配置** - 无需编写代码即可调整任意策略。按项目或全局设置允许列表、受保护分支、阈值，三级配置自动合并。
+- **智能体监控** - 查看智能体在你离开期间的所有操作。浏览会话、检查每次工具调用，精确回顾策略触发的位置。
+
+一切均在本地运行——数据不会离开你的机器。
+
+---
+
+## 系统要求
+
+- Node.js >= 20.9.0
+- Bun >= 1.3.0（可选——仅在开发或从源码构建时需要）
+
+---
+
+## 安装
+
+```bash
+npm install -g failproofai
+# 或
+bun add -g failproofai
+```
+
+---
+
+## 快速开始
+
+### 1. 全局启用策略
+
+```bash
+failproofai policies --install
+```
+
+将 hook 条目写入 `~/.claude/settings.json`。Claude Code 此后将在每次工具调用前后调用 failproofai。
+
+### 2. 启动控制台
+
+```bash
+failproofai
+```
+
+打开 `http://localhost:8020`——浏览会话、查看日志、管理策略。
+
+### 3. 查看当前启用的策略
+
+```bash
+failproofai policies
+```
+
+---
+
+## 策略安装
+
+### 作用域
+
+| 作用域 | 命令 | 写入位置 |
+|--------|------|---------|
+| 全局（默认） | `failproofai policies --install` | `~/.claude/settings.json` |
+| 项目级 | `failproofai policies --install --scope project` | `.claude/settings.json` |
+| 本地级 | `failproofai policies --install --scope local` | `.claude/settings.local.json` |
+
+### 安装指定策略
+
+```bash
+failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+```
+
+### 移除策略
+
+```bash
+failproofai policies --uninstall
+# 或针对特定作用域：
+failproofai policies --uninstall --scope project
+```
+
+---
+
+## 配置
+
+策略配置存储在 `~/.failproofai/policies-config.json`（全局）或项目目录下的 `.failproofai/policies-config.json`（项目级）。
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "sanitize-api-keys",
+    "block-push-master",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"],
+      "hint": "Try creating a fresh branch instead."
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  }
+}
+```
+
+**三级配置作用域**自动合并（项目级 → 本地级 → 全局级）。完整合并规则参见 [docs/configuration.mdx](docs/configuration.mdx)。
+
+---
+
+## 内置策略
+
+| 策略 | 说明 | 可配置项 |
+|------|------|:---:|
+| `block-sudo` | 阻止智能体运行特权系统命令 | `allowPatterns` |
+| `block-rm-rf` | 防止意外递归删除文件 | `allowPaths` |
+| `block-curl-pipe-sh` | 阻止智能体将不可信脚本通过管道传给 shell | |
+| `block-failproofai-commands` | 阻止自我卸载 | |
+| `sanitize-jwt` | 防止 JWT 令牌泄露到智能体上下文中 | |
+| `sanitize-api-keys` | 防止 API 密钥泄露到智能体上下文中 | `additionalPatterns` |
+| `sanitize-connection-strings` | 防止数据库凭据泄露到智能体上下文中 | |
+| `sanitize-private-key-content` | 从输出中删除 PEM 私钥块 | |
+| `sanitize-bearer-tokens` | 从输出中删除 Authorization Bearer 令牌 | |
+| `block-env-files` | 阻止智能体读取 .env 文件 | |
+| `protect-env-vars` | 阻止智能体打印环境变量 | |
+| `block-read-outside-cwd` | 将智能体限制在项目边界内 | `allowPaths` |
+| `block-secrets-write` | 阻止向私钥和证书文件写入 | `additionalPatterns` |
+| `block-push-master` | 防止意外推送到 main/master | `protectedBranches` |
+| `block-work-on-main` | 禁止智能体操作受保护分支 | `protectedBranches` |
+| `block-force-push` | 阻止 `git push --force` | |
+| `warn-git-amend` | 在修改提交前提醒智能体 | |
+| `warn-git-stash-drop` | 在丢弃储藏区前提醒智能体 | |
+| `warn-all-files-staged` | 捕获意外的 `git add -A` | |
+| `warn-destructive-sql` | 在执行前捕获 DROP/DELETE SQL | |
+| `warn-schema-alteration` | 在执行前捕获 ALTER TABLE | |
+| `warn-large-file-write` | 捕获意外的大文件写入 | `thresholdKb` |
+| `warn-package-publish` | 捕获意外的 `npm publish` | |
+| `warn-background-process` | 捕获意外启动的后台进程 | |
+| `warn-global-package-install` | 捕获意外的全局包安装 | |
+| …以及更多 | | |
+
+完整策略详情和参数参考：[docs/built-in-policies.mdx](docs/built-in-policies.mdx)
+
+---
+
+## 自定义策略
+
+编写你自己的策略，使智能体保持可靠并专注任务：
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) return deny("Writes to production paths are blocked");
+    return allow();
+  },
+});
+```
+
+通过以下命令安装：
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+### 决策辅助函数
+
+| 函数 | 效果 |
+|------|------|
+| `allow()` | 允许该操作 |
+| `allow(message)` | 允许并向 Claude 发送信息性上下文 *（beta）* |
+| `deny(message)` | 阻止该操作；消息将显示给 Claude |
+| `instruct(message)` | 向 Claude 的提示词添加上下文；不会阻止操作 |
+
+### 上下文对象（`ctx`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` |
+| `toolName` | `string` | 被调用的工具（`"Bash"`、`"Write"`、`"Read"` 等） |
+| `toolInput` | `object` | 工具的输入参数 |
+| `payload` | `object` | 完整的原始事件载荷 |
+| `session.cwd` | `string` | Claude Code 会话的工作目录 |
+| `session.sessionId` | `string` | 会话标识符 |
+| `session.transcriptPath` | `string` | 会话记录文件的路径 |
+
+自定义 hook 支持传递性本地导入、async/await，以及访问 `process.env`。错误采用放行处理（记录到 `~/.failproofai/hook.log`，内置策略继续执行）。完整指南参见 [docs/custom-hooks.mdx](docs/custom-hooks.mdx)。
+
+### 基于约定的策略（v0.0.2-beta.7+）
+
+将 `*policies.{js,mjs,ts}` 文件放入 `.failproofai/policies/` 目录，它们将自动加载——无需 `--custom` 标志或配置变更。就像 git hooks 一样：放入文件即可生效。
+
+```text
+# 项目级——提交到 git，与团队共享
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# 用户级——个人专属，适用于所有项目
+~/.failproofai/policies/my-policies.mjs
+```
+
+两个级别均会加载（取并集）。文件在各目录内按字母顺序加载。使用 `01-`、`02-` 等前缀来控制加载顺序。即用型示例参见 [examples/convention-policies/](examples/convention-policies/)。
+
+---
+
+## 遥测
+
+Failproof AI 通过 PostHog 收集匿名使用遥测数据，用于了解功能使用情况。会话内容、文件名、工具输入或任何个人信息均不会被发送。
+
+禁用遥测：
+
+```bash
+FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai
+```
+
+---
+
+## 文档
+
+| 指南 | 说明 |
+|------|------|
+| [快速入门](docs/getting-started.mdx) | 安装与初步使用 |
+| [内置策略](docs/built-in-policies.mdx) | 全部 30 条内置策略及其参数 |
+| [自定义策略](docs/custom-policies.mdx) | 编写你自己的策略 |
+| [配置](docs/configuration.mdx) | 配置文件格式与作用域合并规则 |
+| [控制台](docs/dashboard.mdx) | 监控会话并查看策略活动 |
+| [架构](docs/architecture.mdx) | hook 系统的工作原理 |
+| [测试](docs/testing.mdx) | 运行测试与编写新测试 |
+
+### 本地运行文档
+
+```bash
+docker build -f Dockerfile.docs -t failproofai-docs .
+docker run --rm -p 3000:3000 failproofai-docs
+```
+
+在 `http://localhost:3000` 打开 Mintlify 文档站点。挂载 docs 目录后，容器会监听文件变更：
+
+```bash
+docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs
+```
+
+---
+
+## 致 failproofai 贡献者的说明
+
+本仓库的 `.claude/settings.json` 使用 `bun ./bin/failproofai.mjs --hook <EventType>` 而非标准的 `npx -y failproofai` 命令。这是因为在 failproofai 项目内部运行 `npx -y failproofai` 会产生自引用冲突。
+
+对于所有其他仓库，推荐的方式是使用 `npx -y failproofai`，通过以下命令安装：
+
+```bash
+failproofai policies --install --scope project
+```
+
+## 贡献指南
+
+参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+---
+
+## 许可证
+
+参见 [LICENSE](LICENSE)。
+
+---
+
+由 **ExosphereHost: 智能体可靠性研究实验室** 构建与维护。我们通过自研智能体、软件和专业知识，帮助企业和初创公司提升 AI 智能体的可靠性。了解更多，请访问 [exosphere.host](https://exosphere.host)。

package/.next/standalone/docs/introduction.mdx

@@ -0,0 +1,57 @@
+---
+title:  Failproof AI
+description: "Manage hooks and policies that keep your AI agents reliable and running autonomously"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hooks and policies that keep your AI agents reliable and running autonomously - for **Claude Code** and the **Agents SDK**.
+
+AI agents fail in predictable ways. They run destructive commands, leak secrets, drift off-task, get stuck in loops, or push directly to main. Left unattended, small failures cascade.
+
+Failproof AI solves this with **policies** - rules that hook into every agent tool call and can **detect failures**, **mitigate them** (block, instruct, sanitize), and **alert you** when something needs attention. A local dashboard lets you review everything afterward.
+
+Everything runs locally. No data leaves your machine.
+
+## Get started
+
+<CardGroup cols={2}>
+
+<Card title="26 built-in policies" icon="shield" href="/built-in-policies">
+  Block destructive commands, prevent secret leakage, keep agents inside project boundaries, and more - out of the box.
+</Card>
+
+<Card title="Custom policies" icon="code" href="/custom-policies">
+  Write your own rules in JavaScript with a simple allow / deny / instruct API.
+</Card>
+
+<Card title="Agent monitor" icon="chart-line" href="/dashboard">
+  See what your agents did while you were away. Browse sessions, inspect tool calls, review where policies fired.
+</Card>
+
+<Card title="Easy configuration" icon="gear" href="/configuration">
+  Tune any policy without code. Set allowlists, protected branches, or thresholds per-project or globally.
+</Card>
+
+</CardGroup>
+
+## Quick start
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies
+failproofai                      # launch the dashboard
+```
+
+See the [Getting started](/getting-started) guide for the full walkthrough.

package/.next/standalone/docs/it/architecture.mdx

@@ -0,0 +1,333 @@
+---
+---
+title: Architettura
+description: "Come il gestore di hook, il caricamento della configurazione e la valutazione delle politiche funzionano internamente"
+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 politiche e come il dashboard monitora l'attività dell'agente.
+
+---
+
+## Panoramica
+
+failproofai ha due sottosistemi indipendenti:
+
+1. **Gestore di hook** - Un veloce subprocess CLI che Claude Code richiama ad ogni chiamata dello strumento dell'agente. Valuta le politiche e restituisce una decisione.
+2. **Agent Monitor (Dashboard)** - Un'applicazione web Next.js per il monitoraggio delle sessioni dell'agente e la gestione delle politiche.
+
+Entrambi i sottosistemi condividono file di configurazione in `~/.failproofai/` e nella directory `.failproofai/` del progetto, ma vengono eseguiti come processi separati e comunicano solo tramite il filesystem.
+
+---
+
+## Gestore di hook
+
+### Integrazione con Claude Code
+
+Quando esegui `failproofai policies --install`, scrive voci come questa in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code quindi richiama `failproofai --hook PreToolUse` come subprocess prima di ogni chiamata allo strumento, passando un payload JSON su stdin.
+
+### Formato del payload
+
+```json
+{
+  "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 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 politiche consentono implicitamente.
+
+### Formato della risposta
+
+**Deny (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Deny (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruct (qualsiasi evento tranne Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Evento Stop instruct:**
+- Exit code: `2`
+- Motivo scritto su stderr (non stdout)
+
+**Allow:**
+- Exit code: `0`
+- Stdout vuoto
+
+**Allow con messaggio (beta):**
+
+A partire da v0.0.2-beta.3, `allow(message)` consente a una politica di inviare un contesto informativo a Claude anche quando l'operazione è consentita. Il gestore di hook scrive il seguente JSON su **stdout** (non in un file di configurazione — questa è la risposta del gestore a Claude Code, proprio come le risposte deny e instruct sopra):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Exit code: `0` (l'operazione è consentita)
+- Quando più politiche restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con newline in una singola stringa `additionalContext`
+- Se nessuna politica fornisce un messaggio, stdout è vuoto (come prima)
+
+### Pipeline di elaborazione
+
+`src/hooks/handler.ts` implementa la pipeline completa:
+
+```text
+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 i payload tipici senza chiamate LLM.
+
+---
+
+## Caricamento della configurazione
+
+`src/hooks/hooks-config.ts` implementa il caricamento della configurazione a tre ambiti.
+
+```text
+[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 ogni politica, 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 lettura e scrittura, poiché non viene richiamato con un cwd di progetto.
+
+---
+
+## Valutazione delle politiche
+
+`src/hooks/policy-evaluator.ts` esegue le politiche in ordine.
+
+Per ogni politica:
+
+1. Cerca lo schema `params` della politica (se ne ha uno).
+2. Legge `policyParams[policy.name]` dalla configurazione unita.
+3. Unisce i valori forniti dall'utente sui valori predefiniti dello schema per produrre `ctx.params`.
+4. Chiama `policy.fn(ctx)` con il contesto risolto.
+5. Se il risultato è `deny`, ferma immediatamente e restituisci quella decisione.
+6. Se il risultato è `instruct`, accumula il messaggio e continua.
+7. Se il risultato è `allow`, continua alla politica successiva.
+
+Dopo che tutte le politiche vengono eseguite:
+- Se è stato restituito qualsiasi `deny`, emetti la risposta di deny.
+- Se sono stati raccolti risultati `instruct`, emetti una singola risposta instruct con tutti i messaggi uniti.
+- Altrimenti, emetti una risposta allow (stdout vuoto, exit 0).
+
+---
+
+## Politiche integrate
+
+`src/hooks/builtin-policies.ts` definisce tutte le 26 politiche integrate come oggetti `BuiltinPolicyDefinition`:
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+Le politiche che accettano `params` dichiarano un `PolicyParamsSchema` con tipi e valori predefiniti per ogni parametro. L'evaluator di politiche inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni di politica leggono `ctx.params` senza null-guarding perché i valori predefiniti vengono sempre applicati per primi.
+
+Il pattern matching all'interno delle politiche utilizza token di comando parsati (argv), non corrispondenza di stringhe grezze. Questo previene il bypass tramite iniezione di operatori shell (ad esempio, un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando).
+
+---
+
+## Politiche personalizzate
+
+`src/hooks/custom-hooks-registry.ts` implementa un registro supportato da `globalThis`:
+
+```typescript
+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 politica dell'utente:
+
+1. Leggi `customPoliciesPath` dalla configurazione; salta se assente.
+2. Risolvi al percorso assoluto; verifica che il file esista.
+3. Riscrivi tutti gli import `from "failproofai"` al percorso dist effettivo in modo che `customPolicies` si risolva nello stesso registro `globalThis`.
+4. Riscrivi ricorsivamente gli import locali transitivi per garantire la compatibilità ESM.
+5. Scrivi file `.mjs` temporanei e `import()` il file di entry.
+6. Chiama `getCustomHooks()` per recuperare gli hook registrati.
+7. Pulisci tutti i file temporanei in un blocco `finally`.
+
+In caso di errore (file non trovato, errore di sintassi, errore di import), l'errore viene registrato in `~/.failproofai/hook.log` e il loader restituisce un array vuoto. Le politiche integrate non sono interessate.
+
+Le politiche personalizzate vengono valutate dopo tutte le politiche integrate. Un `deny` di politica personalizzata continua a cortocircuitare ulteriori politiche personalizzate (ma tutte le integrate sono già state eseguite a questo punto).
+
+---
+
+## Logging dell'attività
+
+Dopo ogni evento di hook, il gestore aggiunge una riga JSONL a `~/.failproofai/hook-activity.jsonl`:
+
+```json
+{
+  "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 politica 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 l'App Router con React Server Components e Server Actions.
+
+```text
+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   ← Export session as ZIP/JSONL
+```
+
+**Flusso di dati:**
+
+- I componenti 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 (toggle, aggiornamento params, installa/rimuovi).
+- Il visualizzatore di sessione parsifica il formato di trascritto JSONL di Claude e renderizza una timeline di messaggi e chiamate di strumenti.
+
+**Decisioni di design chiave:**
+
+- Nessun database - tutto lo stato persistente è in file semplici (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions per mutazioni - nessuna API REST necessaria per le 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à (toggle di politiche, ricerca attività, visualizzatore di log).
+
+---
+
+## Layout dei file
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Hook event pipeline
+│   ├── builtin-policies.ts       # 26 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
+```