PRD: Copilot SDK Hooks Lifecycle Plugin — Composable Governance via Squad Marketplace

[diberry]

PRD: Copilot SDK Hooks Lifecycle Plugin for Squad

Executive Summary

This PRD proposes a Squad plugin (not a core product change) that implements Copilot SDK lifecycle hooks as a composable, installable package. Unlike PRD #151 which embeds hooks into Squad's core, this approach treats the hooks lifecycle as an opt-in plugin distributed via the Squad marketplace.

The plugin registers onSessionStart, onUserPromptSubmitted, onPreToolUse, onPostToolUse, onSessionEnd, and onErrorOccurred handlers using Squad's existing HookPipeline and SquadSessionHooks APIs. Users install it, configure what they want, and Squad's plugin system activates the hooks at runtime.

Why a plugin instead of core?

• Not every team needs every hook — a plugin lets teams opt into exactly what they want
• Faster iteration — plugin ships independently of Squad's release cycle
• Marketplace showcase — demonstrates that Squad's extension system can handle real governance
• Lower risk — doesn't touch Squad's critical path; users can uninstall if hooks misbehave
• Composable — teams can fork the plugin and customize hooks for their domain

---

How This Fits Squad's Extension Architecture

Squad has a three-layer architecture for extensibility:

Layer	What Lives Here	This Plugin's Relationship
Squad Core	HookPipeline, SquadSessionHooks, adapter layer	Plugin consumes these APIs — does NOT modify them
Squad Extensions (plugins)	Skills, ceremonies, hook packages	This plugin lives here — installed via marketplace
Team Config	squad.config.ts, .squad/policies/	Plugin reads config to know which hooks to activate

The plugin uses publicly exported APIs:

• HookPipeline from @bradygaster/squad-sdk/hooks (addPreToolHook, addPostToolHook)
• SquadSessionHooks from adapter/types.ts (onSessionStart, onSessionEnd, onErrorOccurred, onUserPromptSubmitted)
• SquadSessionConfig for session-level hook registration

No core changes required — the plugin works with Squad as it ships today.

---

Plugin Structure

squad-hooks-lifecycle/
├── package.json
├── README.md
├── src/
│   ├── index.ts              # Plugin entry — exports registerHooks()
│   ├── hooks/
│   │   ├── session-start.ts   # onSessionStart — auto-context loading
│   │   ├── prompt-guard.ts    # onUserPromptSubmitted — directive capture, prompt enhancement
│   │   ├── tool-guard.ts      # onPreToolUse — dynamic policies from decisions.md
│   │   ├── tool-audit.ts      # onPostToolUse — auto-Scribe, audit trail
│   │   ├── session-end.ts     # onSessionEnd — cleanup, metrics, Ralph trigger
│   │   └── error-recovery.ts  # onErrorOccurred — model fallback, rate limit backoff
│   ├── parsers/
│   │   ├── decision-parser.ts # Extracts enforceable rules from decisions.md
│   │   └── directive-detector.ts # Regex + heuristics for "always/never" signals
│   └── config.ts             # Plugin configuration schema
├── skill/
│   └── SKILL.md              # Squad skill teaching agents about the hooks
└── test/
    └── *.test.ts             # Tests for each hook

Registration API

// squad.config.ts — user's project
import { defineSquad } from '@bradygaster/squad-sdk';
import { registerHooks } from 'squad-hooks-lifecycle';

export default defineSquad({
  plugins: [
    registerHooks({
      // Toggle individual hooks on/off
      sessionStart: {
        enabled: true,
        autoLoadHistory: true,     // inject history.md at session start
        autoLoadDecisions: true,   // inject decisions.md snapshot
        autoLoadSkills: true,      // inject matching skills
        maxHistoryEntries: 20,     // limit context size
      },
      promptGuard: {
        enabled: true,
        captureDirectives: true,   // auto-detect "always/never" patterns
        injectDecisions: true,     // add relevant decisions to prompt context
      },
      toolGuard: {
        enabled: true,
        enforceDecisions: true,    // parse decisions.md into tool policies
        agentBoundaries: true,     // restrict writes to charter scope
        decisionFormat: 'structured', // 'structured' | 'prose-inferred'
      },
      toolAudit: {
        enabled: true,
        autoScribe: true,          // trigger Scribe on .squad/ writes
        auditLog: true,            // log all tool calls
        logPath: '.squad/audit/',  // where audit logs go
      },
      sessionEnd: {
        enabled: true,
        autoArchiveHistory: true,  // summarize history.md if over threshold
        captureMetrics: true,      // write session metrics
        ralphTrigger: true,        // notify Ralph of remaining work
      },
      errorRecovery: {
        enabled: true,
        modelFallback: true,       // automatic model fallback chains
        rateLimitBackoff: true,    // exponential backoff on rate limits
        contextOverflowRecovery: true, // summarize + retry on overflow
        fallbackChain: {
          premium: ['claude-opus-4.6', 'claude-opus-4.5', 'claude-sonnet-4.6'],
          standard: ['claude-sonnet-4.6', 'claude-sonnet-4.5', 'gpt-5.4'],
          fast: ['claude-haiku-4.5', 'gpt-5.4-mini', 'gpt-4.1'],
        },
      },
    }),
  ],
});

---

Real-World Use Cases

Use Cases in Manual Copilot CLI Chat Mode

These are scenarios where a human is sitting at the terminal, chatting with Squad via Copilot CLI.

---

UC-1: "My agents keep forgetting team decisions"

