/troubleshoot

name: troubleshoot
description: Investigate unexpected behavior in the current Copilot CLI agent session by analyzing its event log. Use when the user asks why something happened, why a request was slow, why a tool was or was not used, or why instructions/skills/agents did not load.

<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->

Troubleshoot

Purpose

This skill investigates and explains unexpected agent behavior in the **current Copilot CLI agent session** using its on-disk event log.

Use this skill for questions like:

• Why did this request take so long?
• Why was a tool called (or not called)?
• Why did an instruction/skill/agent file not load?
• Why did a tool call fail?
• Why did the model not follow expectations?

Base every conclusion on evidence from the event log. Do not guess.

Locating the Session Log

The skill runs **inside** the session's agent, so the log is on the same machine. It lives outside the workspace — read it via the terminal (`run_in_terminal`), never `grep_search`.

1. **If a `Session log:` path is provided with this message, use it.** It may point to a session **other than** the current one (via `#session`) and may be **comma-separated paths** — investigate all of them and compare. 2. **Sticky reference:** if no path is on the *current* message but an earlier turn in **this conversation** already established a target (a `Session log:` path, or a `#session:` reference), keep analyzing **that same session** for the follow-up. Do **not** fall back to self-discovery here — the newest log is the *current* session, which is the wrong one. Switch only if the user references a new session. 3. **Otherwise, self-discover it:** pick the **most recently modified** `events.jsonl` under `${XDG_STATE_HOME:-$HOME}/.copilot/session-state/<sessionId>/` — this skill is appending to the current session's log, so it's reliably newest. Honor `XDG_STATE_HOME`, else `$HOME`. 4. **If none exists** there, this isn't a Copilot CLI session — tell the user the skill supports Copilot CLI sessions only, and stop.

Data Source — `events.jsonl`

Each line is a JSON object sharing one envelope:

{ "type": "...", "id": "...", "parentId": "...", "agentId": "...", "timestamp": "ISO-8601", "data": { } }

• `type` — the event kind (see below).
• `id` — unique event id.
• `parentId` — the **chronologically preceding** event, not a logical parent. It is a flat back-pointer over every event, *not* the user → turn → tool-call hierarchy. Do not treat it as a logical parent.
• `agentId` — present for sub-agent events; absent for the main agent and session-level events.
• `timestamp` — ISO-8601 time. Compute durations by differencing timestamps (e.g. a tool's start vs. its completion, a turn's `assistant.turn_start` vs. the `assistant.message`).
• `data` — type-specific payload.

Event types (`data.*` fields)

• **`session.start`** (once) — `selectedModel`, `reasoningEffort`.
• **`user.message`** — `content`; `transformedContent` (expanded prompt, when it differs).
• **`assistant.turn_start` / `assistant.turn_end`** — `turnId`; measure a turn's duration vs the following `assistant.message`.
• **`assistant.message`** — `model`, `outputTokens`, `content`, `reasoningText` (thinking, when present), `turnId`, `parentToolCallId` (set ⇒ sub-agent turn spawned by that tool call).
• **`tool.execution_start`** — `toolName`, `toolCallId`, `arguments`, `parentToolCallId` (set ⇒ nested/sub-agent).
• **`tool.execution_complete`** — `toolCallId` (matches start), `success`, `result`. Pair with its start by `toolCallId` for the full call + duration.
• **`session.shutdown`** (once, at end) — `modelMetrics[*].usage`, `totalNanoAiu`. Absent mid-session.
• Other (`hook.*`, `permission.*`, `system.message`) — inspect `data` as needed.

Reconstructing the flow

Iterate records in order and rebuild the logical tree from context:

• `session.start` is the root.
• a `user.message` begins a turn.
• an `assistant.message` answers the current `user.message` — unless it has `data.parentToolCallId`, in which case it belongs to the sub-agent spawned by that tool call.
• a `tool.execution_start` belongs to the current `assistant.message` — unless it has `data.parentToolCallId`, in which case it is nested under that parent tool call.
• pair each `tool.execution_start` with its `tool.execution_complete` by `toolCallId`.

Secondary Source — Agent Host Wire Log (protocol communication)

`events.jsonl` is the **primary** source and answers almost every question on its own. A *separate* log captures the **transport/protocol** between VS Code and the agent host process — the JSON-RPC-style frames that drive sessions.

**Use the wire log only when the symptom points at the agent host / transport itself, not the model or a tool.** Reach for it when:

• the agent host won't start, or the session never begins;
• requests **hang or time out**, or the agent appears stuck "connecting" / unresponsive;
• `createSession` / `subscribe` fails, or expected updates/notifications never arrive;
• you see RPC / protocol / connection errors.

**Do not** open it for ordinary "why did the model/tool do X" questions — `events.jsonl` already answers those. If `events.jsonl` fully explains the behavior, stop there and don't read the wire log.

**It is written by VS Code on the _client_ machine, so it is only reachable for a _local_ agent host** (VS Code and the agent on the same machine). For a remote agent host it lives on the client, not the host this skill runs on — skip it there.

Location

<VS Code user-data dir>/logs/<session-timestamp>/ahp/ahp-<timestamp>-<connectionId>.jsonl

The VS Code user-data dir depends on the build:

• Windows: `%APPDATA%\Code` (Insiders: `Code - Insiders`; OSS/dev may use `Code - OSS` or a custom `--user-data-dir`)
• macOS: `~/Library/Application Support/Code`
• Linux: `~/.config/Code`

A new `logs/<timestam