@goodfoot/agent-hooks 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# @goodfoot/agent-hooks npm package changelog
+
+## 1.0.6
+
+Restructures the README's Install section to separate the npm package from the plugin, and documents verified plugin installation for Claude Code, Codex, Antigravity, and OpenCode. Adds `README.md` and `CHANGELOG.md` to the package's `files` list so both ship to npm; previously neither was published. No changes to the hook API, the compiler, or the CLI.
+
+## 1.0.5
+- Fixed Codex hook scaffold's PreToolUse/PostToolUse examples to avoid accessing unknown tool_input fields
+
+## 1.0.4
+- Fixed the Codex scaffold's generated `biome.json` to properly scope linting/formatting to project files and enable organized imports
+
+## 1.0.3
+- Fixed the Codex scaffold generating hook imports that pointed at the package root instead of the correct path
+- Fixed a type error in the OpenCode README example where the resumed-session branch didn't narrow correctly
+
+## 1.0.2
+- Added OpenCode plugin support, including session guardrails and advisory/policy hooks
+- Wired `--agent opencode` into the unified CLI for scaffolding OpenCode projects
+- Fixed a type error in scaffolded Claude Code hook tests
+
+## 1.0.1
+- Fixed hardcoded version references so displayed/reported versions stay in sync with the installed package
+- Updated documentation
+
+## 1.0.0
+
+Plugin and deprecation groundwork for the 1.0.0 release, plus the Antigravity descope from Step 0.
+
+- **Antigravity:** typed factories, output builders, and a self-oracled conformance matrix ship under the Step 0 Outcome B descope — Antigravity is not a shipped agent this release (`agy` OAuth-walls every non-interactive run; CI provides no usable backend). No `@goodfoot/agent-hooks/antigravity` export or skill exists yet; that lands in a follow-up card once a runnable CLI path exists.
+- **`plugins/agent-hooks`** added with `skills/claude-code` and `skills/codex` — mechanically ported and adapted from `plugins/claude-code-hooks/skills/sdk` and `plugins/codex-hooks/skills/sdk` (package names, import specifiers, CLI invocations, and the `AGENT_HOOKS_LOG_FILE`/`AGENT_HOOKS_LOG_ENV_VAR` env var rename). Each skill opens by checking for the deprecated package in the project's `package.json` and offering the repoint.
+- **`@goodfoot/claude-code-hooks` and `@goodfoot/codex-hooks`** marked deprecated: README banners, CHANGELOG entries, and patch version bumps (1.9.0 → 1.9.1, 1.3.0 → 1.3.1) so the notice reaches the registry page on next publish; their plugin skills narrowed to trigger only on the old package names, with a deprecation pointer at the top of each. `npm deprecate` itself, the version-1.0.0 tag/publish, and the marketplace evidence-gated smoke-install remain a separate, explicitly authorized release step — not run as part of this entry.
+
+## 0.3.0
+
+Codex parity: the full `@goodfoot/codex-hooks` 1.3.0 surface now ships behind `@goodfoot/agent-hooks/codex`.
+
+- **All 10 hook factories** ported with their config shapes (`matcher`, `timeout`, `statusMessage`), result unions, output builders (reserved fields emitted only when passed), input types, constants, and the runtime `execute` entry point. Factory results carry both `.hookEventName` (source name) and `.eventName` (core).
+- **`BlockError` preserved as a subclass of the core `HookBlockError`**, so the shared driver classifies it before consulting policy — carrying an ordering the source runtime already implemented. Public surface unchanged: `name`, `reason`, `instanceof BlockError`.
+- **Wire semantics verbatim:** BlockError → reason on stderr + exit 2 regardless of policy, for every event including SubagentStart (no per-event table — Codex has no narrower native deny); every other unexpected failure → stacktrace + exit 1 under the default policy (Codex exits 1 where Claude Code exits 2), `{}` at exit 0 under `"continue"`; malformed stdin is policy-gated on Codex (NOT unconditionally fail-open — that is Claude Code's rule). Returned-string normalization for the three text-output events is unchanged; other events reject plain text through the same policy path.
+- **Deliberate narrowing — advisory allow-list transcribed from codex-hooks README.md** (Fail-Open Execution): advisory = exactly {UserPromptSubmit, SessionStart, SubagentStart}; never = {PreToolUse, PermissionRequest, blocking PostToolUse/Stop/SubagentStop}; PreCompact/PostCompact are named nowhere in the README and are excluded by default, fail-closed, pending doc clarification. Enforced at factory-call time (runtime gate) and compile time (`MatcherHookConfigFor`/`NoMatcherHookConfigFor`). This intentionally breaks code passing `"continue"` to non-advisory Codex events; no shipped test exercised that gap.
+- **CLI:** `--agent codex` un-stubbed — Codex AST analysis (statusMessage-aware), command-context detection (`.codex-plugin` marker / `--plugin-root` / `.codex` git-toplevel mode / absolute), plugin-mode stable-names default, timeout-in-seconds and statusMessage hooks.json entries; `--plugin-root` flag added to the unified CLI. Codex scaffold templates emit `@goodfoot/agent-hooks` dependencies and `--agent codex` build scripts.
+- **Exports:** closed map grows by one explicit `./codex` subpath (still no wildcard).
+- **Test estate:** all 9 codex unit test files + e2e/runtime-and-build.test.ts ported under tests/codex/ and e2e/codex/ with import-specifier adaptation; parity checker extended to map codex-hooks sources; new conformance matrix documents the three NON-uniform advisory rows (SessionStart/UserPromptSubmit halt vs SubagentStart ignored) from the host-behaviour notes; cross-agent duplication check wired into `test`.
+
+## 0.2.0
+
+Claude Code parity: the full `@goodfoot/claude-code-hooks` 1.9.0 surface now ships behind `@goodfoot/agent-hooks/claude-code`, with one deliberate API narrowing.
+
+- **All 30 hook factories** ported, including `postToolBatchHook`, which the source package defined but never re-exported from its barrel (pre-existing bug fixed here). Output builders, input/output types, tool-helper guards, env utilities, `Logger`, and `EXIT_CODES` are re-exported from the same entry point.
+- **Deliberate narrowing — advisory fail-open allow-list (FMEA F2):** `unexpectedError: "continue"` is rejected for events not on the Claude Code advisory list (`HOOK_EVENT_NAMES` minus `PreToolUse`, `PermissionRequest`, blocking `Stop`/`SubagentStop`, `WorktreeCreate`/`WorktreeRemove`, transcribed verbatim from CARD.md:75). Enforcement is twice-folded: a runtime policy gate that throws at factory-call time, and compile-time config narrowing (`HookConfigFor`/`TypedHookConfigFor`) that makes `"continue"` unassignable on excluded events. This intentionally breaks code that passed `"continue"` to non-advisory events; no shipped test exercised that gap.
+- **`HookBlockError` wire translation:** a thrown block signal survives fail-open under every policy value and translates per event — native tool-scoped deny shapes for `PreToolUse` (`permissionDecision: "deny"`) and `PermissionRequest` (`decision.behavior: "deny"`), `{ continue: false, stopReason }` elsewhere — via the exported `BLOCK_SHAPE_BY_EVENT` table.
+- **Runtime renamed:** `execute()` now lives in `agents/claude-code/transport.ts` and drives through the shared core; wire semantics carried over exactly — JSON-on-stdout at exit 0 (`{}` when empty), stderr-carrying responses exit 2 with no stdout write, malformed stdin fails open unconditionally, worktree events keep their plain-text stdout protocol. Handler functions receive their context via factory-bound `createContext` (SessionStart gets `persistEnvVar`/`persistEnvVars`).
+- **Metadata property renamed:** factory results expose `.eventName` (core's shape) instead of `.hookEventName`.
+- **Log env vars renamed:** compiled hooks read/wire `AGENT_HOOKS_LOG_FILE` / `AGENT_HOOKS_LOG_ENV_VAR` instead of `CLAUDE_CODE_HOOKS_LOG_FILE` / `CLAUDE_CODE_HOOKS_LOG_ENV_VAR`.
+- **CLI:** single `agent-hooks` binary with a NEW required `--agent <claude-code|codex|antigravity>` flag — exit non-zero without it, never inferred; bare invocations are no longer help requests. `codex`/`antigravity` values validate but fail closed until their parity steps land. All prior flags (`--stable-names`, `--log`, `--log-env-var`, `--loader`, `--no-sourcemap`, scaffold) keep their semantics; install-context inference unchanged. Scaffold templates emit `@goodfoot/agent-hooks/claude-code` imports and `--agent claude-code` build scripts.
+- **Exports:** closed map gains the explicit `./claude-code` subpath (no wildcard, ever); `bin`/`publishConfig` name the `agent-hooks` binary.
+- **Test surface:** unit tests, `tests/types/`, and all 21 e2e files + fixtures ported with import-specifier-only adaptation, guarded by a parity script (counterpart presence + per-file assertion counts) wired into `test`; conformance matrix runs compiled bundles in child processes against hand-written expected wire triples.
+
+## 0.1.0
+
+Initial release: agent-neutral core only.
+
+- `defineHook<TInput, TOutput, TContext>(eventName, config, handler, policyGate?)` factory primitive with `unexpectedError` policy plumbing (`"error" | "continue"`, `onUnexpectedError` diagnostic sink) and an injectable per-event policy-validation gate; core hardcodes no event list and fails closed when a gate rejects.
+- `core/transport.ts`: `Transport` interface (`finalize(outcome)` pure mapping plus optional `rawStdout` predicate), shared `drive(transport, hookFn)` driver owning stdin read, JSON parse, handler invocation, buffered single-write emission, and process exit; `HookOutcome<TOutput>` discriminated union (`response`, `block`, `handlerError`, `rawStdout`).
+- `HookBlockError` — policy-exempt block-signal channel: classified before `unexpectedError` policy, so an advisory event's intentional block survives fail-open under every policy value.
+- `Logger` ported behavior-identically from `@goodfoot/claude-code-hooks` (silent by default, JSON Lines file output, event subscription).
+- Env utilities ported from `@goodfoot/claude-code-hooks`.
+- Stdin read + JSON parse helpers shared by both source runtimes.
+- Root-export lint as tests: `src/index.ts` re-exports `./core*` only; package `exports` map is a closed list with no `./*` wildcard subpath, with a fail-case fixture proving the check rejects wildcards.
+- Per-agent entry points (`claude-code`, `codex`, `antigravity`) intentionally absent; they land with their implementations.

package/README.md

@@ -20,11 +20,86 @@ validate against.
 
 ## Install
 
+Two things ship under the `agent-hooks` name. The **npm package** is the hook API and the
+compiler CLI. The **plugin** carries the `agent-hooks` skill, which teaches a coding agent
+how to write and compile hooks against this package — install it in whichever agent you
+develop with.
+
+### The npm package
+
 ```bash
 yarn add @goodfoot/agent-hooks
 # or npm install, pnpm, etc.
 ```
 
+### The plugin, for development
+
+All four hosts install from the published marketplace at
+[`goodfoot-io/marketplace`](https://github.com/goodfoot-io/marketplace). Claude Code and
+Codex resolve the repository directly; Antigravity and OpenCode need a local checkout
+because neither exposes a remote marketplace for skills.
+
+Note that the plugin and the npm package version independently — the plugin version you
+install will not match the package version above.
+
+#### Claude Code
+
+```bash
+claude plugin marketplace add goodfoot-io/marketplace
+claude plugin install agent-hooks@goodfoot
+```
+
+Verify with `claude plugin list` — `agent-hooks@goodfoot` should be listed as enabled.
+
+#### Codex
+
+```bash
+codex plugin marketplace add goodfoot-io/marketplace
+codex plugin add agent-hooks@goodfoot
+```
+
+The marketplace source must be a repository, git URL, or directory; passing the manifest
+path itself is rejected. `codex plugin add` requires the `<plugin>@<marketplace>` form.
+Verify with `codex plugin list --json`; the skill tree lands under
+`$CODEX_HOME/plugins/cache/goodfoot/agent-hooks/<version>/skills`.
+
+#### Antigravity
+
+`agy` has no marketplace command, so install from a checkout:
+
+```bash
+git clone https://github.com/goodfoot-io/marketplace.git
+agy plugin install ./marketplace/plugins-antigravity/agent-hooks
+```
+
+A successful install reports `skills : N processed`; `agents`, `commands`, `mcpServers`,
+and `hooks` report `skipped (not found)`, which is expected for a skills-only plugin.
+Verify with `agy plugin list`.
+
+This installs the authoring skill only. It is unrelated to `--agent antigravity`, which
+the compiler CLI still rejects (see the status note above).
+
+#### OpenCode
+
+OpenCode plugins are hook-transport modules and cannot contribute skills — skills load
+only from `skills.paths`. `opencode plugin` will not install this. Clone the repository
+and register the skill directory in `opencode.json`:
+
+```bash
+git clone https://github.com/goodfoot-io/marketplace.git
+```
+
+```json
+{
+  "skills": {
+    "paths": ["./marketplace/plugins-opencode/agent-hooks/skills"]
+  }
+}
+```
+
+Verify with `opencode debug skill`, which lists every discovered skill. This is separate
+from compiling hooks *for* OpenCode, covered in [OpenCode](#opencode) below.
+
 ## Quick Start
 
 ### 1. Write a hook

package/dist/agents/codex/scaffold.js

@@ -55,7 +55,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            [PACKAGE_NAME]: "^1.0.5",
+            [PACKAGE_NAME]: "^1.0.6",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.9",

package/dist/cli.js

@@ -26,7 +26,7 @@ import { scaffoldProject } from "./scaffold.js";
 // ============================================================================
 // Constants
 // ============================================================================
-const VERSION = "1.0.5";
+const VERSION = "1.0.6";
 const DEFAULT_ESBUILD_LOADERS = {
     ".md": "text",
 };

package/dist/scaffold.js

@@ -131,7 +131,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            "@goodfoot/agent-hooks": "^1.0.5",
+            "@goodfoot/agent-hooks": "^1.0.6",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.16",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/agent-hooks",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Unified agent hooks library: shared core runtime with per-agent entry points for Claude Code, Codex, and Antigravity",
   "homepage": "https://github.com/goodfoot-io/marketplace/tree/main/packages/agent-hooks",
   "repository": {
@@ -15,14 +15,15 @@
   },
   "files": [
     "dist",
-    "types"
+    "types",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc --build tsconfig.build.json",
     "lint": "biome check --write --unsafe --max-diagnostics 500 ./src ./tests ./e2e ./scripts && node ./scripts/check-stale-imports.mjs",
-    "test": "node ./scripts/check-e2e-parity.mjs && node ./scripts/check-stale-imports.mjs && node ./scripts/check-agent-duplication.mjs && vitest run",
-    "check:e2e-parity": "node ./scripts/check-e2e-parity.mjs",
+    "test": "node ./scripts/check-stale-imports.mjs && node ./scripts/check-agent-duplication.mjs && vitest run",
     "release": "bash ../../scripts/release-package.sh agent-hooks",
     "release:dry-run": "bash ../../scripts/release-package.sh agent-hooks --dry-run"
   },