clearclaw 0.1.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,17 +1,22 @@
 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;
-    private allowedUserId;
+    private allowedUserIds;
     private typingIntervals;
     private pendingCallbacks;
-    constructor(botToken: string, allowedUserId: number);
+    private pendingTextResolvers;
+    constructor(botToken: string, allowedUserIds: Set<string>);
     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

@@ -4,22 +4,36 @@ import log from "../logger.js";
 export class TelegramChannel extends EventEmitter {
     name = "telegram";
     bot;
-    allowedUserId;
+    allowedUserIds;
     typingIntervals = new Map();
     // Pending interactive responses: callbackId → resolve function
     pendingCallbacks = new Map();
-    constructor(botToken, allowedUserId) {
+    // Pending text input: chatId → resolve function (for requestText follow-ups)
+    pendingTextResolvers = new Map();
+    constructor(botToken, allowedUserIds) {
         super();
-        this.allowedUserId = allowedUserId;
+        this.allowedUserIds = allowedUserIds;
         this.bot = new Bot(botToken);
     }
     async connect() {
         // Auth check: only respond to allowed user
         this.bot.on("message:text", (ctx) => {
-            if (ctx.from?.id !== this.allowedUserId)
+            if (!ctx.from?.id || !this.allowedUserIds.has(`tg:${ctx.from.id}`))
                 return;
             const chatId = `tg:${ctx.chat.id}`;
-            this.emit("message", { chatId, text: ctx.message.text });
+            // Intercept for requestText follow-ups before emitting as a new message
+            const textResolver = this.pendingTextResolvers.get(chatId);
+            if (textResolver) {
+                this.pendingTextResolvers.delete(chatId);
+                textResolver(ctx.message.text);
+                return;
+            }
+            const user = {
+                id: `tg:${ctx.from.id}`,
+                name: [ctx.from.first_name, ctx.from.last_name].filter(Boolean).join(" "),
+                ...(ctx.from.username && { handle: ctx.from.username }),
+            };
+            this.emit("message", { chatId, user, text: ctx.message.text });
         });
         // Handle inline keyboard button presses
         this.bot.on("callback_query:data", async (ctx) => {
@@ -56,58 +70,117 @@ 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
-        const cbEntries = buttons.map((btn) => ({
-            btn,
-            cbData: `${callbackId}:${btn.value}`,
-        }));
-        // 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);
             }
         };
         // Wait for button press or timeout (30 minutes)
-        return new Promise((resolve) => {
+        const pressed = await new Promise((resolve) => {
             const timeout = setTimeout(() => {
                 cleanupAll();
-                resolve({ value: "" });
+                resolve(null);
             }, 30 * 60 * 1000);
             for (const { btn, cbData } of cbEntries) {
                 this.pendingCallbacks.set(cbData, () => {
                     clearTimeout(timeout);
                     cleanupAll();
-                    resolve({ value: btn.value });
+                    resolve(btn);
                 });
             }
         });
+        if (!pressed)
+            return { value: "" };
+        // If the button requests text, prompt for follow-up input
+        if (pressed.requestText) {
+            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);
+            });
+            return { value: pressed.value, text: followUpText };
+        }
+        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) {

package/dist/config.d.ts

@@ -1,9 +1,10 @@
 import type { PermissionMode } from "./types.js";
 export interface Config {
     botToken: string;
-    allowedUserId: number;
+    allowedUserIds: Set<string>;
     permissionMode: PermissionMode;
     dataDir: string;
+    defaultPromptPath: string;
     workspacesPath: string;
     logPath: string;
 }

package/dist/config.js

@@ -5,10 +5,10 @@ export function loadConfig() {
     const dataDir = process.env.CLEARCLAW_HOME ?? path.join(os.homedir(), ".clearclaw");
     fs.mkdirSync(dataDir, { recursive: true });
     const botToken = requireEnv("TELEGRAM_BOT_TOKEN");
-    const allowedUserId = Number(requireEnv("ALLOWED_USER_ID"));
-    if (Number.isNaN(allowedUserId)) {
-        throw new Error("ALLOWED_USER_ID must be a number");
-    }
+    const rawIds = process.env.ALLOWED_USER_IDS ?? process.env.ALLOWED_USER_ID;
+    if (!rawIds)
+        throw new Error("Missing required env var: ALLOWED_USER_IDS");
+    const allowedUserIds = new Set(rawIds.split(",").map((s) => s.trim()).filter(Boolean));
     const permissionMode = (process.env.PERMISSION_MODE ?? "default");
     const valid = [
         "default",
@@ -22,9 +22,10 @@ export function loadConfig() {
     }
     return {
         botToken,
-        allowedUserId,
+        allowedUserIds,
         permissionMode,
         dataDir,
+        defaultPromptPath: path.join(dataDir, "workspace", "CLAUDE.md"),
         workspacesPath: path.join(dataDir, "workspaces.json"),
         logPath: path.join(dataDir, "clearclaw.log"),
     };

package/dist/engine/claude-code.js

@@ -4,7 +4,7 @@ import { formatToolDescription } from "../format.js";
 export class ClaudeCodeEngine {
     name = "claude-code";
     async *runTurn(opts) {
-        const { sessionId, cwd, prompt, permissionMode, onPermissionRequest, signal, } = opts;
+        const { sessionId, cwd, prompt, permissionMode, onPermissionRequest, appendSystemPrompt, signal, } = opts;
         const abortController = new AbortController();
         // Wire external signal to our abort controller
         if (signal) {
@@ -22,11 +22,24 @@ export class ClaudeCodeEngine {
                 input,
                 description,
                 reason: options.decisionReason,
+                toolUseId: options.toolUseID,
             });
             if (resp.decision === "allow") {
                 return { behavior: "allow", updatedInput: input };
             }
-            return { behavior: "deny", message: "User denied" };
+            const denyMessage = resp.message
+                ? `User denied this action with feedback: ${resp.message}`
+                : "User denied";
+            // Deny with note: let the model read the feedback and adjust.
+            // Plain deny: interrupt to stop the turn immediately.
+            // (The SDK has a bug where interrupt causes an unhandled rejection —
+            // handleControlRequest writes to stdin after the subprocess exits.
+            // Suppressed by the unhandledRejection handler in index.ts.)
+            return {
+                behavior: "deny",
+                message: denyMessage,
+                interrupt: !resp.message,
+            };
         };
         const q = query({
             prompt,
@@ -38,9 +51,20 @@ export class ClaudeCodeEngine {
                 canUseTool,
                 abortController,
                 settingSources: ["user", "project", "local"],
+                ...(appendSystemPrompt
+                    ? {
+                        systemPrompt: {
+                            type: "preset",
+                            preset: "claude_code",
+                            append: appendSystemPrompt,
+                        },
+                    }
+                    : {}),
             },
         });
         let resultSessionId;
+        let turnStats;
+        let lastInputTokens = 0;
         const toolUseIdToName = new Map();
         try {
             for await (const msg of q) {
@@ -50,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,
                             };
                         }
                     }
@@ -78,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)
                             }
                         }
                     }
