failproofai 0.0.12 → 0.0.13-beta.0

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.12",
+  "version": "0.0.13-beta.0",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"

package/.next/standalone/server.js

@@ -9,7 +9,7 @@ const currentPort = parseInt(process.env.PORT, 10) || 3000
 const hostname = process.env.HOSTNAME || '0.0.0.0'
 
 let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
-const nextConfig = {"env":{"NEXT_PUBLIC_APP_VERSION":"0.0.12"},"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":true,"customCacheHandler":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{"serverFunctions":true,"browserToTerminal":"warn"},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/home/runner/work/failproofai/failproofai","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"appNewScrollHandler":false,"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"cachedNavigations":false,"partialFallbacks":false,"dynamicOnHover":false,"varyParams":false,"prefetchInlining":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":3,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"strictRouteTypes":false,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":true,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"gestureTransition":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":"warn","lockDistDir":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":true,"turbopackPluginRuntimeStrategy":"childProcesses","optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","outputFileTracingExcludes":{"*":["node_modules/@img/**","node_modules/sharp/**"]},"turbopack":{"root":"/home/runner/work/failproofai/failproofai"},"distDirRoot":".next"}
+const nextConfig = {"env":{"NEXT_PUBLIC_APP_VERSION":"0.0.13-beta.0"},"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":true,"customCacheHandler":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{"serverFunctions":true,"browserToTerminal":"warn"},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/home/runner/work/failproofai/failproofai","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"appNewScrollHandler":false,"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"cachedNavigations":false,"partialFallbacks":false,"dynamicOnHover":false,"varyParams":false,"prefetchInlining":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":3,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"strictRouteTypes":false,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":true,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"gestureTransition":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":"warn","lockDistDir":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":true,"turbopackPluginRuntimeStrategy":"childProcesses","optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","outputFileTracingExcludes":{"*":["node_modules/@img/**","node_modules/sharp/**"]},"turbopack":{"root":"/home/runner/work/failproofai/failproofai"},"distDirRoot":".next"}
 
 process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
 

package/dist/cli.mjs

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // package.json
-var version2 = "0.0.12";
+var version2 = "0.0.13-beta.0";
 var init_package = () => {};
 
 // src/posthog-key.ts
@@ -151,7 +151,11 @@ var init_types = __esm(() => {
     "permission_request",
     "post_tool_use",
     "user_prompt_submit",
-    "stop"
+    "stop",
+    "subagent_start",
+    "pre_compact",
+    "post_compact",
+    "subagent_stop"
   ];
   CODEX_EVENT_MAP = {
     session_start: "SessionStart",
@@ -159,7 +163,11 @@ var init_types = __esm(() => {
     permission_request: "PermissionRequest",
     post_tool_use: "PostToolUse",
     user_prompt_submit: "UserPromptSubmit",
-    stop: "Stop"
+    stop: "Stop",
+    subagent_start: "SubagentStart",
+    pre_compact: "PreCompact",
+    post_compact: "PostCompact",
+    subagent_stop: "SubagentStop"
   };
   CODEX_TOOL_MAP = {
     apply_patch: "Edit",
@@ -173,7 +181,12 @@ var init_types = __esm(() => {
     "PreToolUse",
     "PostToolUse",
     "Stop",
-    "SubagentStop"
+    "SubagentStop",
+    "PostToolUseFailure",
+    "ErrorOccurred",
+    "PreCompact",
+    "PermissionRequest",
+    "Notification"
   ];
   COPILOT_TOOL_MAP = {
     bash: "Bash",
@@ -358,7 +371,8 @@ var init_types = __esm(() => {
     "Elicitation",
     "ElicitationResult",
     "UserPromptExpansion",
-    "PostToolBatch"
+    "PostToolBatch",
+    "Setup"
   ];
 });
 
@@ -6740,7 +6754,7 @@ var init_integrations = __esm(() => {
       return {
         type: "command",
         command,
-        timeout: 60000,
+        timeout: 60,
         [FAILPROOFAI_HOOK_MARKER]: true
       };
     },
@@ -7081,7 +7095,7 @@ var init_integrations = __esm(() => {
       return {
         type: "command",
         command,
-        timeout: 60000,
+        timeout: 60,
         [FAILPROOFAI_HOOK_MARKER]: true
       };
     },
@@ -11845,7 +11859,7 @@ import { realpathSync as realpathSync4 } from "fs";
 import { dirname as dirname9, resolve as resolve17 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 // package.json
-var version = "0.0.12";
+var version = "0.0.13-beta.0";
 
 // bin/failproofai.mjs
 if (!process.env.FAILPROOFAI_PACKAGE_ROOT) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.12",
+  "version": "0.0.13-beta.0",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"

package/scripts/sync-agent-cli-harnesses-prompt.md

@@ -0,0 +1,222 @@
+ultracode
+
+You are an automated **ultracode** (multi-agent) run inside a fresh clone of the
+failproofai repository. Your job is to keep failproofai in sync with the upstream
+documentation for **every** agent CLI we integrate with, then open exactly one
+pull request with the fix — or, if a sync PR is already open, comment on it instead.
+
+## Run contract (read first)
+
+- You are running **headless and autonomously**. No human is watching; nobody can
+  answer a question mid-run. For reversible actions that follow from this task,
+  proceed without asking. Do **not** end your turn with a plan or a question —
+  finish the work.
+- The entrypoint has **already cut a fresh branch** named `auto/sync-cli-harnesses-<UTC>`.
+  Do all your work here; do **not** switch branches or work on `main`.
+- failproofai's own Stop hooks are active in this checkout. If you make commits, you
+  will not be allowed to stop until you have **committed**, **pushed**, and **opened a
+  PR** for them. If you make **no** commits (nothing to sync, or you only commented on
+  an already-open sync PR), a clean working tree stops fine — so on those paths, do
+  **not** edit any files.
+- Use ultracode / multi-agent orchestration: in Phase 1, fan out **one subagent per
+  CLI** so the seven harnesses are checked in parallel.
+
+failproofai integrates with **seven** agent CLIs. Each has its own hook surface,
+tracked in `src/hooks/types.ts` and written to disk by `src/hooks/integrations.ts`:
+
+| CLI            | Event array (`src/hooks/types.ts`) | Event map | Settings file written (`src/hooks/integrations.ts`) |
+|----------------|------------------------------------|-----------|------------------------------------------------------|
+| Claude Code    | `HOOK_EVENT_TYPES` (canonical)     | — (canonical)          | `.claude/settings.json` |
+| OpenAI Codex   | `CODEX_HOOK_EVENT_TYPES`           | `CODEX_EVENT_MAP`      | `.codex/hooks.json` |
+| GitHub Copilot | `COPILOT_HOOK_EVENT_TYPES`         | — (already Pascal)     | `.github/hooks/failproofai.json` |
+| Cursor Agent   | `CURSOR_HOOK_EVENT_TYPES`          | `CURSOR_EVENT_MAP`     | `.cursor/hooks.json` |
+| OpenCode       | `OPENCODE_HOOK_EVENT_TYPES`        | `OPENCODE_EVENT_MAP`   | `.opencode/opencode.json` + `.opencode/plugins/failproofai.mjs` |
+| Pi             | `PI_HOOK_EVENT_TYPES`              | `PI_EVENT_MAP`         | `.pi/settings.json` |
+| Gemini CLI     | `GEMINI_HOOK_EVENT_TYPES`          | `GEMINI_EVENT_MAP`     | `.gemini/settings.json` |
+
+## What "drift" means — three scopes
+
+For each verified CLI, compare the upstream docs to this repo across three scopes:
+
+1. **Scope 1 — hook event names.** Events documented upstream but missing from (or
+   removed from) the CLI's `*HOOK_EVENT_TYPES` array in `src/hooks/types.ts`.
+2. **Scope 2 — tool / payload schema.** Changes to the CLI's tool names or payload
+   field shapes, tracked in the `*_TOOL_MAP` / `*_TOOL_INPUT_MAP` tables in
+   `src/hooks/types.ts` and in the per-CLI response-shape branches of
+   `src/hooks/policy-evaluator.ts`.
+3. **Scope 3 — settings-file shape.** Changes to the structure of the config file
+   failproofai writes for the CLI: the hard-coded literals in
+   `src/hooks/integrations.ts` (matcher-wrapper vs flat-array vs packages-array vs
+   plugin registration; field names like `command` vs `bash`/`powershell`;
+   `timeout` vs `timeoutSec` and its **unit** seconds-vs-ms; presence of `version`
+   / `$schema` / `matcher`; the settings-file path) **and** the committed dogfood
+   fixture on disk. The canonical worked example is git history / PR #482, which
+   dropped an invalid top-level `version` field and fixed a `60000`ms→`60`s timeout
+   unit in `.codex/hooks.json` by editing the writer, the fixture, and the tests
+   together.
+
+## Reading rules
+
+- This run relaxed two policies (`require-ci-green-before-stop`,
+  `block-read-outside-cwd`) so you can read and edit the settings fixtures. Even so,
+  when you only need to **inspect** a committed fixture, prefer
+  `git show HEAD:<path>` (e.g. `git show HEAD:.codex/hooks.json`) — it is never
+  blocked and is the reliable way to read `.claude/settings.json`, `.codex/hooks.json`,
+  `.cursor/hooks.json`, `.github/hooks/failproofai.json`, `.gemini/settings.json`,
+  `.pi/settings.json`, and `.opencode/*`.
+- Do **NOT** run `failproofai policies --install` (or any `failproofai` subcommand)
+  to regenerate a fixture — it is blocked. Edit fixtures by hand.
+
+## Phase 1 — Fan out one subagent per CLI
+
+Spawn one subagent per CLI (seven, in parallel). Each subagent, for its CLI:
+
+1. `WebFetch` the docs URL(s) below and extract the authoritative lists: the hook
+   **event names**, the **tool names / payload field names**, and the
+   **settings-file schema** (top-level keys, per-entry shape, command field name,
+   timeout field name **and unit**, and whether `matcher` / `version` / `$schema`
+   are present). **Use upstream casing exactly** — Codex snake_case, Cursor
+   camelCase, OpenCode dot.namespaced, Pi snake_case, Claude/Copilot/Gemini
+   PascalCase. Do **not** normalize.
+2. Compare against this repo: the CLI's `*HOOK_EVENT_TYPES` array + paired
+   `*EVENT_MAP` (scope 1); its `*_TOOL_MAP` / `*_TOOL_INPUT_MAP` and its branch in
+   `src/hooks/policy-evaluator.ts` (scope 2); its literals in
+   `src/hooks/integrations.ts` + its dogfood fixture read via `git show` (scope 3).
+3. Return a structured report: `{ cli, status: up-to-date | drift | unverified,
+   scope1: {added, removed}, scope2: {...}, scope3: {...}, sources: [...] }`.
+
+If a docs URL 404s, redirects to a stub, or has no parseable list, mark that CLI
+`unverified` and skip its diff. **Do not invent events, tools, or fields. Do not
+guess from prior knowledge.** Pi is the most likely `unverified` candidate (its
+surface is documented in the package source, not a clean enumeration).
+
+| CLI       | Docs URL(s) |
+|-----------|-------------|
+| Claude    | https://code.claude.com/docs/en/hooks (reference) · https://code.claude.com/docs/en/hooks-guide (summary) |
+| Codex     | https://developers.openai.com/codex/hooks |
+| Copilot   | https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks · https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-hooks-reference (tool names) |
+| Cursor    | https://cursor.com/docs/hooks |
+| OpenCode  | https://opencode.ai/docs/plugins/ |
+| Pi        | https://www.npmjs.com/package/@mariozechner/pi-coding-agent |
+| Gemini    | https://geminicli.com/docs/hooks/ · https://geminicli.com/docs/reference/tools/ (tool names) |
+
+## Phase 2 — Decide what to do (do this BEFORE editing any files)
+
+Merge the subagent reports into one list of detected drift. Then, **before you edit a
+single file**, decide which path you are on — editing first would leave uncommitted
+changes that block a clean stop on the comment / no-op paths below.
+
+1. **No drift in any verified CLI** → do nothing: make no edits, open no PR, post no
+   comment. Stop. (`unverified` alone is not drift — the docs may just be unreachable
+   today.)
+
+2. **Drift exists — first check for an already-open sync PR:**
+   `gh pr list --base main --state open --search "[auto] sync agent CLI harnesses" --json number,url,headRefName`.
+
+   - **If an open sync PR already exists, do NOT open a second PR and do NOT edit any
+     files.** Read what it already covers (`gh pr diff <number>` plus its body) and
+     compare against your detected drift. If that PR already covers everything you
+     found, stop — nothing to add. If you found drift the PR is **missing**, post ONE
+     comment listing exactly what's missing, then stop —
+     `gh pr comment <number> --body "..."`, e.g.:
+
+     > This open sync PR is missing newly-detected drift:
+     > - **Cursor**: upstream added event `afterEdit` — append to `CURSOR_HOOK_EVENT_TYPES` (+ a `CURSOR_EVENT_MAP` entry).
+     > - **Gemini**: the `run_shell_command` tool was renamed to `shell` — the `GEMINI_TOOL_MAP` key is stale.
+     >
+     > (hook-sync bot — please fold these into this PR rather than opening a second sync PR.)
+
+     Never push commits to another PR's branch; only comment, and leave the working
+     tree clean so this run stops cleanly.
+
+   - **If no open sync PR exists → go to Phase 3** to apply the fixes and open one.
+
+## Phase 3 — Apply the fixes and open one PR
+
+Only reached when there is real drift **and** no open sync PR. Edit only what drift
+requires.
+
+### Scope 1 (event names)
+- **Append** new events just before `] as const`, preserving upstream casing.
+- **Delete** removed events; if the CLI has an `*EVENT_MAP`, also delete the same
+  key from that map (the `Record` is exhaustive — a stale key fails `tsc`).
+- For **map-bearing CLIs** (Codex, Cursor, OpenCode, Pi, Gemini), do **NOT** invent
+  the canonical mapping for a newly-added event — leave it out of the `*EVENT_MAP`
+  so `tsc` fails intentionally, and add a reviewer-checklist item to the PR body
+  (see below). For **Claude and Copilot** (no map), the build stays green.
+- **Fix hardcoded test counts** when the relevant array changed:
+  - If `HOOK_EVENT_TYPES` (Claude) changed: in `__tests__/hooks/manager.test.ts`,
+    update the `installs hooks for all <N> event types` description AND both
+    `expect(Object.keys(written.hooks)).toHaveLength(<N>)` assertions.
+  - If `GEMINI_HOOK_EVENT_TYPES` changed: in `__tests__/hooks/integrations.test.ts`,
+    update the `expect(gemini.eventTypes).toHaveLength(<N>)` assertion AND the
+    matching description string.
+  - Locate these by searching for the current count number.
+
+### Scope 2 / Scope 3 (tool schema / settings-file shape)
+- Apply a fix **only when it is unambiguous and needs no human judgement** — e.g.
+  an invalid field to remove, a wrong timeout unit, or a renamed tool id (the PR
+  #482 class). When you do, move the whole quartet together, exactly like #482:
+  the writer in `src/hooks/integrations.ts` (+ a shared helper if it dedupes
+  logic), the committed dogfood fixture, the unit test in
+  `__tests__/hooks/integrations.test.ts`, and the e2e test in
+  `__tests__/e2e/hooks/<cli>-integration.e2e.test.ts` — plus a `types.ts` comment
+  if it documents the old shape.
+- If the correct fix needs judgement (which canonical event/tool a new item maps
+  to; an ambiguous schema change), **leave the code untouched** and record it as a
+  reviewer-checklist item instead. Bias toward reporting over auto-editing core
+  integration code.
+- Do **NOT** add `*EVENT_MAP`, `*_TOOL_MAP`, or `*_TOOL_INPUT_MAP` entries for
+  newly-added items — the canonical mapping is a human decision.
+
+### CHANGELOG (required)
+Add a single-line entry to `CHANGELOG.md` under `## <version> — <YYYY-MM-DD>` where
+`<version>` is the `version` field in `package.json` (read it) and `<YYYY-MM-DD>` is
+today's UTC date. If that heading does not exist yet, create it above the previous
+version's section. There is no `## Unreleased` section. Use the `### Features` (or
+`### Fixes` for a shape correction) subsection.
+
+### Commit, push, open the PR
+1. Stage only the files you intentionally edited (never `git add -A`):
+   `src/hooks/types.ts`, `src/hooks/integrations.ts`, `src/hooks/policy-evaluator.ts`,
+   the touched `__tests__/...` files, the touched dogfood fixtures, and
+   `CHANGELOG.md` — whichever actually changed.
+2. Commit (e.g. `feat: sync agent CLI harnesses with upstream docs`), then
+   `git push -u origin "$(git branch --show-current)"`.
+3. `gh pr create --base main --title "[auto] sync agent CLI harnesses with upstream docs" --body "<body>"`.
+
+The PR **body** must contain, in order:
+
+1. **Summary table** — one row per CLI: `| CLI | scope-1 | scope-2 | scope-3 | status |`
+   where status is `up to date`, `drift`, or `unverified`.
+2. **Per-CLI sections** — for each CLI with drift, list the added/removed events,
+   tool/schema changes, and settings-shape changes.
+3. **Reviewer checklist** — one unchecked box per item that needs a human decision:
+   - For each newly-added event on a map-bearing CLI:
+     `- [ ] Add \`<event>: "???"\` to \`<MAP_NAME>\` in \`src/hooks/types.ts\` (canonical Claude \`HookEventType\` chosen by reviewer)`
+   - For each scope-2/scope-3 change you deferred as judgement-heavy.
+4. **Sources** — the docs URL(s) consulted per CLI.
+5. **Unverified notes** — one line per `unverified` CLI explaining why.
+6. **Final note (verbatim):**
+   > **CI is expected to fail on this PR if a map-bearing CLI gained new events — a
+   > reviewer must add the missing `*EVENT_MAP` entries (replacing `"???"`) before
+   > merging. For drift in Claude or Copilot only (no event map), CI should pass on
+   > this commit alone. CI must pass and this PR must be reviewed before merging.**
+
+## Constraints
+
+- **Only edit** these paths, and only where drift requires it: `src/hooks/types.ts`,
+  `src/hooks/integrations.ts`, `src/hooks/policy-evaluator.ts`,
+  `__tests__/hooks/manager.test.ts`, `__tests__/hooks/integrations.test.ts`,
+  `__tests__/e2e/hooks/<cli>-integration.e2e.test.ts`, the seven dogfood fixtures
+  (`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
+  `.github/hooks/failproofai.json`, `.opencode/opencode.json`,
+  `.opencode/plugins/failproofai.mjs`, `.pi/settings.json`, `.gemini/settings.json`),
+  and `CHANGELOG.md`.
+- Do **NOT** edit `.failproofai/policies-config.json` (the entrypoint manages it),
+  `src/hooks/handler.ts`, `src/hooks/manager.ts`, or any other source file.
+- Do **NOT** add entries to any `*EVENT_MAP`, `*_TOOL_MAP`, or `*_TOOL_INPUT_MAP`
+  for newly-added items. Removing a key when its array entry is removed IS allowed
+  (and required to keep the build green).
+- Do **NOT** invent events, tools, or fields. If WebFetch fails or the docs don't
+  expose a clean list, mark the CLI `unverified` and move on.

package/src/hooks/integrations.ts

@@ -154,7 +154,10 @@ export const claudeCode: Integration = {
     return {
       type: "command",
       command,
-      timeout: 60_000,
+      // Claude reads `timeout` in SECONDS per https://code.claude.com/docs/en/hooks
+      // ("Seconds before canceling. Defaults: 600 for command ...; 60 for agent"),
+      // NOT milliseconds. 60 = 60s; the old 60000 meant ~16.7h. (#482-class unit fix)
+      timeout: 60,
       [FAILPROOFAI_HOOK_MARKER]: true,
     };
   },
@@ -285,8 +288,10 @@ export const codex: Integration = {
         : `"${binaryPath}" --hook ${eventType} --cli codex`;
     return {
       type: "command",
-      // Codex reads `timeout` in SECONDS (its `timeout_sec` field, default 600) —
-      // NOT milliseconds like Claude/Cursor/Gemini. 60 = 60s, not 60000ms (~16.7h).
+      // Codex reads `timeout` in SECONDS (the field is literally `timeout`,
+      // default 600 per https://developers.openai.com/codex/hooks) — same unit as
+      // Claude/Cursor/Copilot, and unlike Gemini, whose `timeout` is in
+      // milliseconds (default 60000). 60 = 60s, not 60000ms (~16.7h).
       command,
       timeout: 60,
       [FAILPROOFAI_HOOK_MARKER]: true,
@@ -591,11 +596,13 @@ export const cursor: Integration = {
       scope === "project"
         ? `npx -y failproofai --hook ${eventType} --cli cursor`
         : `"${binaryPath}" --hook ${eventType} --cli cursor`;
-    // `timeout` is documented as ms in Cursor's schema (matches Claude).
+    // `timeout` is documented in SECONDS in Cursor's schema per
+    // https://cursor.com/docs/hooks ("Execution timeout in seconds"; doc examples
+    // use 30 and 10), NOT milliseconds. 60 = 60s; the old 60000 meant ~16.7h.
     return {
       type: "command",
       command,
-      timeout: 60_000,
+      timeout: 60,
       [FAILPROOFAI_HOOK_MARKER]: true,
     };
   },

package/src/hooks/types.ts

@@ -18,6 +18,18 @@ export const CODEX_HOOK_EVENT_TYPES = [
   "post_tool_use",
   "user_prompt_submit",
   "stop",
+  // Newly documented upstream (https://developers.openai.com/codex/hooks) —
+  // snake_case forms of the documented SubagentStart / PreCompact / PostCompact /
+  // SubagentStop events. Each has an exact 1:1 canonical HookEventType (already
+  // present in HOOK_EVENT_TYPES), so their CODEX_EVENT_MAP entries below are
+  // filled in directly. The map is an exhaustive `Record<CodexHookEventType,
+  // HookEventType>`, so tsc guarantees every event here keeps a mapping — a
+  // partial sync (event added, mapping missing) fails the build instead of
+  // silently writing an `undefined` event key into users' .codex/hooks.json.
+  "subagent_start",
+  "pre_compact",
+  "post_compact",
+  "subagent_stop",
 ] as const;
 export type CodexHookEventType = (typeof CODEX_HOOK_EVENT_TYPES)[number];
 
@@ -28,6 +40,10 @@ export const CODEX_EVENT_MAP: Record<CodexHookEventType, HookEventType> = {
   post_tool_use: "PostToolUse",
   user_prompt_submit: "UserPromptSubmit",
   stop: "Stop",
+  subagent_start: "SubagentStart",
+  pre_compact: "PreCompact",
+  post_compact: "PostCompact",
+  subagent_stop: "SubagentStop",
 };
 
 /**
@@ -92,6 +108,18 @@ export const COPILOT_HOOK_EVENT_TYPES = [
   "PostToolUse",
   "Stop",
   "SubagentStop",
+  // Newly documented upstream (cli-hooks-reference), each with an explicit
+  // PascalCase "VS Code compatible" variant shown in the docs. No COPILOT_EVENT_MAP
+  // exists (Copilot names are already Pascal), so appending keeps the build green.
+  // NOTE: `subagentStart` is also newly documented but appears camelCase-ONLY (no
+  // PascalCase variant listed), so it is deferred to the reviewer checklist rather
+  // than guessing a casing. `notification`, by contrast, DOES have a documented
+  // `Notification` PascalCase variant, so it is appended below.
+  "PostToolUseFailure",
+  "ErrorOccurred",
+  "PreCompact",
+  "PermissionRequest",
+  "Notification",
 ] as const;
 export type CopilotHookEventType = (typeof COPILOT_HOOK_EVENT_TYPES)[number];
 
@@ -556,6 +584,18 @@ export const HOOK_EVENT_TYPES = [
   "ElicitationResult",
   "UserPromptExpansion",
   "PostToolBatch",
+  // Newly documented upstream (https://code.claude.com/docs/en/hooks lifecycle
+  // table). `Setup` fires only on `--init`/`--maintenance` (low-frequency), so it
+  // is appended and installed like any other event.
+  //
+  // `MessageDisplay` is intentionally NOT appended. The docs mark it observe-only
+  // (it cannot block or modify anything) and note it fires on *every* assistant
+  // message display with no matcher support. Since `writeHookEntries` installs a
+  // hook for every entry in this array, appending it would spawn a failproofai
+  // subprocess on every message render for zero enforcement value. Deferred to the
+  // PR reviewer checklist; add it here only if a future observe-only use case
+  // (e.g. redaction/telemetry) justifies the per-message cost.
+  "Setup",
 ] as const;
 
 export type HookEventType = (typeof HOOK_EVENT_TYPES)[number];