@betrue/openclaw-claude-code-plugin 1.0.0

package/src/tools/claude-bg.ts

@@ -0,0 +1,100 @@
+import { Type } from "@sinclair/typebox";
+import { sessionManager, resolveOriginChannel } from "../shared";
+
+export function registerClaudeBgTool(api: any): void {
+  api.registerTool(
+    {
+      name: "claude_bg",
+      description:
+        "Send a Claude Code session back to background (stop streaming). If no session specified, detaches whichever session is currently in foreground.",
+      parameters: Type.Object({
+        session: Type.Optional(
+          Type.String({
+            description:
+              "Session name or ID to send to background. If omitted, detaches the current foreground session.",
+          }),
+        ),
+        channel: Type.Optional(
+          Type.String({
+            description:
+              'Origin channel in "channel:target" format (e.g. "telegram:123456789"). Pass this when calling from an agent tool context.',
+          }),
+        ),
+      }),
+      async execute(_id: string, params: any) {
+        if (!sessionManager) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: SessionManager not initialized. The claude-code service must be running.",
+              },
+            ],
+          };
+        }
+
+        // If a specific session is given, detach it
+        if (params.session) {
+          const session = sessionManager.resolve(params.session);
+          if (!session) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Error: Session "${params.session}" not found.`,
+                },
+              ],
+            };
+          }
+
+          const channelId = resolveOriginChannel({ id: _id }, params.channel);
+          session.saveFgOutputOffset(channelId);
+          session.foregroundChannels.delete(channelId);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Session ${session.name} [${session.id}] moved to background.`,
+              },
+            ],
+          };
+        }
+
+        // No session specified — find any session that has this channel in foreground
+        const resolvedId = resolveOriginChannel({ id: _id }, params.channel);
+        const allSessions = sessionManager.list("all");
+        const fgSessions = allSessions.filter((s) =>
+          s.foregroundChannels.has(resolvedId),
+        );
+
+        if (fgSessions.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No session is currently in foreground.",
+              },
+            ],
+          };
+        }
+
+        const names: string[] = [];
+        for (const s of fgSessions) {
+          s.saveFgOutputOffset(resolvedId);
+          s.foregroundChannels.delete(resolvedId);
+          names.push(`${s.name} [${s.id}]`);
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Moved to background: ${names.join(", ")}`,
+            },
+          ],
+        };
+      },
+    },
+    { optional: false },
+  );
+}

package/src/tools/claude-fg.ts

@@ -0,0 +1,106 @@
+import { Type } from "@sinclair/typebox";
+import { sessionManager, formatDuration, resolveOriginChannel } from "../shared";
+
+export function registerClaudeFgTool(api: any): void {
+  api.registerTool(
+    {
+      name: "claude_fg",
+      description:
+        "Bring a Claude Code session to foreground (by name or ID). Shows buffered output and streams new output.",
+      parameters: Type.Object({
+        session: Type.String({
+          description: "Session name or ID to bring to foreground",
+        }),
+        lines: Type.Optional(
+          Type.Number({
+            description: "Number of recent buffered lines to show (default 30)",
+          }),
+        ),
+        channel: Type.Optional(
+          Type.String({
+            description:
+              'Origin channel in "channel:target" format (e.g. "telegram:123456789"). Pass this when calling from an agent tool context.',
+          }),
+        ),
+      }),
+      async execute(_id: string, params: any) {
+        if (!sessionManager) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: SessionManager not initialized. The claude-code service must be running.",
+              },
+            ],
+          };
+        }
+
+        const session = sessionManager.resolve(params.session);
+
+        if (!session) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Session "${params.session}" not found.`,
+              },
+            ],
+          };
+        }
+
+        // Mark this conversation as a foreground channel
+        // _id is tool call ID; use explicit params.channel when available
+        const channelId = resolveOriginChannel({ id: _id }, params.channel);
+
+        // Get catchup output (produced while this channel was backgrounded)
+        const catchupLines = session.getCatchupOutput(channelId);
+
+        session.foregroundChannels.add(channelId);
+
+        const duration = formatDuration(session.duration);
+
+        const header = [
+          `Session ${session.name} [${session.id}] now in foreground.`,
+          `Status: ${session.status.toUpperCase()} | Duration: ${duration}`,
+          `${"─".repeat(60)}`,
+        ].join("\n");
+
+        // Build catchup section if there's missed output
+        let catchupSection = "";
+        if (catchupLines.length > 0) {
+          catchupSection = [
+            `📋 Catchup (${catchupLines.length} missed output${catchupLines.length === 1 ? "" : "s"}):`,
+            catchupLines.join("\n"),
+            `${"─".repeat(60)}`,
+          ].join("\n");
+        }
+
+        // If no catchup, fall back to showing recent lines
+        const body =
+          catchupLines.length > 0
+            ? catchupSection
+            : (session.getOutput(params.lines ?? 30).length > 0
+                ? session.getOutput(params.lines ?? 30).join("\n")
+                : "(no output yet)");
+
+        const footer =
+          session.status === "running" || session.status === "starting"
+            ? `\n${"─".repeat(60)}\nStreaming new output... Use claude_bg to detach.`
+            : `\n${"─".repeat(60)}\nSession is ${session.status}. No more output expected.`;
+
+        // Mark that this channel has now seen all output up to this point
+        session.markFgOutputSeen(channelId);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${header}\n${body}${footer}`,
+            },
+          ],
+        };
+      },
+    },
+    { optional: false },
+  );
+}

package/src/tools/claude-kill.ts

@@ -0,0 +1,66 @@
+import { Type } from "@sinclair/typebox";
+import { sessionManager } from "../shared";
+
+export function registerClaudeKillTool(api: any): void {
+  api.registerTool(
+    {
+      name: "claude_kill",
+      description: "Terminate a running Claude Code session by name or ID.",
+      parameters: Type.Object({
+        session: Type.String({ description: "Session name or ID to terminate" }),
+      }),
+      async execute(_id: string, params: any) {
+        if (!sessionManager) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: SessionManager not initialized. The claude-code service must be running.",
+              },
+            ],
+          };
+        }
+
+        const session = sessionManager.resolve(params.session);
+
+        if (!session) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Session "${params.session}" not found.`,
+              },
+            ],
+          };
+        }
+
+        if (
+          session.status === "completed" ||
+          session.status === "failed" ||
+          session.status === "killed"
+        ) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Session ${session.name} [${session.id}] is already ${session.status}. No action needed.`,
+              },
+            ],
+          };
+        }
+
+        sessionManager.kill(session.id);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Session ${session.name} [${session.id}] has been terminated.`,
+            },
+          ],
+        };
+      },
+    },
+    { optional: false },
+  );
+}

package/src/tools/claude-launch.ts

@@ -0,0 +1,173 @@
+import { Type } from "@sinclair/typebox";
+import { sessionManager, pluginConfig, resolveOriginChannel } from "../shared";
+
+export function registerClaudeLaunchTool(api: any): void {
+  api.registerTool(
+    {
+      name: "claude_launch",
+      description:
+        "Launch a Claude Code session in background to execute a development task. Supports resuming previous sessions and multi-turn conversations. Returns a session ID and name for tracking.",
+      parameters: Type.Object({
+        prompt: Type.String({ description: "The task prompt to execute" }),
+        name: Type.Optional(
+          Type.String({
+            description:
+              "Short human-readable name for the session (kebab-case, e.g. 'fix-auth'). Auto-generated from prompt if omitted.",
+          }),
+        ),
+        workdir: Type.Optional(
+          Type.String({ description: "Working directory (defaults to cwd)" }),
+        ),
+        model: Type.Optional(
+          Type.String({ description: "Model name to use" }),
+        ),
+        max_budget_usd: Type.Optional(
+          Type.Number({
+            description: "Maximum budget in USD (default 5)",
+          }),
+        ),
+        system_prompt: Type.Optional(
+          Type.String({ description: "Additional system prompt" }),
+        ),
+        allowed_tools: Type.Optional(
+          Type.Array(Type.String(), {
+            description: "List of allowed tools",
+          }),
+        ),
+        resume_session_id: Type.Optional(
+          Type.String({
+            description:
+              "Claude session ID to resume (from a previous session's claudeSessionId). Continues the conversation from where it left off.",
+          }),
+        ),
+        fork_session: Type.Optional(
+          Type.Boolean({
+            description:
+              "When resuming, fork to a new session instead of continuing the existing one. Use with resume_session_id.",
+          }),
+        ),
+        multi_turn: Type.Optional(
+          Type.Boolean({
+            description:
+              "Enable multi-turn mode. The session stays open for follow-up messages via claude_respond. Default: false.",
+          }),
+        ),
+        permission_mode: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("default"),
+              Type.Literal("plan"),
+              Type.Literal("acceptEdits"),
+              Type.Literal("bypassPermissions"),
+            ],
+            {
+              description:
+                "Permission mode for the session. Defaults to plugin config or 'bypassPermissions'.",
+            },
+          ),
+        ),
+        channel: Type.Optional(
+          Type.String({
+            description:
+              'Origin channel for notifications, in "channel:target" format (e.g. "telegram:123456789"). Pass this when calling from an agent tool context so notifications reach the right channel.',
+          }),
+        ),
+      }),
+      async execute(_id: string, params: any) {
+        if (!sessionManager) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: SessionManager not initialized. The claude-code service must be running.",
+              },
+            ],
+          };
+        }
+
+        const workdir = params.workdir || pluginConfig.defaultWorkdir || process.cwd();
+        const maxBudgetUsd = params.max_budget_usd ?? pluginConfig.defaultBudgetUsd ?? 5;
+
+        try {
+          // Resolve resume_session_id: accept name, internal ID, or Claude UUID
+          let resolvedResumeId = params.resume_session_id;
+          if (resolvedResumeId) {
+            const resolved = sessionManager.resolveClaudeSessionId(resolvedResumeId);
+            if (!resolved) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `Error: Could not resolve resume_session_id "${resolvedResumeId}" to a Claude session ID. Use claude_sessions to list available sessions.`,
+                  },
+                ],
+              };
+            }
+            resolvedResumeId = resolved;
+          }
+
+          const session = sessionManager.spawn({
+            prompt: params.prompt,
+            name: params.name,
+            workdir,
+            model: params.model || pluginConfig.defaultModel,
+            maxBudgetUsd,
+            systemPrompt: params.system_prompt,
+            allowedTools: params.allowed_tools,
+            resumeSessionId: resolvedResumeId,
+            forkSession: params.fork_session,
+            multiTurn: params.multi_turn,
+            permissionMode: params.permission_mode,
+            // _id is the tool call ID (e.g. "toolu_xxx"), not a channel ID.
+            // When the agent passes params.channel explicitly, use that;
+            // otherwise resolveOriginChannel falls back to config.
+            originChannel: resolveOriginChannel({ id: _id }, params.channel),
+          });
+
+          const promptSummary =
+            params.prompt.length > 80
+              ? params.prompt.slice(0, 80) + "..."
+              : params.prompt;
+
+          const details = [
+            `Session launched successfully.`,
+            `  Name: ${session.name}`,
+            `  ID: ${session.id}`,
+            `  Dir: ${workdir}`,
+            `  Model: ${session.model ?? "default"}`,
+            `  Prompt: "${promptSummary}"`,
+          ];
+
+          if (params.resume_session_id) {
+            details.push(`  Resume: ${params.resume_session_id}${params.fork_session ? " (forked)" : ""}`);
+          }
+          if (params.multi_turn) {
+            details.push(`  Mode: multi-turn (use claude_respond to send follow-up messages)`);
+          }
+
+          details.push(``);
+          details.push(`Use claude_sessions to check status, claude_output to see output.`);
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: details.join("\n"),
+              },
+            ],
+          };
+        } catch (err: any) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error launching session: ${err.message}`,
+              },
+            ],
+          };
+        }
+      },
+    },
+    { optional: false },
+  );
+}

package/src/tools/claude-output.ts

@@ -0,0 +1,80 @@
+import { Type } from "@sinclair/typebox";
+import { sessionManager, formatDuration } from "../shared";
+
+export function registerClaudeOutputTool(api: any): void {
+  api.registerTool(
+    {
+      name: "claude_output",
+      description: "Show recent output from a Claude Code session (by name or ID).",
+      parameters: Type.Object({
+        session: Type.String({ description: "Session name or ID to get output from" }),
+        lines: Type.Optional(
+          Type.Number({
+            description: "Number of recent lines to show (default 50)",
+          }),
+        ),
+        full: Type.Optional(
+          Type.Boolean({
+            description: "Show all available output",
+          }),
+        ),
+      }),
+      async execute(_id: string, params: any) {
+        if (!sessionManager) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: SessionManager not initialized. The claude-code service must be running.",
+              },
+            ],
+          };
+        }
+
+        const session = sessionManager.resolve(params.session);
+
+        if (!session) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Session "${params.session}" not found.`,
+              },
+            ],
+          };
+        }
+
+        const outputLines = params.full
+          ? session.getOutput()
+          : session.getOutput(params.lines ?? 50);
+
+        const duration = formatDuration(session.duration);
+        const header = [
+          `Session: ${session.name} [${session.id}] | Status: ${session.status.toUpperCase()} | Duration: ${duration}`,
+          `${"─".repeat(60)}`,
+        ].join("\n");
+
+        if (outputLines.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `${header}\n(no output yet)`,
+              },
+            ],
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${header}\n${outputLines.join("\n")}`,
+            },
+          ],
+        };
+      },
+    },
+    { optional: false },
+  );
+}

package/src/tools/claude-respond.ts

@@ -0,0 +1,113 @@
+import { Type } from "@sinclair/typebox";
+import { sessionManager, notificationRouter } from "../shared";
+
+export function registerClaudeRespondTool(api: any): void {
+  api.registerTool(
+    {
+      name: "claude_respond",
+      description:
+        "Send a follow-up message to a running Claude Code session. The session must be running. Works with multi-turn sessions (launched with multi_turn: true) or any running session via SDK streamInput.",
+      parameters: Type.Object({
+        session: Type.String({
+          description: "Session name or ID to respond to",
+        }),
+        message: Type.String({
+          description: "The message to send to the session",
+        }),
+        interrupt: Type.Optional(
+          Type.Boolean({
+            description:
+              "If true, interrupt the current turn before sending the message. Useful to redirect the session mid-response.",
+          }),
+        ),
+      }),
+      async execute(_id: string, params: any) {
+        if (!sessionManager) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: SessionManager not initialized. The claude-code service must be running.",
+              },
+            ],
+          };
+        }
+
+        const session = sessionManager.resolve(params.session);
+
+        if (!session) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Session "${params.session}" not found.`,
+              },
+            ],
+          };
+        }
+
+        if (session.status !== "running") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Session ${session.name} [${session.id}] is not running (status: ${session.status}). Cannot send a message to a non-running session.`,
+              },
+            ],
+          };
+        }
+
+        try {
+          // Optionally interrupt the current turn
+          if (params.interrupt) {
+            await session.interrupt();
+          }
+
+          // Send the message
+          await session.sendMessage(params.message);
+
+          // Display the response in the origin channel so the conversation is visible
+          if (notificationRouter && session.originChannel) {
+            const respondMsg = [
+              `↩️ [${session.name}] Responded:`,
+              params.message,
+            ].join("\n");
+            notificationRouter.emitToChannel(session.originChannel, respondMsg);
+          }
+
+          const msgSummary =
+            params.message.length > 80
+              ? params.message.slice(0, 80) + "..."
+              : params.message;
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `Message sent to session ${session.name} [${session.id}].`,
+                  params.interrupt ? `  (interrupted current turn first)` : "",
+                  `  Message: "${msgSummary}"`,
+                  ``,
+                  `Use claude_output to see the response.`,
+                ]
+                  .filter(Boolean)
+                  .join("\n"),
+              },
+            ],
+          };
+        } catch (err: any) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error sending message: ${err.message}`,
+              },
+            ],
+          };
+        }
+      },
+    },
+    { optional: false },
+  );
+}

package/src/tools/claude-sessions.ts

@@ -0,0 +1,63 @@
+import { Type } from "@sinclair/typebox";
+import { sessionManager, formatSessionListing } from "../shared";
+
+export function registerClaudeSessionsTool(api: any): void {
+  api.registerTool(
+    {
+      name: "claude_sessions",
+      description:
+        "List all Claude Code sessions with their status and progress.",
+      parameters: Type.Object({
+        status: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("all"),
+              Type.Literal("running"),
+              Type.Literal("completed"),
+              Type.Literal("failed"),
+            ],
+            { description: 'Filter by status (default "all")' },
+          ),
+        ),
+      }),
+      async execute(_id: string, params: any) {
+        if (!sessionManager) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: SessionManager not initialized. The claude-code service must be running.",
+              },
+            ],
+          };
+        }
+
+        const filter = params.status || "all";
+        const sessions = sessionManager.list(filter);
+
+        if (sessions.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No sessions found.",
+              },
+            ],
+          };
+        }
+
+        const lines = sessions.map(formatSessionListing);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: lines.join("\n\n"),
+            },
+          ],
+        };
+      },
+    },
+    { optional: false },
+  );
+}