typeclaw 0.6.0 → 0.8.0

package/README.md

@@ -19,34 +19,37 @@ 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
+- 🔎 **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
 
-### 🌱 Self-improving, in detail
+## Where it goes further
 
-The bundled `memory` plugin turns lived experience into reusable knowledge. No manual prompt engineering. No curated example library.
-
-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 +70,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 +81,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,11 +89,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/).
 
-## Website
+## Acknowledgments
 
-The landing page and documentation site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/). It's a Next.js + Fumadocs app — see [`docs/README.md`](./docs/README.md) for layout and the contributor workflow.
+- **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.6.0",
+  "version": "0.8.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/scripts/dump-system-prompt.ts

@@ -4,12 +4,19 @@ import { parseArgs } from 'node:util'
 
 import { composeSystemPrompt, deriveSystemPromptMode, type SystemPromptMode } from '@/agent'
 import type { SessionOrigin, SessionRoleContext } from '@/agent/session-origin'
+import { renderNowBlock } from '@/agent/system-prompt'
 
 type OriginKind = 'tui' | 'cron' | 'channel' | 'subagent'
 const ALL_KINDS: readonly OriginKind[] = ['tui', 'cron', 'channel', 'subagent'] as const
 
 const PLACEHOLDER_RUNTIME_VERSION = '1.2.3-debug'
 
+// Fixed wall-clock for the `## Now` block. The dumper needs a deterministic
+// timestamp so successive runs produce byte-identical output (and so the
+// snapshot tests in dump-system-prompt.test.ts don't drift). Production
+// callers always pass the live `new Date()` — see `composeSystemPrompt`.
+const PLACEHOLDER_NOW = new Date('2026-05-22T15:11:00+09:00')
+
 const PLACEHOLDER_SELF = [
   '# Identity',
   '',
@@ -236,12 +243,14 @@ function dumpSubagentOverridePrompt(): DumpResult {
   const fixture = buildFixture('subagent')
   const runtimeBlock = `## Runtime\n\nTypeClaw runtime version: ${PLACEHOLDER_RUNTIME_VERSION}.`
   const originBlock = `## Session origin\n\nYou are a \`${(fixture.origin as { subagent: string }).subagent}\` subagent spawned by parent session\n\`${(fixture.origin as { parentSessionId: string }).parentSessionId}\`. Stay narrowly within the task you were given.\nReturn cleanly when done; do not sprawl into unrelated work.\n\n## Your role in this session\n\nRole: \`${fixture.roleContext.role}\`. Permissions: ${fixture.roleContext.permissions.map((p) => `\`${p}\``).join(', ')}.\n\nThis is the role the runtime resolved at session creation. Tool calls\nand channel admission are gated by these permissions; a \`blocked:\` or\n"denied by permissions" message means the current actor lacks the\npermission the guard was looking for. See the \`typeclaw-permissions\`\nskill for what each role can do and how to grant access.`
+  const nowBlock = renderNowBlock(PLACEHOLDER_NOW)
 
