typeclaw 0.10.0 → 0.11.1

package/README.md

@@ -1,5 +1,9 @@
 # TypeClaw
 
+<p align="center">
+  <img src="./docs/public/typeey.png" alt="Typeey, the TypeClaw mascot — a plush bird with navy wings sitting in grass" width="240" />
+</p>
+
 > A TypeScript-native, Bun-powered, Docker-friendly general-purpose agent runtime.
 
 ## Why?
@@ -89,7 +93,7 @@ bun run lint
 bun run format
 ```
 
-See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy. The docs site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/).
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the recommended local dev loop (`bun link` → `typeclaw init`), commit and PR conventions, and where to ask questions. See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy. The docs site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/).
 
 ## Acknowledgments
 

package/package.json

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

package/src/agent/index.ts

@@ -51,6 +51,7 @@ import { createChannelHistoryTool } from './tools/channel-history'
 import { createChannelReplyTool } from './tools/channel-reply'
 import { createChannelSendTool } from './tools/channel-send'
 import { createRestartTool } from './tools/restart'
+import { createSkipResponseTool } from './tools/skip-response'
 import { createSpawnSubagentTool } from './tools/spawn-subagent'
 import { createStreamSnapshotTool } from './tools/stream-snapshot'
 import { createSubagentCancelTool } from './tools/subagent-cancel'
@@ -298,13 +299,14 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
             lookAtTool,
             ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
             ...(options.stream ? [createStreamSnapshotTool({ stream: options.stream })] : []),
-            ...buildChannelTools(options.channelRouter, options.origin),
+            ...buildChannelTools(options.channelRouter, options.origin, sessionManager.getSessionId()),
             ...(options.containerName
               ? [
                   createRestartTool({
                     containerName: options.containerName,
                     originatingSessionId: sessionManager.getSessionId(),
                     ...(options.stream ? { stream: options.stream } : {}),
+                    ...buildRestartHandoffWiring(options, sessionManager),
                   }),
                 ]
               : []),
@@ -378,6 +380,26 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
   return { session, dispose }
 }
 
+// Decides whether the restart tool should write the cross-restart handoff
+// file (`<agentDir>/.typeclaw/restart-pending.json`) and supplies the agentDir
+// + session file path it needs to do so. Returns an empty object — meaning
+// "no handoff" — for any session whose origin is not TUI, so a channel-
+// originated or cron-originated `restart` call cannot accidentally produce an
+// "I'm back" greeting in the next container's first TUI session. See
+// issue #291's scoping concerns. Also returns empty when the session is not
+// persisted to disk (in-memory sessions have no file the next container could
+// reopen).
+export function buildRestartHandoffWiring(
+  options: { origin?: SessionOrigin; plugins?: { agentDir: string } },
+  sessionManager: SessionManager,
+): { agentDir?: string; originatingSessionFile?: string } {
+  if (options.origin?.kind !== 'tui') return {}
+  const agentDir = options.plugins?.agentDir
+  const sessionFile = sessionManager.getSessionFile()
+  if (agentDir === undefined || sessionFile === undefined) return {}
+  return { agentDir, originatingSessionFile: sessionFile }
+}
+
 // Subscribes the given session to the in-process broadcast that the `restart`
 // tool fires on a successful hostd ACK. The subscriber dispatches by identity:
 // the session whose tool execution fired the restart (originator) gets a
@@ -466,13 +488,21 @@ export function formatRestartNoticeOriginating(restartedAt: string): string {
 }
 
 // Builds the channel tool subset: channel_send (always when a router is
-// available), plus channel_reply + channel_history (only when the session
-// origin is a channel — those rely on origin-bound addressing). Extracted
-// from createSessionWithDispose so composition can be unit-tested without
+// available), plus channel_reply + channel_history + skip_response (only
+// when the session origin is a channel — those rely on origin-bound
+// addressing or per-session turn state). Extracted from
+// createSessionWithDispose so composition can be unit-tested without
 // going through createAgentSession / auth.
+//
+// `sessionId` is required for `skip_response` (the tool addresses the
+// LiveSession by id when stamping the skip flag) and optional otherwise.
+// Callers that don't have it (e.g. early composition tests) get the
+// pre-skip-response tool set, which is forward-compatible — the prompt
+// guidance still mentions the NO_REPLY fallback for those cases.
 export function buildChannelTools(
   channelRouter: ChannelRouter | undefined,
   origin: SessionOrigin | undefined,
+  sessionId?: string,
 ): ToolDefinition[] {
   if (!channelRouter) return []
   const tools: ToolDefinition[] = []
@@ -492,6 +522,9 @@ export function buildChannelTools(
         origin: { adapter: origin.adapter },
       }),
     )
+    if (sessionId !== undefined) {
+      tools.push(createSkipResponseTool({ router: channelRouter, sessionId }))
+    }
   } else {
     tools.push(createChannelSendTool({ router: channelRouter }))
   }

package/src/agent/multimodal/look-at.ts

@@ -80,6 +80,14 @@ export const lookAtTool = defineTool({
         parentSessionId: '<look-at-tool>',
       }
 
+      // TODO(usage-accounting): this falls through to SessionManager.inMemory()
+      // because no sessionManager is passed, so the look_at subagent's
+      // message.usage never reaches the sessions/ JSONLs that `typeclaw usage`
+      // and the bundled `backup` plugin scan. Same root-cause class as the
+      // plugin-command/cron-handler path fixed in `runPromptForCommand`
+      // (src/server/command-runner.ts). Fixing this requires threading a
+      // SessionFactory into pi-coding-agent's tool execute() signature, which
+      // is a separate change.
       const { session, dispose } = await createSessionWithDispose({
         systemPromptOverride: systemPrompt,
         origin,

package/src/agent/restart-handoff/index.ts

@@ -0,0 +1,91 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { restartHandoffPath } from './paths'
+
+export { restartHandoffPath } from './paths'
+
+export const RESTART_HANDOFF_TTL_MS = 60_000
+
+export type RestartHandoff = {
+  schemaVersion: 1
+  restartedAt: string
+  originatingSessionId: string
+  originatingSessionFile: string
+}
+
+// Atomic write via `.tmp` + rename so a crash mid-write never leaves the
+// reader pointed at a partial JSON blob. The new container's consume() will
+// either see the prior good file, the new good file, or nothing — never a
+// half-written one. Errors are swallowed: handoff is best-effort. A failed
+// write means the next boot cold-starts (no greeting), which is the same
+// graceful degradation as the dying container being SIGKILL'd before the
+// write could run.
+export async function writeRestartHandoff(agentDir: string, handoff: RestartHandoff): Promise<void> {
+  const path = restartHandoffPath(agentDir)
+  try {
+    await mkdir(dirname(path), { recursive: true })
+    const tmp = `${path}.tmp`
+    await writeFile(tmp, JSON.stringify(handoff), 'utf8')
+    await rename(tmp, path)
+  } catch {
+    return
+  }
+}
+
+// Read-and-delete in one call so the file is removed even if the caller
+// rejects the contents (TTL expired, malformed JSON, wrong schemaVersion).
+// Otherwise a stale file would linger until the NEXT restart wrote a fresh
+// one, and the boot consumer would re-read the stale entry every time.
+//
+// Returns the parsed handoff iff the file existed, was valid JSON of the
+// expected shape, and was within `ttlMs` of `now`. Otherwise returns null.
+// `now` and `ttlMs` are injectable so tests can drive the recency gate
+// without sleeping.
+export async function consumeRestartHandoff(
+  agentDir: string,
+  options: { now?: number; ttlMs?: number } = {},
+): Promise<RestartHandoff | null> {
+  const path = restartHandoffPath(agentDir)
+  const now = options.now ?? Date.now()
+  const ttlMs = options.ttlMs ?? RESTART_HANDOFF_TTL_MS
+
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return null
+  }
+
+  await rm(path, { force: true }).catch(() => undefined)
+
+  const handoff = parseHandoff(raw)
+  if (handoff === null) return null
+
+  const restartedAtMs = Date.parse(handoff.restartedAt)
+  if (Number.isNaN(restartedAtMs)) return null
+  if (now - restartedAtMs > ttlMs) return null
+
+  return handoff
+}
+
+function parseHandoff(raw: string): RestartHandoff | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (parsed === null || typeof parsed !== 'object') return null
+  const obj = parsed as Record<string, unknown>
+  if (obj.schemaVersion !== 1) return null
+  if (typeof obj.restartedAt !== 'string') return null
+  if (typeof obj.originatingSessionId !== 'string' || obj.originatingSessionId === '') return null
+  if (typeof obj.originatingSessionFile !== 'string' || obj.originatingSessionFile === '') return null
+  return {
+    schemaVersion: 1,
+    restartedAt: obj.restartedAt,
+    originatingSessionId: obj.originatingSessionId,
+    originatingSessionFile: obj.originatingSessionFile,
+  }
+}

package/src/agent/restart-handoff/paths.ts

@@ -0,0 +1,11 @@
+import { join } from 'node:path'
+
+// Single source of truth for the restart-handoff file path so the writer
+// (src/agent/tools/restart.ts) and the reader (src/server/index.ts) cannot
+// drift. Sibling of `.typeclaw/backup-message.tmp` — same ephemeral-tenant
+// pattern (write-then-read-and-delete, not gitignored, dir created on
+// demand). See src/bundled-plugins/backup/subagents.ts:messageFilePath for
+// the prior art.
+export function restartHandoffPath(agentDir: string): string {
+  return join(agentDir, '.typeclaw', 'restart-pending.json')
+}

package/src/agent/session-origin.ts

@@ -222,9 +222,27 @@ function renderChannelOrigin(
     '',
     '**For every user message in this session, you MUST call `channel_reply`',
     '(or `channel_send`) at least once before ending your turn**, unless the',
-    'user explicitly told you to stay silent. If you intentionally do not',
-    'reply, your entire final visible response must be exactly `NO_REPLY`.',
-    'Any other visible text without a channel tool call is blocked.',
+    'user explicitly told you to stay silent or you have nothing genuinely',
+    'new to add. When you intentionally do not reply, prefer the structured',
+    'silent-turn tool over leaking your decision into visible text:',
+    '',
+    '- **`skip_response({ reason })`** — preferred. Records a short reason',
+    '  to host logs (visible via `typeclaw logs -f`) and suppresses the',
+    '  channel reply for this turn. The user sees nothing; the operator',
+    '  sees why. Use this whenever you have a reason worth recording',
+    '  ("no new info beyond previous reply", "user asked me to stay',
+    '  silent", "subagent result duplicates what I already sent", etc.).',
+    '  The contract is bidirectional: after calling `skip_response`, any',
+    '  `channel_reply`/`channel_send` in the same turn will be rejected,',
+    '  AND calling `skip_response` after a reply has already landed in',
+    '  this turn will also be rejected. Commit to silence or commit to',
+    '  replying, not both. Do not include secrets or long reasoning in',
+    '  the reason; keep it under one sentence.',
+    '- **`NO_REPLY` text sentinel** — fallback. End your turn with',
+    '  exactly `NO_REPLY` as your visible response and no channel tool',
+    '  call. Use this only when `skip_response` is unavailable or you',
+    '  have no reason worth recording. Any other visible text without a',
+    '  channel tool call is blocked.',
     '',
     '**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',
@@ -233,13 +251,15 @@ function renderChannelOrigin(
     '',
     '**Backgrounded work does not end the obligation.** If you spawn a',
     'subagent with `run_in_background: true` to answer the current inbound,',
-    "you have promised a reply you have not delivered yet. Don't end the",
-    'turn with `NO_REPLY` — the system will not surface the subagent result',
-    'on its own. When the subagent-completion `<system-reminder>` arrives,',
-    'fetch the result with `subagent_output` and send it via `channel_reply`',
-    'in that turn. `NO_REPLY` is only legal on the post-result turn if there',
-    'is genuinely nothing user-facing to share (e.g. the result is empty or',
-    'identical to something you already replied with this conversation).',
+    "you have promised a reply you have not delivered yet. Don't skip the",
+    'turn — the system will not surface the subagent result on its own.',
+    'When the subagent-completion `<system-reminder>` arrives, fetch the',
+    'result with `subagent_output` and send it via `channel_reply` in that',
+    'turn. `skip_response` (or `NO_REPLY`) is only legal on the post-result',
+    'turn if there is genuinely nothing user-facing to share (e.g. the',
+    'result is empty or identical to something you already replied with',
+    'this conversation) — and in that case, `skip_response({ reason: "..." })`',
+    'is preferred so the operator can see why the result was dropped.',
     '',
     'Do not send a second reply just to rephrase, restate, or "confirm in',
     'plain language" something you already said.',

package/src/agent/subagent-completion-reminder.ts

@@ -23,8 +23,10 @@ const CHANNEL_REPLY_NUDGE =
   'so end your turn via `channel_reply` (or `channel_send`) to surface the result. ' +
   'Plain-text output is invisible here. If you spawned this subagent to answer a user, ' +
   'this is the turn where that promised reply lands — fetch the result via `subagent_output` ' +
-  'and send it. `NO_REPLY` is only correct when the result is genuinely empty or duplicates ' +
-  'something you already replied with in this conversation.'
+  'and send it. If the result is genuinely empty or duplicates something you already replied ' +
+  'with in this conversation, call `skip_response({ reason: "..." })` instead so the operator ' +
+  'can see why the post-completion turn was silent. `NO_REPLY` is the legacy fallback only when ' +
+  '`skip_response` is unavailable.'
 
 export function renderSubagentCompletionReminder(args: CompletionReminderArgs): string {
   const durationStr = formatReminderDuration(args.durationMs)

package/src/agent/system-prompt.ts

@@ -70,7 +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.
 
-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.
+**Concrete threshold: ~30 seconds.** If you expect a tool call to take longer than that, delegate. While your own \`bash\` is blocked, you cannot reply, the channel typing indicator cannot heartbeat past silent stretches (it caps after a couple of minutes of no tool activity by design — see \`MAX_TYPING_HEARTBEAT_MS\`), and the user sees a frozen-looking conversation. Specifically: do NOT run \`npm install\`, \`bun install\`, \`docker build\`, \`docker compose up\`, multi-target \`curl\` probes, headed-browser scrapes, WebSocket/CDP captures, long \`pytest\`/\`npm test\` suites, or any "do N requests across hosts" loop in your own session — delegate every one of those to \`operator\`. Single fast \`bash\` calls (a \`git status\`, a \`ls\`, a one-shot \`curl\` against a known endpoint) stay in your session; that's not what this rule is targeting.
+
+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. Skipping the reply is legal 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. In that case, prefer \`skip_response({ reason: "result confirms prior reply" })\` over the \`NO_REPLY\` text sentinel — the structured tool records why, so the operator can audit silent post-completion turns. 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) or \`codex\` (OpenAI Codex CLI) 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.
 

package/src/agent/tools/restart.ts

@@ -1,6 +1,9 @@
+import { basename } from 'node:path'
+
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
+import { writeRestartHandoff } from '@/agent/restart-handoff'
 import { send, sendHttp } from '@/hostd/client'
 import { containerSocketPath } from '@/hostd/paths'
 import type { Stream } from '@/stream'
@@ -36,6 +39,24 @@ export type CreateRestartToolOptions = {
   // true)` assertion flips to `ok: false, reason: 'daemon ack timeout'`.
   // Optional so production callers keep the 5s default unchanged.
   ackTimeoutMs?: number