@@ -101,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") };
                     }
@@ -112,13 +163,18 @@ export class ClaudeCodeEngine {
             }
         }
         catch (err) {
-            yield {
-                type: "error",
-                message: err instanceof Error ? err.message : String(err),
-            };
+            if (err instanceof Error && err.name === "AbortError") {
+                log.info("[sdk] turn aborted");
+            }
+            else {
+                yield {
+                    type: "error",
+                    message: err instanceof Error ? err.message : String(err),
+                };
+            }
         }
         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/index.js

@@ -5,17 +5,33 @@ import { WorkspaceStore } from "./workspace-store.js";
 import { ClaudeCodeEngine } from "./engine/claude-code.js";
 import { TelegramChannel } from "./channel/telegram.js";
 import { Orchestrator } from "./orchestrator.js";
+// The Claude Agent SDK has a bug: handleControlRequest() writes to the
+// subprocess stdin without a .catch(), so aborting during a permission
+// callback causes an unhandled rejection (write to dead process).
+// Suppress that specific error so we can use abort for deny + /cancel.
+process.on("unhandledRejection", (reason) => {
+    const msg = reason instanceof Error ? reason.message : String(reason);
+    if (msg.includes("Operation aborted") ||
+        msg.includes("Failed to write to process stdin") ||
+        msg.includes("Cannot write to terminated process")) {
+        log.warn("[sdk] suppressed write error (known SDK bug): %s", msg);
+        return;
+    }
+    log.fatal({ err: reason }, "Unhandled rejection");
+    process.exit(1);
+});
 async function main() {
     const config = loadConfig();
     initLogger(config.logPath);
     const workspaceStore = new WorkspaceStore(config.workspacesPath);
-    const channel = new TelegramChannel(config.botToken, config.allowedUserId);
+    const channel = new TelegramChannel(config.botToken, config.allowedUserIds);
     const engine = new ClaudeCodeEngine();
     const orchestrator = new Orchestrator({
         channel,
         engine,
         workspaceStore,
         permissionMode: config.permissionMode,
+        defaultPromptPath: config.defaultPromptPath,
     });
     await orchestrator.start();
 }

