macroclaw 0.4.0 → 0.6.0

package/README.md

@@ -5,52 +5,6 @@ Telegram-to-Claude-Code bridge. Bun + Grammy.
 Uses the Claude Code CLI (`claude -p`) rather than the Agent SDK to avoid any possible
 ToS issues with using a Claude subscription programmatically.
 
-## Vision
-
-Macroclaw is a minimal bridge between Telegram and Claude Code. It handles the parts
-that a Claude session can't: receiving messages, managing processes, scheduling tasks,
-and delivering responses.
-
-Everything else — personality, memory, skills, behavior, conventions — lives in the
-workspace. The platform stays small so the workspace can be infinitely customizable
-without touching platform code.
-
-## Architecture
-
-Macroclaw follows a **thin platform, rich workspace** design:
-
-**Platform** (this repo) — the runtime bridge:
-- Telegram bot connection and message routing
-- Claude Code process orchestration and session management
-- Background agent spawning and lifecycle
-- Cron scheduler (reads job definitions from workspace)
-- Message queue (FIFO, serial processing)
-- Timeout management and auto-retry
-
-**Workspace** — the intelligence layer, initialized from [`workspace-template/`](workspace-template/):
-- [`CLAUDE.md`](workspace-template/CLAUDE.md) — agent behavior, conventions, response style
-- [`.claude/skills/`](workspace-template/.claude/skills/) — teachable capabilities
-- [`.macroclaw/cron.json`](workspace-template/.macroclaw/cron.json) — scheduled job definitions
-- [`MEMORY.md`](workspace-template/MEMORY.md) — persistent memory
-
-### Where does a new feature belong?
-
-**Platform** when it:
-- Requires external API access (Telegram, future integrations)
-- Manages processes (spawning Claude, background agents, timeouts)
-- Operates outside Claude sessions (cron scheduling, message queuing)
-- Is a security boundary (chat authorization, workspace isolation)
-- Is bootstrap logic (workspace initialization)
-
-**Workspace** when it:
-- Defines agent behavior or personality
-- Is a convention Claude can follow via instructions
-- Can be implemented as a skill
-- Is data that Claude reads/writes (memory, tasks, cron definitions)
-- Is a formatting or response style rule
-
-> **Litmus test:** Could this feature work if you just wrote instructions in CLAUDE.md and/or created a skill? If yes → workspace. If no → platform.
-
 ## Security Model
 
 Macroclaw runs with `dangerouslySkipPermissions` enabled. This is intentional — the bot
