clearclaw 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alleriasun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# ClearClaw
+
+Your coding agent, from your phone — personal assistant + project workspaces on your machine, built on the CLI's permissions, config, and memory instead of replacing them.
+
+## Why
+
+You want to talk to your coding agent from your phone. Not a chatbot — the actual agent on your actual machine, with your files, your tools, your everything.
+
+Most projects in this space add their own permission system, config format, plugin model. You end up managing two systems: the CLI you already configured, and the middleware on top.
+
+ClearClaw reuses what the CLI already has:
+
+- **No duplicate permissions.** The CLI has `settings.json` with allow/deny rules. ClearClaw relays prompts as buttons — the CLI's rules apply as-is.
+- **No duplicate config.** Your settings, MCP servers, tool allowlists — all loaded automatically. Nothing to re-configure.
+- **No duplicate memory.** `CLAUDE.md` lives in your project. The CLI loads it. ClearClaw doesn't touch it.
+- **Small and auditable.** ~1500 lines, 7 files. No plugin system, no eval, no embedded runtime.
+
+## What It Does
+
+- Routes messages between your phone and your coding agent (Telegram today, Slack planned)
+- Permission prompts with diffs, tool status, and feedback — like the terminal, on your phone
+- Maps chat groups to project workspaces — each group = a working directory
+- Personal assistant workspace for non-project conversations
+- Session continuity between terminal and phone
+
+## What It Doesn't Do
+
+- Own permissions, config, memory, or system prompts — the CLI owns those
+- Run inference or embed an agent runtime
+- Require containers, VMs, or cloud services
+- Provide a plugin or extension system
+
+## Quick Start
+
+```bash
+export TELEGRAM_BOT_TOKEN="your-bot-token"
+export ALLOWED_USER_IDS="tg:your-telegram-id"
+
+npx clearclaw
+```
+
+Or install globally: `npm install -g clearclaw`
+
+Optional: `PERMISSION_MODE` (`default` | `acceptEdits` | `bypassPermissions` | `plan`), `CLEARCLAW_HOME` (default `~/.clearclaw`).
+
+## Architecture
+
+Two interfaces keep the core thin: **Channels** (Telegram, Slack, ...) handle messaging, **Engines** (Claude Code, Codex, Kiro, ...) handle the agent. The orchestrator routes between them — adding a channel or engine means adding a file. Details in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Prior Art
+
+| Project | Description |
+|---------|-------------|
+| [Claude Code Remote Control](https://docs.anthropic.com/en/docs/claude-code/remote-control) | Anthropic's first-party `/rc`. Max-only, single session, no daemon. |
+| [OpenClaw](https://github.com/openclaw/openclaw) | Full monolith with plugin system. [Security concerns](https://github.com/openclaw/openclaw/security). |
+| [NanoClaw](https://github.com/qwibitai/nanoclaw) | Container-isolated, multi-channel. |
+| [remotecode](https://github.com/kcisoul/remotecode) | Telegram relay with HITL permissions. |
+| [Claude-Code-Remote](https://github.com/JessyTsui/Claude-Code-Remote) | Multi-channel: Telegram, Discord, Email, LINE. |
+| [claude-telegram-relay](https://github.com/godagoo/claude-telegram-relay) | Minimal Telegram daemon. |
+| [Happy Coder](https://happy.engineering/) | Native apps, E2EE, multi-session. Polished, closed-source. |
+| [Paseo](https://paseo.sh/) | Agent-agnostic daemon (Claude Code, Codex, OpenCode). E2EE. |
+| [yottoCode](https://yottocode.com/) | Native macOS + Telegram, voice I/O. |
+
+## License
+
+[MIT](LICENSE)

package/dist/channel/telegram.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import type { Channel, Button, ButtonResponse, SendMessageOpts } from "../types.js";
+import type { Channel, Button, ButtonResponse, SendMessageOpts, SendInteractiveOpts } from "../types.js";
 export declare class TelegramChannel extends EventEmitter implements Channel {
     name: string;
     private bot;
@@ -11,8 +11,12 @@ export declare class TelegramChannel extends EventEmitter implements Channel {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
-    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<void>;
-    sendInteractive(chatId: string, text: string, buttons: Button[]): Promise<ButtonResponse>;
+    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<string[]>;
+    sendInteractive(chatId: string, text: string, buttons: Button[][], opts?: SendInteractiveOpts): Promise<ButtonResponse>;
+    editMessage(chatId: string, handle: string, text: string): Promise<void>;
+    deleteMessage(chatId: string, handle: string): Promise<void>;
+    pinMessage(chatId: string, handle: string): Promise<void>;
+    unpinAllMessages(chatId: string): Promise<void>;
     setTyping(chatId: string, isTyping: boolean): Promise<void>;
     private numericId;
 }

package/dist/channel/telegram.js

@@ -70,39 +70,66 @@ export class TelegramChannel extends EventEmitter {
     async sendMessage(chatId, text, opts) {
         const numId = this.numericId(chatId);
         const chunks = splitMessage(text);
+        const handles = [];
         for (const chunk of chunks) {
             try {
-                await this.bot.api.sendMessage(numId, chunk, {
+                const sent = await this.bot.api.sendMessage(numId, chunk, {
                     parse_mode: opts?.parseMode,
                 });
+                handles.push(String(sent.message_id));
             }
             catch (err) {
                 if (opts?.parseMode) {
                     log.warn("[channel] sendMessage failed with %s, retrying as plain text", opts.parseMode);
-                    await this.bot.api.sendMessage(numId, chunk);
+                    const sent = await this.bot.api.sendMessage(numId, chunk);
+                    handles.push(String(sent.message_id));
                 }
                 else {
                     throw err;
                 }
             }
         }
+        return handles;
     }
-    async sendInteractive(chatId, text, buttons) {
+    async sendInteractive(chatId, text, buttons, opts) {
         const numId = this.numericId(chatId);
         const callbackId = crypto.randomUUID().slice(0, 8);
-        // Pre-compute callback data keys (use index to avoid collisions when buttons share values)
-        const cbEntries = buttons.map((btn, i) => ({
-            btn,
-            cbData: `${callbackId}:${i}`,
-        }));
-        // Build inline keyboard
+        // Pre-compute callback data keys (use flat index to avoid collisions when buttons share values)
+        const cbEntries = [];
+        let idx = 0;
+        for (const row of buttons) {
+            for (const btn of row) {
+                cbEntries.push({ btn, cbData: `${callbackId}:${idx++}` });
+            }
+        }
+        // Build inline keyboard — each inner array is a row
         const keyboard = new InlineKeyboard();
-        for (const { btn, cbData } of cbEntries) {
-            keyboard.text(btn.label, cbData);
+        let flatIdx = 0;
+        for (const row of buttons) {
+            for (const _btn of row) {
+                const { cbData } = cbEntries[flatIdx++];
+                keyboard.text(_btn.label, cbData);
+            }
+            keyboard.row();
+        }
+        let sent;
+        try {
+            sent = await this.bot.api.sendMessage(numId, text, {
+                reply_markup: keyboard,
+                ...(opts?.parseMode && { parse_mode: opts.parseMode }),
+            });
+        }
+        catch (err) {
+            if (opts?.parseMode) {
+                log.warn("[channel] sendInteractive failed with %s, retrying as plain text", opts.parseMode);
+                sent = await this.bot.api.sendMessage(numId, text, {
+                    reply_markup: keyboard,
+                });
+            }
+            else {
+                throw err;
+            }
         }
-        await this.bot.api.sendMessage(numId, text, {
-            reply_markup: keyboard,
-        });
         const cleanupAll = () => {
             for (const { cbData } of cbEntries) {
                 this.pendingCallbacks.delete(cbData);
@@ -126,8 +153,9 @@ export class TelegramChannel extends EventEmitter {
             return { value: "" };
         // If the button requests text, prompt for follow-up input
         if (pressed.requestText) {
-            await this.bot.api.sendMessage(numId, "Type your note:", {
+            await this.bot.api.sendMessage(numId, "Add your feedback:", {
                 reply_markup: { force_reply: true },
+                reply_parameters: { message_id: sent.message_id },
             });
             const followUpText = await new Promise((resolve) => {
                 this.pendingTextResolvers.set(chatId, resolve);
@@ -136,6 +164,24 @@ export class TelegramChannel extends EventEmitter {
         }
         return { value: pressed.value };
     }
+    async editMessage(chatId, handle, text) {
+        const numId = this.numericId(chatId);
+        await this.bot.api.editMessageText(numId, Number(handle), text);
+    }
+    async deleteMessage(chatId, handle) {
+        const numId = this.numericId(chatId);
+        await this.bot.api.deleteMessage(numId, Number(handle));
+    }
+    async pinMessage(chatId, handle) {
+        const numId = this.numericId(chatId);
+        await this.bot.api.pinChatMessage(numId, Number(handle), {
+            disable_notification: true,
+        });
+    }
+    async unpinAllMessages(chatId) {
+        const numId = this.numericId(chatId);
+        await this.bot.api.unpinAllChatMessages(numId);
+    }
     async setTyping(chatId, isTyping) {
         if (isTyping) {
             if (this.typingIntervals.has(chatId))

package/dist/engine/claude-code.js

@@ -22,6 +22,7 @@ export class ClaudeCodeEngine {
                 input,
                 description,
                 reason: options.decisionReason,
+                toolUseId: options.toolUseID,
             });
             if (resp.decision === "allow") {
                 return { behavior: "allow", updatedInput: input };
@@ -62,6 +63,8 @@ export class ClaudeCodeEngine {
             },
         });
         let resultSessionId;
+        let turnStats;
+        let lastInputTokens = 0;
         const toolUseIdToName = new Map();
         try {
             for await (const msg of q) {
@@ -71,17 +74,28 @@ export class ClaudeCodeEngine {
                 }
                 // Extract text and tool_use from assistant messages
                 if (msg.type === "assistant") {
-                    const { content } = msg.message;
+                    // BetaMessage type isn't directly importable (@anthropic-ai/sdk not installed);
+                    // .message is typed as `any` so property access works without casting.
+                    const betaMsg = msg.message;
+                    if (betaMsg.usage) {
+                        const u = betaMsg.usage;
+                        lastInputTokens = (u.input_tokens ?? 0)
+                            + (u.cache_read_input_tokens ?? 0)
+                            + (u.cache_creation_input_tokens ?? 0);
+                    }
+                    const { content } = betaMsg;
                     for (const block of content) {
                         if (block.type === "text" && block.text) {
                             yield { type: "text", text: block.text };
                         }
                         if (block.type === "tool_use") {
-                            toolUseIdToName.set(block.id, block.name);
+                            const toolUseId = block.id;
+                            toolUseIdToName.set(toolUseId, block.name);
                             yield {
                                 type: "tool_use",
                                 toolName: block.name,
                                 input: block.input,
+                                toolUseId,
                             };
                         }
                     }
@@ -99,7 +113,7 @@ export class ClaudeCodeEngine {
                                 if (output) {
                                     yield { type: "tool_result", toolName, output };
                                 }
-                                toolUseIdToName.delete(b.tool_use_id);
+                                // Retain for turn-level stats (map is GC'd when generator ends)
                             }
                         }
                     }
@@ -122,10 +136,26 @@ export class ClaudeCodeEngine {
                         yield { type: "text", text: cmdOut.content };
                     }
                 }
-                // Capture result
+                // Capture result and build turn stats
                 if (msg.type === "result") {
                     const result = msg;
                     resultSessionId = result.session_id;
+                    const models = Object.keys(result.modelUsage);
+                    if (models.length > 0) {
+                        const model = models[0];
+                        const mu = result.modelUsage[model];
+                        // Build per-tool call counts from accumulated map
+                        const toolCalls = {};
+                        for (const name of toolUseIdToName.values()) {
+                            toolCalls[name] = (toolCalls[name] ?? 0) + 1;
+                        }
+                        turnStats = {
+                            model,
+                            contextUsed: lastInputTokens,
+                            contextWindow: mu.contextWindow,
+                            toolCalls,
+                        };
+                    }
                     if (result.subtype !== "success" && result.errors.length) {
                         yield { type: "error", message: result.errors.join("\n") };
                     }
@@ -144,7 +174,7 @@ export class ClaudeCodeEngine {
             }
         }
         if (resultSessionId) {
-            yield { type: "done", sessionId: resultSessionId };
+            yield { type: "done", sessionId: resultSessionId, stats: turnStats };
         }
     }
 }

package/dist/format.d.ts

@@ -1,19 +1,24 @@
 /**
- * Diff formatting utilities for tool_use display in Telegram.
+ * Formatting utilities for Telegram display.
  *
- * Uses the `diff` library for proper unified diffs with context lines.
+ * Uses the `diff` library for unified diffs in Edit permission prompts.
  */
 /**
- * Format a tool_use event for display. Returns a MarkdownV2 string.
- * Edit/Write get rich formatting; all others get a one-line status.
+ * Summary line for the rolling tool message after a turn completes.
+ * e.g. "🔧 3× Read, 2× Grep, 1× Bash"
  */
-export declare function formatToolUse(toolName: string, input: Record<string, unknown>): string;
+export declare function formatToolCallSummary(toolCalls: Record<string, number>): string | null;
 /**
- * Format a tool_result event for display. Returns a MarkdownV2 code block
- * with input + output, or null if suppressed/empty.
+ * Short one-liner for the rolling tool message. Includes key detail
+ * but truncated to stay compact.
  */
-export declare function formatToolResult(toolName: string, output: string): string | null;
+export declare function formatToolStatusLine(toolName: string, input: Record<string, unknown>): string;
 /**
- * Human-readable one-liner for a tool invocation (used in permission prompts).
+ * Format a permission prompt for display. Returns a MarkdownV2 string.
+ * Edit/Write include the diff/preview; other tools get a one-line description.
+ */
+export declare function formatPermissionPrompt(toolName: string, input: Record<string, unknown>, description: string): string;
+/**
+ * Human-readable one-liner for a tool invocation (used in engine's canUseTool).
  */
 export declare function formatToolDescription(toolName: string, input: Record<string, unknown>): string;

package/dist/format.js

@@ -1,22 +1,62 @@
 /**
- * Diff formatting utilities for tool_use display in Telegram.
+ * Formatting utilities for Telegram display.
  *
- * Uses the `diff` library for proper unified diffs with context lines.
+ * Uses the `diff` library for unified diffs in Edit permission prompts.
  */
 import { createTwoFilesPatch } from "diff";
 const MAX_LINES = 200;
+const MAX_STATUS_LEN = 60;
 /**
- * Format a tool_use event for display. Returns a MarkdownV2 string.
- * Edit/Write get rich formatting; all others get a one-line status.
+ * Summary line for the rolling tool message after a turn completes.
+ * e.g. "🔧 3× Read, 2× Grep, 1× Bash"
  */
-export function formatToolUse(toolName, input) {
+export function formatToolCallSummary(toolCalls) {
+    const entries = Object.entries(toolCalls);
+    if (entries.length === 0)
+        return null;
+    const breakdown = entries
+        .sort(([, a], [, b]) => b - a)
+        .map(([name, count]) => `${count}× ${name}`)
+        .join(", ");
+    return `🔧 ${breakdown}`;
+}
+/**
+ * Short one-liner for the rolling tool message. Includes key detail
+ * but truncated to stay compact.
+ */
+export function formatToolStatusLine(toolName, input) {
+    const full = `🔧 ${formatToolStatus(toolName, input)}`;
+    if (full.length <= MAX_STATUS_LEN)
+        return full;
+    return `${full.slice(0, MAX_STATUS_LEN - 1)}…`;
+}
+/**
+ * Format a permission prompt for display. Returns a MarkdownV2 string.
+ * Edit/Write include the diff/preview; other tools get a one-line description.
+ */
+export function formatPermissionPrompt(toolName, input, description) {
     if (toolName === "Edit") {
-        return formatEditDiff(input);
+        const edit = input;
+        const patch = createTwoFilesPatch(`a/${edit.file_path}`, `b/${edit.file_path}`, edit.old_string, edit.new_string, "", "", { context: 3 });
+        const lines = patch.split("\n");
+        const start = lines.findIndex((l) => l.startsWith("---"));
+        const diffLines = start >= 0 ? lines.slice(start) : lines;
+        const body = escapeMarkdownV2(truncateLines(diffLines, MAX_LINES), true);
+        const header = escapeMarkdownV2(`🔐 Allow Edit? ${edit.file_path}`);
+        return `${header}\n\`\`\`diff\n${body}\n\`\`\``;
     }
     if (toolName === "Write") {
-        return formatWritePreview(input);
+        const write = input;
+        const lines = write.content.split("\n");
+        const body = escapeMarkdownV2(truncateLines(lines, MAX_LINES), true);
+        const header = escapeMarkdownV2(`🔐 Allow Write? ${write.file_path} (${lines.length} lines)`);
+        return `${header}\n\`\`\`\n${body}\n\`\`\``;
     }
-    return escapeMarkdownV2(`🔧 ${formatToolStatus(toolName, input)}`);
+    // Non-Edit/Write tools: emoji header + detail in code block
+    const detail = formatToolDetail(toolName, input);
+    const header = escapeMarkdownV2(`🔐 Allow ${toolName}?`);
+    const body = escapeMarkdownV2(truncateLines(detail.split("\n"), MAX_LINES), true);
+    return `${header}\n\`\`\`\n${body}\n\`\`\``;
 }
 function formatToolStatus(toolName, input) {
     switch (toolName) {
@@ -24,6 +64,10 @@ function formatToolStatus(toolName, input) {
             return `Bash: ${input.command ?? "(unknown)"}`;
         case "Read":
             return `Read: ${input.file_path ?? "(unknown)"}`;
+        case "Edit":
+            return `Edit: ${input.file_path ?? "(unknown)"}`;
+        case "Write":
+            return `Write: ${input.file_path ?? "(unknown)"}`;
         case "Glob":
             return `Glob: ${input.pattern ?? "(unknown)"}`;
         case "Grep":
@@ -38,22 +82,27 @@ function formatToolStatus(toolName, input) {
             return toolName;
     }
 }
-function formatEditDiff(input) {
-    const patch = createTwoFilesPatch(`a/${input.file_path}`, `b/${input.file_path}`, input.old_string, input.new_string, "", "", { context: 3 });
-    // Strip the "Index:" / "===" preamble, keep --- / +++ / @@ lines onward.
-    const lines = patch.split("\n");
-    const start = lines.findIndex((l) => l.startsWith("---"));
-    const diffLines = start >= 0 ? lines.slice(start) : lines;
-    const body = truncateLines(diffLines, MAX_LINES);
-    const header = escapeMarkdownV2(`\u270f\ufe0f Edit: ${input.file_path}`);
-    return `${header}\n\`\`\`diff\n${body}\n\`\`\``;
-}
-function formatWritePreview(input) {
-    const lines = input.content.split("\n");
-    const totalLines = lines.length;
-    const body = truncateLines(lines, MAX_LINES);
-    const header = escapeMarkdownV2(`\ud83d\udcc4 Write: ${input.file_path} (${totalLines} lines)`);
-    return `${header}\n\`\`\`\n${body}\n\`\`\``;
+/** Extract the key detail for a tool's permission prompt (command, query, URL, etc.). */
+function formatToolDetail(toolName, input) {
+    switch (toolName) {
+        case "Bash":
+            return String(input.command ?? "");
+        case "Read":
+        case "Edit":
+        case "Write":
+            return String(input.file_path ?? "");
+        case "Glob":
+        case "Grep":
+            return String(input.pattern ?? "");
+        case "WebSearch":
+            return String(input.query ?? "");
+        case "WebFetch":
+            return String(input.url ?? "");
+        case "Agent":
+            return String(input.description ?? "");
+        default:
+            return JSON.stringify(input, null, 2);
+    }
 }
 function truncateLines(lines, max) {
     if (lines.length <= max) {
@@ -63,33 +112,17 @@ function truncateLines(lines, max) {
     const remaining = lines.length - max;
     return `${shown}\n... (${remaining} more lines)`;
 }
-// Tools whose output is noisy or redundant (tool_use already shows input).
-// New/unknown tools show by default.
-const SUPPRESSED_RESULTS = new Set([
-    "Read", "Edit", "Write", "Glob", "Agent",
-    "TodoWrite", "NotebookEdit", "EnterPlanMode", "ExitPlanMode",
-]);
-/**
- * Format a tool_result event for display. Returns a MarkdownV2 code block
- * with input + output, or null if suppressed/empty.
- */
-export function formatToolResult(toolName, output) {
-    if (SUPPRESSED_RESULTS.has(toolName))
-        return null;
-    if (!output.trim())
-        return null;
-    const body = truncateLines(output.split("\n"), MAX_LINES);
-    return `\`\`\`\n${body}\n\`\`\``;
-}
 /**
- * Escape special characters for MarkdownV2 (outside code blocks).
- * Inside ``` blocks, no escaping is needed.
+ * Escape for Telegram MarkdownV2.
+ * Outside code blocks: all special chars. Inside: only backtick and backslash
+ * (other chars are literal inside pre blocks, escaping them adds visible backslashes).
  */
-function escapeMarkdownV2(text) {
-    return text.replace(/([_*\[\]()~`>#+\-=|{}.!\\])/g, "\\$1");
+function escapeMarkdownV2(text, codeBlock = false) {
+    const pattern = codeBlock ? /[`\\]/g : /[_*\[\]()~`>#+\-=|{}.!\\]/g;
+    return text.replace(pattern, "\\$&");
 }
 /**
- * Human-readable one-liner for a tool invocation (used in permission prompts).
+ * Human-readable one-liner for a tool invocation (used in engine's canUseTool).
  */
 export function formatToolDescription(toolName, input) {
     switch (toolName) {

package/dist/orchestrator.d.ts

@@ -20,6 +20,8 @@ export declare class Orchestrator {
     stop(): Promise<void>;
     private handleMessage;
     private routeEngineEvent;
+    private updateStatusMessage;
+    private clearStatusMessage;
     /** Read default workspace CLAUDE.md to append to non-default workspace sessions. */
     private readDefaultPrompt;
 }

package/dist/orchestrator.js

@@ -1,7 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import log from "./logger.js";
-import { formatToolUse, formatToolResult } from "./format.js";
+import { formatToolStatusLine, formatToolCallSummary, formatPermissionPrompt } from "./format.js";
+const MODE_OPTIONS = [
+    { label: "Default", value: "default" },
+    { label: "Accept Edits", value: "acceptEdits" },
+    { label: "Plan", value: "plan" },
+    { label: "Bypass", value: "bypassPermissions" },
+];
 export class Orchestrator {
     channel;
     engine;
@@ -19,7 +25,10 @@ export class Orchestrator {
     chat(chatId) {
         let s = this.chats.get(chatId);
         if (!s) {
-            s = { busy: false, abort: null };
+            s = {
+                busy: false, abort: null, permissionMode: null, statusHandle: null, stats: null,
+                toolCallHandle: null,
+            };
             this.chats.set(chatId, s);
         }
         return s;
@@ -46,6 +55,27 @@ export class Orchestrator {
         try {
             log.info(`[msg] ${msg.user.name} (${msg.user.id}) ${msg.text.slice(0, 80)}`);
             const state = this.chat(msg.chatId);
+            // /mode — switch permission mode (works even during active turns)
+            if (msg.text === "/mode") {
+                const currentMode = state.permissionMode ?? this.permissionMode;
+                const buttons = [
+                    MODE_OPTIONS.slice(0, 2).map((opt) => ({
+                        label: opt.value === currentMode ? `✓ ${opt.label}` : opt.label,
+                        value: opt.value,
+                    })),
+                    MODE_OPTIONS.slice(2).map((opt) => ({
+                        label: opt.value === currentMode ? `✓ ${opt.label}` : opt.label,
+                        value: opt.value,
+                    })),
+                ];
+                const resp = await this.channel.sendInteractive(msg.chatId, `Current mode: ${MODE_OPTIONS.find((o) => o.value === currentMode)?.label ?? currentMode}`, buttons);
+                if (resp.value) {
+                    state.permissionMode = resp.value;
+                    await this.updateStatusMessage(msg.chatId, state);
+                    log.info("[cmd] mode → %s", resp.value);
+                }
+                return;
+            }
             // /new — reset session
             if (msg.text === "/new") {
                 const ws = this.workspaceStore.byChat(msg.chatId);
@@ -54,6 +84,9 @@ export class Orchestrator {
                     return;
                 }
                 this.workspaceStore.clearSession(ws.name);
+                state.permissionMode = null;
+                state.stats = null;
+                await this.updateStatusMessage(msg.chatId, state);
                 log.info("[cmd] session cleared for workspace %s", ws.name);
                 await this.channel.sendMessage(msg.chatId, "Session cleared.");
                 return;
@@ -98,16 +131,21 @@ export class Orchestrator {
                     sessionId: ws.current_session_id,
                     cwd: ws.cwd,
                     prompt,
-                    permissionMode: this.permissionMode,
+                    permissionMode: state.permissionMode ?? this.permissionMode,
                     appendSystemPrompt,
                     signal: abort.signal,
                     onPermissionRequest: async (req) => {
                         log.info(`[perm] ${req.toolName}`);
-                        const resp = await this.channel.sendInteractive(msg.chatId, `Allow ${req.toolName}?\n${req.description}`, [
-                            { label: "Allow", value: "allow" },
-                            { label: "Deny", value: "deny" },
-                            { label: "Deny+Note", value: "deny", requestText: true },
-                        ]);
+                        const promptText = formatPermissionPrompt(req.toolName, req.input, req.description);
+                        const resp = await this.channel.sendInteractive(msg.chatId, promptText, [
+                            [
+                                { label: "👍 Allow", value: "allow" },
+                                { label: "👎 Deny", value: "deny" },
+                            ],
+                            [
+                                { label: "📝 Deny + Note", value: "deny", requestText: true },
+                            ],
+                        ], { parseMode: "MarkdownV2" });
                         log.info(`[perm] ${req.toolName} → ${resp.value || "timeout"}${resp.text ? ` "${resp.text}"` : ""}`);
                         return {
                             decision: resp.value === "allow" ? "allow" : "deny",
@@ -134,26 +172,32 @@ export class Orchestrator {
         }
     }
     async routeEngineEvent(chatId, event, workspaceName) {
+        const state = this.chat(chatId);
         switch (event.type) {
             case "text":
                 await this.channel.sendMessage(chatId, event.text);
                 break;
             case "tool_use": {
-                const formatted = formatToolUse(event.toolName, event.input);
-                await this.channel.sendMessage(chatId, formatted, {
-                    parseMode: "MarkdownV2",
-                });
-                break;
-            }
-            case "tool_result": {
-                const formatted = formatToolResult(event.toolName, event.output);
-                if (formatted) {
-                    await this.channel.sendMessage(chatId, formatted, {
-                        parseMode: "MarkdownV2",
-                    });
+                // Rolling message: each tool_use replaces the single message's content
+                const line = formatToolStatusLine(event.toolName, event.input);
+                if (state.toolCallHandle) {
+                    try {
+                        await this.channel.editMessage(chatId, state.toolCallHandle, line);
+                    }
+                    catch {
+                        const handles = await this.channel.sendMessage(chatId, line);
+                        state.toolCallHandle = handles[0];
+                    }
+                }
+                else {
+                    const handles = await this.channel.sendMessage(chatId, line);
+                    state.toolCallHandle = handles[0];
                 }
                 break;
             }
+            case "tool_result":
+                // All tool results suppressed — Claude summarizes in its text response
+                break;
             case "rate_limit": {
                 const resetMsg = event.resetsAt
                     ? ` Resets at ${new Date(event.resetsAt).toLocaleTimeString()}.`
@@ -162,16 +206,81 @@ export class Orchestrator {
                 await this.channel.sendMessage(chatId, `⚠️ Rate limited (${event.status}).${resetMsg}`);
                 break;
             }
-            case "done":
+            case "done": {
+                // Edit rolling tool message to show summary
+                if (state.toolCallHandle && event.stats) {
+                    const summary = formatToolCallSummary(event.stats.toolCalls);
+                    if (summary) {
+                        try {
+                            await this.channel.editMessage(chatId, state.toolCallHandle, summary);
+                        }
+                        catch { /* edit failed, leave as-is */ }
+                    }
+                }
+                state.toolCallHandle = null;
                 log.info(`[turn] done session=${event.sessionId}`);
                 this.workspaceStore.setSession(workspaceName, event.sessionId);
+                if (event.stats)
+                    state.stats = event.stats;
+                await this.updateStatusMessage(chatId, state);
                 break;
+            }
             case "error":
                 log.error(`[turn] error: ${event.message}`);
                 await this.channel.sendMessage(chatId, `Error: ${event.message}`);
                 break;
         }
     }
+    async updateStatusMessage(chatId, state) {
+        const mode = state.permissionMode ?? this.permissionMode;
+        const modeLabel = MODE_OPTIONS.find((o) => o.value === mode)?.label ?? mode;
+        const parts = [];
+        if (state.stats) {
+            const pct = state.stats.contextWindow > 0
+                ? Math.round((state.stats.contextUsed / state.stats.contextWindow) * 100)
+                : 0;
+            parts.push(`🤖 ${formatModelName(state.stats.model)} ${pct}% | 🔒 ${modeLabel}`);
+        }
+        else {
+            parts.push(`🔒 ${modeLabel}`);
+        }
+        const text = parts.join("\n");
+        if (state.statusHandle) {
+            try {
+                await this.channel.editMessage(chatId, state.statusHandle, text);
+            }
+            catch (err) {
+                if (!(err instanceof Error && err.message.includes("message is not modified")))
+                    throw err;
+            }
+        }
+        else {
+            // Clear stale pins from previous server runs
+            try {
+                await this.channel.unpinAllMessages(chatId);
+            }
+            catch { /* not admin */ }
+            const handles = await this.channel.sendMessage(chatId, text);
+            state.statusHandle = handles[0];
+            try {
+                await this.channel.pinMessage(chatId, state.statusHandle);
+            }
+            catch (err) {
+                log.warn("[cmd] failed to pin status message (bot may not be admin): %s", err instanceof Error ? err.message : String(err));
+            }
+        }
+    }
+    async clearStatusMessage(chatId, state) {
+        if (!state.statusHandle)
+            return;
+        try {
+            await this.channel.deleteMessage(chatId, state.statusHandle);
+        }
+        catch (err) {
+            log.warn("[cmd] failed to delete status message: %s", err instanceof Error ? err.message : String(err));
+        }
+        state.statusHandle = null;
+    }
     /** Read default workspace CLAUDE.md to append to non-default workspace sessions. */
     readDefaultPrompt() {
         try {
@@ -183,4 +292,8 @@ export class Orchestrator {
         }
     }
 }
+/** Strip "claude-" prefix and date suffix from model ID. e.g. "claude-opus-4-6-20250514" → "opus-4-6" */
+function formatModelName(modelId) {
+    return modelId.replace(/^claude-/, "").replace(/-\d{8}$/, "");
+}
 //# sourceMappingURL=orchestrator.js.map

package/dist/types.d.ts

@@ -7,8 +7,12 @@ export interface Channel {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
-    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<void>;
-    sendInteractive(chatId: string, text: string, buttons: Button[]): Promise<ButtonResponse>;
+    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<string[]>;
+    sendInteractive(chatId: string, text: string, buttons: Button[][], opts?: SendInteractiveOpts): Promise<ButtonResponse>;
+    editMessage(chatId: string, handle: string, text: string): Promise<void>;
+    deleteMessage(chatId: string, handle: string): Promise<void>;
+    pinMessage(chatId: string, handle: string): Promise<void>;
+    unpinAllMessages(chatId: string): Promise<void>;
     setTyping(chatId: string, isTyping: boolean): Promise<void>;
     on<K extends keyof ChannelEvents>(event: K, listener: (...args: ChannelEvents[K]) => void): this;
     off<K extends keyof ChannelEvents>(event: K, listener: (...args: ChannelEvents[K]) => void): this;
@@ -26,6 +30,9 @@ export interface ButtonResponse {
 export interface SendMessageOpts {
     parseMode?: "MarkdownV2" | "HTML";
 }
+export interface SendInteractiveOpts {
+    parseMode?: "MarkdownV2" | "HTML";
+}
 export interface Engine {
     name: string;
     runTurn(opts: RunTurnOpts): AsyncIterable<EngineEvent>;
@@ -44,11 +51,18 @@ export interface PermissionRequest {
     input: Record<string, unknown>;
     description: string;
     reason?: string;
+    toolUseId: string;
 }
 export interface PermissionResponse {
     decision: "allow" | "deny";
     message?: string;
 }
+export interface TurnStats {
+    model: string;
+    contextUsed: number;
+    contextWindow: number;
+    toolCalls: Record<string, number>;
+}
 export type EngineEvent = {
     type: "text";
     text: string;
@@ -56,6 +70,7 @@ export type EngineEvent = {
     type: "tool_use";
     toolName: string;
     input: Record<string, unknown>;
+    toolUseId: string;
 } | {
     type: "tool_result";
     toolName: string;
@@ -67,6 +82,7 @@ export type EngineEvent = {
 } | {
     type: "done";
     sessionId: string;
+    stats?: TurnStats;
 } | {
     type: "error";
     message: string;

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "clearclaw",
-  "version": "0.2.0",
+  "version": "0.3.0",
+  "description": "Your coding agent, from your phone — personal assistant + project workspaces on your machine, built on the CLI's permissions, config, and memory instead of replacing them.",
   "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alleriasun/clearclaw.git"
+  },
+  "homepage": "https://github.com/alleriasun/clearclaw",
+  "keywords": [
+    "claude-code",
+    "telegram",
+    "relay",
+    "agent-sdk",
+    "cli",
+    "remote",
+    "mobile",
+    "openclaw",
+    "nanoclaw",
+    "remotecode"
+  ],
   "bin": {
     "clearclaw": "dist/index.js"
   },