@github/copilot-sdk 1.0.17-preview.0 → 1.0.17-preview.10

package/dist/session.js

@@ -20,6 +20,18 @@ function copyDefinedWorkflowAgentOption(source, target, key) {
     target[key] = value;
   }
 }
+function toToolDefinition(tool) {
+  return {
+    name: tool.name,
+    description: tool.description ?? "",
+    parameters: toJsonSchema(tool.parameters),
+    overridesBuiltInTool: tool.overridesBuiltInTool,
+    skipPermission: tool.skipPermission,
+    defer: tool.defer,
+    metadata: tool.metadata,
+    isTerminal: tool.isTerminal
+  };
+}
 const workflowExecutionStore = new AsyncLocalStorage();
 function throwIfWorkflowExecutionIsActive() {
   if (workflowExecutionStore.getStore()?.active) {
@@ -240,6 +252,8 @@ class CopilotSession {
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
+  /** Settles once every earlier `setTools` call has finished. */
+  setToolsQueue = Promise.resolve();
   pendingExternalTools = /* @__PURE__ */ new Map();
   canvases = /* @__PURE__ */ new Map();
   bearerTokenProviders = /* @__PURE__ */ new Map();
@@ -252,6 +266,7 @@ class CopilotSession {
   elicitationHandler;
   exitPlanModeHandler;
   autoModeSwitchHandler;
+  skillProvider;
   hooks;
   transformCallbacks;
   _rpc = null;
@@ -664,6 +679,7 @@ class CopilotSession {
     this.elicitationHandler = void 0;
     this.exitPlanModeHandler = void 0;
     this.autoModeSwitchHandler = void 0;
+    this.skillProvider = void 0;
     this.commandHandlers.clear();
     this.canvases.clear();
     this.workflows.clear();
@@ -1051,7 +1067,20 @@ class CopilotSession {
     }
     for (const tool of tools) {
       if (tool.handler) {
-        this.toolHandlers.set(tool.name, tool.handler);
+        const handler = tool.handler;
+        if (tool.name === "apply_patch" && tool.overridesBuiltInTool && toJsonSchema(tool.parameters)?.type === "string") {
+          this.toolHandlers.set(tool.name, (args, invocation) => {
+            if (typeof args === "string") {
+              return handler(args, invocation);
+            }
+            if (typeof args === "object" && args !== null && "input" in args && typeof args.input === "string") {
+              return handler(args.input, invocation);
+            }
+            throw new TypeError("apply_patch string override requires a string input");
+          });
+        } else {
+          this.toolHandlers.set(tool.name, handler);
+        }
       }
     }
   }
@@ -1557,6 +1586,68 @@ class CopilotSession {
   registerUserInputHandler(handler) {
     this.userInputHandler = handler;
   }
+  /**
+   * Registers the session's skill provider.
+   *
+   * @param provider - The skill provider, or undefined to remove it
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerSkillProvider(provider) {
+    this.skillProvider = provider;
+  }
+  /**
+   * Handles a `skillProvider.list` request from the runtime.
+   *
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSkillProviderList(token) {
+    const provider = this.requireSkillProvider();
+    return await this.callSkillProvider("listSkills", token, async (options) => ({
+      skills: await provider.listSkills(options) ?? []
+    }));
+  }
+  /**
+   * Handles a `skillProvider.read` request from the runtime.
+   *
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSkillProviderRead(name, token) {
+    const provider = this.requireSkillProvider();
+    return await this.callSkillProvider("readSkill", token, async (options) => ({
+      markdown: await provider.readSkill(name, options) ?? null
+    }));
+  }
+  requireSkillProvider() {
+    if (!this.skillProvider) {
+      throw new Error(`No skill provider for session: ${this.sessionId}`);
+    }
+    return this.skillProvider;
+  }
+  /**
+   * Runs a provider call with an abort signal tied to the runtime's request
+   * cancellation. Failures are logged locally and reported generically.
+   */
+  async callSkillProvider(operation, token, call) {
+    const controller = new AbortController();
+    const subscription = token?.onCancellationRequested(() => controller.abort());
+    if (token?.isCancellationRequested) {
+      controller.abort();
+    }
+    try {
+      return await call({ signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new ResponseError(-32800, `Skill provider ${operation} cancelled`);
+      }
+      console.error(`Skill provider ${operation} failed`, {
+        sessionId: this.sessionId,
+        error
+      });
+      throw skillProviderFailure(operation);
+    } finally {
+      subscription?.dispose();
+    }
+  }
   /**
    * Registers hook handlers for session lifecycle events.
    *
@@ -1646,7 +1737,9 @@ class CopilotSession {
       sessionStart: this.hooks.onSessionStart,
       sessionEnd: this.hooks.onSessionEnd,
       errorOccurred: this.hooks.onErrorOccurred,
-      agentStop: this.hooks.onAgentStop
+      agentStop: this.hooks.onAgentStop,
+      subagentStart: this.hooks.onSubagentStart,
+      subagentStop: this.hooks.onSubagentStop
     };
     const handler = handlerMap[hookType];
     if (!handler) {
@@ -1810,6 +1903,59 @@ class CopilotSession {
   async setAutoTier(autoTier) {
     return await this.rpc.model.switchAutoTier({ autoTier });
   }
+  /**
+   * Replace the tools this client supplies to the session.
+   *
+   * `tools` becomes the complete set of tools this client implements,
+   * replacing the ones it supplied when the session was created or resumed,
+   * or in an earlier call. Built-in, MCP, and plugin tools, and tools other
+   * connected clients supply, are unaffected. Pass an empty array to remove
+   * all of this client's tools.
+   *
+   * Tools are defined the same way as for `createSession`: calls to tools
+   * with a `handler` are dispatched to it, and tools without one are
+   * declaration-only. Once the runtime accepts the replacement, every tool
+   * call this session dispatches uses the new handlers; calls already
+   * running finish on their original handlers. If the runtime rejects the
+   * replacement, this rejects and the previous tools and handlers stay in
+   * place. Concurrent calls on the same session are applied one at a time,
+   * in the order they are made.
+   *
+   * The agent sees the new tools from its next model request, which can fall
+   * within a turn in progress. A model request already in flight was made
+   * with the previous tools, so the agent can still call a tool you removed.
+   * This session doesn't answer that call, and it can stay pending until the
+   * turn is aborted. If a running turn might still call a tool you remove,
+   * replace tools while the session is idle.
+   *
+   * @param tools - The complete set of tools this client supplies
+   *
+   * @experimental Wraps the experimental `session.tools.set` RPC and may change
+   * or be removed in a future release.
+   *
+   * @example
+   * ```typescript
+   * await session.setTools([
+   *     defineTool("search_issues", {
+   *         description: "Search the issues shown on the current page",
+   *         parameters: z.object({ query: z.string() }),
+   *         handler: async ({ query }) => searchIssues(query),
+   *     }),
+   * ]);
+   * ```
+   */
+  async setTools(tools) {
+    const definitions = tools.map(toToolDefinition);
+    const replacement = this.setToolsQueue.then(async () => {
+      await this.rpc.tools.set({ tools: definitions });
+      this.registerTools(tools);
+    });
+    this.setToolsQueue = replacement.then(
+      () => void 0,
+      () => void 0
+    );
+    await replacement;
+  }
   /**
    * Log a message to the session timeline.
    * The message appears in the session event stream and is visible to SDK consumers
@@ -1855,6 +2001,9 @@ function toCanvasRpcError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new ResponseError(ErrorCodes.InternalError, message, { code, message });
 }
+function skillProviderFailure(operation) {
+  return new ResponseError(ErrorCodes.InternalError, `Skill provider ${operation} failed`);
+}
 function strictJsonValidationError(context, category, message, path) {
   return new ResponseError(ErrorCodes.InternalError, message, {
     code: context.code,

package/dist/sessionFsProvider.d.ts

@@ -37,6 +37,10 @@ export declare class SessionFsSqliteTransactionFailure extends Error {
     readonly errorClass: SessionFsSqliteTransactionErrorClass;
     constructor(message: string, errorClass?: SessionFsSqliteTransactionErrorClass);
 }
+/** Throw from `writeFile` only when the provider changed the target before failing. */
+export declare class SessionFsWriteFailure extends Error {
+    readonly writeChanged = true;
+}
 /**
  * SQLite operations for the per-session database.
  * Implementers provide query execution and existence checking.
@@ -78,7 +82,11 @@ export interface SessionFsSqliteProvider {
 export interface SessionFsProvider {
     /** Reads the full content of a file. Throw if the file does not exist. */
     readFile(path: string): Promise<string>;
-    /** Writes content to a file, creating parent directories if needed. */
+    /** Read exact file bytes. Required when capabilities.binary is enabled. */
+    readFileBytes?(path: string): Promise<Uint8Array>;
+    /** Write exact file bytes. Required when capabilities.binary is enabled. */
+    writeFileBytes?(path: string, content: Uint8Array, mode?: number): Promise<void>;
+    /** Writes content to a file, creating parent directories if needed. Throw {@link SessionFsWriteFailure} if a failed write changed the target. */
     writeFile(path: string, content: string, mode?: number): Promise<void>;
     /** Appends content to a file, creating parent directories if needed. */
     appendFile(path: string, content: string, mode?: number): Promise<void>;

package/dist/sessionFsProvider.js

@@ -1,3 +1,5 @@
+const MAX_BINARY_BYTES = (64 * 1024 * 1024 - 1024) / 4 * 3;
+const MAX_BINARY_CONTENT_LENGTH = Math.ceil(MAX_BINARY_BYTES / 3) * 4;
 class SessionFsSqliteTransactionFailure extends Error {
   /** Failure classification reported to the runtime. */
   errorClass;
@@ -7,6 +9,9 @@ class SessionFsSqliteTransactionFailure extends Error {
     this.errorClass = errorClass;
   }
 }
+class SessionFsWriteFailure extends Error {
+  writeChanged = true;
+}
 function normalizeSqliteParams(params) {
   if (!params) {
     return void 0;
@@ -29,10 +34,60 @@ function createSessionFsAdapter(provider) {
         return { content: "", error: toSessionFsError(err) };
       }
     },
+    readFileBytes: async ({ path }) => {
+      if (!provider.readFileBytes) {
+        return {
+          content: "",
+          error: { code: "UNKNOWN", message: "Binary reads are not supported" }
+        };
+      }
+      try {
+        const bytes = await provider.readFileBytes(path);
+        if (bytes.length > MAX_BINARY_BYTES) {
+          return {
+            content: "",
+            error: {
+              code: "UNKNOWN",
+              message: "sessionFs.readFileBytes content exceeds the binary read limit"
+            }
+          };
+        }
+        return {
+          content: Buffer.from(bytes).toString("base64")
+        };
+      } catch (err) {
+        return { content: "", error: toSessionFsError(err) };
+      }
+    },
     writeFile: async ({ path, content, mode }) => {
       try {
         await provider.writeFile(path, content, mode);
         return void 0;
+      } catch (err) {
+        const error = toSessionFsError(err);
+        return err instanceof SessionFsWriteFailure ? { ...error, writeChanged: true } : error;
+      }
+    },
+    writeFileBytes: async ({ path, content, mode }) => {
+      if (!provider.writeFileBytes) {
+        return { code: "UNKNOWN", message: "Binary writes are not supported" };
+      }
+      if (content.length > MAX_BINARY_CONTENT_LENGTH) {
+        return {
+          code: "UNKNOWN",
+          message: "sessionFs.writeFileBytes content exceeds the binary write limit"
+        };
+      }
+      const bytes = Buffer.from(content, "base64");
+      if (bytes.toString("base64") !== content || bytes.length > MAX_BINARY_BYTES) {
+        return {
+          code: "UNKNOWN",
+          message: "invalid sessionFs.writeFileBytes base64 content"
+        };
+      }
+      try {
+        await provider.writeFileBytes(path, bytes, mode);
+        return void 0;
       } catch (err) {
         return toSessionFsError(err);
       }
@@ -169,5 +224,6 @@ function toSqliteTransactionError(err) {
 }
 export {
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   createSessionFsAdapter
 };

package/dist/types.d.ts

@@ -48,7 +48,10 @@ export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
 export type { SessionFsSqliteStatement } from "./sessionFsProvider.js";
 export type { SessionFsSqliteTransactionErrorClass } from "./sessionFsProvider.js";
 export { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
+export { SessionFsWriteFailure } from "./sessionFsProvider.js";
 export type { LlmInferenceHeaders } from "./generated/rpc.js";
+import type { SkillProviderDescriptor } from "./generated/rpc.js";
+export type { SkillProviderDescriptor };
 export type { PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSurface, PermissionResponseCapability, } from "./generated/rpc.js";
 export type { PermissionDecisionSource } from "./generated/session-events.js";
 export type { CopilotRequestContext } from "./copilotRequestHandler.js";
@@ -922,6 +925,8 @@ export interface SystemMessageReplaceConfig {
 /**
  * Customize mode: Override individual sections of the system prompt.
  * Keeps the SDK-managed prompt structure while allowing targeted modifications.
+ * The `last_instructions` section includes configured subagent-model guidance.
+ * Its overrides and transforms control that prose, not runtime model selection or tool availability.
  */
 export interface SystemMessageCustomizeConfig {
     mode: "customize";
@@ -1098,8 +1103,9 @@ export type AutoModeSwitchHandler = (request: AutoModeSwitchRequest, invocation:
  * Base interface for all hook inputs
  */
 export interface BaseHookInput {
-    /** The runtime session ID of the session that triggered the hook.
-     * For sub-agent hooks this differs from `invocation.sessionId`. */
+    /** The runtime session ID associated with the hook. Child tool hooks use
+     * the child session ID; sub-agent lifecycle hooks use the parent session ID,
+     * matching `invocation.sessionId`. */
     sessionId: string;
     /** Time at which the hook event was emitted by the runtime. */
     timestamp: Date;
@@ -1366,6 +1372,54 @@ export interface AgentStopHookOutput {
 export type AgentStopHandler = (input: AgentStopHookInput, invocation: {
     sessionId: string;
 }) => Promise<AgentStopHookOutput | void> | AgentStopHookOutput | void;
+/**
+ * Input for the hook fired before a sub-agent's first turn.
+ *
+ * The session metadata belongs to the parent session, not the child.
+ */
+export interface SubagentStartHookInput extends BaseHookInput {
+    transcriptPath: string;
+    agentName: string;
+    agentDisplayName?: string;
+    agentDescription?: string;
+}
+/** Output for the sub-agent start hook. Context is prepended to the child's initial prompt. */
+export interface SubagentStartHookOutput {
+    additionalContext?: string;
+}
+/** Handler for the sub-agent start hook. */
+export type SubagentStartHandler = (input: SubagentStartHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SubagentStartHookOutput | void> | SubagentStartHookOutput | void;
+/**
+ * Input for the hook fired after a sub-agent completes a turn.
+ *
+ * The response is the child's last assistant message before any hook rewrite.
+ */
+export interface SubagentStopHookInput extends SubagentStartHookInput {
+    agentId?: string;
+    agentType: string;
+    stopReason: "end_turn";
+    response: string;
+}
+/**
+ * Output for the sub-agent stop hook. `"block"` with a nonempty `reason` continues
+ * the child; otherwise `modifiedResponse` replaces the response reported to the parent.
+ * When both are supplied, a valid block takes precedence over the rewrite.
+ */
+export type SubagentStopHookOutput = {
+    decision: "block";
+    reason: string;
+    modifiedResponse?: string;
+} | {
+    decision?: "allow";
+    reason?: never;
+    modifiedResponse?: string;
+};
+/** Handler for the sub-agent stop hook. */
+export type SubagentStopHandler = (input: SubagentStopHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SubagentStopHookOutput | void> | SubagentStopHookOutput | void;
 /**
  * Configuration for session hooks
  */
@@ -1422,6 +1476,13 @@ export interface SessionHooks {
      * agent stop.
      */
     onAgentStop?: AgentStopHandler;
+    /** Called before a sub-agent's first turn. Return context to prepend to its prompt. */
+    onSubagentStart?: SubagentStartHandler;
+    /**
+     * Called after a sub-agent completes a turn. Return a block reason to
+     * continue the child, or a replacement response to report to the parent.
+     */
+    onSubagentStop?: SubagentStopHandler;
 }
 /**
  * Base interface for MCP server configuration.
@@ -1821,6 +1882,13 @@ export interface ManagedSettingsPermissions {
      * (across managed layers) must admit an operation for it to be allowed.
      */
     allow?: string[];
+    /**
+     * Closed-world host boundary expressed as `Domain(hostname)`, `Domain(IP)`,
+     * or `Domain(*.example.com)` rules. Schemes, ports, paths, queries, and
+     * fragments are rejected. Multiple managed layers intersect their lists;
+     * an empty list denies all hosts.
+     */
+    limitTo?: string[];
 }
 /**
  * Host-injected enterprise managed settings. The first supported contract is
@@ -1834,6 +1902,57 @@ export interface ManagedSettings {
 }
 /** Selects the model-facing shape of the built-in `ask_user` tool. */
 export type AskUserVariant = "legacy" | "elicitation";
+/**
+ * Supplies session-scoped skills from the host's own storage, such as a
+ * database, instead of `SKILL.md` files on disk.
+ *
+ * The runtime calls {@link SkillProvider.listSkills} when it builds the
+ * session's skill catalog, and {@link SkillProvider.readSkill} each time it
+ * needs a skill's instructions: when the model loads the skill through the
+ * `skill` tool, when a user runs `/skill-name`, or when a custom agent lists
+ * the skill. Calls may run concurrently, including on behalf of sub-agents, and
+ * each call must finish within 30 seconds. Errors thrown by a provider are
+ * never shown to the model.
+ *
+ * Supply a provider with {@link SessionConfigBase.skillProvider}. Providers
+ * aren't supported for cloud sessions.
+ *
+ * @experimental Session-scoped skill providers are experimental and may change
+ * or be removed in future SDK or CLI releases.
+ */
+export interface SkillProvider {
+    /**
+     * Returns catalog metadata for every skill the provider supplies. The
+     * descriptors are authoritative: names must be unique ignoring case, and
+     * the runtime validates their limits.
+     */
+    listSkills(options: SkillProviderCallOptions): SkillProviderDescriptor[] | Promise<SkillProviderDescriptor[]>;
+    /**
+     * Returns the `SKILL.md` text for the named skill, or `null`/`undefined`
+     * when the skill no longer exists.
+     *
+     * YAML frontmatter is optional. Fields it omits come from the skill's
+     * descriptor, fields it declares must match the descriptor, and
+     * `allowed-tools` can only be set there. Text whose first line is `---` is
+     * parsed as frontmatter.
+     *
+     * @param name - The skill's name, as listed by {@link SkillProvider.listSkills}.
+     */
+    readSkill(name: string, options: SkillProviderCallOptions): string | null | undefined | Promise<string | null | undefined>;
+}
+/**
+ * Per-call options passed to {@link SkillProvider} methods.
+ *
+ * @experimental Session-scoped skill providers are experimental and may change
+ * or be removed in future SDK or CLI releases.
+ */
+export interface SkillProviderCallOptions {
+    /**
+     * Aborted when the runtime cancels the call, for example when it times out
+     * or the session disconnects. The runtime ignores any later result.
+     */
+    signal: AbortSignal;
+}
 /**
  * Shared configuration fields used by both {@link SessionConfig} (for
  * creating a new session) and {@link ResumeSessionConfig} (for resuming
@@ -2253,6 +2372,22 @@ export interface SessionConfigBase {
      * Directories to load skills from.
      */
     skillDirectories?: string[];
+    /**
+     * Supplies skills from the host's own storage instead of `SKILL.md` files on
+     * disk. Provider skills join the session's skill catalog alongside file-based
+     * skills. See {@link SkillProvider}.
+     *
+     * Supplying a provider enables skills unless `enableSkills` is set explicitly,
+     * so set `enableSkills: true` when the client runs in `"empty"` mode. With
+     * `enableSkills: false` the provider stays bound but receives no calls.
+     *
+     * The provider isn't persisted. Pass it again when resuming the session;
+     * resuming without one removes the provider's skills.
+     *
+     * @experimental Session-scoped skill providers are experimental and may change
+     * or be removed in future SDK or CLI releases.
+     */
+    skillProvider?: SkillProvider;
     /**
      * Local filesystem paths to Open Plugins-format directories
      * (https://open-plugins.com/) to load for this session.
@@ -2522,6 +2657,12 @@ export interface ProviderTokenArgs {
  * surface and may change or be removed in future SDK or CLI releases.
  */
 export type BearerTokenProvider = (args: ProviderTokenArgs) => Promise<string>;
+/**
+ * Product serving a configured provider's model. Allowed values are
+ * "openai", "anthropic", "azure_openai", "ollama", "lm_studio",
+ * "foundry_local", and "llama_cpp".
+ */
+export type ProviderConfigModelProvider = "openai" | "anthropic" | "azure_openai" | "ollama" | "lm_studio" | "foundry_local" | "llama_cpp";
 /**
  * Configuration for a custom API provider.
  */
@@ -2544,6 +2685,11 @@ export interface ProviderConfig {
      * providers using `wireApi: "responses"`.
      */
     transport?: "http" | "websockets";
+    /**
+     * Product serving the model, such as "ollama" or "lm_studio", reported in
+     * telemetry as `model_provider`. Only affects telemetry.
+     */
+    modelProvider?: ProviderConfigModelProvider;
     /**
      * API endpoint URL
      */
@@ -2637,6 +2783,11 @@ export interface NamedProviderConfig {
      * Wire API format (openai/azure only). Defaults to "completions".
      */
     wireApi?: "completions" | "responses";
+    /**
+     * Product serving this provider's models, such as "ollama" or "lm_studio",
+     * reported in telemetry as `model_provider`. Only affects telemetry.
+     */
+    modelProvider?: ProviderConfigModelProvider;
     /**
      * API endpoint URL.
      */
@@ -2878,6 +3029,12 @@ export interface SessionFsConfig {
          * @default false
          */
         sqlite?: boolean;
+        /**
+         * Whether this provider supports exact binary reads and writes through readFileBytes and writeFileBytes.
+         * Required to view images stored only in the provider.
+         * @default false
+         */
+        binary?: boolean;
     };
 }
 /**

package/dist/types.js

@@ -1,5 +1,6 @@
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
 import { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
+import { SessionFsWriteFailure } from "./sessionFsProvider.js";
 import {
   CopilotRequestHandler,
   CopilotWebSocketHandler,
@@ -106,10 +107,10 @@ const SYSTEM_MESSAGE_SECTIONS = {
   tool_instructions: { description: "Per-tool usage instructions" },
   custom_instructions: { description: "Repository and organization custom instructions" },
   runtime_instructions: {
-    description: "Runtime-provided context and instructions (e.g. system notifications, memories, workspace context, mode-specific instructions, content-exclusion policy)"
+    description: "Runtime-provided system-prompt context and instructions, such as system notifications, memories, workspace context, and content-exclusion policy. Mode-specific instructions can travel in transition messages instead."
   },
   last_instructions: {
-    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
+    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion, and configured subagent-model guidance when the task tool is available"
   }
 };
 function isAttributedPermissionResult(result) {
@@ -149,6 +150,7 @@ export {
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   approveAll,
   convertMcpCallToolResult,
   createAttributedPermissionResult,

package/docs/agent-author.md

@@ -122,10 +122,12 @@ hooks: {
     onSessionStart: async (input, invocation) => { ... },
     onSessionEnd: async (input, invocation) => { ... },
     onErrorOccurred: async (input, invocation) => { ... },
+    onSubagentStart: async (input, invocation) => { ... },
+    onSubagentStop: async (input, invocation) => { ... },
 }
 ```
 
-All hook inputs include `timestamp` (`Date`) and `workingDirectory`.
+All hook inputs include `sessionId`, `timestamp` (`Date`) and `workingDirectory`.
 All handlers receive `invocation: { sessionId: string }` as the second argument.
 All handlers may return `void`/`undefined` (no-op) or an output object.
 
@@ -214,7 +216,32 @@ fire it.
 | `retryCount` | `number` | Max retries (when errorHandling is "retry") |
 | `userNotification` | `string` | Message shown to the user |
 
----
+### onSubagentStart
+
+Fires before a sub-agent's first turn. The input's `sessionId` and the
+invocation's `sessionId` identify the parent session, not the child.
+
+**Input:** `{ sessionId: string, transcriptPath: string, agentName: string, agentDisplayName?: string, agentDescription?: string, timestamp, workingDirectory }`
+
+**Output (optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `additionalContext` | `string` | Prepended to the child's initial prompt |
+
+### onSubagentStop
+
+Fires after a sub-agent completes a turn. The input includes the child's last
+assistant `response` and the parent's session metadata. `agentId` is available
+when the task registry supplies one. This is distinct from `onAgentStop`, which
+only runs for the top-level agent.
+
+**Input:** `{ sessionId: string, transcriptPath: string, agentName: string, agentDisplayName?: string, agentDescription?: string, agentId?: string, agentType: string, stopReason: "end_turn", response: string, timestamp, workingDirectory }`
+
+**Output (choose one, or return nothing):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `decision` and `reason` | `"block"` and `string` | Continue the child for another turn using `reason` |
+| `modifiedResponse` | `string` | Replace the child's response reported to the parent |
 
 ## Session Object
 

package/package.json

@@ -5,8 +5,8 @@
         "url": "https://github.com/github/copilot-agent-runtime.git",
         "directory": "src/sdk/nodejs"
     },
-    "version": "1.0.17-preview.0",
-    "copilotCliVersion": "1.0.92-0",
+    "version": "1.0.17-preview.10",
+    "copilotCliVersion": "1.0.93-4",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -98,22 +98,23 @@
     },
     "files": [
         "dist/**/*",
+        "!dist/tsconfig.tsbuildinfo",
         "docs/**/*",
         "README.md"
     ],
     "copilotRuntime": {
-        "sourceSha": "9e1fdbf2c78159c5f2c7c85d073c3207c27ac0a2",
-        "version": "1.0.92-0",
+        "sourceSha": "0e56b9a0033f48e4358ee027a4077cd6ebd61f32",
+        "version": "1.0.93-4",
         "visibility": "public"
     },
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.17-preview.0",
-        "@github/copilot-sdk-darwin-x64": "1.0.17-preview.0",
-        "@github/copilot-sdk-linux-arm64": "1.0.17-preview.0",
-        "@github/copilot-sdk-linux-x64": "1.0.17-preview.0",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.17-preview.0",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.17-preview.0",
-        "@github/copilot-sdk-win32-arm64": "1.0.17-preview.0",
-        "@github/copilot-sdk-win32-x64": "1.0.17-preview.0"
+        "@github/copilot-sdk-darwin-arm64": "1.0.17-preview.10",
+        "@github/copilot-sdk-darwin-x64": "1.0.17-preview.10",
+        "@github/copilot-sdk-linux-arm64": "1.0.17-preview.10",
+        "@github/copilot-sdk-linux-x64": "1.0.17-preview.10",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.17-preview.10",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.17-preview.10",
+        "@github/copilot-sdk-win32-arm64": "1.0.17-preview.10",
+        "@github/copilot-sdk-win32-x64": "1.0.17-preview.10"
     }
 }