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. PermissionResult::Decision now contains the decision and an optional context:

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

This is an intentional Rust source break. Clients that construct or match PermissionResult::Decision directly must use the new struct variant. The compiler identifies these sites during migration, including wildcard matches that could otherwise mistake a contextual decision for NoResult. Existing handler implementations that use the result helpers and existing session registration remain unchanged. This avoids a parallel attributed handler trait and keeps all decisions in one semantic variant.

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 that construct or match PermissionResult::Decision directly must migrate from the tuple variant to the new struct 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

[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? 👀

[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.

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds decisionContext forwarding across all six SDK implementations. Here's what I verified:

API surface — all six SDKs covered

SDK	New API
Node.js	createAttributedPermissionResult(result, context) + AttributedPermissionResult type
Python	create_attributed_permission_result(result, context) + AttributedPermissionResult
Go	NewAttributedPermissionResult(result, context) + AttributedPermissionResult struct
.NET	DecisionContext property on PermissionDecision
Java	PermissionRequestResult.setDecisionContext(context) / .getDecisionContext()
Rust	PermissionResult::approve_once().with_context(context)

Behavior consistency

All six implementations agree on:

• decisionContext is sent as a top-level sibling of result, not nested inside it
• When no context is supplied, the field is omitted entirely (not sent as null)
• NoResult decisions suppress the response even when context is attached
• Applying context twice replaces the previous context rather than nesting

Minor observation — Go "Experimental" label

The Go SDK marks AttributedPermissionResult and NewAttributedPermissionResult with // Experimental: doc comments, but the equivalent APIs in other SDKs (Node, Python, .NET, Java, Rust) carry no such label. This isn't a correctness issue, but you may want to decide whether to align the stability signal across all languages — either adding the experimental note to the others or removing it from Go.

Testing

All six SDKs include unit tests covering: context forwarding, omission when absent, no-result suppression, and context replacement. Node adds an E2E test; Rust adds a fake-server wire-format test.

Overall the PR maintains strong cross-SDK consistency. 👍

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