feat(hooks): export HookHandler / HookEvent / HookResult — the typed config hook handler contract

[ScriptedAlchemy]

Fixes #488.

What

agent-bundle (root) and agent-bundle/config now export the typed contract of a hooks.<event>.handler module, from the new packages/agent-bundle/src/adapters/hook-handler.ts:

• HookHandler<E> — (event: HookEvent<E>, context: HookHandlerContext) => HookResult<E> | void | Promise<…>; the second argument is what the generated wrapper already passes ({ nativeEvent, nativeInput, target }).
• HookEvent<E> and the named payloads SessionStartHookEvent, BeforeToolHookEvent, AfterToolHookEvent, StopHookEvent, AgentStartHookEvent, AgentStopHookEvent (+ HookEventBase, HookEventPayloads). A field is required only when every host's wrapper guarantees it (sessionId always; toolName/toolInput/toolUseId on tool events; stopHookActive on stop events; agentId/agentType on agentStart; agentType on agentStop).
• HookResult<E> = HookContinueResult<E> | HookDenyResult<E>, derived from the exported per-event table hookResultContract (deny / additionalContext / updatedInput per event). Illegal fields are typed ?: never, so satisfies rejects them regardless of excess-property rules: a denying sessionStart, outcome: 'stop' anywhere, reason beside continue, a denial without reason, updatedInput while denying or on any event but beforeTool, additionalContext on beforeTool/stop/agentStart/agentStop.
• HookHandlerEventName / hookHandlerEventNames — the six canonical events every host maps to a plain hook (sessionStart, beforeTool, afterTool, stop, agentStart, agentStop); the contract is keyed by it, not by CanonicalHookEvent, because workspaceOpen is served by an event route and a config-declared handler for it is a build error on every host.
• hookEventFields — the runtime twin of the payload types (required/optional field names per event).
• CanonicalHookEvent, AgentBundleHookEntry, AgentBundleHookInput are exported alongside (they were not public before, contrary to the issue text).

