feat: add GitHub Copilot CLI plugin

.github/plugin/marketplace.json

@@ -0,0 +1,32 @@
+{
+  "name": "agent-trace",
+  "owner": {
+    "name": "Siddhant Khare",
+    "email": "siddhantkhare2694@gmail.com"
+  },
+  "metadata": {
+    "description": "GitHub Copilot CLI plugins for agent observability.",
+    "version": "0.94.0"
+  },
+  "plugins": [
+    {
+      "name": "agent-strace",
+      "description": "Capture, replay, and analyze GitHub Copilot CLI agent sessions.",
+      "version": "0.94.0",
+      "source": ".",
+      "author": {
+        "name": "Siddhant Khare",
+        "email": "siddhantkhare2694@gmail.com"
+      },
+      "homepage": "https://github.com/Siddhant-K-code/agent-trace",
+      "repository": "https://github.com/Siddhant-K-code/agent-trace",
+      "license": "MIT",
+      "keywords": [
+        "agents",
+        "copilot-cli",
+        "observability",
+        "tracing"
+      ]
+    }
+  ]
+}

README.md

@@ -57,6 +57,17 @@ agent-strace replay            # replay the latest
 
 Full config and JSON: [docs/setup.md](docs/setup.md)
 
+### GitHub Copilot CLI plugin
+
+After installing `agent-strace`, install the repository as a Copilot CLI plugin to enable tracing hooks plus the trace analyst agent and skill:
+
+```bash
+copilot plugin marketplace add Siddhant-K-code/agent-trace
+copilot plugin install agent-strace@agent-trace
+```
+
+See the [Copilot CLI plugin guide](docs/copilot-plugin.md) for verification and usage.
+
 **Option 2: MCP proxy** — wraps any MCP server, works with Cursor, Windsurf, and Copilot Desktop MCP servers
 
 ```bash

agents/trace-analyst.agent.md

@@ -0,0 +1,23 @@
+---
+name: trace-analyst
+description: Investigates agent-strace sessions to explain behavior, failures, cost, and tool usage.
+tools: ["bash"]
+---
+
+You are an agent-session forensic analyst. Use the installed `agent-strace` CLI
+to investigate recorded sessions and report evidence-based findings.
+
+1. Confirm `agent-strace` is available before analysis. If it is missing, explain
+   that the `agent-strace` Python package is a prerequisite for this plugin.
+2. Use `agent-strace list` to resolve the relevant session when the user does not
+   provide an ID.
+3. Start with `inspect`, `explain`, and `timeline`. Use `lint`, `audit`, `why`,
+   `diff`, or `compare` only when they answer the user's question.
+4. Cite session IDs, event numbers, commands, and timestamps that support each
+   material conclusion. Distinguish observed facts from inferences.
+5. Treat `.agent-traces/` as read-only unless the user explicitly requests a
+   command that changes stored traces.
+6. Never expose redacted values or infer secrets from placeholders.
+
+Return the main finding first, followed by concise supporting evidence and the
+most relevant remediation when a problem is found.

docs/copilot-plugin.md

@@ -0,0 +1,75 @@
+# GitHub Copilot CLI plugin
+
+The `agent-strace` Copilot CLI plugin records lifecycle events and adds a trace
+analyst agent and skill for investigating sessions.
+
+## Install
+
+Install the zero-dependency Python CLI first so the plugin hooks can invoke it:
+
+```bash
+uv tool install agent-strace
+# or: pip install agent-strace
+```
+
+Add this repository as a marketplace, then install its plugin:
+
+```bash
+copilot plugin marketplace add Siddhant-K-code/agent-trace
+copilot plugin install agent-strace@agent-trace
+```
+
+Restart Copilot CLI after installation. Do not also run
+`agent-strace setup --cli copilot`; both approaches register the same hooks and
+would record duplicate events.
+
+## Verify
+
+```bash
+copilot plugin list
+agent-strace --version
+```
+
+In an interactive Copilot CLI session, use `/agent` to select `trace-analyst` or
+run `/skills list` to confirm the `agent-strace` skill loaded. New sessions are
+written to `.agent-traces/` in the working directory.
+
+## Use
+
+Ask Copilot to analyze the latest agent trace, or run commands directly:
+
+```bash
+agent-strace list
+agent-strace replay
+agent-strace explain
+agent-strace timeline
+agent-strace lint
+```
+
+The hooks capture session starts and ends, prompts, successful and failed tool
+calls, and agent-stop events exposed by Copilot CLI. Secret redaction remains
+enabled by default.
+
+## Develop locally
+
+From a clone of this repository:
+
+```bash
+pip install -e .
+copilot plugin marketplace add "$PWD"
+copilot plugin install agent-strace@agent-trace
+```
+
+Copilot caches installed plugin components. Run
+`copilot plugin marketplace update agent-trace` followed by
+`copilot plugin update agent-strace` after changing the manifest, hooks, agent,
+or skill.
+
+## Uninstall
+
+```bash
+copilot plugin uninstall agent-strace
+```
+
+Locally installed plugins run only in Copilot CLI. Copilot cloud agent does not
+load plugins installed on a developer machine.

docs/setup.md

@@ -141,27 +141,34 @@ Cursor hook coverage depends on the events Cursor emits. Native hooks capture pr
 
 ### GitHub Copilot CLI hooks
 
-`agent-strace setup --cli copilot` writes user-level Copilot hooks:
+The recommended setup is the Copilot CLI plugin, which bundles the hooks plus a trace analyst agent and skill:
+
+```bash
+copilot plugin marketplace add Siddhant-K-code/agent-trace
+copilot plugin install agent-strace@agent-trace
+```
+
+See [Copilot CLI plugin](copilot-plugin.md) for verification and usage. Alternatively, `agent-strace setup --cli copilot` writes only the user-level Copilot hooks:
 
 ```
 ~/.copilot/
 └── hooks/
     └── agent-strace.json
 ```
 
-Set `COPILOT_HOME` to install into a different Copilot config directory. The generated config registers Copilot lifecycle hooks using the VS Code-compatible event names:
+Set `COPILOT_HOME` to install into a different Copilot config directory. The generated config registers Copilot lifecycle hooks using the native event names:
 
 ```json
 {
   "version": 1,
   "hooks": {
-    "SessionStart": [{ "hooks": [{ "type": "command", "command": "agent-strace hook --provider copilot session-start" }] }],
-    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "agent-strace hook --provider copilot user-prompt" }] }],
-    "PreToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "agent-strace hook --provider copilot pre-tool" }] }],
-    "PostToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "agent-strace hook --provider copilot post-tool" }] }],
-    "PostToolUseFailure": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "agent-strace hook --provider copilot post-tool-failure" }] }],
-    "Stop": [{ "hooks": [{ "type": "command", "command": "agent-strace hook --provider copilot stop" }] }],
-    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "agent-strace hook --provider copilot session-end" }] }]
+    "sessionStart": [{ "type": "command", "command": "agent-strace hook --provider copilot session-start", "timeoutSec": 10 }],
+    "userPromptSubmitted": [{ "type": "command", "command": "agent-strace hook --provider copilot user-prompt", "timeoutSec": 10 }],
+    "preToolUse": [{ "type": "command", "command": "agent-strace hook --provider copilot pre-tool", "timeoutSec": 10 }],
+    "postToolUse": [{ "type": "command", "command": "agent-strace hook --provider copilot post-tool", "timeoutSec": 10 }],
+    "postToolUseFailure": [{ "type": "command", "command": "agent-strace hook --provider copilot post-tool-failure", "timeoutSec": 10 }],
+    "agentStop": [{ "type": "command", "command": "agent-strace hook --provider copilot stop", "timeoutSec": 10 }],
+    "sessionEnd": [{ "type": "command", "command": "agent-strace hook --provider copilot session-end", "timeoutSec": 10 }]
   }
 }
 ```

hooks.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "command": "agent-strace hook --provider copilot session-start",
+        "timeoutSec": 10
+      }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "command": "agent-strace hook --provider copilot user-prompt",
+        "timeoutSec": 10
+      }
+    ],
+    "preToolUse": [
+      {
+        "type": "command",
+        "command": "agent-strace hook --provider copilot pre-tool",
+        "timeoutSec": 10
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "command": "agent-strace hook --provider copilot post-tool",
+        "timeoutSec": 10
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "type": "command",
+        "command": "agent-strace hook --provider copilot post-tool-failure",
+        "timeoutSec": 10
+      }
+    ],
+    "agentStop": [
+      {
+        "type": "command",
+        "command": "agent-strace hook --provider copilot stop",
+        "timeoutSec": 10
+      }
+    ],
+    "sessionEnd": [
+      {
+        "type": "command",
+        "command": "agent-strace hook --provider copilot session-end",
+        "timeoutSec": 10
+      }
+    ]
+  }
+}

plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "agent-strace",
+  "description": "Capture, replay, and analyze GitHub Copilot CLI agent sessions.",
+  "version": "0.94.0",
+  "author": {
+    "name": "Siddhant Khare",
+    "email": "siddhantkhare2694@gmail.com"
+  },
+  "homepage": "https://github.com/Siddhant-K-code/agent-trace",
+  "repository": "https://github.com/Siddhant-K-code/agent-trace",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "copilot-cli",
+    "observability",
+    "tracing"
+  ],
+  "agents": "agents/",
+  "skills": "skills/",
+  "hooks": "hooks.json"
+}

skills/agent-strace/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: agent-strace
+description: Trace and investigate GitHub Copilot CLI sessions with agent-strace. Use when the user wants to capture a Copilot session, replay agent activity, explain a decision, diagnose repeated tool calls or failures, inspect cost, or audit a recorded session.
+---
+
+# agent-strace
+
+Use the local `agent-strace` executable. The plugin contributes lifecycle hooks,
+but the Python package must also be installed and available on `PATH`.
+
+## Prerequisite check
+
+Run `agent-strace --version`. If it is unavailable, stop and provide one of:
+
+```bash
+uv tool install agent-strace
+pip install agent-strace
+```
+
+Do not silently substitute another tracing tool.
+
+## Capture
+
+Installed plugin hooks automatically record new Copilot CLI sessions to
+`.agent-traces/`. Do not also run `agent-strace setup --cli copilot`; that would
+register duplicate hooks.
+
+## Investigate
+
+Choose the smallest command set that answers the request:
+
+```bash
+agent-strace list
+agent-strace inspect <session-id>
+agent-strace replay <session-id>
+agent-strace explain <session-id>
+agent-strace timeline <session-id>
+agent-strace why <session-id> <event-number>
+agent-strace lint <session-id>
+agent-strace audit <session-id>
+agent-strace cost <session-id>
+agent-strace diff <session-a> <session-b>
+agent-strace compare <session-a> <session-b>
+```
+
+Resolve an omitted session ID with `agent-strace list`. Prefer text output for
+interactive analysis and JSON only when structured processing is necessary.
+Report exact session IDs and event numbers for material findings.
+
+## Safety
+
+- Treat trace storage as read-only unless the user requests retention, import,
+  anonymization, or another mutating operation.
+- Preserve secret redaction.
+- Do not claim causal intent from proximity alone; use `why` or clearly label the
+  conclusion as an inference.

src/agent_trace/__init__.py

@@ -1,3 +1,3 @@
 """agent-trace: strace for AI agents."""
 
-__version__ = "0.93.1"
+__version__ = "0.94.0"