@xelauvas/xela-cli 0.3.0 → 0.4.0

package/src/tools/MonitorTool/prompt.ts

@@ -0,0 +1,45 @@
+export const MONITOR_TOOL_NAME = 'Monitor'
+
+export const DESCRIPTION = `Start a background monitor that streams events from a long-running script. Each stdout line is an event — you keep working and notifications arrive in the chat. Events arrive on their own schedule and are not replies from the user.
+
+Pick by how many notifications you need:
+- **One** ("tell me when the server is ready / the build finishes") → use **Bash with \`run_in_background\`** and a command that exits when the condition is true, e.g. \`until grep -q "Ready in" dev.log; do sleep 0.5; done\`. You get a single completion notification when it exits.
+- **One per occurrence, until the monitor expires** ("tell me every time an ERROR line appears") → Monitor with an unbounded command (\`tail -f\`, \`inotifywait -m\`, \`while true\`).
+- **One per occurrence, until a known end** ("emit each CI step result, stop when the run completes") → Monitor with a command that emits lines and then exits.
+
+Your script's stdout is the event stream. Each line becomes a notification. Exit ends the watch.
+
+  # Each matching log line is an event
+  tail -f /var/log/app.log | grep --line-buffered "ERROR"
+
+  # Each file change is an event
+  inotifywait -m --format '%e %f' /watched/dir
+
+  # Poll and emit one line per new item
+  last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  while true; do
+    now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    gh api "repos/owner/repo/issues/123/comments?since=$last" --jq '.[] | "\\(.user.login): \\(.body)"'
+    last=$now; sleep 30
+  done
+
+**Don't use an unbounded command for a single notification.** \`tail -f\`, \`inotifywait -m\` and \`while true\` never exit on their own, so the monitor stays armed until timeout even after the event has fired.
+
+**Script quality:**
+- Every pipe stage must flush per line: \`grep\` needs \`--line-buffered\`, \`awk\` needs \`fflush()\`. \`head\` cannot flush at all.
+- In poll loops, handle transient failures (\`curl ... || true\`) — one failed request shouldn't kill the monitor.
+- Poll intervals: 30s+ for remote APIs, 0.5-1s for local checks.
+- Write a specific \`description\` — it appears in every notification ("errors in deploy.log", not "watching logs").
+- Only stdout is the event stream. Merge stderr with \`2>&1\` when its failures matter.
+
+**Coverage — silence is not success.** Your filter must match every terminal state, not just the happy path: a monitor that greps only for the success marker stays silent through a crash. Widen the alternation: \`grep -E --line-buffered "elapsed_steps=|Traceback|Error|FAILED|Killed|OOM"\`.
+
+**Output volume**: every stdout line is a conversation message, so filter to the lines you would act on. Monitors that produce too many events are stopped automatically; restart with a tighter filter.
+
+Lines within 200ms are batched into a single notification. Every monitor expires after \`timeout_ms\` (default 5 minutes, at most 30 minutes); you get one notice at expiry and can re-arm. Use TaskStop to cancel early.
+
+**ws source** — open a WebSocket and stream each incoming text frame as an event, no shell and no polling:
+
+  Monitor({ ws: { url: 'wss://events.example.com/stream' }, description: 'deploy events' })
+
+Each text frame becomes one notification. Socket close ends the watch with the close code surfaced.`