The table is the portable contract — a field it admits is accepted by every host's wrapper and reaches that host's native output — because a handler typed once must run unchanged, with the same effect, on every host it targets. Host-specific behaviour stays runtime-only and is pinned by the test: additionalContext on beforeTool (every validator accepts it, but Cursor's preToolUse output carries only a permission or an input rewrite, so it is delivered on Claude/Codex alone); Cursor admits a denying agentStart; Claude/Codex admit additionalContext on agentStart; Claude admits additionalContext on agentStop. One caveat the type cannot carry is documented instead (rule JSDoc + guide): Cursor consumes an agentStop denial only when the subagent's status is completed.

Can't-drift guarantee. The wrappers' runtime validateResult is unchanged (the issue asks for that: JS and prebuilt handlers keep the same runtime contract). packages/agent-bundle/tests/hook-handler-contract.test.ts loads the generated Claude, Codex, and Cursor wrapper sources with their validators exported and:

• runs all 32 result shapes over the four admitted keys × 6 events × 3 hosts through the real validateResult, asserting that everything the table admits every host accepts, and that the set of shapes a host accepts beyond the table equals exactly the documented leniency set (so any change to hook-contract.ts validateResult or to the table fails the test);
• runs each host's native fixture through validateNativeInput + the wrapper decoder and checks the decoded field set against hookEventFields (required present, nothing undeclared);
• compile-time (via pnpm typecheck): keyof HookEvent<E> with its required/optional split equals hookEventFields[E]; seven legal handlers type-check; ten illegal results are @ts-expect-error (including beforeTool context and a workspaceOpen handler).

Consumer code replaced

• examples/hooks-and-scripts/src/hooks/session-start.ts, examples/mcp-app/src/hooks/session-start.ts: the hand-written interface SessionStartEvent and outcome: 'continue' as const are gone; both are export default ((event) => ({ … })) satisfies HookHandler<'sessionStart'> (event.sessionId is now known to be a string).
• examples/hooks-and-scripts gains a tsconfig.json and a typecheck script wired into check, so a sessionStart handler returning { outcome: 'deny', reason } fails pnpm typecheck there as the issue's acceptance requires (it previously had no typecheck at all; the wrapper still fails it at runtime).
• website/docs/{en,zh}/guide/authoring/hooks.mdx "The handler contract": the typed form replaces the hand-written interface; the four-key table and per-event rules stay as the runtime contract.

Relationship to #466

#466 asks for a canonical per-family payload on AgentEventRouteProps for RSC event routes (src/events/**). This PR types the plain config hook handler (hooks.<event>.handler): its event parameter and its result, including the per-event legality the wrapper enforces. The per-family field table here (hookEventFields / the *HookEvent interfaces, keyed by CanonicalHookEvent) is the natural shared source for #466's payloads, but #466 is not implemented here: event routes still receive { canonical, native, signal }, and a handler result has no counterpart on that side.

Checks

• pnpm typecheck, pnpm lint clean; pnpm test:unit 3249/3249 (incl. the new contract test, 4 cases); pnpm build.
• examples/hooks-and-scripts pnpm check (validate + build + typecheck, Claude host validation passed); examples/mcp-app validate + build + typecheck.
• pnpm docs:site:build passes (TypeDoc renders the new root/config pages; parity ok).

Changeset

.changeset/488-hook-handler-types.md (agent-bundle: patch).

Review status

• 9236269b6 — Codex reviewed; three threads on hook-handler.ts, all addressed in df51483d8:
  • P1 "Exclude Cursor-dropped before-tool context": beforeTool.additionalContext is now false in the portable table (Cursor validates the field but its preToolUse output has no context channel). The contract's definition is tightened to accepted and delivered on every host; the agreement test pins the five before-tool context shapes as validator-only leniencies on all three hosts, and { additionalContext } satisfies HookResult<'beforeTool'> is an @ts-expect-error.
  • P2 "Model Cursor's conditional agent-stop denial": denial stays in the portable agentStop result (it is a Claude/Codex/Cursor feature) and the status rule is documented where a reader meets it — HookResultRule.deny JSDoc, the table comment, and the hooks guide (en + zh): Cursor consumes an agentStop denial only for status === "completed", so a handler targeting Cursor checks context.nativeInput.status first.
  • P2 "Exclude the unmapped workspace-open handler": the contract is keyed by the new HookHandlerEventName (six events); workspaceOpen has no HookHandler/HookEvent/HookResult, the test derives the event set from the hosts' plain-hook event maps and asserts workspaceOpen is absent, and HookHandler<'workspaceOpen'> is an @ts-expect-error.
  • Re-verified: pnpm typecheck, pnpm lint, the contract test (4/4), examples typecheck, pnpm docs:site:build. Rebased onto current main.
• Awaiting the reviewer on the current head. Per this task's rules no PR comments are posted; review threads are answered by commits and recorded here.

CanonicalHookEvent) is the natural shared source for #466's payloads, but #466 is not implemented here: event routes still receive { canonical, native, signal }, and a handler result has no counterpart on that side.

Checks

• pnpm typecheck, pnpm lint clean; pnpm test:unit 3249/3249 (incl. the new contract test, 4 cases); pnpm build.
• examples/hooks-and-scripts pnpm check (validate + build + typecheck, Claude host validation passed); examples/mcp-app validate + build + typecheck.
• pnpm docs:site:build passes (TypeDoc renders the new root/config pages; parity ok).

Changeset

.changeset/488-hook-handler-types.md (agent-bundle: patch).

Review status

• 9236269b6 — Codex reviewed; three threads on hook-handler.ts, all addressed in df51483d8:
  • P1 "Exclude Cursor-dropped before-tool context": beforeTool.additionalContext is now false in the portable table (Cursor validates the field but its preToolUse output has no context channel). The contract's definition is tightened to accepted and delivered on every host; the agreement test pins the five before-tool context shapes as validator-only leniencies on all three hosts, and { additionalContext } satisfies HookResult<'beforeTool'> is an @ts-expect-error.
  • P2 "Model Cursor's conditional agent-stop denial": denial stays in the portable agentStop result (it is a Claude/Codex/Cursor feature) and the status rule is documented where a reader meets it — HookResultRule.deny JSDoc, the table comment, and the hooks guide (en + zh): Cursor consumes an agentStop denial only for status === "completed", so a handler targeting Cursor checks context.nativeInput.status first.
  • P2 "Exclude the unmapped workspace-open handler": the contract is keyed by the new HookHandlerEventName (six events); workspaceOpen has no HookHandler/HookEvent/HookResult, the test derives the event set from the hosts' plain-hook event maps and asserts workspaceOpen is absent, and HookHandler<'workspaceOpen'> is an @ts-expect-error.
  • Re-verified: pnpm typecheck, pnpm lint, the contract test (4/4), examples typecheck, pnpm docs:site:build. Rebased onto current main.
