github · pelikhan · Jun 3, 2026 · Jun 3, 2026 · Jun 3, 2026 · Jun 3, 2026
diff --git a/.github/workflows/daily-ambient-context-optimizer.lock.yml b/.github/workflows/daily-ambient-context-optimizer.lock.yml
diff --git a/.github/workflows/deep-report.lock.yml b/.github/workflows/deep-report.lock.yml
diff --git a/docs/src/content/docs/reference/copilot-sdk-driver-specification.md b/docs/src/content/docs/reference/copilot-sdk-driver-specification.md
@@ -7,7 +7,7 @@ sidebar:
 
 # Copilot SDK Driver Specification
 
-**Version**: 1.0.0  
+**Version**: 1.0.1  
 **Status**: Draft Specification  
 **Latest Version**: [copilot-sdk-driver-specification](/gh-aw/reference/copilot-sdk-driver-specification/)  
 **Editor**: GitHub Agentic Workflows Team
@@ -16,7 +16,7 @@ sidebar:
 
 ## Abstract
 
-This specification defines the normative behavior of a Copilot SDK driver that runs an agent session against a Copilot SDK endpoint and emits session telemetry. The specification is language agnostic and focuses on environment variable contracts, permission-checking policy, and required logging behavior. Non-normative examples use TypeScript. Conforming implementations provide deterministic permission enforcement, auditable diagnostics, and interoperable runtime behavior across host environments.
+This specification defines the normative behavior of a Copilot SDK driver that runs an agent session against a Copilot SDK endpoint and emits session telemetry. The specification is language agnostic and focuses on environment variable contracts, permission-checking policy, required logging behavior, and connection-token propagation between the harness-managed sidecar and the driver. Non-normative examples use TypeScript. Conforming implementations provide deterministic permission enforcement, auditable diagnostics, and interoperable runtime behavior across host environments.
 
 ## Status of This Document
 
@@ -116,6 +116,15 @@ A conforming implementation MUST execute the following sequence:
 
 A complete implementation (Level 3) SHOULD serialize non-ephemeral session events to a JSON Lines stream compatible with downstream timeline rendering.
 
+### 3.4 Harness Connection Token Flow
+
+When SDK mode is enabled (`COPILOT_SDK_URI` is set), the harness MUST generate a per-run `COPILOT_CONNECTION_TOKEN` and MUST pass the same token value to both:
+
+1. The harness-managed Copilot sidecar process
+2. The SDK driver subprocess environment
+
+The SDK driver MUST treat `COPILOT_CONNECTION_TOKEN` as a required input and MUST fail fast with non-zero exit when it is missing.
+
 ---
 
 ## 4. Configuration and Environment Variables
@@ -124,21 +133,32 @@ A complete implementation (Level 3) SHOULD serialize non-ephemeral session event
 
 In standalone mode, the implementation MUST enforce the following contract:
 
-| Variable | Required | Description | Default / Validation |
-| --- | --- | --- | --- |
-| `GH_AW_PROMPT` | Yes | Path to prompt file | MUST exist and be readable |
-| `COPILOT_SDK_URI` | Yes | SDK endpoint URI | MUST be non-empty |
-| `COPILOT_CONNECTION_TOKEN` | Yes | Shared connection token | MUST be non-empty |
-| `COPILOT_MODEL` | No | Model override | OPTIONAL |
-| `COPILOT_SDK_SEND_TIMEOUT_MS` | No | Send timeout in milliseconds | Input SHOULD be a positive integer; default `600000`; implementations MUST fall back on invalid values |
-| `COPILOT_SDK_LOG_LEVEL` | No | SDK client log level | Valid values: `none`, `error`, `warning`, `info`, `debug`, `all`; invalid values MUST fall back to `warning` |
-| `GITHUB_WORKSPACE` | No | Working directory hint | SHOULD be used when present |
+| Variable                      | Required | Description                                               | Default / Validation                                                                                         |
+| ----------------------------- | -------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `GH_AW_PROMPT`                | Yes      | Path to prompt file                                       | MUST exist and be readable                                                                                   |
+| `COPILOT_SDK_URI`             | Yes      | SDK endpoint URI                                          | MUST be non-empty                                                                                            |
+| `COPILOT_CONNECTION_TOKEN`    | Yes      | Per-run shared token generated by the harness in SDK mode | MUST be non-empty in the driver environment                                                                  |
+| `COPILOT_MODEL`               | No       | Model override                                            | OPTIONAL                                                                                                     |
+| `COPILOT_SDK_SEND_TIMEOUT_MS` | No       | Send timeout in milliseconds                              | Input SHOULD be a positive integer; default `600000`; implementations MUST fall back on invalid values       |
+| `COPILOT_SDK_LOG_LEVEL`       | No       | SDK client log level                                      | Valid values: `none`, `error`, `warning`, `info`, `debug`, `all`; invalid values MUST fall back to `warning` |
+| `GITHUB_WORKSPACE`            | No       | Working directory hint                                    | SHOULD be used when present                                                                                  |
+
+### 4.2 Connection Token Requirement
 
