typeclaw 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -45,6 +45,7 @@
     "@clack/prompts": "^1.2.0",
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.6.0",
     "agent-messenger": "2.19.1",
     "cheerio": "^1.2.0",

package/src/agent/index.ts

@@ -2,13 +2,21 @@ import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { createAgentSession, DefaultResourceLoader, SessionManager } from '@mariozechner/pi-coding-agent'
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  defineTool as definePiTool,
+  SessionManager,
+} from '@mariozechner/pi-coding-agent'
 import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent'
 
 import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
 import { defaultThinkingLevelForRef, providerForModelRef, type KnownModelRef } from '@/config/providers'
+import { renderMcpCatalog } from '@/mcp/catalog'
+import type { McpManager } from '@/mcp/manager'
+import { createMcpDispatcherTools, MCP_DISPATCHER_TOOL_NAMES } from '@/mcp/tools'
 import type { PermissionService, RolesConfig } from '@/permissions'
 import type {
   BuiltinToolRef,
@@ -34,6 +42,7 @@ import {
   wrapPluginTool,
   wrapSystemAgentTool,
   wrapSystemTool,
+  zodToToolParameters,
 } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
 import { loadSelf } from './self'
@@ -98,6 +107,7 @@ export type CreateSessionOptions = {
   sessionManager?: SessionManager
   stream?: Stream
   channelRouter?: ChannelRouter
+  mcpManager?: McpManager
   // Bypass the file-based resource loader (IDENTITY.md, SOUL.md, MEMORY.md,
   // memory/, bundled skills) and use this string verbatim as the system prompt.
   systemPromptOverride?: string
@@ -232,6 +242,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           ...(options.origin ? { origin: options.origin } : {}),
           ...(options.permissions ? { permissions: options.permissions } : {}),
           ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
+          ...(options.mcpManager !== undefined ? { mcpManager: options.mcpManager } : {}),
         })
 
   const getOrigin: () => SessionOrigin | undefined =
@@ -307,6 +318,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
             websearchTool,
             webfetchTool,
             lookAtTool,
+            ...(options.mcpManager ? buildMcpDispatcherToolDefinitions(options.mcpManager) : []),
             ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
             ...(options.stream ? [createStreamSnapshotTool({ stream: options.stream })] : []),
             ...buildChannelTools(options.channelRouter, options.origin, sessionManager.getSessionId()),
@@ -555,6 +567,40 @@ export function buildChannelTools(
   return tools
 }
 
+export function buildMcpDispatcherToolDefinitions(manager: McpManager): ToolDefinition[] {
+  const tools = createMcpDispatcherTools(manager)
+  return [
+    defineMcpDispatcherTool(MCP_DISPATCHER_TOOL_NAMES[0], tools[0]),
+    defineMcpDispatcherTool(MCP_DISPATCHER_TOOL_NAMES[1], tools[1]),
+    defineMcpDispatcherTool(MCP_DISPATCHER_TOOL_NAMES[2], tools[2]),
+  ]
+}
+
+function defineMcpDispatcherTool<P>(name: string, tool: PluginTool<P>): ToolDefinition {
+  return definePiTool({
+    name,
+    label: name,
+    description: tool.description,
+    parameters: zodToToolParameters(tool.parameters),
+    async execute(_toolCallId, params, signal) {
+      const validated = tool.parameters.safeParse(params)
+      if (!validated.success) {
+        return {
+          content: [{ type: 'text' as const, text: `invalid arguments: ${validated.error.message}` }],
+          details: null,
+        }
+      }
+      const result = await tool.execute(validated.data, {
+        signal,
+        sessionId: 'mcp-dispatcher',
+        agentDir: process.cwd(),
+        logger: { info() {}, warn() {}, error() {} },
+      })
+      return { content: result.content, details: result.details ?? null }
+    },
+  })
+}
+
 export function buildSubagentOrchestrationTools(opts: {
   liveRegistry: LiveSubagentRegistry | undefined
   registry: SubagentRegistry | undefined
@@ -722,6 +768,7 @@ export type CreateResourceLoaderOptions = {
   plugins?: PluginSessionWiring
   materializedSkills?: MaterializedSkills | null
   origin?: SessionOrigin
+  mcpManager?: McpManager
   permissions?: PermissionService
   runtimeVersion?: string
   // Explicit override for the prompt mode. When omitted, the mode is derived
@@ -785,6 +832,7 @@ export type SystemPromptComposition = {
   runtimeVersion?: string
   origin?: SessionOrigin
   roleContext?: SessionRoleContext
+  mcpCatalog?: string
   gitNudge: string
   memorySection: string
 }
@@ -822,6 +870,9 @@ export function composeSystemPrompt(parts: SystemPromptComposition): string {
   if (parts.origin !== undefined) {
     prompt = `${prompt}\n\n${renderSessionOrigin(parts.origin, Date.now(), parts.roleContext)}`
   }
+  if (parts.mcpCatalog !== undefined && parts.mcpCatalog !== '') {
+    prompt = `${prompt}\n\n${parts.mcpCatalog}`
+  }
   if (parts.gitNudge !== '') {
     prompt = `${prompt}\n\n${parts.gitNudge}`
   }
@@ -901,6 +952,9 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
     ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
     ...(options.origin !== undefined ? { origin: options.origin } : {}),
     ...(roleContext !== undefined ? { roleContext } : {}),
+    ...(mode === 'full' && options.mcpManager !== undefined
+      ? { mcpCatalog: renderMcpCatalog(options.mcpManager.listServers()) }
+      : {}),
     gitNudge,
     memorySection,
   })

package/src/agent/loop-guard.ts

@@ -1,39 +1,63 @@
-// Detects when the model calls the same tool with byte-identical arguments in
-// a tight streak — the classic "stuck in a thought-loop" failure where the
-// agent repeats `bash("ls")` or `read("foo.ts")` indefinitely waiting for a
-// different answer. Two-tier escalation:
+// Detects when the model is stuck looping on tool calls. Two independent
+// detectors run per call; the more severe decision wins.
 //
-//   - At LOOP_SOFT_WARN consecutive identical calls (default 3), the next call
-//     completes normally but the wrapped tool's output is suffixed with a nudge
-//     telling the model it's looping. Soft warning fires ONCE per streak so
-//     the model isn't drowning in identical reminders.
-//   - At LOOP_HARD_BLOCK consecutive identical calls (default 5), the call is
-//     refused outright. The wrapping in plugin-tools.ts maps the refusal to
-//     `errorResult` for plugin tools (the model sees a tool error and must
-//     change strategy) and to a thrown Error for system / pi-builtin tools
-//     (matches the existing `tool.before { block: true }` plumbing).
+// 1. Consecutive-identical (reason: 'consecutive') — catches the tight loop
+//    where the agent repeats `bash("ls")` byte-for-byte waiting for a different
+//    answer. Soft-warn at LOOP_SOFT_WARN (3), hard-block at LOOP_HARD_BLOCK (5).
 //
-// State is per-session and bounded: the guard keeps at most MAX_SESSIONS
-// session entries with LRU eviction, and each session holds at most one
-// signature + counter (we only care about the current tail streak). When a
-// different tool/args combination arrives, the streak resets to 1.
+// 2. Windowed-frequency (reason: 'windowed') — catches interleaved cycles the
+//    consecutive detector cannot see, e.g. read(a)→edit(b)→read(a)→edit(b)…, or
+//    re-reading one file with drifting offsets. Over a sliding window of the
+//    last WINDOW_SIZE calls, if one signature recurs WINDOW_SOFT_WARN times it
+//    warns and WINDOW_HARD_BLOCK times it blocks. Path-bearing tools coarsen
+//    their signature to the path alone (offsets/limits/line ranges dropped) so
+//    that paging the same file in a cycle collapses to one signature.
 //
-// The detector is intentionally placed INSIDE the tool wrappers (not as a
+// Both warn/block decisions carry the byte-identical or coarsened nudge text.
+// The wrapping in plugin-tools.ts maps a block to `errorResult` for plugin tools
+// and to a thrown Error for system / pi-builtin tools (matching the existing
+// `tool.before { block: true }` plumbing).
+//
+// State is per-session and bounded by MAX_SESSIONS with LRU eviction. The
+// detector is intentionally placed INSIDE the tool wrappers (not as a
 // `tool.before` plugin) so it covers every tool category — plugin tools,
 // TypeClaw system tools, and pi-coding-agent builtins — through one chokepoint.
 
 export const LOOP_SOFT_WARN = 3
 export const LOOP_HARD_BLOCK = 5
 
-// Caps in-process memory across many sessions. Each entry is small
-// (signature string + small counters), so this bound is generous; we just
-// don't want unbounded growth if sessionIds churn.
+export const WINDOW_SIZE = 16
+export const WINDOW_SOFT_WARN = 4
+export const WINDOW_HARD_BLOCK = 6
+
+// Tools whose first path-like argument identifies the target. Their windowed
+// signature keys on that path alone so paging one file with drifting
+// offset/limit collapses to a single signature. Two classes, because the
+// builtins differ in whether the path is required:
+//
+//   - REQUIRED-path tools (read/write/edit): path is mandatory. Coarsen only
+//     when a path key is present; an absent path is malformed input, not a
+//     default, so we must NOT collapse such calls to a shared target.
+//   - DEFAULT-path tools (grep/find/ls): path is OPTIONAL and defaults to the
+//     cwd ("."). Omitting the path and varying only non-target args (pattern,
+//     limit) still hits the same directory, so an omitted/empty path coarsens
+//     to `${tool}#path:.` — otherwise those calls would evade the detector.
+//
+// `glob` is intentionally absent: pi-coding-agent has no `glob` builtin (the
+// glob-pattern arg lives inside grep/find), so listing it here matched nothing.
+const REQUIRED_PATH_TOOLS = new Set(['read', 'write', 'edit'])
+const DEFAULT_PATH_TOOLS = new Set(['grep', 'find', 'ls'])
+const PATH_ARG_KEYS = ['path', 'file', 'filePath', 'filename']
+const DEFAULT_PATH_TARGET = '.'
+
 const MAX_SESSIONS = 256
 
+export type LoopReason = 'consecutive' | 'windowed'
+
 export type LoopGuardDecision =
   | { kind: 'ok' }
-  | { kind: 'warn'; count: number; message: string }
-  | { kind: 'block'; count: number; message: string }
+  | { kind: 'warn'; count: number; reason: LoopReason; message: string }
+  | { kind: 'block'; count: number; reason: LoopReason; message: string }
 
 export type LoopGuard = {
   check: (sessionId: string, tool: string, args: unknown) => LoopGuardDecision
@@ -42,28 +66,53 @@ export type LoopGuard = {
 }
 
 type SessionState = {
+  // Consecutive-identical streak: the current tail signature, its run length,
+  // and whether this streak already emitted its one soft warning.
   signature: string
   count: number
-  // Fires the soft warning exactly once per streak instead of every call
-  // from the 3rd onwards. Re-arms when the streak breaks.
   warned: boolean
+  // Windowed history: the last WINDOW_SIZE coarsened signatures, plus the set
+  // of signatures that already emitted their one windowed soft warning while
+  // still present in the window.
+  window: string[]
+  windowWarned: Set<string>
 }
 
 export type CreateLoopGuardOptions = {
   softWarn?: number
   hardBlock?: number
   maxSessions?: number
+  windowSize?: number
+  windowSoftWarn?: number
+  windowHardBlock?: number
 }
 
 export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard {
   const softWarn = options.softWarn ?? LOOP_SOFT_WARN
   const hardBlock = options.hardBlock ?? LOOP_HARD_BLOCK
   const maxSessions = options.maxSessions ?? MAX_SESSIONS
+  const windowSize = options.windowSize ?? WINDOW_SIZE
+  const windowSoftWarn = options.windowSoftWarn ?? WINDOW_SOFT_WARN
+  const windowHardBlock = options.windowHardBlock ?? WINDOW_HARD_BLOCK
 
   if (softWarn < 2) throw new Error(`loop-guard: softWarn must be >= 2 (got ${softWarn})`)
   if (hardBlock <= softWarn) {
     throw new Error(`loop-guard: hardBlock (${hardBlock}) must be greater than softWarn (${softWarn})`)
   }
+  if (windowSoftWarn < 2) {
+    throw new Error(`loop-guard: windowSoftWarn must be >= 2 (got ${windowSoftWarn})`)
+  }
+  if (windowHardBlock <= windowSoftWarn) {
+    throw new Error(
+      `loop-guard: windowHardBlock (${windowHardBlock}) must be greater than windowSoftWarn (${windowSoftWarn})`,
+    )
+  }
+  if (windowSize < 2) throw new Error(`loop-guard: windowSize must be >= 2 (got ${windowSize})`)
+  if (windowSize < windowHardBlock) {
+    throw new Error(
+      `loop-guard: windowSize (${windowSize}) must be >= windowHardBlock (${windowHardBlock}) for the block to be reachable`,
+    )
+  }
 
   // Map preserves insertion order; we rely on that for LRU eviction.
   const sessions = new Map<string, SessionState>()
@@ -77,50 +126,90 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
     }
   }
 
+  function evaluateConsecutive(state: SessionState, tool: string): LoopGuardDecision {
+    if (state.count >= hardBlock) {
+      return {
+        kind: 'block',
+        count: state.count,
+        reason: 'consecutive',
+        message: formatBlockMessage(tool, state.count),
+      }
+    }
+    if (state.count >= softWarn && !state.warned) {
+      state.warned = true
+      return { kind: 'warn', count: state.count, reason: 'consecutive', message: formatWarnMessage(tool, state.count) }
+    }
+    return { kind: 'ok' }
+  }
+
+  function evaluateWindowed(state: SessionState, tool: string, windowSig: string): LoopGuardDecision {
+    const count = state.window.reduce((n, sig) => (sig === windowSig ? n + 1 : n), 0)
+    if (count >= windowHardBlock) {
+      return {
+        kind: 'block',
+        count,
+        reason: 'windowed',
+        message: formatWindowedBlockMessage(tool, count),
+      }
+    }
+    if (count >= windowSoftWarn && !state.windowWarned.has(windowSig)) {
+      state.windowWarned.add(windowSig)
+      return {
+        kind: 'warn',
+        count,
+        reason: 'windowed',
+        message: formatWindowedWarnMessage(tool, count),
+      }
+    }
+    return { kind: 'ok' }
+  }
+
   return {
     check(sessionId, tool, args) {
       const signature = makeCallSignature(tool, args)
+      const windowSig = makeWindowSignature(tool, args)
       const existing = sessions.get(sessionId)
 
-      if (!existing || existing.signature !== signature) {
-        touch(sessionId, { signature, count: 1, warned: false })
-        return { kind: 'ok' }
-      }
-
-      const nextCount = existing.count + 1
-      const nextState: SessionState = {
+      const state: SessionState = existing ?? {
         signature,
-        count: nextCount,
-        warned: existing.warned,
+        count: 0,
+        warned: false,
+        window: [],
+        windowWarned: new Set(),
       }
 
-      if (nextCount >= hardBlock) {
-        touch(sessionId, nextState)
-        return {
-          kind: 'block',
-          count: nextCount,
-          message: formatBlockMessage(tool, nextCount),
-        }
+      if (state.signature !== signature) {
+        state.signature = signature
+        state.count = 1
+        state.warned = false
+      } else {
+        state.count += 1
       }
 
-      if (nextCount >= softWarn && !nextState.warned) {
-        nextState.warned = true
-        touch(sessionId, nextState)
-        return {
-          kind: 'warn',
-          count: nextCount,
-          message: formatWarnMessage(tool, nextCount),
+      state.window.push(windowSig)
+      if (state.window.length > windowSize) {
+        const evicted = state.window.shift()
+        if (evicted !== undefined && !state.window.includes(evicted)) {
+          state.windowWarned.delete(evicted)
         }
       }
 
-      touch(sessionId, nextState)
+      touch(sessionId, state)
+
+      const consecutive = evaluateConsecutive(state, tool)
+      if (consecutive.kind === 'block') return consecutive
+
+      // Back-to-back identical calls are the consecutive detector's domain; let
+      // it own them so a tight streak doesn't also trip the windowed detector.
+      // The windowed detector exists for INTERLEAVED cycles, so it only acts
+      // when this call breaks the immediate streak (count === 1).
+      const windowed = state.count === 1 ? evaluateWindowed(state, tool, windowSig) : { kind: 'ok' as const }
+      if (windowed.kind === 'block') return windowed
+      if (consecutive.kind === 'warn') return consecutive
+      if (windowed.kind === 'warn') return windowed
       return { kind: 'ok' }
     },
     reset(sessionId) {
-      const existing = sessions.get(sessionId)
-      if (!existing) return
-      // Resetting is what `tool.after` does on a non-identical call too;
-      // exposed for callers that observe a strategy change externally.
       sessions.delete(sessionId)
     },
     forget(sessionId) {
@@ -146,6 +235,24 @@ function formatBlockMessage(tool: string, count: number): string {
   )
 }
 
+function formatWindowedWarnMessage(tool: string, count: number): string {
+  return (
+    `\n\n[loop-guard] You have called \`${tool}\` on the same target ${count} times in a short span. ` +
+    `This looks like a cycle — revisiting the same work without making progress. ` +
+    `If you have enough information, produce the final answer now. ` +
+    `Otherwise change approach instead of repeating this call.`
+  )
+}
+
+function formatWindowedBlockMessage(tool: string, count: number): string {
+  return (
+    `loop-guard: refused \`${tool}\` — called on the same target ${count} times in a short span. ` +
+    `You are cycling on the same work. Stop. Either (1) produce the final answer with the data you already have, ` +
+    `(2) ask the user a clarifying question, or (3) try a meaningfully different approach. ` +
+    `Do not keep re-running this on the same target.`
+  )
+}
+
 function makeCallSignature(tool: string, args: unknown): string {
   try {
     return `${tool}:${stableStringify(args)}`
@@ -154,6 +261,26 @@ function makeCallSignature(tool: string, args: unknown): string {
   }
 }
 
+// Coarsened signature for windowed detection: path-bearing tools key on their
+// target path alone so re-reading one target with drifting non-path args
+// collapses to a single signature. All other tools fall back to the exact
+// signature.
+function makeWindowSignature(tool: string, args: unknown): string {
+  const isRequiredPath = REQUIRED_PATH_TOOLS.has(tool)
+  const isDefaultPath = DEFAULT_PATH_TOOLS.has(tool)
+  if ((isRequiredPath || isDefaultPath) && args !== null && typeof args === 'object') {
+    const record = args as Record<string, unknown>
+    for (const key of PATH_ARG_KEYS) {
+      const value = record[key]
+      if (typeof value === 'string' && value.length > 0) return `${tool}#path:${value}`
+    }
+    // No explicit path. For default-path tools the effective target is the cwd,
+    // so coarsen to it; for required-path tools we leave the call uncoarsened.
+    if (isDefaultPath) return `${tool}#path:${DEFAULT_PATH_TARGET}`
+  }
+  return makeCallSignature(tool, args)
+}
+
 // Order-independent JSON serialization so semantically-identical objects
 // produce identical signatures regardless of key insertion order.
 function stableStringify(value: unknown): string {

package/src/bundled-plugins/bun-hygiene/README.md

@@ -0,0 +1,82 @@
+# typeclaw-plugin-bun-hygiene
+
+The bundled bun-hygiene plugin. Registers a `tool.before` hook that blocks two classes of `bash` command:
+
+1. **Global package installs** — `npm install -g`, `pnpm add -g`, `yarn global add`, `bun add -g`, and their `--global` / bundled-flag variants.
+2. **Non-bun package managers** — any `npm`, `npx`, `pnpm`, `pnpx`, or `yarn` invocation.
+
+This plugin is **auto-loaded** by every TypeClaw agent. There is no `plugins[]` entry to add. Both guards carry an `acknowledgeGuards` escape hatch (below) for the cases where the agent genuinely needs the blocked command.
+
+## Why it exists
+
+**Global installs don't persist.** The agent folder is bind-mounted at `/agent`; everything else in the container — including `~/.bun`, `~/.npm`, and the global `node_modules` a global install writes to — is ephemeral and wiped on every `typeclaw restart`. An agent that runs `npm install -g some-cli` gets a tool that works for the rest of the session and silently vanishes on the next boot, leading to confusing "command not found" failures that look like regressions. The fix is to either add the dependency to `package.json` (`bun add <pkg>`, which lives in the bind-mounted folder and survives) or run it once without installing (`bunx <pkg>`).
+
+**The container standardizes on bun.** TypeClaw is Bun-native end to end (see the root README). Mixing in `npm`/`pnpm`/`yarn` produces competing lockfiles and install trees, and `npx` pulls a second package-execution path when `bunx` already covers it. Steering every package-manager call to bun keeps the dependency state coherent.
+
+Both guards **block with guidance** rather than silently rewriting the command — the agent sees exactly why the command was rejected and what to run instead, the same UX as the bundled `security` and `guard` policies.
+
+## Guards
+
+| Guard                  | Triggers on                                                                                       | Guidance in the block reason                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `globalInstall`        | `npm`/`pnpm` install/add with `-g`/`--global`, `yarn global add`, `bun add -g` / `bun install -g` | Use `bun add <pkg>` (persists) or `bunx <pkg>` (ephemeral run).            |
+| `nonBunPackageManager` | `npm`, `npx`, `pnpm`, `pnpx`, `yarn` at a command boundary                                        | Use `bun install` / `bun add <pkg>`, and `bunx <pkg>` instead of npx/pnpx. |
+
+A global install (e.g. `npm install -g x`) trips **only** `globalInstall`, not both — the global install is the more specific violation, so acknowledging `globalInstall` lets the command through without a second acknowledgement for `nonBunPackageManager`.
+
+## Bypass
+
+Both guards follow the repo-wide `acknowledgeGuards` convention (shared with the `security` and `guard` plugins). To run a blocked command intentionally, pass the matching flag in the `bash` tool arguments:
+
+```jsonc
+// bash tool args
+{ "command": "npm install", "acknowledgeGuards": { "nonBunPackageManager": true } }
+{ "command": "npm install -g some-cli", "acknowledgeGuards": { "globalInstall": true } }
+```
+
+## How it works
+
+`checkBunHygieneGuard` in `policy.ts` does not regex the raw command. It runs a small single-pass tokenizer (`splitSegments`) that turns the command into a list of **segments**, each a list of **words**:
+
+- Segments break on real command separators — `;`, `&&`, `||`, `|`, `&`, newline, `\r` — and on subshell / command-substitution openers (`(`, `$(`, backtick), **including `$(`/backtick inside double quotes** (Bash executes those, e.g. `echo "$(npm install -g x)"`; the outer double-quote mode resumes when the substitution closes so a trailing command isn't swallowed). Single-quoted bodies stay literal, matching Bash.
+- The tokenizer is quote-aware (a separator inside `"..."`/`'...'` is literal) and escape-aware (`\x` is a literal `x`, so `\npm` resolves to `npm` and `\;` is not a separator). A `\<newline>` is a POSIX line continuation — it is removed and the surrounding text joined, so `npm install \⏎-g x` is one command (a global install), while a bare newline separates commands.
+
+For each segment, the guard strips leading **preamble wrappers** (`sudo`, `env`, `command`, `exec`, `nice`, `nohup`, `stdbuf`, `setsid`, `time`, `xargs`, and any `VAR=val` assignment) — including their options, and the argument a flag consumes (`sudo -u nobody`, `nice -n 10`, `env -i`) — to find the real command word, then classifies:
+
+1. command word is `npm`/`npx`/`pnpm`/`pnpx`/`yarn` (or `bun`) **and** the segment has an install subcommand **and** a global flag → `globalInstall` (for `yarn`, the `global add` sequence must appear adjacent and in command position, so `yarn add global foo` — a local install of a package named `global` — is not misflagged);
+2. command word is a non-bun manager (not via global) → `nonBunPackageManager`;
+3. otherwise → allowed.
+
+A `globalInstall` verdict on any segment wins over a plain non-bun verdict. This is a command-position detector, not a full shell parser — it doesn't interpret redirections or expansions beyond boundary marking — but it is linear-time and closes the structural gaps a single regex left open.
+
+## Scope: not a security boundary
+
+This guard is a **hygiene nudge**, not an isolation mechanism. It deliberately does not chase manager invocations hidden inside a wrapper's code payload — `sh -c 'npm install'`, `bash -lc "pnpm add foo"`, `python -c '...os.system("npx tsc")'`, `node -e`, `eval`, `base64 | sh`, etc. That set is unbounded (any interpreter can reach any binary), and inspecting arbitrary `-c`/`-e` payloads is an arms race with diminishing returns and rising false-positive risk. An agent that genuinely wants a package manager can always reach one; the guard's job is to steer the common, direct invocations toward bun and to stop accidental global installs. The real isolation boundary is the per-tool **bwrap sandbox** (see `/docs/internals/sandbox`), not this policy. Optioned preamble _wrappers_ (`env -i`, `sudo -u`, `nice -n`) are handled because they prefix a real command word that the tokenizer can still see; code-payload wrappers are not, by design.
+
+## Why a tokenizer, not a regex
+
+The earlier implementation matched boundary-anchored regexes against an escape/quote-normalized copy of the command. Review surfaced three structural gaps that are awkward to close with one regex but fall out naturally from the segment model:
+
+- **Escaped / quoted command words.** `\npm install`, `"npm" install`, `'npm' install`, `n\px …` all run the real binary; the tokenizer collapses escapes and quotes at the word level, so each resolves to its bare command word.
+- **Leading assignments.** `FOO=bar npm install` runs npm with `FOO` set. Stripping `VAR=val` (and `sudo`/`env`/`command`/`exec`/`nice`) preamble words finds the manager behind them.
+- **Newline = separate command.** `npm install\n-g typescript` is two commands; the `-g` does not make the install global. Per-segment scoping means a flag in one segment never combines with an install in another, so this classifies as `nonBunPackageManager` (the `npm install` line), not `globalInstall`.
+
+It also recognizes an explicit falsy global flag (`--global=false|0|no|off`) as **not** a global install, and detects managers inside subshells / command substitutions.
+
+## Option placement in global installs
+
+Because classification scans a segment's words as a set (after preamble stripping), options may sit anywhere relative to the subcommand and the global flag, in either order: `npm --prefix /tmp install -g x`, `npm install --foo bar -g x`, `npm -g install x`, `pnpm add --reporter silent -g foo`, and `bun --cwd /x add -g foo` all attribute to `globalInstall`.
+
+## What is NOT blocked
+
+- `bun`, `bunx`, `bun run`, `bun add`, `bun install` (local) — the intended package commands. (`bun add -g` / `bun install -g` are still blocked as global installs: bun globals live in `~/.bun`, outside `/agent`, and are wiped on restart.)
+- A non-bun manager name appearing as a substring or argument: `my-npm-wrapper`, `./npm`, `cat npm-debug.log`, `git commit -m "drop npm"`, `grep -rn npx src/`, `echo "npm install -g foo"`. Only the **command word** of a segment is classified, so a manager name inside an argument, path, quoted string, or longer token never trips the guard.
+
+## Ordering against other bundled plugins
+
+Registered after `guard` in `src/run/bundled-plugins.ts`. It guards a disjoint surface (package-manager bash commands), so its position only matters for precedence: keeping it after `security` and `guard` means any of their blocks wins first.
+
+## Tests
+
+- `policy.test.ts` — pure-function unit tests for the detection logic: every global-install form, every non-bun manager, the allowed-command set (bun/bunx, substrings, paths, quoted text), both bypasses, the global-install-takes-precedence rule, escaped/quoted evasions, leading-assignment preambles, newline-as-separator scoping, falsy `--global=`, option placement, and subshell/substitution detection.
+- `index.test.ts` — composition tests: the plugin registers the `tool.before` hook and wires it to the policy (block on global install, block on npx, allow bunx, honor the bypass).

package/src/bundled-plugins/bun-hygiene/index.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { checkBunHygieneGuard } from './policy'
+
+export default definePlugin({
+  plugin: async () => ({
+    hooks: {
+      'tool.before': (event) => checkBunHygieneGuard({ tool: event.tool, args: event.args }),
+    },
+  }),
+})