• Awaiting the reviewer on the current head. Per this task's rules no PR comments are posted; review threads are answered by commits and recorded here.

CanonicalHookEvent) is the natural shared source for #466's payloads, but #466 is not implemented here: event routes still receive { canonical, native, signal }, and a handler result has no counterpart on that side.

Checks

• pnpm typecheck, pnpm lint clean; pnpm test:unit 3249/3249 (incl. the new contract test, 4 cases); pnpm build.
• examples/hooks-and-scripts pnpm check (validate + build + typecheck, Claude host validation passed); examples/mcp-app validate + build + typecheck.
• pnpm docs:site:build passes (TypeDoc renders the new root/config pages; parity ok).

Changeset

.changeset/488-hook-handler-types.md (agent-bundle: patch).

Review status

• 9236269b6 — Codex reviewed; three threads on hook-handler.ts, all addressed in df51483d8:
  • P1 "Exclude Cursor-dropped before-tool context": beforeTool.additionalContext is now false in the portable table (Cursor validates the field but its preToolUse output has no context channel). The contract's definition is tightened to accepted and delivered on every host; the agreement test pins the five before-tool context shapes as validator-only leniencies on all three hosts, and { additionalContext } satisfies HookResult<'beforeTool'> is an @ts-expect-error.
  • P2 "Model Cursor's conditional agent-stop denial": denial stays in the portable agentStop result (it is a Claude/Codex/Cursor feature) and the status rule is documented where a reader meets it — HookResultRule.deny JSDoc, the table comment, and the hooks guide (en + zh): Cursor consumes an agentStop denial only for status === "completed", so a handler targeting Cursor checks context.nativeInput.status first.
  • P2 "Exclude the unmapped workspace-open handler": the contract is keyed by the new HookHandlerEventName (six events); workspaceOpen has no HookHandler/HookEvent/HookResult, the test derives the event set from the hosts' plain-hook event maps and asserts workspaceOpen is absent, and HookHandler<'workspaceOpen'> is an @ts-expect-error.
  • Re-verified: pnpm typecheck, pnpm lint, the contract test (4/4), examples typecheck, pnpm docs:site:build. Rebased onto current main.
• Awaiting the reviewer on the current head. Per this task's rules no PR comments are posted; review threads are answered by commits and recorded here.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6a70b2e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agent-bundle	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-04T06:25:49.850771Z	9236269	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@533

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@533

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@533

commit: 6a70b2e

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9236269b61

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Exclude Cursor-dropped before-tool context

When a beforeTool handler targets Cursor, this contract permits additionalContext, but cursorHookWrapperSource accepts the field and then its encodeOutput emits only a denial or an input rewrite for this event, silently dropping the context. This makes a result accepted by HookHandler<'beforeTool'> fail to provide the promised context on one supported host; either exclude this field from the portable contract or preserve it in Cursor's projection.

AGENTS.md reference: AGENTS.md:L78-L81

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Model Cursor's conditional agent-stop denial

When Cursor invokes agentStop with the valid error or aborted status, an unconditional denial allowed by this portable type reaches encodeOutput and throws because Cursor consumes followup_message only for status === "completed". The new contract therefore admits a handler that cannot run across all valid Cursor payloads as advertised; exclude denial from the portable result or model and document the status-dependent restriction.

AGENTS.md reference: AGENTS.md:L78-L81

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Exclude the unmapped workspace-open handler

Any consumer can now compile a HookHandler<'workspaceOpen'>, yet every production target's plain-hook event map omits workspaceOpen, and the documented supported form is an event route with a different component contract; a config-declared handler therefore always produces a build diagnostic and never reaches a generated handler wrapper. Remove workspaceOpen from this config-handler contract unless a production hook mapping is added.

AGENTS.md reference: AGENTS.md:L11-L16

Useful? React with 👍 / 👎.