feat: Agency plugin manifests + PostToolUse hook (Phase 1)

Phase 1 cross-engine: Agency manifests (agency.json, .mcp.json, hooks/), classification-only PostToolUse hook via lib/heuristics.mjs, session summary taskDescription fallback fix. 184 tests. 3-model council approved. Docs: README runtime compat table, cross-engine-spec Phase 2 invariants, AGENTS.md architecture updates.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: vidhartbhatia

.claude-plugin/plugin.json

@@ -1,7 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin.json",
   "name": "copilot-brag-sheet",
-  "version": "1.0.3",
   "description": "Auto-track AI coding sessions into a structured work impact log. Local-first, MCP-conformant. Cross-engine: Claude Code, Copilot CLI, Codex CLI, Cursor, Agency.",
   "author": {
     "name": "Microsoft",
@@ -17,6 +16,7 @@
     "performance-review",
     "local-first"
   ],
+  "hooks": "hooks/hooks.json",
   "skills": [
     "./skills/brag-sheet/SKILL.md"
   ],

.github/workflows/release.yml

@@ -60,11 +60,15 @@ jobs:
           required=(
             extension.mjs
             mcp-server.mjs
+            agency.json
+            .mcp.json
             plugin.json
             package.json
             bin/install.mjs
             bin/setup.mjs
             bin/mcp-server.mjs
+            hooks/hooks.json
+            hooks/post-tool-use.mjs
             lib/config.mjs
             lib/git-backup.mjs
             lib/heuristics.mjs

.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "brag-sheet": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/mcp-server.mjs"],
+      "description": "Save, review, and export brag-sheet entries via MCP."
+    }
+  }
+}

AGENTS.md

@@ -59,13 +59,27 @@ Copilot CLI host  ──spawns──▶  extension.mjs (joinSession)
                                             │
                                             ▼
                               optional: git commit/push to private repo
