@github/copilot-sdk 1.0.11-preview.1 → 1.0.11

package/dist/cjs/client.js

@@ -291,6 +291,7 @@ class CopilotClient {
   /** Connection-level session filesystem config, set via constructor option. */
   sessionFsConfig = null;
   requestHandler = null;
+  builtinPluginDirectories = [];
   onGitHubTelemetry;
   clientGlobalHandlers = {};
   /**
@@ -419,6 +420,16 @@ class CopilotClient {
     if (options.sessionFs) {
       this.validateSessionFsConfig(options.sessionFs);
     }
+    if (options.builtinPluginDirectories) {
+      for (const path of options.builtinPluginDirectories) {
+        if (!(0, import_node_path.isAbsolute)(path)) {
+          throw new Error(
+            `builtinPluginDirectories must contain only absolute paths: ${path}`
+          );
+        }
+      }
+      this.builtinPluginDirectories = [...options.builtinPluginDirectories];
+    }
     if (conn.kind === "uri") {
       const { host, port } = this.parseCliUrl(conn.url);
       this.actualHost = host;
@@ -573,6 +584,16 @@ class CopilotClient {
       }
       await this.connectToServer();
       await this.verifyProtocolVersion();
+      if (this.builtinPluginDirectories.length > 0) {
+        try {
+          await this.connection.sendRequest("plugins.builtin.set", {
+            paths: this.builtinPluginDirectories
+          });
+        } catch (error) {
+          await this.forceStop();
+          throw error;
+        }
+      }
       if (this.sessionFsConfig) {
         await this.connection.sendRequest("sessionFs.setProvider", {
           initialCwd: this.sessionFsConfig.initialCwd,

package/dist/cjs/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   ToolSet: () => import_toolSet.ToolSet,
   approveAll: () => import_types2.approveAll,
   convertMcpCallToolResult: () => import_types2.convertMcpCallToolResult,
+  createAttributedPermissionResult: () => import_types2.createAttributedPermissionResult,
   createCanvas: () => import_canvas.createCanvas,
   createSessionFsAdapter: () => import_types2.createSessionFsAdapter,
   defineFactory: () => import_factory.defineFactory,
@@ -66,6 +67,7 @@ var import_types2 = require("./types.js");
   ToolSet,
   approveAll,
   convertMcpCallToolResult,
+  createAttributedPermissionResult,
   createCanvas,
   createSessionFsAdapter,
   defineFactory,

package/dist/cjs/session.js

@@ -26,6 +26,7 @@ var import_node = require("vscode-jsonrpc/node.js");
 var import_rpc = require("./generated/rpc.js");
 var import_canvas = require("./canvas.js");
 var import_telemetry = require("./telemetry.js");
+var import_types = require("./types.js");
 var import_factory = require("./factory.js");
 function isFactoryResumeErrorCode(value) {
   return value === "not_found" || value === "non_resumable" || value === "already_active" || value === "factory_already_running" || value === "factory_limits_invalid" || value === "factory_session_disposed" || value === "factory_storage_unavailable" || value === "factory_storage_corrupt";
@@ -736,17 +737,22 @@ class CopilotSession {
    */
   async _executePermissionAndRespond(requestId, permissionRequest) {
     try {
-      const result = await this.permissionHandler(permissionRequest, {
+      const handlerResult = await this.permissionHandler(permissionRequest, {
         sessionId: this.sessionId,
         managedSettingsEnabled: this.managedSettingsEnabled
       });
+      const isAttributed = (0, import_types.isAttributedPermissionResult)(handlerResult);
+      const result = isAttributed ? handlerResult.result : handlerResult;
+      const decisionContext = isAttributed ? handlerResult.decisionContext : void 0;
       if (result.kind === "no-result") {
         return;
       }
       if (this.disconnected) {
         return;
       }
-      await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
+      await this.rpc.permissions.handlePendingPermissionRequest(
+        decisionContext === void 0 ? { requestId, result } : { requestId, result, decisionContext }
+      );
     } catch (error) {
       if (this.disconnected) {
         return;

package/dist/cjs/types.js

@@ -27,9 +27,11 @@ __export(types_exports, {
   SessionFsSqliteTransactionFailure: () => import_sessionFsProvider2.SessionFsSqliteTransactionFailure,
   approveAll: () => approveAll,
   convertMcpCallToolResult: () => convertMcpCallToolResult,
+  createAttributedPermissionResult: () => createAttributedPermissionResult,
   createSessionFsAdapter: () => import_sessionFsProvider.createSessionFsAdapter,
   defaultJoinSessionPermissionHandler: () => defaultJoinSessionPermissionHandler,
-  defineTool: () => defineTool
+  defineTool: () => defineTool,
+  isAttributedPermissionResult: () => isAttributedPermissionResult
 });
 module.exports = __toCommonJS(types_exports);
 var import_sessionFsProvider = require("./sessionFsProvider.js");
@@ -141,6 +143,13 @@ const SYSTEM_MESSAGE_SECTIONS = {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
 };
+function isAttributedPermissionResult(result) {
+  return result.kind === "attributed";
+}
+function createAttributedPermissionResult(result, decisionContext) {
+  const inner = isAttributedPermissionResult(result) ? result.result : result;
+  return { kind: "attributed", result: inner, decisionContext };
+}
 const approveAll = (request, invocation) => {
   if (invocation.managedSettingsEnabled) {
     throw new Error("approveAll cannot be used when managed settings are enabled");
@@ -167,7 +176,9 @@ const defaultJoinSessionPermissionHandler = () => ({
   SessionFsSqliteTransactionFailure,
   approveAll,
   convertMcpCallToolResult,
+  createAttributedPermissionResult,
   createSessionFsAdapter,
   defaultJoinSessionPermissionHandler,
-  defineTool
+  defineTool,
+  isAttributedPermissionResult
 });

package/dist/client.d.ts

@@ -37,6 +37,7 @@ export declare class CopilotClient {
     /** Connection-level session filesystem config, set via constructor option. */
     private sessionFsConfig;
     private requestHandler;
+    private builtinPluginDirectories;
     private onGitHubTelemetry?;
     private clientGlobalHandlers;
     /**

package/dist/client.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { Socket } from "node:net";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   createMessageConnection,
@@ -268,6 +268,7 @@ class CopilotClient {
   /** Connection-level session filesystem config, set via constructor option. */
   sessionFsConfig = null;
   requestHandler = null;
+  builtinPluginDirectories = [];
   onGitHubTelemetry;
   clientGlobalHandlers = {};
   /**
@@ -396,6 +397,16 @@ class CopilotClient {
     if (options.sessionFs) {
       this.validateSessionFsConfig(options.sessionFs);
     }
+    if (options.builtinPluginDirectories) {
+      for (const path of options.builtinPluginDirectories) {
+        if (!isAbsolute(path)) {
+          throw new Error(
+            `builtinPluginDirectories must contain only absolute paths: ${path}`
+          );
+        }
+      }
+      this.builtinPluginDirectories = [...options.builtinPluginDirectories];
+    }
     if (conn.kind === "uri") {
       const { host, port } = this.parseCliUrl(conn.url);
       this.actualHost = host;
@@ -550,6 +561,16 @@ class CopilotClient {
       }
       await this.connectToServer();
       await this.verifyProtocolVersion();
+      if (this.builtinPluginDirectories.length > 0) {
+        try {
+          await this.connection.sendRequest("plugins.builtin.set", {
+            paths: this.builtinPluginDirectories
+          });
+        } catch (error) {
+          await this.forceStop();
+          throw error;
+        }
+      }
       if (this.sessionFsConfig) {
         await this.connection.sendRequest("sessionFs.setProvider", {
           initialCwd: this.sessionFsConfig.initialCwd,

package/dist/factory.d.ts

@@ -17,12 +17,16 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
 /**
- * Conservative JSON shape language accepted for structured factory agent output.
+ * Conservative JSON shape language accepted by the Agent Factories surface, for
+ * both structured factory agent output and a factory's declared `argsSchema`.
  *
- * This is a best-effort structural guard used to decide whether a subagent's
- * structured output should be accepted or retried — **not** a full JSON Schema
+ * This is a best-effort structural guard — used to decide whether a subagent's
+ * structured output should be accepted or retried, and whether a caller's
+ * factory `args` match the declared shape — **not** a full JSON Schema
  * validator. Only these keywords are honored: `type`, `required`, `enum`,
- * `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`.
+ * `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`. A `type`
+ * is one of `null`, `boolean`, `integer`, `number`, `string`, `array`, or
+ * `object`, or a non-empty array of those (for example `["object", "null"]`).
  *
  * Everything else is **ignored, not enforced**. In particular, string
  * constraints (`pattern`, `minLength`, `maxLength`, `format`), numeric ranges

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { BuiltInTools, ToolSet } from "./toolSet.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
-export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
+export { defineTool, approveAll, createAttributedPermissionResult, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
 export type { RunOptions, ResumeOptions, FactoryResumeErrorCode, SessionFactoryApi, FactoryAgentOptions, FactoryContext, FactoryDefinition, FactoryHandle, FactoryJsonSchema, JsonValue, FactoryPipelineStage, FactoryStepOptions, FactoryRunResult, FactoryRunStatus, FactoryRunSummary, FactoryRunDetail, FactoryProgressPage, FactoryProgressLine, FactoryPhaseObservation, FactoryPhaseStatus, FactoryAgentSummary, } from "./factory.js";

package/dist/index.js

@@ -11,6 +11,7 @@ import {
 import {
   defineTool,
   approveAll,
+  createAttributedPermissionResult,
   convertMcpCallToolResult,
   createSessionFsAdapter,
   CopilotRequestHandler,
@@ -37,6 +38,7 @@ export {
   ToolSet,
   approveAll,
   convertMcpCallToolResult,
+  createAttributedPermissionResult,
   createCanvas,
   createSessionFsAdapter,
   defineFactory,

package/dist/session.js

@@ -3,6 +3,7 @@ import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.
 import { createSessionRpc } from "./generated/rpc.js";
 import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
+import { isAttributedPermissionResult } from "./types.js";
 import {
   FACTORY_AGENT_OPTION_KEYS,
   getFactoryDefinition,
@@ -718,17 +719,22 @@ class CopilotSession {
    */
   async _executePermissionAndRespond(requestId, permissionRequest) {
     try {
-      const result = await this.permissionHandler(permissionRequest, {
+      const handlerResult = await this.permissionHandler(permissionRequest, {
         sessionId: this.sessionId,
         managedSettingsEnabled: this.managedSettingsEnabled
       });
+      const isAttributed = isAttributedPermissionResult(handlerResult);
+      const result = isAttributed ? handlerResult.result : handlerResult;
+      const decisionContext = isAttributed ? handlerResult.decisionContext : void 0;
       if (result.kind === "no-result") {
         return;
       }
       if (this.disconnected) {
         return;
       }
-      await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
+      await this.rpc.permissions.handlePendingPermissionRequest(
+        decisionContext === void 0 ? { requestId, result } : { requestId, result, decisionContext }
+      );
     } catch (error) {
       if (this.disconnected) {
         return;

package/dist/types.d.ts

@@ -6,7 +6,7 @@ import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
-import type { JsonValue } from "./factory.js";
+import type { FactoryJsonSchema, JsonValue } from "./factory.js";
 import type { GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
@@ -27,6 +27,7 @@ export type { SessionFsSqliteStatement } from "./sessionFsProvider.js";
 export type { SessionFsSqliteTransactionErrorClass } from "./sessionFsProvider.js";
 export { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
 export type { LlmInferenceHeaders } from "./generated/rpc.js";
+export type { PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, } from "./generated/rpc.js";
 export type { CopilotRequestContext } from "./copilotRequestHandler.js";
 export { CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, } from "./copilotRequestHandler.js";
 /**
@@ -228,6 +229,12 @@ export interface CopilotClientOptions {
      * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
      */
     baseDirectory?: string;
+    /**
+     * Absolute paths to trusted plugin directories bundled by the host.
+     * When non-empty, the complete set is registered with the runtime during
+     * startup before any sessions can be created.
+     */
+    builtinPluginDirectories?: readonly string[];
     /**
      * Log level for the Copilot runtime. When omitted, the runtime uses its
      * own default (currently `"info"`).
@@ -853,7 +860,7 @@ export interface SystemMessageCustomizeConfig {
  * - Customize mode: Section-level overrides with graceful fallback
  */
 export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
-import type { PermissionDecisionRequest } from "./generated/rpc.js";
+import type { PermissionDecisionRequest, PermissionDecisionContext } from "./generated/rpc.js";
 /**
  * Permission request types from the server. This is the generated
  * discriminated union from the runtime schema — switch on `kind` to
@@ -883,10 +890,35 @@ export type PermissionRequestedEvent = Omit<GeneratedPermissionRequestedEvent, "
 export type PermissionRequestResult = PermissionDecisionRequest["result"] | {
     kind: "no-result";
 };
+/**
+ * A {@link PermissionRequestResult} annotated with the
+ * {@link PermissionDecisionContext} describing how and where the decision was
+ * reached. The context is informational only — it never changes permission
+ * behavior. Supplying it lets the runtime attribute auto-approval telemetry to
+ * the responding surface.
+ */
+export interface AttributedPermissionResult {
+    kind: "attributed";
+    result: PermissionRequestResult;
+    decisionContext: PermissionDecisionContext;
+}
+/**
+ * Narrows a {@link PermissionHandler} return value to an attributed result.
+ */
+export declare function isAttributedPermissionResult(result: PermissionRequestResult | AttributedPermissionResult): result is AttributedPermissionResult;
+/**
+ * Pair a permission decision with the context describing how and where it was
+ * made, so the runtime can attribute auto-approval telemetry.
+ *
+ * Passing an already-attributed result replaces the previous context rather
+ * than nesting it. The context is informational only and never changes
+ * permission behavior.
+ */
+export declare function createAttributedPermissionResult(result: PermissionRequestResult | AttributedPermissionResult, decisionContext: PermissionDecisionContext): AttributedPermissionResult;
 export type PermissionHandler = (request: PermissionRequest, invocation: {
     sessionId: string;
     managedSettingsEnabled?: boolean;
-}) => Promise<PermissionRequestResult> | PermissionRequestResult;
+}) => Promise<PermissionRequestResult | AttributedPermissionResult> | PermissionRequestResult | AttributedPermissionResult;
 /**
  * Approves permission requests when managed settings are disabled.
  */
@@ -1619,6 +1651,30 @@ export interface FactoryMeta {
         title: string;
         detail?: string;
     }>;
+    /**
+     * Optional declared shape of the arguments this factory expects as `ctx.args`.
+     *
+     * Declaring one is strongly recommended for any factory that reads `ctx.args`.
+     * When the model invokes the factory through the `run_factory` tool, the CLI
+     * validates `args` against this declaration **before** the run starts, so a
+     * malformed call is rejected with a correction hint and retried without ever
+     * creating a run row, prompting the user for permission, or spending credits. A
+     * factory that declares nothing is never validated: a malformed call starts,
+     * takes an approval, spends credits, and then fails inside the factory body.
+     * `factories_manage` with `operation: "inspect"` reports the declared shape so an
+     * agent can read it before invoking.
+     *
+     * This covers the model's `run_factory` path only. `session.factory.run(...)` is
+     * not validated against the declaration, so a factory should still check
+     * `ctx.args` rather than assume the declared shape held.
+     *
+     * Enforcement covers structure — types, required properties, and enum/const
+     * values. Finer constraints such as `minLength`, `pattern`, and
+     * `additionalProperties` are recorded in the declaration but not enforced. See
+     * {@link FactoryJsonSchema} for the accepted subset. A declaration outside that
+     * subset is rejected at registration.
+     */
+    argsSchema?: FactoryJsonSchema;
     /** Optional resource ceilings presented to the user before execution. */
     limits?: FactoryLimits;
 }

package/dist/types.js

@@ -112,6 +112,13 @@ const SYSTEM_MESSAGE_SECTIONS = {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
 };
+function isAttributedPermissionResult(result) {
+  return result.kind === "attributed";
+}
+function createAttributedPermissionResult(result, decisionContext) {
+  const inner = isAttributedPermissionResult(result) ? result.result : result;
+  return { kind: "attributed", result: inner, decisionContext };
+}
 const approveAll = (request, invocation) => {
   if (invocation.managedSettingsEnabled) {
     throw new Error("approveAll cannot be used when managed settings are enabled");
@@ -137,7 +144,9 @@ export {
   SessionFsSqliteTransactionFailure,
   approveAll,
   convertMcpCallToolResult,
+  createAttributedPermissionResult,
   createSessionFsAdapter,
   defaultJoinSessionPermissionHandler,
-  defineTool
+  defineTool,
+  isAttributedPermissionResult
 };

package/docs/factories.md

@@ -16,6 +16,13 @@ const reviewChanged = defineFactory({
             "Review changed files and verify the findings. " +
             "args: { files: string[] } — the paths to review.",
         phases: [{ title: "Review" }, { title: "Verify" }],
+        argsSchema: {
+            type: "object",
+            required: ["files"],
+            properties: {
+                files: { type: "array", items: { type: "string" } },
+            },
+        },
         limits: {
             maxConcurrentSubagents: 3,
             maxTotalSubagents: 10,
@@ -41,9 +48,19 @@ const reviewChanged = defineFactory({
 const session = await joinSession({ factories: [reviewChanged] });
 ```
 
-Factory metadata contains a stable `name`, a human-readable `description`, declared `phases`, and optional `limits`. Phase entries contain a `title` and optional `detail`.
+Factory metadata contains a stable `name`, a human-readable `description`, declared `phases`, an optional `argsSchema`, and optional `limits`. Phase entries contain a `title` and optional `detail`.
+
+## Declaring an argument shape
+
+A factory that reads `ctx.args` should declare `meta.argsSchema`, as the example above does. When the model invokes the factory through the `run_factory` tool, the CLI validates `args` against the declaration **before** the run starts.
+
+Declaring one turns an expensive failure into a cheap one. With a schema, a malformed call is rejected up front — the model gets a correction hint and retries, and no run row, permission prompt, or credit spend happens. Without one, nothing validates: the run starts, takes a user approval, spends credits, and then dies inside the factory body with a confusing error. Agents can read the declared shape with `factories_manage` using `operation: "inspect"`.
+
+Enforcement covers structure — types, required properties, and enum or const values. Finer constraints such as `minLength`, `pattern`, or `additionalProperties` are recorded in the declaration but not enforced. The accepted vocabulary is the `FactoryJsonSchema` subset also used for subagent structured output: `type`, `required`, `enum`, `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`. A `type` is one of `null`, `boolean`, `integer`, `number`, `string`, `array`, or `object`, or a non-empty array of those such as `["object", "null"]`. A declaration outside that subset is rejected at registration.
+
+`argsSchema` is optional and backward compatible. A factory that omits it behaves exactly as before, so **the `description` is then the only thing telling an agent what arguments to supply** — state the expected shape there.
 
-There is no declared schema for `ctx.args`. The `run_factory` tool forwards `args` verbatim and its parameter is untyped, so **the `description` is the only thing telling an agent what arguments to supply** — state the expected shape there whenever a factory reads `ctx.args`, as the example above does. Arguments supplied by an extension calling `session.factory.run(...)` directly are typed through `defineFactory<TArgs>`, but that typing does not reach the model. A factory that reads `ctx.args` should validate it rather than assume a shape.
+Validation covers the model's `run_factory` path only. An extension calling `session.factory.run(...)` directly is not validated against `argsSchema`; those arguments are typed through `defineFactory<TArgs>` instead, and that typing does not reach the model. So a factory that reads `ctx.args` should still validate it rather than assume a shape — the declared subset does not enforce every constraint, and it does not run at all on the SDK path.
 
 `defineFactory<TArgs, TResult>` accepts a `run(context)` function returning `Promise<TResult>`, where `TResult` is `JsonValue | void`. Objects, arrays, strings, numbers, booleans, and `null` are valid results. Returning `undefined` completes the factory with no result. Other non-JSON values are rejected.
 
@@ -193,7 +210,7 @@ async ({ args, agent, phase }) => {
 };
 ```
 
-Authoring registers the factory but does not run it. Invoke it afterwards with `run_factory`. Use `factories_manage` with `operation: "list"` to see the factories already registered in the session and `operation: "inspect"` to read one factory's description, phases, and limits before running it.
+Authoring registers the factory but does not run it. Invoke it afterwards with `run_factory`. Use `factories_manage` with `operation: "list"` to see the factories already registered in the session and `operation: "inspect"` to read one factory's description, phases, declared argument shape, and limits before running it.
 
 ## Observe a run
 

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.11-preview.1",
+  "version": "1.0.11",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",