@github/copilot-sdk 1.0.0-beta.8 → 1.0.0

package/dist/types.d.ts

@@ -3,12 +3,14 @@
  */
 import type { Canvas } from "./canvas.js";
 import type { SessionFsProvider } from "./sessionFsProvider.js";
-import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { ReasoningSummary, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 import type { RemoteSessionMode } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
+import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type SessionEvent = GeneratedSessionEvent;
+export type { ReasoningSummary } from "./generated/session-events.js";
 export type { SessionFsProvider } from "./sessionFsProvider.js";
 export { createSessionFsAdapter } from "./sessionFsProvider.js";
 export type { SessionFsFileInfo } from "./sessionFsProvider.js";
@@ -128,12 +130,38 @@ export declare const RuntimeConnection: {
         connectionToken?: string;
     }) => UriRuntimeConnection;
 };
+/**
+ * Controls SDK defaults for ambient features.
+ *
+ * - `"copilot-cli"` (default): Defaults equivalent to Copilot CLI. Useful when
+ *   building a coding agent that shares sessions with Copilot CLI. Do not use
+ *   this mode for server-based multi-user applications — the default coding
+ *   agent has tools and capabilities that operate across sessions and can
+ *   access the host OS environment.
+ * - `"empty"`: Disables optional features by default. The app must explicitly
+ *   opt into anything it needs. Required for any scenario where CLI-like
+ *   ambient behavior is unsafe (e.g. multi-user servers).
+ */
+export type CopilotClientMode = "empty" | "copilot-cli";
 export interface CopilotClientOptions {
     /**
      * How to connect to the Copilot runtime. When omitted, defaults to
      * {@link RuntimeConnection.forStdio} with the bundled runtime.
      */
     connection?: RuntimeConnection;
+    /**
+     * Selects the SDK defaulting strategy. See {@link CopilotClientMode}.
+     *
+     * When set to `"empty"`, the SDK validates that the app has supplied the
+     * required configuration ({@link CopilotClientOptions.baseDirectory} or
+     * {@link CopilotClientOptions.sessionFs}, plus
+     * {@link SessionConfigBase.availableTools} on each session) and translates
+     * session creation requests into runtime options that flip tool filter
+     * precedence to deny-wins so exclusions are expressible.
+     *
+     * @default "copilot-cli"
+     */
+    mode?: CopilotClientMode;
     /**
      * Working directory for the runtime process.
      * If not set, inherits the current process's working directory.
@@ -391,6 +419,17 @@ export interface SessionCapabilities {
     ui?: {
         /** Whether the host supports interactive elicitation dialogs. */
         elicitation?: boolean;
+        /**
+         * Whether the runtime has accepted the session's MCP Apps (SEP-1865)
+         * opt-in. `true` when the consumer set `enableMcpApps: true` on
+         * create/resume **and** the runtime's `MCP_APPS` feature flag (or
+         * `COPILOT_MCP_APPS=true` env override) is on. Otherwise absent or
+         * `false`, indicating the runtime silently dropped the opt-in.
+         *
+         * @experimental This property is part of an experimental wire-protocol surface
+         * (SEP-1865) and may change or be removed in a future release.
+         */
+        mcpApps?: boolean;
         /** Whether the host supports canvas rendering. */
         canvases?: boolean;
     };
