typeclaw 0.7.0 → 0.9.0

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'
@@ -39,24 +40,27 @@ const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   Type.Object(
     {
       nonWorkspaceWrite: Type.Optional(Type.Boolean()),
+      rolePromotion: Type.Optional(Type.Boolean()),
+      cronPromotion: Type.Optional(Type.Boolean()),
     },
     { additionalProperties: false },
   ),
 )
 
-// `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 +235,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 +288,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 +313,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 +397,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-meta.ts

@@ -9,12 +9,29 @@ export type SessionMetaPayload = {
 export type MinimalSessionOrigin =
   | { kind: 'tui' }
   | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }
-  | { kind: 'channel'; adapter: string; workspace: string; chat: string; thread: string | null }
+  | {
+      kind: 'channel'
+      adapter: string
+      workspace: string
+      // Optional human-readable names persisted alongside IDs so offline
+      // tooling (`typeclaw inspect`, future report commands) can render
+      // sessions as `Slack acme-corp/#general` instead of bare IDs without
+      // re-querying the adapter at runtime. Workspace/chat NAMES are not
+      // secrets — they are visible to any participant — and they are
+      // stable across reopens, so the tradeoff is one-time write cost for
+      // permanent offline readability. Author handles, participant lists,
+      // and membership counts remain dropped (those carry author identity
+      // and would land in `sessions/`'s auto-backup git history).
+      workspaceName?: string
+      chat: string
+      chatName?: string
+      thread: string | null
+    }
   | { kind: 'subagent'; subagent: string; parentSessionId: string }
 
 // Reduce a full SessionOrigin to the minimum projection persisted to disk.
 // Drops participant lists, membership counts, recursive provenance, and
-// platform-rendered names — none of which `typeclaw usage` reads, and all of
+// author identifiers — none of which `typeclaw usage` reads, and all of
 // which would otherwise land in git history when sessions/ is auto-backed-up.
 // Kept as a separate function so the boundary between "data the LLM sees in
 // the system prompt" (full origin) and "data persisted for usage reporting"
@@ -34,7 +51,9 @@ function minimalOrigin(origin: SessionOrigin): MinimalSessionOrigin {
         kind: 'channel',
         adapter: origin.adapter,
         workspace: origin.workspace,
+        ...(origin.workspaceName !== undefined ? { workspaceName: origin.workspaceName } : {}),
         chat: origin.chat,
+        ...(origin.chatName !== undefined ? { chatName: origin.chatName } : {}),
         thread: origin.thread,
       }
     case 'subagent':

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/subagent-completion-reminder.ts

@@ -0,0 +1,89 @@
+// Shared renderer for the `<system-reminder>` block injected into a parent
+// session's prompt queue when one of its backgrounded subagents finishes.
+// Used by the TUI route in src/server/index.ts and the channel-router
+// bridge so the model sees identical wording across origins. The
+// `channel` knob is the only per-origin difference: channel sessions
+// need the "end your reply via channel_reply" nudge because plain-text
+// output is invisible there AND the reminder is not a user message —
+// the channel origin block's MUST-call-channel_reply rule is keyed to
+// user messages, so a model that reads the spec literally would
+// otherwise leave the reply un-sent.
+
+export type CompletionReminderArgs = {
+  subagent: string
+  taskId: string
+  ok: boolean
+  durationMs: number
+  error?: string
+  channel?: boolean
+}
+
+const CHANNEL_REPLY_NUDGE =
+  'This reminder is a system message, not a user inbound — but you are in a channel session, ' +
+  'so end your turn via `channel_reply` (or `channel_send`) to surface the result. ' +
+  'Plain-text output is invisible here. If there is genuinely nothing to surface, end with `NO_REPLY`.'
+
+export function renderSubagentCompletionReminder(args: CompletionReminderArgs): string {
+  const durationStr = formatReminderDuration(args.durationMs)
+  const channelTail = args.channel === true ? ` ${CHANNEL_REPLY_NUDGE}` : ''
+  if (args.ok) {
+    return (
+      `<system-reminder>\n` +
+      `Subagent \`${args.subagent}\` (${args.taskId}) completed in ${durationStr}. ` +
+      `Use subagent_output to fetch the result.${channelTail}\n` +
+      `</system-reminder>`
+    )
+  }
+  const err = args.error ?? 'unknown error'
+  return (
+    `<system-reminder>\n` +
+    `Subagent \`${args.subagent}\` (${args.taskId}) FAILED after ${durationStr}: ${err}. ` +
+    `Use subagent_output to inspect.${channelTail}\n` +
+    `</system-reminder>`
+  )
+}
+
+export function formatReminderDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const totalSec = Math.floor(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const min = Math.floor(totalSec / 60)
+  const sec = totalSec % 60
+  return `${min}m${sec}s`
+}
+
+export type SubagentCompletedPayload = {
+  taskId: string
+  subagent: string
+  parentSessionId: string
+  ok: boolean
+  durationMs: number
+  error?: string
+}
+
+// Type guard for the `subagent.completed` broadcast payload. Subscribers
+// to `target: { kind: 'broadcast' }` see every broadcast; this guard
+// filters and narrows in one place so callers don't repeat the
+// typeof-checking dance.
+export function parseSubagentCompletedPayload(payload: unknown): SubagentCompletedPayload | null {
+  if (payload === null || typeof payload !== 'object') return null
+  const p = payload as {
+    kind?: unknown
+    taskId?: unknown
+    subagent?: unknown
+    parentSessionId?: unknown
+    ok?: unknown
+    durationMs?: unknown
+    error?: unknown
+  }
+  if (p.kind !== 'subagent.completed') return null
+  if (typeof p.parentSessionId !== 'string') return null
+  return {
+    taskId: typeof p.taskId === 'string' ? p.taskId : '<unknown>',
+    subagent: typeof p.subagent === 'string' ? p.subagent : 'subagent',
+    parentSessionId: p.parentSessionId,
+    ok: p.ok === true,
+    durationMs: typeof p.durationMs === 'number' ? p.durationMs : 0,
+    ...(typeof p.error === 'string' ? { error: p.error } : {}),
+  }
+}

