sdk: Expose AgentStop session hook across languages - #2054
Open
belaltaher8 wants to merge 4 commits into
Open
Conversation
The runtime already fires the top-level agent's `agentStop` hook and
registers it for SDK callback sessions (REGISTERED_CALLBACK_EVENT_NAMES),
with a working block/continue re-prompt loop, but the Node SDK never
exposed it: SessionHooks had no `onAgentStop` and `_handleHooksInvoke`
had no dispatch entry, so `agentStop` callbacks were silently dropped.
Add the AgentStopHookInput/Output/Handler types, the `onAgentStop` field
on SessionHooks, and the `agentStop` entry in the hook dispatcher.
Returning `{ decision: "block", reason }` keeps the agent running with
`reason` enqueued as a follow-up message (e.g. to remediate findings a
handler surfaced); returning nothing lets the agent stop.
This unblocks the Copilot cloud agent restoring its post-completion
security-tool hooks (dependabot / secret scanning) on the proper platform
hook rather than ad-hoc per-commit hooks.
Note: parallel changes for the Python/Go/.NET SDKs are follow-ups.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2031e02b-7fe5-4075-9d75-eb20eb29f407
Contributor
There was a problem hiding this comment.
Pull request overview
Exposes the Node.js SDK’s top-level agentStop lifecycle hook.
Changes:
- Adds typed agent-stop input, output, and handler APIs.
- Routes
agentStopcallbacks through the session dispatcher. - Adds dispatcher and JSON-RPC unit tests.
Show a summary per file
| File | Description |
|---|---|
nodejs/src/types.ts |
Defines the agent-stop hook API. |
nodejs/src/session.ts |
Dispatches agent-stop callbacks. |
nodejs/test/client.test.ts |
Tests direct and JSON-RPC dispatch. |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 3
- Review effort level: Medium
Add AgentStop types and dispatch support for Python, Go, .NET, Rust, and Java, and normalize the Node stop_hook_active wire field. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4f4d61ce-6d2f-4b72-a2da-52f60300df59
Export Node hook types, document the hook, cover wire-field normalization, add Go and .NET E2E block-continuation coverage, and format the Python README. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4f4d61ce-6d2f-4b72-a2da-52f60300df59
belaltaher8
changed the title
Document the public input member names for Node, Python, Go, .NET, Rust, and Java. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4f4d61ce-6d2f-4b72-a2da-52f60300df59
belaltaher8
marked this pull request as ready for review
July 28, 2026 02:50
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Exposes the top-level agent's
agentStoplifecycle hook across the Node.js, Python, Go, .NET, Rust, and Java SDKs.The Copilot CLI runtime already fires
agentStopwhen the top-level agent reaches a natural terminal stop and supports a block/continue loop: returning{ decision: "block", reason }enqueuesreasonas a follow-up message, while consecutive blocks are capped to prevent runaway loops. This PR adds the missing public SDK types and callback dispatch paths.Changes
agentStopthrough each language's existinghooks.invokecallback transport.stop_hook_activewire field to Node's publicstopHookActivefield.SessionHooksfrom the package root.Motivation
This enables SDK consumers, including Copilot cloud coding agent integrations, to run completion checks at the natural end of an agent turn and request remediation through the platform hook instead of relying on ad-hoc commit-boundary callbacks.
Behavior
Returning no decision allows the agent to stop normally. Returning:
{ "decision": "block", "reason": "Run final validation and fix any failures." }keeps the agent running with the reason as a follow-up prompt. Consumers can use the active-stop flag (
stopHookActive, with language-appropriate casing) to avoid repeatedly blocking a continuation turn.Related: github/copilot-agent-runtime#13230