-### 4.2 Timeout Environment Variable
+`COPILOT_CONNECTION_TOKEN` is a harness-generated per-run secret used by the SDK driver to authenticate to the harness-managed sidecar session.
+
+In SDK mode, a conforming implementation:
+
+- MUST generate a token value with sufficient entropy for local authentication.
+- MUST propagate the same token to sidecar and driver processes for a given run.
+- MUST require the token in the driver process environment before creating `RuntimeConnection`.
+- MUST NOT log the raw token value.
+
+### 4.3 Timeout Environment Variable
 
 `COPILOT_SDK_SEND_TIMEOUT_MS` controls maximum send wait duration for prompt completion in standalone mode. Implementations MUST treat this value as milliseconds and MUST apply the default value (`600000`) when unset, non-numeric, or non-positive.
 
-### 4.3 TypeScript Example (Non-Normative)
+### 4.4 TypeScript Example (Non-Normative)
 
 Prerequisite: install [`@github/copilot-sdk`](https://www.npmjs.com/package/@github/copilot-sdk) in the runtime where this example executes.
 
@@ -320,6 +340,7 @@ Implementations MUST provide automated tests for all Level 1 and Level 2 require
 - **T-CSD-004**: Invalid log level falls back to `warning`.
 - **T-CSD-005**: Unset `COPILOT_SDK_SEND_TIMEOUT_MS` falls back to default `600000`.
 - **T-CSD-006**: Non-numeric or non-positive `COPILOT_SDK_SEND_TIMEOUT_MS` falls back to default `600000`.
+- **T-CSD-007**: In SDK mode, harness and driver receive the same non-empty `COPILOT_CONNECTION_TOKEN`, and token values are not logged.
 
 #### 8.1.2 Permission Tests
 
@@ -342,18 +363,19 @@ Implementations MUST provide automated tests for all Level 1 and Level 2 require
 
 ### 8.2 Compliance Checklist
 
-| Requirement | Test ID | Level | Status |
-| --- | --- | --- | --- |
-| Required standalone variables enforced | T-CSD-001..003 | 1 | Required |
-| Log-level and timeout fallback behavior | T-CSD-004..006 | 1 | Required |
-| Default permission delegation | T-CSD-101 | 2 | Required |
-| Allow-all permission behavior | T-CSD-102 | 2 | Required |
-| Scoped `read` default-deny and explicit allow | T-CSD-103..104 | 2 | Required |
-| Scoped write/url/custom-tool enforcement | T-CSD-105..107 | 2 | Required |
-| Scoped MCP/shell enforcement | T-CSD-108..109 | 2 | Required |
-| Unknown-kind rejection | T-CSD-110 | 2 | Required |
-| Permission denial diagnostics | T-CSD-111, T-CSD-202 | 2 | Required |
-| Lifecycle logging coverage | T-CSD-201 | 3 | Recommended |
+| Requirement                                   | Test ID              | Level | Status      |
+| --------------------------------------------- | -------------------- | ----- | ----------- |
+| Required standalone variables enforced        | T-CSD-001..003       | 1     | Required    |
+| Connection token generation and propagation   | T-CSD-007            | 1     | Required    |
+| Log-level and timeout fallback behavior       | T-CSD-004..006       | 1     | Required    |
+| Default permission delegation                 | T-CSD-101            | 2     | Required    |
+| Allow-all permission behavior                 | T-CSD-102            | 2     | Required    |
+| Scoped `read` default-deny and explicit allow | T-CSD-103..104       | 2     | Required    |
+| Scoped write/url/custom-tool enforcement      | T-CSD-105..107       | 2     | Required    |
+| Scoped MCP/shell enforcement                  | T-CSD-108..109       | 2     | Required    |
+| Unknown-kind rejection                        | T-CSD-110            | 2     | Required    |
+| Permission denial diagnostics                 | T-CSD-111, T-CSD-202 | 2     | Required    |
+| Lifecycle logging coverage                    | T-CSD-201            | 3     | Recommended |
 
 ---
 
@@ -370,12 +392,12 @@ Implementations MUST provide automated tests for all Level 1 and Level 2 require
 
 ### Appendix B: Error Conditions
 
-| Condition | Required Behavior |
-| --- | --- |
-| Missing required standalone variable | Log error and exit non-zero |
-| Prompt file unreadable | Log error and exit non-zero |
-| Permission denied | Reject request and log denial summary |
-| Session runtime error | Return failure result and log error summary |
+| Condition                            | Required Behavior                           |
+| ------------------------------------ | ------------------------------------------- |
+| Missing required standalone variable | Log error and exit non-zero                 |
+| Prompt file unreadable               | Log error and exit non-zero                 |
+| Permission denied                    | Reject request and log denial summary       |
+| Session runtime error                | Return failure result and log error summary |
 
 ### Appendix C: Security Considerations
 
@@ -406,6 +428,12 @@ A conforming implementation SHOULD:
 
 ## 11. Change Log
 
+### Version 1.0.1 (Draft Specification)
+
+- Added normative connection-token flow requirements based on harness SDK mode behavior.
+- Clarified that `COPILOT_CONNECTION_TOKEN` is harness-generated and required in the driver environment.
+- Added compliance test coverage for token propagation and non-disclosure in logs.
+
 ### Version 1.0.0 (Draft Specification)
 
 - Added initial formal specification for Copilot SDK driver behavior.