+  // Agent folder root. Required to write the cross-restart handoff file
+  // (`<agentDir>/.typeclaw/restart-pending.json`) that lets the next
+  // container reattach to the originating session and produce the
+  // "I'm back" turn. Omit to skip the handoff write (used by sessions
+  // whose origin is not TUI — see `originatingSessionFile` below — and
+  // by ad-hoc tool construction in tests that do not need the handoff).
+  agentDir?: string
+  // Absolute path or basename of the originating session's JSONL file on
+  // disk. Required alongside `agentDir` to enable the handoff; the new
+  // container uses this to reopen the session via `SessionManager.open`
+  // so the `typeclaw.restart-self` custom message entry that was just
+  // appended is part of the LLM context on the next turn. When omitted,
+  // no handoff is written — the new container cold-starts and no
+  // "I'm back" greeting fires. Gates the handoff on the origin being a
+  // TUI session: channel/cron/subagent origins should pass undefined so
+  // the next boot does not produce a stray channel post or unattended
+  // greeting (see issue #291's scoping concerns).
+  originatingSessionFile?: string
 }
 
 export type RestartToolDetails = { ok: boolean; containerName: string; reason?: string }
@@ -55,6 +76,8 @@ export function createRestartTool({
   stream,
   originatingSessionId,
   ackTimeoutMs,
+  agentDir,
+  originatingSessionFile,
 }: CreateRestartToolOptions) {
   const doExit = exit ?? ((code: number) => process.exit(code))
   const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
@@ -104,13 +127,31 @@ export function createRestartTool({
       // synchronous (broker.ts deliver()) and SessionManager.appendCustomMessageEntry
       // does a synchronous JSONL write, so the fan-out completes inside this
       // tick — well before the EXIT_DELAY_MS timer fires.
+      const restartedAt = new Date().toISOString()
       const broadcast: ContainerRestartingBroadcast = {
         kind: 'container-restarting',
-        restartedAt: new Date().toISOString(),
+        restartedAt,
         originatingSessionId,
       }
       stream?.publish({ target: { kind: 'broadcast' }, payload: broadcast })
 
+      // Write the cross-restart handoff AFTER the broadcast has run so the
+      // originating session's JSONL already contains the `typeclaw.restart-self`
+      // custom message entry that the next container will hydrate on
+      // `SessionManager.open`. Without that ordering, the new container could
+      // theoretically open the JSONL before the entry was flushed and miss
+      // the model-instruction the entry carries. Gated on agentDir +
+      // originatingSessionFile so non-TUI origins (channel/cron/subagent)
+      // skip the file write — see issue #291's scoping concerns.
+      if (agentDir !== undefined && originatingSessionFile !== undefined) {
+        await writeRestartHandoff(agentDir, {
+          schemaVersion: 1,
+          restartedAt,
+          originatingSessionId,
+          originatingSessionFile: basename(originatingSessionFile),
+        })
+      }
+
       // Schedule the exit on the next tick so the tool result is delivered to
       // the model before the process dies. The host daemon polls for the
       // container's removal before re-running `start`, so a small delay here

package/src/agent/tools/skip-response.ts

@@ -0,0 +1,157 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { ChannelRouter } from '@/channels/router'
+
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+
+export type CreateSkipResponseToolOptions = {
+  router: ChannelRouter
+  // The channel session's id, used to locate the right LiveSession in the
+  // router and stamp the skip flag with its current turnSeq. Mirrors how
+  // `injectSubagentCompletionReminder` addresses live sessions by their
+  // session id rather than ChannelKey — keeps the tool agnostic to which
+  // adapter/workspace/chat it was wired into.
+  sessionId: string
+  logger?: ChannelToolLogger
+}
+
+const REASON_MAX_CHARS = 500
+
+export type SkipResponseDetails = {
+  ok: boolean
+  suppressed: boolean
+  reason: string
+  error?: string
+}
+
+// `skip_response` is the structured alternative to ending a turn with the
+// `NO_REPLY` text sentinel. The model invokes it when it has decided not
+// to send a user-facing reply but has a meaningful reason (`no new info`,
+// `user asked me to stay silent`, `subagent result duplicates an earlier
+// reply`, etc.). The reason lands in `typeclaw logs -f` so the operator
+// can audit silent turns; the channel router suppresses the assistant
+// text recovery for the current turn so nothing ever reaches the chat.
+//
+// This is intentionally NOT a replacement for `NO_REPLY`. The text
+// sentinel remains the fallback for cases where the model cannot or will
+// not call a tool (degraded provider, structured-output disabled, etc.).
+// `skip_response` is preferred whenever the model has a reason worth
+// recording. See session-origin.ts for the prompt-level decision rule.
+//
+// Order-dependence with `channel_reply`/`channel_send`: once `skip_response`
+// fires in a turn, the router rejects any subsequent tool-source send for
+// the same turn with `SKIP_RESPONSE_LOCK_ERROR`. The model gets a clear
+// error and learns to commit on the next turn instead of mid-turn.
+export function createSkipResponseTool({
+  router,
+  sessionId,
+  logger = consoleChannelLogger,
+}: CreateSkipResponseToolOptions) {
+  return defineTool({
+    name: 'skip_response',
+    label: 'Skip Response',
+    description:
+      'Decline to send a user-facing reply this turn, with a logged reason. Use this ' +
+      'instead of narrating "I have nothing to add" / "I will stay quiet" in your visible ' +
+      'response. The reason is written to host logs (visible via `typeclaw logs -f`) but ' +
+      'never delivered to the user. The contract is bidirectional: after calling this, any ' +
+      '`channel_reply` / `channel_send` in the same turn will be rejected, AND calling this ' +
+      'after a `channel_reply` / `channel_send` has already landed in this turn will also ' +
+      'be rejected — commit to silence or commit to replying, not both. Decide before you ' +
+      'send, and call this as your terminal tool when you decide to stay silent. Prefer ' +
+      'this over the `NO_REPLY` text sentinel whenever you have a reason worth recording.',
+    parameters: Type.Object({
+      reason: Type.String({
+        description:
+          'A short, operator-readable reason for skipping. Keep it under 500 characters. Examples: ' +
+          '"no new info beyond the previous reply", "user asked me to stay silent", "subagent result ' +
+          'is empty". Do NOT include secrets, private message bodies, or long chain-of-thought-style ' +
+          'reasoning — this string goes to logs.',
+        minLength: 1,
+        maxLength: REASON_MAX_CHARS,
+      }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const reason = params.reason.trim()
+      if (reason === '') {
+        logger.warn(formatChannelToolFailure('skip_response', 'empty reason'))
+        const details: SkipResponseDetails = { ok: false, suppressed: false, reason: '', error: 'empty reason' }
+        return {
+          content: [{ type: 'text' as const, text: 'skip_response denied: `reason` must not be empty.' }],
+          details,
+        }
+      }
+
+      const result = router.markTurnSkipped({ parentSessionId: sessionId, reason })
+      if (result.kind === 'send-already-happened') {
+        // Symmetric counterpart of the send-after-skip lock in `router.send()`.
+        // The model already committed to replying earlier in this turn; calling
+        // skip_response now would land the reply AND claim silence at the same
+        // time, which is the contract violation the lock exists to prevent.
+        // Surface a clear error and refuse to stamp the flag so the rest of
+        // the turn behaves as a normal reply turn.
+        logger.warn(
+          formatChannelToolFailure(
+            'skip_response',
+            `channel send already happened this turn (reason=${JSON.stringify(reason)})`,
+          ),
+        )
+        const details: SkipResponseDetails = {
+          ok: false,
+          suppressed: false,
+          reason,
+          error: 'send-already-happened',
+        }
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text:
+                'skip_response denied: you already sent a channel reply in this turn. ' +
+                'Commit to silence or commit to replying, not both. ' +
+                'End your turn now; the reply you already sent stands.',
+            },
+          ],
+          details,
+        }
+      }
+      if (result.kind === 'no-live-session') {
+        // Defensive: the tool is only wired into channel-origin sessions
+        // by buildChannelTools, so this branch should be unreachable in
+        // practice. If it ever fires, log loudly so the operator can see
+        // a model trying to skip a non-channel turn — we still return
+        // success so the model doesn't retry, but the log captures the
+        // anomaly.
+        logger.warn(
+          formatChannelToolFailure(
+            'skip_response',
+            `no live channel session for sessionId=${sessionId} (reason=${JSON.stringify(reason)})`,
+          ),
+        )
+        const details: SkipResponseDetails = { ok: true, suppressed: false, reason }
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'skip_response acknowledged but no live channel session found; nothing to suppress. Reason logged.',
+            },
+          ],
+          details,
+        }
+      }
+
+      const details: SkipResponseDetails = { ok: true, suppressed: true, reason }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `skip_response accepted: this turn will not produce a user-facing reply. Reason logged: ${JSON.stringify(reason)}. End your turn now; do not call channel_reply or channel_send for the rest of this turn.`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+}

package/src/bundled-plugins/memory/README.md

@@ -12,6 +12,7 @@ Auto-loaded by every TypeClaw agent. No `plugins[]` entry to add and no opt-out.
     "idleMs": 60000,
     "bufferBytes": 500000,
     "injectionBudgetBytes": 16384,
+    "minIdleDeltaLines": 3,
     "dreaming": { "schedule": "*/30 * * * *" }
   }
 }
