Hooks loader supports only 6 of 13 CLI SDK hook events — missing preCompact, agentStop, subagent*, permissionRequest, notification, postToolUseFailure

[raykao]

Summary

src/core/hooks-loader.ts wires up 6 hook events:

preToolUse, postToolUse, userPromptSubmitted,
sessionStart, sessionEnd, errorOccurred

The upstream @github/copilot SDK (QueryHooks interface) supports 13:

export declare interface QueryHooks {
  preToolUse?: PreToolUseHook[];
  postToolUse?: PostToolUseHook[];
  postToolUseFailure?: PostToolUseFailureHook[];   // ← missing
  userPromptSubmitted?: UserPromptSubmittedHook[];
  sessionStart?: SessionStartHook[];
  sessionEnd?: SessionEndHook[];
  errorOccurred?: ErrorOccurredHook[];
  agentStop?: AgentStopHook[];                     // ← missing
  subagentStop?: SubagentStopHook[];               // ← missing
  subagentStart?: SubagentStartHook[];             // ← missing
  preCompact?: PreCompactHook[];                   // ← missing
  permissionRequest?: PermissionRequestHook[];     // ← missing
  notification?: NotificationHook[];               // ← missing
}

(Source: node_modules/@github/copilot/sdk/index.d.ts:11762)

The CLI hooks reference documents all 13 events: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-hooks-reference

Why this matters

The 7 missing hooks unlock several high-value use cases that aren't possible today through the bridge:

Hook	Use case
preCompact	Persist context before compaction discards it — critical for memory-capture pipelines (e.g. auto-write Beads memories before tokens are dropped)
agentStop	End-of-turn checkpoints; can block and force another turn (e.g. "did you write memories?" gate)
subagentStart / subagentStop	Observe and control delegated agent task tool calls — important for fleet-mode/multi-agent observability
permissionRequest	Programmatic allow/deny for headless / -p mode and CI; complements preToolUse
notification	Inject additionalContext into session on shell completion, agent idle, etc. — async signal hooks
postToolUseFailure	Provide structured recovery guidance when a tool fails (vs. just suppressing)

The most impactful is preCompact — it's the missing piece for an "auto-memory" hook similar to claude-mem's pipeline, where observed tool calls get summarised into persistent storage before the context window collapses.

Proposed change

Mostly mechanical:

1. Extend the LoadedHooks interface in src/core/hooks-loader.ts with the 7 missing on* callbacks.
2. Extend the EVENT_TO_SDK map with the 7 new event-name mappings.
3. Forward them through to the SDK's QueryHooks when constructing sessions in session-manager.ts.
4. Update docs/configuration.md (Hooks section) — currently only documents preToolUse and postToolUse; should reflect the full event list and link to the upstream CLI hooks reference.

Decision-control surface (allow/deny/block/additionalContext) for the new events is already defined by the SDK and CLI docs, so no new wire-format design is needed — the bridge just needs to forward stdin/stdout shape per event.

Scope check

• Bridge-only change. No upstream @github/copilot SDK enhancement required — the SDK already exposes all 13 events.
• Docs in docs/configuration.md (Hooks section) currently lists only preToolUse/postToolUse; the loader actually supports 6, so there's already a doc/code drift to close as part of this.

Happy to put up a PR if helpful.

[raykao]

Took a closer look before writing any code, and I think the issue's premise needs a small correction before this can move forward. Posting findings here so others hitting the same idea don't go down the wrong path.

What the bridge actually depends on

The bridge does not depend on @github/copilot directly. It only imports from @github/copilot-sdk:

src/core/session-manager.ts:1:  import { CopilotSession, approveAll } from '@github/copilot-sdk';
src/core/session-manager.ts:28: import type { SystemMessageCustomizeConfig } from '@github/copilot-sdk';
src/core/bridge.ts:18:          } from '@github/copilot-sdk';