+
+Agency host  ──spawns──▶  hooks/post-tool-use.mjs (subprocess per event)
+                               │
+                               ├── reads JSON payload from stdin
+                               ├── classifies via lib/heuristics.mjs
+                               └── writes JSON response to stdout
+                                   (Phase 1: classification only, no persistence)
+
+MCP host  ──stdio──▶  mcp-server.mjs (@modelcontextprotocol/sdk)
+                           │
+                           ├── tools: save_to_brag_sheet / review_brag_sheet / generate_work_log
+                           └── delegates to lib/operations.mjs
 ```
 
 **Entry points** (start here):
 
 | File | Role |
 |---|---|
 | [`extension.mjs`](extension.mjs) | The only file that imports `@github/copilot-sdk/extension`. Wires hooks and tools to `lib/*`. **All Copilot-specific glue lives here and nowhere else.** |
+| [`mcp-server.mjs`](mcp-server.mjs) | MCP stdio server exposing all three tools. Uses `@modelcontextprotocol/sdk` + `zod`. Works with any MCP-compatible host. |
+| [`hooks/post-tool-use.mjs`](hooks/post-tool-use.mjs) | Agency PostToolUse hook. Classifies tool calls via `lib/heuristics.mjs`, returns classification to host via stdout. **Phase 1: classification only, no persistence.** |
 | [`bin/install.mjs`](bin/install.mjs) | `npm i -g copilot-brag-sheet && copilot-brag-sheet` — copies package files into `~/.copilot/extensions/` and runs setup. |
 | [`bin/setup.mjs`](bin/setup.mjs) | Interactive wizard: presets, git backup, output path. Non-TTY exits cleanly (CI-safe). |
 | [`install.sh`](install.sh) / [`install.ps1`](install.ps1) | Curl-pipe-bash installers. Cross-platform CI-tested on PS 5.1 and pwsh 7. |
@@ -202,7 +216,7 @@ real bug reports). Don't change them without an issue and discussion first.
 
 ## 5. Testing strategy
 
-Current state: **177 tests, all green, run cross-platform in CI.** Counts
+Current state: **184 tests, all green, run cross-platform in CI.** Counts
 per file (verify with `Select-String -Pattern '^\s*it\('`):
 
 | File | Tests | Covers |
@@ -212,14 +226,15 @@ per file (verify with `Select-String -Pattern '^\s*it\('`):
 | `test/git-backup.test.mjs` | 19 | `ensureGitRepo`, `addRemote`, `backupToGit` with a mocked `git` runner. |
 | `test/mcp-server.test.mjs` | 18 | MCP server tool handlers via buildServer(), Zod validation, pagination, structured output. |
 | `test/operations.test.mjs` | 16 | Shared saveBragEntry, reviewBragEntries, generateWorkLog with real disk I/O. |
-| `test/render.test.mjs` | 14 | Markdown rendering, week boundaries (UTC), category grouping, escaping. |
+| `test/render.test.mjs` | 15 | Markdown rendering, week boundaries (UTC), category grouping, escaping, taskDescription fallback. |
 | `test/storage.test.mjs` | 12 | Atomic JSON/text writes, shard layout, filter semantics, update flow. |
 | `test/config.test.mjs` | 9 | Default merge, microsoft preset, category resolution. |
 | `test/records.test.mjs` | 8 | Record factories, sanitization, file-path dedup. |
 | `test/paths.test.mjs` | 7 | Per-platform data dir resolution, env-var overrides. |
 | `test/lock.test.mjs` | 7 | Lock acquisition, stale-PID cleanup, contention. |
+| `test/hooks.test.mjs` | 6 | Agency PostToolUse hook subprocess tests: classification, malformed input, stdout purity, camelCase compat. |
 | `test/pack-smoke.test.mjs` | 1 | Tarball validation, install simulation. |
-| **Total** | **177** | |
+| **Total** | **184** | |
 
 **What's covered:**
 
@@ -347,8 +362,8 @@ Until then, the `_npmUser` is whoever holds the `NPM_TOKEN`, not
 | **npm** | ✅ live (`copilot-brag-sheet`) | `npm i -g copilot-brag-sheet && copilot-brag-sheet` runs `bin/install.mjs`. |
 | **`install.sh` / `install.ps1`** | ✅ live | One-line curl-pipe-bash from `raw.githubusercontent.com/...`. CI-tested on PS 5.1 + pwsh 7 + bash. |
 | **awesome-copilot skill** | ✅ live | [`SKILL.md`](skills/brag-sheet/SKILL.md) is mirrored in [github/awesome-copilot](https://github.com/github/awesome-copilot) (PR #1428). The skill is the prompt; this repo is the prompt **plus** the deterministic capture. |
-| **Claude Code plugin** | 🟡 planned | Tracked in [`docs/cross-engine-spec.md`](docs/cross-engine-spec.md). Will reuse `lib/*` unchanged via a thin Claude adapter. |
-| **MCP server** | 🟡 planned | `mcp-server.mjs` will expose the same three tools to any MCP-compatible host (Cursor, VS Code, Codex, Copilot CLI). |
+| **Claude Code plugin** | ✅ partial (tools: v1.1; auto-tracking: Phase 2) | Tracked in [`docs/cross-engine-spec.md`](docs/cross-engine-spec.md). MCP tools work fully; auto-tracking hooks are classification-only (persistence in Phase 2). |
+| **MCP server** | ✅ live | `mcp-server.mjs` exposes all three tools to any MCP-compatible host (Cursor, VS Code, Codex, Copilot CLI) via `copilot-brag-sheet-mcp` bin. |
 | **`copilot plugin install`** | 🚫 blocked upstream | This is a `joinSession()` extension, not an MCP plugin — needs [github/copilot-cli#3023](https://github.com/github/copilot-cli/issues/3023). Don't try to register it under `~/.copilot/plugins/`. |
 
 Don't add new distribution channels (e.g. Homebrew, scoop, winget)
@@ -371,6 +386,11 @@ proving distribution conversion before fanning out further.
 | `lib/records.mjs` | Record factories, `sanitize`, `addFileToRecord`. | Changing the record schema (and read §10 first). |
 | `lib/render.mjs` | Records → Markdown. Reserved markers live here. | Changing the work-log Markdown layout. |
 | `lib/git-backup.mjs` | Optional git init/commit/push of data dir. | Adding remote types, fixing git edge cases. |
+| `mcp-server.mjs` | MCP stdio server (3 tools). Only file that imports `@modelcontextprotocol/sdk` + `zod`. | Adding an MCP tool or changing protocol behavior. |
+| `agency.json` | Agency governance manifest (layer 4, developer-tools). **No `version` field** — `package.json` is source of truth. | Changing Agency category, engines, or governance metadata. |
+| `.mcp.json` | Standalone MCP server config for Agency hosts. | Changing MCP server args or transport. |
+| `hooks/hooks.json` | Agency hook declarations (PostToolUse). | Adding a hook event (e.g. SessionStart, SessionEnd for Phase 2). |
+| `hooks/post-tool-use.mjs` | Agency PostToolUse hook. Classifies tool calls via `lib/heuristics.mjs`. **Phase 1: classification only.** | Changing classification behavior or adding persistence (Phase 2). |
 | `bin/install.mjs` | Post-`npm-i` wizard launcher. Copies pkg → `~/.copilot/extensions/`. | Changing the install layout or required-files list. |
 | `bin/setup.mjs` | Interactive setup wizard. Non-TTY-safe. | Adding a config field, preset, or onboarding step. |
 | `install.sh` / `install.ps1` | Curl-pipe-bash installers. | Cross-platform install behavior. PR must include CI smoke updates. |

CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+### Added
+
+- **Agency plugin manifests** — `agency.json` (governance manifest), `.mcp.json` (standalone MCP config), and `hooks/hooks.json` (PostToolUse hook declaration) enable installation via `agency plugin install`. The PostToolUse hook classifies tool calls using `lib/heuristics.mjs` and returns classification data to the host. **Phase 1: classification only; session persistence is deferred to Phase 2.**
+- **`hooks/post-tool-use.mjs`** — Agency PostToolUse hook script. Reads JSON from stdin, classifies file edits / PR creation / git actions, writes JSON response to stdout. Stateless subprocess — each invocation is independent.
+
 ### Changed
 
 - **Extracted `lib/heuristics.mjs`** — tool classification sets, extraction helpers (`extractPrInfo`, `detectShellGitAction`), brag keyword detection (`isBragRequest`), and composite `classifyToolUse()` are now importable from any entry point. `extension.mjs` imports from this module instead of defining them inline.
@@ -17,6 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 ### Fixed
 
 - **git config fallback null guard** — `extension.mjs` now applies the same `?? { enabled: false, push: false }` guard as `mcp-server.mjs`, preventing a potential NPE when `config.git` is undefined.
+- **Empty session summaries in work-log** — `formatSessionRow` now falls back to `taskDescription` (captured from the user's first prompt) when `summary` is absent. Previously sessions without a host-provided `finalMessage` rendered as blank rows in the session activity log.
 
 ## [1.1.0] — 2026-05-11
 

README.md

@@ -52,6 +52,18 @@ Plus three tools the agent can call on your behalf:
 | `review_brag_sheet` | Review recent entries for performance discussions |
 | `generate_work_log` | Render all records into a Markdown file |
 
+### Runtime compatibility
+
+| Runtime | Manual tools | Auto-tracking | Status |
+|---------|-------------|---------------|--------|
+| **Copilot CLI** | ✅ Full | ✅ Full | Production |
+| **MCP hosts** (Claude, Cursor, VS Code) | ✅ Full | ⚠️ Phase 2 | Beta |
+| **Agency** | ✅ Full | ⚠️ Phase 2 | Beta |
+
+**MCP / Agency users:** The three tools (`save_to_brag_sheet`, `review_brag_sheet`, `generate_work_log`) work fully. Automatic session tracking (files edited, PRs created, git actions) requires the Copilot CLI `joinSession()` runtime and is not yet available in other hosts. For now, say `"brag — <accomplishment>"` to capture work manually.
+
+**Copilot CLI users:** Full automatic tracking works today — no action needed.
+
 ### When the agent will use this
 
 The agent picks up these tools when you say (anything close to) one of:

agency.json

@@ -0,0 +1,13 @@
+{
+  "engines": {
+    "agency": ">=1.0.0"
+  },
+  "category": "developer-tools",
+  "description": "Auto-track AI coding sessions into a structured work impact log. Local-first, zero telemetry.",
+  "governance": {
+    "layer": 4,
+    "certification": "draft",
+    "organization": "Microsoft",
+    "teamScope": ["microsoft/copilot-brag-sheet-maintainers"]
+  }
+}

docs/cross-engine-spec.md

@@ -1,11 +1,32 @@
 # Cross-Engine Support: MCP Server + Hooks
 
 > **Issue:** microsoft/copilot-brag-sheet#22  
-> **Status:** Research complete, spec draft, pending full review  
+> **Status:** Phase 1 shipped (tools + classification hooks); Phase 2 pending (persistence)  
 > **Priority:** Post-FHL (after May 1)  
 > **Scope:** Full (tools + hooks — full extension parity)  
 > **Distribution:** Agency first (internal MSFT), then public Claude Code plugin
 
+## Phase Status
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| MCP server (`mcp-server.mjs`) | ✅ Shipped v1.1.0 | 3 tools over stdio, `@modelcontextprotocol/sdk` + `zod` |
+| Agency manifests (`agency.json`, `.mcp.json`) | ✅ Shipped | Layer 4, developer-tools category |
+| PostToolUse hook (classification) | ✅ Shipped | Classifies tool calls, returns `{ continue, classification }` to host |
+| PostToolUse hook (persistence) | ⚠️ Phase 2 | Classification data is returned to host but not accumulated on disk |
+| SessionStart / SessionEnd hooks | ⚠️ Phase 2 | Needed for file-based session record lifecycle |
+
+## Phase 2 Design Invariants
+
+These invariants are locked now to ensure Phase 2 is a non-breaking addition:
+
+1. **Hooks are stateless subprocesses.** All cross-invocation state goes through `lib/storage.mjs` (atomic writes + `withFileLock`).
+2. **Stdout is the hook response channel.** Same rule as `extension.mjs` §10.5. Debug → stderr, gated on `BRAG_SHEET_DEBUG=1`.
+3. **Hook failures must not break the host session.** Always emit valid JSON, never throw.
+4. **`classification` field is provisional** until Phase 2 stabilizes the persistence story. Consumers depend on it at their own risk.
+5. **Session-key strategy is TBD.** Will be resolved when SessionStart hook is added — likely minted by SessionStart and exported via env var or sidecar file for PostToolUse to read.
+6. **Phase 2 additions are non-breaking:** new hooks (`SessionStart`, `SessionEnd`) and disk I/O inside `PostToolUse`. The stdout response shape grows, never shrinks.
+
 ---
 
 ## Problem

docs/testing-strategy.md

@@ -7,7 +7,7 @@
 
 ## Current state — 2026-05
 
-**177 tests, 100% pass rate, 30 suites, run cross-platform in CI.**
+**184 tests, 100% pass rate, 31 suites, run cross-platform in CI.**
 CI matrix: `{ubuntu-latest, macos-latest, windows-latest} × {Node 18, 20, 22}` =
 **9 combinations** running on every PR and `main` push, plus three
 **install-smoke** jobs that exercise the curl-pipe-bash installers
@@ -16,7 +16,7 @@ CI matrix: `{ubuntu-latest, macos-latest, windows-latest} × {Node 18, 20, 22}`
 Run the suite locally:
 
 ```bash
-npm test                                      # all 177
+npm test                                      # all 184
 node --test test/storage.test.mjs             # one file
 node --test --test-name-pattern="atomic"      # one pattern
 ```
@@ -46,15 +46,16 @@ No test framework dependency — we use `node:test` and
 | [`lib/lock.mjs`](../lib/lock.mjs) | `test/lock.test.mjs` | 7 | Successful acquire/release, contention (`EEXIST` retries), stale-PID detection (`process.kill(pid, 0)`), lock-file content readback, timeout. | Multi-process contention (we mock PIDs). Filesystem-level locking on network shares (SMB/NFS). |
 | [`lib/storage.mjs`](../lib/storage.mjs) | `test/storage.test.mjs` | 12 | Atomic JSON write (tmp file cleanup on failure), atomic text write (round-trip, overwrite), shard layout (`YYYY/MM/<ts>_<id>.json`), shard-bound filtering on `since`/`until`, type/category/repo/tags filters, `updateRecord` merge semantics, `logError` never throws. | Disk-full scenarios. `fsync` failures (we trust the OS). Records with `Date.parse`-invalid timestamps in old data. |
 | [`lib/records.mjs`](../lib/records.mjs) | `test/records.test.mjs` | 8 | `createSessionRecord` + `createEntryRecord` shape, `sanitize()` (newlines, markers, headings, pipes, length cap), `addFileToRecord` dedup + `.copilot/session-state` filtering + repo-relative path normalization. | Case-insensitive dedup on Windows/macOS. Path traversal (`../`) attempts. |
-| [`lib/render.mjs`](../lib/render.mjs) | `test/render.test.mjs` | 14 | `weekOf` UTC consistency including year boundaries, `renderMarkdown` empty/single/multi-week/multi-category cases, session-log opt-in, escaping pipes in tables, ordering newest-first, "Other" bucket for uncategorized, `renderReviewSummary` window filtering. | Internationalized week boundaries (we hardcode UTC). Locale-specific month names. |
+| [`lib/render.mjs`](../lib/render.mjs) | `test/render.test.mjs` | 15 | `weekOf` UTC consistency including year boundaries, `renderMarkdown` empty/single/multi-week/multi-category cases, session-log opt-in, escaping pipes in tables, ordering newest-first, "Other" bucket for uncategorized, `taskDescription` fallback for sessions without summary, `renderReviewSummary` window filtering. | Internationalized week boundaries (we hardcode UTC). Locale-specific month names. |
 | [`lib/git-backup.mjs`](../lib/git-backup.mjs) | `test/git-backup.test.mjs` | 19 | `ensureGitRepo` init + idempotent reuse, `addRemote`, `hasRemote`, `backupToGit` happy path / no-changes / commit-fail / push-fail, error logging via the injectable runner pattern (`createGitRunner`). | Real `git` binary execution (we mock). Auth failures on push. Detached HEAD states. Repos with submodules. |
 | [`extension.mjs`](../extension.mjs) | `test/extension.test.mjs` | 32 | Session lifecycle (active/finalized/orphaned/emergency-saved), file tracking (edit/create classification, dedup, `.copilot/session-state` skip, repo-relative normalization), significant-action accumulation, `save_to_brag_sheet` flow, category validation, summary sanitization, repo/branch auto-detection, `review_brag_sheet` rendering, `generate_work_log` write, brag/PR/git smoke tests (importing from `lib/heuristics.mjs`). | Hooks firing inside the SDK runtime (see "What is NOT covered" below). |
 | [`mcp-server.mjs`](../mcp-server.mjs) | `test/mcp-server.test.mjs` | 18 | MCP server tool handlers via `buildServer()`, Zod input validation, pagination, structured output, response_format switching. | Real MCP transport. |
+| [`hooks/post-tool-use.mjs`](../hooks/post-tool-use.mjs) | `test/hooks.test.mjs` | 6 | Subprocess stdin/stdout classification (file edit, PR creation, unrecognized tool), malformed-input graceful fallback, stdout purity (no console.log pollution), camelCase payload compat. | Hook execution inside a real Agency host. Phase 2 persistence paths. |
 | [`bin/setup.mjs`](../bin/setup.mjs) | — | 0 | — | Interactive prompts. Non-TTY exit (covered indirectly by CI matrix). |
 | [`bin/install.mjs`](../bin/install.mjs) | install-smoke (CI) | 0 unit | Tarball → `~/.copilot/extensions/...` layout. Re-run idempotency. | Failure path when `COPILOT_HOME` exists but isn't writable. |
 | [`install.sh`](../install.sh) / [`install.ps1`](../install.ps1) | install-smoke (CI) | — | End-to-end install on Linux/macOS, Windows PS 5.1, Windows pwsh 7+ (matches real-world Windows 10/11 default shell). | Air-gapped installs. Behind-corporate-proxy installs. |
 
-**Total: 177 unit tests + 4 install-smoke jobs (3 OS × shells).**
+**Total: 184 unit tests + 4 install-smoke jobs (3 OS × shells).**
 
 ---
 

hooks/hooks.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "node ${PLUGIN_ROOT}/hooks/post-tool-use.mjs",
+        "timeout": 5,
+        "description": "Classify tool calls and track files, PRs, and git actions to the brag sheet"
+      }
+    ]
+  }
+}