sdk: Forward decisionContext on permission replies across languages

[aymenfurter]

Why

The runtime emits auto_approval_decision telemetry only when the client sends an explicit decisionContext with its permission reply. The wire schema, runtime, and generated SDK types already support the field.

The hand-written permission reply paths in these SDKs did not forward it. Hosts that answered permission requests through an SDK therefore could not tell the runtime whether a decision came from a person, host policy, or an automated recommendation.

What changed

Permission handlers can now attach optional decision context. The SDK sends it as a top-level sibling of result in session.permissions.handlePendingPermissionRequest:

• Node: createAttributedPermissionResult(result, context)
• Python: copilot.create_attributed_permission_result(result, context)
• Go: copilot.NewAttributedPermissionResult(result, context)
• .NET: set DecisionContext on the permission decision
• Java: PermissionRequestResult.approveOnce().setDecisionContext(context)
• Rust: PermissionResult::approve_once().with_context(context)

Each SDK follows its existing language conventions. Applying context twice replaces the previous context instead of nesting it. A no-result response remains suppressed.

When a handler does not supply context, the SDK sends the same legacy JSON shape with only sessionId, requestId, and result. It does not send decisionContext: null.

No schema or generated code changed. This PR only fills the gap in the hand-written permission reply paths.

Rust compatibility

Rust keeps PermissionHandler as the single handler API. Attribution is represented by a new PermissionResult::AttributedDecision { decision, context } variant, and with_context returns PermissionResult directly.

This is an intentional Rust source break. Clients that match PermissionResult exhaustively must handle the new variant. Existing handler implementations and session registration remain unchanged. This avoids a parallel attributed handler trait and avoids ambiguous configuration with two public handler fields.

The other five SDK changes are additive.

Testing

• Unit tests in all six SDKs cover context forwarding, omission when absent, no-result behavior, and replacement when context is applied twice.
• The Node E2E test runs the real permission flow and checks the exact params passed to the CLI.
• The Rust fake-server test captures the actual outbound JSON-RPC request and verifies that decisionContext is beside result, not inside it.
• Rust library and session tests pass. Clippy and formatting are clean.
• The targeted Node, Python, Go, .NET, and Java test suites pass.

Release note

Permission handlers can attach decisionContext so the runtime can attribute permission decisions. This is additive for Node, Python, Go, .NET, and Java. Rust clients with exhaustive matches on PermissionResult must handle the new AttributedDecision variant.

[github-actions]

Generated by SDK Consistency Review Agent for #2294 · sonnet46 53.2 AIC · ⌖ 5.69 AIC · ⊞ 6.6K

[Copilot]

Pull request overview

Adds optional permission-decision provenance forwarding across all six SDKs while preserving the legacy wire shape when absent.

Changes:

• Adds language-specific APIs for attaching decisionContext.
• Forwards context beside result in permission RPCs.
• Adds unit and E2E coverage plus compatibility documentation.

Show a summary per file

File	Description
test/snapshots/permissions/should_honor_a_decision_annotated_with_decisioncontext.yaml	Adds shared permission E2E fixture.
rust/tests/e2e/permissions.rs	Tests attributed rejection end to end.
rust/src/types.rs	Re-exports generated context types.
rust/src/session.rs	Builds attributed permission RPC parameters.
rust/src/handler.rs	Adds attributed permission results.
python/test_permission_decision_context.py	Tests Python serialization behavior.
python/copilot/session.py	Adds and forwards attributed results.
python/copilot/__init__.py	Exports the new Python API.
nodejs/test/e2e/permissions.e2e.test.ts	Verifies live RPC shape and behavior.
nodejs/test/client.test.ts	Tests Node.js attribution handling.
nodejs/src/types.ts	Defines attributed result helpers and types.
nodejs/src/session.ts	Forwards context in permission replies.
nodejs/src/index.ts	Exports the new Node.js API.
java/src/test/java/com/github/copilot/rpc/PermissionRequestResultDecisionContextTest.java	Tests Java result serialization.
java/src/main/java/com/github/copilot/rpc/PermissionRequestResult.java	Stores optional decision context.
java/src/main/java/com/github/copilot/CopilotSession.java	Passes context to the generated RPC.
go/types.go	Exposes generated decision-context types.
go/session.go	Unwraps and forwards attributed decisions.
go/permissions.go	Adds the Go attribution wrapper.
go/permission_context_test.go	Tests raw Go JSON-RPC output.
dotnet/test/Unit/ClientSessionLifetimeTests.cs	Tests .NET forwarding and omission.
dotnet/src/Session.cs	Passes context through the RPC client.
dotnet/src/PermissionDecision.cs	Adds fluent context attachment.
docs/troubleshooting/compatibility.md	Documents optional attribution support.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 5
• Review effort level: Balanced

[stephentoub]

Is this necessary?

[aymenfurter]

Renamed to setDecisionContext to match the getter and the other setters here, and dropped the requireNonNull since null now means "no context" everywhere else.

[github-actions]

✅ Cross-SDK Consistency Review

This PR adds decisionContext support to all six SDK implementations consistently. No cross-language gaps found.

Feature parity: All SDKs ✅

SDK	Helper API	Pattern
Node.js	createAttributedPermissionResult(result, ctx)	Wrapper function, exports new types
Python	create_attributed_permission_result(result, ctx)	Wrapper function + AttributedPermissionResult dataclass
Go	NewAttributedPermissionResult(result, ctx)	Struct embedding rpc.PermissionDecision, satisfies the interface
.NET	decision.DecisionContext = ctx	[JsonIgnore] property on PermissionDecision base class
Java	result.setDecisionContext(ctx)	@JsonIgnore field with fluent setter on PermissionRequestResult
Rust	PermissionResult::approve_once().with_context(ctx)	New AttributedDecision enum variant + builder method

Key consistency properties verified ✅

• Wire shape is identical across all SDKs: decisionContext is always emitted as a sibling of result, never nested inside it
• Backward-compatible: omitting context produces byte-identical output to the current behavior (no decisionContext key emitted)
• Re-attribution replaces, never nests: all implementations unwrap an already-attributed result before re-wrapping
• No-result decisions: all SDKs correctly handle the case where NoResult suppresses the response even when context is attached
• Naming conventions: each SDK follows its established idiom (camelCase for JS/Java, snake_case for Python/Rust, PascalCase for Go/C#)

Tests coverage ✅

All SDKs include unit tests covering: context present, context absent (key set verification), re-application replacing not nesting, and no-result with context. Node and Rust additionally have E2E coverage verifying the outgoing wire shape.

The changes are well-structured and maintain strong cross-language consistency.

Generated by SDK Consistency Review Agent for #2294 · sonnet46 33 AIC · ⌖ 5.48 AIC · ⊞ 6.6K · ◷

[Copilot]

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[aymenfurter]

@stephentoub I moved this PR back to draft after finding that the current Rust API change breaks existing clients. Adding AttributedDecision to PermissionResult, or marking the enum #[non_exhaustive], breaks clients that match its existing variants exhaustively.

I tested a backwards-compatible alternative that keeps PermissionHandler and PermissionResult unchanged. It adds a separate AttributedPermissionHandler for clients that need to provide decisionContext.

Existing clients continue to use:

impl PermissionHandler for MyHandler {
    async fn handle(...) -> PermissionResult {
        PermissionResult::approve_once()
    }
}

SessionConfig::default()
    .with_permission_handler(Arc::new(MyHandler))

Copilot App would use:

impl AttributedPermissionHandler for CopilotAppPermissionHandler {
    async fn handle(...) -> AttributedPermissionResult {
        PermissionResult::approve_once().with_context(
            PermissionDecisionContext {
                outcome: PermissionDecisionOutcome::PromptedUser,
                source: PermissionDecisionSource::HumanResponse,
                surface: PermissionDecisionSurface::CopilotApp,
            },
        )
    }
}

let client = Client::start(ClientOptions::default()).await?;

let session = client
    .create_session(
        SessionConfig::default().with_attributed_permission_handler(
            Arc::new(CopilotAppPermissionHandler),
        ),
    )
    .await?;

Existing clients compile without changes, and context-aware clients implement only one handler method. The cost is one additional handler trait and configuration method.

[stephentoub]

Adding AttributedDecision to PermissionResult, or marking the enum #[non_exhaustive], breaks clients that match its existing variants exhaustively.

In the past, I believe @tclem has suggested we shouldn't care about such breaking changes for rust consumers. Tim?

[aymenfurter]

@tclem What do you think? 👀

[tclem]

This test passes even if decisionContext forwarding is removed; it only observes the rejection. Please test the outbound JSON-RPC request with the existing fake server in session_test.rs, asserting decisionContext beside result.

  _{Generated via Copilot (GPT-5.6 Sol) on behalf of @tclem}

[aymenfurter]

Agreed. I removed the E2E test because it only proved that the rejection was honored. The replacement test uses the existing fake server in session_test.rs, captures the outbound JSON-RPC request, and verifies that decisionContext is beside result.

[tclem]

Can we avoid introducing a second handler hierarchy? Attribution changes the response metadata, not the dispatch contract. I’d rather evolve PermissionResult and keep PermissionHandler as the single API. If source compatibility is mandatory, a provided PermissionHandler::handle_with_context defaulting to the existing handle is still less permanent surface than parallel traits and configuration.

  _{Generated via Copilot (GPT-5.6 Sol) on behalf of @tclem}

[aymenfurter]

Agreed. I removed AttributedPermissionHandler and kept PermissionHandler as the single dispatch API. PermissionResult now carries the optional attribution through an AttributedDecision variant. This intentionally creates one Rust source break: exhaustive matches on PermissionResult must handle the new variant. Existing handler implementations and session registration remain unchanged.

[tclem]

This API is misleading: PermissionResult::approve_once().with_context(ctx) no longer returns PermissionResult, so it cannot be returned from PermissionHandler::handle. Please keep with_context returning Self; the obvious usage should compile.

  _{Generated via Copilot (GPT-5.6 Sol) on behalf of @tclem}

[aymenfurter]

Fixed. with_context now returns Self, so PermissionResult::approve_once().with_context(context) can be returned directly from PermissionHandler::handle. Calling it again replaces the previous context.

[tclem]

These public fields can both be set through direct assignment, while resolve_handler silently prefers the attributed handler. Since direct field assignment is explicitly supported, this introduces an invalid and ambiguous state. A single handler field avoids it.

  _{Generated via Copilot (GPT-5.6 Sol) on behalf of @tclem}

[aymenfurter]

Fixed. SessionConfig and ResumeSessionConfig now have only one permission handler field. The attributed field and its precedence rules are gone.

[tclem]

strange to have a function called attributed that returns UnattributedHandler...

[aymenfurter]

Removed. The attributed() adapter and UnattributedHandler type no longer exist.

[aymenfurter]

We decided to make the breaking change for Rust. PermissionResult now has an AttributedDecision variant, so clients with exhaustive matches must handle the new variant. Existing PermissionHandler implementations and session registration remain unchanged. This lets us keep one handler API instead of introducing a parallel attributed handler hierarchy. Tim confirmed that this kind of Rust source break is acceptable.

[tclem]

Could we extend Decision instead of adding a second semantic decision variant?

Decision {
    decision: PermissionDecision,
    context: Option<PermissionDecisionContext>,
}

AttributedDecision is still a decision, so every consumer must remember to handle both variants. More importantly, downstream code matching Decision(_) with a wildcard arm keeps compiling and may silently treat an attributed decision like NoResult. Since we're already taking a breaking change here, I'd prefer the compiler-guided break and the coherent model.

  _{Generated via Copilot (GPT-5.6 Sol) on behalf of @tclem}