Persona: Solo developer using Squad on a side project. Has 10+ decisions in decisions.md but agents routinely ignore them.

Hook: onSessionStart (auto-context loading)

Before plugin: User starts a session. Agent spawns. Coordinator prompt says "read decisions.md." Agent reads 3 of 12 decisions (context budget), misses the one about "always use Tailwind". Agent writes Bootstrap CSS. User is frustrated.

With plugin: onSessionStart hook fires, reads decisions.md, and injects the full decision set as structured context. Agent sees all 12 decisions before it writes a single line. Bootstrap is never introduced.

Business value:

Product Squad: Proves that Squad's governance model works in practice, not just on paper. Turns decisions.md from a suggestion box into an enforcement layer — a key differentiator in the AI team framework space.
Customer: Decisions actually stick. The team's institutional memory works every session, not just when agents happen to read the right file.

---

UC-2: "I said 'always use async/await' last week and the agent used callbacks today"

Persona: Tech lead using Squad for a Node.js project. Gave a directive in a previous session that wasn't carried forward.

Hook: onUserPromptSubmitted (directive capture)

Before plugin: User says "always use async/await, never callbacks." Coordinator captures it in decisions/inbox/ (maybe). Next session, different coordinator context, directive is lost. Agent writes callback-style code.

With plugin: onUserPromptSubmitted hook fires on every message. Detects the "always/never" pattern. Auto-writes to decisions/inbox/. On the next message in any session, onSessionStart loads it from decisions.md. Directive persists permanently.

Business value:

Product Squad: Demonstrates that Squad has memory across sessions — not just within a session. This is a top-3 user complaint ("my agents forget things") and the plugin solves it mechanically.
Customer: Say it once, it sticks forever. No more repeating yourself across sessions.

---

UC-3: "An agent edited a file it shouldn't have touched"

Persona: Team of 3 using Squad with role-based agents. Backend agent modified a frontend component.

Hook: onPreToolUse (dynamic policies + agent boundaries)

Before plugin: Backend agent "Fenster" is told to fix an API bug. While exploring, it edits src/components/LoginForm.tsx — a frontend file outside its scope. PR review catches it, but time is wasted.

With plugin: onPreToolUse hook fires before every file write. Checks agent's charter scope (backend: src/api/**, src/services/**). LoginForm.tsx is outside scope — write is blocked with reason: "File outside your charter scope. Route to the Frontend agent." Agent self-corrects or coordinator re-routes.

Business value:

Product Squad: Enforces the agent boundary model that Squad promises but currently only advises. Moves from "agents should stay in scope" to "agents cannot leave scope."
Customer: Clean PRs with no scope creep. Code review effort drops because agents physically can't touch files outside their domain.

---

UC-4: "I want to know what my agents actually did"

Persona: Engineering manager who runs Squad sessions but wants a trail of what happened for compliance.

Hook: onPostToolUse (audit trail)

Before plugin: Session ends. Manager asks "what files did agents touch?" Answer: check orchestration logs (if Scribe ran), check git diff (if agents committed), or re-read the session transcript. Tedious.

With plugin: Every tool call is logged to .squad/audit/ with timestamp, agent name, tool name, arguments summary, and result status. Manager runs cat .squad/audit/2026-04-14*.jsonl | jq '.toolName' | sort | uniq -c and gets a complete picture in seconds.

Business value:

Product Squad: Opens Squad to enterprise customers who require audit trails. Compliance-ready logging is a gate for regulated industries (fintech, healthcare, government).
Customer: Complete visibility without effort. "What happened?" is answered by a JSONL file, not a detective mission through logs.

---

UC-5: "My session crashed because the model hit a rate limit"

Persona: Developer running a large fan-out (5 agents in parallel). Third agent hits a rate limit and the session dies.

Hook: onErrorOccurred (model fallback + rate limit backoff)

Before plugin: Agent 3 of 5 hits rate limit. Error surfaces to coordinator. Coordinator's prose instructions say "retry with next model" but the context is already pressured from 2 completed agents. Coordinator fumbles the fallback. Session stalls.

With plugin: onErrorOccurred hook fires immediately. Detects rate limit error code. Applies exponential backoff (1s, 2s, 4s). If still rate-limited, falls back to next model in chain (claude-sonnet-4.6 -> claude-sonnet-4.5 -> gpt-5.4). Agent 3 continues on the fallback model. User never notices.

Business value:

Product Squad: Directly addresses the #1 reliability complaint — sessions dying mid-work. Makes Squad viable for heavy workloads (5+ parallel agents) that stress model rate limits.
Customer: Sessions don't crash. Rate limits are invisible. The work gets done even when infrastructure hiccups.

---

UC-6: "History.md is 50KB and my agents are slow"

Persona: Long-running project (3 months). History files have grown to 30-50KB per agent. Session starts are sluggish.

Hook: onSessionEnd (auto-archive + metrics)

Before plugin: User must remember to ask Scribe to summarize. If they forget, history grows unbounded. Eventually agents burn 2000+ tokens just reading their own history. Session startup takes 45+ seconds.

With plugin: onSessionEnd hook fires every time a session ends. Checks each agent's history.md size. If over 15KB, triggers summarization — moves old entries to history-archive.md, keeps a compressed summary. Next session starts with a lean 3KB history. Metrics written to .squad/metrics/session-2026-04-14.json.

Business value:

Product Squad: Solves "Squad gets slower over time" — a retention killer. Makes Squad viable for long-running projects without manual maintenance.
Customer: Zero-maintenance history hygiene. Sessions stay fast month after month. Metrics show token trends so teams can optimize.

