viveworker 0.8.9 → 0.8.10

package/README.md

@@ -218,10 +218,19 @@ If you prefer manual setup, add this to an MCP client:
 Available tools:
 
 - `viveworker_status` checks bridge, pairing, Remote connection, A2A, File Share, and Moltbook status
+- `viveworker_stats` reads package adoption and usage stats
+- `viveworker_share_list` lists File Share uploads and optional usage metrics
+- `viveworker_a2a_activity` reads local A2A activity
+- `viveworker_a2a_card` reads the current local A2A agent card
+- `viveworker_moltbook_list` lists Moltbook inbox comments
+- `viveworker_moltbook_show` reads one Moltbook comment
+- `viveworker_moltbook_thread` reads the thread for one Moltbook comment
 - `viveworker_notify` sends an informational phone notification and timeline entry
 - `viveworker_ask` asks a question on the paired phone and waits for the answer
 - `viveworker_request_approval` asks the phone to approve or reject a proposed action
 - `viveworker_share_file` uploads a workspace file to File Share after phone approval
+- `viveworker_share_replace` replaces the file behind an existing File Share slug after phone approval
+- `viveworker_share_link` mints a short-lived passwordless File Share token URL after phone approval
 - `viveworker_thread_share` shares context into another Codex / Claude / inbox thread
 - `viveworker_send_a2a_task` sends a task to a registered A2A target after phone approval
 
@@ -230,8 +239,9 @@ Available prompts include setup guidance, control-plane usage, risky-action appr
 Security defaults:
 
 - MCP is stdio-only in this release; there is no HTTP MCP server
+- MCP read-only inspection tools use a fixed command allowlist; MCP is not a generic shell or CLI executor
 - file sharing is limited to the current workspace and refuses `.env`, credential directories, private keys, and secret-looking paths
-- File Share and A2A task sending require phone approval
+- File Share uploads/replacements and A2A task sending require phone approval
 - MCP tool calls are recorded locally with `provider: "mcp"`
 - prompts, message bodies, file contents, file paths, command text, tokens, public keys, and IP addresses are not sent to central analytics
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viveworker",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "description": "Mobile control plane for AI agents. Approve, answer, and hand off work for Codex, Claude, MCP-ready tools, and A2A from one phone.",
   "author": "Yuta Hoshino <hoshino.lireneo@gmail.com>",
   "license": "MIT",

package/plugins/viveworker-control-plane/skills/viveworker-control-plane/SKILL.md

@@ -37,7 +37,12 @@ Use this flow when the user says "set up viveworker", "pair my phone", "vivework
 - Use `viveworker_ask` for a short user decision that blocks progress.
 - Use `viveworker_request_approval` before risky, external, irreversible, payment-related, or user-visible actions.
 - Use `viveworker_notify` for informational updates that should appear on the phone and timeline.
+- Use `viveworker_stats` for package adoption or usage stats.
+- Use `viveworker_share_list` to inspect File Share uploads or usage metrics.
+- Use `viveworker_a2a_activity` or `viveworker_a2a_card` to inspect A2A activity or local agent-card settings.
+- Use `viveworker_moltbook_list`, `viveworker_moltbook_show`, or `viveworker_moltbook_thread` to inspect Moltbook inbox comments or threads.
 - Use `viveworker_share_file` when a local deliverable should become a limited File Share URL.
+- Use `viveworker_share_replace` when an existing File Share slug should point at a new file.
 - Use `viveworker_thread_share` when context should move to another Codex / Claude / inbox thread.
 - Use `viveworker_send_a2a_task` when the user asks to delegate to a registered A2A target.
 
@@ -47,7 +52,8 @@ Use this flow when the user says "set up viveworker", "pair my phone", "vivework
 - Treat timeout, rejection, or missing response as not approved.
 - Do not send secrets, private keys, `.env` content, credentials, relay tokens, public keys, or unnecessary file contents through MCP.
 - Do not use MCP as a shell executor. It creates control-plane events; it should not run arbitrary commands.
-- Do not upload files through File Share without phone approval.
+- Read-only inspection tools use fixed command allowlists and must not mutate local state.
+- Do not upload or replace files through File Share without phone approval.
 - Use registered A2A target aliases only. Do not inline API keys.
 
 ## Natural language triggers