package/dist/orchestrator.d.ts

@@ -5,16 +5,23 @@ export interface OrchestratorOpts {
     engine: Engine;
     workspaceStore: WorkspaceStore;
     permissionMode: PermissionMode;
+    defaultPromptPath: string;
 }
 export declare class Orchestrator {
     private channel;
     private engine;
     private workspaceStore;
     private permissionMode;
-    private busyChats;
+    private defaultPromptPath;
+    private chats;
     constructor(opts: OrchestratorOpts);
+    private chat;
     start(): Promise<void>;
     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,16 +1,37 @@
+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;
     workspaceStore;
     permissionMode;
-    busyChats = new Set();
+    defaultPromptPath;
+    chats = new Map();
     constructor(opts) {
         this.channel = opts.channel;
         this.engine = opts.engine;
         this.workspaceStore = opts.workspaceStore;
         this.permissionMode = opts.permissionMode;
+        this.defaultPromptPath = opts.defaultPromptPath;
+    }
+    chat(chatId) {
+        let s = this.chats.get(chatId);
+        if (!s) {
+            s = {
+                busy: false, abort: null, permissionMode: null, statusHandle: null, stats: null,
+                toolCallHandle: null,
+            };
+            this.chats.set(chatId, s);
+        }
+        return s;
     }
     async start() {
         this.channel.on("message", (msg) => {
@@ -32,7 +53,29 @@ export class Orchestrator {
     }
     async handleMessage(msg) {
         try {
-            log.info(`[msg] ${msg.text.slice(0, 80)}`);
+            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);
@@ -41,41 +84,72 @@ 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;
             }
-            // Reject during active turn (per-workspace)
-            if (this.busyChats.has(msg.chatId)) {
-                log.info("[msg] rejected (busy)");
-                await this.channel.sendMessage(msg.chatId, "Still working on the previous message...");
+            // /cancel — abort the running turn
+            if (msg.text === "/cancel") {
+                if (state.abort) {
+                    state.abort.abort();
+                    log.info("[cmd] turn cancelled");
+                }
+                else {
+                    await this.channel.sendMessage(msg.chatId, "Nothing to cancel.");
+                }
                 return;
             }
-            this.busyChats.add(msg.chatId);
+            // Workspace lookup — guard all turn logic below
             const ws = this.workspaceStore.byChat(msg.chatId);
             if (!ws) {
                 log.info("[msg] no workspace for chat %s", msg.chatId);
-                this.busyChats.delete(msg.chatId);
                 await this.channel.sendMessage(msg.chatId, "No workspace linked to this group.");
                 return;
             }
+            // Reject during active turn (per-chat)
+            if (state.busy) {
+                log.info("[msg] rejected (busy)");
+                await this.channel.sendMessage(msg.chatId, "Still working on the previous message...");
+                return;
+            }
+            state.busy = true;
+            const abort = new AbortController();
+            state.abort = abort;
             log.info(`[turn] start session=${ws.current_session_id ?? "new"} cwd=${ws.cwd}`);
             await this.channel.setTyping(msg.chatId, true);
+            // Append default workspace CLAUDE.md to non-default workspace sessions
+            const isDefaultWorkspace = ws.cwd === path.dirname(this.defaultPromptPath);
+            const appendSystemPrompt = isDefaultWorkspace ? undefined : this.readDefaultPrompt();
+            // In group workspaces, prepend sender identity so the engine knows who's talking
+            const sender = msg.user.handle ? `${msg.user.name} (@${msg.user.handle})` : msg.user.name;
+            const prompt = isDefaultWorkspace ? msg.text : `[${sender}]: ${msg.text}`;
             try {
                 for await (const event of this.engine.runTurn({
                     sessionId: ws.current_session_id,
                     cwd: ws.cwd,
-                    prompt: msg.text,
-                    permissionMode: this.permissionMode,
+                    prompt,
+                    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}?`, [
-                            { label: "Allow", value: "allow" },
-                            { label: "Deny", value: "deny" },
-                        ]);
-                        log.info(`[perm] ${req.toolName} → ${resp.value || "timeout"}`);
+                        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",
+                            message: resp.text,
                         };
                     },
                 })) {
@@ -83,8 +157,13 @@ export class Orchestrator {
                 }
             }
             finally {
-                this.busyChats.delete(msg.chatId);
+                const cancelled = abort.signal.aborted;
+                state.busy = false;
+                state.abort = null;
                 await this.channel.setTyping(msg.chatId, false);
+                if (cancelled) {
+                    await this.channel.sendMessage(msg.chatId, "Turn cancelled.");
+                }
             }
         }
         catch (err) {
@@ -93,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()}.`
@@ -121,15 +206,94 @@ 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 {
+            const content = fs.readFileSync(this.defaultPromptPath, "utf-8").trim();
+            return content || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** 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;
@@ -17,13 +21,18 @@ export interface Channel {
 export interface Button {
     label: string;
     value: string;
+    requestText?: boolean;
 }
 export interface ButtonResponse {
     value: string;
+    text?: string;
 }
 export interface SendMessageOpts {
     parseMode?: "MarkdownV2" | "HTML";
 }
+export interface SendInteractiveOpts {
+    parseMode?: "MarkdownV2" | "HTML";
+}
 export interface Engine {
     name: string;
     runTurn(opts: RunTurnOpts): AsyncIterable<EngineEvent>;
@@ -34,6 +43,7 @@ export interface RunTurnOpts {
     prompt: string;
     permissionMode: PermissionMode;
     onPermissionRequest: (req: PermissionRequest) => Promise<PermissionResponse>;
+    appendSystemPrompt?: string;
     signal?: AbortSignal;
 }
 export interface PermissionRequest {
@@ -41,9 +51,17 @@ 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";
@@ -52,6 +70,7 @@ export type EngineEvent = {
     type: "tool_use";
     toolName: string;
     input: Record<string, unknown>;
+    toolUseId: string;
 } | {
     type: "tool_result";
     toolName: string;
@@ -63,6 +82,7 @@ export type EngineEvent = {
 } | {
     type: "done";
     sessionId: string;
+    stats?: TurnStats;
 } | {
     type: "error";
     message: string;
@@ -73,8 +93,14 @@ export interface Workspace {
     chat_id: string;
     current_session_id: string | null;
 }
+export interface UserInfo {
+    id: string;
+    name: string;
+    handle?: string;
+}
 export interface InboundMessage {
     chatId: string;
+    user: UserInfo;
     text: string;
 }
 export type { PermissionMode };

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "clearclaw",
-  "version": "0.1.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"
   },
@@ -11,7 +30,8 @@
   ],
   "scripts": {
     "start": "tsx src/index.ts",
-    "dev": "tsc --watch & nodemon --watch dist --exec 'node dist/index.js'",
+    "dev": "tsx --watch src/index.ts",
+    "dev:relay": "nodemon --watch dist --exec 'node dist/index.js'",
     "build": "tsc",
     "check": "tsc --noEmit"
   },