package/src/agent/subagents.ts

@@ -206,12 +206,13 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
       hooks && sessionId !== undefined && agentDir !== undefined
         ? { sessionId, agentDir, ...(origin !== undefined ? { origin } : {}) }
         : undefined
+    const userPromptForTurn = override?.userPrompt ?? options.userPrompt
     try {
       if (hooks && turnEvent !== undefined) {
-        await hooks.runSessionTurnStart(turnEvent)
+        await hooks.runSessionTurnStart({ ...turnEvent, userPrompt: userPromptForTurn })
       }
       try {
-        await session.prompt(override?.userPrompt ?? options.userPrompt)
+        await session.prompt(userPromptForTurn)
       } finally {
         if (hooks && turnEvent !== undefined) {
           await hooks.runSessionTurnEnd(turnEvent)

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.
@@ -8,22 +10,22 @@ TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your
 - **SOUL.md** *(always injected below)* — your character, tone, voice. Edit rarely.
 - **USER.md** *(read on demand)* — what you know about the user. Update as you learn.
 - **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
-- **MEMORY.md** *(always injected below, READ-ONLY)* — long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or in \`memory/\` daily streams; never edit MEMORY.md directly.
+- **\`memory/topics/\`** *(always injected below, READ-ONLY)* — sharded long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`; never edit memory shards directly.
 
-If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never MEMORY.md.
+If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards.
 
 ## Your workspace
 
 - **\`workspace/\`** — your free-write zone for drafts, scratch work, generated artifacts. Do not create files at the agent-folder root unless the user explicitly asks.
 - **\`sessions/\`** — transcripts of past conversations. Runtime-managed; don't write here.
-- **\`memory/\`** *(undreamed daily streams injected below)* — dated streams written by the memory-logger between sessions. Runtime-owned.
+- **\`memory/streams/\`** *(not injected — reach via \`memory_search\`)* — dated streams written by the memory-logger between sessions. Runtime-owned. Undreamed observations are searchable on demand instead of injected into every prompt.
 - **\`memory/skills/\`** — muscle-memory skills written by the dreaming subagent. Auto-loaded; don't write here directly.
 - **\`.agents/skills/\`** — user-installed skills.
 
 ## 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,13 +41,13 @@ 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
 
 - Match the user's register. If SOUL.md specifies a voice, use it. Otherwise, be concise and direct, without filler or flattery.
-- Prefer reading files over guessing — IDENTITY / SOUL / USER / MEMORY / AGENTS or the workspace. Follow AGENTS.md in whatever role IDENTITY.md assigns you; propose additions to AGENTS.md when you find gaps worth codifying.
+- Prefer reading files over guessing — IDENTITY / SOUL / USER / memory topics / AGENTS or the workspace. Follow AGENTS.md in whatever role IDENTITY.md assigns you; propose additions to AGENTS.md when you find gaps worth codifying.
 - Answer questions. Do work. Don't over-explain unless asked.
 - If a request is ambiguous in a way that doubles the effort, ask one clarifying question; otherwise proceed with a reasonable default.
 - Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
@@ -60,7 +62,7 @@ There are two delegation modes. Pick deliberately.
 
 When you need information to answer the user and the search is broad, fire 2-5 subagents in parallel with \`run_in_background: true\` covering different angles. End your response after spawning. The system will deliver a \`<system-reminder>\` for each completion; gather results then answer the user. Do NOT poll \`subagent_output\` in a tight loop.
 
-The bundled \`explorer\` subagent is the right tool for **local** reconnaissance — anything reachable on the agent's filesystem: code, past sessions (\`sessions/*.jsonl\`), MEMORY.md and daily memory streams, skills, cron jobs, config, git history, mounts, channels state. It is read-only and runs on a fast/cheap model, so fire liberally. Do NOT ask it to plan, decide, or write code — it finds and reports.
+The bundled \`explorer\` subagent is the right tool for **local** reconnaissance — anything reachable on the agent's filesystem: code, past sessions (\`sessions/*.jsonl\`), memory topic shards and daily memory streams, skills, cron jobs, config, git history, mounts, channels state. It is read-only and runs on a fast/cheap model, so fire liberally. Do NOT ask it to plan, decide, or write code — it finds and reports.
 
 The bundled \`scout\` subagent is its external counterpart — web research only. Use it when you need information from public sources (docs, library references, vendor changelogs, news, anything not already in this agent's folder). Scout runs \`websearch\` and \`webfetch\` in a fresh context window so the search churn does not pollute yours; it returns a citation-backed answer with a confidence rating. Prefer scout over running \`websearch\`/\`webfetch\` yourself when the research is non-trivial (more than 1-2 queries) or when you want to save your context for the synthesis step.
 
@@ -68,9 +70,11 @@ 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.
+In a channel session, the completion \`<system-reminder>\` is NOT a user message — the channel origin's "you MUST call \`channel_reply\` for every user message" rule does not literally apply, but the underlying constraint does: plain-text output is invisible in a channel. Surface the result via \`channel_reply\` (or \`channel_send\`) so the user actually sees it. Failures need surfacing too: when a delegated task didn't complete, the user needs the outcome and whatever partial progress you got. \`NO_REPLY\` is the escape hatch only when the user has already seen the substantive answer — typically because you posted it via \`channel_reply\` in the same turn that spawned the subagent, and the reminder is purely confirming completion of a step the user is already tracking. Otherwise, post the result.
+
+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 +121,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,16 +161,16 @@ 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
+//   5. Filesystem hygiene — workspace boundary, memory-shard ownership, and
+//      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
+//      does not gate bash/git on the
 //      runtime-managed paths.
 //
 // What does NOT live here, by design:
@@ -151,12 +185,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/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/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.`

package/src/bundled-plugins/explorer/explorer.ts

@@ -9,7 +9,7 @@ You are STRICTLY PROHIBITED from:
 - Creating, modifying, or deleting files
 - Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any write operation
 - Starting long-running background processes
-- Writing to MEMORY.md, sessions/, workspace/, or any other runtime-managed path
+- Writing to memory/topics/, memory/streams/, sessions/, workspace/, or any other runtime-managed path
 - Spawning further subagents — you are at the end of the delegation chain
 
 Your role is EXCLUSIVELY to search and analyze existing local state.
@@ -32,7 +32,7 @@ The agent folder is mounted at \`/agent\` inside the container. Search the narro
 
 1. **Codebase** — \`/agent/\` root and subdirs (excluding the runtime-managed paths below). Source files, docs, identity files (\`IDENTITY.md\`, \`SOUL.md\`, \`USER.md\`, \`AGENTS.md\`).
 2. **Sessions** — \`/agent/sessions/*.jsonl\` — conversation transcripts. Each line is a JSON event (user message, tool call, tool result, assistant message). Filename pattern \`\${ISO_TIMESTAMP}_\${UUID}.jsonl\`. \`grep\` works directly on the JSONL.
-3. **Memory** — \`/agent/MEMORY.md\` (long-term consolidated memory) and \`/agent/memory/yyyy-MM-dd.jsonl\` (daily fragment streams written by the memory-logger subagent). \`memory/.dreaming-state.json\` tracks the dreaming watermark. Do NOT edit any of these — they are runtime-owned.
+3. **Memory** — \`/agent/memory/topics/*.md\` (long-term topic shards) and \`/agent/memory/streams/yyyy-MM-dd.jsonl\` (daily fragment streams written by the memory-logger subagent). \`memory/.dreaming-state.json\` tracks the dreaming watermark. Do NOT edit any of these — they are runtime-owned.
 4. **Muscle-memory skills** — \`/agent/memory/skills/<name>/SKILL.md\` — procedures the dreaming subagent distilled from repeated work.
 5. **User-installed skills** — \`/agent/.agents/skills/<name>/SKILL.md\` — hand-authored or downloaded skills.
 6. **Workspace** — \`/agent/workspace/\` — the agent's free-write zone. Drafts, scratch work, generated artifacts.

package/src/bundled-plugins/guard/index.ts

@@ -2,6 +2,7 @@ import { definePlugin } from '@/plugin'
 
 import {
   checkManagedConfigGuard,
+  checkMemoryTopicsDeleteGuard,
   checkNonWorkspaceWriteGuard,
   checkSkillAuthoringGuard,
   checkUncommittedChangesAdvice,
@@ -23,7 +24,19 @@ export default definePlugin({
           agentDir: ctx.agentDir,
         })
         if (skillResult) return skillResult
-        return checkNonWorkspaceWriteGuard({ tool: event.tool, args: event.args, agentDir: ctx.agentDir })
+        const memoryTopicsDeleteResult = checkMemoryTopicsDeleteGuard({
+          tool: event.tool,
+          args: event.args,
+          agentDir: ctx.agentDir,
+          origin: event.origin,
+        })
+        if (memoryTopicsDeleteResult) return memoryTopicsDeleteResult
+        return checkNonWorkspaceWriteGuard({
+          tool: event.tool,
+          args: event.args,
+          agentDir: ctx.agentDir,
+          origin: event.origin,
+        })
       },
       'tool.after': async (event, ctx) => {
         await checkUncommittedChangesAdvice({

package/src/bundled-plugins/guard/policies/managed-config.ts

@@ -39,19 +39,31 @@ export async function checkManagedConfigGuard(options: {
   }
 }
 
+// Oracle PR #305 findings #5 and #6: identity-based managed-file
+// detection. The earlier shape compared `basename(realpath(target))` to
+// the managed-file list, which missed two attacks: (5) a symlink at
+// agent root `typeclaw.json -> workspace/tc.json` realpathed to a name
+// outside the managed list, and (6) on case-insensitive filesystems,
+// `TYPECLAW.JSON` addresses the same file as `typeclaw.json` but
+// basename string-equality missed the casing variant.
+//
+// New shape: for each managed-file name, compute the canonical agent-
+// root path and compare against the target. We accept if EITHER the
+// lexical paths match OR they realpath to the same file. Branch (a)
+// covers symlinks and case-aliased filesystems; branch (b) keeps the
+// canonical lexical name authoritative even before the file exists
+// (first-init writes).
 async function resolveManagedTarget(agentDir: string, targetPath: string): Promise<{ file: ManagedFile } | undefined> {
   const resolvedAgentDir = path.resolve(agentDir)
-  const realAgentDir = await resolveRealIntendedPath(resolvedAgentDir)
-  const realTargetPath = await resolveRealIntendedPath(targetPath)
-
-  if (path.dirname(realTargetPath) !== realAgentDir) return undefined
-
-  const basename = path.basename(realTargetPath)
-  return isManagedFile(basename) ? { file: basename } : undefined
-}
-
-function isManagedFile(basename: string): basename is ManagedFile {
-  return MANAGED_FILES.has(basename as ManagedFile)
+  const resolvedTarget = path.resolve(targetPath)
+  for (const file of MANAGED_FILES) {
+    const canonical = path.join(resolvedAgentDir, file)
+    if (canonical === resolvedTarget) return { file }
+    const realCanonical = await resolveRealIntendedPath(canonical)
+    const realTarget = await resolveRealIntendedPath(resolvedTarget)
+    if (realCanonical === realTarget) return { file }
+  }
+  return undefined
 }
 
 function validateManagedContent(file: ManagedFile, content: string): { ok: true } | { ok: false; reason: string } {
@@ -81,6 +93,20 @@ async function intendedContent(
     return blockReason(tool, targetPath, 'edit calls must include an edits array')
   }
 
+  // Oracle PR #305 finding #4: refuse multi-edit on managed files to
+  // avoid simulator-vs-pi divergence. The canonical workflow for
+  // typeclaw.json / cron.json is read + modify in memory + write the
+  // whole file back; multi-edit is not required and the divergence
+  // would let an attacker validate a different final file here than
+  // the one pi actually writes.
+  if (edits.length > 1) {
+    return blockReason(
+      tool,
+      targetPath,
+      'multi-edit calls on managed files are refused — use `write` with full content instead',
+    )
+  }
+
   let content: string
   try {
     content = await readFile(targetPath, 'utf8')
@@ -100,10 +126,14 @@ async function intendedContent(
     if (oldText.length === 0) {
       return blockReason(tool, targetPath, 'edit oldText must not be empty')
     }
-    if (!content.includes(oldText)) {
+    const firstIdx = content.indexOf(oldText)
+    if (firstIdx === -1) {
       return blockReason(tool, targetPath, 'edit oldText was not found in existing file')
     }
-    content = content.replace(oldText, newText)
+    if (content.indexOf(oldText, firstIdx + 1) !== -1) {
+      return blockReason(tool, targetPath, 'edit oldText is not unique in the existing file')
+    }
+    content = content.slice(0, firstIdx) + newText + content.slice(firstIdx + oldText.length)
   }
   return { content }
 }