-  const prompt = `${PLACEHOLDER_SUBAGENT_OVERRIDE}\n\n${runtimeBlock}\n\n${originBlock}`
+  const prompt = `${PLACEHOLDER_SUBAGENT_OVERRIDE}\n\n${runtimeBlock}\n\n${originBlock}\n\n${nowBlock}`
   const sections: SectionBreakdown[] = [
     mkSection('Subagent override prompt', PLACEHOLDER_SUBAGENT_OVERRIDE),
     mkSection('Runtime block', runtimeBlock),
     mkSection('Session origin + role', originBlock),
+    mkSection('Now (wall clock)', nowBlock),
   ]
   return {
     prompt,
@@ -264,6 +273,7 @@ function dumpDefaultLoaderPrompt(kind: Exclude<OriginKind, 'subagent'>, options:
     roleContext: fixture.roleContext,
     gitNudge: wantGitNudge ? PLACEHOLDER_GIT_NUDGE : '',
     memorySection: fixture.memory,
+    now: PLACEHOLDER_NOW,
   } as const
 
   const prompt = composeSystemPrompt(parts)
@@ -289,6 +299,7 @@ function dumpDefaultLoaderPrompt(kind: Exclude<OriginKind, 'subagent'>, options:
     sections.push(mkSection('Git nudge', parts.gitNudge))
   }
   sections.push(mkSection('Memory (MEMORY.md + streams)', parts.memorySection))
+  sections.push(mkSection('Now (wall clock)', renderNowBlock(PLACEHOLDER_NOW)))
 
   return {
     prompt,

package/src/agent/auth.ts

@@ -124,8 +124,8 @@ function missingCredentialMessage(providerId: KnownProviderId): string {
   }
   if (apiKeyOnly && provider.apiKeyEnv) {
     return modelName
-      ? `Set ${provider.apiKeyEnv} in .env (or secrets.json#providers.${provider.id}.key.value) to use ${modelName} via ${provider.name}.`
-      : `Set ${provider.apiKeyEnv} in .env (or secrets.json#providers.${provider.id}.key.value) to use ${provider.name} (referenced by a non-default profile).`
+      ? `Run \`typeclaw init\` to add an API key for ${modelName} via ${provider.name} (stored in secrets.json#providers.${provider.id}.key.value; ${provider.apiKeyEnv} in .env also works for override).`
+      : `Run \`typeclaw init\` to add an API key for ${provider.name} (referenced by a non-default profile; stored in secrets.json#providers.${provider.id}.key.value; ${provider.apiKeyEnv} in .env also works for override).`
   }
-  return `No credentials for ${provider.name}. Either set ${provider.apiKeyEnv ?? '<api-key-env>'} in .env or run \`typeclaw init\` and pick "OAuth".`
+  return `No credentials for ${provider.name}. Run \`typeclaw init\` to add an API key (stored in secrets.json) or pick "OAuth".`
 }

package/src/agent/index.ts

@@ -27,13 +27,19 @@ 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 {
+  buildBuiltinPiToolOverrides,
+  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 { DEFAULT_SYSTEM_PROMPT, renderNowBlock, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
 import {
   createBudgetState,
   type ToolResultBudget,
@@ -313,7 +319,22 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
               stream: options.stream,
             }),
           ]
-  const customToolsPreBudget = [...wrapSystemTools(customSystemTools, options.plugins, getOrigin), ...pluginCustomTools]
+  // Hook coverage for pi's builtin coding tools (read/bash/edit/write/grep/
+  // find/ls) — pi 0.67.3 ignores `tools:` for implementation, so the only
+  // way to interpose typeclaw guards is to ship same-named ToolDefinition
+  // entries through `customTools`. Skipped when there are no tool hooks,
+  // since wrapping reduces to a passthrough in that case.
+  const builtinPiToolOverrides =
+    options.plugins && hasToolHooks(options.plugins)
+      ? buildBuiltinPiToolOverrides({
+          agentDir: options.plugins.agentDir,
+          sessionId: options.plugins.sessionId,
+          hooks: options.plugins.hooks,
+          getOrigin,
+        })
+      : []
+  const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, options.plugins, getOrigin)
+  const customToolsPreBudget = [...wrappedCustomSystemTools, ...pluginCustomTools, ...builtinPiToolOverrides]
   const customTools =
     sessionBudget && sessionBudgetState
       ? customToolsPreBudget.map((t) => wrapToolDefinitionWithBudget(t, sessionBudget, sessionBudgetState))
@@ -331,6 +352,21 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     customTools,
   })
 