@@ -849,6 +888,47 @@ export interface PostToolUseHookOutput {
 export type PostToolUseHandler = (input: PostToolUseHookInput, invocation: {
     sessionId: string;
 }) => Promise<PostToolUseHookOutput | void> | PostToolUseHookOutput | void;
+/**
+ * Input for post-tool-use-failure hook.
+ *
+ * Dispatched after a tool execution whose `resultType` is `"failure"`.
+ * The input differs from {@link PostToolUseHookInput}: the host CLI does not
+ * forward the full `ToolResultObject` to failure hooks — only `error`, the
+ * stringified failure message extracted from the tool's result, is provided.
+ */
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+    toolName: string;
+    toolArgs: unknown;
+    /**
+     * Failure message from the tool's result (the `error` field of the
+     * underlying `ToolResultObject`, falling back to its text/log fields).
+     */
+    error: string;
+}
+/**
+ * Output for post-tool-use-failure hook.
+ *
+ * Only `additionalContext` is consumed by the host CLI — it is appended as
+ * hidden guidance to the model alongside the failed tool result. Other fields
+ * such as `modifiedResult` or `suppressOutput` are not honored for failure
+ * hooks (see {@link PostToolUseHookOutput} for the success-only hook).
+ */
+export interface PostToolUseFailureHookOutput {
+    additionalContext?: string;
+}
+/**
+ * Handler for post-tool-use-failure hook.
+ *
+ * Fires after a tool execution whose result was `"failure"`. `onPostToolUse`
+ * only fires for successful results, so register this handler to observe or
+ * react to failed tool outcomes.
+ *
+ * Note: `"rejected"`, `"denied"`, and `"timeout"` results do not currently
+ * trigger this hook either — only `"failure"` does.
+ */
+export type PostToolUseFailureHandler = (input: PostToolUseFailureHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PostToolUseFailureHookOutput | void> | PostToolUseFailureHookOutput | void;
 /**
  * Input for user-prompt-submitted hook
  */
@@ -947,9 +1027,20 @@ export interface SessionHooks {
      */
     onPreMcpToolCall?: PreMcpToolCallHandler;
     /**
-     * Called after a tool is executed
+     * Called after a tool is executed with a successful result.
+     *
+     * For failed tool executions, register {@link onPostToolUseFailure} instead;
+     * this handler does not fire for non-success results.
      */
     onPostToolUse?: PostToolUseHandler;
+    /**
+     * Called after a tool execution whose result was `"failure"`.
+     *
+     * Register this handler alongside {@link onPostToolUse} to observe failed
+     * tool calls — `onPostToolUse` only fires for successful results, so
+     * without this hook failed tool calls are invisible to extensions.
+     */
+    onPostToolUseFailure?: PostToolUseFailureHandler;
     /**
      * Called when the user submits a prompt
      */
@@ -1108,10 +1199,38 @@ export interface InfiniteSessionConfig {
      */
     bufferExhaustionThreshold?: number;
 }
+/**
+ * Configuration for handling large tool outputs.
+ *
+ * When a tool produces output exceeding the configured size, the output is
+ * written to a temp file and a reference is returned to the model instead of
+ * the full payload.
+ */
+export interface LargeToolOutputConfig {
+    /**
+     * Whether large output handling is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum size in bytes before output is written to a temp file.
+     * @default 51200
+     */
+    maxSizeBytes?: number;
+    /**
+     * Directory to write temp files to. Defaults to the OS temp directory.
+     */
+    outputDirectory?: string;
+}
 /**
  * Valid reasoning effort levels for models that support it.
  */
 export type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
+/**
+ * Context window tier for the session. "long_context" pins the session to the
+ * long-context tier when the selected model supports it.
+ */
+export type ContextTier = "default" | "long_context";
 /**
  * Stable extension identity for session participants that provide canvases.
  */
@@ -1142,13 +1261,30 @@ export interface SessionConfigBase {
      * Use client.listModels() to check supported values for each model.
      */
     reasoningEffort?: ReasoningEffort;
+    /**
+     * Reasoning summary mode for models that support configurable reasoning summaries.
+     * Use "none" to suppress summary output regardless of whether reasoning is enabled.
+     */
+    reasoningSummary?: ReasoningSummary;
+    /**
+     * Context window tier for models that support it. Use "long_context" to pin
+     * the session to the long-context tier; omit or use "default" otherwise.
+     */
+    contextTier?: ContextTier;
     /** Per-property overrides for model capabilities, deep-merged over runtime defaults. */
     modelCapabilities?: ModelCapabilitiesOverride;
+    /**
+     * Configuration for handling large tool outputs. When a tool produces
+     * output exceeding the configured size, the output is written to a temp
+     * file and a reference is returned to the model instead of the full
+     * payload.
+     */
+    largeOutput?: LargeToolOutputConfig;
     /**
      * Override the default configuration directory location.
      * When specified, the session will use this directory for storing config and state.
      */
-    configDir?: string;
+    configDirectory?: string;
     /**
      * When true, automatically discovers MCP server configurations (e.g. `.mcp.json`,
      * `.vscode/mcp.json`) and skill directories from the working directory and merges
@@ -1188,6 +1324,19 @@ export interface SessionConfigBase {
      * stay clean.
      */
     requestExtensions?: boolean;
+    /**
+     * Optional override path to a `copilot-sdk/` folder to inject into
+     * extension subprocesses for this session in place of the bundled SDK.
+     * When unset or invalid (missing folder or missing `index.js` /
+     * `extension.js`), the runtime falls back to the bundled SDK without
+     * throwing. Takes precedence over any server-level default.
+     *
+     * Only honored on session create and resume — extensions joining via
+     * `joinSession` cannot override the SDK path, because the extension
+     * subprocess has already been forked by the host with the SDK the host
+     * chose. `JoinSessionConfig` omits this field for that reason.
+     */
+    extensionSdkPath?: string;
     /**
      * Stable extension identity for canvas providers on this connection. When
      * set, the runtime uses `${source}:${name}` as the agent-facing extension
@@ -1207,14 +1356,25 @@ export interface SessionConfigBase {
     systemMessage?: SystemMessageConfig;
     /**
      * List of tool names to allow. When specified, only these tools will be available.
-     * Takes precedence over excludedTools.
+     *
+     * Supports source-qualified filter patterns (`builtin:*`, `builtin:<name>`,
+     * `mcp:*`, `mcp:<name>`, `custom:*`, `custom:<name>`) as well as the bare
+     * name form (exact match across any source). Build this list with
+     * {@link ToolSet} for type safety and readable intent.
+     *
+     * Composes with {@link excludedTools}: a tool is enabled when it matches
+     * `availableTools` (or `availableTools` is unset) AND it does not match
+     * `excludedTools`. This lets you express "everything matching X except Y".
      */
-    availableTools?: string[];
+    availableTools?: string[] | ToolSet;
     /**
-     * List of tool names to disable. All other tools remain available.
-     * Ignored if availableTools is specified.
+     * List of tool names to disable. Supports the same pattern syntax as
+     * {@link availableTools}.
+     *
+     * Always takes precedence over {@link availableTools}: a tool listed here
+     * is disabled even if it also matches `availableTools`.
      */
-    excludedTools?: string[];
+    excludedTools?: string[] | ToolSet;
     /**
      * Custom provider configuration (BYOK - Bring Your Own Key).
      * When specified, uses the provided API endpoint instead of the Copilot API.
@@ -1229,6 +1389,39 @@ export interface SessionConfigBase {
      * This is independent of the OpenTelemetry configuration in {@link CopilotClientOptions.telemetry}.
      */
     enableSessionTelemetry?: boolean;
+    /**
+     * When true, the runtime skips loading custom-instruction sources
+     * (e.g. `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`).
+     *
+     * Defaults to `false` (custom instructions are loaded). Under
+     * {@link CopilotClientOptions.mode} = `"empty"`, defaults to `true`; apps
+     * can pass `false` here to opt back in.
+     */
+    skipCustomInstructions?: boolean;
+    /**
+     * When true, custom agents default to local-only execution and are not
+     * dispatched to remote workers.
+     *
+     * Defaults to `false`. Under {@link CopilotClientOptions.mode} = `"empty"`,
+     * defaults to `true`; apps can pass `false` here to opt back in.
+     */
+    customAgentsLocalOnly?: boolean;
+    /**
+     * When true, the runtime instructs the agent to include a `Co-authored-by`
+     * trailer in commit messages it composes.
+     *
+     * Defaults to `true`. Under {@link CopilotClientOptions.mode} = `"empty"`,
+     * defaults to `false`; apps can pass `true` here to opt back in.
+     */
+    coauthorEnabled?: boolean;
+    /**
+     * When true, the `manage_schedule` tool is exposed to the agent.
+     *
+     * Defaults to whatever the runtime exposes (typically gated to staff
+     * users). Under {@link CopilotClientOptions.mode} = `"empty"`, defaults to
+     * `false`; apps can pass `true` here to opt back in.
+     */
+    manageScheduleEnabled?: boolean;
     /**
      * Optional handler for permission requests from the server.
      * When omitted, permission requests are surfaced as events and left pending for
@@ -1246,6 +1439,33 @@ export interface SessionConfigBase {
      * Also enables the `elicitation` capability on the session.
      */
     onElicitationRequest?: ElicitationHandler;
+    /**
+     * Enable MCP Apps (SEP-1865) UI passthrough on this session.
+     *
+     * When `true` **and** the runtime has MCP Apps enabled (via the
+     * `MCP_APPS` feature flag or `COPILOT_MCP_APPS=true` environment
+     * override), the runtime adds the `mcp-apps` capability to the session,
+     * which causes it to advertise the `extensions.io.modelcontextprotocol/ui`
+     * extension to MCP servers (so they expose `_meta.ui.resourceUri` on
+     * tools) and to expose the `session.rpc.mcp.apps.{listTools,callTool,
+     * readResource,setHostContext,getHostContext,diagnose}` JSON-RPC methods.
+     *
+     * If the runtime gate is off, the opt-in is silently dropped server-side
+     * (the runtime logs a warning); the session is created normally but the
+     * MCP Apps surface is unavailable. Inspect the runtime's
+     * `capabilities.ui.mcpApps` on the create/resume response to detect this.
+     *
+     * SDK consumers MUST set this to `true` only when they have an iframe
+     * renderer that can display `ui://` MCP App bundles. Setting it without a
+     * renderer will cause MCP servers to register UI-enabled tool variants
+     * the consumer cannot display.
+     *
+     * @experimental This option is part of an experimental wire-protocol surface
+     * (SEP-1865) and may change or be removed in a future release.
+     *
+     * @default false
+     */
+    enableMcpApps?: boolean;
     /**
      * Handler for exit-plan-mode requests from the agent.
      * When provided, enables `exitPlanMode.request` callbacks.
@@ -1284,6 +1504,14 @@ export interface SessionConfigBase {
      * @default true
      */
     includeSubAgentStreamingEvents?: boolean;
+    /**
+     * Controls how MCP OAuth tokens are stored for this session.
+     * - `"persistent"` — tokens are stored in the OS keychain (shared across sessions)
+     * - `"in-memory"` — tokens are stored in memory and discarded when the session ends
+     *
+     * @default "in-memory"
+     */
+    mcpOAuthTokenStorage?: "persistent" | "in-memory";
     /**
      * MCP server configurations for the session.
      * Keys are server names, values are server configurations.
@@ -1310,6 +1538,20 @@ export interface SessionConfigBase {
      * Directories to load skills from.
      */
     skillDirectories?: string[];
+    /**
+     * Local filesystem paths to Open Plugins-format directories
+     * (https://open-plugins.com/) to load for this session.
+     *
+     * Relative paths resolve against `workingDirectory` (or the runtime cwd if
+     * unset); absolute paths are recommended. Invalid entries are logged and
+     * skipped.
+     *
+     * Treated as an explicit opt-in: plugin agents and rules load even when
+     * {@link SessionConfigBase.enableConfigDiscovery} is false. Loaded assets
+     * slot between project (cwd) sources and personal/home sources in the
+     * session-wide precedence order.
+     */
+    pluginDirectories?: string[];
     /**
      * Additional directories to search for custom instruction files.
      */
@@ -1335,6 +1577,53 @@ export interface SessionConfigBase {
      * the identity used for content exclusion, model routing, and quota checks.
      */
     gitHubToken?: string;
+    /**
+     * When true, skips embedding-based retrieval for this session.
+     * Use in multitenant deployments to prevent cross-session information leakage
+     * through the shared embedding cache.
+     */
+    skipEmbeddingRetrieval?: boolean;
+    /**
+     * Controls how the embedding cache is stored for this session.
+     * - `"persistent"`: Embeddings are cached on disk and shared across sessions/restarts.
+     * - `"in-memory"`: Embeddings are cached in memory only and discarded when the session ends.
+     */
+    embeddingCacheStorage?: "persistent" | "in-memory";
+    /**
+     * Organization-level custom instructions to include in the system prompt.
+     * Allows hosts to inject organization-specific guidance without relying on
+     * filesystem-based instruction discovery.
+     */
+    organizationCustomInstructions?: string;
+    /**
+     * When true, enables on-demand discovery of instruction files (AGENTS.md,
+     * .github/copilot-instructions.md, etc.) after successful file views.
+     */
+    enableOnDemandInstructionDiscovery?: boolean;
+    /**
+     * When true, enables loading of file-based hooks from `.github/hooks/`.
+     * This is separate from the `hooks` callback parameter which gates SDK
+     * hook event registration.
+     */
+    enableFileHooks?: boolean;
+    /**
+     * When true, enables git operations on the host filesystem (branch detection,
+     * file status, commit history). When false, no git context is surfaced in
+     * the system prompt.
+     */
+    enableHostGitOperations?: boolean;
+    /**
+     * When true, enables the cross-session store for search and retrieval
+     * across sessions. When false, session content is not written to or
+     * read from the shared session store.
+     */
+    enableSessionStore?: boolean;
+    /**
+     * When true, enables skill loading (including builtin skills and discovered
+     * skill directories). When false, no skills are loaded regardless of
+     * `skillDirectories` or `enableConfigDiscovery` settings.
+     */
+    enableSkills?: boolean;
     /**
      * Per-session remote behavior control:
      * - `"off"` — local only, no remote export (default)
@@ -1514,10 +1803,19 @@ export interface MessageOptions {
      * - "immediate": Send immediately
      */
     mode?: "enqueue" | "immediate";
+    /**
+     * The UI mode the agent was in when this message was sent (for example "plan" or "autopilot").
+     * Defaults to the session's current mode when unset.
+     */
+    agentMode?: "interactive" | "plan" | "autopilot" | "shell";
     /**
      * Custom HTTP headers to include in outbound model requests for this turn.
      */
     requestHeaders?: Record<string, string>;
+    /**
+     * If provided, this is shown in the timeline instead of `prompt`.
+     */
+    displayPrompt?: string;
 }
 /**
  * All possible event type strings from SessionEvent

package/docs/agent-author.md

@@ -118,19 +118,20 @@ hooks: {
     onUserPromptSubmitted: async (input, invocation) => { ... },
     onPreToolUse: async (input, invocation) => { ... },
     onPostToolUse: async (input, invocation) => { ... },
+    onPostToolUseFailure: async (input, invocation) => { ... },
     onSessionStart: async (input, invocation) => { ... },
     onSessionEnd: async (input, invocation) => { ... },
     onErrorOccurred: async (input, invocation) => { ... },
 }
 ```
 
-All hook inputs include `timestamp` (unix ms) and `cwd` (working directory).
+All hook inputs include `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.
 
 ### onUserPromptSubmitted
 
-**Input:** `{ prompt: string, timestamp, cwd }`
+**Input:** `{ prompt: string, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -140,7 +141,7 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onPreToolUse
 
-**Input:** `{ toolName: string, toolArgs: unknown, timestamp, cwd }`
+**Input:** `{ toolName: string, toolArgs: unknown, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -152,7 +153,10 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onPostToolUse
 
-**Input:** `{ toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, cwd }`
+**Input:** `{ toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, workingDirectory }`
+
+Fires only when the tool returned a successful result. To observe non-success
+outcomes, register `onPostToolUseFailure` as well.
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -160,9 +164,29 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 | `modifiedResult` | `ToolResultObject` | Replaces the tool result |
 | `additionalContext` | `string` | Injected into the conversation |
 
+### onPostToolUseFailure
+
+**Input:** `{ toolName: string, toolArgs: unknown, error: string, timestamp, workingDirectory }`
+
+Fires after a tool execution whose result was `"failure"`. `onPostToolUse`
+does **not** fire for these outcomes, so register this handler to observe or
+react to them — useful for telemetry, replay buffers, fault-injection tests,
+or pairing pre/post tool tracking that would otherwise leak when the tool
+fails. Note the input shape differs from `onPostToolUse`: only `error` (the
+stringified failure message) is provided, not the full `toolResult`.
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `additionalContext` | `string` | Appended as hidden guidance the model sees alongside the failed tool result |
+
+Note: only `"failure"` results trigger this hook. Other non-success
+`resultType` values (`"rejected"`, `"denied"`, `"timeout"`) do not currently
+fire it.
+
 ### onSessionStart
 
-**Input:** `{ source: "startup" \| "resume" \| "new", initialPrompt?: string, timestamp, cwd }`
+**Input:** `{ source: "startup" \| "resume" \| "new", initialPrompt?: string, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -171,7 +195,7 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onSessionEnd
 
-**Input:** `{ reason: "complete" \| "error" \| "abort" \| "timeout" \| "user_exit", finalMessage?: string, error?: string, timestamp, cwd }`
+**Input:** `{ reason: "complete" \| "error" \| "abort" \| "timeout" \| "user_exit", finalMessage?: string, error?: string, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -181,7 +205,7 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onErrorOccurred
 
-**Input:** `{ error: string, errorContext: "model_call" \| "tool_execution" \| "system" \| "user_input", recoverable: boolean, timestamp, cwd }`
+**Input:** `{ error: string, errorContext: "model_call" \| "tool_execution" \| "system" \| "user_input", recoverable: boolean, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |

package/docs/examples.md

@@ -152,16 +152,17 @@ Hooks intercept and modify behavior at key lifecycle points. Register them in th
 
 ### Available Hooks
 
-| Hook                    | Fires When                | Can Modify                                  |
-| ----------------------- | ------------------------- | ------------------------------------------- |
-| `onUserPromptSubmitted` | User sends a message      | The prompt text, add context                |
-| `onPreToolUse`          | Before a tool executes    | Tool args, permission decision, add context |
-| `onPostToolUse`         | After a tool executes     | Tool result, add context                    |
-| `onSessionStart`        | Session starts or resumes | Add context, modify config                  |
-| `onSessionEnd`          | Session ends              | Cleanup actions, summary                    |
-| `onErrorOccurred`       | An error occurs           | Error handling strategy (retry/skip/abort)  |
-
-All hook inputs include `timestamp` (unix ms) and `cwd` (working directory).
+| Hook                    | Fires When                               | Can Modify                                  |
+| ----------------------- | ---------------------------------------- | ------------------------------------------- |
+| `onUserPromptSubmitted` | User sends a message                     | The prompt text, add context                |
+| `onPreToolUse`          | Before a tool executes                   | Tool args, permission decision, add context |
+| `onPostToolUse`         | After a tool executes successfully       | Tool result, add context                    |
+| `onPostToolUseFailure`  | After a tool execution returns a failure | Add hidden guidance to the model            |
+| `onSessionStart`        | Session starts or resumes                | Add context                                 |
+| `onSessionEnd`          | Session ends                             | Cleanup actions, summary                    |
+| `onErrorOccurred`       | An error occurs                          | Error handling strategy (retry/skip/abort)  |
+
+All hook inputs include `timestamp` (`Date`) and `workingDirectory`.
 
 ### Modifying the user's message
 
@@ -267,12 +268,18 @@ hooks: {
 }
 ```
 
-### Augmenting tool results with extra context
+### Reacting when a tool fails
+
+`onPostToolUse` only fires for successful tool executions. To observe or react
+to failures, register `onPostToolUseFailure`. The input includes
+`input.error` (the stringified failure message); only `additionalContext` on
+the return value is consumed by the runtime, and it is appended as hidden
+guidance alongside the failed tool result.
 
 ```js
 hooks: {
-    onPostToolUse: async (input) => {
-        if (input.toolName === "bash" && input.toolResult?.resultType === "failure") {
+    onPostToolUseFailure: async (input) => {
+        if (input.toolName === "bash") {
             return {
                 additionalContext: "The command failed. Try a different approach.",
             };
@@ -408,7 +415,7 @@ session.on("assistant.message", (event) => {
 | Event Type                  | Description                                      | Key Data Fields                                        |
 | --------------------------- | ------------------------------------------------ | ------------------------------------------------------ |
 | `assistant.message`         | Agent's final response                           | `content`, `messageId`, `toolRequests`                 |
-| `assistant.streaming_delta` | Token-by-token streaming (ephemeral)             | `totalResponseSizeBytes`                               |
+| `assistant.message_delta`   | Message content chunks (ephemeral)               | `deltaContent`                                         |
 | `tool.execution_start`      | A tool is about to run                           | `toolCallId`, `toolName`, `arguments`                  |
 | `tool.execution_complete`   | A tool finished running                          | `toolCallId`, `toolName`, `success`, `result`, `error` |
 | `user.message`              | User sent a message                              | `content`, `attachments`, `source`                     |
@@ -622,8 +629,11 @@ const session = await joinSession({
         onPreToolUse: async (input) => {
             if (input.toolName === "bash") {
                 const cmd = String(input.toolArgs?.command || "");
-                if (/rm\\s+-rf\\s+\\/ / i.test(cmd) || /Remove-Item\\s+.*-Recurse/i.test(cmd)) {
-                    return { permissionDecision: "deny" };
+                if (/rm\\s+-rf\\s+\//i.test(cmd) || /Remove-Item\\s+.*-Recurse/i.test(cmd)) {
+                    return {
+                        permissionDecision: "deny",
+                        permissionDecisionReason: "Destructive commands are not allowed.",
+                    };
                 }
             }
         },

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -44,7 +44,7 @@
     "generate": "cd ../scripts/codegen && npm run generate",
     "update:protocol-version": "tsx scripts/update-protocol-version.ts",
     "prepublishOnly": "npm run build",
-    "package": "npm run clean && npm run build && node scripts/set-version.js && npm pack && npm version 0.1.0 --no-git-tag-version --allow-same-version"
+    "package": "npm run clean && npm run build && node scripts/set-version.js && npm pack && npm version 0.0.0-dev --no-git-tag-version --allow-same-version"
   },
   "keywords": [
     "github",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.55-1",
+    "@github/copilot": "^1.0.57",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },