@gethmy/mcp 2.8.2 → 2.8.4

package/dist/cli.js

@@ -1551,6 +1551,9 @@ class HarmonyApiClient {
   async toggleSubtask(subtaskId) {
     return this.request("POST", `/subtasks/${subtaskId}/toggle`);
   }
+  async updateSubtask(subtaskId, updates) {
+    return this.request("PATCH", `/subtasks/${subtaskId}`, updates);
+  }
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
@@ -2026,7 +2029,8 @@ var AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
   "harmony_update_card",
   "harmony_create_subtask",
-  "harmony_toggle_subtask"
+  "harmony_toggle_subtask",
+  "harmony_update_subtask"
 ]);
 var INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var CHECK_INTERVAL_MS = 60 * 1000;
@@ -2944,7 +2948,12 @@ var TOOLS = {
         priority: { type: "string", enum: ["low", "medium", "high", "urgent"] },
         assigneeId: { type: "string", nullable: true },
         dueDate: { type: "string", nullable: true },
-        done: { type: "boolean", description: "Mark card as done or not done" }
+        done: { type: "boolean", description: "Mark card as done or not done" },
+        planId: {
+          type: "string",
+          nullable: true,
+          description: "Plan ID to link this card to, or null to unlink. Sets cards.plan_id. The plan must exist and belong to the same project."
+        }
       },
       required: ["cardId"]
     }
@@ -3243,6 +3252,25 @@ var TOOLS = {
       required: ["subtaskId"]
     }
   },
+  harmony_update_subtask: {
+    description: "Update a subtask: rename its title, set an explicit completion state, and/or reorder it. Unlike harmony_toggle_subtask (which flips completion), `completed` here sets an explicit value — safe to call idempotently. At least one of title/completed/position is required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subtaskId: { type: "string" },
+        title: { type: "string", description: "New title (1–500 chars)" },
+        completed: {
+          type: "boolean",
+          description: "Explicit completion state (set, not toggle)"
+        },
+        position: {
+          type: "number",
+          description: "New position (0-based ordering within the card)"
+        }
+      },
+      required: ["subtaskId"]
+    }
+  },
   harmony_delete_subtask: {
     description: "Delete a subtask",
     inputSchema: {
@@ -4360,13 +4388,15 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
+      const planId = args.planId === undefined ? undefined : args.planId === null ? null : z.string().uuid().parse(args.planId);
       const result = await client3.updateCard(cardId, {
         title: args.title,
         description: args.description,
         priority: args.priority,
         assigneeId: args.assigneeId,
         dueDate: args.dueDate,
-        done: args.done
+        done: args.done,
+        planId
       });
       return { success: true, ...result };
     }
@@ -4569,6 +4599,24 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.toggleSubtask(subtaskId);
       return { success: true, ...result };
     }
