@gethmy/mcp 2.8.1 → 2.8.3

package/dist/cli.js

@@ -1121,6 +1121,87 @@ function getDisplayLinkType(linkType, direction) {
     return linkType;
   return LINK_TYPE_INVERSES[linkType];
 }
+// ../harmony-shared/dist/commentSerializer.js
+var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function authorLabel(c) {
+  if (c.author_type === "agent")
+    return "AI agent";
+  return c.author?.full_name || c.author?.email || "teammate";
+}
+function criticalIds(comments) {
+  const keep = new Set;
+  for (const c of comments) {
+    if (c.comment_type === "decision")
+      keep.add(c.id);
+    if (c.supersedes_id) {
+      keep.add(c.id);
+      keep.add(c.supersedes_id);
+    }
+    if (c.confirms_id) {
+      keep.add(c.id);
+      keep.add(c.confirms_id);
+    }
+  }
+  return keep;
+}
+function serializeCommentThread(comments, options = {}) {
+  const { heading = "Conversation", includeInstructions = true, activity = [], maxComments } = options;
+  const visible = comments.filter((c) => !c.deleted_at).slice().sort((a, b) => a.created_at.localeCompare(b.created_at));
+  if (visible.length === 0)
+    return "";
+  const indexById = new Map;
+  visible.forEach((c, i) => {
+    indexById.set(c.id, i + 1);
+  });
+  let rendered = visible;
+  let elidedCount = 0;
+  if (maxComments && visible.length > maxComments) {
+    const keep = criticalIds(visible);
+    const recentThreshold = visible.length - maxComments;
+    rendered = visible.filter((c, i) => i >= recentThreshold || keep.has(c.id));
+    elidedCount = visible.length - rendered.length;
+  }
+  const ref = (id) => {
+    const n = indexById.get(id);
+    return n ? `#${n}` : `#${id.slice(0, 8)}`;
+  };
+  const lines = [];
+  if (elidedCount > 0) {
+    lines.push({
+      at: visible[0]?.created_at ?? "",
+      text: `(${elidedCount} earlier comment(s) omitted for brevity)`
+    });
+  }
+  for (const c of rendered) {
+    const tags = [];
+    if (c.edited_at)
+      tags.push("edited");
+    if (c.supersedes_id)
+      tags.push(`supersedes ${ref(c.supersedes_id)}`);
+    if (c.confirms_id)
+      tags.push(`confirms ${ref(c.confirms_id)}`);
+    if (c.resolved_at)
+      tags.push("resolved");
+    const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
+    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
+    lines.push({ at: c.created_at, text: `${header}
+${c.body.trim()}` });
+  }
+  for (const a of activity) {
+    const actor = a.actor ? `${a.actor} ` : "";
+    lines.push({ at: a.at, text: `· (system) ${a.at} — ${actor}${a.text}` });
+  }
+  lines.sort((a, b) => a.at.localeCompare(b.at));
+  const body = lines.map((l) => l.text).join(`
+
+`);
+  const instruction = includeInstructions ? `
+
+${CONFLICT_INSTRUCTION}` : "";
+  return `## ${heading} (oldest → newest)
+
+${body}${instruction}`;
+}
 // ../harmony-shared/dist/constants.js
 var TIMINGS = {
   SEARCH_DEBOUNCE: 300,
@@ -1473,6 +1554,28 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async addComment(cardId, body, opts) {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId
+    });
+  }
+  async getComments(cardId, opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit != null)
+      qs.set("limit", String(opts.limit));
+    if (opts?.offset != null)
+      qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+  async updateComment(commentId, updates) {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
   async startAgentSession(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1830,6 +1933,24 @@ class HarmonyApiClient {
       assembledContext: assembledContextStr,
       assemblyId
     });
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments, {
+          heading: "Comments",
+          maxComments: 40
+        });
+        if (section)
+          result.prompt = `${result.prompt}
+
+${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
     try {
       await this.recordPromptHistory({
         cardId: cardData.id,
@@ -3132,6 +3253,66 @@ var TOOLS = {
       required: ["subtaskId"]
     }
   },
+  harmony_add_comment: {
+    description: "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID to comment on" },
+        body: { type: "string", description: "Comment body (Markdown)" },
+        commentType: {
+          type: "string",
+          enum: [
+            "message",
+            "progress",
+            "question",
+            "blocker",
+            "decision",
+            "summary",
+            "finding"
+          ],
+          description: "Type of comment. 'question'/'blocker' signal you need a human; default 'message'."
+        },
+        supersedesId: {
+          type: "string",
+          description: "Comment id this comment corrects/updates"
+        },
+        confirmsId: {
+          type: "string",
+          description: "Comment id this comment reaffirms"
+        }
+      },
+      required: ["cardId", "body"]
+    }
+  },
+  harmony_get_comments: {
+    description: "Get the comment thread on a card (oldest → newest). Returns human + agent comments with author, type, edited/resolved state, and supersede/confirm links. Read this before acting so you weigh later comments over earlier ones they contradict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string" },
+        limit: { type: "number" },
+        offset: { type: "number" }
+      },
+      required: ["cardId"]
+    }
+  },
+  harmony_update_comment: {
+    description: "Update one of your own comments: edit the body, pin it, or resolve a question/blocker once it has been answered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        commentId: { type: "string" },
+        body: { type: "string" },
+        pinned: { type: "boolean" },
+        resolve: {
+          type: "boolean",
+          description: "Mark (true) or clear (false) the resolved state"
+        }
+      },
+      required: ["commentId"]
+    }
+  },
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
     inputSchema: {
@@ -4393,6 +4574,49 @@ async function handleToolCall(name, args, deps) {
       await client3.deleteSubtask(subtaskId);
       return { success: true };
     }
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(1e4).parse(args.body);
+      const commentType = args.commentType !== undefined ? z.enum([
+        "message",
+        "progress",
+        "question",
+        "blocker",
+        "decision",
+        "summary",
+        "finding"
+      ]).parse(args.commentType) : undefined;
+      const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
+      const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
+      const result = await client3.addComment(cardId, body, {
+        commentType,
+        supersedesId,
+        confirmsId
+      });
+      return { success: true, ...result };
+    }
+    case "harmony_get_comments": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const limit = args.limit !== undefined ? z.number().int().min(1).max(500).parse(args.limit) : undefined;
+      const offset = args.offset !== undefined ? z.number().int().min(0).parse(args.offset) : undefined;
+      const result = await client3.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates = {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(1e4).parse(args.body);
+      }
+      if (args.pinned !== undefined) {
+        updates.pinned = z.boolean().parse(args.pinned);
+      }
+      if (args.resolve !== undefined) {
+        updates.resolve = z.boolean().parse(args.resolve);
+      }
+      const result = await client3.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
     case "harmony_list_workspaces": {
       const result = await client3.listWorkspaces();
       return { success: true, ...result };
@@ -6133,9 +6357,10 @@ function appendToToml(filePath, section, content, options = {}) {
   }
   try {
     const existing = readFileSync6(filePath, "utf-8");
-    if (existing.includes(section)) {
+    if (existing.includes(`[${section}]`)) {
       if (options.force) {
-        const updated = existing.replace(new RegExp(`\\[${section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\][\\s\\S]*?(?=\\[|$)`), content.trim() + `
+        const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const updated = existing.replace(new RegExp(`(?:#[^\\n]*\\n)*\\[${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`), content.trim() + `
 
 `);
         writeFileSync4(filePath, updated, { mode: 420 });
@@ -6209,6 +6434,53 @@ function getWriteSummary(files, options = {}) {
 }
 
 // src/tui/setup.ts
+var SAFE_HARMONY_TOOLS = [
+  "harmony_get_card",
+  "harmony_get_card_by_short_id",
+  "harmony_search_cards",
+  "harmony_get_board",
+  "harmony_get_context",
+  "harmony_list_projects",
+  "harmony_list_workspaces",
+  "harmony_get_card_links",
+  "harmony_get_card_attachments",
+  "harmony_get_card_external_links",
+  "harmony_get_comments",
+  "harmony_get_plan",
+  "harmony_list_plans",
+  "harmony_get_agent_session",
+  "harmony_get_workspace_members",
+  "harmony_resolve_links",
+  "harmony_recall",
+  "harmony_memory_search",
+  "harmony_generate_prompt",
+  "harmony_create_card",
+  "harmony_update_card",
+  "harmony_move_card",
+  "harmony_assign_card",
+  "harmony_create_subtask",
+  "harmony_toggle_subtask",
+  "harmony_add_label_to_card",
+  "harmony_remove_label_from_card",
+  "harmony_create_label",
+  "harmony_add_comment",
+  "harmony_update_comment",
+  "harmony_add_link_to_card",
+  "harmony_remove_link_from_card",
+  "harmony_start_agent_session",
+  "harmony_update_agent_progress",
+  "harmony_end_agent_session",
+  "harmony_set_project_context",
+  "harmony_set_workspace_context",
+  "harmony_create_plan",
+  "harmony_update_plan",
+  "harmony_advance_plan",
+  "harmony_remember",
+  "harmony_relate",
+  "harmony_update_memory",
+  "harmony_process_command",
+  "harmony_sync"
+];
 var GLOBAL_SKILLS_DIR = join7(homedir6(), ".agents", "skills");
 var API_URL = "https://app.gethmy.com/api";
 async function registerMcpServer() {
@@ -6231,9 +6503,7 @@ async function writeMcpConfigFallback(home) {
   }
   let settings = {};
   if (existsSync9(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
-    } catch {}
+    settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
   }
   const mcpServers = settings.mcpServers || {};
   mcpServers.harmony = {
@@ -6243,6 +6513,31 @@ async function writeMcpConfigFallback(home) {
   settings.mcpServers = mcpServers;
   writeFileSync5(settingsPath, JSON.stringify(settings, null, 2));
 }
+async function allowlistHarmonyTools(home, allowAll) {
+  const { readFileSync: readFileSync7, writeFileSync: writeFileSync5, mkdirSync: mkdirSync6, existsSync: existsSync9 } = await import("node:fs");
+  const settingsPath = join7(home, ".claude", "settings.json");
+  const settingsDir = dirname3(settingsPath);
+  if (!existsSync9(settingsDir)) {
+    mkdirSync6(settingsDir, { recursive: true });
+  }
+  let settings = {};
+  if (existsSync9(settingsPath)) {
+    settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
+  }
+  const permissions = settings.permissions || {};
+  const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
+  const hasBlanket = allow.includes("mcp__harmony") || allow.includes("mcp__harmony__*");
+  const wanted = allowAll ? ["mcp__harmony"] : SAFE_HARMONY_TOOLS.map((t) => `mcp__harmony__${t}`);
+  const missing = hasBlanket ? [] : wanted.filter((r) => !allow.includes(r));
+  if (missing.length === 0) {
+    return "already";
+  }
+  allow.push(...missing);
+  permissions.allow = allow;
+  settings.permissions = permissions;
+  writeFileSync5(settingsPath, JSON.stringify(settings, null, 2));
+  return "added";
+}
 async function validateApiKey(apiKey, apiUrl = API_URL) {
   try {
     const response = await fetch(`${apiUrl}/v1/workspaces`, {
@@ -7007,6 +7302,26 @@ async function runSetup(options = {}) {
       }
     }
   }
+  if (claudeDetected || selectedAgents.includes("claude")) {
+    const allowAll = options.allowAllTools === true;
+    const message = allowAll ? "Allowlist EVERY Harmony tool without confirmation, including destructive ones (delete/archive/api-key/invite)?" : "Allowlist common Harmony tools (reads + create/update/move/comment) so /hmy doesn't prompt each time? Destructive tools (delete/archive/api-key/invite) will still ask.";
+    const allowTools = await p3.confirm({ message, initialValue: true });
+    if (p3.isCancel(allowTools)) {
+      p3.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    if (allowTools) {
+      try {
+        const result = await allowlistHarmonyTools(home, allowAll);
+        const scope = allowAll ? "all tools" : "safe tools";
+        console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join7(home, ".claude", "settings.json"), home))} ${colors.dim(result === "added" ? `(${scope} allowlisted)` : `(${scope} already allowlisted)`)}`);
+      } catch {
+        p3.log.warning("Could not allowlist Harmony tools. Run /permissions in Claude Code and choose “always allow” for Harmony, or add mcp__harmony to permissions.allow in ~/.claude/settings.json.");
+      }
+    } else {
+      console.log(`  ${colors.dim("Skipped tool allowlist — you'll be prompted per tool, or run /permissions in Claude Code later.")}`);
+    }
+  }
   if (selectedWorkspaceId || selectedProjectId) {
     const localConfig = {};
     if (selectedWorkspaceId)
@@ -7137,7 +7452,7 @@ program.command("reset").description("Remove stored configuration").action(() =>
   console.log(`
 To reconfigure, run: npx @gethmy/mcp setup`);
 });
-program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "API key (skips prompt)").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").action(async (slug, options) => {
+program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "API key (skips prompt)").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").option("--allow-all-tools", "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.").action(async (slug, options) => {
   await runSetup({
     force: options.force,
     apiKey: options.apiKey,
@@ -7150,7 +7465,8 @@ program.command("setup").description("Smart setup wizard for Harmony MCP (recomm
     skipContext: options.skipContext,
     skipDocs: options.skipDocs,
     newAccount: options.new,
-    name: options.name
+    name: options.name,
+    allowAllTools: options.allowAllTools
   });
 });
 program.parse();

package/dist/index.js

@@ -932,6 +932,87 @@ function getDisplayLinkType(linkType, direction) {
     return linkType;
   return LINK_TYPE_INVERSES[linkType];
 }
+// ../harmony-shared/dist/commentSerializer.js
+var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function authorLabel(c) {
+  if (c.author_type === "agent")
+    return "AI agent";
+  return c.author?.full_name || c.author?.email || "teammate";
+}
+function criticalIds(comments) {
+  const keep = new Set;
+  for (const c of comments) {
+    if (c.comment_type === "decision")
+      keep.add(c.id);
+    if (c.supersedes_id) {
+      keep.add(c.id);
+      keep.add(c.supersedes_id);
+    }
+    if (c.confirms_id) {
+      keep.add(c.id);
+      keep.add(c.confirms_id);
+    }
+  }
+  return keep;
+}
+function serializeCommentThread(comments, options = {}) {
+  const { heading = "Conversation", includeInstructions = true, activity = [], maxComments } = options;
+  const visible = comments.filter((c) => !c.deleted_at).slice().sort((a, b) => a.created_at.localeCompare(b.created_at));
+  if (visible.length === 0)
+    return "";
+  const indexById = new Map;
+  visible.forEach((c, i) => {
+    indexById.set(c.id, i + 1);
+  });
+  let rendered = visible;
+  let elidedCount = 0;
+  if (maxComments && visible.length > maxComments) {
+    const keep = criticalIds(visible);
+    const recentThreshold = visible.length - maxComments;
+    rendered = visible.filter((c, i) => i >= recentThreshold || keep.has(c.id));
+    elidedCount = visible.length - rendered.length;
+  }
+  const ref = (id) => {
+    const n = indexById.get(id);
+    return n ? `#${n}` : `#${id.slice(0, 8)}`;
+  };
+  const lines = [];
+  if (elidedCount > 0) {
+    lines.push({
+      at: visible[0]?.created_at ?? "",
+      text: `(${elidedCount} earlier comment(s) omitted for brevity)`
+    });
+  }
+  for (const c of rendered) {
+    const tags = [];
+    if (c.edited_at)
+      tags.push("edited");
+    if (c.supersedes_id)
+      tags.push(`supersedes ${ref(c.supersedes_id)}`);
+    if (c.confirms_id)
+      tags.push(`confirms ${ref(c.confirms_id)}`);
+    if (c.resolved_at)
+      tags.push("resolved");
+    const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
+    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
+    lines.push({ at: c.created_at, text: `${header}
+${c.body.trim()}` });
+  }
+  for (const a of activity) {
+    const actor = a.actor ? `${a.actor} ` : "";
+    lines.push({ at: a.at, text: `· (system) ${a.at} — ${actor}${a.text}` });
+  }
+  lines.sort((a, b) => a.at.localeCompare(b.at));
+  const body = lines.map((l) => l.text).join(`
+
+`);
+  const instruction = includeInstructions ? `
+
+${CONFLICT_INSTRUCTION}` : "";
+  return `## ${heading} (oldest → newest)
+
+${body}${instruction}`;
+}
 // ../harmony-shared/dist/constants.js
 var TIMINGS = {
   SEARCH_DEBOUNCE: 300,
@@ -1469,6 +1550,28 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async addComment(cardId, body, opts) {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId
+    });
+  }
+  async getComments(cardId, opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit != null)
+      qs.set("limit", String(opts.limit));
+    if (opts?.offset != null)
+      qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+  async updateComment(commentId, updates) {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
   async startAgentSession(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1826,6 +1929,24 @@ class HarmonyApiClient {
       assembledContext: assembledContextStr,
       assemblyId
     });
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments, {
+          heading: "Comments",
+          maxComments: 40
+        });
+        if (section)
+          result.prompt = `${result.prompt}
+
+${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
     try {
       await this.recordPromptHistory({
         cardId: cardData.id,
@@ -3128,6 +3249,66 @@ var TOOLS = {
       required: ["subtaskId"]
     }
   },
+  harmony_add_comment: {
+    description: "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID to comment on" },
+        body: { type: "string", description: "Comment body (Markdown)" },
+        commentType: {
+          type: "string",
+          enum: [
+            "message",
+            "progress",
+            "question",
+            "blocker",
+            "decision",
+            "summary",
+            "finding"
+          ],
+          description: "Type of comment. 'question'/'blocker' signal you need a human; default 'message'."
+        },
+        supersedesId: {
+          type: "string",
+          description: "Comment id this comment corrects/updates"
+        },
+        confirmsId: {
+          type: "string",
+          description: "Comment id this comment reaffirms"
+        }
+      },
+      required: ["cardId", "body"]
+    }
+  },
+  harmony_get_comments: {
+    description: "Get the comment thread on a card (oldest → newest). Returns human + agent comments with author, type, edited/resolved state, and supersede/confirm links. Read this before acting so you weigh later comments over earlier ones they contradict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string" },
+        limit: { type: "number" },
+        offset: { type: "number" }
+      },
+      required: ["cardId"]
+    }
+  },
+  harmony_update_comment: {
+    description: "Update one of your own comments: edit the body, pin it, or resolve a question/blocker once it has been answered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        commentId: { type: "string" },
+        body: { type: "string" },
+        pinned: { type: "boolean" },
+        resolve: {
+          type: "boolean",
+          description: "Mark (true) or clear (false) the resolved state"
+        }
+      },
+      required: ["commentId"]
+    }
+  },
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
     inputSchema: {
@@ -4389,6 +4570,49 @@ async function handleToolCall(name, args, deps) {
       await client3.deleteSubtask(subtaskId);
       return { success: true };
     }
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(1e4).parse(args.body);
+      const commentType = args.commentType !== undefined ? z.enum([
+        "message",
+        "progress",
+        "question",
+        "blocker",
+        "decision",
+        "summary",
+        "finding"
+      ]).parse(args.commentType) : undefined;
+      const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
+      const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
+      const result = await client3.addComment(cardId, body, {
+        commentType,
+        supersedesId,
+        confirmsId
+      });
+      return { success: true, ...result };
+    }
+    case "harmony_get_comments": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const limit = args.limit !== undefined ? z.number().int().min(1).max(500).parse(args.limit) : undefined;
+      const offset = args.offset !== undefined ? z.number().int().min(0).parse(args.offset) : undefined;
+      const result = await client3.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates = {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(1e4).parse(args.body);
+      }
+      if (args.pinned !== undefined) {
+        updates.pinned = z.boolean().parse(args.pinned);
+      }
+      if (args.resolve !== undefined) {
+        updates.resolve = z.boolean().parse(args.resolve);
+      }
+      const result = await client3.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
     case "harmony_list_workspaces": {
       const result = await client3.listWorkspaces();
       return { success: true, ...result };

package/dist/lib/api-client.js

@@ -724,6 +724,87 @@ function getDisplayLinkType(linkType, direction) {
     return linkType;
   return LINK_TYPE_INVERSES[linkType];
 }
+// ../harmony-shared/dist/commentSerializer.js
+var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function authorLabel(c) {
+  if (c.author_type === "agent")
+    return "AI agent";
+  return c.author?.full_name || c.author?.email || "teammate";
+}
+function criticalIds(comments) {
+  const keep = new Set;
+  for (const c of comments) {
+    if (c.comment_type === "decision")
+      keep.add(c.id);
+    if (c.supersedes_id) {
+      keep.add(c.id);
+      keep.add(c.supersedes_id);
+    }
+    if (c.confirms_id) {
+      keep.add(c.id);
+      keep.add(c.confirms_id);
+    }
+  }
+  return keep;
+}
+function serializeCommentThread(comments, options = {}) {
+  const { heading = "Conversation", includeInstructions = true, activity = [], maxComments } = options;
+  const visible = comments.filter((c) => !c.deleted_at).slice().sort((a, b) => a.created_at.localeCompare(b.created_at));
+  if (visible.length === 0)
+    return "";
+  const indexById = new Map;
+  visible.forEach((c, i) => {
+    indexById.set(c.id, i + 1);
+  });
+  let rendered = visible;
+  let elidedCount = 0;
+  if (maxComments && visible.length > maxComments) {
+    const keep = criticalIds(visible);
+    const recentThreshold = visible.length - maxComments;
+    rendered = visible.filter((c, i) => i >= recentThreshold || keep.has(c.id));
+    elidedCount = visible.length - rendered.length;
+  }
+  const ref = (id) => {
+    const n = indexById.get(id);
+    return n ? `#${n}` : `#${id.slice(0, 8)}`;
+  };
+  const lines = [];
+  if (elidedCount > 0) {
+    lines.push({
+      at: visible[0]?.created_at ?? "",
+      text: `(${elidedCount} earlier comment(s) omitted for brevity)`
+    });
+  }
+  for (const c of rendered) {
+    const tags = [];
+    if (c.edited_at)
+      tags.push("edited");
+    if (c.supersedes_id)
+      tags.push(`supersedes ${ref(c.supersedes_id)}`);
+    if (c.confirms_id)
+      tags.push(`confirms ${ref(c.confirms_id)}`);
+    if (c.resolved_at)
+      tags.push("resolved");
+    const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
+    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
+    lines.push({ at: c.created_at, text: `${header}
+${c.body.trim()}` });
+  }
+  for (const a of activity) {
+    const actor = a.actor ? `${a.actor} ` : "";
+    lines.push({ at: a.at, text: `· (system) ${a.at} — ${actor}${a.text}` });
+  }
+  lines.sort((a, b) => a.at.localeCompare(b.at));
+  const body = lines.map((l) => l.text).join(`
+
+`);
+  const instruction = includeInstructions ? `
+
+${CONFLICT_INSTRUCTION}` : "";
+  return `## ${heading} (oldest → newest)
+
+${body}${instruction}`;
+}
 // ../harmony-shared/dist/constants.js
 var TIMINGS = {
   SEARCH_DEBOUNCE: 300,
@@ -1076,6 +1157,28 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async addComment(cardId, body, opts) {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId
+    });
+  }
+  async getComments(cardId, opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit != null)
+      qs.set("limit", String(opts.limit));
+    if (opts?.offset != null)
+      qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+  async updateComment(commentId, updates) {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
   async startAgentSession(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1433,6 +1536,24 @@ class HarmonyApiClient {
       assembledContext: assembledContextStr,
       assemblyId
     });
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments, {
+          heading: "Comments",
+          maxComments: 40
+        });
+        if (section)
+          result.prompt = `${result.prompt}
+
+${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
     try {
       await this.recordPromptHistory({
         cardId: cardData.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -1,4 +1,8 @@
-import { getDisplayLinkType } from "@harmony/shared";
+import {
+  type Comment,
+  getDisplayLinkType,
+  serializeCommentThread,
+} from "@harmony/shared";
 import { getApiKey, getApiUrl } from "./config.js";
 
 export interface ApiResponse<T = unknown> {
@@ -617,6 +621,46 @@ export class HarmonyApiClient {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
 
+  // ============ COMMENT OPERATIONS ============
+
+  async addComment(
+    cardId: string,
+    body: string,
+    opts?: {
+      commentType?: string;
+      supersedesId?: string;
+      confirmsId?: string;
+      agentSessionId?: string;
+    },
+  ): Promise<{ comment: unknown }> {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId,
+    });
+  }
+
+  async getComments(
+    cardId: string,
+    opts?: { limit?: number; offset?: number },
+  ): Promise<{ comments: unknown[] }> {
+    const qs = new URLSearchParams();
+    if (opts?.limit != null) qs.set("limit", String(opts.limit));
+    if (opts?.offset != null) qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+
+  async updateComment(
+    commentId: string,
+    updates: { body?: string; pinned?: boolean; resolve?: boolean },
+  ): Promise<{ comment: unknown }> {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
+
   // ============ AGENT CONTEXT OPERATIONS ============
 
   async startAgentSession(
@@ -1448,6 +1492,26 @@ export class HarmonyApiClient {
       assemblyId,
     });
 
+    // Append the card's comment thread (people + agents). This is the central
+    // injection point: every caller of harmony_generate_prompt (daemon, Claude
+    // Code, in-app builder) gets the recency-ordered thread + conflict rule.
+    // Best-effort — never fail prompt generation on a comments fetch error.
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200,
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments as Comment[], {
+          heading: "Comments",
+          maxComments: 40,
+        });
+        if (section) result.prompt = `${result.prompt}\n\n${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
+
     // AGP P2: persist a session-linked snapshot. Best-effort — never fail
     // prompt generation just because logging didn't land.
     try {

package/src/cli.ts

@@ -158,6 +158,10 @@ program
   .option("--skip-docs", "Skip project docs scaffold/verification")
   .option("--new", "Create a new account (skip the choice prompt)")
   .option("-n, --name <name>", "Full name (for account creation)")
+  .option(
+    "--allow-all-tools",
+    "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.",
+  )
   .action(async (slug, options) => {
     await runSetup({
       force: options.force,
@@ -176,6 +180,7 @@ program
       skipDocs: options.skipDocs,
       newAccount: options.new,
       name: options.name,
+      allowAllTools: options.allowAllTools,
     });
   });
 

package/src/server.ts

@@ -636,6 +636,72 @@ export const TOOLS = {
     },
   },
 
+  // Comment operations
+  harmony_add_comment: {
+    description:
+      "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID to comment on" },
+        body: { type: "string", description: "Comment body (Markdown)" },
+        commentType: {
+          type: "string",
+          enum: [
+            "message",
+            "progress",
+            "question",
+            "blocker",
+            "decision",
+            "summary",
+            "finding",
+          ],
+          description:
+            "Type of comment. 'question'/'blocker' signal you need a human; default 'message'.",
+        },
+        supersedesId: {
+          type: "string",
+          description: "Comment id this comment corrects/updates",
+        },
+        confirmsId: {
+          type: "string",
+          description: "Comment id this comment reaffirms",
+        },
+      },
+      required: ["cardId", "body"],
+    },
+  },
+  harmony_get_comments: {
+    description:
+      "Get the comment thread on a card (oldest → newest). Returns human + agent comments with author, type, edited/resolved state, and supersede/confirm links. Read this before acting so you weigh later comments over earlier ones they contradict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string" },
+        limit: { type: "number" },
+        offset: { type: "number" },
+      },
+      required: ["cardId"],
+    },
+  },
+  harmony_update_comment: {
+    description:
+      "Update one of your own comments: edit the body, pin it, or resolve a question/blocker once it has been answered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        commentId: { type: "string" },
+        body: { type: "string" },
+        pinned: { type: "boolean" },
+        resolve: {
+          type: "boolean",
+          description: "Mark (true) or clear (false) the resolved state",
+        },
+      },
+      required: ["commentId"],
+    },
+  },
+
   // Context operations
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
@@ -2177,6 +2243,71 @@ async function handleToolCall(
       return { success: true };
     }
 
