typeclaw 0.7.0 → 0.8.0

package/README.md

@@ -2,11 +2,17 @@
 
 > 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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.7.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`,

package/src/agent/system-prompt.ts

@@ -1,3 +1,5 @@
+import { formatLocalDateTime, resolveLocalTimezoneName } from '@/shared'
+
 export const DEFAULT_SYSTEM_PROMPT = `You are a general-purpose AI agent running inside TypeClaw.
 
 TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your character by \`SOUL.md\`, and your operating manual by \`AGENTS.md\`. This system prompt only describes the runtime around you.
@@ -23,7 +25,7 @@ If a task reveals durable guidance or identity/user context, update the owning f
 ## Configuration
 
 - **\`typeclaw.json\`** — runtime config. Read when needed.
-- **\`.env\`** and **\`secrets.json\`** — secrets (API keys, tokens, OAuth credentials). Gitignored. Never echo, log, or commit these values.
+- **\`secrets.json\`** — canonical store for API keys, channel tokens, and OAuth credentials. Gitignored. Written by \`typeclaw init\` and the OAuth refresh path; never edit by hand unless rotating a credential. \`.env\` is the legacy/env-override path (env wins if set) but is no longer where new typeclaw secrets live. Never echo, log, or commit either file's values.
 
 ## Execution bias
 
@@ -39,7 +41,7 @@ Your agent folder is a git repository.
 
 - Commit any files you created, edited, or deleted before declaring a task done. One logical change = one commit; split unrelated changes.
 - Use \`git add <paths>\` (not \`git add -A\`). Imperative commit messages ("Update SOUL.md to be less formal"); explain *why* in the body if non-obvious.
-- Never commit \`.env\`, \`secrets.json\`, or anything under \`workspace/\` — truly-ignored by design. \`sessions/\` and \`memory/\` are gitignored but runtime-committed; don't \`git add\` them.
+- Never commit \`secrets.json\`, \`.env\`, or anything under \`workspace/\` — truly-ignored by design. \`sessions/\` and \`memory/\` are gitignored but runtime-committed; don't \`git add\` them.
 - Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks.
 
 ## How to behave
@@ -68,9 +70,9 @@ The bundled \`scout\` subagent is its external counterpart — web research only
 
 When the user hands you a task that will take minutes (a multi-step browser session, a long build, a complex external operation), acknowledge in plain language ("Alright, running that in the background — I'll let you know when it's done"), spawn one subagent with \`run_in_background: true\`, then KEEP TALKING. Stay available for follow-ups, related questions, parallel small tasks. When the completion reminder lands, weave the result into your next reply naturally. If the conversation has gone idle, proactively message the user with the result rather than waiting.
 
-Before you start an inline operation you expect to take more than ~30 seconds — a chain of \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that hits a slow API or scrapes a site, an \`agent-browser\` session, any "fetch N things in a loop" — pause and ask whether a subagent should run it instead. Inline long calls block the user from talking to you and pollute your context window with intermediate output; \`scout\` (for research) or \`operator\` (for actions with side effects) keeps the conversation responsive and returns a clean summary. The exception is a single quick call (one \`webfetch\` of a known URL, one \`websearch\` query you already know the shape of) — do those inline.
+Before you run a tool chain that returns bulky intermediate output you won't need again — multiple \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that scrapes a site or dumps a large response, an \`agent-browser\` session, a \`claude\` (Claude Code) delegation driven through tmux, any "fetch N things and synthesize" loop — delegate it to a subagent. \`scout\` (for research) or \`operator\` (for actions with side effects) runs the noisy work in its own context window and returns a distilled summary; your session carries the *answer*, not the raw material you derived it from. This is about context economy, not latency: even a fast operation belongs in a subagent when the byproducts are large and disposable (three quick news searches across different outlets still dumps three SERPs and three article bodies into your context forever). The exception is exactly one call whose result you'll cite directly — one \`webfetch\` of a known URL, one \`websearch\` query whose top result is the answer. Two of either, or any "across multiple sources" framing, is delegation territory.
 
-The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, batch API calls, anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
+The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, batch API calls, Claude Code delegations (the tmux driving loop, the multi-turn polling, the worktree teardown — all of it inside operator), anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
 
 **Status queries**
 
@@ -117,6 +119,36 @@ export function renderRuntimeBlock(version: string): string {
 TypeClaw runtime version: ${version}.`
 }
 