---

Use Cases in Agentic SDK Mode

These are scenarios where Squad is embedded in an application via @bradygaster/squad-sdk, running autonomously without a human at the keyboard.

---

UC-7: "CI pipeline spawns agents to review PRs — needs guardrails"

Persona: Platform team running Squad in CI. GitHub Action triggers Squad SDK to review every PR with 3 agents (security, architecture, tests).

Hook: onPreToolUse (tool guard) + onSessionStart (auto-context) + onErrorOccurred (fallback)

Scenario: PR bradygaster#247 is opened. CI triggers Squad SDK. Three review agents spawn. Security agent needs to read .env.example but must never read .env. Architecture agent should only read, never write. Test agent can write test files only.

import { CopilotClient } from '@github/copilot-sdk';
import { registerHooks } from 'squad-hooks-lifecycle';

const hooks = registerHooks({
  sessionStart: { enabled: true, autoLoadDecisions: true },
  toolGuard: {
    enabled: true,
    agentBoundaries: true,
    // Security agent: read-only, no .env
    // Architecture agent: read-only
    // Test agent: write to test/** only
  },
  errorRecovery: { enabled: true, modelFallback: true },
});

const client = new CopilotClient();
const session = await client.createSession({ hooks: hooks.asSessionHooks() });

Business value:

Product Squad: Proves Squad SDK works in headless/CI environments — not just interactive chat. This is the enterprise adoption vector: automated code review pipelines powered by Squad agents with governance.
Customer: Automated PR review with real guardrails. Security agent can't leak secrets. Architecture agent can't introduce changes. All enforced by hooks, not prompts.

---

UC-8: "Nightly batch processes 50 issues — needs cost control"

Persona: Startup using Squad SDK to auto-triage and fix GitHub issues overnight. Batch of 50 issues. Budget: $20/night.

Hook: onSessionEnd (metrics) + onErrorOccurred (fallback for cost) + onPreToolUse (rate limiting)

Scenario: Ralph-like loop processes issues. After 30 issues, token spend approaches budget. Need to downgrade models or pause.

const hooks = registerHooks({
  sessionEnd: {
    enabled: true,
    captureMetrics: true,
    // Metrics include: tokens_used, model, duration, tools_called
  },
  errorRecovery: {
    enabled: true,
    modelFallback: true,
    fallbackChain: {
      // Start cheap, only upgrade if needed
      standard: ['claude-haiku-4.5', 'gpt-5.4-mini'],
    },
  },
  toolGuard: {
    enabled: true,
    // Custom pre-tool hook: check cumulative cost
    customPreHooks: [
      async (ctx) => {
        const spent = await readMetrics();
        if (spent > 18.00) {
          return { action: 'block', reason: 'Budget limit reached ($18/$20)' };
        }
        return { action: 'allow' };
      },
    ],
  },
});

Business value:

Product Squad: Enables cost-controlled autonomous operation — the missing piece for Squad in production. No AI team framework offers per-session budget enforcement at the tool level.
Customer: Run Squad overnight without fear of runaway costs. Budget caps are enforced mechanically, not by hoping the coordinator remembers.

---

UC-9: "Multi-tenant SaaS — each customer gets different agent permissions"

Persona: SaaS platform embedding Squad SDK. Each customer tenant has different permissions (free tier: read-only agents, pro tier: full agents, enterprise: custom policies).

Hook: onSessionStart (inject tenant config) + onPreToolUse (tenant-scoped permissions)

Scenario: Customer A (free) starts a session. Customer B (enterprise) starts a session. Same Squad SDK, different permissions.

function createTenantHooks(tenant: Tenant) {
  return registerHooks({
    sessionStart: {
      enabled: true,
      // Inject tenant-specific context
      customContext: `Tenant: ${tenant.name}, Plan: ${tenant.plan}`,
    },
    toolGuard: {
      enabled: true,
      customPreHooks: [
        async (ctx) => {
          if (tenant.plan === 'free' && isWriteTool(ctx.toolName)) {
            return { action: 'block', reason: 'Upgrade to Pro for write access' };
          }
          if (tenant.plan !== 'enterprise' && isDangerousTool(ctx.toolName)) {
            return { action: 'block', reason: 'Enterprise only' };
          }
          return { action: 'allow' };
        },
      ],
    },
  });
}

Business value:

Product Squad: Positions Squad SDK as embeddable in SaaS products — a new market segment. Multi-tenant governance via hooks is a compelling SDK selling point.
Customer: Build AI-powered features with Squad SDK and offer tiered access to customers. Permission boundaries are enforced by hooks, not application logic.

---

UC-10: "Autonomous agent loop with human-in-the-loop approval gates"

Persona: Enterprise deploying Squad SDK for code generation. Policy: all file writes must be approved by a human reviewer before committing.

Hook: onPreToolUse (approval gate) + onPostToolUse (audit) + onSessionEnd (compliance report)

Scenario: Agent generates code. Before any file write, a webhook fires to the approval system. Human approves or rejects. Agent proceeds or stops.

const hooks = registerHooks({
  toolGuard: {
    enabled: true,
    customPreHooks: [
      async (ctx) => {
        if (isWriteTool(ctx.toolName)) {
          const approval = await requestHumanApproval({
            agent: ctx.agentName,
            tool: ctx.toolName,
            file: ctx.arguments.path,
            preview: ctx.arguments.content?.substring(0, 500),
          });
          if (approval.status === 'rejected') {
            return { action: 'block', reason: `Rejected by ${approval.reviewer}: ${approval.reason}` };
          }
        }
        return { action: 'allow' };
      },
    ],
  },
  toolAudit: {
    enabled: true,
    auditLog: true,
    // Every approval/rejection is logged for compliance
  },
  sessionEnd: {
    enabled: true,
    captureMetrics: true,
    // Generate compliance report: N writes approved, M rejected, by whom
  },
});