@@ -22,6 +23,7 @@ Auto-loaded by every TypeClaw agent. No `plugins[]` entry to add and no opt-out.
 | `memory.idleMs`               | `60000`          | Debounce window before `memory-logger` spawns after a prompt completes. Minimum `1000`.                                                                                                                                                        |
 | `memory.bufferBytes`          | `500000`         | Size-based ceiling: spawns `memory-logger` when the transcript grows by this many bytes since the last run. `0` disables. Minimum `10000` when non-zero.                                                                                       |
 | `memory.injectionBudgetBytes` | `16384`          | Total shard-body budget for direct-mode memory injection. Above this, `loadMemory` switches to index-mode (headings + metadata only) and the agent must call `memory_search` to fetch specific topics or recent stream events. Minimum `4096`. |
+| `memory.minIdleDeltaLines`    | `3`              | Minimum JSONL line growth since the last `memory-logger` run required to fire an idle spawn. Below this, the idle timer ticks but no spawn fires. `0` disables (legacy always-fire-on-idle behavior). Independent of `bufferBytes`.            |
 | `memory.dreaming.schedule`    | `"*/30 * * * *"` | Five-field cron expression for the dreaming subagent.                                                                                                                                                                                          |
 
 All fields are **restart-required** — the plugin reads them once at boot.