package/src/tools/OverflowTestTool/OverflowTestTool.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod/v4'
+import { buildTool } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+
+export const OVERFLOW_TEST_TOOL_NAME = 'OverflowTest'
+
+const MAX_KB = 4096
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    size_kb: z.number().int().positive().max(MAX_KB).default(256).describe('How many kilobytes of text to return'),
+    marker: z.string().max(40).default('OVERFLOW').describe('Token repeated in the output, to check what survives truncation or compaction'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() => z.object({ text: z.string(), bytes: z.number() }))
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+/**
+ * Developer tool: returns a large, numbered payload so context-overflow
+ * handling (truncation, microcompact, reactive compact) can be exercised
+ * without a real workload. Gated behind OVERFLOW_TEST_TOOL.
+ */
+export const OverflowTestTool = buildTool({
+  name: OVERFLOW_TEST_TOOL_NAME,
+  searchHint: 'generate a large tool result for overflow testing',
+  maxResultSizeChars: MAX_KB * 1024 + 100,
+  userFacingName: () => 'Overflow test',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description({ size_kb }) {
+    return `Generate ${size_kb} KB of test output`
+  },
+  async prompt() {
+    return 'Testing tool: returns the requested number of kilobytes of numbered filler lines. Only use it when explicitly asked to test context overflow behaviour.'
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return { tool_use_id: toolUseID, type: 'tool_result', content: output.text }
+  },
+  renderToolUseMessage(input: { size_kb?: number }) {
+    return `${input.size_kb ?? 256} KB`
+  },
+  renderToolResultMessage(output: Output) {
+    return `${Math.round(output.bytes / 1024)} KB generated`
+  },
+  async call({ size_kb, marker }) {
+    const target = size_kb * 1024
+    const lines: string[] = []
+    let bytes = 0
+    for (let i = 1; bytes < target; i++) {
+      const line = `${marker} line ${i.toString().padStart(7, '0')} ${'x'.repeat(48)}\n`
+      lines.push(line)
+      bytes += line.length
+    }
+    const text = lines.join('')
+    return { data: { text, bytes: text.length } }
+  },
+})

package/src/tools/PushNotificationTool/PushNotificationTool.ts