package/scripts/mcp-server.mjs

@@ -127,7 +127,7 @@ class ViveworkerMcpServer {
         websiteUrl: "https://viveworker.com",
       },
       instructions:
-        "Use viveworker tools when you need to notify, ask, request approval, share a file, hand off context, or delegate an A2A task through the user's paired mobile control plane.",
+        "Use viveworker tools when you need to inspect viveworker state, notify, ask, request approval, share a file, hand off context, or delegate an A2A task through the user's paired mobile control plane.",
     };
   }
 }
@@ -138,6 +138,20 @@ async function callTool(params) {
   switch (name) {
     case "viveworker_status":
       return toolOk(await bridgeEvent({ eventType: "status" }, SHORT_TIMEOUT_MS));
+    case "viveworker_stats":
+      return toolOk(await toolStats(args));
+    case "viveworker_share_list":
+      return toolOk(await toolShareList(args));
+    case "viveworker_a2a_activity":
+      return toolOk(await toolA2AActivity(args));
+    case "viveworker_a2a_card":
+      return toolOk(await toolA2ACard(args));
+    case "viveworker_moltbook_list":
+      return toolOk(await toolMoltbookList(args));
+    case "viveworker_moltbook_show":
+      return toolOk(await toolMoltbookShow(args));
+    case "viveworker_moltbook_thread":
+      return toolOk(await toolMoltbookThread(args));
     case "viveworker_notify":
       return toolOk(await toolNotify(args));
     case "viveworker_ask":
@@ -146,6 +160,8 @@ async function callTool(params) {
       return toolOk(await toolRequestApproval(args));
     case "viveworker_share_file":
       return toolOk(await toolShareFile(args));
+    case "viveworker_share_replace":
+      return toolOk(await toolShareReplace(args));
     case "viveworker_share_link":
       return toolOk(await toolShareLink(args));
     case "viveworker_thread_share":
@@ -157,6 +173,52 @@ async function callTool(params) {
   }
 }
 
+async function toolStats(args) {
+  const pkg = optionalString(args.pkg || args.packageName);
+  const cliArgs = ["stats", "--json"];
+  if (pkg) {
+    assertSafeNpmPackageName(pkg);
+    cliArgs.push("--pkg", pkg);
+  }
+  return runViveworkerCliJson(cliArgs, 60_000);
+}
+
+async function toolShareList(args) {
+  const cliArgs = ["share", "list", "--json"];
+  if (optionalBoolean(args.metrics)) {
+    cliArgs.push("--metrics");
+  }
+  return runViveworkerCliJson(cliArgs, 45_000);
+}
+
+async function toolA2AActivity(_args) {
+  return runViveworkerCliJson(["a2a", "activity"], 30_000);
+}
+
+async function toolA2ACard(_args) {
+  const output = await runViveworkerCliText(["a2a", "card"], 30_000);
+  return { ok: true, output: output.stdout.trim() };
+}
+
+async function toolMoltbookList(args) {
+  const cliArgs = ["moltbook", "list"];
+  if (optionalBoolean(args.all)) {
+    cliArgs.push("--all");
+  }
+  const output = await runViveworkerCliText(cliArgs, 30_000);
+  return { ok: true, output: output.stdout.trim() };
+}
+
+async function toolMoltbookShow(args) {
+  const commentId = requiredSafeIdentifier(args.commentId, "commentId");
+  return runViveworkerCliJson(["moltbook", "show", commentId], 30_000);
+}
+
+async function toolMoltbookThread(args) {
+  const commentId = requiredSafeIdentifier(args.commentId, "commentId");
+  return runViveworkerCliJson(["moltbook", "thread", commentId], 45_000);
+}
+
 async function toolNotify(args) {
   const title = requiredString(args.title, "title");
   const message = requiredString(args.message, "message");
@@ -245,11 +307,46 @@ async function toolShareFile(args) {
   return { approved: true, share: upload, tokenizedLink: link };
 }
 
-async function toolShareLink(args) {
-  const slug = requiredString(args.slug, "slug");
-  if (!/^[A-Za-z0-9]+$/.test(slug)) {
-    throw rpcInvalidParams("slug must contain only letters and numbers");
+async function toolShareReplace(args) {
+  const slug = requiredShareSlug(args.slug);
+  const requestedPath = requiredString(args.path, "path");
+  const workspaceRoot = optionalString(args.workspaceRoot) || process.env.VIVEWORKER_MCP_WORKSPACE_ROOT || process.cwd();
+  const file = await validateSharePath(requestedPath, workspaceRoot, "share_replace");
+  const stat = await fs.stat(file.realPath);
+  const expiresDays = optionalString(args.expiresDays ?? args["expires-days"]);
+  const noOptimize = optionalBoolean(args.noOptimize ?? args["no-optimize"]);
+  const approval = await bridgeEvent({
+    eventType: "approval_request",
+    title: "Replace viveworker File Share file",
+    message: [
+      "An MCP client wants to replace the file behind an existing viveworker File Share URL.",
+      "",
+      `Share slug: ${slug}`,
+      `New file: ${file.displayPath}`,
+      `Size: ${stat.size} bytes`,
+      expiresDays ? `Expires days: ${expiresDays}` : "Expires days: keep existing/default",
+      noOptimize ? "HTML optimization: disabled for this replace" : "",
+      "",
+      "This changes what existing recipients see at the same share link.",
+      "Approve only if this replacement file is safe to send outside this Mac.",
+    ].filter(Boolean).join("\n"),
+    approvalKind: "file_share_replace",
+    fileRefs: [file.displayPath],
+    timeoutMs: clampTimeout(args.timeoutMs),
+  }, clampTimeout(args.timeoutMs));
+  if (!approval.approved) {
+    return { approved: false, decision: approval.decision || "rejected" };
   }
+
+  const replaceArgs = ["share", "replace", slug, file.realPath, "--json"];
+  if (expiresDays) replaceArgs.push("--expires-days", expiresDays);
+  if (noOptimize) replaceArgs.push("--no-optimize");
+  const replace = await runViveworkerCliJson(replaceArgs, 90_000);
+  return { approved: true, share: replace };
+}
+
+async function toolShareLink(args) {
+  const slug = requiredShareSlug(args.slug);
   const password = requiredString(args.password, "password");
   if (password.length > 256) {
     throw rpcInvalidParams("password is too long (max 256 characters)");
@@ -424,7 +521,7 @@ function httpJson(endpoint, options) {
   });
 }
 
-async function validateSharePath(filePath, workspaceRoot) {
+async function validateSharePath(filePath, workspaceRoot, toolName = "share_file") {
   const root = path.resolve(String(workspaceRoot || ""));
   const candidate = path.resolve(String(filePath || ""));
   const [rootReal, fileReal] = await Promise.all([
@@ -433,16 +530,16 @@ async function validateSharePath(filePath, workspaceRoot) {
   ]);
   const rel = path.relative(rootReal, fileReal);
   if (rel.startsWith("..") || path.isAbsolute(rel)) {
-    throw new Error("share_file is limited to the current workspace root");
+    throw new Error(`${toolName} is limited to the current workspace root`);
   }
   const stat = await fs.stat(fileReal);
   if (!stat.isFile()) {
-    throw new Error("share_file path must be a regular file");
+    throw new Error(`${toolName} path must be a regular file`);
   }
   assertNotSensitivePath(rel || path.basename(fileReal));
   const ext = path.extname(fileReal).toLowerCase();
   if (!SHARE_FILE_EXTENSIONS.has(ext)) {
-    throw new Error(`share_file accepts only ${Array.from(SHARE_FILE_EXTENSIONS).join(" / ")} files. Got: ${ext || "(no extension)"}`);
+    throw new Error(`${toolName} accepts only ${Array.from(SHARE_FILE_EXTENSIONS).join(" / ")} files. Got: ${ext || "(no extension)"}`);
   }
   return {
     realPath: fileReal,
@@ -476,7 +573,16 @@ function assertNotSensitivePath(relPath) {
   }
 }
 
-function runViveworkerCliJson(args, timeoutMs) {
+async function runViveworkerCliJson(args, timeoutMs) {
+  const { stdout } = await runViveworkerCliText(args, timeoutMs);
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    throw new Error(`viveworker CLI returned non-JSON: ${stdout.slice(0, 200)}`);
+  }
+}
+
+function runViveworkerCliText(args, timeoutMs) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [viveworkerCli, ...args], {
       cwd: packageRoot,
@@ -502,11 +608,7 @@ function runViveworkerCliJson(args, timeoutMs) {
         reject(new Error((stderr || stdout || `viveworker CLI failed with code ${code}`).trim()));
         return;
       }
-      try {
-        resolve(JSON.parse(stdout));
-      } catch {
-        reject(new Error(`viveworker CLI returned non-JSON: ${stdout.slice(0, 200)}`));
-      }
+      resolve({ stdout, stderr });
     });
   });
 }
@@ -657,6 +759,29 @@ function slugFromShareUrl(value) {
   }
 }
 
+function assertSafeNpmPackageName(value) {
+  const text = optionalString(value);
+  if (!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u.test(text)) {
+    throw rpcInvalidParams("pkg must be a valid npm package name");
+  }
+}
+
+function requiredSafeIdentifier(value, name) {
+  const text = requiredString(value, name);
+  if (!/^[A-Za-z0-9._:-]{1,160}$/u.test(text)) {
+    throw rpcInvalidParams(`${name} contains unsupported characters`);
+  }
+  return text;
+}
+
+function requiredShareSlug(value) {
+  const slug = requiredString(value, "slug");
+  if (!/^[A-Za-z0-9]+$/.test(slug)) {
+    throw rpcInvalidParams("slug must contain only letters and numbers");
+  }
+  return slug;
+}
+
 async function createShareTokenLink(slug, password, ttlHours) {
   const linkArgs = ["share", "link", slug, "--password", password, "--json"];
   if (ttlHours !== undefined) {
@@ -808,6 +933,87 @@ const TOOLS = [
     description: "Return bridge, pairing, remote connection, A2A, and File Share status.",
     inputSchema: { type: "object", additionalProperties: false },
   },
+  {
+    name: "viveworker_stats",
+    title: "Read viveworker stats",
+    description: "Read viveworker package adoption and usage stats. Read-only.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        pkg: { type: "string" },
+      },
+    },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "viveworker_share_list",
+    title: "List File Share uploads",
+    description: "List File Share uploads and optionally include usage metrics. Read-only.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        metrics: { type: "boolean" },
+      },
+    },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "viveworker_a2a_activity",
+    title: "Read A2A activity",
+    description: "Read local A2A activity from the default viveworker state. Read-only.",
+    inputSchema: { type: "object", additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "viveworker_a2a_card",
+    title: "Read A2A card",
+    description: "Read the current local A2A agent card settings. Read-only.",
+    inputSchema: { type: "object", additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "viveworker_moltbook_list",
+    title: "List Moltbook inbox",
+    description: "List Moltbook inbox comments. Read-only.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        all: { type: "boolean" },
+      },
+    },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "viveworker_moltbook_show",
+    title: "Read Moltbook comment",
+    description: "Show one Moltbook comment by commentId. Read-only.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        commentId: { type: "string" },
+      },
+      required: ["commentId"],
+    },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "viveworker_moltbook_thread",
+    title: "Read Moltbook thread",
+    description: "Show the Moltbook thread for one commentId. Read-only.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        commentId: { type: "string" },
+      },
+      required: ["commentId"],
+    },
+    annotations: { readOnlyHint: true },
+  },
   {
     name: "viveworker_notify",
     title: "Notify phone",
@@ -893,6 +1099,24 @@ const TOOLS = [
       required: ["path"],
     },
   },
+  {
+    name: "viveworker_share_replace",
+    title: "Replace File Share file",
+    description: "After phone approval, replace the file behind an existing viveworker File Share slug.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        slug: { type: "string" },
+        path: { type: "string" },
+        workspaceRoot: { type: "string" },
+        expiresDays: { type: "string" },
+        noOptimize: { type: "boolean" },
+        timeoutMs: { type: "number" },
+      },
+      required: ["slug", "path"],
+    },
+  },
   {
     name: "viveworker_share_link",
     title: "Create File Share token URL",
@@ -977,7 +1201,7 @@ const PROMPTS = [
       title: "Share deliverable",
       description: "Package a local deliverable through viveworker File Share with phone approval.",
     },
-    text: "When the user asks to share a report, prototype, screenshot, CSV, or standalone HTML deliverable, use viveworker_share_file. Only share files inside the workspace and never share secrets or credentials. If the user wants a password-protected share but the recipient should not know the password, set password plus tokenize=true, or use viveworker_share_link for an existing password-protected slug to mint a short-lived ?t= URL.",
+    text: "When the user asks to share a report, prototype, screenshot, CSV, or standalone HTML deliverable, use viveworker_share_file. When the user asks to replace the file behind an existing File Share slug, use viveworker_share_replace. Only share files inside the workspace and never share secrets or credentials. If the user wants a password-protected share but the recipient should not know the password, set password plus tokenize=true, or use viveworker_share_link for an existing password-protected slug to mint a short-lived ?t= URL.",
   },
   {
     definition: {

package/scripts/viveworker-bridge.mjs

@@ -1803,11 +1803,6 @@ function unwrapShellCommand(commandText) {
     .trim();
 }
 
-function extractCommandLineFromFunctionOutput(outputText) {
-  const match = String(outputText || "").match(/^Command:\s+(.+)$/mu);
-  return unwrapShellCommand(match?.[1] || "");
-}
-
 function parseToolArgumentsJson(value) {
   if (isPlainObject(value)) {
     return value;
@@ -1864,16 +1859,21 @@ function redactTimelineCommandText(commandText) {
     .replace(/\b([A-Z0-9_]*(?:API_KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)[A-Z0-9_]*=)(["']?)[^\s"']+\2/giu, "$1[redacted]");
 }
 
+function escapeMarkdownCodeFenceBody(text) {
+  return cleanText(text || "").replace(/```/gu, "\\`\\`\\`");
+}
+
 function timelineCommandMessage(locale, { commandText = "", toolName = "", fileRefs = [] } = {}) {
+  const safeCommandText = escapeMarkdownCodeFenceBody(redactTimelineCommandText(commandText));
   const commandBlock = commandText
-    ? `${t(locale, "server.message.commandLabel")}\n\`\`\`sh\n${redactTimelineCommandText(commandText)}\n\`\`\``
+    ? `${t(locale, "server.message.commandLabel")}\n\`\`\`sh\n${safeCommandText}\n\`\`\``
     : "";
   const toolBlock = !commandBlock && toolName
-    ? `${t(locale, "server.message.toolLabel")}\n\`\`\`text\n${cleanText(toolName)}\n\`\`\``
+    ? `${t(locale, "server.message.toolLabel")}\n\`\`\`text\n${escapeMarkdownCodeFenceBody(toolName)}\n\`\`\``
     : "";
   const files = normalizeTimelineFileRefs(fileRefs);
   const filesBlock = files.length
-    ? `${t(locale, "server.message.filesLabel")}\n\`\`\`text\n${files.join("\n")}\n\`\`\``
+    ? `${t(locale, "server.message.filesLabel")}\n\`\`\`text\n${files.map(escapeMarkdownCodeFenceBody).join("\n")}\n\`\`\``
     : "";
   return [commandBlock || toolBlock, filesBlock].filter(Boolean).join("\n\n");
 }
@@ -2003,7 +2003,7 @@ function sedCommandPathArgs(tokens) {
 function autoPilotApprovalMessage(locale, commandText) {
   const prefix = t(locale, "server.message.autoPilotTrustedReadApproved");
   const commandBlock = cleanText(commandText || "")
-    ? `${t(locale, "server.message.commandLabel")}\n\`\`\`sh\n${cleanText(commandText || "")}\n\`\`\``
+    ? `${t(locale, "server.message.commandLabel")}\n\`\`\`sh\n${escapeMarkdownCodeFenceBody(commandText)}\n\`\`\``
     : "";
   return [prefix, commandBlock].filter(Boolean).join("\n\n");
 }
@@ -7080,11 +7080,6 @@ async function buildRolloutFileTimelineEntries({ config, record, fileState, runt
       });
       return [];
     }
-    const commandText = extractCommandLineFromFunctionOutput(payload.output ?? "");
-    if (!commandText) {
-      return [];
-    }
-    const classified = classifyTimelineCommand(commandText);
     upsertTimelineActivity({
       config,
       runtime,
@@ -7096,19 +7091,7 @@ async function buildRolloutFileTimelineEntries({ config, record, fileState, runt
       source: "codex-tool-output",
       atMs: createdAtMs,
     });
-    return [
-      buildToolTimelineEntry({
-        provider: "codex",
-        threadId,
-        threadLabel,
-        callId,
-        createdAtMs,
-        fileEventType: classified.fileEventType,
-        commandText: classified.commandText || commandText,
-        fileRefs: classified.fileRefs,
-        cwd: fileState.cwd || "",
-      }),
-    ].filter(Boolean);
+    return [];
   }
 
   if (payloadType === "custom_tool_call_output") {
@@ -11033,7 +11016,7 @@ function formatCommandApprovalMessage(params, locale = config?.defaultLocale ||
     parts.push(t(locale, "server.message.commandApprovalNeeded"));
   }
   if (command) {
-    parts.push(`${t(locale, "server.message.commandLabel")}\n\`\`\`sh\n${command}\n\`\`\``);
+    parts.push(`${t(locale, "server.message.commandLabel")}\n\`\`\`sh\n${escapeMarkdownCodeFenceBody(command)}\n\`\`\``);
   }
   return parts.join("\n\n") || t(locale, "server.message.commandApprovalNeeded");
 }

package/scripts/viveworker-claude-hook.mjs

@@ -148,7 +148,7 @@ async function handlePermissionRequest() {
   } else if (toolName === "Bash") {
     approvalKind = "command";
     const cmd = String(toolInput.command || "");
-    messageText = `Command approval needed.\n\`\`\`\n${cmd.slice(0, 500)}\n\`\`\``;
+    messageText = `Command approval needed.\n\`\`\`\n${escapeMarkdownCodeFenceBody(cmd.slice(0, 500))}\n\`\`\``;
   } else if (toolName === "ExitPlanMode") {
     approvalKind = "plan";
     messageText = "Plan approval needed.";
@@ -708,6 +708,10 @@ function sanitizeForPath(s) {
   return s.replace(/[^a-zA-Z0-9_-]/gu, "_").slice(0, 64);
 }
 
+function escapeMarkdownCodeFenceBody(text) {
+  return String(text || "").replace(/```/gu, "\\`\\`\\`");
+}
+
 function encodeFilePathForSnapshot(filePath) {
   return filePath.replace(/[/\\]/gu, "_") + ".snap";
 }

package/skills/viveworker-control-plane/SKILL.md

@@ -34,9 +34,14 @@ Keep onboarding calm and step-by-step. Do not make the user debug config files u
 ## Tool Selection
 
 - Use `viveworker_notify` for informational milestones that should appear on the phone or timeline, such as "build finished", "review ready", or "agent is blocked".
+- Use `viveworker_stats` when the user asks for viveworker package adoption or usage stats.
+- Use `viveworker_share_list` when the user asks what is currently in File Share or asks for share usage metrics.
+- Use `viveworker_a2a_activity` or `viveworker_a2a_card` when troubleshooting A2A activity or local agent-card settings.
+- Use `viveworker_moltbook_list`, `viveworker_moltbook_show`, or `viveworker_moltbook_thread` when inspecting Moltbook inbox comments or threads.
 - Use `viveworker_ask` when the next step depends on a human preference, missing requirement, or choice that should not be guessed.
 - Use `viveworker_request_approval` before actions that are externally visible, hard to undo, risky, sensitive, delegated, paid, or likely to surprise the user.
 - Use `viveworker_share_file` when the user wants a workspace deliverable shared as a limited File Share URL. Good fits include `.html`, `.htm`, `.pdf`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, and `.csv`.
+- Use `viveworker_share_replace` when the user wants to replace or update the file behind an existing File Share slug.
 - Use `viveworker_thread_share` when context should move to another Codex session, Claude session, or viveworker inbox while preserving a human-visible handoff.
 - Use `viveworker_send_a2a_task` only for registered A2A target aliases and bounded tasks with clear acceptance criteria.
 
@@ -47,10 +52,12 @@ Keep onboarding calm and step-by-step. Do not make the user debug config files u
 - Include relevant file refs, but never include secrets, tokens, private keys, or unnecessary file contents.
 - Treat timeout, rejection, or transport failure as "not approved". Do not continue as if approval was granted.
 - After the tool returns, summarize the decision or returned artifact to the user.
+- Read-only inspection tools use fixed command allowlists. Do not try to route arbitrary shell commands or side-effectful viveworker CLI actions through MCP.
 
 ## File Share Rules
 
 - Share only files inside the workspace root.
+- Replacing an existing share changes what existing recipients see at that URL; require phone approval and make that consequence clear.
 - Do not share `.env`, credential files, private keys, `.ssh`, `.aws`, `.gnupg`, or secret-looking paths.
 - Prefer sharing final deliverables, not internal source files, unless the user explicitly asks.
 - For unsupported file types, explain the accepted types and suggest exporting to HTML, PDF, image, or CSV first.

package/templates/CLAUDE.viveworker.md

@@ -23,10 +23,18 @@ Then restart the Claude Code session. If the tools are not available, ask the us
 ## Tools
 
 - `viveworker_status` checks bridge, pairing, Remote connection, A2A, File Share, and Moltbook state.
+- `viveworker_stats` reads package adoption and usage stats.
+- `viveworker_share_list` lists File Share uploads and optional usage metrics.
+- `viveworker_a2a_activity` reads local A2A activity.
+- `viveworker_a2a_card` reads the current local A2A agent card.
+- `viveworker_moltbook_list` lists Moltbook inbox comments.
+- `viveworker_moltbook_show` reads one Moltbook comment.
+- `viveworker_moltbook_thread` reads the thread for one Moltbook comment.
 - `viveworker_notify` sends an informational phone notification and records a timeline entry.
 - `viveworker_ask` asks the paired phone a question and waits for the answer.
 - `viveworker_request_approval` asks the phone to approve or reject a proposed action.
 - `viveworker_share_file` uploads a workspace file to File Share after phone approval. For password-protected handoff, pass `tokenize: true` to return a short-lived passwordless `?t=` URL.
+- `viveworker_share_replace` replaces the file behind an existing File Share slug after phone approval.
 - `viveworker_share_link` mints a short-lived passwordless `?t=` URL for an existing password-protected File Share slug after phone approval.
 - `viveworker_thread_share` shares context into another Codex / Claude / inbox thread.
 - `viveworker_send_a2a_task` sends a task to a registered A2A target after phone approval.
@@ -36,9 +44,11 @@ Then restart the Claude Code session. If the tools are not available, ask the us
 - If the user says "ask me on my phone", "スマホに聞いて", or a short decision blocks progress, use `viveworker_ask`.
 - If the user asks you to proceed with a risky, external, irreversible, payment-related, or user-visible action, use `viveworker_request_approval`.
 - If the user asks for a report, prototype, screenshot, PDF, CSV, or standalone HTML to become a shareable link, use `viveworker_share_file`.
+- If the user asks to replace or update the file at an existing File Share link, use `viveworker_share_replace`.
 - If the user asks for a password-protected share but wants the recipient to open it without knowing the password, use `viveworker_share_file` with `password` and `tokenize: true`, or use `viveworker_share_link` for an existing slug.
 - If the user says "share this with Codex/Claude", "Aの内容をBに共有して", or wants context handed to another session, use `viveworker_thread_share`.
 - If the user wants another registered agent to do work, use `viveworker_send_a2a_task`.
+- For troubleshooting or inspection, prefer the read-only MCP tools above before asking the user to run CLI commands.
 
 ## Prompting rules
 
@@ -64,6 +74,7 @@ Claude may not automatically notice newly shared messages from another session.
 
 - MCP is a control-plane surface, not a shell executor.
 - Do not run shell strings through MCP.
-- File Share and A2A task sending require phone approval.
+- Read-only inspection tools use fixed command allowlists and should not be used to mutate local state.
+- File Share uploads/replacements and A2A task sending require phone approval.
 - Use registered A2A aliases only; do not ask the user to paste API keys into prompts.
 - Prefer `viveworker_status` before troubleshooting a missing notification, stale pairing, or remote connectivity issue.