copilot-cli-subsession

# Invoke Copilot CLI Sub-Session Use this skill when a main session (in Copilot CLI or VS Code) needs to spawn a **fresh, isolated Copilot CLI sub-session** with full control over its identity and runtime. ## When to use - Run a long or risky sub-workflow in a separate process that does not pollute the main session context. - Pin a specific **custom agent** to the sub-session. - Pin a specific **BYOK provider / model** for the sub-session (default: `opencode-go-deepseek-v4-flash`, reasoning-effort `high`; per-model levels are grounded in the `copilot-byok` skill's [`references/shared/reasoning-effort-lookup.md`](../copilot-byok/references/shared/reasoning-effort-lookup.md)). - Self-generate a **session name** (`--name`) and **session UUID** (`--session-id`) so the main session can send follow-up prompts to the same sub-session. - Capture structured output (text or JSONL) for programmatic parsing. ## What it produces - A PowerShell script: `scripts/Invoke-CopilotCliSubSession.ps1`. - This skill guides the agent to call that script with the correct parameters. The agent should proactively assign a descriptive `-Name` in kebab-case. - By default the sub-session **inherits** the main session's MCP servers and custom instructions (same working directory, same `~/.copilot/`). ## Quick start ```powershell # Minimal invocation — uses default BYOK profile (opencode-go-deepseek-v4-flash) at reasoning-effort high .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "analyze-async" ` -Prompt "Analyze the project structure and list all async methods." # Specific agent, model override, named session, multi-line prompt .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "security-audit" ` -Agent "security-auditor" ` -Model "claude-opus-4.5" ` -SessionId "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ` -Prompt @" Review the codebase for security vulnerabilities: 1. Check for SQL injection in data access layer 2. Audit authentication middleware 3. Verify CSRF protection is active 4. Report findings with severity levels "@ # Invoke a built-in command or skill via slash command .\scripts\Invoke-CopilotCliSubSession.ps1 ` -SlashCommand "handoff" ` -Prompt "Describe the current session state" ` -Name "session-handoff" # Invoke a skill without extra prompt .\scripts\Invoke-CopilotCliSubSession.ps1 ` -SlashCommand "git-atomic-commit" ` -Name "auto-commit" # Invoke with a custom agent .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Agent "dotnet-diag:optimizing-dotnet-performance" ` -Name "perf-analysis" ` -Prompt "Scan for async anti-patterns" # Context handoff: list relevant file paths; sub-session reads them itself .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "exec-plan" ` -Prompt @" Execute the implementation plan at: c:/Workplace/my-repo/openspec/changes/auth-impl/plan.md c:/Workplace/my-repo/openspec/changes/auth-impl/tasks.md Reference specs: c:/Workplace/my-repo/openspec/specs/auth/spec.md Working directory: c:/Workplace/my-repo Read each file before executing. Report progress after each step. "@ # Chain two prompts on the same sub-session by reusing SessionId $uuid = "b2c3d4e5-f6a7-8901-bcde-f12345678901" $r1 = .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "research-auth" ` -SessionId $uuid ` -Prompt "Research this repo's authentication approach." ` -JsonOutput $r2 = .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "research-auth" ` -SessionId $uuid ` -Prompt "Based on the research, propose three security improvements." ` -JsonOutput ``` ## Required vs optional parameters | Parameter | Required | Default | Purpose | |-----------|----------|---------|---------| | `-SlashCommand` | No | — | Built-in command or skill name to invoke (e.g., `handoff`, `git-atomic-commit`, `plan`, `review`). Script prepends `/`. When given with `-Prompt`, the prompt becomes the command argument. **At least one of `-SlashCommand` or `-Prompt` is required.** | | `-Prompt` | No* | — | The task prompt, or argument to `-SlashCommand` when both are given. Supports multi-line (here-strings, `` `n ``, literal newlines). \*Required when `-SlashCommand` is not provided. | | `-Name` | No | — | Human-readable session name (`--name`). Use kebab-case slugs (e.g. `"analyze-async"`). The agent should proactively generate one. | | `-SessionId` | No | auto-generated UUID | Custom UUID for `--session-id`. Must be valid UUID format. When omitted, a UUID is auto-generated. Reuse the same value across calls to chain messages on the same session. | | `-Agent` | No | — | Custom agent name. Qualify plugin agents as `plugin:agent-name` (colon, e.g. `dotnet-diag:optimizing-dotnet-performance`). Repo agents use bare name. | | `-Model` | No | — | Model override. Takes precedence over the BYOK profile's model. | | `-ByokProfile` | No | `opencode-go-deepseek-v4-flash` | BYOK profile name from `~/.copilot/byok-profiles.json`. | | `-ByokAccount` | No | — | Account override for account-grouped profiles (e.g., multiple OpenCode Go subscriptions). Takes precedence over the profile's `account` pin and the config-level `activeAccount`. When omitted, the profile pin or `activeAccount` is used. | | `-CopilotHome` | No | — | **Staging `COPILOT_HOME`** for the sub-process — the explicit opt-in to full config isolation (CLI 1.0.77+: `--config-dir` was removed; `COPILOT_HOME` is the supported override). The **first time** this path is used, the script seeds a minimal staging tree from production `~/.copilot`: `byok-profiles.json` (required) plus `mcp-config.json` when present. Seeding runs **once only** — afterwards production and staging are fully independent; staging is durable and never re-seeded or auto-cleaned (delete the tree manually to reset). Default: production `~/.copilot` (no isolation). Alias: `-ConfigDir` (deprecated). | | `-ReasoningEffort` | No | `high` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (per-model subset may vary; `minimal` is newer — verified in CLI 1.0.77). The default BYOK profile (`opencode-go-deepseek-v4-flash`) runs at `high` by default. For the grounded per-model lookup — which levels a model supports and whether to omit the flag — see the `copilot-byok` skill's [`references/shared/reasoning-effort-lookup.md`](../copilot-byok/references/shared/reasoning-effort-lookup.md). | | `-WorkingDir` | No | current location | Working directory for the sub-process. | | `-JsonOutput` | Switch | off | Emit JSONL instead of plain text. | | `-NoAllowAll` | Switch | off | Opt out of `--allow-all --no-ask-user`. By default the sub-session runs with full permissions. | | `-DisableBuiltInMcps` | Switch | off | Isolate from main session's MCP servers. | | `-NoCustomInstructions` | Switch | off | Skip project custom instructions. | | `-TimeoutSeconds` | No | `600` | Kill the sub-process after N seconds. | | `-Passthrough` | No | — | Extra arguments forwarded to `copilot`. | ## Session naming (`-Name`) The agent should always assign a meaningful `-Name` in **kebab-case** that describes the sub-session's purpose: - `"research-csrf-patterns"` — a research task - `"implement-oauth-middleware"` — an implementation task - `"review-pr-142"` — a review task This name appears in `copilot --resume` listings and session logs. It is distinct from `-SessionId` (the UUID used for programmatic chaining). Pass both: `-Name` for human readability, `-SessionId` for script-level chaining. ## Choosing a session ID - **Auto-generated**: when `-SessionId` is omitted, a valid UUID is auto-generated using `New-Guid`. Every call gets a fresh session unless you reuse the same UUID. - **Explicit UUID**: pass a valid UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). Invalid UUIDs trigger a warning and are replaced with an auto-generated one. - **Follow-up to the same sub-session**: reuse the exact same `-SessionId` value; the prior session state is reloaded via `--session-id`. - **Valid UUIDs only**: `--session-id` requires standard format (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). ## Multi-line prompts `-Prompt` accepts multi-line strings natively. Use PowerShell here-strings for multi-paragraph task descriptions: ```powershell .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "code-review" ` -Prompt @" Review the following PR checklist: 1. Verify all edge cases are covered 2. Check for proper error handling 3. Ensure tests pass with >80% coverage 4. Validate API contract changes Report findings in a markdown table. "@ ``` Inline newlines via `` `n `` also work: `-Prompt "Line 1`nLine 2`nLine 3"`. ## Slash command invocation (`-SlashCommand`) `-SlashCommand` wraps Copilot CLI's interactive slash commands for non-interactive use. Pass just the command name (no leading `/`) — the script prepends `/` automatically. **Supported commands**: Any built-in CLI command (`help`, `init`, `diff`, `pr`, `review`, `plan`, `research`, `delegate`, `rewind`, `compact`, `share`, `allow-all`, `add-dir`, `skills`) and any installed skill (`git-atomic-commit`, `handoff`, `mermaid-creator`, etc.). > ⚠️ **`model` is excluded from reliable non-interactive use** (verified CLI 1.0.77, 2026-08-03, **BYOK/custom-provider routing**). `-p "/model X"` forwards the text to the *current* model as a prompt — it roleplays the switch and the backend never changes (`model.call_start` stays the same in JSONL). > ⚠️ **Scope of this finding**: the roleplay behavior was verified with **BYOK** (custom provider, e.g. OpenCode Go). For **GitHub Copilot Subscription** models it is **unverified** — do not assume `-p "/model X"` is roleplay there, since model selection routes through the GitHub platform rather than a custom endpoint. The only verified in-session switch is the interactive TUI `/model` picker (emits `session.model_change`); the only verified programmatic switch is `-Model` / `--model` at process start (e.g. `-Model kimi-k2.7-code`), which switches the real backend. ```powershell # Slash command only .\scripts\Invoke-CopilotCliSubSession.ps1 -SlashCommand "plan" -Name "planning-pass" # Slash command with arguments (Prompt becomes the argument) .\scripts\Invoke-CopilotCliSubSession.ps1 -SlashCommand "handoff" -Prompt "Describe session results" -Name "handoff-pass" # Equivalent freeform prompt (also valid) .\scripts\Invoke-CopilotCliSubSession.ps1 -Prompt "/handoff Describe session results" -Name "handoff-pass" ``` **Multi-step orchestration pattern**: ```powershell # Plan → Execute → Review with slash commands .\scripts\Invoke-CopilotCliSubSession.ps1 -SlashCommand "plan" -Prompt "Implement user auth" -Name "plan-auth" -SessionId $uuid .\scripts\Invoke-CopilotCliSubSession.ps1 -Prompt "Execute the plan above" -Name "exec-auth" -SessionId $uuid .\scripts\Invoke-CopilotCliSubSession.ps1 -SlashCommand "review" -Name "review-auth" -SessionId $uuid ``` ## Custom agent invocation (`-Agent`) Pin a specific agent to the sub-session. Plugin agents use **colon**: `plugin:agent-name`. Repo agents use bare name. ```powershell # Plugin agent .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Agent "dotnet-diag:optimizing-dotnet-performance" ` -Prompt "Analyze this project's performance" ` -Name "perf-analysis" # Repo agent (discovered from .github/agents/) .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Agent "my-custom-agent" ` -Prompt "Execute the workflow" ` -Name "custom-workflow" ``` Agent discovery paths (in precedence order): 1. `~/.copilot/agents/` (user-level) 2. `.github/agents/` (repo-level) 3. `plugin:agent-name` (qualified, from installed plugins) The agent is invoked via the Copilot CLI `--agent` flag and inherits the sub-session's model, BYOK config, and all other parameters. ## Context handoff convention When delegating to a sub-session, **always prioritize listing the full absolute paths of relevant files** in `-Prompt`. The sub-session can read those files itself using its own tools (`cat`, `grep`, `read`). Only embed content inline when the context is short and simple enough to fit in a single message. ### Why - The sub-session starts with a blank context — it does not know what files the main session worked with, what decisions were made, or what artifacts exist. - MCP and custom instructions inheritance provides *environment* (tools, config), not *session memory*. - Listing file paths is cheaper, avoids duplication, and lets the sub-session choose what to read in depth. ### Do this ```powershell # PREFERRED — list full paths; sub-session reads files itself .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "exec" ` -Prompt @" Execute the implementation plan at: c:/Workplace/my-repo/openspec/changes/auth-impl/plan.md c:/Workplace/my-repo/openspec/changes/auth-impl/tasks.md Reference specs: c:/Workplace/my-repo/openspec/specs/auth/spec.md Start from working directory: c:/Workplace/my-repo After each step, report progress. "@ # EXCEPTION — directly embed only when context is short and simple .\scripts\Invoke-CopilotCliSubSession.ps1 ` -Name "quick-fix" ` -Prompt "Fix the typo in src/utils/helpers.ts line 42: change 'teh' to 'the'." ``` ### Practical workflow 1. Identify the relevant files from the main session (plan, research, spec, ADR, design doc, task list). 2. List their **full absolute paths** in the `-Prompt` argument, grouped by role. 3. Include the **working directory** and the **final instruction** — what the sub-session should produce. 4. Only embed content inline (via here-string) when the context is trivially short (a few lines). 5. Use the returned `SessionId` to chain follow-up messages if the task requires multiple turns. ### What to reference | Context type | Files to reference by path | |--------------|----------------------------| | Implementation plan | `openspec/changes/*/plan.md`, `openspec/changes/*/tasks.md` |