Summary

Describe the problem and fix in 2–5 bullets:

• Problem: the docs still blur file-based hooks, plugin lifecycle hooks, and plugin-managed legacy hook registration into one generic “hooks” concept.
• Why it matters: that ambiguity keeps driving middleware/security proposals toward the wrong surface and makes api.registerHook(...) look like the default API instead of the compatibility bridge.
• What changed: docs/automation/hooks.md now defines the operator-automation boundary for HOOK-style hooks, and docs/tools/plugin.md now makes api.on(...) the preferred runtime lifecycle/middleware surface while documenting api.registerHook(...) as the legacy internal-hook bridge.
• What did NOT change (scope boundary): no runtime hook behavior changed in this PR, and OTEL/diagnostic-event guidance stays out of scope for a follow-up docs pass.

Change Type (select all)

• Docs

Scope (select all touched areas)

• API / contracts
• UI / DX

Linked Issue/PR

• Closes hooks: unify internal + plugin hook registries to fix 5 systemic bugs #30784
• Related docs: clarify api.on() vs api.registerHook() for plugin hooks #10680
• Related docs(hooks): document plugin hook names and clarify naming #12819
• Related Feature: Inbound/outbound middleware hooks for security layers #39582
• Related feat(hooks): add before_llm_call + after_llm_call plugin hooks [claude, human developer oversight] #39206
• Related feat(hooks): add before_response_emit hook for output policies [claude, human developer oversight] #39207
• Related feat(hooks): add context_assembled, loop_iteration_start/end observability hooks [claude, human developer oversight] #33915
• Related feat(hooks): add sender identity and session context to plugin hook agent context [claude, human developer oversight] #33914

User-visible / Behavior Changes

• Docs now explicitly tell users when to choose HOOK.md hooks vs typed plugin hooks.
• Plugin docs now route middleware/security work to api.on(...) instead of api.registerHook(...).
• None of the runtime hook implementations changed.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm
• Model/provider: n/a
• Integration/channel (if any): n/a
• Relevant config (redacted): none

Steps

1. Read the existing hook and plugin docs against the current hook implementations.
2. Update the docs to separate operator/file-based hooks from typed plugin lifecycle hooks.
3. Run pnpm check.

Expected

• Docs reflect the actual hook surface ownership and point new middleware proposals at the typed plugin runner.

Actual

• Docs now make that boundary explicit, and pnpm check passes.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: reviewed docs/automation/hooks.md and docs/tools/plugin.md against src/hooks/internal-hooks.ts, src/plugins/hooks.ts, src/plugins/registry.ts, and src/plugins/types.ts.
• Edge cases checked: verified the docs do not promise event.messages replies on lifecycle-only surfaces and do not claim api.registerHook(...) has ordering/block semantics.
• What you did not verify: no runtime behavior changed, so there was no manual gateway/channel exercise in this PR.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this PR.
• Files/config to restore: docs/automation/hooks.md, docs/tools/plugin.md
• Known bad symptoms reviewers should watch for: docs accidentally promising runtime behavior that does not exist.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: the docs could sound more deprecatory than the implementation actually is.
  • Mitigation: the text keeps api.registerHook(...) supported, but limits new middleware-style work to api.on(...).