+  // Re-narrow the active tool set after `createAgentSession`. pi 0.67.3's
+  // `_refreshToolRegistry` runs with `includeAllExtensionTools: true` and
+  // pushes every customTool name into the active set, which would widen
+  // a subagent's declared `[edit]` to all 7 builtin overrides plus every
+  // typeclaw custom tool. The intended active set is the names the caller
+  // would have gotten WITHOUT the builtin overrides: pi's `initialActiveToolNames`
+  // (derived from `tools:`) union the names from typeclaw/plugin customTools.
+  // `builtinPiToolOverrides` are implementation overrides, never additions.
+  if (builtinPiToolOverrides.length > 0) {
+    const baseActiveNames = tools !== undefined ? tools.map((t) => t.name) : ['read', 'bash', 'edit', 'write']
+    const customToolActiveNames = [...wrappedCustomSystemTools, ...pluginCustomTools].map((t) => t.name)
+    const intendedActive = [...new Set([...baseActiveNames, ...customToolActiveNames])]
+    session.setActiveToolsByName(intendedActive)
+  }
+
   const unsubRestart = subscribeRestartNotice(options.stream, sessionManager)
 
   const dispose = async () => {
@@ -591,10 +627,12 @@ export async function createOverrideResourceLoader(
   origin?: SessionOrigin,
   permissions?: PermissionService,
   runtimeVersion?: string,
+  now: Date = new Date(),
 ): Promise<DefaultResourceLoader> {
   const withRuntime =
     runtimeVersion !== undefined ? `${systemPrompt}\n\n${renderRuntimeBlock(runtimeVersion)}` : systemPrompt
-  const finalPrompt = withOrigin(withRuntime, origin, permissions)
+  const withOriginRendered = withOrigin(withRuntime, origin, permissions)
+  const finalPrompt = `${withOriginRendered}\n\n${renderNowBlock(now)}`
   const loader = new DefaultResourceLoader({
     systemPromptOverride: () => finalPrompt,
     appendSystemPromptOverride: () => [],
@@ -615,6 +653,11 @@ export type CreateResourceLoaderOptions = {
   // 'full' to force the heavy prompt even on an unattended origin (rarely
   // useful; mostly an escape hatch for ad-hoc debugging).
   mode?: SystemPromptMode
+  // Wall-clock anchor stamped into the trailing `## Now` block of the
+  // rendered system prompt. Production callers omit this so each session
+  // gets the current time at creation; tests pass a fixed Date to keep
+  // assertions deterministic. See `renderNowBlock` in system-prompt.ts.
+  now?: Date
 }
 
 // Origins where the operator-facing DEFAULT_SYSTEM_PROMPT, git-nudge, and the
@@ -672,6 +715,7 @@ export type SystemPromptComposition = {
   roleContext?: SessionRoleContext
   gitNudge: string
   memorySection: string
+  now?: Date
 }
 
 // Section-order contract for the system prompt. Kept as a pure string→string
@@ -687,10 +731,15 @@ export type SystemPromptComposition = {
 // 2. gitNudge — rare changes; agent folders force-commit sessions/ and
 //    memory/ after every turn, so the dirty-files list is empty most of
 //    the time.
-// 3. memorySection — most volatile: MEMORY.md grows on every dream cycle
-//    and memory/yyyy-MM-dd.md grows after every channel turn that triggers
-//    memory-logger. Pinning it to the end keeps everything above it
-//    cacheable across session resurrections.
+// 3. memorySection — volatile: MEMORY.md grows on every dream cycle and
+//    memory/yyyy-MM-dd.md grows after every channel turn that triggers
+//    memory-logger.
+// 4. now block — most volatile: changes per second. Pinned to the very
+//    end so every byte UP TO this block stays in the provider's cache
+//    prefix; only the trailing ~60 bytes invalidate on each new session.
+//    `now` is optional — when omitted (debug dumps without a fixed clock,
+//    legacy callers) the block is skipped entirely. See `renderNowBlock`
+//    in system-prompt.ts for why this block exists at all.
 export function composeSystemPrompt(parts: SystemPromptComposition): string {
   const base = parts.mode === 'slim' ? SLIM_SYSTEM_PROMPT : DEFAULT_SYSTEM_PROMPT
   let prompt = `${base}\n\n${parts.self}`
@@ -706,6 +755,9 @@ export function composeSystemPrompt(parts: SystemPromptComposition): string {
   if (parts.memorySection !== '') {
     prompt = `${prompt}\n\n${parts.memorySection}`
   }
+  if (parts.now !== undefined) {
+    prompt = `${prompt}\n\n${renderNowBlock(parts.now)}`
+  }
   return prompt
 }
 
@@ -750,6 +802,7 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
     ...(roleContext !== undefined ? { roleContext } : {}),
     gitNudge,
     memorySection,
+    now: options.now ?? new Date(),
   })
 
   const additionalSkillPaths = [getBundledSkillsDir()]

package/src/agent/multimodal/read-redirect.ts

@@ -0,0 +1,43 @@
+import path from 'node:path'
+
+import { ACKNOWLEDGE_GUARDS, type GuardBlock, isGuardAcknowledged } from '@/bundled-plugins/guard/policy'
+
+export const GUARD_IMAGE_READ_REDIRECT = 'imageReadRedirect'
+
+// Mirrors the IMAGE_MIME_TYPES set in @mariozechner/pi-coding-agent
+// (dist/utils/mime.ts). Keeping the trigger surface aligned with the upstream
+// read tool's image-attachment behavior means we redirect on exactly the
+// extensions that would otherwise inject `{ type: 'image' }` content parts
+// into the main agent's history.
+//
+// Extension-only matching is preferred over the upstream MIME sniffer's
+// 4100-byte file open because this check runs on every `read` call;
+// extensionless image files still leak as before (no regression), and the
+// agent can force-read via `acknowledgeGuards.imageReadRedirect: true` when
+// it genuinely needs the bytes (e.g. writing image-processing code).
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp'])
+
+export function checkImageReadRedirect(options: {
+  tool: string
+  args: Record<string, unknown>
+}): GuardBlock | undefined {
+  const { tool, args } = options
+  if (tool !== 'read') return undefined
+  if (isGuardAcknowledged(args, GUARD_IMAGE_READ_REDIRECT)) return undefined
+
+  const rawPath = args.path
+  if (typeof rawPath !== 'string' || rawPath === '') return undefined
+
+  const ext = path.extname(rawPath).toLowerCase()
+  if (!IMAGE_EXTENSIONS.has(ext)) return undefined
+
+  return {
+    block: true,
+    reason: [
+      `Guard \`${GUARD_IMAGE_READ_REDIRECT}\` blocked read of an image file: ${rawPath}.`,
+      `Reading images via \`read\` injects the raw bytes into your message history as an image attachment, which can quickly fill your context window.`,
+      `Use \`look_at\` with \`path: ${JSON.stringify(rawPath)}\` instead — it routes the bytes through a vision-capable subagent and returns only text to you. Pass an optional \`prompt\` to ask a specific question (returns shorter text than the default describe-everything path).`,
+      `If you genuinely need the raw image bytes (e.g. writing image-processing code), retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_IMAGE_READ_REDIRECT}: true\` in the tool arguments.`,
+    ].join(' '),
+  }
+}

package/src/agent/plugin-tools.ts

@@ -31,6 +31,7 @@ import type {
   ToolResult,
 } from '@/plugin'
 
+import { checkImageReadRedirect } from './multimodal/read-redirect'
 import type { SessionOrigin } from './session-origin'
 import { webfetchTool } from './tools/webfetch'
 import { websearchTool } from './tools/websearch'
@@ -44,19 +45,20 @@ const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   ),
 )
 
-// `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.
+// pi-coding-agent 0.67.3 contract (load-bearing for hook coverage):
+//   - `createAgentSession({ tools: AgentTool[] })` is ONLY a name filter for
+//     `initialActiveToolNames`. It does NOT swap builtin implementations.
+//   - `customTools: ToolDefinition[]` entries override builtins by name in
+//     `_refreshToolRegistry` (the registry merge writes customTools last).
+//
+// Consequence: to put a `tool.before` hook around pi's builtin read/bash/edit/
+// write, TypeClaw must wrap them as `ToolDefinition`s and pass them via
+// `customTools` — not via `tools`. `wrapAgentToolAsCustomToolDefinition`
+// produces those wrapped definitions; `setupSession` in `src/agent/index.ts`
+// appends them whenever the session has any `tool.before` / `tool.after`
+// hooks registered. Subagent narrowing still comes from `tools:` (the
+// name-filter path); the wrapped customTools just replace the implementation
+// underneath so subagent and channel sessions share the same hook coverage.
 type PiAgentToolName = 'read' | 'bash' | 'edit' | 'write' | 'grep' | 'find' | 'ls'
 type TypeclawToolName = 'websearch' | 'webfetch'
 
@@ -231,6 +233,10 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
       if (guardResult !== undefined) {
         throw new Error(`blocked: ${guardResult.reason}`)
       }
+      const readGuardResult = runFinalReadGuards({ tool: tool.name, args: mutableArgs })
+      if (readGuardResult !== undefined) {
+        throw new Error(`blocked: ${readGuardResult.reason}`)
+      }
       stripGuardAcknowledgements(mutableArgs)
 
       const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate, ctx)
@@ -280,6 +286,10 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
       if (guardResult !== undefined) {
         throw new Error(`blocked: ${guardResult.reason}`)
       }
+      const readGuardResult = runFinalReadGuards({ tool: tool.name, args: mutableArgs })
+      if (readGuardResult !== undefined) {
+        throw new Error(`blocked: ${readGuardResult.reason}`)
+      }
       stripGuardAcknowledgements(mutableArgs)
 
       const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate)