@@ -138,6 +92,52 @@ bun test       # run tests (100% coverage enforced)
 bun run claude # open Claude Code CLI in current main session
 ```
 
+## Vision
+
+Macroclaw is a minimal bridge between Telegram and Claude Code. It handles the parts
+that a Claude session can't: receiving messages, managing processes, scheduling tasks,
+and delivering responses.
+
+Everything else — personality, memory, skills, behavior, conventions — lives in the
+workspace. The platform stays small so the workspace can be infinitely customizable
+without touching platform code.
+
+## Architecture
+
+Macroclaw follows a **thin platform, rich workspace** design:
+
+**Platform** (this repo) — the runtime bridge:
+- Telegram bot connection and message routing
+- Claude Code process orchestration and session management
+- Background agent spawning and lifecycle
+- Cron scheduler (reads job definitions from workspace)
+- Message queue (FIFO, serial processing)
+- Timeout management and auto-retry
+
+**Workspace** — the intelligence layer, initialized from [`workspace-template/`](workspace-template/):
+- [`CLAUDE.md`](workspace-template/CLAUDE.md) — agent behavior, conventions, response style
+- [`.claude/skills/`](workspace-template/.claude/skills/) — teachable capabilities
+- [`.macroclaw/cron.json`](workspace-template/.macroclaw/cron.json) — scheduled job definitions
+- [`MEMORY.md`](workspace-template/MEMORY.md) — persistent memory
+
+### Where does a new feature belong?
+
+**Platform** when it:
+- Requires external API access (Telegram, future integrations)
+- Manages processes (spawning Claude, background agents, timeouts)
+- Operates outside Claude sessions (cron scheduling, message queuing)
+- Is a security boundary (chat authorization, workspace isolation)
+- Is bootstrap logic (workspace initialization)
+
+**Workspace** when it:
+- Defines agent behavior or personality
+- Is a convention Claude can follow via instructions
+- Can be implemented as a skill
+- Is data that Claude reads/writes (memory, tasks, cron definitions)
+- Is a formatting or response style rule
+
+> **Litmus test:** Could this feature work if you just wrote instructions in CLAUDE.md and/or created a skill? If yes → workspace. If no → platform.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macroclaw",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Telegram-to-Claude-Code bridge",
   "license": "MIT",
   "type": "module",

package/src/app.test.ts

@@ -516,6 +516,51 @@ describe("App", () => {
       expect(opts.prompt).toBe('[Context: button-click] User tapped "Yes"');
     });
 
+    it("handles _dismiss callback by removing reply markup", async () => {
+      const config = makeConfig();
+      const app = new App(config);
+      const bot = app.bot as any;
+      const handler = bot.filterHandlers.get("callback_query:data")![0];
+
+      const ctx = {
+        chat: { id: 12345 },
+        callbackQuery: { data: "_dismiss" },
+        answerCallbackQuery: mock(async () => {}),
+        editMessageReplyMarkup: mock(async () => {}),
+      };
+
+      await handler(ctx);
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(ctx.answerCallbackQuery).toHaveBeenCalled();
+      expect(ctx.editMessageReplyMarkup).toHaveBeenCalledWith({ reply_markup: undefined });
+      expect((config.claude as any).run).not.toHaveBeenCalled();
+    });
+
+    it("handles peek: callback by routing to orchestrator.handlePeek", async () => {
+      const config = makeConfig();
+      const app = new App(config);
+      const bot = app.bot as any;
+      const handler = bot.filterHandlers.get("callback_query:data")![0];
+
+      const ctx = {
+        chat: { id: 12345 },
+        callbackQuery: { data: "peek:test-session-123" },
+        answerCallbackQuery: mock(async () => {}),
+        editMessageReplyMarkup: mock(async () => {}),
+      };
+
+      await handler(ctx);
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(ctx.answerCallbackQuery).toHaveBeenCalled();
+      expect(ctx.editMessageReplyMarkup).toHaveBeenCalledWith({ reply_markup: { inline_keyboard: [[{ text: "✓ Peeked", callback_data: "_noop" }]] } });
+      // handlePeek sends "Agent not found" since no active agents
+      const calls = (bot.api.sendMessage as any).mock.calls;
+      const text = calls[calls.length - 1][1];
+      expect(text).toBe("Agent not found or already finished.");
+    });
+
     it("ignores callback_query from unauthorized chats", async () => {
       const config = makeConfig();
       const app = new App(config);

package/src/app.ts

@@ -140,12 +140,26 @@ export class App {
 
     this.#bot.on("callback_query:data", async (ctx) => {
       await ctx.answerCallbackQuery();
-      const label = ctx.callbackQuery.data;
-      if (label === "_noop") return;
-      await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [[{ text: `✓ ${label}`, callback_data: "_noop" }]] } });
+      const data = ctx.callbackQuery.data;
+      if (data === "_noop") return;
       if (ctx.chat?.id.toString() !== this.#config.authorizedChatId) return;
-      log.debug({ label }, "Button clicked");
-      this.#orchestrator.handleButton(label);
+
+      if (data === "_dismiss") {
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        return;
+      }
+
+      if (data.startsWith("peek:")) {
+        const sessionId = data.slice(5);
+        await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [[{ text: "✓ Peeked", callback_data: "_noop" }]] } });
+        log.debug({ sessionId }, "Peek requested");
+        this.#orchestrator.handlePeek(sessionId);
+        return;
+      }
+
+      await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [[{ text: `✓ ${data}`, callback_data: "_noop" }]] } });
+      log.debug({ label: data }, "Button clicked");
+      this.#orchestrator.handleButton(data);
     });
 
     this.#bot.on("message:text", (ctx) => {

package/src/claude.integration-test.ts

@@ -54,7 +54,7 @@ describe("claude CLI structured output", () => {
     const claude = new Claude({ workspace: WORKSPACE, jsonSchema: SIMPLE_SCHEMA });
     const result = await runSync(claude, {
       prompt: "Say hello",
-      sessionFlag: "--session-id",
+      resume: false,
       sessionId: randomUUID(),
       model: "haiku",
     });
@@ -67,7 +67,7 @@ describe("claude CLI structured output", () => {
     const claude = new Claude({ workspace: WORKSPACE, jsonSchema: SIMPLE_SCHEMA });
     const result = await runSync(claude, {
       prompt: "Say hello",
-      sessionFlag: "--session-id",
+      resume: false,
       sessionId: randomUUID(),
       model: "haiku",
       systemPrompt: "You are a helpful assistant. This is a direct message from the user.",
@@ -81,7 +81,7 @@ describe("claude CLI structured output", () => {
     const claude = new Claude({ workspace: WORKSPACE, jsonSchema: FULL_SCHEMA });
     const result = await runSync(claude, {
       prompt: "Say hello",
-      sessionFlag: "--session-id",
+      resume: false,
       sessionId: randomUUID(),
       model: "haiku",
       systemPrompt: "You are a helpful assistant. This is a direct message from the user.",
@@ -96,7 +96,7 @@ describe("claude CLI structured output", () => {
     const claude = new Claude({ workspace, jsonSchema: FULL_SCHEMA });
     const result = await runSync(claude, {
       prompt: "Say hello",
-      sessionFlag: "--session-id",
+      resume: false,
       sessionId: randomUUID(),
       model: "sonnet",
       systemPrompt: `You are an AI assistant running inside macroclaw. This is a direct message from the user.`,

package/src/claude.test.ts

@@ -45,7 +45,6 @@ function makeClaude() {
 function opts(overrides?: Partial<ClaudeRunOptions>): ClaudeRunOptions {
   return {
     prompt: "test message",
-    sessionFlag: "--session-id",
     sessionId: "sid-1",
     ...overrides,
   };
@@ -58,7 +57,7 @@ async function runSync(claude: Claude, options: ClaudeRunOptions): Promise<Claud
 }
 
 describe("Claude", () => {
-  it("passes --session-id flag when given", async () => {
+  it("passes --session-id flag when resume is false/unset", async () => {
     mockSpawn({ stdout: jsonResult({ action: "send", message: "Hello" }), exitCode: 0 });
     const claude = makeClaude();
     const result = await runSync(claude, opts());
@@ -69,10 +68,10 @@ describe("Claude", () => {
     );
   });
 
-  it("passes --resume flag when given", async () => {
+  it("passes --resume flag when resume is true", async () => {
     mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
     const claude = makeClaude();
-    await claude.run(opts({ sessionFlag: "--resume", sessionId: "sid-2" }));
+    await claude.run(opts({ resume: true, sessionId: "sid-2" }));
     expect(Bun.spawn).toHaveBeenCalledWith(
       expect.arrayContaining(["claude", "-p", "--resume", "sid-2"]),
       expect.objectContaining({ cwd: TEST_WORKSPACE }),
@@ -102,7 +101,7 @@ describe("Claude", () => {
   it("passes --fork-session when forkSession is true", async () => {
     mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
     const claude = makeClaude();
-    await claude.run(opts({ sessionFlag: "--resume", sessionId: "sid-fork", forkSession: true, prompt: "bg task" }));
+    await claude.run(opts({ resume: true, sessionId: "sid-fork", forkSession: true, prompt: "bg task" }));
     expect(Bun.spawn).toHaveBeenCalledWith(
       expect.arrayContaining(["--resume", "sid-fork", "--fork-session"]),
       expect.objectContaining({ cwd: TEST_WORKSPACE }),
@@ -125,6 +124,25 @@ describe("Claude", () => {
     expect(args).not.toContain("--append-system-prompt");
   });
 
+  it("omits --json-schema when plainText is true", async () => {
+    const envelope = JSON.stringify({ type: "result", result: "status update", duration_ms: 100, total_cost_usd: 0.01, session_id: "sid-pt" });
+    mockSpawn({ stdout: envelope, exitCode: 0 });
+    const claude = makeClaude();
+    const result = await runSync(claude, opts({ sessionId: "sid-pt", plainText: true }));
+    const args = (Bun.spawn as any).mock.calls[0][0] as string[];
+    expect(args).not.toContain("--json-schema");
+    expect(args).toContain("--output-format");
+    expect(result.result).toBe("status update");
+  });
+
+  it("includes --json-schema when plainText is not set", async () => {
+    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
+    const claude = makeClaude();
+    await claude.run(opts({ sessionId: "sid-schema" }));
+    const args = (Bun.spawn as any).mock.calls[0][0] as string[];
+    expect(args).toContain("--json-schema");
+  });
+
   it("throws ClaudeProcessError on non-zero exit", async () => {
     mockSpawn({ stderr: "something went wrong", exitCode: 1 });
     const claude = makeClaude();
@@ -179,7 +197,7 @@ describe("Claude", () => {
   it("returns structured_output from successful response", async () => {
     mockSpawn({ stdout: jsonResult({ action: "silent", actionReason: "no new results" }), exitCode: 0 });
     const claude = makeClaude();
-    const result = await runSync(claude, opts({ sessionFlag: "--resume", sessionId: "sid-8" }));
+    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-8" }));
     expect(result.structuredOutput).toEqual({ action: "silent", actionReason: "no new results" });
     expect(result.sessionId).toBe("test-session-id");
   });
@@ -188,7 +206,7 @@ describe("Claude", () => {
     const envelope = JSON.stringify({ type: "result", result: "plain text", duration_ms: 100, total_cost_usd: 0.01, session_id: "sid-abc" });
     mockSpawn({ stdout: envelope, exitCode: 0 });
     const claude = makeClaude();
-    const result = await runSync(claude, opts({ sessionFlag: "--resume", sessionId: "sid-9" }));
+    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-9" }));
     expect(result.structuredOutput).toBeNull();
     expect(result.result).toBe("plain text");
     expect(result.sessionId).toBe("sid-abc");
@@ -198,14 +216,14 @@ describe("Claude", () => {
     const envelope = JSON.stringify({ type: "result", result: "text", duration_ms: 100, total_cost_usd: 0.01 });
     mockSpawn({ stdout: envelope, exitCode: 0 });
     const claude = makeClaude();
-    const result = await runSync(claude, opts({ sessionFlag: "--resume", sessionId: "sid-9c" }));
+    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-9c" }));
     expect(result.sessionId).toBe("");
   });
 
   it("returns result from envelope", async () => {
     mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
     const claude = makeClaude();
-    const result = await runSync(claude, opts({ sessionFlag: "--resume", sessionId: "sid-9b" }));
+    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-9b" }));
     expect(result.result).toBe("");
   });
 
@@ -213,7 +231,7 @@ describe("Claude", () => {
     mockSpawn({ stdout: "not json at all", exitCode: 0 });
     const claude = makeClaude();
     try {
-      await runSync(claude, opts({ sessionFlag: "--resume", sessionId: "sid-10" }));
+      await runSync(claude, opts({ resume: true, sessionId: "sid-10" }));
       expect.unreachable("should have thrown");
     } catch (err) {
       expect(err).toBeInstanceOf(ClaudeParseError);
@@ -224,7 +242,7 @@ describe("Claude", () => {
   it("returns duration and cost from envelope", async () => {
     mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
     const claude = makeClaude();
-    const result = await runSync(claude, opts({ sessionFlag: "--resume", sessionId: "sid-11" }));
+    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-11" }));
     expect(result.duration).toBe("1.2s");
     expect(result.cost).toBe("$0.0500");
   });
@@ -232,7 +250,7 @@ describe("Claude", () => {
   it("does not set timeout when timeoutMs is not provided", async () => {
     mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
     const claude = makeClaude();
-    const result = await runSync(claude, opts({ sessionFlag: "--resume", sessionId: "sid-12" }));
+    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-12" }));
     expect(result.structuredOutput).toEqual({ action: "send" });
   });
 

package/src/claude.ts

@@ -4,12 +4,13 @@ const log = createLogger("claude");
 
 export interface ClaudeRunOptions {
   prompt: string;
-  sessionFlag: "--resume" | "--session-id";
+  resume?: boolean;
   sessionId: string;
   forkSession?: boolean;
   model?: string;
   systemPrompt?: string;
   timeoutMs?: number;
+  plainText?: boolean;
 }
 
 export interface ClaudeResult {
@@ -89,7 +90,9 @@ export class Claude {
     const env = { ...process.env };
     delete env.CLAUDECODE;
 
-    const args = ["claude", "-p", options.sessionFlag, options.sessionId, "--output-format", "json", "--json-schema", this.#jsonSchema];
+    const sessionFlag = options.resume ? "--resume" : "--session-id";
+    const args = ["claude", "-p", sessionFlag, options.sessionId, "--output-format", "json"];
+    if (!options.plainText) args.push("--json-schema", this.#jsonSchema);
     if (options.forkSession) args.push("--fork-session");
     if (options.model) args.push("--model", options.model);
     if (options.systemPrompt) args.push("--append-system-prompt", options.systemPrompt);
@@ -98,7 +101,7 @@ export class Claude {
     log.debug(
       {
         model: options.model,
-        sessionFlag: options.sessionFlag,
+        resume: options.resume,
         sessionId: options.sessionId,
         promptLen: options.prompt.length,
         hasSystemPrompt: !!options.systemPrompt,

package/src/cli.ts

@@ -3,6 +3,7 @@ import {existsSync, readFileSync} from "node:fs";
 import {join, resolve} from "node:path";
 import {createInterface} from "node:readline";
 import {defineCommand} from "citty";
+import pkg from "../package.json" with { type: "json" };
 import {initLogger} from "./logger";
 import {ServiceManager, type SystemService} from "./service";
 import {loadSessions} from "./sessions";
@@ -180,7 +181,7 @@ const serviceCommand = defineCommand({
 });
 
 export const main = defineCommand({
-	meta: { name: "macroclaw", description: "Telegram-to-Claude-Code bridge", version: "0.0.0-dev" },
+	meta: { name: pkg.name, description: pkg.description, version: pkg.version },
 	subCommands: { start: startCommand, setup: setupCommand, claude: claudeCommand, service: serviceCommand },
 });
 

package/src/orchestrator.test.ts

@@ -230,7 +230,7 @@ describe("Orchestrator", () => {
   });
 
   describe("session management", () => {
-    it("uses --resume for existing session", async () => {
+    it("uses resume=true for existing session", async () => {
       saveSessions({ mainSessionId: "existing-session" }, tmpSettingsDir);
       const claude = mockClaude(successResult({ action: "send", message: "ok", actionReason: "ok" }));
       const { orch } = makeOrchestrator(claude);
@@ -238,7 +238,7 @@ describe("Orchestrator", () => {
       orch.handleMessage("hello");
       await waitForProcessing();
 
-      expect(claude.run.mock.calls[0][0].sessionFlag).toBe("--resume");
+      expect(claude.run.mock.calls[0][0].resume).toBe(true);
       expect(claude.run.mock.calls[0][0].sessionId).toBe("existing-session");
     });
 
@@ -249,7 +249,7 @@ describe("Orchestrator", () => {
       orch.handleMessage("hello");
       await waitForProcessing();
 
-      expect(claude.run.mock.calls[0][0].sessionFlag).toBe("--session-id");
+      expect(claude.run.mock.calls[0][0].resume).toBe(false);
       expect(claude.run.mock.calls[0][0].sessionId).toMatch(/^[0-9a-f]{8}-/);
     });
 
@@ -267,12 +267,12 @@ describe("Orchestrator", () => {
       await waitForProcessing();
 
       expect(callCount).toBe(2);
-      expect(claude.run.mock.calls[0][0].sessionFlag).toBe("--resume");
-      expect(claude.run.mock.calls[1][0].sessionFlag).toBe("--session-id");
+      expect(claude.run.mock.calls[0][0].resume).toBe(true);
+      expect(claude.run.mock.calls[1][0].resume).toBe(false);
       expect(claude.run.mock.calls[1][0].sessionId).not.toBe("old-session");
     });
 
-    it("switches to --resume after first success", async () => {
+    it("switches to resume=true after first success", async () => {
       const claude = mockClaude(successResult({ action: "send", message: "ok", actionReason: "ok" }));
       const { orch } = makeOrchestrator(claude);
 
@@ -281,8 +281,8 @@ describe("Orchestrator", () => {
       orch.handleMessage("second");
       await waitForProcessing();
 
-      expect(claude.run.mock.calls[0][0].sessionFlag).toBe("--session-id");
-      expect(claude.run.mock.calls[1][0].sessionFlag).toBe("--resume");
+      expect(claude.run.mock.calls[0][0].resume).toBe(false);
+      expect(claude.run.mock.calls[1][0].resume).toBe(true);
     });
 
     it("handleSessionCommand sends session via onResponse", async () => {
@@ -314,7 +314,7 @@ describe("Orchestrator", () => {
       await waitForProcessing();
 
       // background-agent should use --resume and forkSession
-      expect(claude.run.mock.calls[1][0].sessionFlag).toBe("--resume");
+      expect(claude.run.mock.calls[1][0].resume).toBe(true);
       expect(claude.run.mock.calls[1][0].forkSession).toBe(true);
     });
 
@@ -519,6 +519,92 @@ describe("Orchestrator", () => {
 
       expect(responses[0].message).toBe("No background agents running.");
     });
+
+    it("includes peek buttons and dismiss when agents are running", async () => {
+      const claude = mockClaude(() => new Promise<ClaudeResult>(() => {}));
+      const { orch, responses } = makeOrchestrator(claude);
+
+      orch.handleBackgroundCommand("long-task");
+      await waitForProcessing();
+
+      orch.handleBackgroundList();
+      await waitForProcessing();
+
+      const listResponse = responses[responses.length - 1];
+      expect(listResponse.message).toContain("long-task");
+      expect(listResponse.buttons).toBeDefined();
+      expect(listResponse.buttons!.length).toBe(2); // 1 peek + dismiss
+      const peekBtn = listResponse.buttons![0];
+      expect(typeof peekBtn).toBe("object");
+      expect((peekBtn as any).data).toMatch(/^peek:/);
+      expect((peekBtn as any).text).toContain("long-task");
+      expect(listResponse.buttons![1]).toBe("_dismiss");
+    });
+  });
+
+  describe("handlePeek", () => {
+    it("returns 'not found' for unknown sessionId", async () => {
+      const claude = mockClaude(successResult({ action: "send", message: "ok", actionReason: "ok" }));
+      const { orch, responses } = makeOrchestrator(claude);
+
+      await orch.handlePeek("nonexistent-session");
+      await waitForProcessing();
+
+      expect(responses[0].message).toBe("Agent not found or already finished.");
+    });
+
+    it("peeks at running agent and returns status", async () => {
+      let callCount = 0;
+      const claude = mockClaude(async (): Promise<ClaudeResult> => {
+        callCount++;
+        if (callCount === 1) return new Promise(() => {}); // bg agent never finishes
+        return { structuredOutput: null, sessionId: "peek-session", result: "Working on it, 50% done." };
+      });
+      const { orch, responses } = makeOrchestrator(claude);
+
+      orch.handleBackgroundCommand("research");
+      await waitForProcessing();
+
+      // Get the internal session ID from the peek button
+      orch.handleBackgroundList();
+      await waitForProcessing();
+      const listResponse = responses[responses.length - 1];
+      const peekBtn = listResponse.buttons![0] as { text: string; data: string };
+      const sessionId = peekBtn.data.slice(5); // strip "peek:"
+
+      await orch.handlePeek(sessionId);
+      await waitForProcessing();
+
+      const messages = responses.map((r) => r.message);
+      expect(messages.some((m) => m.includes("Peeking at"))).toBe(true);
+      expect(messages.some((m) => m.includes("Working on it"))).toBe(true);
+    });
+
+    it("handles Claude error during peek gracefully", async () => {
+      let callCount = 0;
+      const claude = mockClaude(async (): Promise<ClaudeResult> => {
+        callCount++;
+        if (callCount === 1) return new Promise(() => {}); // bg agent never finishes
+        throw new Error("connection lost");
+      });
+      const { orch, responses } = makeOrchestrator(claude);
+
+      orch.handleBackgroundCommand("failing-peek");
+      await waitForProcessing();
+
+      // Get the internal session ID from the peek button
+      orch.handleBackgroundList();
+      await waitForProcessing();
+      const listResponse = responses[responses.length - 1];
+      const peekBtn = listResponse.buttons![0] as { text: string; data: string };
+      const sessionId = peekBtn.data.slice(5);
+
+      await orch.handlePeek(sessionId);
+      await waitForProcessing();
+
+      const messages = responses.map((r) => r.message);
+      expect(messages.some((m) => m.includes("Couldn't peek at"))).toBe(true);
+    });
   });
 
   describe("handleBackgroundCommand", () => {

package/src/orchestrator.ts

@@ -5,6 +5,7 @@ import { createLogger } from "./logger";
 import { BG_TIMEOUT, CRON_TIMEOUT, MAIN_TIMEOUT, SYSTEM_PROMPT } from "./prompts";
 import { Queue } from "./queue";
 import { loadSessions, newSessionId, type Sessions, saveSessions } from "./sessions";
+import type { ButtonSpec } from "./telegram";
 
 const log = createLogger("orchestrator");
 
@@ -32,10 +33,12 @@ const jsonSchema = JSON.stringify(z.toJSONSchema(claudeResponseSchema, { target:
 
 // --- Public response type ---
 
+export type { ButtonSpec };
+
 export interface OrchestratorResponse {
   message: string;
   files?: string[];
-  buttons?: string[];
+  buttons?: ButtonSpec[];
 }
 
 // --- Internal request types ---
@@ -86,7 +89,7 @@ export class Orchestrator {
   #claude: Claude;
   #sessions: Sessions;
   #sessionId: string;
-  #sessionFlag: "--resume" | "--session-id";
+  #resumeSession: boolean;
   #sessionResolved = false;
   #config: OrchestratorConfig;
   #active = new Map<string, BackgroundInfo>();
@@ -101,10 +104,10 @@ export class Orchestrator {
 
     if (this.#sessions.mainSessionId) {
       this.#sessionId = this.#sessions.mainSessionId;
-      this.#sessionFlag = "--resume";
+      this.#resumeSession = true;
     } else {
       this.#sessionId = newSessionId();
-      this.#sessionFlag = "--session-id";
+      this.#resumeSession = false;
       saveSessions({ mainSessionId: this.#sessionId }, config.settingsDir);
       log.info({ sessionId: this.#sessionId }, "Created new session");
     }
@@ -140,7 +143,39 @@ export class Orchestrator {
       const elapsed = Math.round((Date.now() - a.startTime.getTime()) / 1000);
       return `- ${escapeHtml(a.name)} (${elapsed}s)`;
     });
-    this.#callOnResponse({ message: lines.join("\n") });
+    const buttons: ButtonSpec[] = agents.map((a) => {
+      const elapsed = Math.round((Date.now() - a.startTime.getTime()) / 1000);
+      const text = `${a.name} (${elapsed}s)`.slice(0, 27);
+      return { text, data: `peek:${a.sessionId}` };
+    });
+    buttons.push("_dismiss");
+    this.#callOnResponse({ message: lines.join("\n"), buttons });
+  }
+
+  async handlePeek(sessionId: string): Promise<void> {
+    const agent = this.#active.get(sessionId);
+    if (!agent) {
+      this.#callOnResponse({ message: "Agent not found or already finished." });
+      return;
+    }
+
+    this.#callOnResponse({ message: `Peeking at <b>${escapeHtml(agent.name)}</b>...` });
+
+    try {
+      const result = await this.#claude.run({
+        resume: true,
+        sessionId,
+        forkSession: true,
+        model: "haiku",
+        plainText: true,
+        prompt: "Give a brief status update: what has been done so far, what's currently happening, and what's remaining. 2-3 sentences max.",
+      });
+
+      const text = isDeferred(result) ? "Agent is still working..." : (result.result ?? "[No output]");
+      this.#callOnResponse({ message: `<b>[${escapeHtml(agent.name)}]</b> ${text}` });
+    } catch (err) {
+      this.#callOnResponse({ message: `Couldn't peek at ${escapeHtml(agent.name)}: ${err}` });
+    }
   }
 
   handleSessionCommand(): void {
@@ -265,15 +300,15 @@ export class Orchestrator {
     await logPrompt(request);
 
     if (built.useMainSession) {
-      let result = await this.#callClaude(built, this.#sessionFlag, this.#sessionId, options?.forkSession);
+      let result = await this.#callClaude(built, this.#resumeSession, this.#sessionId, options?.forkSession);
 
       // Session resolution: if resume failed on first call, create new session
-      if (!isDeferred(result) && !this.#sessionResolved && this.#sessionFlag === "--resume" && result.response.actionReason === "process-error") {
+      if (!isDeferred(result) && !this.#sessionResolved && this.#resumeSession && result.response.actionReason === "process-error") {
         this.#sessionId = newSessionId();
         log.info({ sessionId: this.#sessionId }, "Resume failed, created new session");
-        this.#sessionFlag = "--session-id";
+        this.#resumeSession = false;
         saveSessions({ mainSessionId: this.#sessionId }, this.#config.settingsDir);
-        result = await this.#callClaude(built, this.#sessionFlag, this.#sessionId);
+        result = await this.#callClaude(built, this.#resumeSession, this.#sessionId);
       }
 
       if (isDeferred(result)) return result;
@@ -288,7 +323,7 @@ export class Orchestrator {
       // Mark resolved on first success
       if (!this.#sessionResolved && result.response.actionReason !== "process-error") {
         this.#sessionResolved = true;
-        this.#sessionFlag = "--resume";
+        this.#resumeSession = true;
       }
 
       await logResult(result.response);
@@ -297,7 +332,7 @@ export class Orchestrator {
 
     // background-agent: fork from main session for full context
     log.debug({ name: (request as { name: string }).name }, "Processing background-agent (forked session)");
-    const bgResult = await this.#callClaude(built, "--resume", this.#sessionId, true);
+    const bgResult = await this.#callClaude(built, true, this.#sessionId, true);
     if (isDeferred(bgResult)) return bgResult;
     await logResult(bgResult.response);
     return bgResult.response;
@@ -368,11 +403,11 @@ export class Orchestrator {
     return { response: { action: "send", message: msg, actionReason: "no-structured-output" }, sessionId: result.sessionId };
   }
 
-  async #callClaude(built: BuiltRequest, flag: "--resume" | "--session-id", sid: string, forkSession?: boolean): Promise<CallResult | ClaudeDeferredResult> {
+  async #callClaude(built: BuiltRequest, resume: boolean, sid: string, forkSession?: boolean): Promise<CallResult | ClaudeDeferredResult> {
     try {
       const result = await this.#claude.run({
         prompt: built.prompt,
-        sessionFlag: flag,
+        resume,
         sessionId: sid,
         forkSession,
         model: built.model,

package/src/telegram.test.ts

@@ -136,6 +136,20 @@ describe("buildInlineKeyboard", () => {
     expect(btn.callback_data).toBe("A");
     expect((kb.inline_keyboard[2][0] as any).text).toBe("C");
   });
+
+  it("supports object buttons with separate text and data", () => {
+    const kb = buildInlineKeyboard([
+      { text: "Peek agent-1 (30s)", data: "peek:session-123" },
+      "_dismiss",
+    ]);
+    expect(kb.inline_keyboard.length).toBe(2);
+    const peekBtn = kb.inline_keyboard[0][0] as any;
+    expect(peekBtn.text).toBe("Peek agent-1 (30s)");
+    expect(peekBtn.callback_data).toBe("peek:session-123");
+    const dismissBtn = kb.inline_keyboard[1][0] as any;
+    expect(dismissBtn.text).toBe("_dismiss");
+    expect(dismissBtn.callback_data).toBe("_dismiss");
+  });
 });
 
 describe("downloadFile", () => {

package/src/telegram.ts

@@ -5,6 +5,8 @@ import { join } from "node:path";
 import { Bot, InlineKeyboard, InputFile } from "grammy";
 import { createLogger } from "./logger";
 
+export type ButtonSpec = string | { text: string; data: string };
+
 const log = createLogger("telegram");
 
 const MAX_LENGTH = 4096;
@@ -15,11 +17,16 @@ export function createBot(token: string) {
   return new Bot(token);
 }
 
-export function buildInlineKeyboard(buttons: string[]): InlineKeyboard {
+export function buildInlineKeyboard(buttons: ButtonSpec[]): InlineKeyboard {
   const kb = new InlineKeyboard();
   for (let i = 0; i < buttons.length; i++) {
     if (i > 0) kb.row();
-    kb.text(buttons[i], buttons[i]);
+    const b = buttons[i];
+    if (typeof b === "string") {
+      kb.text(b, b);
+    } else {
+      kb.text(b.text, b.data);
+    }
   }
   return kb;
 }
@@ -28,7 +35,7 @@ export async function sendResponse(
   bot: Bot,
   chatId: string,
   text: string,
-  buttons?: string[],
+  buttons?: ButtonSpec[],
 ): Promise<void> {
   const opts = { parse_mode: "HTML" as const };
   const replyMarkup = buttons?.length ? buildInlineKeyboard(buttons) : undefined;