+    case "harmony_update_subtask": {
+      const subtaskId = z.string().uuid().parse(args.subtaskId);
+      const updates = {};
+      if (args.title !== undefined) {
+        updates.title = z.string().min(1).max(500).parse(args.title);
+      }
+      if (args.completed !== undefined) {
+        updates.completed = z.boolean().parse(args.completed);
+      }
+      if (args.position !== undefined) {
+        updates.position = z.number().int().min(0).parse(args.position);
+      }
+      if (Object.keys(updates).length === 0) {
+        throw new Error("harmony_update_subtask requires at least one of: title, completed, position");
+      }
+      const result = await client3.updateSubtask(subtaskId, updates);
+      return { success: true, ...result };
+    }
     case "harmony_delete_subtask": {
       const subtaskId = z.string().uuid().parse(args.subtaskId);
       await client3.deleteSubtask(subtaskId);
@@ -6357,9 +6405,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 });
@@ -6433,6 +6482,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() {
@@ -6455,9 +6551,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 = {
@@ -6467,6 +6561,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`, {
@@ -7231,6 +7350,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)
@@ -7361,7 +7500,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,
@@ -7374,7 +7513,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

@@ -1547,6 +1547,9 @@ class HarmonyApiClient {
   async toggleSubtask(subtaskId) {
     return this.request("POST", `/subtasks/${subtaskId}/toggle`);
   }
+  async updateSubtask(subtaskId, updates) {
+    return this.request("PATCH", `/subtasks/${subtaskId}`, updates);
+  }
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
@@ -2022,7 +2025,8 @@ var AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
   "harmony_update_card",
   "harmony_create_subtask",
-  "harmony_toggle_subtask"
+  "harmony_toggle_subtask",
+  "harmony_update_subtask"
 ]);
 var INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var CHECK_INTERVAL_MS = 60 * 1000;
@@ -2940,7 +2944,12 @@ var TOOLS = {
         priority: { type: "string", enum: ["low", "medium", "high", "urgent"] },
         assigneeId: { type: "string", nullable: true },
         dueDate: { type: "string", nullable: true },
-        done: { type: "boolean", description: "Mark card as done or not done" }
+        done: { type: "boolean", description: "Mark card as done or not done" },
+        planId: {
+          type: "string",
+          nullable: true,
+          description: "Plan ID to link this card to, or null to unlink. Sets cards.plan_id. The plan must exist and belong to the same project."
+        }
       },
       required: ["cardId"]
     }
@@ -3239,6 +3248,25 @@ var TOOLS = {
       required: ["subtaskId"]
     }
   },
+  harmony_update_subtask: {
+    description: "Update a subtask: rename its title, set an explicit completion state, and/or reorder it. Unlike harmony_toggle_subtask (which flips completion), `completed` here sets an explicit value — safe to call idempotently. At least one of title/completed/position is required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subtaskId: { type: "string" },
+        title: { type: "string", description: "New title (1–500 chars)" },
+        completed: {
+          type: "boolean",
+          description: "Explicit completion state (set, not toggle)"
+        },
+        position: {
+          type: "number",
+          description: "New position (0-based ordering within the card)"
+        }
+      },
+      required: ["subtaskId"]
+    }
+  },
   harmony_delete_subtask: {
     description: "Delete a subtask",
     inputSchema: {
@@ -4356,13 +4384,15 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
+      const planId = args.planId === undefined ? undefined : args.planId === null ? null : z.string().uuid().parse(args.planId);
       const result = await client3.updateCard(cardId, {
         title: args.title,
         description: args.description,
         priority: args.priority,
         assigneeId: args.assigneeId,
         dueDate: args.dueDate,
-        done: args.done
+        done: args.done,
+        planId
       });
       return { success: true, ...result };
     }
@@ -4565,6 +4595,24 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.toggleSubtask(subtaskId);
       return { success: true, ...result };
     }
+    case "harmony_update_subtask": {
+      const subtaskId = z.string().uuid().parse(args.subtaskId);
+      const updates = {};
+      if (args.title !== undefined) {
+        updates.title = z.string().min(1).max(500).parse(args.title);
+      }
+      if (args.completed !== undefined) {
+        updates.completed = z.boolean().parse(args.completed);
+      }
+      if (args.position !== undefined) {
+        updates.position = z.number().int().min(0).parse(args.position);
+      }
+      if (Object.keys(updates).length === 0) {
+        throw new Error("harmony_update_subtask requires at least one of: title, completed, position");
+      }
+      const result = await client3.updateSubtask(subtaskId, updates);
+      return { success: true, ...result };
+    }
     case "harmony_delete_subtask": {
       const subtaskId = z.string().uuid().parse(args.subtaskId);
       await client3.deleteSubtask(subtaskId);

package/dist/lib/api-client.js

@@ -1154,6 +1154,9 @@ class HarmonyApiClient {
   async toggleSubtask(subtaskId) {
     return this.request("POST", `/subtasks/${subtaskId}/toggle`);
   }
+  async updateSubtask(subtaskId, updates) {
+    return this.request("PATCH", `/subtasks/${subtaskId}`, updates);
+  }
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }

package/package.json

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

package/src/api-client.ts

@@ -474,6 +474,7 @@ export class HarmonyApiClient {
       dueDate?: string | null;
       done?: boolean;
       archivedAt?: string | null;
+      planId?: string | null;
     },
   ): Promise<{ card: unknown }> {
     return this.request("PATCH", `/cards/${cardId}`, updates);
@@ -617,6 +618,13 @@ export class HarmonyApiClient {
     return this.request("POST", `/subtasks/${subtaskId}/toggle`);
   }
 
+  async updateSubtask(
+    subtaskId: string,
+    updates: { title?: string; completed?: boolean; position?: number },
+  ): Promise<{ subtask: unknown }> {
+    return this.request("PATCH", `/subtasks/${subtaskId}`, updates);
+  }
+
   async deleteSubtask(subtaskId: string): Promise<{ success: boolean }> {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }

package/src/auto-session.ts

@@ -78,6 +78,7 @@ export const AUTO_START_TRIGGERS = new Set([
   "harmony_update_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
+  "harmony_update_subtask",
 ]);
 
 export const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes

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

@@ -308,6 +308,12 @@ export const TOOLS = {
         assigneeId: { type: "string", nullable: true },
         dueDate: { type: "string", nullable: true },
         done: { type: "boolean", description: "Mark card as done or not done" },
+        planId: {
+          type: "string",
+          nullable: true,
+          description:
+            "Plan ID to link this card to, or null to unlink. Sets cards.plan_id. The plan must exist and belong to the same project.",
+        },
       },
       required: ["cardId"],
     },
@@ -625,6 +631,26 @@ export const TOOLS = {
       required: ["subtaskId"],
     },
   },
+  harmony_update_subtask: {
+    description:
+      "Update a subtask: rename its title, set an explicit completion state, and/or reorder it. Unlike harmony_toggle_subtask (which flips completion), `completed` here sets an explicit value — safe to call idempotently. At least one of title/completed/position is required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subtaskId: { type: "string" },
+        title: { type: "string", description: "New title (1–500 chars)" },
+        completed: {
+          type: "boolean",
+          description: "Explicit completion state (set, not toggle)",
+        },
+        position: {
+          type: "number",
+          description: "New position (0-based ordering within the card)",
+        },
+      },
+      required: ["subtaskId"],
+    },
+  },
   harmony_delete_subtask: {
     description: "Delete a subtask",
     inputSchema: {
@@ -1944,6 +1970,13 @@ async function handleToolCall(
 
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
+      // null = unlink, undefined = leave untouched, otherwise must be a UUID.
+      const planId =
+        args.planId === undefined
+          ? undefined
+          : args.planId === null
+            ? null
+            : z.string().uuid().parse(args.planId);
       const result = await client.updateCard(cardId, {
         title: args.title as string | undefined,
         description: args.description as string | undefined,
@@ -1951,6 +1984,7 @@ async function handleToolCall(
         assigneeId: args.assigneeId as string | null | undefined,
         dueDate: args.dueDate as string | null | undefined,
         done: args.done as boolean | undefined,
+        planId,
       });
       return { success: true, ...result };
     }
@@ -2237,6 +2271,31 @@ async function handleToolCall(
       return { success: true, ...result };
     }
 
+    case "harmony_update_subtask": {
+      const subtaskId = z.string().uuid().parse(args.subtaskId);
+      const updates: {
+        title?: string;
+        completed?: boolean;
+        position?: number;
+      } = {};
+      if (args.title !== undefined) {
+        updates.title = z.string().min(1).max(500).parse(args.title);
+      }
+      if (args.completed !== undefined) {
+        updates.completed = z.boolean().parse(args.completed);
+      }
+      if (args.position !== undefined) {
+        updates.position = z.number().int().min(0).parse(args.position);
+      }
+      if (Object.keys(updates).length === 0) {
+        throw new Error(
+          "harmony_update_subtask requires at least one of: title, completed, position",
+        );
+      }
+      const result = await client.updateSubtask(subtaskId, updates);
+      return { success: true, ...result };
+    }
+
     case "harmony_delete_subtask": {
       const subtaskId = z.string().uuid().parse(args.subtaskId);
       await client.deleteSubtask(subtaskId);

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 });