@@ -108,12 +110,26 @@ The migration is idempotent and crash-safe.
 
 ## How `session.idle` works
 
-Core fires `session.idle` immediately after every `session.prompt()` completion. The plugin owns the debounce: a `Map<sessionId, Timeout>` reset on every event. When the timer fires, the plugin spawns `memory-logger` for that session.
+Core fires `session.idle` immediately after every `session.prompt()` completion. The plugin owns the debounce: a `Map<sessionId, Timeout>` reset on every event. When the timer fires, the plugin spawns `memory-logger` for that session — unless the min-delta gate suppresses the spawn (see below).
 
-If the user starts a new prompt before the timer fires, the next `session.idle` resets it. If the user disconnects, `session.end` cancels the timer and fires `memory-logger` immediately.
+If the user starts a new prompt before the timer fires, the next `session.idle` resets it. If the user disconnects, `session.end` cancels the timer and fires `memory-logger` immediately (unless the byte-equality skip suppresses it; see below).
 
 In busy channel sessions the agent rarely goes idle long enough to trip the timer. The size-based ceiling handles this: on every `session.idle` the plugin `fs.stat`s the transcript and compares against the size at the last memory-logger run. Once growth reaches `memory.bufferBytes`, the timer is cancelled and `memory-logger` spawns immediately.
 