@@ -0,0 +1,119 @@
+import { spawn } from 'child_process'
+import { z } from 'zod/v4'
+import { buildTool } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+
+export const PUSH_NOTIFICATION_TOOL_NAME = 'PushNotification'
+
+const PROMPT = `Send a desktop notification to the user, for moments they would want to be interrupted for: a long task finished, a decision is needed, something broke. Keep the title under 50 characters and the body to one or two sentences. Do not use it for routine progress; the transcript already shows that.`
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    title: z.string().max(120).describe('Notification title'),
+    body: z.string().max(1000).optional().describe('Notification body'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({ channels: z.array(z.string()), message: z.string() }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+function run(cmd: string, args: string[], timeoutMs = 4000): Promise<boolean> {
+  return new Promise(resolve => {
+    try {
+      const child = spawn(cmd, args, { stdio: 'ignore' })
+      const t = setTimeout(() => {
+        child.kill()
+        resolve(false)
+      }, timeoutMs)
+      child.on('error', () => {
+        clearTimeout(t)
+        resolve(false)
+      })
+      child.on('exit', code => {
+        clearTimeout(t)
+        resolve(code === 0)
+      })
+    } catch {
+      resolve(false)
+    }
+  })
+}
+
+function isWsl(): boolean {
+  return !!process.env.WSL_DISTRO_NAME || !!process.env.WSL_INTEROP
+}
+
+/**
+ * Best effort across environments: terminal notification escape (OSC 9 /
+ * OSC 777, understood by Windows Terminal, iTerm2, kitty, WezTerm...), then a
+ * native notifier when one exists. Returns the channels that accepted it.
+ */
+export async function sendDesktopNotification(title: string, body: string): Promise<string[]> {
+  const channels: string[] = []
+  if (process.stdout.isTTY) {
+    const text = body ? `${title}: ${body}` : title
+    process.stdout.write(`\u001b]9;${text}\u0007`)
+    process.stdout.write(`\u001b]777;notify;${title};${body}\u0007`)
+    process.stdout.write('\u0007')
+    channels.push('terminal')
+  }
+  if (process.platform === 'darwin') {
+    const script = `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`
+    if (await run('osascript', ['-e', script])) channels.push('macos')
+  } else if (process.platform === 'linux') {
+    if (isWsl()) {
+      const ps = `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null; $t=[Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02); $n=$t.GetElementsByTagName('text'); $n.Item(0).AppendChild($t.CreateTextNode(${JSON.stringify(title)})) | Out-Null; $n.Item(1).AppendChild($t.CreateTextNode(${JSON.stringify(body)})) | Out-Null; [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Xela').Show([Windows.UI.Notifications.ToastNotification]::new($t))`
+      if (await run('powershell.exe', ['-NoProfile', '-Command', ps], 8000)) channels.push('windows-toast')
+    }
+    if (await run('notify-send', [title, body])) channels.push('notify-send')
+  }
+  return channels
+}
+
+export const PushNotificationTool = buildTool({
+  name: PUSH_NOTIFICATION_TOOL_NAME,
+  searchHint: 'desktop notification to the user',
+  maxResultSizeChars: 500,
+  userFacingName: () => 'Notify',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description({ title }) {
+    return `Notify: ${title}`
+  },
+  async prompt() {
+    return PROMPT
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return { tool_use_id: toolUseID, type: 'tool_result', content: output.message }
+  },
+  renderToolUseMessage(input: { title?: string }) {
+    return input.title ?? ''
+  },
+  renderToolResultMessage(output: Output) {
+    return output.channels.length ? `sent via ${output.channels.join(', ')}` : 'no notification channel available'
+  },
+  async call({ title, body }) {
+    const channels = await sendDesktopNotification(title, body ?? '')
+    const message = channels.length
+      ? `Notification sent (${channels.join(', ')}).`
+      : 'No notification channel was available; the user will only see this transcript.'
+    return { data: { channels, message } }
+  },
+})

package/src/tools/ReviewArtifactTool/ReviewArtifactTool.ts

@@ -0,0 +1,93 @@
+import { mkdirSync, writeFileSync } from 'fs'
+import { dirname, isAbsolute, join, relative, resolve } from 'path'
+import { z } from 'zod/v4'
+import { buildTool } from '../../Tool.js'
+import { getCwd } from '../../utils/cwd.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { REVIEW_ARTIFACT_PROMPT, REVIEW_ARTIFACT_TOOL_NAME } from './prompt.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    title: z.string().min(1).max(200).describe('Report title'),
+    content: z.string().min(1).describe('Full Markdown body of the report'),
+    path: z.string().optional().describe('Where to write it; default .claude/reviews/<date>-<slug>.md'),
+    findings: z.number().int().nonnegative().optional().describe('Number of confirmed findings (for the summary line)'),
+    severity: z.enum(['none', 'low', 'medium', 'high', 'blocker']).optional().describe('Highest severity found'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({ path: z.string(), bytes: z.number(), message: z.string() }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'review'
+}
+
+export function defaultArtifactPath(title: string): string {
+  const date = new Date().toISOString().slice(0, 10)
+  return join('.claude', 'reviews', `${date}-${slugify(title)}.md`)
+}
+
+export function resolveArtifactPath(input: { title: string; path?: string }): string {
+  const p = input.path?.trim() || defaultArtifactPath(input.title)
+  return isAbsolute(p) ? p : resolve(getCwd(), p)
+}
+
+export const ReviewArtifactTool = buildTool({
+  name: REVIEW_ARTIFACT_TOOL_NAME,
+  searchHint: 'publish a code review report as a Markdown artifact',
+  maxResultSizeChars: 2000,
+  userFacingName: () => 'Review artifact',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return false
+  },
+  isReadOnly() {
+    return false
+  },
+  async checkPermissions(input) {
+    // Always confirmed by the user through ReviewArtifactPermissionRequest.
+    return {
+      behavior: 'ask',
+      message: `Publish review artifact "${input.title}" to ${relative(getCwd(), resolveArtifactPath(input))}`,
+    }
+  },
+  async description({ title }) {
+    return `Publish review: ${title}`
+  },
+  async prompt() {
+    return REVIEW_ARTIFACT_PROMPT
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return { tool_use_id: toolUseID, type: 'tool_result', content: output.message }
+  },
+  renderToolUseMessage(input: { title?: string; path?: string }) {
+    return input.title ?? input.path ?? ''
+  },
+  renderToolResultMessage(output: Output) {
+    return `written to ${output.path}`
+  },
+  async call(input) {
+    const target = resolveArtifactPath(input)
+    mkdirSync(dirname(target), { recursive: true })
+    const header = `# ${input.title}\n\n_Generated ${new Date().toISOString()}${input.findings !== undefined ? ` · ${input.findings} finding${input.findings === 1 ? '' : 's'}` : ''}${input.severity && input.severity !== 'none' ? ` · highest severity: ${input.severity}` : ''}_\n\n`
+    const body = input.content.startsWith('# ') ? input.content : header + input.content
+    writeFileSync(target, body.endsWith('\n') ? body : body + '\n')
+    const rel = relative(getCwd(), target)
+    const message = `Review artifact written to ${rel}${input.findings !== undefined ? ` (${input.findings} finding${input.findings === 1 ? '' : 's'})` : ''}. Tell the user the path and summarize the findings.`
+    return { data: { path: rel, bytes: body.length, message } }
+  },
+})

package/src/tools/ReviewArtifactTool/prompt.ts

@@ -0,0 +1,5 @@
+export const REVIEW_ARTIFACT_TOOL_NAME = 'ReviewArtifact'
+
+export const REVIEW_ARTIFACT_PROMPT = `Publish a review artifact: a Markdown report of a code review, bug hunt or audit that the team can read and act on without the transcript.
+
+The user is shown the title and a preview and approves before anything is written. Reports go under \`.claude/reviews/\` in the project unless a path is given. Include: scope, findings ordered by severity with file:line references and a concrete failure scenario each, what was checked and found fine, and open questions. Call it once per review, at the end.`

package/src/tools/SendUserFileTool/SendUserFileTool.ts

@@ -0,0 +1,87 @@
+import { copyFileSync, existsSync, mkdirSync, statSync } from 'fs'
+import { basename, isAbsolute, join, resolve } from 'path'
+import { z } from 'zod/v4'
+import { buildTool } from '../../Tool.js'
+import { getCwd } from '../../utils/cwd.js'
+import { getClaudeConfigHomeDir } from '../../utils/envUtils.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { DESCRIPTION, SEND_USER_FILE_PROMPT, SEND_USER_FILE_TOOL_NAME } from './prompt.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    file_path: z.string().describe('Path of the file to deliver (absolute, or relative to the working directory)'),
+    description: z.string().optional().describe('What the file is, in a few words (shown to the user)'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    deliveredPath: z.string(),
+    sizeBytes: z.number(),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export function getOutboxDir(): string {
+  return process.env.CLAUDE_CODE_OUTBOX_DIR || join(getClaudeConfigHomeDir(), 'outbox')
+}
+
+function formatSize(n: number): string {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`
+}
+
+export const SendUserFileTool = buildTool({
+  name: SEND_USER_FILE_TOOL_NAME,
+  searchHint: 'deliver a produced file to the user',
+  maxResultSizeChars: 2000,
+  userFacingName: () => 'Send file',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return false
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description({ file_path }) {
+    return `${DESCRIPTION}: ${basename(file_path)}`
+  },
+  async prompt() {
+    return SEND_USER_FILE_PROMPT
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return { tool_use_id: toolUseID, type: 'tool_result', content: output.message }
+  },
+  renderToolUseMessage(input: { file_path?: string; description?: string }) {
+    return `${input.file_path ?? ''}${input.description ? ` · ${input.description}` : ''}`
+  },
+  renderToolResultMessage(output: Output) {
+    return `delivered to ${output.deliveredPath} (${formatSize(output.sizeBytes)})`
+  },
+  async call({ file_path, description }) {
+    const source = isAbsolute(file_path) ? file_path : resolve(getCwd(), file_path)
+    if (!existsSync(source) || !statSync(source).isFile()) {
+      throw new Error(`File not found: ${source}`)
+    }
+    const dir = getOutboxDir()
+    mkdirSync(dir, { recursive: true })
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+    const target = join(dir, `${stamp}-${basename(source)}`)
+    copyFileSync(source, target)
+    const sizeBytes = statSync(target).size
+    const message = `File delivered to the user: ${target} (${formatSize(sizeBytes)})${description ? ` — ${description}` : ''}. The original stays at ${source}.`
+    return { data: { deliveredPath: target, sizeBytes, message } }
+  },
+})

package/src/tools/SendUserFileTool/prompt.ts

@@ -0,0 +1,7 @@
+export const SEND_USER_FILE_TOOL_NAME = 'SendUserFile'
+
+export const DESCRIPTION = 'Deliver a file to the user'
+
+export const SEND_USER_FILE_PROMPT = `Deliver a file you produced (report, export, screenshot, archive) to the user.
+
+The file is copied into the session outbox directory and the user is told where it is, so it survives temporary directories being cleaned up. Use it for deliverables the user asked for, not for every file you touch. Pass a short description so the notification is meaningful.`

package/src/tools/SleepTool/SleepTool.ts

@@ -0,0 +1,126 @@
+import { z } from 'zod/v4'
+import { isProactiveActive, scheduleNextTick } from '../../proactive/index.js'
+import { buildTool } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { DESCRIPTION, SLEEP_TOOL_NAME, SLEEP_TOOL_PROMPT } from './prompt.js'
+
+const MAX_SECONDS = 60 * 60
+// Proactive sleeps are capped lower so a user prompt never waits long behind one.
+const PROACTIVE_MAX_SECONDS = 15 * 60
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    seconds: z
+      .number()
+      .positive()
+      .max(MAX_SECONDS)
+      .describe(`How long to wait, in seconds (at most ${MAX_SECONDS})`),
+    reason: z.string().optional().describe('Why you are waiting (shown to the user)'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    sleptMs: z.number(),
+    interrupted: z.boolean(),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+function waitFor(ms: number, signal: AbortSignal): Promise<boolean> {
+  return new Promise<boolean>(resolve => {
+    if (signal.aborted) return resolve(true)
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve(false)
+    }, ms)
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve(true)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+export const SleepTool = buildTool({
+  name: SLEEP_TOOL_NAME,
+  searchHint: 'wait without holding a shell',
+  maxResultSizeChars: 1000,
+  userFacingName: () => 'Sleep',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  // Only offered while proactive mode is running; otherwise the model has no
+  // reason to wait and would only burn a turn.
+  isEnabled() {
+    return isProactiveActive()
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description({ seconds, reason }) {
+    return `${DESCRIPTION}: ${seconds}s${reason ? ` (${reason})` : ''}`
+  },
+  async prompt() {
+    return SLEEP_TOOL_PROMPT
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return { tool_use_id: toolUseID, type: 'tool_result', content: output.message }
+  },
+  renderToolUseMessage(input: { seconds?: number; reason?: string }) {
+    return `${input.seconds ?? '?'}s${input.reason ? ` · ${input.reason}` : ''}`
+  },
+  renderToolResultMessage(output: Output) {
+    return output.interrupted ? `interrupted after ${Math.round(output.sleptMs / 1000)}s` : `slept ${Math.round(output.sleptMs / 1000)}s`
+  },
+  async call({ seconds }, { abortController }) {
+    // In proactive mode the wait is the gap until the next <tick>: schedule
+    // it and end the turn instead of holding the loop open.
+    if (isProactiveActive()) {
+      // Proactive mode: really wait (abortable). Returning immediately let a
+      // small model keep working in a tight loop instead of ending its turn;
+      // blocking makes "do the task, Sleep 60" pace itself at one cycle per
+      // minute whatever the model does afterwards. The footer countdown
+      // shows the wake-up time; a tick that fires meanwhile is queued.
+      const ms = Math.min(seconds, PROACTIVE_MAX_SECONDS) * 1000
+      scheduleNextTick(ms)
+      const start = Date.now()
+      const interrupted = await waitFor(ms, abortController.signal)
+      const sleptMs = Date.now() - start
+      return {
+        data: {
+          sleptMs,
+          interrupted,
+          message: interrupted
+            ? `Sleep interrupted after ${Math.round(sleptMs / 1000)}s.`
+            : `Slept ${Math.round(sleptMs / 1000)}s. If there is still nothing to do, end your turn now; the next tick will wake you.`,
+        },
+      }
+    }
+    const start = Date.now()
+    const ms = Math.min(seconds, MAX_SECONDS) * 1000
+    const interrupted = await waitFor(ms, abortController.signal)
+    const sleptMs = Date.now() - start
+    return {
+      data: {
+        sleptMs,
+        interrupted,
+        message: interrupted
+          ? `Sleep interrupted after ${Math.round(sleptMs / 1000)}s.`
+          : `Slept for ${Math.round(sleptMs / 1000)}s.`,
+      },
+    }
+  },
+})

package/src/tools/SnipTool/SnipTool.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod/v4'
+import { buildTool } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import { DESCRIPTION, SNIP_TOOL_NAME } from './prompt.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    start_id: z
+      .string()
+      .describe('The [id:...] tag of the first message to remove (just the id, e.g. "3kd92a")'),
+    end_id: z
+      .string()
+      .describe('The [id:...] tag of the last message to remove (inclusive)'),
+    reason: z
+      .string()
+      .optional()
+      .describe('One short phrase on why this range is no longer needed'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    scheduled: z.literal(true),
+    start_id: z.string(),
+    end_id: z.string(),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+/**
+ * The tool call itself is the snip marker: the next query pass
+ * (snipCompactIfNeeded) finds Snip tool_use blocks without a matching
+ * boundary, removes the tagged range and leaves a boundary behind.
+ */
+export const SnipTool = buildTool({
+  name: SNIP_TOOL_NAME,
+  searchHint: 'drop stale earlier messages from the context window',
+  maxResultSizeChars: 10_000,
+  userFacingName: () => 'Snip',
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async checkPermissions(input) {
+    return { behavior: 'allow', updatedInput: input }
+  },
+  async description({ start_id, end_id }) {
+    return `Snip messages ${start_id}..${end_id}`
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: jsonStringify(output),
+    }
+  },
+  renderToolUseMessage(input: { start_id?: string; end_id?: string; reason?: string }) {
+    return `${input.start_id ?? '?'} → ${input.end_id ?? '?'}${input.reason ? ` · ${input.reason}` : ''}`
+  },
+  renderToolResultMessage() {
+    return null
+  },
+  async call({ start_id, end_id }) {
+    const clean = (s: string): string => s.trim().replace(/^\[?id:/, '').replace(/\]$/, '')
+    return {
+      data: {
+        scheduled: true as const,
+        start_id: clean(start_id),
+        end_id: clean(end_id),
+        message:
+          'Scheduled. The range is removed from your context starting with the next turn; a boundary note will mark where it was.',
+      },
+    }
+  },
+})

package/src/tools/SnipTool/prompt.ts

@@ -0,0 +1,5 @@
+export const SNIP_TOOL_NAME = 'Snip'
+
+export const DESCRIPTION = `Remove a range of earlier messages from your context window when they are no longer needed (stale tool output, exploration that led nowhere, resolved sub-tasks). User messages carry an \`[id:xxxxxx]\` tag; pass the first and last tag of the range you want gone. Everything from start_id through end_id (inclusive) stops being sent to the model from the next turn on, and a short boundary note takes its place. The user still sees the original messages in their scrollback.
+
+Use it when the conversation has grown and a chunk of it is clearly done: large file reads you already acted on, failed attempts you have moved past, verbose command output whose conclusion you have noted. Keep anything you may still need to quote or re-check. The most recent turns cannot be snipped. Tool calls and their results are removed together so the transcript stays consistent.`