typeclaw 0.7.0 → 0.9.0

package/README.md

@@ -2,18 +2,24 @@
 
 > A TypeScript-native, Bun-powered, Docker-friendly general-purpose agent runtime.
 
-Full docs: **[typeclaw.dev](https://typeclaw.dev)**.
-
 ## Why?
 
-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.
+There are great agents out there. None of them were quite the shape I wanted:
+
+- **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
+
+None of that matters to most people. It matters to me. If you're like me, TypeClaw is the right choice.
 
 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
-- **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
+- **Self-improving** — the agent observes its own work, distills it into sharded long-term memory and reusable skills, and gets sharper over time without you writing prompts for it
 
 If you're like me, TypeClaw is the right choice. If not, that's fine too.
 
@@ -25,18 +31,18 @@ If you're like me, TypeClaw is the right choice. If not, that's fine too.
 - ⏰ **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
 - 🔎 **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
+- 🛡 **Security guards** — bundled `tool.before` policies catch secret exfil, SSRF, prompt injection, tainted git remotes, and silent privilege escalation (role/cron promotion) before they fire
+- 📊 **Usage, inspect, doctor** — `typeclaw usage` reports token/$ spend per session, model, or day; `typeclaw inspect` replays a session transcript and tails live activity; `typeclaw doctor` diagnoses host, agent folder, and plugin state
 
 ## Where it goes further
 
-- 🌱 **Self-improving** — bundled `memory` plugin distills sessions into long-term `MEMORY.md` without you writing prompts for it
+- 🌱 **Self-improving** — bundled `memory` plugin logs sessions to daily streams, then a `dreaming` subagent distills them into sharded long-term memory (`memory/topics/`) on its own schedule; no prompts to write
 - 🧠 **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
+- 🧱 **Managed-file guards** — `typeclaw.json`, `cron.json`, memory shards, and bundled skills are protected from accidental rewrites; invalid config writes and silent role/cron privilege grants 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
@@ -72,7 +78,7 @@ See `typeclaw --help` for the full command surface, or [typeclaw.dev](https://ty
 git clone https://github.com/typeclaw/typeclaw
 cd typeclaw
 bun install
-bun test
+bun run test
 ```
 
 Pre-commit checks (all must pass — no exceptions):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -36,7 +36,7 @@
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
     "check": "bun run typecheck && bun run lint && bun run format:check",
-    "test": "bun test",
+    "test": "bun test --parallel",
     "generate:schema": "bun run scripts/generate-schema.ts",
     "debug:prompt": "bun run scripts/dump-system-prompt.ts",
     "postinstall": "bun run scripts/generate-schema.ts"
@@ -46,7 +46,7 @@
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
     "@mozilla/readability": "^0.6.0",
-    "agent-messenger": "2.15.0",
+    "agent-messenger": "2.17.0",
     "cheerio": "^1.2.0",
     "citty": "^0.2.2",
     "cron-parser": "^5.5.0",
@@ -56,9 +56,11 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@sinonjs/fake-timers": "^15.4.0",
     "@types/bun": "latest",
     "@types/jsdom": "^28.0.1",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/sinonjs__fake-timers": "^15.0.1",
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",
     "@typescript/native-preview": "^7.0.0-dev.20260416.1",

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/scripts/require-parallel.ts

@@ -0,0 +1,41 @@
+// Preloaded by bunfig.toml `[test] preload`. Denies `bun test` without
+// --parallel. Serial runs are ~3.4x slower (44s → 13s, see commit
+// 1c66d5e), and Bun has no bunfig knob for the flag yet (verified
+// against bunfig.zig in oven-sh/bun main, May 2026). Without this
+// guard, IDE test runners and ad-hoc shells silently fall back to the
+// slow path.
+//
+// Detection: Bun strips CLI flags from `Bun.argv` before invoking the
+// preload, so we can't scrape the flag directly. Instead we look for
+// BUN_TEST_WORKER_ID, which Bun sets in the preload env exactly when
+// `--parallel` is active (the variable carries the worker index for
+// the IPC handshake between coordinator and workers). Empirically
+// verified against bun 1.3.14: present under --parallel, absent under
+// serial. If a future Bun version renames this var, the guard fails
+// closed (treats every run as serial → always denies), which is the
+// safe direction.
+//
+// Bypass with TYPECLAW_ALLOW_SERIAL_TESTS=1 when debugging a flaky
+// test where worker contention obscures the failure.
+
+const isParallelWorker = typeof process.env.BUN_TEST_WORKER_ID === 'string'
+
+if (isParallelWorker) {
+  // proceed
+} else if (process.env.TYPECLAW_ALLOW_SERIAL_TESTS === '1') {
+  console.warn('[require-parallel] Running serially — TYPECLAW_ALLOW_SERIAL_TESTS=1 set.')
+} else {
+  console.error('')
+  console.error('  ✗ `bun test` without --parallel is denied in this repo.')
+  console.error('')
+  console.error('    Serial runs take ~46s; --parallel cuts that to ~14s on a multi-core')
+  console.error('    machine and is what CI uses. Bun does not (yet) accept `[test] parallel`')
+  console.error('    in bunfig.toml, so we enforce it via this preload.')
+  console.error('')
+  console.error('    Use one of:')
+  console.error('      bun run test                              # preferred')
+  console.error('      bun test --parallel                       # direct')
+  console.error('      TYPECLAW_ALLOW_SERIAL_TESTS=1 bun test    # intentional serial run')
+  console.error('')
+  process.exit(1)
+}

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
 }
 
@@ -713,7 +765,40 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   const agentDir = options.agentDir ?? process.cwd()
   const mode: SystemPromptMode = options.mode ?? deriveSystemPromptMode(options.origin)
   const basePrompt = mode === 'slim' ? SLIM_SYSTEM_PROMPT : DEFAULT_SYSTEM_PROMPT
-  let self = await loadSelf(agentDir)
+
+  // Kick off the three independent I/O paths concurrently. Sequential awaits
+  // here used to be the dominant cold-start cost amplifier: loadSelf is 2
+  // file reads, renderGitNudge spawns a subprocess, loadMemory reads N topic
+  // shards. None of them depend on each other, so we run them in parallel.
+  // The plugin hook (runSessionPrompt) only needs `self`, so it can overlap
+  // with the gitNudge subprocess and the shard reads while `self` is in
+  // flight too.
+  //
+  // Plugin-hook contract: `runSessionPrompt` runs AFTER gitNudge/memory I/O
+  // has been kicked off. A hook that mutates `memory/topics/` or git-tracked
+  // files during its body races those in-flight reads -- mutations may or
+  // may not be reflected in the resulting prompt. The bundled hooks only
+  // mutate the prompt string itself; third-party plugins that need to mutate
+  // disk before the suffix sections see it must do so before/outside the
+  // session-prompt hook.
+  //
+  // We wrap gitNudge and memory promises in `settled` shells so any
+  // rejection from them cannot surface as an unhandled rejection during the
+  // window where we're awaiting selfPromise + runSessionPrompt. Production
+  // callers don't reject (renderGitNudge swallows internally, loadMemory
+  // catches ENOENT) but a non-ENOENT fs error (EACCES/EIO) on the agent
+  // folder would otherwise terminate the process before we reach the
+  // gather point.
+  const selfPromise = loadSelf(agentDir)
+  const gitNudgeSettled = mode === 'slim' ? Promise.resolve(ok('')) : settle(renderGitNudge(agentDir))
+  const memorySettled = settle(
+    loadMemory(agentDir, {
+      ...(options.origin !== undefined ? { origin: options.origin } : {}),
+      ...(options.plugins?.sessionId !== undefined ? { currentSessionId: options.plugins.sessionId } : {}),
+    }),
+  )
+
+  let self = await selfPromise
 
   if (options.plugins) {
     // The plugin hook receives the partially-assembled prompt (base + identity)
@@ -736,11 +821,9 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   // commit guidance the nudge points back to is itself excluded from the slim
   // base prompt. Memory is still included so cron jobs that depend on MEMORY.md
   // context (e.g. "send today's standup summary") keep working.
-  const gitNudge = mode === 'slim' ? '' : await renderGitNudge(agentDir)
-  const memorySection = await loadMemory(agentDir, {
-    ...(options.origin !== undefined ? { origin: options.origin } : {}),
-    ...(options.plugins?.sessionId !== undefined ? { currentSessionId: options.plugins.sessionId } : {}),
-  })
+  const [gitNudgeResult, memoryResult] = await Promise.all([gitNudgeSettled, memorySettled])
+  const gitNudge = unwrapSettled(gitNudgeResult)
+  const memorySection = unwrapSettled(memoryResult)
 
   const systemPrompt = composeSystemPrompt({
     mode,
@@ -750,6 +833,7 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
     ...(roleContext !== undefined ? { roleContext } : {}),
     gitNudge,
     memorySection,
+    now: options.now ?? new Date(),
   })
 
   const additionalSkillPaths = [getBundledSkillsDir()]
@@ -819,3 +903,21 @@ function resolveRoleContext(
 export function getBundledSkillsDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
 }
+
+type Settled<T> = { ok: true; value: T } | { ok: false; error: unknown }
+
+function ok<T>(value: T): Settled<T> {
+  return { ok: true, value }
+}
+
+function settle<T>(promise: Promise<T>): Promise<Settled<T>> {
+  return promise.then(
+    (value): Settled<T> => ({ ok: true, value }),
+    (error: unknown): Settled<T> => ({ ok: false, error }),
+  )
+}
+
+function unwrapSettled<T>(result: Settled<T>): T {
+  if (result.ok) return result.value
+  throw result.error
+}

package/src/agent/live-sessions.ts

@@ -0,0 +1,34 @@
+import type { AgentSession } from './index'
+
+export type LiveAgentSession = {
+  sessionId: string
+  session: Pick<AgentSession, 'subscribe'>
+}
+
+export class LiveSessionRegistry {
+  private readonly entries = new Map<string, LiveAgentSession>()
+
+  register(live: LiveAgentSession): void {
+    this.entries.set(live.sessionId, live)
+  }
+
+  unregister(sessionId: string): void {
+    this.entries.delete(sessionId)
+  }
+
+  get(sessionId: string): LiveAgentSession | undefined {
+    return this.entries.get(sessionId)
+  }
+
+  has(sessionId: string): boolean {
+    return this.entries.has(sessionId)
+  }
+
+  size(): number {
+    return this.entries.size
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}

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(' '),
+  }
+}