docs: rename assign-to-copilot to copilot-cloud-agent, consolidate create-agent-session (#37149)

- Rename reference/assign-to-copilot.mdx → reference/copilot-cloud-agent.mdx
- Consolidate create-agent-session safe output docs into the new page alongside assign-to-agent
- New page title: 'Copilot Cloud Agent' covering both safe outputs with shared Auth section
- Add redirect /reference/assign-to-copilot/ → /gh-aw/reference/copilot-cloud-agent/ in astro.config.mjs
- Update sidebar label/link to 'Safe Outputs (Copilot Cloud Agent)'
- Fix all inbound links across safe-outputs.md, auth.mdx, glossary.md, staged-mode.md, safe-outputs-pull-requests.md, research-plan-assign-ops.md

Author: dsyme

docs/astro.config.mjs

@@ -94,6 +94,7 @@ export default defineConfig({
 		// Reference renames
 		'/reference/custom-agents/': '/gh-aw/reference/copilot-custom-agents/',
 		'/reference/custom-agent/': '/gh-aw/reference/custom-agent-for-aw/',
+		'/reference/assign-to-copilot/': '/gh-aw/reference/copilot-cloud-agent/',
 
 		// Organization Practices moved under Guides
 		'/organization-practices/': '/gh-aw/practices/organization-practices/',
@@ -416,7 +417,7 @@ export default defineConfig({
 						{ label: 'MCP Scripts', link: '/reference/mcp-scripts/' },
 						{ label: 'MCP Scripts (Spec)', link: '/reference/mcp-scripts-specification/' },
 						{ label: 'Safe Outputs', link: '/reference/safe-outputs/' },
-						{ label: 'Safe Outputs (Assign to Copilot)', link: '/reference/assign-to-copilot/' },
+						{ label: 'Safe Outputs (Copilot Cloud Agent)', link: '/reference/copilot-cloud-agent/' },
 						{ label: 'Safe Outputs (Custom)', link: '/reference/custom-safe-outputs/' },
 						{ label: 'Safe Outputs (Pull Requests)', link: '/reference/safe-outputs-pull-requests/' },
 						{ label: 'Safe Outputs (Spec)', link: '/reference/safe-outputs-specification/' },

docs/src/content/docs/patterns/research-plan-assign-ops.md

@@ -5,7 +5,7 @@ sidebar:
   badge: { text: 'Multi-phase', variant: 'caution' }
 ---
 
-ResearchPlanAssignOps is a four-phase development pattern that moves from automated discovery to merged code with human control at every decision point. A research agent surfaces insights, a planning agent converts them into actionable issues, a coding agent implements the work by [assigning issues to GitHub Copilot](/gh-aw/reference/assign-to-copilot/), and a human reviews and merges.
+ResearchPlanAssignOps is a four-phase development pattern that moves from automated discovery to merged code with human control at every decision point. A research agent surfaces insights, a planning agent converts them into actionable issues, a coding agent implements the work by [assigning issues to GitHub Copilot](/gh-aw/reference/copilot-cloud-agent/), and a human reviews and merges.
 
 ## The Four Phases
 
@@ -179,4 +179,4 @@ Prefer a simpler pattern when:
 - [DispatchOps](/gh-aw/patterns/dispatch-ops/) — Manually triggered research and one-off investigations
 - [WorkQueueOps](/gh-aw/patterns/workqueue-ops/) — Sequential queue processing for large backlogs
 - [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations
-- [Assign to Copilot](/gh-aw/reference/assign-to-copilot/) — Assigning issues to GitHub Copilot
+- [Copilot Cloud Agent](/gh-aw/reference/copilot-cloud-agent/) — Assigning issues to GitHub Copilot

docs/src/content/docs/reference/auth.mdx

@@ -34,7 +34,7 @@ Workflows using the following **read** operations from GitHub require [Additiona
 
 Workflows using the following features of [Safe Outputs](/gh-aw/reference/safe-outputs/) require additional authentication, via either a secret containing a PAT or GitHub App:
 - [**Safe outputs writing cross-repo**](/gh-aw/reference/safe-outputs/#cross-repository-operations)
-- [**Safe outputs assigning Copilot coding agent to issues/PRs**](/gh-aw/reference/assign-to-copilot/)
+- [**Safe outputs assigning Copilot coding agent to issues/PRs**](/gh-aw/reference/copilot-cloud-agent/)
 - [**Safe outputs updating GitHub Projects**](/gh-aw/patterns/project-ops/#project-token-authentication)
 - [**Safe outputs triggering CI on PRs**](/gh-aw/reference/triggering-ci/)
 

…ent/docs/reference/assign-to-copilot.mdx …t/docs/reference/copilot-cloud-agent.mdxdocs/src/content/docs/reference/assign-to-copilot.mdx renamed to docs/src/content/docs/reference/copilot-cloud-agent.mdx docs/src/content/docs/reference/assign-to-copilot.mdx renamed to docs/src/content/docs/reference/copilot-cloud-agent.mdx

@@ -1,21 +1,50 @@
 ---
-title: Assign to Copilot
-description: Programmatically assign GitHub Copilot coding agent to issues and pull requests
+title: Copilot Cloud Agent
+description: Spawn new Copilot cloud agent sessions and assign Copilot to issues and pull requests
 sidebar:
   order: 810
 ---
 
 import Video from '../../../components/Video.astro';
 
-This page describes how to programmatically assign the [GitHub Copilot coding agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) to issues or pull requests using the `assign-to-agent` safe output. This automates the [standard GitHub workflow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot).
+This page covers two safe outputs for invoking the [GitHub Copilot cloud agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) from workflows:
 
-## When to Use
+- **[`create-agent-session`](#create-agent-session)** — Spawn a new Copilot agent session to work on a task
+- **[`assign-to-agent`](#assign-to-agent)** — Assign Copilot to an existing issue or pull request
 
-Use `assign-to-agent` when you need to programmatically assign Copilot coding agent to **existing** issues or PRs through workflow automation.
+Both safe outputs require a fine-grained PAT — see [Authentication](#authentication) below.
 
-If you're creating new issues and want to assign Copilot coding agent immediately, use `assignees: copilot` in your [`create-issue`](/gh-aw/reference/safe-outputs/#issue-creation-create-issue) configuration instead.
+## Create Agent Session
 
-## Configuration
+Creates a new Copilot coding agent session from workflow output, allowing a workflow to spawn follow-up work autonomously. The agent session appears as a GitHub issue that triggers Copilot to implement the described task and open a pull request.
+
+### Configuration
+
+```yaml wrap
+safe-outputs:
+  create-agent-session:
+    base: "main"                 # base branch for agent session PR
+    max: 1                       # max sessions (default: 1, maximum: 10)
+    target-repo: "owner/repo"    # cross-repository
+    allowed-repos: ["org/repo1", "org/repo2"]  # additional allowed repositories
+    github-token: ${{ secrets.GH_AW_AGENT_TOKEN }} # token for permissions
+```
+
+### Cross-Repository
+
+`create-agent-session` supports `target-repo` and `allowed-repos` for cross-repository use but does **not** support `target-repo: "*"` — use an explicit `owner/repo` value or `allowed-repos` instead.
+
+## Assign to Agent
+
+Programmatically assigns the GitHub Copilot coding agent to **existing** issues or pull requests through workflow automation. This automates the [standard GitHub workflow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot).
+
+### When to Use
+
+Use `assign-to-agent` when you need to programmatically assign Copilot to **existing** issues or PRs.
+
+If you're creating new issues and want to assign Copilot immediately, use `assignees: copilot` in your [`create-issue`](/gh-aw/reference/safe-outputs/#issue-creation-create-issue) configuration instead.
+
+### Configuration
 
 ```yaml wrap
 safe-outputs:
@@ -36,27 +65,27 @@ safe-outputs:
 
 **Supported agents:** `copilot` (`copilot-swe-agent`)
 
-## Target Issue or Pull Request
+### Target Issue or Pull Request
 
 The `target` parameter determines which issue or PR to assign the agent to:
 
 - `target: "triggering"` (default) - Auto-resolves from `github.event.issue.number` or `github.event.pull_request.number`
 - `target: "*"` - Requires explicit `issue_number` or `pull_number` in agent output
 - `target: "123"` - Always uses issue/PR #123
 
-## Cross-Repository PR Creation
+### Cross-Repository PR Creation
 
 Use `pull-request-repo` to create pull requests in a different repository than where the issue lives — useful when issues are tracked centrally but code lives elsewhere. The issue repository is determined by `target-repo` or defaults to the workflow's repository.
 
 `pull-request-repo` is automatically included in the allowed list; use `allowed-pull-request-repos` for additional repositories. Use `base-branch` to target a specific branch (defaults to the target repo's default branch).
 
-## Assignee Filtering
+### Assignee Filtering
 
 When an `allowed` list is configured, existing agent assignees not in the list are removed while regular user assignees are preserved.
 
 ## Authentication
 
-This safe output requires a fine-grained PAT to authenticate the agent assignment operation. The default `GITHUB_TOKEN` lacks the necessary permissions.
+Both safe outputs require a fine-grained PAT. The default `GITHUB_TOKEN` lacks the necessary permissions.
 
 ### Using a Personal Access Token (PAT)
 

docs/src/content/docs/reference/glossary.md

@@ -234,11 +234,11 @@ A safe output capability for removing labels from issues or pull requests. Suppo
 
 ### Assign to Agent
 
-A safe output capability (`assign-to-agent:`) that programmatically assigns the GitHub Copilot coding agent to existing issues or pull requests. Automates the standard GitHub workflow for delegating implementation tasks to Copilot. Supports cross-repository PR creation via `pull-request-repo` and agent model selection via `model`. See [Assign to Copilot](/gh-aw/reference/assign-to-copilot/).
+A safe output capability (`assign-to-agent:`) that programmatically assigns the GitHub Copilot coding agent to existing issues or pull requests. Automates the standard GitHub workflow for delegating implementation tasks to Copilot. Supports cross-repository PR creation via `pull-request-repo` and agent model selection via `model`. See [Copilot Cloud Agent](/gh-aw/reference/copilot-cloud-agent/).
 
 ### GH_AW_AGENT_TOKEN
 
-A recognized "magic" repository secret name that GitHub Agentic Workflows automatically uses as a fallback Personal Access Token for `assign-to-agent` operations. When set, no explicit `github-token:` reference is needed in workflow frontmatter — the token is injected automatically. Required because GitHub App installation tokens are rejected by the Copilot assignment API. The token fallback chain is: `assign-to-agent.github-token` → `safe-outputs.github-token` → `GH_AW_AGENT_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN`. See [Assign to Copilot](/gh-aw/reference/assign-to-copilot/).
+A recognized "magic" repository secret name that GitHub Agentic Workflows automatically uses as a fallback Personal Access Token for `assign-to-agent` operations. When set, no explicit `github-token:` reference is needed in workflow frontmatter — the token is injected automatically. Required because GitHub App installation tokens are rejected by the Copilot assignment API. The token fallback chain is: `assign-to-agent.github-token` → `safe-outputs.github-token` → `GH_AW_AGENT_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN`. See [Copilot Cloud Agent](/gh-aw/reference/copilot-cloud-agent/).
 
 ### Custom Safe Outputs
 

docs/src/content/docs/reference/safe-outputs-pull-requests.md

@@ -323,7 +323,7 @@ safe-outputs:
 
 **Target**: `"triggering"` (requires PR event), `"*"` (any PR), or number (specific PR).
 
-Use `allowed-reviewers: [copilot]` to assign the Copilot PR reviewer bot. See [Assign to Agent](/gh-aw/reference/assign-to-copilot/).
+Use `allowed-reviewers: [copilot]` to assign the Copilot PR reviewer bot. See [Copilot Cloud Agent](/gh-aw/reference/copilot-cloud-agent/).
 
 ## Compile-Time Warnings for `target: "*"`
 

docs/src/content/docs/reference/safe-outputs.md

@@ -72,7 +72,7 @@ The agent requests issue creation; a separate job with `issues: write` creates i
 - [**Dispatch Repository Event**](#repository-dispatch-dispatch_repository) (`dispatch_repository`) - Trigger `repository_dispatch` events in external repositories, experimental (cross-repo)
 - [**Code Scanning Alerts**](#code-scanning-alerts-create-code-scanning-alert) (`create-code-scanning-alert`) - Generate SARIF security advisories (max: unlimited, same-repo only)
 - [**Autofix Code Scanning Alerts**](#autofix-code-scanning-alerts-autofix-code-scanning-alert) (`autofix-code-scanning-alert`) - Create automated fixes for code scanning alerts (max: 10, same-repo only)
-- [**Create Agent Session**](#agent-session-creation-create-agent-session) (`create-agent-session`) - Create Copilot coding agent sessions (max: 1)
+- [**Create Agent Session**](/gh-aw/reference/copilot-cloud-agent/#create-agent-session) (`create-agent-session`) - Create Copilot coding agent sessions (max: 1)
 
 ### System Types (Auto-Enabled)
 
@@ -1311,6 +1311,8 @@ safe-outputs:
     github-token: ${{ secrets.SOME_CUSTOM_TOKEN }} # optional custom token for permissions
 ```
 
+See **[Copilot Cloud Agent](/gh-aw/reference/copilot-cloud-agent/#create-agent-session)** for full details and authentication setup.
+
 ### Assign to Agent (`assign-to-agent:`)
 
 Programmatically assigns GitHub Copilot coding agent to **existing** issues or pull requests through workflow automation. This safe output automates the [standard GitHub workflow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot).
@@ -1332,7 +1334,7 @@ safe-outputs:
     github-token: ${{ secrets.SOME_CUSTOM_TOKEN }} # optional custom token for permissions
 ```
 
-See **[Assign to Copilot](/gh-aw/reference/assign-to-copilot/)** for complete configuration options and authorization setup.
+See **[Copilot Cloud Agent](/gh-aw/reference/copilot-cloud-agent/#assign-to-agent)** for complete configuration options and authorization setup.
 
 If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](#issue-creation-create-issue) configuration instead.
 

docs/src/content/docs/reference/staged-mode.md

@@ -105,7 +105,7 @@ Staged mode is supported by all built-in safe output types:
 | [`dispatch-workflow`](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) | Target workflow, inputs |
 | [`assign-to-agent`](/gh-aw/reference/safe-outputs/#assign-to-agent-assign-to-agent) | Target issue/PR |
 | [`assign-to-user`](/gh-aw/reference/safe-outputs/#assign-to-user-assign-to-user) | Target item, user |
-| [`create-agent-session`](/gh-aw/reference/safe-outputs/#agent-session-creation-create-agent-session) | Session details |
+| [`create-agent-session`](/gh-aw/reference/copilot-cloud-agent/#create-agent-session) | Session details |
 
 [Custom safe output jobs](/gh-aw/reference/custom-safe-outputs/) receive the `GH_AW_SAFE_OUTPUTS_STAGED` environment variable set to `"true"` when staged mode is active, allowing you to implement your own preview behavior.