typeclaw 0.5.1 → 0.7.0

package/README.md

@@ -2,51 +2,48 @@
 
 > A TypeScript-native, Bun-powered, Docker-friendly general-purpose agent runtime.
 
-## Why?
-
-There are great agents out there. None of them were quite the shape I wanted:
+Full docs: **[typeclaw.dev](https://typeclaw.dev)**.
 
-- **OpenClaw** — feature-rich, but heavy
-- **NanoClaw** — simple, but no plugin system
-- **PicoClaw** — fast, but Go (so plugins live outside the runtime)
-- **ZeroClaw** — light, but Rust (same problem, different ecosystem)
-- **Hermes Agent** — awesome, but Python
+## Why?
 
-None of that matters to most people. It matters to me. If you're like me, TypeClaw is the right choice.
+There are great agents out there. None of them were quite the shape I wanted — most are written in Go, Rust, or Python, which means plugins live outside the runtime (IPC, FFI, or a separate process). The ones in TypeScript are either too heavy or too bare.
 
 TypeClaw is the agent I wanted to use:
 
 - **TypeScript end to end** — agent core, plugins, channel adapters, CLI, TUI all in one language
 - **Bun-native plugins** — plugins are just TS modules; no IPC, no FFI, hot-reloadable config
 - **Docker-friendly by default** — every agent runs in its own container; the host CLI is purely a launcher
-- **Multi-channel out of the box** — Slack, Discord, TUI, websocket — all routed through one in-process stream
 - **Self-improving** — the agent observes its own work, distills it into long-term memory and reusable skills, and gets sharper over time without you writing prompts for it
 
-## Features
+If you're like me, TypeClaw is the right choice. If not, that's fine too.
 
-- 🐳 **Sandboxed by default** — every agent runs in its own Docker container, with an `.env` and bind-mounted host folders
-- 🔌 **Plugin system** — plain TypeScript modules contribute tools, skills, subagents, channels, and typed config
-- 💬 **Multi-channel** — Slack, Discord, and a websocket TUI out of the box; one agent, many inboxes
-- 👥 **Group chat awareness** — knows who's in the room, distinguishes humans from bots, and stays engaged after a reply without re-mentioning
+## What you'd expect
+
+- 🐳 **Sandboxed by default** — every agent runs in its own Docker container with `.env` injection and bind-mounted host folders
+- 🔌 **Plugin system** — plain TypeScript modules contribute tools, skills, subagents, channels, commands, and typed config
+- 💬 **Multi-channel** — Slack, Discord, Telegram, KakaoTalk, GitHub webhooks, and a websocket TUI; one agent, many inboxes
 - ⏰ **Cron** — schedule prompts or shell commands; per-job coalescing so slow jobs don't pile up
 - 📚 **Skills on demand** — markdown procedures the agent loads only when relevant; zero token cost until used
-- 🌱 **Self-improving** — bundled memory plugin observes the agent's work and consolidates it into long-term memory (see below)
-- 🧠 **Muscle memory** — repeated procedures get distilled into reusable skills that the agent writes for itself
-- 🔄 **Hot reload** — change `typeclaw.json`, `typeclaw reload` — no restart for most fields
-- 🔁 **Self-restart** — the agent can bounce its own container when it updates itself
-- 🌐 **Auto port-forward** — dev servers inside the container appear on `localhost`, even loopback-only ones
-- 🌍 **Public tunnels** — Cloudflare Quick (zero signup) or bring-your-own external URL; the agent self-registers GitHub webhooks at the resulting public URL
-- 🎼 **Compose** — orchestrate multiple agents across multiple folders
-
-### 🌱 Self-improving, in detail
+- 🔎 **Web research** — bundled `scout` subagent plus first-class `websearch` and `webfetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
+- 🛡 **Security guards** — bundled `tool.before` policies catch secret exfil, SSRF, prompt injection, and tainted git remotes before they fire
+- 📊 **Usage and doctor** — `typeclaw usage` reports token/$ spend per session, model, or day; `typeclaw doctor` diagnoses host, agent folder, and plugin state
 
-The bundled `memory` plugin turns lived experience into reusable knowledge. No manual prompt engineering. No curated example library.
+## Where it goes further
 
-1. **Observe.** After every idle turn, a `memory-logger` subagent reads the transcript and appends notable fragments to `memory/yyyy-MM-dd.md`. Cheap, frequent, lossy by design.
-2. **Dream.** On a cron schedule (default 4am), a `dreaming` subagent consolidates daily streams into `MEMORY.md`, and — when it spots a procedure worth remembering — writes it as **muscle memory**: a new skill at `memory/skills/<name>/SKILL.md`.
-3. **Apply.** Tomorrow's prompt sees the updated `MEMORY.md`. Muscle-memory skills sit alongside bundled and user-installed ones, loaded on demand. Every dream is committed with a one-line summary — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮` — so growth is auditable.
+- 🌱 **Self-improving** — bundled `memory` plugin distills sessions into long-term `MEMORY.md` without you writing prompts for it
+- 🧠 **Muscle memory** — repeated procedures get distilled into reusable skills the agent writes for itself and loads on later runs
+- 💾 **Auto-backup** — the bundled `backup` plugin commits session logs and memory on every idle window with an LLM-generated commit subject
+- 🪄 **Subagents** — first-class child sessions with their own system prompt, payload schema, and per-payload coalescing; cron and the main agent fire them through one in-process Stream
+- 🪪 **Roles and permissions** — `owner` / `trusted` / `member` / `guest` with first-message match rules per channel; gates `channel.respond`, cron scheduling, and security bypasses, so a Slack stranger can't tell the agent to push to main
+- 👥 **Group chat awareness** — knows who's in the room, distinguishes humans from bots, and stays engaged after a reply without re-mentioning
+- 🧱 **Managed-file guards** — `typeclaw.json`, `cron.json`, `MEMORY.md`, and bundled skills are protected from accidental rewrites; invalid config writes are rejected at the tool boundary
+- 🌐 **Headed browser inside the container** — bundled `agent-browser` plugin ships Chrome under Xvfb so the agent can drive real web pages past bot fingerprinting
+- 🌍 **Tunnels and auto port-forward** — dev servers inside the container appear on `localhost` (even loopback-only ones); public URLs via Cloudflare Quick (zero signup) or your own external URL, with GitHub webhooks self-registered at the resulting URL
+- 🔄 **Hot reload** — change `typeclaw.json`, run `typeclaw reload` — no restart for most fields
+- 🔁 **Self-restart** — the agent can bounce its own container when it updates itself
+- 🎼 **Compose** — orchestrate multiple agents across multiple folders
 
-See [`src/bundled-plugins/memory/README.md`](./src/bundled-plugins/memory/README.md) for the full contract.
+Memory loop and subagent architecture are covered in detail in [AGENTS.md](./AGENTS.md) and [`src/bundled-plugins/memory/README.md`](./src/bundled-plugins/memory/README.md).
 
 ## Install
 
@@ -67,59 +64,7 @@ typeclaw tui         # attach a terminal UI to the running agent
 
 That's it. The agent is now alive, listening on a websocket, ready to receive prompts from the TUI or any wired channel.
 
-## CLI
-
-| Command                             | Purpose                                                                             |
-| ----------------------------------- | ----------------------------------------------------------------------------------- |
-| `typeclaw init`                     | Scaffold a new agent folder                                                         |
-| `typeclaw start`                    | Build and run the container                                                         |
-| `typeclaw stop`                     | Stop the container                                                                  |
-| `typeclaw restart`                  | `stop` then `start`                                                                 |
-| `typeclaw status`                   | Show container + daemon registration state                                          |
-| `typeclaw logs`                     | Stream container stdout/stderr with local timestamps; `-f` to follow                |
-| `typeclaw tui`                      | Attach a terminal UI over the agent's websocket                                     |
-| `typeclaw shell`                    | Open a shell inside the running container                                           |
-| `typeclaw reload`                   | Push a live config reload to the running agent                                      |
-| `typeclaw compose`                  | Orchestrate multiple agents                                                         |
-| `typeclaw cron list`                | List every cron job registered in the running agent (user `cron.json` + plugins)    |
-| `typeclaw channel add <kind>`       | Wire a new channel adapter (Slack, Discord, Telegram, KakaoTalk, GitHub)            |
-| `typeclaw channel set <kind>`       | Rotate the credentials of an already-configured channel (bot/app tokens, PAT, etc.) |
-| `typeclaw channel reauth kakaotalk` | Re-authenticate KakaoTalk after a stale-token 401 or to rotate the stored password  |
-| `typeclaw tunnel ...`               | Add/list/status/remove public tunnels and inspect tunnel logs                       |
-
-## Configuration
-
-Agent folder layout after `init`:
-
-```
-my-agent/
-├── typeclaw.json     # main config (schema-validated)
-├── cron.json         # scheduled jobs (optional)
-├── .env              # secrets, injected via --env-file
-├── Dockerfile        # auto-managed by typeclaw, refreshed every `start`
-├── package.json      # `typeclaw` as a dependency
-├── .gitignore        # auto-managed
-├── workspace/        # agent's free-write zone (gitignored)
-├── sessions/         # JSONL session logs (gitignored, force-committed by auto-backup)
-└── memory/           # MEMORY.md + muscle-memory skills (gitignored, force-committed by dreaming)
-```
-
-`typeclaw.json` is JSON Schema–validated (see `typeclaw.schema.json`). Highlights:
-
-- `port` — preferred host port (CLI falls back to ephemeral on conflict)
-- `mounts` — host directories to expose inside the container
-- `plugins` — list of plugin module specifiers
-- `channels` — `slack-bot` / `discord-bot` config
-- `portForward` — allow/deny list for auto port forwarding (default: `*`)
-- `tunnels` — declare public URLs for inbound webhooks and ad-hoc exposure (`cloudflare-quick` or `external`)
-- `dockerfile` — toggles for `gh`, `python`, `tmux`, `ffmpeg`, `cjkFonts`, plus `append` lines
-- `memory` — idle window and dreaming schedule for the memory plugin
-
-`Dockerfile` and `.gitignore` are owned by TypeClaw and rewritten on every `start` — edit `src/init/dockerfile.ts` and re-run `start --build` to ship template changes.
-
-### Secrets
-
-Credentials live in two gitignored files: `.env` (plain `KEY=value` lines, injected into the container via `--env-file`) and `secrets.json` (a structured store managed by TypeClaw). **Env-wins**: when a credential's canonical env var (e.g. `FIREWORKS_API_KEY`, `SLACK_BOT_TOKEN`) is set, that value is used at runtime — `secrets.json` is never auto-mutated to capture it. Every secret-bearing field in `secrets.json` is a `Secret` (`string | { value?, env? }`), so the file can rebind a credential to a custom env-var name on demand. See [AGENTS.md § Secrets](./AGENTS.md#secrets) for the full contract.
+See `typeclaw --help` for the full command surface, or [typeclaw.dev](https://typeclaw.dev) for guides and configuration reference.
 
 ## Development
 
@@ -130,7 +75,7 @@ bun install
 bun test
 ```
 
-Pre-commit checks (must all pass — no exceptions):
+Pre-commit checks (all must pass — no exceptions):
 
 ```sh
 bun run typecheck
@@ -138,7 +83,12 @@ bun run lint
 bun run format
 ```
 
-See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy.
+See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy. The docs site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/).
+
+## Acknowledgments
+
+- **Multi-channel** is powered by [agent-messenger](https://github.com/agent-messenger/agent-messenger) — every non-GitHub adapter (`slack-bot`, `discord-bot`, `telegram-bot`, `kakaotalk`) is built on its SDK. Thanks to the maintainers for the credential extraction, listener protocols, and platform coverage that made multi-channel a feature instead of a year-long project.
+- **Subagent architecture** is inspired by [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) by [@code-yeongyu](https://github.com/code-yeongyu). Thanks for the shape that made this clean.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/index.ts

@@ -25,12 +25,14 @@ import type { Stream } from '@/stream'
 import { getAuthFor } from './auth'
 import { createCompactionSettingsManager } from './compaction'
 import { renderGitNudge } from './git-nudge'
+import type { LiveSubagentRegistry } from './live-subagents'
 import { lookAtTool } from './multimodal'
 import { resolveBuiltinToolRefs, wrapPluginTool, wrapSystemAgentTool, wrapSystemTool } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
 import { loadSelf } from './self'
 import { SESSION_META_CUSTOM_TYPE, sessionMetaPayload } from './session-meta'
 import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
+import type { CreateSessionForSubagent, SubagentRegistry } from './subagents'
 import { DEFAULT_SYSTEM_PROMPT, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
 import {
   createBudgetState,
@@ -43,7 +45,10 @@ import { createChannelHistoryTool } from './tools/channel-history'
 import { createChannelReplyTool } from './tools/channel-reply'
 import { createChannelSendTool } from './tools/channel-send'
 import { createRestartTool } from './tools/restart'
+import { createSpawnSubagentTool } from './tools/spawn-subagent'
 import { createStreamSnapshotTool } from './tools/stream-snapshot'
+import { createSubagentCancelTool } from './tools/subagent-cancel'
+import { createSubagentOutputTool } from './tools/subagent-output'
 import { webfetchTool } from './tools/webfetch'
 import { websearchTool } from './tools/websearch'
 
@@ -153,6 +158,16 @@ export type CreateSessionOptions = {
   // already seen") provide their own here. See `ToolResultBudget` for the
   // shared shape.
   toolResultBudgetMessage?: ToolResultBudget['exhaustedMessage']
+  // Orchestration wiring. When all three of `liveSubagentRegistry`,
+  // `subagentRegistry`, and `createSessionForSubagent` are present (AND
+  // `pluginSubagent` is unset), the session exposes the spawn_subagent,
+  // subagent_output, and subagent_cancel tools. Subagent-origin sessions
+  // get an empty tool set via the `pluginSubagent` branch; the gate here
+  // (omitting these for subagent sessions) is what prevents recursive
+  // spawning.
+  liveSubagentRegistry?: LiveSubagentRegistry
+  subagentRegistry?: SubagentRegistry
+  createSessionForSubagent?: CreateSessionForSubagent
 }
 
 export type CreateSessionResult = {
@@ -205,9 +220,16 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
   const getOrigin: () => SessionOrigin | undefined =
     options.originRef !== undefined ? () => options.originRef!.current : () => options.origin
 
-  const subagentBuiltinTools = options.pluginSubagent?.toolRefs
+  // Subagent built-in tool refs are dual-routed (see BUILTIN_TOOL_DEFINITION
+  // dual-map in plugin-tools.ts): pi-side coding tools go to `tools:` so they
+  // become the strict base set, typeclaw-side web tools go to `customTools:`.
+  // The two `tools:` fields below (effective `options.tools` and the resolved
+  // subagent pi-side builtins) are mutually exclusive — `options.tools` is only
+  // passed by non-subagent callers like multimodal look-at; subagent sessions
+  // never set both.
+  const resolvedSubagentBuiltins = options.pluginSubagent?.toolRefs
     ? resolveBuiltinToolRefs(options.pluginSubagent.toolRefs)
-    : undefined
+    : { agentTools: [], toolDefinitions: [] }
   const pluginCustomTools = options.pluginSubagent
     ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin)
     : wrapRegistryTools(options.plugins, getOrigin)
@@ -224,11 +246,9 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     : undefined
   const sessionBudgetState = sessionBudget ? createBudgetState() : undefined
 
-  const hookWrappedTools = wrapSystemAgentTools(
-    options.tools ?? (subagentBuiltinTools as AgentSessionTools | undefined),
-    options.plugins,
-    getOrigin,
-  )
+  const effectiveTools =
+    options.tools ?? (options.pluginSubagent ? (resolvedSubagentBuiltins.agentTools as AgentSessionTools) : undefined)
+  const hookWrappedTools = wrapSystemAgentTools(effectiveTools, options.plugins, getOrigin)
   const tools =
     sessionBudget && sessionBudgetState && hookWrappedTools
       ? (hookWrappedTools.map((t) =>
@@ -265,7 +285,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     options.customTools !== undefined
       ? options.customTools
       : options.pluginSubagent
-        ? []
+        ? resolvedSubagentBuiltins.toolDefinitions
         : [
             websearchTool,
             webfetchTool,
@@ -282,6 +302,16 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
                   }),
                 ]
               : []),
+            ...buildSubagentOrchestrationTools({
+              liveRegistry: options.liveSubagentRegistry,
+              registry: options.subagentRegistry,
+              createSessionForSubagent: options.createSessionForSubagent,
+              agentDir: options.plugins?.agentDir,
+              parentSessionId: sessionManager.getSessionId(),
+              getOrigin,
+              permissions: options.permissions,
+              stream: options.stream,
+            }),
           ]
   const customToolsPreBudget = [...wrapSystemTools(customSystemTools, options.plugins, getOrigin), ...pluginCustomTools]
   const customTools =
@@ -430,6 +460,48 @@ export function buildChannelTools(
   return tools
 }
 
+export function buildSubagentOrchestrationTools(opts: {
+  liveRegistry: LiveSubagentRegistry | undefined
+  registry: SubagentRegistry | undefined
+  createSessionForSubagent: CreateSessionForSubagent | undefined
+  agentDir: string | undefined
+  parentSessionId: string
+  getOrigin: () => SessionOrigin | undefined
+  permissions: PermissionService | undefined
+  stream: Stream | undefined
+}): ToolDefinition[] {
+  if (
+    opts.liveRegistry === undefined ||
+    opts.registry === undefined ||
+    opts.createSessionForSubagent === undefined ||
+    opts.agentDir === undefined
+  ) {
+    return []
+  }
+  return [
+    createSpawnSubagentTool({
+      registry: opts.registry,
+      liveRegistry: opts.liveRegistry,
+      createSessionForSubagent: opts.createSessionForSubagent,
+      agentDir: opts.agentDir,
+      parentSessionId: opts.parentSessionId,
+      getOrigin: opts.getOrigin,
+      ...(opts.permissions ? { permissions: opts.permissions } : {}),
+      ...(opts.stream ? { stream: opts.stream } : {}),
+    }),
+    createSubagentOutputTool({
+      liveRegistry: opts.liveRegistry,
+      getOrigin: opts.getOrigin,
+      ...(opts.permissions ? { permissions: opts.permissions } : {}),
+    }),
+    createSubagentCancelTool({
+      liveRegistry: opts.liveRegistry,
+      getOrigin: opts.getOrigin,
+      ...(opts.permissions ? { permissions: opts.permissions } : {}),
+    }),
+  ]
+}
+
 function wrapRegistryTools(
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,

package/src/agent/live-subagents.ts

@@ -0,0 +1,215 @@
+import type { AgentSession } from './index'
+
+export type SubagentProgressEvent =
+  | { kind: 'started'; ts: number }
+  | { kind: 'tool'; name: string; ok: boolean; ts: number }
+  | { kind: 'message'; preview: string; ts: number }
+
+export type SubagentStatus = 'running' | 'completed' | 'failed'
+
+export type SubagentCompletion = {
+  ok: boolean
+  finalMessage?: string
+  error?: string
+  durationMs: number
+}
+
+export type LiveSubagent = {
+  taskId: string
+  sessionId: string
+  subagentName: string
+  parentSessionId?: string
+  startedAt: number
+  status: SubagentStatus
+  completion?: SubagentCompletion
+  abort: () => Promise<void>
+  awaitCompletion: () => Promise<SubagentCompletion>
+}
+
+export const MAX_EVENTS_PER_SUBAGENT = 100
+export const MESSAGE_PREVIEW_CHARS = 200
+
+type AgentSessionEvent =
+  | { type: 'message_update'; assistantMessageEvent: { type: string; delta?: string } }
+  | { type: 'message_end'; message: unknown }
+  | { type: 'tool_execution_start'; toolCallId: string; toolName: string; args: unknown }
+  | { type: 'tool_execution_end'; toolCallId: string; toolName: string; result: unknown; isError: boolean }
+  | { type: string }
+
+export function coarsen(event: AgentSessionEvent, now: number): SubagentProgressEvent | null {
+  if (event.type === 'tool_execution_end') {
+    const ev = event as Extract<AgentSessionEvent, { type: 'tool_execution_end' }>
+    return { kind: 'tool', name: ev.toolName, ok: !ev.isError, ts: now }
+  }
+  if (event.type === 'message_end') {
+    const ev = event as Extract<AgentSessionEvent, { type: 'message_end' }>
+    const preview = extractMessagePreview(ev.message)
+    if (preview === null) return null
+    return { kind: 'message', preview, ts: now }
+  }
+  return null
+}
+
+function extractMessagePreview(message: unknown): string | null {
+  if (message === null || typeof message !== 'object') return null
+  const content = (message as { content?: unknown }).content
+  if (typeof content === 'string') {
+    const trimmed = content.trim()
+    return trimmed ? trimmed.slice(0, MESSAGE_PREVIEW_CHARS) : null
+  }
+  if (Array.isArray(content)) {
+    for (const part of content) {
+      if (part && typeof part === 'object' && (part as { type?: unknown }).type === 'text') {
+        const text = (part as { text?: unknown }).text
+        if (typeof text === 'string') {
+          const trimmed = text.trim()
+          if (trimmed) return trimmed.slice(0, MESSAGE_PREVIEW_CHARS)
+        }
+      }
+    }
+  }
+  return null
+}
+
+export type StatusSnapshot = {
+  taskId: string
+  sessionId: string
+  subagentName: string
+  status: SubagentStatus
+  startedAt: number
+  elapsedMs: number
+  eventsCount: number
+  eventsRecent: SubagentProgressEvent[]
+  lastActivity: SubagentProgressEvent | null
+  statusSummary: string
+  completion?: SubagentCompletion
+}
+
+export class LiveSubagentRegistry {
+  private readonly entries = new Map<string, LiveSubagent>()
+  private readonly events = new Map<string, SubagentProgressEvent[]>()
+
+  register(live: LiveSubagent): void {
+    if (this.entries.has(live.taskId)) {
+      throw new Error(`task ${live.taskId} already registered`)
+    }
+    this.entries.set(live.taskId, live)
+    this.events.set(live.taskId, [{ kind: 'started', ts: live.startedAt }])
+  }
+
+  unregister(taskId: string): void {
+    this.entries.delete(taskId)
+    this.events.delete(taskId)
+  }
+
+  get(taskId: string): LiveSubagent | undefined {
+    return this.entries.get(taskId)
+  }
+
+  list(filter?: { parentSessionId?: string }): LiveSubagent[] {
+    const all = Array.from(this.entries.values())
+    if (filter?.parentSessionId === undefined) return all
+    return all.filter((e) => e.parentSessionId === filter.parentSessionId)
+  }
+
+  hasLiveForSession(sessionId: string): boolean {
+    for (const e of this.entries.values()) {
+      if (e.sessionId === sessionId && e.status === 'running') return true
+    }
+    return false
+  }
+
+  recordEvent(taskId: string, event: SubagentProgressEvent): void {
+    const ring = this.events.get(taskId)
+    if (ring === undefined) return
+    ring.push(event)
+    if (ring.length > MAX_EVENTS_PER_SUBAGENT) {
+      ring.splice(0, ring.length - MAX_EVENTS_PER_SUBAGENT)
+    }
+  }
+
+  recordCompletion(taskId: string, completion: SubagentCompletion): void {
+    const entry = this.entries.get(taskId)
+    if (entry === undefined) return
+    entry.completion = completion
+    entry.status = completion.ok ? 'completed' : 'failed'
+  }
+
+  snapshot(taskId: string, now: number = Date.now()): StatusSnapshot | undefined {
+    const entry = this.entries.get(taskId)
+    if (entry === undefined) return undefined
+    const events = this.events.get(taskId) ?? []
+    const eventsRecent = events.slice(-10)
+    const lastActivity: SubagentProgressEvent | null = events.length > 0 ? (events[events.length - 1] ?? null) : null
+    const elapsedMs = (entry.completion ? entry.startedAt + entry.completion.durationMs : now) - entry.startedAt
+    return {
+      taskId: entry.taskId,
+      sessionId: entry.sessionId,
+      subagentName: entry.subagentName,
+      status: entry.status,
+      startedAt: entry.startedAt,
+      elapsedMs,
+      eventsCount: events.length,
+      eventsRecent,
+      lastActivity,
+      statusSummary: renderStatusSummary(entry, events.length, lastActivity, elapsedMs),
+      ...(entry.completion ? { completion: entry.completion } : {}),
+    }
+  }
+
+  clear(): void {
+    this.entries.clear()
+    this.events.clear()
+  }
+}
+
+function renderStatusSummary(
+  entry: LiveSubagent,
+  eventsCount: number,
+  lastActivity: SubagentProgressEvent | null,
+  elapsedMs: number,
+): string {
+  const elapsed = formatElapsed(elapsedMs)
+  if (entry.status === 'completed') return `Completed in ${elapsed}.`
+  if (entry.status === 'failed') {
+    const err = entry.completion?.error ?? 'unknown error'
+    return `Failed after ${elapsed}: ${err}`
+  }
+  const last = describeLastActivity(lastActivity)
+  return `Running for ${elapsed}. ${eventsCount} event${eventsCount === 1 ? '' : 's'} so far${last ? `. Last: ${last}` : ''}.`
+}
+
+function describeLastActivity(event: SubagentProgressEvent | null): string | null {
+  if (event === null) return null
+  if (event.kind === 'tool') return `${event.ok ? '' : 'failed '}tool ${event.name}`
+  if (event.kind === 'message') {
+    const preview = event.preview.length > 60 ? `${event.preview.slice(0, 60)}…` : event.preview
+    return `message "${preview}"`
+  }
+  return null
+}
+
+function formatElapsed(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const totalSec = Math.floor(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const min = Math.floor(totalSec / 60)
+  const sec = totalSec % 60
+  return `${min}m${sec}s`
+}
+
+export function attachProgressCapture(
+  registry: LiveSubagentRegistry,
+  taskId: string,
+  session: Pick<AgentSession, 'subscribe'>,
+): () => void {
+  const unsubscribe = session.subscribe((event: unknown) => {
+    const coarsened = coarsen(event as AgentSessionEvent, Date.now())
+    if (coarsened !== null) {
+      registry.recordEvent(taskId, coarsened)
+    }
+  })
+  return () => {
+    if (typeof unsubscribe === 'function') unsubscribe()
+  }
+}

package/src/agent/plugin-tools.ts

@@ -16,6 +16,7 @@ import { z } from 'zod'
 
 import {
   ACKNOWLEDGE_GUARDS,
+  checkManagedConfigGuard,
   checkNonWorkspaceWriteGuard,
   checkSkillAuthoringGuard,
 } from '@/bundled-plugins/guard/policy'
@@ -31,15 +32,8 @@ import type {
 } from '@/plugin'
 
 import type { SessionOrigin } from './session-origin'
-
-type AnyAgentTool =
-  | typeof piReadTool
-  | typeof piBashTool
-  | typeof piEditTool
-  | typeof piWriteTool
-  | typeof piGrepTool
-  | typeof piFindTool
-  | typeof piLsTool
+import { webfetchTool } from './tools/webfetch'
+import { websearchTool } from './tools/websearch'
 
 const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   Type.Object(
@@ -50,22 +44,64 @@ const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   ),
 )
 
-const BUILTIN_TOOL_MAP: Record<string, AnyAgentTool> = {
+// `BuiltinToolRef.__builtinTool` strings are dual-routed when a plugin
+// subagent declares them: pi-coding-agent's own coding tools flow through
+// `createAgentSession({ tools: AgentTool[] })` (which pi treats as a strict
+// base-tool override — exactly the declared subset becomes active), and
+// typeclaw's own web tools flow through `customTools: ToolDefinition[]` (the
+// only path pi accepts for non-pi tool definitions). Routing typeclaw tools
+// through `tools:` silently drops them (pi's `tools` validator rejects shapes
+// it doesn't recognize); routing pi tools through `customTools:` would work
+// but ALSO auto-injects pi's default 4 base tools (read/bash/edit/write),
+// widening every plugin subagent's allowlist beyond what it declared. The
+// dual route is the only shape that gives "subagent gets exactly what it
+// asked for, nothing more." See `src/agent/index.ts` `createSessionWithDispose`
+// for the consumer that splits the resolved arrays into the two pi fields.
+type PiAgentToolName = 'read' | 'bash' | 'edit' | 'write' | 'grep' | 'find' | 'ls'
+type TypeclawToolName = 'websearch' | 'webfetch'
+
+const PI_AGENT_TOOL_MAP: Record<PiAgentToolName, AgentTool<any, any>> = {
+  read: piReadTool,
   bash: piBashTool,
   edit: piEditTool,
-  find: piFindTool,
+  write: piWriteTool,
   grep: piGrepTool,
+  find: piFindTool,
   ls: piLsTool,
-  read: piReadTool,
-  write: piWriteTool,
 }
 
-export function resolveBuiltinToolRefs(refs: BuiltinToolRef[]): AnyAgentTool[] {
-  return refs.map((ref) => {
-    const tool = BUILTIN_TOOL_MAP[ref.__builtinTool]
-    if (!tool) throw new Error(`unknown built-in tool ref: ${ref.__builtinTool}`)
-    return tool
-  })
+const TYPECLAW_TOOL_DEFINITION_MAP: Record<TypeclawToolName, ToolDefinition<any, any, any>> = {
+  websearch: websearchTool,
+  webfetch: webfetchTool,
+}
+
+function isPiAgentToolName(name: string): name is PiAgentToolName {
+  return name in PI_AGENT_TOOL_MAP
+}
+
+function isTypeclawToolName(name: string): name is TypeclawToolName {
+  return name in TYPECLAW_TOOL_DEFINITION_MAP
+}
+
+export type ResolvedBuiltinTools = {
+  agentTools: AgentTool<any, any>[]
+  toolDefinitions: ToolDefinition<any, any, any>[]
+}
+
+export function resolveBuiltinToolRefs(refs: BuiltinToolRef[]): ResolvedBuiltinTools {
+  const agentTools: AgentTool<any, any>[] = []
+  const toolDefinitions: ToolDefinition<any, any, any>[] = []
+  for (const ref of refs) {
+    const name = ref.__builtinTool
+    if (isPiAgentToolName(name)) {
+      agentTools.push(PI_AGENT_TOOL_MAP[name])
+    } else if (isTypeclawToolName(name)) {
+      toolDefinitions.push(TYPECLAW_TOOL_DEFINITION_MAP[name])
+    } else {
+      throw new Error(`unknown built-in tool ref: ${name}`)
+    }
+  }
+  return { agentTools, toolDefinitions }
 }
 
 export type WrapToolOptions = {
@@ -274,7 +310,11 @@ function errorResult(message: string) {
 }
 
 async function runFinalWriteGuards(options: { tool: string; args: Record<string, unknown>; agentDir: string }) {
-  return (await checkSkillAuthoringGuard(options)) ?? checkNonWorkspaceWriteGuard(options)
+  return (
+    (await checkManagedConfigGuard(options)) ??
+    (await checkSkillAuthoringGuard(options)) ??
+    checkNonWorkspaceWriteGuard(options)
+  )
 }
 
 function withGuardAcknowledgements<TParams extends TSchema>(toolName: string, parameters: TParams): TParams {