Upstream sync: Port 39 new commits from copilot-sdk (2026-03-24)

[Copilot]

Ports 39 upstream commits (062b61c → 40887393) from the official Copilot SDK to the Java SDK.

---

Before the change?

• Unknown session event types from newer CLI versions were silently dropped (returned null from parser)
• No way to have a permission handler abstain from answering (multi-client scenarios)
• No way to mark a tool as safe/skip-permission
• System message customization was limited to full replace or append — no section-level control
• setModel() had no reasoning effort parameter
• No inline binary (blob) attachment support
• No OpenTelemetry configuration support
• autoRestart option was still active (upstream removed it)

After the change?

Forward compatibility

• Unknown event types now return UnknownSessionEvent (preserves id/timestamp/parentId) instead of null, so handlers receive all events from newer CLI versions

Permission handling

• PermissionRequestResultKind.NO_RESULT — handler abstains, leaving the request for another client; SDK skips the RPC response in both v2 and v3 protocol paths

Tool definitions

• ToolDefinition.skipPermission field + createSkipPermission() factory — CLI bypasses permission prompt for the tool

System message fine-grained customization (SystemMessageMode.CUSTOMIZE)

• SectionOverrideAction enum (replace, remove, append, prepend, transform)
• SectionOverride class — per-section override with optional async transform callback
• SystemPromptSections — well-known section identifier constants
• SystemMessageConfig.setSections(Map<String, SectionOverride>) — section-level overrides
• systemMessage.transform RPC handler registered automatically when transform callbacks are present

new SessionConfig()
    .setSystemMessage(new SystemMessageConfig()
        .setMode(SystemMessageMode.CUSTOMIZE)
        .setSections(Map.of(
            SystemPromptSections.TONE,
                new SectionOverride().setAction(SectionOverrideAction.REPLACE)
                                     .setContent("Be concise and formal."),
            SystemPromptSections.IDENTITY,
                new SectionOverride().setTransform(content ->
                    CompletableFuture.completedFuture(content + "\nAlways end with DONE."))
        )))

Model switching

• CopilotSession.setModel(String model, String reasoningEffort) — new overload; existing setModel(String) delegates to it

Attachments — type-safe polymorphic hierarchy

• MessageAttachment sealed interface — Java equivalent of the .NET SDK's UserMessageDataAttachmentsItem polymorphic base class, with Jackson @JsonTypeInfo/@JsonSubTypes annotations for polymorphic serialization
• Attachment record now implements MessageAttachment (with getType() bridge method)
• BlobAttachment — final class implementing MessageAttachment for inline base64-encoded binary (e.g. images)
• MessageOptions.setAttachments(List<? extends MessageAttachment>) — accepts List<Attachment>, List<BlobAttachment>, or List<MessageAttachment> with full compile-time safety
• SendMessageRequest uses List<MessageAttachment> internally

// Single-type list (type inferred)
new MessageOptions().setAttachments(List.of(
    new Attachment("file", "/path/to/file.java", "Source")));

// Mixed list (explicit type hint)
new MessageOptions().setAttachments(List.<MessageAttachment>of(
    new Attachment("file", "/path/to/file.java", "Source"),
    new BlobAttachment().setData(base64Data).setMimeType("image/png")));

Observability

• TelemetryConfig class + CopilotClientOptions.setTelemetry(TelemetryConfig) — sets COPILOT_OTEL_* env vars on CLI process startup

Deprecations

• CopilotClientOptions.autoRestart — marked @Deprecated, no-op

Bug fixes

• Fixed compilation errors in NO_RESULT permission handling: PermissionRequestResultKind is a string-backed value class (not an enum), so replaced valueOf() with constructor call in CopilotSession and .name() with .getValue() in RpcHandlerDispatcher

Pull request checklist

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
• mvn spotless:apply has been run to format the code
• mvn clean verify passes locally

Does this introduce a breaking change?

• Yes
• No

Attachment now implements the new MessageAttachment sealed interface and MessageOptions.setAttachments accepts List<? extends MessageAttachment>. All existing caller code compiles unchanged: List.of(new Attachment(...)) infers List<Attachment> which matches List<? extends MessageAttachment>. No casts required.

---

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.