Business value:

Product Squad: Unlocks regulated industries (finance, healthcare, defense) where autonomous AI agents require human oversight. This is the enterprise gate — without it, Squad can't enter these markets.
Customer: Full human-in-the-loop control without losing the speed of AI agents. Every action is approved, logged, and reportable for auditors.

---

UC-11: "Agent fleet with centralized observability"

Persona: DevOps team running 20+ Squad instances across microservices. Needs centralized monitoring of all agent activity.

Hook: onPostToolUse (telemetry) + onErrorOccurred (alerting) + onSessionEnd (aggregation)

Scenario: Each microservice repo has its own Squad. DevOps needs a single dashboard showing: which agents ran, what they did, error rates, token spend.

const hooks = registerHooks({
  toolAudit: {
    enabled: true,
    customPostHooks: [
      async (ctx) => {
        // Ship telemetry to centralized collector
        await fetch('https://telemetry.internal/ingest', {
          method: 'POST',
          body: JSON.stringify({
            repo: process.env.REPO_NAME,
            agent: ctx.agentName,
            tool: ctx.toolName,
            duration: ctx.duration,
            success: !ctx.error,
            timestamp: new Date().toISOString(),
          }),
        });
        return { result: ctx.result }; // pass through unchanged
      },
    ],
  },
  errorRecovery: {
    enabled: true,
    customErrorHooks: [
      async (error) => {
        // Alert on-call if error rate spikes
        await fetch('https://pagerduty.internal/alert', {
          method: 'POST',
          body: JSON.stringify({ source: 'squad', error: error.message }),
        });
      },
    ],
  },
});

Business value:

Product Squad: Enables fleet-scale Squad deployments. Observability is non-negotiable for platform teams managing multiple AI agent instances. This makes Squad enterprise-infrastructure-grade.
Customer: One dashboard for all Squad activity across all repos. Error spikes trigger PagerDuty. Token spend is tracked per-repo. DevOps has full visibility.

---

UC-12: "Auto-fix failing CI — agents respond to webhook, hooks enforce safety"

Persona: Platform team. When CI fails, a webhook triggers Squad SDK to diagnose and fix the failure autonomously.

Hook: onSessionStart (inject CI context) + onPreToolUse (safety limits) + onPostToolUse (validate fix) + onSessionEnd (report)

Scenario: CI fails on PR bradygaster#312. Webhook fires. Squad SDK spins up. Agent reads CI logs, identifies the issue, applies a fix, runs tests locally, pushes if green.

const hooks = registerHooks({
  sessionStart: {
    enabled: true,
    customContext: async () => {
      const ciLogs = await fetchCILogs(process.env.CI_RUN_ID);
      return `CI Failure Context:\n${ciLogs.substring(0, 5000)}`;
    },
  },
  toolGuard: {
    enabled: true,
    customPreHooks: [
      async (ctx) => {
        // Safety: max 3 file edits per CI-fix session
        const editCount = getSessionEditCount();
        if (isWriteTool(ctx.toolName) && editCount >= 3) {
          return { action: 'block', reason: 'Max 3 edits per CI-fix session. Escalate to human.' };
        }
        // Safety: never edit CI config files
        if (ctx.arguments?.path?.includes('.github/workflows/')) {
          return { action: 'block', reason: 'Cannot modify CI workflows autonomously.' };
        }
        return { action: 'allow' };
      },
    ],
  },
  sessionEnd: {
    enabled: true,
    captureMetrics: true,
    // Report: what was fixed, how many attempts, was it pushed
  },
});

Business value:

Product Squad: Demonstrates Squad SDK as an autonomous CI remediation engine — a high-value, high-visibility use case that sells itself. Every engineering team wants "CI fixes itself."
Customer: CI failures are auto-diagnosed and fixed with guardrails. Agent can't go rogue (max 3 edits, can't modify workflows). If it can't fix it in 3 edits, it escalates to a human.

---

Plugin vs. Core: Decision Matrix