+    // Comment operations
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(10_000).parse(args.body);
+      const commentType =
+        args.commentType !== undefined
+          ? z
+              .enum([
+                "message",
+                "progress",
+                "question",
+                "blocker",
+                "decision",
+                "summary",
+                "finding",
+              ])
+              .parse(args.commentType)
+          : undefined;
+      const supersedesId =
+        args.supersedesId !== undefined
+          ? z.string().uuid().parse(args.supersedesId)
+          : undefined;
+      const confirmsId =
+        args.confirmsId !== undefined
+          ? z.string().uuid().parse(args.confirmsId)
+          : undefined;
+      const result = await client.addComment(cardId, body, {
+        commentType,
+        supersedesId,
+        confirmsId,
+      });
+      return { success: true, ...result };
+    }
+
+    case "harmony_get_comments": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const limit =
+        args.limit !== undefined
+          ? z.number().int().min(1).max(500).parse(args.limit)
+          : undefined;
+      const offset =
+        args.offset !== undefined
+          ? z.number().int().min(0).parse(args.offset)
+          : undefined;
+      const result = await client.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates: { body?: string; pinned?: boolean; resolve?: boolean } =
+        {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(10_000).parse(args.body);
+      }
+      if (args.pinned !== undefined) {
+        updates.pinned = z.boolean().parse(args.pinned);
+      }
+      if (args.resolve !== undefined) {
+        updates.resolve = z.boolean().parse(args.resolve);
+      }
+      const result = await client.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
+
     // Context operations
     case "harmony_list_workspaces": {
       const result = await client.listWorkspaces();

package/src/tui/setup.ts

@@ -44,8 +44,68 @@ export interface SetupOptions {
   skipDocs?: boolean;
   newAccount?: boolean;
   name?: string;
+  allowAllTools?: boolean;
 }
 
+/**
+ * Harmony tools that are safe to run without per-call confirmation: reads and
+ * routine writes the /hmy flow leans on. Destructive or sensitive tools are
+ * deliberately ABSENT so they keep prompting — deletes, archives, API-key
+ * minting, and invitations are exactly where the permission prompt earns its
+ * keep, especially under autonomous agent runs. New tools default to prompting
+ * until someone classifies them here (safe failure mode). `--allow-all-tools`
+ * overrides this with a blanket grant.
+ */
+const SAFE_HARMONY_TOOLS = [
+  // Reads
+  "harmony_get_card",
+  "harmony_get_card_by_short_id",
+  "harmony_search_cards",
+  "harmony_get_board",
+  "harmony_get_context",
+  "harmony_list_projects",
+  "harmony_list_workspaces",
+  "harmony_get_card_links",
+  "harmony_get_card_attachments",
+  "harmony_get_card_external_links",
+  "harmony_get_comments",
+  "harmony_get_plan",
+  "harmony_list_plans",
+  "harmony_get_agent_session",
+  "harmony_get_workspace_members",
+  "harmony_resolve_links",
+  "harmony_recall",
+  "harmony_memory_search",
+  "harmony_generate_prompt",
+  // Routine writes
+  "harmony_create_card",
+  "harmony_update_card",
+  "harmony_move_card",
+  "harmony_assign_card",
+  "harmony_create_subtask",
+  "harmony_toggle_subtask",
+  "harmony_add_label_to_card",
+  "harmony_remove_label_from_card",
+  "harmony_create_label",
+  "harmony_add_comment",
+  "harmony_update_comment",
+  "harmony_add_link_to_card",
+  "harmony_remove_link_from_card",
+  "harmony_start_agent_session",
+  "harmony_update_agent_progress",
+  "harmony_end_agent_session",
+  "harmony_set_project_context",
+  "harmony_set_workspace_context",
+  "harmony_create_plan",
+  "harmony_update_plan",
+  "harmony_advance_plan",
+  "harmony_remember",
+  "harmony_relate",
+  "harmony_update_memory",
+  "harmony_process_command",
+  "harmony_sync",
+];
+
 // Central skills directory for global installation
 const GLOBAL_SKILLS_DIR = join(homedir(), ".agents", "skills");
 
@@ -87,14 +147,12 @@ async function writeMcpConfigFallback(home: string): Promise<void> {
     mkdirSync(settingsDir, { recursive: true });
   }
 
-  // Read existing settings or start fresh
+  // Read existing settings. If the file exists but doesn't parse, bail rather
+  // than overwrite — don't wipe a user's hand-edited settings.json to register
+  // one MCP server. The caller falls back to a manual-setup instruction.
   let settings: Record<string, unknown> = {};
   if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-    } catch {
-      // Invalid JSON, start fresh
-    }
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
   }
 
   // Merge mcpServers config
@@ -109,6 +167,65 @@ async function writeMcpConfigFallback(home: string): Promise<void> {
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 }
 
+/**
+ * Allowlist Harmony MCP tools in Claude Code settings so the /hmy flow runs
+ * without per-tool permission prompts. Merges rules into permissions.allow in
+ * ~/.claude/settings.json, preserving existing settings. Idempotent.
+ *
+ * Default (allowAll=false): writes a per-tool rule (`mcp__harmony__<tool>`) for
+ * each entry in SAFE_HARMONY_TOOLS only — destructive tools keep prompting.
+ * allowAll=true: writes the bare `mcp__harmony` rule (every tool, incl.
+ * destructive). The bare form grants all tools and is supported across all
+ * Claude Code versions.
+ */
+async function allowlistHarmonyTools(
+  home: string,
+  allowAll: boolean,
+): Promise<"added" | "already"> {
+  const { readFileSync, writeFileSync, mkdirSync, existsSync } = await import(
+    "node:fs"
+  );
+  const settingsPath = join(home, ".claude", "settings.json");
+  const settingsDir = dirname(settingsPath);
+
+  if (!existsSync(settingsDir)) {
+    mkdirSync(settingsDir, { recursive: true });
+  }
+
+  // Read existing settings. If the file exists but doesn't parse, bail rather
+  // than overwrite — clobbering a user's hand-edited settings.json to add a
+  // permission rule is never worth it. The caller surfaces the manual-fix path.
+  let settings: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  }
+
+  const permissions = (settings.permissions as Record<string, unknown>) || {};
+  const allow = Array.isArray(permissions.allow)
+    ? (permissions.allow as string[])
+    : [];
+
+  // A pre-existing blanket grant already covers everything either mode adds.
+  const hasBlanket =
+    allow.includes("mcp__harmony") || allow.includes("mcp__harmony__*");
+
+  const wanted = allowAll
+    ? ["mcp__harmony"]
+    : SAFE_HARMONY_TOOLS.map((t) => `mcp__harmony__${t}`);
+
+  const missing = hasBlanket ? [] : wanted.filter((r) => !allow.includes(r));
+  if (missing.length === 0) {
+    return "already";
+  }
+
+  allow.push(...missing);
+  permissions.allow = allow;
+  settings.permissions = permissions;
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  return "added";
+}
+
 interface Workspace {
   id: string;
   name: string;
@@ -1187,6 +1304,38 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     }
   }
 
+  // Step 8c: Allowlist Harmony tools so /hmy runs without permission prompts.
+  // Default = safe subset (reads + routine writes); destructive tools still
+  // prompt. `--allow-all-tools` opts into a blanket grant.
+  if (claudeDetected || selectedAgents.includes("claude")) {
+    const allowAll = options.allowAllTools === true;
+    const message = allowAll
+      ? "Allowlist EVERY Harmony tool without confirmation, including destructive ones (delete/archive/api-key/invite)?"
+      : "Allowlist common Harmony tools (reads + create/update/move/comment) so /hmy doesn't prompt each time? Destructive tools (delete/archive/api-key/invite) will still ask.";
+    const allowTools = await p.confirm({ message, initialValue: true });
+    if (p.isCancel(allowTools)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    if (allowTools) {
+      try {
+        const result = await allowlistHarmonyTools(home, allowAll);
+        const scope = allowAll ? "all tools" : "safe tools";
+        console.log(
+          `  ${colors.success("✓")} ${colors.dim(formatPath(join(home, ".claude", "settings.json"), home))} ${colors.dim(result === "added" ? `(${scope} allowlisted)` : `(${scope} already allowlisted)`)}`,
+        );
+      } catch {
+        p.log.warning(
+          "Could not allowlist Harmony tools. Run /permissions in Claude Code and choose “always allow” for Harmony, or add mcp__harmony to permissions.allow in ~/.claude/settings.json.",
+        );
+      }
+    } else {
+      console.log(
+        `  ${colors.dim("Skipped tool allowlist — you'll be prompted per tool, or run /permissions in Claude Code later.")}`,
+      );
+    }
+  }
+
   // Step 9: Save local context
   if (selectedWorkspaceId || selectedProjectId) {
     const localConfig: { workspaceId?: string; projectId?: string } = {};

package/src/tui/writer.ts

@@ -156,13 +156,14 @@ export function appendToToml(
   try {
     const existing = readFileSync(filePath, "utf-8");
 
-    if (existing.includes(section)) {
+    if (existing.includes(`[${section}]`)) {
       if (options.force) {
-        // Replace existing section
+        // Replace existing section, including any comment lines directly above
+        // it. The end anchor is `\n[` (a table header at line start) or EOF —
+        // NOT a bare `[`, so we don't stop early on the `[` inside `args = [...]`.
+        const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
         const updated = existing.replace(
-          new RegExp(
-            `\\[${section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\][\\s\\S]*?(?=\\[|$)`,
-          ),
+          new RegExp(`(?:#[^\\n]*\\n)*\\[${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`),
           content.trim() + "\n\n",
         );
         writeFileSync(filePath, updated, { mode: 0o644 });