+### Min-delta gate (idle)
+
+The `session.idle` hook fires after every prompt completion. A chatty channel session that briefly quiets four times in seven minutes would otherwise pay the per-spawn floor (system-prompt prefill + stream-file read + several decision-making turns) on each tick — even when only a handful of new transcript lines have arrived, almost certainly containing nothing memorable.
+
+`memory.minIdleDeltaLines` (default `3`) gates the idle-timer spawn: when the timer fires, if the transcript grew by fewer than this many JSONL lines since the last memory-logger run for the session, the spawn is skipped. The skip is logged as `memory-logger idle skip ses_X (delta below minIdleDeltaLines=N)`. The buffer-trip path is unaffected — sessions that grow `bufferBytes` of unread transcript still spawn regardless of line delta.
+
+### Byte-equality skip (session.end)
+
+When `session.end` arrives and an earlier idle/buffer-trip spawn already drained the transcript to its current size, the session-end spawn is skipped. The skip is logged as `memory-logger session-end skip ses_X (no new bytes since last spawn at N)`. The skip only applies when a real baseline was recorded (`bytesAtLastRun > 0`); sessions that ended before any spawn ran still fire on close.
+
+### Daily-stream cursor (memory-logger payload)
+
+Each `memory-logger` spawn captures the line count of `memory/streams/<today>.jsonl` at the END of its run and stamps it on a per-`parentSessionId` cursor keyed by today's date. The NEXT spawn for the same session on the same day receives `streamLineCursor: N` in its payload — the subagent uses it to skip ahead to `offset=N+1` if it does the optional local-dedup read of today's stream. The cursor is dropped on cross-day rollover (yesterday's cursor points into yesterday's file, which is no longer the spawn's target) and on `session.end`.
+
 ## Tests
 
 Test files in this directory (kebab-case, `.test.ts` neighbors): `paths`, `slug`, `frontmatter`, `topics`, `shard-snapshot`, `delete-tool`, `citations`, `citation-superset`, `migration`, `load-shards`, `load-memory`, `injection-plan`, `search-tool`, `memory-retrieval`, `memory-logger`, `dreaming`, `index`, `integration`. Plus guard policies in `../guard/policies/`: `memory-topics-delete`, `memory-topics-write`, `memory-retrieval-cache-write`.