Factor	Core (PRD #151)	Plugin (This PRD)
Availability	All Squad users get it	Opt-in install
Release cycle	Tied to Squad releases	Independent — ship anytime
Customization	Config only	Fork + modify freely
Risk to core	High — touches critical path	Zero — external package
Enterprise appeal	"Built-in governance"	"Composable governance"
Cost to implement	High — needs core review	Medium — uses public APIs
Backward compat	Must not break existing users	Only affects users who install
Marketplace signal	N/A	Proves marketplace works for real governance plugins

Recommendation: Ship the plugin FIRST. If adoption proves demand, promote the most-used hooks into core in a future release. This is the lower-risk path that still delivers all the value.

---

Implementation Priority

Priority	Hook	CLI Chat Value	SDK Agentic Value
P0	onErrorOccurred (model fallback)	Sessions stop crashing	Autonomous loops stay alive
P0	onSessionStart (auto-context)	Agents remember decisions	Headless agents get full context
P1	onPreToolUse (dynamic policies)	Agents stay in scope	Multi-tenant permissions
P1	onPostToolUse (audit trail)	"What happened?" answered	Fleet observability
P2	onSessionEnd (cleanup/metrics)	History stays lean	Cost tracking per-session
P2	onUserPromptSubmitted (directives)	Directives persist	Prompt-level governance

Success Metrics

• Plugin installs via marketplace: 50+ repos in first quarter
• Session failure rate for plugin users drops below 3% (from ~10%)
• Audit log adoption: 80%+ of plugin users enable audit trail
• Zero-config value: users who install with defaults see immediate improvement (auto-context + error recovery)

---

This PRD complements PRD #151 (core hooks). Both can coexist — the plugin uses Squad's public APIs, and if specific hooks prove essential, they can graduate into core.

[github-actions]

🏗️ Squad Triage — Flight (Lead)

Issue: #152 — PRD: Copilot SDK Hooks Lifecycle Plugin — Composable Governance via Squad Marketplace
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work

@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

Team roster:

• Flight (Lead) → label: squad:flight
• Procedures (Prompt Engineer) → label: squad:procedures
• EECOM (Core Dev) → label: squad:eecom
• FIDO (Quality Owner) → label: squad:fido
• PAO (DevRel) → label: squad:pao
• CAPCOM (SDK Expert) → label: squad:capcom
• CONTROL (TypeScript Engineer) → label: squad:control
• Surgeon (Release Manager) → label: squad:surgeon
• Booster (CI/CD Engineer) → label: squad:booster
• GNC (Node.js Runtime) → label: squad:gnc
• Network (Distribution) → label: squad:network
• RETRO (Security) → label: squad:retro
• INCO (CLI UX & Visual Design) → label: squad:inco
• GUIDO (VS Code Extension) → label: squad:guido
• Telemetry (Aspire & Observability) → label: squad:telemetry
• VOX (REPL & Interactive Shell) → label: squad:vox
• DSKY (TUI Engineer) → label: squad:dsky
• Sims (E2E Test Engineer) → label: squad:sims
• Handbook (SDK Usability) → label: squad:handbook
• Ralph (Work Monitor) → label: squad:ralph
• @copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

[diberry]

Team Review Summary — PRD #152: Copilot SDK Hooks Lifecycle Plugin

Verdict: APPROVE WITH CONDITIONS (4/4 reviewers)

All four reviewers approve the plugin approach. Consensus: ship as plugin first, promote to core later. Gonzo identified 3 core blockers that narrow the MVP scope.

---

Kermit (Lead/PM) — Strategic Review

Verdict: Approve — plugin first, promote after 6 months

• Plugin path is lower-risk, faster to market, stronger positioning as composable platform
• 6 essential use cases: UC-1 (auto-context), UC-3 (agent boundaries), UC-4 (audit), UC-5 (error recovery), UC-7 (CI review), UC-10 (human-in-the-loop)
• Marketplace infrastructure needs only a lightweight registry
• Strategic recommendation: Ship plugin (PRD PRD: Copilot SDK Hooks Lifecycle Plugin — Composable Governance via Squad Marketplace #152) first. After 6 months of validation, promote high-adoption hooks to core (PRD: Copilot SDK Hooks Integration — Migration Avenues & Per-Hook Improvement Plan #151).

Miss Piggy (Product/Docs) — Use Case & Requirements Review

Verdict: Approve with clarifications

• 12 use cases are well-structured and customer-centric, good CLI/SDK balance
• API validation needed: CopilotClient method signatures and hook timing semantics must be verified against actual SDK
• Missing: Documentation plan section — needs README, quickstart, API reference, and cookbook before dev starts
• Code samples need verification against Squad's actual public API surface

Gonzo (Infrastructure) — Technical Feasibility Review

Verdict: Approve — but 3 core blockers identified

1. API mismatch: Two incompatible hook APIs exist (HookPipeline internal vs SquadSessionHooks public). Plugin must use SquadSessionHooks
2. Plugin loader doesn't exist: Squad CLI manages marketplace registries but has no runtime plugin activation. Plugins can't actually execute today
3. Adapter hooks are inert: SquadSessionHooks types are defined but the adapter never calls them — they're type-safe but functionally dead

• Recommendation: Ship as npm package immediately (works today, no core changes). Schedule plugin loader + hook runtime integration as a separate core effort

Scooter (Quality/Process) — Quality Review

Verdict: Conditional GO with 4 mandatory items

1. Plugin approach is safer than core — lower risk, easier rollback, independent release cycle
2. Test strategy gaps: Neither PRD specifies how to test hooks. Recommends layered unit/integration/E2E approach. 6 of 12 use cases can be automated in CI
3. Missing lifecycle procedures: Install, upgrade, uninstall, rollback not specified. What happens when plugin breaks mid-session?
4. No version compatibility strategy: If Squad's public APIs change, how does the plugin handle it?

---

Consolidated Must-Do List Before Implementation

#	Item	Source	Impact
1	Resolve API mismatch — decide: HookPipeline or SquadSessionHooks as plugin target	Gonzo	Blocker — wrong choice = rewrite
2	Ship as npm package first — marketplace delivery requires plugin loader that doesn't exist	Gonzo, Kermit	Scopes MVP correctly
3	Activate adapter hooks — wire SquadSessionHooks so they actually fire at runtime	Gonzo	Blocker — hooks are currently inert
4	Add documentation plan — README, quickstart, API reference, cookbook	Piggy	Required before dev starts
5	Write test strategy — layered unit/integration/E2E, automate 6 of 12 use cases	Scooter	Required before dev starts
6	Define plugin lifecycle — install, upgrade, uninstall, rollback, mid-session failure	Scooter	Required for production readiness
7	Version compatibility matrix — plugin version vs Squad SDK version	Scooter	Required for maintenance
8	Validate code samples — verify TypeScript against actual Squad exports	Piggy, Gonzo	Code samples may be aspirational, not real

Key Strategic Decision

Ship order: npm package (works today) → activate adapter hooks (core PR) → marketplace delivery (future)

The plugin's value is real, but Squad's plugin infrastructure needs 2 core changes (hook activation + plugin loader) before the full marketplace vision works. The npm path delivers value immediately with zero core risk.

---

Full reviews in .squad/decisions/inbox/: kermit-hooks-plugin-prd-review.md, piggy-hooks-plugin-prd-review.md, gonzo-hooks-plugin-prd-review.md, scooter-hooks-plugin-prd-review.md

[diberry]

Business Cases Addendum — All 6 Copilot SDK Hooks

This addendum provides business case tables for ALL hooks — both the 2 currently supported in Squad and the 4 not yet wired. This is the complete picture of what hooks unlock for Squad users.

---

onPreToolUse — Tool Governance & Safety ✅ SUPPORTED TODAY

#	Business Case	Who Benefits
1	File-write guards — restrict agents to writing only in their scope (src/**, not /etc/passwd)	Every Squad user
2	Shell command blocking — prevent rm -rf /, git push --force, DROP TABLE	Every Squad user
3	Agent boundary enforcement — backend agent can't edit frontend files, and vice versa	Teams with role-based agents
4	Read-only mode for reviewers — code review agents can read everything but write nothing	PR review pipelines
5	Sensitive file protection — block access to .env, secrets, credentials files	Security-conscious teams
6	Human approval gate — pause before destructive operations, request human confirmation via webhook	Enterprise compliance
7	Cost control — block expensive operations (large file reads, shell commands) after budget threshold	Budget-conscious teams, SaaS
8	Time-of-day restrictions — block production-touching tools outside business hours	Enterprise ops teams
9	Dependency policy — block npm install for unapproved packages, enforce allowlists	Enterprise security
10	Branch protection — block git push to main/dev, only allow feature branches	Teams with branch policies
11	Tool rate limiting — max N tool calls per session to prevent runaway agents	Autonomous pipelines
12	Argument sanitization — strip or escape dangerous characters from tool arguments before execution	Security hardening
13	Audit-before-execute — log every tool call attempt (including blocked ones) for compliance trail	Regulated industries
14	Multi-tenant tool scoping — free tier gets read-only tools, pro tier gets write, enterprise gets shell	SaaS builders using SDK
15	Context-aware blocking — block different tools based on which agent is running (tester can't deploy)	Teams with specialized agents

onPostToolUse — Audit, Transformation & Automation ✅ SUPPORTED TODAY

#	Business Case	Who Benefits
16	PII scrubbing — redact emails, phone numbers, SSNs from tool output before it enters conversation	Enterprise security, GDPR
17	Auto-Scribe trigger — detect .squad/ file writes and auto-queue Scribe logging work	Squad product (reliability)
18	Audit trail — log every tool result (tool, agent, timestamp, success/fail) to JSONL for compliance	Engineering managers, auditors
19	Secret detection — scan tool output for leaked credentials, API keys, tokens; redact before continuing	Security teams
20	Result caching — cache expensive file reads; if same file is read again, return cached version	Performance optimization
21	Cross-agent notification — when Agent A writes a file Agent B owns, flag it for review	Teams with file ownership
22	Telemetry shipping — send tool usage metrics to Datadog/Grafana/custom collector in real-time	DevOps running Squad fleet
23	Output size limiting — truncate massive tool outputs before they consume context window	Long sessions, large repos
24	Format transformation — convert tool output formats (e.g., JSON to markdown table) for readability	Developer experience
25	Test result parsing — detect test failures in tool output, extract failing test names for follow-up	CI/CD pipelines
26	Diff summarization — after a file edit, auto-generate a human-readable summary of what changed	Code review, audit
27	Webhook notification — fire a webhook after specific tool completions (deploy, merge, release)	ChatOps, Slack integrations
28	Billing metering — count tool calls by type for per-operation billing in SaaS products	SaaS builders

---

onSessionStart — Context & Configuration ❌ NOT YET WIRED

#	Business Case	Who Benefits
29	Auto-inject team decisions so agents never miss a convention	Solo devs, small teams
30	Load tenant config in multi-tenant SaaS (plan, permissions, branding)	SaaS builders using SDK
31	Inject CI failure context (logs, error, PR number) for auto-fix bots	Platform/DevOps teams
32	Pre-load domain knowledge (API schemas, DB models) so agents don't waste tokens discovering it	Enterprise codebases
33	Inject compliance context ("this repo handles PCI data, HIPAA rules apply")	Regulated industries
34	Restore session state from previous session for continuity across restarts	Long-running projects
35	A/B test agent configurations — randomly assign system prompt variants, measure outcomes	Squad product team

onUserPromptSubmitted — Prompt Governance & Intelligence ❌ NOT YET WIRED

#	Business Case	Who Benefits
36	Auto-capture directives ("always use TypeScript", "never use var") as persistent decisions	Any team tired of repeating themselves
37	Prompt-level PII redaction — strip emails/names from prompts before they reach the LLM	Enterprise security teams
38	Language translation — user writes in Japanese, hook translates to English for the model	International teams
39	Prompt enrichment — detect "fix the bug" and auto-append recent error logs as context	Developer productivity
40	Routing hints — detect "@backend" in message, tag metadata so coordinator routes correctly	Teams with many agents
41	Prompt analytics — log every user message (anonymized) to understand usage patterns	Product analytics
42	Content policy enforcement — block prompts that violate org policies before LLM processes them	Enterprise compliance
43	Cost estimation — estimate token cost before sending, warn user if prompt is expensive	Budget-conscious teams

onSessionEnd — Cleanup, Metrics & Continuity ❌ NOT YET WIRED

#	Business Case	Who Benefits
44	Auto-summarize history.md when it exceeds threshold — prevent session slowdown over time	Long-running projects
45	Write session metrics (tokens, tools called, files changed, duration) for cost dashboards	Engineering managers
46	Trigger Ralph work-check — if issues remain, signal that more work exists	Automated pipelines
47	Update now.md — record what the team was last focused on for next session's context	Teams with multiple contributors
48	Slack/Teams notification — "Squad session ended: 3 files changed, 2 decisions made"	Remote teams
49	Git auto-commit .squad/ state changes at session end so nothing is lost	Everyone (data safety)
50	Generate compliance report — session summary for audit trail (who ran, what changed, approvals)	Regulated industries
51	Clean up temp files — remove scratch files, build artifacts, test fixtures created during session	CI environments
52	Billing event — emit usage record for SaaS platforms charging per-session	SaaS builders

onErrorOccurred — Resilience & Recovery ❌ NOT YET WIRED

#	Business Case	Who Benefits
53	Model fallback chains — rate limit on Claude? Auto-retry with GPT. Transparent to user	Everyone running parallel agents
54	Exponential backoff on rate limits — 1s, 2s, 4s retry instead of crashing	Heavy workloads (5+ agents)
55	Context overflow recovery — summarize conversation, retry with compressed context	Long sessions
56	PagerDuty/OpsGenie alerting — error in autonomous pipeline triggers on-call alert	DevOps running Squad in CI
57	Error classification & logging — categorize errors (model, tool, network, permission) for dashboards	Platform teams
58	Graceful degradation — if premium model fails, downgrade to fast model and tell user "running in economy mode"	Cost-sensitive teams
59	Auto-retry with different tool — if gh CLI fails, fall back to GitHub MCP; if MCP fails, fall back to REST	Environments with flaky tools
60	Dead letter queue — failed agent tasks get written to .squad/failed/ for manual retry later	Batch processing pipelines
61	Circuit breaker — after N consecutive errors, stop spawning agents and alert user instead of burning tokens	Autonomous loops (Ralph)

---

Summary by Audience

Audience	Top Business Cases	Hooks Needed
Solo developer	1, 2, 29, 36, 44, 53	All 6 (2 supported, 4 needed)
Small team	3, 17, 21, 29, 36, 47	All 6
Enterprise security	5, 9, 13, 16, 19, 33, 37, 42	PreTool + PostTool + SessionStart + PromptSubmitted
Regulated industry	6, 13, 18, 33, 42, 50	All 6
SaaS builder	7, 14, 28, 30, 43, 52	All 6
DevOps/CI	4, 11, 22, 25, 31, 46, 51, 56	All 6
Engineering manager	18, 22, 26, 41, 45, 57	PostTool + SessionEnd + PromptSubmitted + Error

Cases by Value Tier

Tier	Description	Count
Table stakes (expected in any AI governance)	File guards, shell blocks, PII scrubbing, error recovery	8
Differentiators (unique to Squad's team model)	Agent boundaries, cross-agent notification, auto-Scribe, directive capture	12
Enterprise gates (required for regulated/large orgs)	Audit trails, compliance reports, human approval, content policy	10
Platform enablers (for SaaS/fleet deployments)	Multi-tenant scoping, billing, telemetry, circuit breaker	9
Quality of life (nice to have, improves DX)	Result caching, prompt enrichment, session metrics, history cleanup	22

[diberry]

Correction & Addendum: All 8 Copilot Hooks (Not 6)

The original PRD listed 6 hooks from the Copilot SDK. The full VS Code Agent hooks surface has 8 hooks — the SDK's 6 plus 2 additional hooks exposed in the VS Code agent lifecycle. This addendum corrects the count and adds business cases for the missing hooks.

Complete Hook Map (8 Hooks)

#	Hook	SDK (@github/copilot-sdk)	VS Code Agent	Squad Status
1	Pre-tool execution	onPreToolUse	PreToolUse	✅ Supported via HookPipeline
2	Post-tool execution	onPostToolUse	PostToolUse	✅ Supported via HookPipeline
3	Session start	onSessionStart	SessionStart	❌ Types defined, not wired
4	User prompt submitted	onUserPromptSubmitted	UserPromptSubmit	❌ Types defined, not wired
5	Session end	onSessionEnd	Stop	❌ Types defined, not wired
6	Error occurred	onErrorOccurred	— (SDK only)	❌ Types defined, not wired
7	Pre-context compaction	—	PreCompact	❌ Not in Squad at all
8	Subagent lifecycle	—	SubagentStart / SubagentStop	❌ Not in Squad at all

---

Hook 7: PreCompact — Context Window Preservation

What it does: Fires before the agent's context window is compacted (pruned/truncated to fit token limits). Gives you a chance to export or preserve state before data is lost.

Why this matters for Squad: Squad agents accumulate context over long sessions — decisions, history, tool results. When context compaction triggers, critical information can be silently lost. This hook lets Squad preserve it.

Business Cases

#	Business Case	Who Benefits
62	Save decisions before compaction — export any decisions the agent made but hasn't written to inbox yet	Every Squad user (data safety)
63	Checkpoint history — write agent's accumulated learnings to history.md before they're truncated	Long sessions, complex tasks
64	Context budget alerting — notify user "context is 90% full, compaction imminent" so they can break the task	Interactive CLI users
65	State serialization — serialize in-memory state (variables, counters, partial results) to .squad/sessions/ for recovery	Autonomous SDK pipelines
66	Priority-based retention — tag certain context as "must keep" (decisions, user directives) and "can drop" (verbose tool output) so compaction preserves what matters	Enterprise teams with large contexts
67	Trigger session split — when compaction is about to fire, automatically start a new session with a compressed summary rather than losing detail	Batch processing, Ralph loops
68	Metrics on context pressure — log when compaction fires, how much was dropped, which agents hit limits most often	Squad product team (optimization)

Executive Summary — Business Value:

For Squad product: Solves the "context overflow" problem — the #2 cause of agent degradation in long sessions (after rate limits). Makes Squad viable for complex, multi-hour work sessions without silent data loss.

For Squad customers: Your agent's work doesn't disappear mid-session. Decisions are preserved. History is checkpointed. If context gets tight, the system adapts instead of silently forgetting.

---

Hook 8: SubagentStart / SubagentStop — Multi-Agent Lifecycle

What it does: SubagentStart fires when a child agent (subagent) is spawned. SubagentStop fires when it finishes. This is the multi-agent orchestration hook — it gives the coordinator visibility and control over the entire agent tree.

Why this matters for Squad: This IS Squad's core model. Squad spawns subagents constantly (coordinator → specialist agents). Today, the coordinator manages this entirely through prompt instructions. These hooks make it programmatic.

Business Cases

#	Business Case	Who Benefits
69	Agent spawn registry — track every active agent (who, when, what task, which model) in real-time	Coordinator reliability
70	Concurrent agent limits — block spawn if team already has N agents running (prevent runaway fan-outs)	Cost control, rate limit prevention
71	Agent cost allocation — tag each subagent spawn with a cost center, track spend per-agent	Engineering managers, SaaS billing
72	Spawn-time policy enforcement — validate agent config against team policies before it starts (right model? right scope? approved charter?)	Enterprise governance
73	Auto-context handoff — when subagent starts, automatically pass relevant context from parent (decisions, recent changes, relevant files)	Multi-agent coordination quality
74	Subagent completion tracking — when subagent stops, automatically collect results, update coordinator state, trigger follow-up work	Coordinator reliability (replaces manual read_agent)
75	Silent success detection (solved) — when subagent stops, check if it produced output. If not, check filesystem for artifacts. Log either way	Eliminates the "7-10% silent success" bug
76	Auto-Scribe on agent completion — when any subagent stops, trigger Scribe to log what it did	Audit completeness without coordinator intervention
77	Agent timeout enforcement — if subagent runs longer than threshold, kill it and route to a different agent	Resilience for stuck agents
78	Agent performance metrics — track spawn-to-complete duration, token usage, tool calls per agent for optimization	Squad product team, enterprise dashboards
79	Cascade failure prevention — if 3 subagents fail in a row, stop spawning and alert user (circuit breaker at spawn level)	Autonomous pipelines (Ralph)
80	A/B model testing at spawn — randomly assign different models to subagents, measure quality/speed/cost per model	Squad product team (model selection optimization)
81	Reviewer lockout at spawn time — before spawning a revision agent, verify they're not locked out of the artifact	Reviewer protocol enforcement (currently checked too late)

Executive Summary — Business Value:

For Squad product: This is the single most impactful hook for Squad. Every problem the coordinator struggles with today — silent success, manual result collection, agent timeout, spawn policy enforcement — becomes solvable with programmatic subagent lifecycle hooks. This hook alone could eliminate 50%+ of coordinator failure modes.

For Squad customers: Agent spawning becomes observable and controllable. Cost limits are enforced at spawn time. Stuck agents get killed automatically. Results are collected reliably. The "sometimes agents work, sometimes they don't" experience becomes deterministic.

---

Updated Summary Table (All 8 Hooks, 81 Business Cases)

Hook	Status in Squad	Business Cases	Top Impact
onPreToolUse	✅ Supported	#1–15 (15 cases)	Agent boundaries, tool governance
onPostToolUse	✅ Supported	#16–28 (13 cases)	Audit trail, PII scrubbing
onSessionStart	❌ Types only	#29–35 (7 cases)	Auto-context, tenant config
onUserPromptSubmitted	❌ Types only	#36–43 (8 cases)	Directive capture, prompt governance
onSessionEnd	❌ Types only	#44–52 (9 cases)	Metrics, cleanup, billing
onErrorOccurred	❌ Types only	#53–61 (9 cases)	Model fallback, resilience
PreCompact	❌ Not in Squad	#62–68 (7 cases)	Context preservation, session continuity
SubagentStart/Stop	❌ Not in Squad	#69–81 (13 cases)	Multi-agent orchestration, spawn governance

Revised Priority (with new hooks)

Priority	Hook	Rationale
P0	SubagentStart/Stop	Highest impact for Squad — solves coordinator's core reliability problems
P0	onErrorOccurred	Directly reduces session failures
P0	onSessionStart	Token savings, context reliability
P1	PreCompact	Prevents silent data loss in long sessions
P1	onPostToolUse (extended)	Auto-Scribe, audit trail
P1	onPreToolUse (extended)	Dynamic policies
P2	onSessionEnd	Cleanup, metrics
P2	onUserPromptSubmitted	Directive capture