Document Copilot SDK mode and custom Copilot command behavior

docs/src/content/docs/agent-factory-status.mdx

@@ -57,6 +57,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn,
 | [Daily Agent of the Day Blog Writer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-agent-of-the-day-blog-writer.md) | copilot | [![Daily Agent of the Day Blog Writer](https://github.com/github/gh-aw/actions/workflows/daily-agent-of-the-day-blog-writer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-agent-of-the-day-blog-writer.lock.yml) | - | - |
 | [Daily Agentic Workflow Token Usage Audit](https://github.com/github/gh-aw/blob/main/.github/workflows/agentic-token-audit.md) | copilot | [![Daily Agentic Workflow Token Usage Audit](https://github.com/github/gh-aw/actions/workflows/agentic-token-audit.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/agentic-token-audit.lock.yml) | `daily around 12:00 on weekdays` | - |
 | [Daily AgentRx Trace Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-agentrx-trace-optimizer.md) | claude | [![Daily AgentRx Trace Optimizer](https://github.com/github/gh-aw/actions/workflows/daily-agentrx-trace-optimizer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-agentrx-trace-optimizer.lock.yml) | - | - |
+| [Daily Ambient Context Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-ambient-context-optimizer.md) | copilot | [![Daily Ambient Context Optimizer](https://github.com/github/gh-aw/actions/workflows/daily-ambient-context-optimizer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-ambient-context-optimizer.lock.yml) | - | - |
 | [Daily AstroStyleLite Markdown Spellcheck](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-astrostylelite-markdown-spellcheck.md) | claude | [![Daily AstroStyleLite Markdown Spellcheck](https://github.com/github/gh-aw/actions/workflows/daily-astrostylelite-markdown-spellcheck.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-astrostylelite-markdown-spellcheck.lock.yml) | - | - |
 | [Daily AW Cross-Repo Compile Check](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-aw-cross-repo-compile-check.md) | claude | [![Daily AW Cross-Repo Compile Check](https://github.com/github/gh-aw/actions/workflows/daily-aw-cross-repo-compile-check.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-aw-cross-repo-compile-check.lock.yml) | - | - |
 | [Daily BYOK Ollama Test](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-byok-ollama-test.md) | copilot | [![Daily BYOK Ollama Test](https://github.com/github/gh-aw/actions/workflows/daily-byok-ollama-test.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-byok-ollama-test.lock.yml) | - | - |

docs/src/content/docs/reference/engines.md

@@ -112,6 +112,42 @@ engine:
 
 See [Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) for details.
 
+### Copilot SDK Mode (`copilot-sdk`)
+
+Set `copilot-sdk: true` on the Copilot engine to run the workflow through the Copilot SDK instead of sending the prompt only through the CLI wrapper.
+
+GitHub Agentic Workflows preserves `engine.id: copilot`, starts a headless Copilot CLI sidecar, installs `@github/copilot-sdk`, and connects the workflow to that sidecar through `COPILOT_SDK_URI`.
+
+```yaml wrap
+engine:
+  id: copilot
+  copilot-sdk: true
+```
+
+Use this mode when you need SDK-backed session handling, SDK event capture, or behavior that depends on the Copilot SDK driver contract.
+
+> [!NOTE]
+> `copilot-sdk` is an experimental Copilot-only setting. It does not change the engine ID to `copilot-sdk`.
+
+### Custom Copilot SDK Driver
+
+In `copilot-sdk` mode, the built-in Copilot harness starts the headless sidecar and runs the bundled `copilot_sdk_driver.cjs` program as the default SDK driver. If you need different startup behavior or want to supply your own driver flow, set `engine.harness` to a custom Node.js harness script and keep `copilot-sdk: true`.
+
+```yaml wrap
+engine:
+  id: copilot
+  copilot-sdk: true
+  harness: custom_copilot_harness.cjs
+```
+
+Your custom harness must use a filename ending in `.js`, `.cjs`, or `.mjs`. Do not include path separators, `..`, or shell metacharacters.
+
+These restrictions keep the harness selection safe for sandboxed execution and prevent path traversal or shell injection through workflow configuration. Valid examples include `my_harness.cjs` and `custom-sdk-driver.mjs`. Invalid examples include `../harness.js` and `harness;rm.cjs`.
+
+In SDK mode, the custom harness is responsible for preserving the Copilot SDK sidecar lifecycle and passing the workflow through the expected driver environment.
+
+For the built-in driver contract, required environment variables, permission handling rules, and logging requirements, see [Copilot SDK Driver Specification](/gh-aw/reference/copilot-sdk-driver-specification/).
+
 ### Engine Environment Variables
 
 All engines support custom environment variables through the `env` field: