Summary

Describe the problem and fix in 2–5 bullets:

• Problem: plugin-registered internal hooks (for example session:start) were being cleared during gateway startup when file-based internal hooks were loaded.
• Why it matters: plugins that rely on internal hook callbacks silently stop working after startup.
• What changed: clearInternalHooks() now runs once before plugin loading in src/gateway/server.impl.ts; clearing was removed from sidecar hook loading in src/gateway/server-startup.ts; regression coverage added in src/gateway/server-startup.plugin-internal-hooks.test.ts.
• What did NOT change (scope boundary): no changes to hook file format, plugin API, channel logic, or non-startup hook behavior.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway / orchestration

Linked Issue/PR

• Closes #
• Related [Bug]: Plugin-registered internal hooks are cleared during gateway startup #13709

User-visible / Behavior Changes

• Plugin-registered internal hooks now persist through gateway startup and still fire after internal hook discovery runs.
• No config/default changes.

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 (local verification), CI failure originally observed on Windows test lane
• Runtime/container: Node + pnpm
• Model/provider: N/A
• Integration/channel (if any): plugin internal hooks
• Relevant config (redacted): gateway startup with plugin registering internal hooks

Steps

1. Start gateway with a plugin that registers an internal hook during registration.
2. Ensure internal hook discovery/load runs at startup.
3. Observe whether plugin-registered hook remains registered/fires.

Expected

• Plugin-registered hooks remain active after startup.

Actual

• After fix, plugin-registered hooks remain active; regression test passes.

Evidence

Attach at least one:

• Failing test/log before + passing after

Human Verification (required)

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

• Verified scenarios:
  • pnpm check passes on branch.
  • pnpm test -- src/gateway/server-startup.plugin-internal-hooks.test.ts passes.
  • pnpm test -- src/docker-setup.test.ts passes (Windows-related test portability nudge included on this branch).
• Edge cases checked:
  • Hook registry is cleared before plugin load, not during sidecar hook discovery.
  • File-based internal hooks still load.
• What you did not verify:
  • Full end-to-end channel matrix/manual runtime validation across all integrations.

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 commit(s) from pr/internal-hooks-clear-before-plugins.
• Files/config to restore:
  • src/gateway/server.impl.ts
  • src/gateway/server-startup.ts
  • src/gateway/server-startup.plugin-internal-hooks.test.ts
• Known bad symptoms reviewers should watch for:
  • Plugin internal hooks not firing after startup.

Risks and Mitigations

• Risk: startup ordering regressions around plugin load vs hook discovery.
  • Mitigation: focused regression test added for plugin-registered internal hooks surviving startup.
• Risk: low-level gateway startup flow changed in hot path.
  • Mitigation: change is minimal (clear moved earlier; no new behavior branches added).

Greptile Summary

Fixed plugin-registered internal hooks being cleared during gateway startup. Previously, clearInternalHooks() was called during file-based internal hook discovery, which wiped out hooks that plugins had registered during their initialization. The fix moves the clear operation to run once before plugin loading in src/gateway/server.impl.ts:272, ensuring plugin-registered hooks survive the startup sequence.

• Moved clearInternalHooks() from server-startup.ts to server.impl.ts to run before plugins load
• Added clear explanatory comments about the ordering constraint
• Included regression test validating plugin hooks survive hook discovery

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The change is minimal, well-scoped, and addresses a clear bug in startup ordering. The fix simply moves an existing function call to the correct location in the startup sequence. The regression test provides strong coverage of the exact failure scenario, and the code includes clear comments explaining the constraint.
• No files require special attention

_{Last reviewed commit: 32bcbfc}