@@ -301,6 +311,74 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
   }
 }
 
+// Wraps a pi-coding-agent AgentTool into a ToolDefinition so it can ride in
+// `customTools` and override pi's same-named builtin (see top-of-file contract
+// block). The hook + guard pipeline matches `wrapSystemAgentTool`; only the
+// input/output shape differs.
+export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDetails = unknown>(
+  tool: AgentTool<TParams, TDetails>,
+  opts: WrapSystemToolOptions,
+): ToolDefinition<TParams, TDetails> {
+  return piDefineTool({
+    name: tool.name,
+    label: tool.label,
+    description: tool.description,
+    parameters: withGuardAcknowledgements(tool.name, tool.parameters),
+    prepareArguments: tool.prepareArguments,
+    async execute(toolCallId, params, signal, onUpdate) {
+      const mutableArgs = params as Record<string, unknown>
+      const liveOrigin = opts.getOrigin?.()
+      const blockResult = await opts.hooks.runToolBefore({
+        tool: tool.name,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        args: mutableArgs,
+        ...(liveOrigin !== undefined ? { origin: liveOrigin } : {}),
+      })
+      if (blockResult !== undefined) {
+        throw new Error(`blocked: ${blockResult.reason}`)
+      }
+      const guardResult = await runFinalWriteGuards({
+        tool: tool.name,
+        args: mutableArgs,
+        agentDir: opts.agentDir,
+      })
+      if (guardResult !== undefined) {
+        throw new Error(`blocked: ${guardResult.reason}`)
+      }
+      const readGuardResult = runFinalReadGuards({ tool: tool.name, args: mutableArgs })
+      if (readGuardResult !== undefined) {
+        throw new Error(`blocked: ${readGuardResult.reason}`)
+      }
+      stripGuardAcknowledgements(mutableArgs)
+
+      const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate)
+      const hookResult: ToolResult = {
+        content: result.content as ContentPart[],
+        details: result.details,
+      }
+      await opts.hooks.runToolAfter({
+        tool: tool.name,
+        sessionId: opts.sessionId,
+        callId: toolCallId,
+        result: hookResult,
+      })
+      return {
+        content: hookResult.content as ContentPart[],
+        details: hookResult.details as TDetails,
+      }
+    },
+  })
+}
+
+export function defaultBuiltinPiAgentTools(): AgentTool<any, any>[] {
+  return [piReadTool, piBashTool, piEditTool, piWriteTool, piGrepTool, piFindTool, piLsTool]
+}
+
+export function buildBuiltinPiToolOverrides(opts: WrapSystemToolOptions): ToolDefinition<any, any>[] {
+  return defaultBuiltinPiAgentTools().map((tool) => wrapAgentToolAsCustomToolDefinition(tool, opts))
+}
+
 function errorResult(message: string) {
   return {
     content: [{ type: 'text' as const, text: message }],
@@ -317,6 +395,10 @@ async function runFinalWriteGuards(options: { tool: string; args: Record<string,
   )
 }
 
+function runFinalReadGuards(options: { tool: string; args: Record<string, unknown> }) {
+  return checkImageReadRedirect(options)
+}
+
 function withGuardAcknowledgements<TParams extends TSchema>(toolName: string, parameters: TParams): TParams {
   if (toolName !== 'write' && toolName !== 'edit') return parameters
 

package/src/agent/session-origin.ts

@@ -226,20 +226,13 @@ function renderChannelOrigin(
     'reply, your entire final visible response must be exactly `NO_REPLY`.',
     'Any other visible text without a channel tool call is blocked.',
     '',
-    '**Default to ONE reply per inbound.** Send a second `channel_reply` only',
-    'when the user genuinely benefits from it:',
+    '**One substantive reply per inbound.** If the answer needs more than one',
+    'tool call, send a one-line ack first ("On it."), keep working, then send',
+    'the answer — both in the same turn. The ack is not your reply; the answer',
+    'is. Once the answer lands, end your turn.',
     '',
-    '- the user asked multiple distinct things and each deserves its own',
-    '  scoped answer,',
-    '- your reply exceeds the platform message limit and must be chunked,',
-    '- you need to post an attachment AND commentary on it on Discord (on',
-    '  Slack, pass `text` and `attachments` in a single `channel_reply` call),',
-    '- you are emitting progress updates during a long-running task and the',
-    '  channel would otherwise sit silent.',
-    '',
-    'Do NOT send a second reply just to rephrase, restate, summarize, or',
-    '"confirm in plain language" something you already said. After the first',
-    'reply lands, end your turn — the user will respond if they want more.',
+    'Do not send a second reply just to rephrase, restate, or "confirm in',
+    'plain language" something you already said.',
     '',
     'To reply in this conversation, call `channel_reply({ text })`. Addressing',
     `is filled in from this session, including the thread${origin.thread !== null ? '' : ' (none here — this is a channel-root session)'}, so you don't`,