# Pluggable Tool-Adapter Registry Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Collapse the 7 hardcoded external tools (duplicated across 8 structures) into one derived `BUILTIN_TOOL_MANIFESTS` source of truth + an agent registry, and let a self-hosted operator add a PATH-based CLI runtime via `~/.waggle/adapters/*.json` (zod-validated, no `require()`).

**Architecture:** Declarative `ToolManifest` data lives in `@waggle/shared` (the web bundle + sidecar both read it); the cohort/name/pointer consts derive from it. The agent owns behavior: a `tool-registry.ts` that merges built-in manifests with loaded third-party ones, a `tool-manifest-loader.ts` (declarative, data-only), and a `detectInstalledTools` loop driven by the registry. The 3 desktop candidate-path resolvers stay built-in code (escape hatch); third-party adapters are PATH-only.

**Tech Stack:** TypeScript, zod, Vitest. No new runtime deps.

## Global Constraints

- **`SUPPORTED_TOOLS` stays the `as const` literal anchor** — `ToolId` (the union) is unchanged → zero blast radius on the ~5 `Record<ToolId,…>` consumers.
- **Derived consts must equal today's values** for the 7 built-ins (regression-lock).
- **Third-party adapters: `detect.kind:'path'` only.** `'candidates'` is built-in-code-only (the escape hatch).
- **Loader is data-only:** zod + safe-string refinement (no `; | & $ \` ( )`, no `..`, no path separators in `binaryName`); never `require()`/eval; never throws into detection; missing dir → `[]`.
- **Built-in ids win** over any third-party manifest claiming the same id.
- **Registry = pure data (no functions);** the candidate resolvers stay in `tool-detection.ts` keyed by id (no `registry → detection` cycle: loader ← registry ← detection).
- **Gates:** `tsc` 0 (shared/agent/server/web); existing `tool-detection`/`tool-launcher`/`tools-routes*`/`LauncherApp` suites stay green; new units RED→GREEN.
- **Fast-follow (NOT in v1):** applying a third-party `promptArgTemplate` (the prompt-arg path is web-side `apps/web/src/lib/launcher-prompt-args.ts`; the field is captured but unwired).

## Built-in manifest data (the canonical 7 — used verbatim in Task 1)

| id | displayName | launchable | hookCapable | hookPointer | detect |
|---|---|---|---|---|---|
| claude-code | Claude Code | yes | yes | `.claude/hive-mind-install.json` | `path` binary `claude` |
| claude-desktop | Claude Desktop | yes | **no** | `.config/Claude/hive-mind-install.json` | `candidates` |
| cursor | Cursor | yes | yes | `.cursor/hive-mind-install.json` | `candidates` |
| codex | Codex CLI | yes | yes | `.codex/hive-mind-install.json` | `path` binary `codex` |
| codex-desktop | Codex Desktop | yes | yes | `.codex/hive-mind-install.json` | `candidates` |
| hermes | Hermes Agent | yes | yes | `.hermes/hive-mind-install.json` | `path` binary `hermes` |
| openclaw | OpenClaw | yes | yes | `.openclaw/hive-mind-install.json` | `path` binary `openclaw` |

---

### Task 1: `shared` — `ToolManifest` + `BUILTIN_TOOL_MANIFESTS` + derived consts

**Files:**
- Modify: `packages/shared/src/tool-detection.ts`
- Test: `packages/shared/tests/tool-manifests.test.ts` (new; if `packages/shared/tests` doesn't exist, place under the shared package's test glob — check `packages/shared` for an existing `*.test.ts` to mirror the location)

**Interfaces:**
- Produces: `ToolDetectSpec`, `ToolManifest`, `BUILTIN_TOOL_MANIFESTS: readonly ToolManifest[]`, and **re-derived** `TOOL_DISPLAY_NAMES` / `LAUNCH_COHORT`. `SUPPORTED_TOOLS` / `ToolId` unchanged.

- [ ] **Step 1: Write the failing test** — `packages/shared/tests/tool-manifests.test.ts`:

```ts
import { describe, it, expect } from 'vitest';
import {
  BUILTIN_TOOL_MANIFESTS, SUPPORTED_TOOLS, LAUNCH_COHORT, TOOL_DISPLAY_NAMES,
} from '../src/tool-detection.js';

describe('BUILTIN_TOOL_MANIFESTS', () => {
  it('has one manifest per supported tool, ids matching SUPPORTED_TOOLS', () => {
    expect(BUILTIN_TOOL_MANIFESTS.map((m) => m.id).sort()).toEqual([...SUPPORTED_TOOLS].sort());
  });
  it('marks every built-in as builtin:true and launchable', () => {
    for (const m of BUILTIN_TOOL_MANIFESTS) { expect(m.builtin).toBe(true); expect(m.launchable).toBe(true); }
  });
  it('claude-desktop is the only non-hook-capable tool', () => {
    const nonHook = BUILTIN_TOOL_MANIFESTS.filter((m) => !m.hookCapable).map((m) => m.id);
    expect(nonHook).toEqual(['claude-desktop']);
  });
  it('derives TOOL_DISPLAY_NAMES + LAUNCH_COHORT from the manifests (unchanged values)', () => {
    expect(TOOL_DISPLAY_NAMES['claude-code']).toBe('Claude Code');
    expect(TOOL_DISPLAY_NAMES['codex']).toBe('Codex CLI');
    expect([...LAUNCH_COHORT].sort()).toEqual([...SUPPORTED_TOOLS].sort());
  });
  it('claude-code detects by PATH binary "claude" (not its id)', () => {
    const cc = BUILTIN_TOOL_MANIFESTS.find((m) => m.id === 'claude-code')!;
    expect(cc.detect).toEqual({ kind: 'path', binaryName: 'claude' });
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run packages/shared/tests/tool-manifests.test.ts`
Expected: FAIL — `BUILTIN_TOOL_MANIFESTS` not exported.

- [ ] **Step 3: Implement** in `packages/shared/src/tool-detection.ts` — keep `SUPPORTED_TOOLS`/`ToolId`/`DetectedTool`/`ToolDetectionResult` exactly as-is. Add the types + manifests, and REPLACE the hand-authored `LAUNCH_COHORT` and `TOOL_DISPLAY_NAMES` with derived versions:

```ts
export type ToolDetectSpec =
  | { kind: 'path'; binaryName: string }
  | { kind: 'candidates' };

export interface ToolManifest {
  id: string;
  displayName: string;
  launchable: boolean;
  hookCapable: boolean;
  hookPointer: string;
  detect: ToolDetectSpec;
  /** Declarative inline-prompt arg template for THIRD-PARTY path adapters (e.g.
   *  ['--print', '{prompt}']). Built-ins keep their logic in launcher-prompt-args.ts.
   *  Captured in v1; application is a documented fast-follow. */
  promptArgTemplate?: string[];
  /** true = first-party; false/absent = loaded third-party. */
  builtin?: boolean;
}

export const BUILTIN_TOOL_MANIFESTS: readonly ToolManifest[] = [
  { id: 'claude-code', displayName: 'Claude Code', launchable: true, hookCapable: true, hookPointer: '.claude/hive-mind-install.json', detect: { kind: 'path', binaryName: 'claude' }, builtin: true },
  { id: 'claude-desktop', displayName: 'Claude Desktop', launchable: true, hookCapable: false, hookPointer: '.config/Claude/hive-mind-install.json', detect: { kind: 'candidates' }, builtin: true },
  { id: 'cursor', displayName: 'Cursor', launchable: true, hookCapable: true, hookPointer: '.cursor/hive-mind-install.json', detect: { kind: 'candidates' }, builtin: true },
  { id: 'codex', displayName: 'Codex CLI', launchable: true, hookCapable: true, hookPointer: '.codex/hive-mind-install.json', detect: { kind: 'path', binaryName: 'codex' }, builtin: true },
  { id: 'codex-desktop', displayName: 'Codex Desktop', launchable: true, hookCapable: true, hookPointer: '.codex/hive-mind-install.json', detect: { kind: 'candidates' }, builtin: true },
  { id: 'hermes', displayName: 'Hermes Agent', launchable: true, hookCapable: true, hookPointer: '.hermes/hive-mind-install.json', detect: { kind: 'path', binaryName: 'hermes' }, builtin: true },
  { id: 'openclaw', displayName: 'OpenClaw', launchable: true, hookCapable: true, hookPointer: '.openclaw/hive-mind-install.json', detect: { kind: 'path', binaryName: 'openclaw' }, builtin: true },
] as const;

// Derived from the manifests (single source of truth). SUPPORTED_TOOLS stays the
// type anchor above; these keep their ToolId-typed shapes via the cast.
export const TOOL_DISPLAY_NAMES = Object.fromEntries(
  BUILTIN_TOOL_MANIFESTS.map((m) => [m.id, m.displayName]),
) as Record<ToolId, string>;

export const LAUNCH_COHORT: readonly ToolId[] =
  BUILTIN_TOOL_MANIFESTS.filter((m) => m.launchable).map((m) => m.id as ToolId);
```

(Delete the old literal `LAUNCH_COHORT` and `TOOL_DISPLAY_NAMES` blocks.)

- [ ] **Step 4: Run test + typecheck**

Run: `npx vitest run packages/shared/tests/tool-manifests.test.ts && npx tsc --noEmit -p packages/shared/tsconfig.json`
Expected: PASS + tsc 0.

- [ ] **Step 5: Build shared dist + commit** (downstream tsc reads dist)

```bash
npx tsc -b packages/shared
git add packages/shared/src/tool-detection.ts packages/shared/tests/tool-manifests.test.ts
git commit -m "feat(shared): BUILTIN_TOOL_MANIFESTS source of truth + derived consts (#5)"
```

---

### Task 2: `agent` — declarative manifest loader

**Files:**
- Create: `packages/agent/src/tool-manifest-loader.ts`
- Test: `packages/agent/tests/tool-manifest-loader.test.ts`

**Interfaces:**
- Consumes: `ToolManifest` (Task 1).
- Produces: `loadThirdPartyManifests(deps?: ManifestLoaderDeps): ToolManifest[]`; `ManifestLoaderDeps { dir?: string; readDir?: (dir: string) => string[]; readFile?: (p: string) => string }`.

- [ ] **Step 1: Write the failing test** — `packages/agent/tests/tool-manifest-loader.test.ts`:

```ts
import { describe, it, expect } from 'vitest';
import { loadThirdPartyManifests } from '../src/tool-manifest-loader.js';

function deps(files: Record<string, unknown>) {
  return {
    dir: '/fake',
    readDir: () => Object.keys(files),
    readFile: (p: string) => JSON.stringify(files[p.split('/').pop()!]),
  };
}

describe('loadThirdPartyManifests', () => {
  it('loads a valid PATH manifest, stamped builtin:false', () => {
    const out = loadThirdPartyManifests(deps({
      'foo.json': { id: 'foo-cli', displayName: 'Foo', launchable: true, hookCapable: false, hookPointer: '.foo/hm.json', detect: { kind: 'path', binaryName: 'foo' } },
    }));
    expect(out).toHaveLength(1);
    expect(out[0]).toMatchObject({ id: 'foo-cli', builtin: false, detect: { kind: 'path', binaryName: 'foo' } });
  });

  it('rejects detect.kind:candidates (code-only strategy)', () => {
    const out = loadThirdPartyManifests(deps({
      'bad.json': { id: 'bad', displayName: 'B', launchable: true, hookCapable: false, hookPointer: '.b/hm.json', detect: { kind: 'candidates' } },
    }));
    expect(out).toEqual([]);
  });

  it('rejects shell-metachar / traversal in fields', () => {
    const out = loadThirdPartyManifests(deps({
      'evil.json': { id: 'evil', displayName: 'E', launchable: true, hookCapable: false, hookPointer: '../../etc/passwd', detect: { kind: 'path', binaryName: 'foo; rm -rf /' } },
    }));
    expect(out).toEqual([]);
  });

  it('returns [] when the dir is missing (readDir throws)', () => {
    expect(loadThirdPartyManifests({ dir: '/none', readDir: () => { throw new Error('ENOENT'); }, readFile: () => '' })).toEqual([]);
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run packages/agent/tests/tool-manifest-loader.test.ts`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement** `packages/agent/src/tool-manifest-loader.ts`:

```ts
/**
 * AI-OS #5 — declarative loader for third-party tool adapters from
 * ~/.waggle/adapters/*.json. Data only: zod-validated, safe-string-refined,
 * PATH-detection only, never require()/eval. Never throws into detection.
 */
import os from 'node:os';
import path from 'node:path';
import fs from 'node:fs';
import { z } from 'zod';
import type { ToolManifest } from '@waggle/shared';

// No shell metacharacters, no path traversal, non-empty, bounded.
const SAFE = /^[A-Za-z0-9._/\\-]+$/;
const safe = (max: number) =>
  z.string().min(1).max(max).refine((s) => SAFE.test(s) && !s.includes('..'), 'unsafe string');

const ManifestSchema = z.object({
  id: safe(64),
  displayName: z.string().min(1).max(80),
  launchable: z.boolean(),
  hookCapable: z.boolean(),
  hookPointer: safe(256),
  detect: z.object({ kind: z.literal('path'), binaryName: safe(128).refine((s) => !/[\\/]/.test(s), 'binaryName has a path separator') }),
  promptArgTemplate: z.array(z.string().max(256)).max(20).optional(),
});

export interface ManifestLoaderDeps {
  dir?: string;
  readDir?: (dir: string) => string[];
  readFile?: (p: string) => string;
}

export function loadThirdPartyManifests(deps: ManifestLoaderDeps = {}): ToolManifest[] {
  const dir = deps.dir ?? path.join(os.homedir(), '.waggle', 'adapters');
  const readDir = deps.readDir ?? ((d) => fs.readdirSync(d));
  const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, 'utf8'));
  let names: string[];
  try { names = readDir(dir).filter((n) => n.endsWith('.json')); } catch { return []; }
  const out: ToolManifest[] = [];
  for (const name of names) {
    try {
      const parsed = ManifestSchema.safeParse(JSON.parse(readFile(path.join(dir, name))));
      if (parsed.success) out.push({ ...parsed.data, builtin: false });
    } catch { /* skip malformed file */ }
  }
  return out;
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `npx vitest run packages/agent/tests/tool-manifest-loader.test.ts`
Expected: PASS (4 cases).

- [ ] **Step 5: Commit** (export wired in Task 3's commit)

```bash
git add packages/agent/src/tool-manifest-loader.ts packages/agent/tests/tool-manifest-loader.test.ts
git commit -m "feat(agent): declarative third-party tool-manifest loader (#5)"
```

---

### Task 3: `agent` — `getToolRegistry()`

**Files:**
- Create: `packages/agent/src/tool-registry.ts`
- Modify: `packages/agent/src/index.ts` (exports)
- Test: `packages/agent/tests/tool-registry.test.ts`

**Interfaces:**
- Consumes: `BUILTIN_TOOL_MANIFESTS` (Task 1), `loadThirdPartyManifests` (Task 2).
- Produces: `getToolRegistry(deps?: ManifestLoaderDeps): ToolManifest[]` (built-ins + loaded third-party; built-in ids win).

- [ ] **Step 1: Write the failing test** — `packages/agent/tests/tool-registry.test.ts`:

```ts
import { describe, it, expect } from 'vitest';
import { getToolRegistry } from '../src/tool-registry.js';
import { SUPPORTED_TOOLS } from '@waggle/shared';

const fakeLoaderDeps = (manifests: unknown[]) => ({
  dir: '/fake',
  readDir: () => manifests.map((_, i) => `m${i}.json`),
  readFile: (p: string) => JSON.stringify(manifests[Number(p.match(/m(\d+)\.json/)![1])]),
});

describe('getToolRegistry', () => {
  it('includes all built-in tools when no third-party present', () => {
    const ids = getToolRegistry({ dir: '/none', readDir: () => { throw new Error('ENOENT'); }, readFile: () => '' }).map((m) => m.id);
    expect(ids.sort()).toEqual([...SUPPORTED_TOOLS].sort());
  });

  it('merges a valid third-party PATH adapter', () => {
    const reg = getToolRegistry(fakeLoaderDeps([
      { id: 'foo-cli', displayName: 'Foo', launchable: true, hookCapable: false, hookPointer: '.foo/hm.json', detect: { kind: 'path', binaryName: 'foo' } },
    ]));
    expect(reg.find((m) => m.id === 'foo-cli')).toMatchObject({ builtin: false });
    expect(reg.length).toBe(SUPPORTED_TOOLS.length + 1);
  });

  it('built-in id wins a third-party collision', () => {
    const reg = getToolRegistry(fakeLoaderDeps([
      { id: 'claude-code', displayName: 'HIJACK', launchable: true, hookCapable: false, hookPointer: '.x/hm.json', detect: { kind: 'path', binaryName: 'x' } },
    ]));
    const cc = reg.filter((m) => m.id === 'claude-code');
    expect(cc).toHaveLength(1);
    expect(cc[0].displayName).toBe('Claude Code');
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run packages/agent/tests/tool-registry.test.ts`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement** `packages/agent/src/tool-registry.ts`:

```ts
/**
 * AI-OS #5 — the tool-adapter registry. Pure data: the built-in manifests
 * (source of truth in @waggle/shared) merged with validated third-party
 * manifests from the loader. Built-in ids always win a collision so a
 * third-party file can never hijack a first-party tool.
 */
import { BUILTIN_TOOL_MANIFESTS, type ToolManifest } from '@waggle/shared';
import { loadThirdPartyManifests, type ManifestLoaderDeps } from './tool-manifest-loader.js';

export function getToolRegistry(deps?: ManifestLoaderDeps): ToolManifest[] {
  const builtins = [...BUILTIN_TOOL_MANIFESTS];
  const builtinIds = new Set(builtins.map((m) => m.id));
  const thirdParty = loadThirdPartyManifests(deps).filter((m) => !builtinIds.has(m.id));
  return [...builtins, ...thirdParty];
}
```

- [ ] **Step 4: Export + run** — add to `packages/agent/src/index.ts` (after the existing tool exports):

```ts
export { getToolRegistry } from './tool-registry.js';
export { loadThirdPartyManifests, type ManifestLoaderDeps } from './tool-manifest-loader.js';
```

Run: `npx vitest run packages/agent/tests/tool-registry.test.ts`
Expected: PASS (3 cases).

- [ ] **Step 5: Typecheck + commit**

```bash
npx tsc --noEmit -p packages/agent/tsconfig.json
git add packages/agent/src/tool-registry.ts packages/agent/src/index.ts
git commit -m "feat(agent): getToolRegistry — built-ins + third-party, built-in wins (#5)"
```

---

### Task 4: `agent` — drive `detectInstalledTools` from the registry

**Files:**
- Modify: `packages/agent/src/tool-detection.ts` (the `detectInstalledTools` orchestrator + remove per-tool wrappers + `detectorsById`; keep `detectByPath`/`detectByCandidates`/`probeHooks`/candidate-path helpers)
- Test: `packages/agent/tests/tool-detection.test.ts` (existing — must stay green; add 1 case for a third-party path adapter)

**Interfaces:**
- Consumes: `getToolRegistry` (Task 3), `BUILTIN_TOOL_MANIFESTS` (for the candidate-resolver keys).

- [ ] **Step 1: Read** the existing `tool-detection.test.ts` to confirm the injected deps (`pathFromEnv`, `exists`, `execVersion`) and that it drives `detectInstalledTools(opts)`. The refactor must keep those exact seams.

- [ ] **Step 2: Write the failing test** — append to `tool-detection.test.ts` (mirror its existing `detectInstalledTools({...injected deps...})` setup; add a manifest-loader dep so a third-party adapter is present):

```ts
it('detects a third-party PATH adapter from the registry', async () => {
  const result = await detectInstalledTools({
    platform: 'linux',
    pathFromEnv: async (bin: string) => (bin === 'foo' ? '/usr/bin/foo' : null),
    exists: async (p: string) => p === '/usr/bin/foo',
    execVersion: async () => '1.0.0',
    // NEW: inject the manifest-loader deps so the registry includes a 3rd-party tool
    manifestLoader: {
      dir: '/fake',
      readDir: () => ['foo.json'],
      readFile: () => JSON.stringify({ id: 'foo-cli', displayName: 'Foo', launchable: true, hookCapable: false, hookPointer: '.foo/hm.json', detect: { kind: 'path', binaryName: 'foo' } }),
    },
  });
  const foo = result.tools.find((t) => t.id === 'foo-cli');
  expect(foo?.installed).toBe(true);
  expect(foo?.installedPath).toBe('/usr/bin/foo');
});
```

- [ ] **Step 3: Run test to verify it fails**

Run: `npx vitest run packages/agent/tests/tool-detection.test.ts -t "third-party"`
Expected: FAIL — registry not wired; `manifestLoader` dep unknown.

- [ ] **Step 4: Implement** in `packages/agent/src/tool-detection.ts`:

(a) Imports — add `getToolRegistry` + the manifest type, and `BUILTIN_TOOL_MANIFESTS` is already imported via shared (it imports `SUPPORTED_TOOLS`/`TOOL_DISPLAY_NAMES`):

```ts
import { getToolRegistry } from './tool-registry.js';
import type { ManifestLoaderDeps } from './tool-manifest-loader.js';
import type { ToolManifest } from '@waggle/shared';
```

(b) A candidate-resolver map keyed by built-in id (the escape hatch — the 3 desktop tools). Place it near the candidate-path helpers:

```ts
const CANDIDATE_RESOLVERS: Record<string, (deps: ResolvedDeps) => string[]> = {
  'cursor': cursorCandidatePaths,
  'claude-desktop': claudeDesktopCandidatePaths,
  'codex-desktop': codexDesktopCandidatePaths,
};
```

(c) A manifest-driven single detector replacing the per-tool wrappers:

```ts
async function detectFromManifest(m: ToolManifest, deps: ResolvedDeps): Promise<DetectedTool> {
  if (m.detect.kind === 'path') {
    return detectByPath(m.id as ToolId, m.detect.binaryName, deps, m.hookPointer, m.displayName);
  }
  const resolver = CANDIDATE_RESOLVERS[m.id];
  const candidates = resolver ? resolver(deps) : [];
  return detectByCandidates(m.id as ToolId, candidates, deps, /* withVersion */ false, m.hookPointer, m.displayName);
}
```

(d) Generalize `detectByPath` / `detectByCandidates` / `probeHooks` to take `hookPointer` + `displayName` as params instead of reading `TOOL_DISPLAY_NAMES[id]` / `HOOK_POINTER_BY_TOOL[id]` (so third-party ids work). Change their signatures to accept `hookPointer: string, displayName: string`, and have `probeHooks(hookPointer, deps)` use the passed pointer. Keep `HOOK_POINTER_BY_TOOL` as a derived export for back-compat:

```ts
// derived from the manifests (was a hand-authored Record)
export const HOOK_POINTER_BY_TOOL = Object.fromEntries(
  BUILTIN_TOOL_MANIFESTS.map((m) => [m.id, m.hookPointer]),
) as Record<ToolId, string>;
```

(Import `BUILTIN_TOOL_MANIFESTS` from `@waggle/shared` for this.)

(e) Replace `detectInstalledTools`'s body:

```ts
export async function detectInstalledTools(
  opts: ToolDetectionDeps & { manifestLoader?: ManifestLoaderDeps } = {},
): Promise<ToolDetectionResult> {
  const deps = resolveDeps(opts);
  const registry = getToolRegistry(opts.manifestLoader);
  const tools = await Promise.all(registry.map((m) => detectFromManifest(m, deps)));
  return { platform: deps.platform, detectedAt: new Date().toISOString(), tools };
}
```

(f) Delete `detectClaudeCode`, `detectCursor`, `detectClaudeDesktop`, `detectCodex`, `detectHermes`, `detectOpenClaw`, `detectCodexDesktop`, the old `detectorsById`, and the old hand-authored `HOOK_POINTER_BY_TOOL` block. Keep `detectByPath`, `detectByCandidates`, `probeHooks`, and the 3 `*CandidatePaths` helpers.

> Note: `detectByPath` currently hardcodes `pathFromEnv('claude')` only in the inline claude-code path — the generic `detectByPath` already takes `binaryName`, so claude-code now flows through it with `binaryName: 'claude'` from its manifest. Drop the special-case inline detector.

- [ ] **Step 5: Run the FULL existing suite + new case**

Run: `npx vitest run packages/agent/tests/tool-detection.test.ts`
Expected: PASS — all existing 7-tool detection assertions + the new third-party case.

- [ ] **Step 6: Typecheck + commit**

```bash
npx tsc --noEmit -p packages/agent/tsconfig.json
git add packages/agent/src/tool-detection.ts packages/agent/tests/tool-detection.test.ts
git commit -m "feat(agent): registry-driven detectInstalledTools (#5)"
```

---

### Task 5: `agent` — derive launcher cohorts from the registry

**Files:**
- Modify: `packages/agent/src/tool-launcher.ts` (`HOOKS_COHORT`, `hookPackageFor`, the `launchTool` cohort guard)
- Test: `packages/agent/tests/tool-launcher.test.ts` (existing — stays green; add a manifest-derivation assertion)

**Interfaces:**
- Consumes: `BUILTIN_TOOL_MANIFESTS` (Task 1).

- [ ] **Step 1: Write the failing test** — append to `tool-launcher.test.ts`:

```ts
import { BUILTIN_TOOL_MANIFESTS } from '@waggle/shared';
it('HOOKS_COHORT equals the hook-capable manifests (claude-desktop excluded)', () => {
  const expected = BUILTIN_TOOL_MANIFESTS.filter((m) => m.hookCapable).map((m) => m.id).sort();
  expect([...HOOKS_COHORT].sort()).toEqual(expected);
  expect(HOOKS_COHORT).not.toContain('claude-desktop');
});
```

(`HOOKS_COHORT` is already imported/exported from `tool-launcher.ts`; add the import if missing.)

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run packages/agent/tests/tool-launcher.test.ts -t "HOOKS_COHORT equals"`
Expected: FAIL — if the literal differs OR (more likely) passes already; if it passes, still proceed to make the derivation real so it can't drift.

- [ ] **Step 3: Implement** in `packages/agent/src/tool-launcher.ts` — replace the literal `HOOKS_COHORT` with a derived one and let `hookPackageFor` honor a manifest override:

```ts
import { BUILTIN_TOOL_MANIFESTS, type ToolId } from '@waggle/shared';

export const HOOKS_COHORT: readonly ToolId[] =
  BUILTIN_TOOL_MANIFESTS.filter((m) => m.hookCapable).map((m) => m.id as ToolId);
```

(Keep `LAUNCH_COHORT`'s import from shared as-is — it's already derived in Task 1. The `launchTool` guard `if (!LAUNCH_COHORT.includes(opts.id))` is unchanged.)

- [ ] **Step 4: Run the full launcher suite**

Run: `npx vitest run packages/agent/tests/tool-launcher.test.ts`
Expected: PASS (existing 39 + new).

- [ ] **Step 5: Typecheck + commit**

```bash
npx tsc --noEmit -p packages/agent/tsconfig.json
git add packages/agent/src/tool-launcher.ts packages/agent/tests/tool-launcher.test.ts
git commit -m "feat(agent): derive HOOKS_COHORT from the manifest registry (#5)"
```

---

### Task 6: `web` — derive LauncherApp cohorts from shared manifests

**Files:**
- Modify: `apps/web/src/components/os/apps/LauncherApp.tsx` (the local `LAUNCH_COHORT` / `HOOKS_COHORT` copies, ~lines 41–59)
- Test: `apps/web/src/components/os/apps/LauncherApp.test.tsx` (existing — stays green)

- [ ] **Step 1: Implement** — replace the hand-maintained local arrays with derivations from the shared manifests (kills the "kept local to avoid a runtime import" duplication the comments call out):

```ts
import { BUILTIN_TOOL_MANIFESTS } from '@waggle/shared';

const LAUNCH_COHORT = BUILTIN_TOOL_MANIFESTS.filter((m) => m.launchable).map((m) => m.id);
const HOOKS_COHORT = BUILTIN_TOOL_MANIFESTS.filter((m) => m.hookCapable).map((m) => m.id);
```

(Delete the two local literal arrays + their explanatory comments.)

- [ ] **Step 2: Run the LauncherApp suite + web typecheck**

Run: `cd apps/web && npx vitest run -c vitest.config.ts src/components/os/apps/LauncherApp.test.tsx && npx tsc --noEmit`
Expected: PASS (6 tests) + tsc 0.

- [ ] **Step 3: Commit**

```bash
git add apps/web/src/components/os/apps/LauncherApp.tsx
git commit -m "feat(web): derive LauncherApp cohorts from shared manifests (#5)"
```

---

### Final Gate

- [ ] **Build dists then full typecheck:** `npx tsc -b packages/shared packages/agent && npx tsc --noEmit -p packages/server/tsconfig.json && (cd apps/web && npx tsc --noEmit)` → 0.
- [ ] **Touched suites:** `npx vitest run packages/shared/tests/tool-manifests.test.ts packages/agent/tests/tool-manifest-loader.test.ts packages/agent/tests/tool-registry.test.ts packages/agent/tests/tool-detection.test.ts packages/agent/tests/tool-launcher.test.ts` + `(cd apps/web && npx vitest run -c vitest.config.ts src/components/os/apps/LauncherApp.test.tsx)`.
- [ ] **Server route sanity:** `npx vitest run packages/server/tests/tools-routes.test.ts packages/server/tests/tools-routes-launch.test.ts` (they consume detect/launch — must stay green).
- [ ] **Lint** touched files.

## Fast-follow (documented, NOT silently dropped)

**Third-party `promptArgTemplate` application.** The field is captured + validated in v1 but unwired:
the inline-prompt arg logic lives web-side (`apps/web/src/lib/launcher-prompt-args.ts`) and the dock
computes args before POSTing. Wiring a loaded manifest's `promptArgTemplate` means surfacing the
registry (or its prompt templates) to the web bundle — additive, deferred. Built-in prompt-args are
unchanged.

## Self-Review

**Spec coverage:** §3 Unit A → Task 1 · Unit B (registry) → Task 3 · Unit B (detection) → Task 4 · Unit B (launcher) → Task 5 · Unit C (loader) → Task 2 · web derivation (§7 file list) → Task 6 · §5 security → Task 2 tests. The `promptArgTemplate` application is logged as a fast-follow (field captured in Task 1).

**Placeholder scan:** Task 4 Step 1 + Task 6 are read/edit steps with concrete code; no TBD/TODO. Every code step ships real code.

**Type consistency:** `ToolManifest`/`ToolDetectSpec` (Task 1) consumed unchanged in Tasks 2–6. `loadThirdPartyManifests(deps)` (Task 2) → `getToolRegistry(deps)` (Task 3) → `detectInstalledTools({manifestLoader})` (Task 4). `getToolRegistry` returns `ToolManifest[]`. `detectFromManifest`/`CANDIDATE_RESOLVERS` names consistent within Task 4. `HOOKS_COHORT`/`LAUNCH_COHORT` derived identically in Tasks 1/5/6.