package.json lists @github/copilot-sdk as the only @github/* runtime dependency. @github/copilot is a transitive dep that Dependabot tracks but the bridge code never imports.

What @github/copilot-sdk exposes (latest stable + beta)

SessionHooks in @github/copilot-sdk exposes 6 handlers, and these are the same 6 the bridge already wires up. Verified directly from npm pack of both 0.3.0 (current latest) and 1.0.0-beta.1 (current prerelease):

// node_modules/@github/copilot-sdk/dist/types.d.ts (v0.3.0 and v1.0.0-beta.1, identical)
export interface SessionHooks {
    onPreToolUse?: PreToolUseHandler;
    onPostToolUse?: PostToolUseHandler;
    onUserPromptSubmitted?: UserPromptSubmittedHandler;
    onSessionStart?: SessionStartHandler;
    onSessionEnd?: SessionEndHandler;
    onErrorOccurred?: ErrorOccurredHandler;
}

The README confirms the same 6 under "Available hooks". There is no onPreCompact, onAgentStop, onSubagentStart/Stop, onPermissionRequest, onNotification, or onPostToolUseFailure in the SDK's public surface today.

Where the 10 (not 13) hooks the issue cited actually live

The issue's reference to a 13-hook QueryHooks is from the CLI's bundled SDK at node_modules/@github/copilot/sdk/index.d.ts. Two corrections to that:

1. The actual QueryHooks interface there has 10 hook arrays, not 13. postToolUseFailure, permissionRequest, and notification are not in QueryHooks. The "notification" and "permissionRequest" names show up only as session-event types, not as hook arrays.

   // node_modules/@github/copilot/sdk/index.d.ts:14968 (transitive dep, not used by bridge)
   export declare interface QueryHooks {
     preToolUse?: PreToolUseHook[];
     postToolUse?: PostToolUseHook[];
     userPromptSubmitted?: UserPromptSubmittedHook[];
     sessionStart?: SessionStartHook[];
     sessionEnd?: SessionEndHook[];
     errorOccurred?: ErrorOccurredHook[];
     agentStop?: AgentStopHook[];
     subagentStop?: SubagentStopHook[];
     subagentStart?: SubagentStartHook[];
     preCompact?: PreCompactHook[];
   }

2. That file lives under the CLI's private sdk/ directory. It is not the public @github/copilot-sdk API. Importing from it would couple the bridge to private internals that ship with each CLI release and can break without notice.

Recommendation

Wait for @github/copilot-sdk to expose the additional hook handlers in its public SessionHooks interface. Once that lands, the change in the bridge becomes the small mechanical update originally proposed:

1. Extend SessionHooks in src/core/hooks-loader.ts with the new on* callbacks.
2. Extend the HOOK_TYPE_MAP with the new event-name mappings.
3. Update docs/configuration.md (Hooks section) — it currently lists only preToolUse/postToolUse, so there's an existing doc/code drift that should also be closed (the loader supports 6).

The right place to push for this is the @github/copilot-sdk repo. I'd suggest filing a tracker there asking for parity with the CLI's QueryHooks, with preCompact called out as the highest-value addition for memory-capture pipelines. Happy to file that upstream issue if it's useful.

Reaching into the CLI's private /sdk/ types from the bridge to get there sooner is technically possible but I'd rather not — it trades a clean public dependency for a fragile coupling to internals.

References

@github/copilot-sdk (the bridge's actual SDK dependency):

• npm package: https://www.npmjs.com/package/@github/copilot-sdk
• Source repo: https://github.com/github/copilot-sdk
• SessionHooks interface: see the bundled dist/types.d.ts — export interface SessionHooks { ... } (v0.3.0 and v1.0.0-beta.1)
• README "Session Hooks" section (lists the 6 supported events): bundled node_modules/@github/copilot-sdk/README.md after npm install

@github/copilot CLI (transitive only — bridge does not import from it):

• CLI hooks reference (CLI consumers, not SDK consumers): https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-hooks-reference
• Internal QueryHooks types live in the bundled node_modules/@github/copilot/sdk/index.d.ts (private API; subject to change between releases)

Related code in the bridge:

• src/core/hooks-loader.ts — LoadedHooks interface and HOOK_TYPE_MAP
• src/core/session-manager.ts:444 — resolveHooks and wrapHooksWithAsk

[raykao]

Dug deeper into the SDK and CLI internals after the initial response. The picture is more nuanced than my first comment suggested. Posting the full findings here.

The 6-hook ceiling is enforced by the CLI, not just the SDK

I assumed the limitation was purely in @github/copilot-sdk's TypeScript surface. It is not. The bundled CLI SDK runtime (node_modules/@github/copilot/app.js) has a createHooksProxy method that builds the bridge between the CLI's QueryHooks and the JSON-RPC hooks.invoke channel that talks to SDK consumers. Here is the complete return value of that proxy:

return {
  preToolUse:           [o => r("preToolUse", o)],
  postToolUse:          [o => r("postToolUse", o)],
  userPromptSubmitted:  [o => r("userPromptSubmitted", o)],
  sessionStart:         [o => r("sessionStart", o)],
  sessionEnd:           [o => r("sessionEnd", o)],
  errorOccurred:        [o => r("errorOccurred", o)],
};

agentStop, subagentStart, subagentStop, and preCompact exist on the CLI's internal QueryHooks type but are never forwarded over the wire to SDK consumers. This rules out a few workarounds I had considered:

• Monkey-patching session._handleHooksInvoke does not help — those events never reach the SDK process.
• Subclassing CopilotSession does not help — same reason.
• Importing QueryHooks types from @github/copilot/sdk/index.d.ts does not help — types without runtime delivery are useless.

A proper fix requires changes in both the CLI's createHooksProxy (to forward the additional hook types) and the SDK's SessionHooks interface plus _handleHooksInvoke dispatch table (to receive them). It is a coordinated upstream change, not a bridge-side change.

What works today: the CLI's native hooks.json path

Independent of the SDK protocol, the CLI itself discovers and runs hooks.json files from disk (its getHooksDir looks at <gitRoot>/.github/hooks/ and <configDir>/hooks/). When the CLI runs hooks via this path it executes bash commands directly with no SDK involvement, and this path supports all 13 hook types.

So the most-cited use case in the issue — preCompact to persist context before compaction — is already achievable today by placing a preCompact entry in a hooks.json at a path the CLI itself discovers (e.g., ~/.config/copilot/hooks/hooks.json or workspace .github/hooks/hooks.json). The CLI fires the hook natively. No bridge SDK callback is needed.

The bridge's src/core/hooks-loader.ts is a re-implementation of hooks.json discovery that translates entries into in-process JS callbacks for the SDK's SessionHooks. That re-implementation is what hits the 6-hook ceiling. The CLI's own path is unaffected.

Two distinct asks bundled in this issue

1. "Let the bridge intercept the additional hook types as JS callbacks" — blocked on coordinated upstream work in @github/copilot (the CLI) and @github/copilot-sdk. Not actionable in the bridge today.

2. "Let bridge users actually use the additional hook types" — already achievable today via direct hooks.json configured at CLI-discovered paths. Mostly a docs gap; docs/configuration.md could call this out.

A small actionable item for the bridge

hooks-loader.ts has a VALID_HOOK_TYPES whitelist and logs Unknown hook type for anything outside the 6 it supports. If a user authors ~/.copilot/hooks.json with a preCompact entry expecting the CLI to handle it, the bridge will currently emit a noisy warning even though the CLI handles the hook fine via its own discovery.

Two reasonable options:

• Expand the whitelist to include the additional hook types, load them silently as no-ops in the bridge process, and let the CLI handle execution via its own path. Removes the false-positive warning. Slight risk: shadows the SDK-callback path if it ever lands.
• Document that workspace hooks.json files for additional hook types must live at CLI-discovered paths (not bridge-discovered paths) and let the warning continue as a hint that the bridge is not the right place to register them.

Either is small enough to land independently of the upstream work.

References

• Bridge SDK dependency: @github/copilot-sdk https://www.npmjs.com/package/@github/copilot-sdk (source https://github.com/github/copilot-sdk)
• SDK SessionHooks interface: bundled dist/types.d.ts (v0.3.0 stable, v1.0.0-beta.1 beta — both expose 6 hooks)
• CLI hooks reference (covers all 13 disk-supported hook types): https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-hooks-reference
• CLI internal QueryHooks type (transitive, private): node_modules/@github/copilot/sdk/index.d.ts:14968 (10 hooks, not 13)
• CLI proxy that limits SDK delivery to 6: node_modules/@github/copilot/app.js, createHooksProxy method

[raykao]

Empirical update — partly retracts my earlier "all 13 work via the CLI native disk path" claim.

Set up a smoke test on the dark-factory workspace: hooks.json entries for all 13 hook types, each calling a side-effect-free trace script that logs to /tmp/copilot-hook-trace.log (timestamp, hook name, payload size, sha256, first 200 chars of payload). Started fresh bridge sessions and exercised:

• multi-turn prompts (sessionStart/End)
• multiple tool calls (preToolUse/postToolUse)
• a sub-agent spawn via the task tool with a follow-up read_agent
• a normal "complete" termination plus one "error" termination

Results (~70 hook events captured)

   28 preToolUse
   27 postToolUse
    7 userPromptSubmitted
    6 sessionEnd
    2 sessionStart

Hooks that did NOT fire despite plausible triggers

Hook	Trigger exercised	Fired?
agentStop	Full turn ended cleanly	No
subagentStart / subagentStop	task tool spawned an explore sub-agent (verified via preToolUse toolName:"task")	No
preCompact	Compaction not forced	not triggered
permissionRequest	No interactive prompts	not triggered
notification	No background notifications observed	not triggered
postToolUseFailure	No tool failures	not triggered
errorOccurred	No error path	not triggered

The decisive data point: the trace log captured preToolUse + postToolUse events for toolName: "task" (sub-agent spawn) followed by read_agent, but zero subagentStart or subagentStop lines around them. That definitively refutes the hypothesis I posted earlier — disk-registered entries for the SDK-uncovered hook types do not actually fire under bridge sessions even though the CLI's executeHooks is a generic dispatcher.

Best current hypothesis

The CLI is spawned by the SDK in --headless mode (@github/copilot-sdk/dist/client.js:867). It looks like the additional hook event types (agentStop, subagent*, preCompact, etc.) are only emitted on interactive-UI code paths, or only fire when there is an SDK-protocol consumer wired via createHooksProxy — which is exactly the same 6 the SDK already exposes. Either way, the practical outcome is the same:

Disk-side hooks.json entries beyond the 6 SDK-supported types are silently inert under bridge sessions today.

Practical implications

• The bridge today is effectively bounded to the same 6 hooks the SDK exposes. The "use the CLI's disk path" workaround I suggested does not unlock the additional 7 in headless/bridge mode.
• claude-mem-style preCompact memory hooks won't work today via copilot-bridge, even installed at CLI-discovered paths. (preCompact was not directly tested via forced compaction, but given that other hooks of the same class don't fire, the assumption that it does would be optimistic.)
• The original framing in this issue is closer to correct than my second comment suggested. Apologies for the back-and-forth — wanted to verify before pushing in either direction.

Worth confirming separately

A focused test that forces compaction (/compact slash command if the bridge passes it through, or a long enough session to auto-compact) would close the inconclusive preCompact row above. Same for a deliberate error or permission prompt for errorOccurred / permissionRequest. I'll run those if/when there's time, but didn't want to delay the correction.

Net recommendation

Treat this as upstream-only. The fix needs to land in:

1. @github/copilot CLI: extend createHooksProxy to forward the additional hook types over hooks.invoke RPC (and ensure they actually emit in headless mode).
2. @github/copilot-sdk: extend SessionHooks to expose handlers for the new types and extend _handleHooksInvoke's dispatch table.

Once that lands, the bridge-side change in this issue becomes the small mechanical update originally proposed (extend SessionHooks interface + HOOK_TYPE_MAP in src/core/hooks-loader.ts, update docs/configuration.md).

[raykao]

Refined mental model based on the smoke-test results above. Trying to give a more precise picture of WHY each hook does or doesn't fire under bridge sessions, since "SDK doesn't expose them" is close to right but not exactly what's happening.

The 5 hooks that fire come from universal CLI code paths

preToolUse, postToolUse, userPromptSubmitted, sessionStart, sessionEnd (and presumably errorOccurred, untested) are emitted from CLI code paths that run on every interaction regardless of mode (interactive UI, headless, SDK-driven):

• Every tool call goes through the CLI's tool-dispatch wrapper -> preToolUse/postToolUse fire.
• Every user message gets parsed -> userPromptSubmitted fires.
• Every session lifecycle hits open/close -> sessionStart/sessionEnd fire.

The CLI runs these dispatchers on behalf of the SDK consumer, so the events fire under bridge sessions too. Wiring them into the bridge (5 of 6 are already wired in src/core/hooks-loader.ts — just errorOccurred documentation drift) is the actionable bridge-side scope.

The hooks that don't fire are tied to CLI-internal subsystems that the bridge bypasses

Hook	CLI subsystem that emits it	Why bridge bypasses it
agentStop	End of CLI's own agent turn loop	Bridge owns the turn loop. Bridge sends a prompt, the CLI forwards to the LLM, the LLM responds, the bridge decides what's next. The CLI never enters its "agent loop turn complete" code path under SDK mode.
subagentStart / subagentStop	CLI's native sub-agent orchestrator	Bridge has its OWN sub-agent system (the task tool). To the CLI, that's just a registered custom tool with the name "task". The CLI never invokes its own sub-agent orchestrator, so its sub-agent events never fire.
preCompact	CLI's internal context compaction (auto OR /compact)	Auto-compact MIGHT still fire if context fills up under bridge — not yet tested. Manual /compact doesn't fire because the bridge forwards /compact as plain user text via userPromptSubmitted, not as a CLI slash command (verified in trace).

So the precise framing isn't "the SDK doesn't pass these events to the CLI." It's:

The hooks that fire under bridge sessions are the ones whose emission lives in code paths the CLI runs as a tool/lifecycle dispatcher for the SDK. The hooks that don't fire are ones whose emission lives in code paths the CLI only enters when it is the orchestrator (its own turn loop, its own sub-agent spawner, its own slash-command interpreter).

What this means for the bridge-side fix

The original mechanical change in this issue is still correct in scope but the impact picture is layered:

1. Wire the 1 missing SDK-supported hook (errorOccurred) and close the documentation drift. Cheap and clearly useful.
2. Stop warning "Unknown hook type" for the 7 remaining types. Either silently no-op them (so users authoring hooks.json against the upstream CLI hooks reference don't see a noisy warning), or document explicitly that those types are not supported under bridge sessions and need to be configured at CLI-discovered paths instead.
3. Document the actual behavior model in docs/configuration.md. Right now the docs only mention preToolUse/postToolUse, which dramatically understates what the bridge already supports AND understates the limitations on what the disk-loaded path delivers.

Upstream (@github/copilot CLI + @github/copilot-sdk) work needed for the rest

Each of the unfired hooks needs a different upstream change, not just an SDK-protocol wiring fix:

• agentStop: CLI would need to emit at the boundary of every SDK-handled prompt-response cycle, OR expose a way for SDK consumers to signal "turn complete." Design change.
• subagent*: CLI would need to define what "sub-agent" means when SDK consumers invoke their own orchestration, OR provide a way for SDK consumers to declare that their custom tool IS a sub-agent invocation.
• preCompact: Most likely already fires on auto-compact under SDK mode, just unverified. If true, this is the lowest-hanging fruit (only requires SDK-protocol wiring changes to forward, no CLI design change).
• permissionRequest, notification, postToolUseFailure: not in the CLI's QueryHooks interface at all (only in CLI's session-event types), so these would need both CLI emission AND SDK protocol wiring.

Outstanding test before the picture is fully closed

preCompact on auto-compact is the one inconclusive case. A focused test (long enough headless session to fill context and trigger auto-compact, with a preCompact hook installed at a CLI-discovered path) would either confirm it works today (in which case the bridge could light it up with minimal changes) or extend the "needs upstream design" list.

If preCompact does work, then claude-mem-style memory capture under bridge IS achievable today via the CLI native disk path, just not via bridge-side JS callback. That single hook is by far the highest-value of the 7 for memory-pipeline use cases.