@@ -7,6 +7,34 @@ See [GitHub Releases](https://github.com/github/copilot-sdk/releases) for the fu
 
 ## [Unreleased]
 
+### Feature: structured Policy Helper failures and scoped recheck
+
+Node and Rust managed-settings snapshots now expose bounded structured Policy Helper failures, including actionable messages, remediation, details, explicit help links, and secondary diagnostics. The same DTO is preserved in applicable `session.create`, `session.resume`, and policy-dependent activation RPC error data without replacing the operation's primary code or message.
+
+Use `policyHelperCapabilities` to detect support. Older runtimes omit the capability object; the absence of `policyHelperFailure` alone does not prove recovery or support. When `recheck` is true, the new session-scoped RPC performs a fresh helper evaluation for the current policy context.
+
+```ts
+const snapshot = await session.rpc.managedSettings.get();
+if (snapshot.policyHelperCapabilities?.recheck) {
+    await session.rpc.managedSettings.recheckPolicyHelper();
+}
+```
+
+```rust
+let snapshot = session.rpc().managed_settings().get().await?;
+if snapshot
+    .policy_helper_capabilities
+    .as_ref()
+    .is_some_and(|capabilities| capabilities.recheck)
+{
+    session
+        .rpc()
+        .managed_settings()
+        .recheck_policy_helper()
+        .await?;
+}
+```
+
 ## [v1.0.14](https://github.com/github/copilot-sdk/releases/tag/v1.0.14) (2026-09-16)
 
 ### Feature: typed message provenance for user, system, and agent sources
 
@@ -1438,6 +1438,33 @@ security checks, user permissions, or sandbox policy. `permissions.limitTo` neit
 enables the sandbox nor changes `sandbox.userPolicy.network`; configure sandbox
 network restrictions explicitly.
 
+### Policy Helper failures and scoped recheck
+
+Managed-settings snapshots may include a structured `policyHelperFailure` and
+the explicit `policyHelperCapabilities` supported by the runtime. Treat helper
+text as untrusted plain text, keep `diagnostic` secondary, and sanitize an
+explicit `helpLink` again before navigation.
+
+```typescript
+const snapshot = await session.rpc.managedSettings.get();
+
+if (snapshot.policyHelperFailure) {
+    console.warn(snapshot.policyHelperFailure.message);
+}
+
+if (snapshot.policyHelperCapabilities?.recheck === true) {
+    const refreshed = await session.rpc.managedSettings.recheckPolicyHelper();
+    // Only a current capable snapshot without policyHelperFailure establishes recovery.
+    console.log(refreshed.policyHelperFailure ?? "Policy Helper recovered");
+}
+```
+
+Older runtimes omit `policyHelperCapabilities`. Do not infer support or recovery
+only because `policyHelperFailure` is absent. Applicable `session.create`,
+`session.resume`, and policy-dependent activation failures preserve the same DTO
+under JSON-RPC `error.data.policyHelperFailure` while retaining the primary
+operation error code and message.
+
 ### Permission Result Kinds
 
 The handler must return one of the `PermissionDecision` shapes (or `{ kind: "no-result" }`). Approval scopes are present-tense — they describe the decision to apply, not the outcome reported back on session events:
 
@@ -26,6 +26,7 @@ import {
     type GitHubTelemetryNotification,
     type ManagedSettings,
     type ModelInfo,
+    type PolicyHelperFailure,
     type SubagentStartHookOutput,
     type SubagentStopHookOutput,
     type SessionFsProvider,
@@ -5483,12 +5484,17 @@ describe("RPC error data preservation", () => {
     it.each(["session.create", "session.resume"] as const)(
         "preserves structured data from %s",
         async (method) => {
-            const data = {
-                context: {
-                    category: "structured-runtime-failure",
-                    message: "The runtime preserved structured operation context.",
-                },
-            };
+            const policyHelperFailure = {
+                authority: "future-authority",
+                category: "future-category",
+                code: "helper.future-code",
+                failureMode: "future-mode",
+                message: "The Policy Helper rejected the current configuration.",
+                previousPolicyRetained: true,
+                reason: "future-reason",
+                severity: "future-severity",
+            } satisfies PolicyHelperFailure;
+            const data = { policyHelperFailure };
             const responseError = new ResponseError(-32001, "session operation failed", data);
             const client = new CopilotClient({ autoStart: false });
             (client as any).connection = {
@@ -5515,6 +5521,7 @@ describe("RPC error data preservation", () => {
             expect(responseError.code).toBe(-32001);
             expect(responseError.message).toBe("session operation failed");
             expect(responseError.data).toBe(data);
+            expect(responseError.data.policyHelperFailure).toBe(policyHelperFailure);
         }
     );
 });
 
@@ -0,0 +1,122 @@
+import { ResponseError, type MessageConnection } from "vscode-jsonrpc/node.js";
+import { describe, expect, it, vi } from "vitest";
+import { createServerRpc, createSessionRpc } from "../src/generated/rpc.js";
+import type { ManagedSettingsResolvedData, PolicyHelperFailure } from "../src/index.js";
+
+const policyHelperFailure = {
+    authority: "future-authority",
+    category: "future-category",
+    code: "helper.future-code",
+    details: [
+        {
+            path: "allowedRepositories",
+            message: "Expected an array.",
+        },
+    ],
+    diagnostic: "bounded diagnostic",
+    failureMode: "future-mode",
+    helpLink: {
+        url: "https://docs.example.com/policy-helper",
+        label: "Review configuration",
+    },
+    message: "The Policy Helper rejected the current configuration.",
+    previousPolicyRetained: true,
+    reason: "future-reason",
+    remediation: "Update the configuration and recheck managed policy.",
+    severity: "future-severity",
+} satisfies PolicyHelperFailure;
+
+const managedSettingsSnapshot = {
+    bypassPermissionsDisabled: true,
+    deviceManaged: false,
+    failClosed: true,
+    managedKeys: ["permissions"],
+    policyHelperCapabilities: {
+        recheck: true,
+        structuredFailure: true,
+    },
+    policyHelperFailure,
+    policyHelperManaged: true,
+    serverManaged: true,
+    source: "policyHelper",
+} satisfies ManagedSettingsResolvedData;
+
+describe("Policy Helper failure contracts", () => {
+    it("round trips the complete DTO and preserves future string values", () => {
+        const roundTripped = JSON.parse(
+            JSON.stringify(managedSettingsSnapshot)
+        ) as ManagedSettingsResolvedData;
+
+        expect(roundTripped.policyHelperCapabilities).toEqual({
+            recheck: true,
+            structuredFailure: true,
+        });
+        expect(roundTripped.policyHelperFailure).toEqual(policyHelperFailure);
+        expect(roundTripped.policyHelperFailure?.category).toBe("future-category");
+        expect(roundTripped.policyHelperFailure?.failureMode).toBe("future-mode");
+        expect(roundTripped.policyHelperFailure?.severity).toBe("future-severity");
+        expect(roundTripped.policyHelperFailure?.reason).toBe("future-reason");
+        expect(roundTripped.policyHelperFailure?.authority).toBe("future-authority");
+        expect(roundTripped.policyHelperFailure?.code).toBe("helper.future-code");
+    });
+
+    it("keeps older runtime snapshots compatible", () => {
+        const legacySnapshot: ManagedSettingsResolvedData = {
+            bypassPermissionsDisabled: false,
+            deviceManaged: false,
+            failClosed: false,
+            managedKeys: [],
+            serverManaged: false,
+            source: "none",
+        };
+
+        expect(legacySnapshot.policyHelperCapabilities).toBeUndefined();
+        expect(legacySnapshot.policyHelperFailure).toBeUndefined();
+    });
+
+    it("binds the session-scoped recheck RPC and returns its authoritative snapshot", async () => {
+        const sendRequest = vi.fn().mockResolvedValue(managedSettingsSnapshot);
+        const rpc = createSessionRpc(
+            { sendRequest } as unknown as MessageConnection,
+            "policy-session"
+        );
+
+        const result = await rpc.managedSettings.recheckPolicyHelper();
+
+        expect(sendRequest).toHaveBeenCalledWith("session.managedSettings.recheckPolicyHelper", {
+            sessionId: "policy-session",
+        });
+        expect(result.policyHelperCapabilities?.recheck).toBe(true);
+        expect(result.policyHelperFailure).toEqual(policyHelperFailure);
+    });
+
+    it("preserves Policy Helper context on policy-dependent activation errors", async () => {
+        const errorData = {
+            code: "plugin_activation_failed",
+            policyHelperFailure,
+        };
+        const responseError = new ResponseError(-32001, "plugin activation failed", errorData);
+        const sendRequest = vi.fn().mockRejectedValue(responseError);
+        const rpc = createServerRpc({ sendRequest } as unknown as MessageConnection);
+
+        const error = await rpc.managedSettings
+            .resolve({
+                workingDirectory: "/workspace",
+                policyHelperReason: "pluginActivation",
+            })
+            .then(
+                () => undefined,
+                (reason: unknown) => reason
+            );
+
+        expect(sendRequest).toHaveBeenCalledWith("managedSettings.resolve", {
+            workingDirectory: "/workspace",
+            policyHelperReason: "pluginActivation",
+        });
+        expect(error).toBe(responseError);
+        expect(responseError.code).toBe(-32001);
+        expect(responseError.message).toBe("plugin activation failed");
+        expect(responseError.data).toBe(errorData);
+        expect(responseError.data.policyHelperFailure).toBe(policyHelperFailure);
+    });
+});