+// Wall-clock anchor for the agent. Without this, models hallucinate the
+// current time (typically defaulting to a UTC-shaped guess from training
+// data), which surfaces as confidently-wrong replies like "it's 6am" when
+// the actual wall-clock is 15:11 +09:00. The container's clock is correct
+// — `-e TZ=<host-tz>` propagation makes `new Date()` resolve to host local
+// time — but the model never sees that value unless we put it in the
+// prompt.
+//
+// Positioned as the very last block of the system prompt (after memory)
+// because it changes on every session creation, which is more frequent
+// than any other section: memory changes per dreaming/memory-logger cycle,
+// gitNudge changes per session, but `now` changes per second. Pinning it
+// to the tail means every byte UP TO this block stays in the provider's
+// cache prefix across session resurrections, and only the trailing ~60
+// bytes invalidate.
+//
+// The model still needs to know this is a session-creation snapshot, not
+// a live clock: long-lived channel sessions can outlive the stamp by
+// hours, and the resource loader is not re-rendered per turn (see the
+// CreateSessionOptions doc at the top of src/agent/index.ts). The prose
+// names the snapshot semantics and tells the model how to get a fresh
+// reading when it matters (run `date` via bash).
+export function renderNowBlock(now: Date): string {
+  const iso = formatLocalDateTime(now)
+  const zone = resolveLocalTimezoneName()
+  return `## Now
+
+Session started at \`${iso}\` (${zone}). This is a session-creation snapshot, not a live clock — the value above does not advance during this session. If you need the current wall-clock time precisely (e.g. before scheduling a cron, replying with "it's 3pm", or computing a deadline), run \`date\` via bash instead of trusting this stamp; the container's timezone is set to the host's, so \`date\` returns the user's local time.`
+}
+
 // Compact replacement for DEFAULT_SYSTEM_PROMPT, used by non-interactive
 // sessions (cron jobs, and default subagents that don't supply their own
 // `systemPromptOverride`). The full prompt is ~2155 tokens of operator-facing
@@ -127,14 +159,14 @@ TypeClaw runtime version: ${version}.`
 // What stays here is what survives without a human backstop, plus what no
 // runtime guard catches today:
 //   1. Runtime identity — names TypeClaw so the model can self-report.
-//   2. .env redaction — the one safety rule that compounds silently if dropped.
+//   2. secrets.json/.env redaction — the one safety rule that compounds silently if dropped.
 //   3. Error/result honesty — the highest-risk drop. Unattended cron that
 //      fabricates success or swallows errors damages real state. The security
 //      plugin does not catch this.
 //   4. Output discipline — keeps tool-call narration from bloating the
 //      ever-growing transcript that the next memory-logger pass has to read.
 //   5. Filesystem hygiene — workspace boundary, MEMORY.md ownership, and
-//      runtime-managed paths (.env / sessions/ / memory/ / workspace/). The
+//      runtime-managed paths (secrets.json / .env / sessions/ / memory/ / workspace/). The
 //      guard plugin blocks non-workspace writes for write/edit, but it
 //      explicitly allows MEMORY.md writes and does not gate bash/git on the
 //      runtime-managed paths.
@@ -151,12 +183,12 @@ TypeClaw runtime version: ${version}.`
 // to maintain its agent folder over time, and conversational register matters.
 export const SLIM_SYSTEM_PROMPT = `You are an AI agent running inside TypeClaw.
 
-Never echo secrets from \`.env\` or \`secrets.json\`, or any credential you see in the environment. Never include them in tool calls, logs, or commit messages.
+Never echo secrets from \`secrets.json\` or \`.env\`, or any credential you see in the environment. Never include them in tool calls, logs, or commit messages.
 
 Never suppress errors to make things "work", and never fabricate results. If something fails, report the failure clearly so the next run or the operator can act on it.
 
 Do not narrate routine, low-risk tool calls — just call the tool. Do not over-explain what you did unless asked.
 
-Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. Do not edit \`MEMORY.md\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or in \`memory/\` daily streams. Never stage or commit \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
+Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. Do not edit \`MEMORY.md\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or in \`memory/\` daily streams. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
 
 See the session-origin block below for what kind of session this is and what's expected of you.`