@hanhnd/agent-kit 1.0.17 → 1.0.19

package/README.md

@@ -11,7 +11,8 @@
 | `/ak:brainstorm [idea]`           | Strategic architectural analysis                                   |
 | `/ak:plan [file or idea]`         | Create an implementation blueprint                                 |
 | `/ak:code [file or task]`         | Implement from a plan                                              |
-| `/ak:code-simplify`               | Refactor modified code for readability                             |
+| `/ak:code-simplify`               | Simplify modified code for readability                             |
+| `/ak:code-refactor`               | Refactor modified code for readability                             |
 | `/ak:research [topic]`            | Research a topic                                                   |
 | `/ak:review-pr [PR URL]`          | Review a pull request                                              |
 | `/ak:review`                      | Review uncommitted local changes                                   |
@@ -68,7 +69,7 @@ You don't need to run the wiki manually. Five hooks keep it fed automatically:
 
 ```bash
 claude plugin marketplace add https://github.com/hanh-nd/agent-kit
-claude plugin install ak
+claude plugin install agent-kit
 ```
 
 The plugin fetches from GitHub, registers the MCP server automatically, and makes all commands available immediately.
@@ -91,8 +92,8 @@ BITBUCKET_DEFAULT_WORKSPACE = your-default-workspace-slug
 
 To use multiple profiles, add `[work]`, `[personal]`, etc. sections and set `KIT_PROFILE=work` in your environment.
 
-To update: `claude plugin update ak`
-To uninstall: `claude plugin uninstall ak`
+To update: `claude plugin update agent-kit`
+To uninstall: `claude plugin uninstall agent-kit`
 
 ---
 
@@ -113,7 +114,7 @@ npm run build
 
 ```bash
 claude plugin marketplace add /absolute/path/to/agent-kit
-claude plugin install ak
+claude plugin install agent-kit
 ```
 
 This registers the MCP server automatically (pointing to your local build). Do **not** manually add a `kit-agents` entry to `settings.json` — the plugin handles that.
@@ -147,7 +148,9 @@ BITBUCKET_DEFAULT_WORKSPACE = your-default-workspace-slug
 If you want to reuse the commands with [Gemini CLI](https://geminicli.com) (for `/ak:delegate` to Gemini), install it using:
 
 ```bash
-gemini extension install https://github.com/hanh-nd/agent-kit
+git clone https://github.com/hanh-nd/agent-kit.git
+cd agent-kit/plugins/agent-kit
+gemini extension link .gemini
 ```
 
 ---

package/dist/kit-server.js

@@ -20997,6 +20997,12 @@ import * as path from "path";
 function getWorkspaceRoot() {
   return process.env.WORKSPACE_DIR || process.env.CLAUDE_WORKSPACE || process.env.GEMINI_WORKSPACE || process.env.INIT_CWD || process.env.PWD || process.cwd();
 }
+function mcpText(text) {
+  return { content: [{ type: "text", text }] };
+}
+function mcpJson(obj) {
+  return mcpText(JSON.stringify(obj, null, 2));
+}
 
 // src/tools/config.ts
 var FORBIDDEN_FILES = [
@@ -21060,13 +21066,9 @@ function registerCoreTools(server2) {
         }
         const filePath = path.join(handoffDir, filename);
         fs.writeFileSync(filePath, content, "utf8");
-        return {
-          content: [{ type: "text", text: `\u2705 Saved to: ${filePath}` }]
-        };
+        return mcpText(`\u2705 Saved to: ${filePath}`);
       } catch (error2) {
-        return {
-          content: [{ type: "text", text: `Error saving handoff: ${error2}` }]
-        };
+        return mcpText(`Error saving handoff: ${error2}`);
       }
     }
   );
@@ -21171,9 +21173,12 @@ function registerAgentTools(server2) {
         'Task message or path to a handoff file (e.g., ".agent-kit/handoffs/plans/plan-xyz.md")'
       )
     },
-    async ({ agent, task }) => {
+    async ({ agent, task }, extra) => {
+      const workspaceRoot = getWorkspaceRoot();
+      let job;
+      let logPath;
+      let killChild;
       try {
-        const workspaceRoot = getWorkspaceRoot();
         let prompt = task;
         const resolvedTask = path3.resolve(workspaceRoot, task);
         if (fs2.existsSync(resolvedTask) && fs2.statSync(resolvedTask).isFile()) {
@@ -21181,9 +21186,7 @@ function registerAgentTools(server2) {
             validatePath(task, workspaceRoot);
             prompt = fs2.readFileSync(resolvedTask, "utf-8");
           } catch (err) {
-            return {
-              content: [{ type: "text", text: `Error reading task file: ${err}` }]
-            };
+            return mcpText(`Error reading task file: ${err}`);
           }
         }
         let usedAgent = agent;
@@ -21195,107 +21198,89 @@ function registerAgentTools(server2) {
             fallbackReason = `${agent} CLI not installed, fell back to ${fallback}`;
           } else {
             const installHint = agent === "gemini" ? "Install Gemini CLI: https://github.com/google-gemini/gemini-cli" : "Install Claude CLI: npm install -g @anthropic-ai/claude-code";
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify(
-                    {
-                      agent,
-                      status: "error",
-                      output: "",
-                      error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`
-                    },
-                    null,
-                    2
-                  )
-                }
-              ]
-            };
+            return mcpJson({
+              agent,
+              status: "error",
+              output: "",
+              error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`
+            });
           }
         }
         const agentArgs = usedAgent === "gemini" ? ["-y", "-p", prompt] : ["--dangerously-skip-permissions", "-p", prompt];
-        const slug = taskSlug(task);
-        const { logPath, logStream } = initAgentLog(workspaceRoot, slug, usedAgent);
+        const { logPath: lp, logStream } = initAgentLog(workspaceRoot, taskSlug(task), usedAgent);
+        logPath = lp;
         const jobId = randomUUID();
         const child = spawn(usedAgent, agentArgs, {
           cwd: workspaceRoot,
-          env: { ...process.env, GEMINI_WORKSPACE: workspaceRoot }
+          env: { ...process.env, GEMINI_WORKSPACE: workspaceRoot },
+          detached: process.platform !== "win32"
         });
-        const job = {
-          id: jobId,
+        const killTree = (sig) => {
+          if (process.platform !== "win32" && child.pid) {
+            try {
+              process.kill(-child.pid, sig);
+            } catch {
+              child.kill(sig);
+            }
+          } else {
+            child.kill(sig);
+          }
+        };
+        job = {
           agent: usedAgent,
           process: child,
           startedAt: /* @__PURE__ */ new Date(),
           chunks: [],
           logStream,
-          timeoutHandle: setTimeout(() => {
-            child.kill("SIGTERM");
-          }, AGENT_TIMEOUT)
+          timeoutHandle: setTimeout(() => killTree("SIGTERM"), AGENT_TIMEOUT)
         };
         jobRegistry.set(jobId, job);
-        try {
-          await new Promise((resolve3, reject) => {
-            child.stdout?.on("data", (data) => {
-              job.chunks.push(data.toString());
-              job.logStream.write(data);
-            });
-            child.stderr?.on("data", (data) => {
-              job.chunks.push(data.toString());
-              job.logStream.write(data);
-            });
-            child.on("close", (code) => {
-              if (code === 0) resolve3();
-              else reject(new Error(`Process exited with code ${code}`));
-            });
-            child.on("error", reject);
+        killChild = () => {
+          killTree("SIGTERM");
+          setTimeout(() => killTree("SIGKILL"), 5e3).unref();
+        };
+        if (extra.signal.aborted) killChild();
+        else extra.signal.addEventListener("abort", killChild);
+        await new Promise((resolve3, reject) => {
+          child.stdout?.on("data", (data) => {
+            job.chunks.push(data.toString());
+            job.logStream.write(data);
           });
-          const output = job.chunks.join("");
-          const safeOutput = sanitizeOutput(output);
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(
-                  {
-                    agent: usedAgent,
-                    status: fallbackReason ? "fallback" : "success",
-                    log: logPath,
-                    output: safeOutput,
-                    ...fallbackReason && { fallback_reason: fallbackReason }
-                  },
-                  null,
-                  2
-                )
-              }
-            ]
-          };
-        } catch (error2) {
-          throw error2;
-        } finally {
-          job.logStream.end();
-          clearTimeout(job.timeoutHandle);
-          jobRegistry.delete(jobId);
-        }
+          child.stderr?.on("data", (data) => {
+            job.chunks.push(data.toString());
+            job.logStream.write(data);
+          });
+          child.on("close", (code, signal) => {
+            if (code === 0) resolve3();
+            else
+              reject(
+                new Error(`Process exited with code ${code}${signal ? ` (signal: ${signal})` : ""}`)
+              );
+          });
+          child.on("error", reject);
+        });
+        return mcpJson({
+          agent: usedAgent,
+          status: fallbackReason ? "fallback" : "success",
+          log: logPath,
+          output: sanitizeOutput(job.chunks.join("")),
+          ...fallbackReason && { fallback_reason: fallbackReason }
+        });
       } catch (error2) {
+        if (extra.signal.aborted) {
+          return mcpJson({
+            agent,
+            status: "cancelled",
+            log: logPath,
+            output: sanitizeOutput(job?.chunks.join("") ?? "")
+          });
+        }
         const msg = error2 instanceof Error ? error2.message : String(error2);
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  agent,
-                  status: "error",
-                  output: "",
-                  error: msg
-                },
-                null,
-                2
-              )
-            }
-          ]
-        };
+        return mcpJson({ agent, status: "error", output: "", error: msg });
+      } finally {
+        if (killChild) extra.signal.removeEventListener("abort", killChild);
+        job?.logStream.end();
+        if (job) clearTimeout(job.timeoutHandle);
       }
     }
   );
@@ -21529,63 +21514,18 @@ var JiraTicketSchema = external_exports.object({
   errorMessages: external_exports.array(external_exports.string()).optional(),
   fields: JiraFieldsSchema
 });
-function buildJiraBasicAuth() {
-  const email2 = getCredential("ATLASSIAN_USER_EMAIL");
-  const token = getCredential("ATLASSIAN_API_TOKEN");
-  if (!email2 || !token) {
-    throw new Error("Missing ATLASSIAN_USER_EMAIL or ATLASSIAN_API_TOKEN");
-  }
+function buildBasicAuth(emailVar, tokenVar) {
+  const email2 = getCredential(emailVar);
+  const token = getCredential(tokenVar);
+  if (!email2 || !token) throw new Error(`Missing ${emailVar} or ${tokenVar}`);
   return "Basic " + Buffer.from(`${email2}:${token}`).toString("base64");
 }
-function buildBitbucketBasicAuth() {
-  const email2 = getCredential("BITBUCKET_USER_EMAIL");
-  const token = getCredential("BITBUCKET_API_TOKEN");
-  if (!email2 || !token) {
-    throw new Error("Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN");
-  }
-  return "Basic " + Buffer.from(`${email2}:${token}`).toString("base64");
-}
-async function callAtlassianRestApi(url) {
-  const auth = buildJiraBasicAuth();
-  const resp = await fetch(url, { headers: { Authorization: auth, Accept: "application/json" } });
-  if (resp.status === 401) {
-    throw new Error("\u274C Auth failed: check ATLASSIAN_USER_EMAIL and ATLASSIAN_API_TOKEN");
-  }
-  if (resp.status === 404) {
-    throw new Error(`\u274C Not found: ${url}`);
-  }
-  if (!resp.ok) {
-    throw new Error(`\u274C API error ${resp.status}: ${await resp.text()}`);
-  }
-  return await resp.json();
-}
-async function callBitbucketRestApi(url) {
-  const auth = buildBitbucketBasicAuth();
-  const resp = await fetch(url, { headers: { Authorization: auth, Accept: "application/json" } });
-  if (resp.status === 401) {
-    throw new Error("\u274C Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN");
-  }
-  if (resp.status === 404) {
-    throw new Error(`\u274C Not found: ${url}`);
-  }
-  if (!resp.ok) {
-    throw new Error(`\u274C API error ${resp.status}: ${await resp.text()}`);
-  }
-  return await resp.json();
-}
-async function callBitbucketDiffApi(url) {
-  const auth = buildBitbucketBasicAuth();
-  const resp = await fetch(url, { headers: { Authorization: auth, Accept: "text/plain" } });
-  if (resp.status === 401) {
-    throw new Error("\u274C Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN");
-  }
-  if (resp.status === 404) {
-    throw new Error(`\u274C Not found: ${url}`);
-  }
-  if (!resp.ok) {
-    throw new Error(`\u274C API error ${resp.status}: ${await resp.text()}`);
-  }
-  return await resp.text();
+async function callRestApi(url, auth, accept = "application/json") {
+  const resp = await fetch(url, { headers: { Authorization: auth, Accept: accept } });
+  if (resp.status === 401) throw new Error(`\u274C Auth failed (401): ${url}`);
+  if (resp.status === 404) throw new Error(`\u274C Not found: ${url}`);
+  if (!resp.ok) throw new Error(`\u274C API error ${resp.status}: ${await resp.text()}`);
+  return accept === "text/plain" ? resp.text() : resp.json();
 }
 function registerIntegrationTools(server2) {
   server2.tool(
@@ -21601,18 +21541,6 @@ function registerIntegrationTools(server2) {
     },
     async ({ input, workspace, repoSlug, includeDiff }) => {
       try {
-        const bbEmail = getCredential("BITBUCKET_USER_EMAIL");
-        const bbToken = getCredential("BITBUCKET_API_TOKEN");
-        if (!bbEmail || !bbToken) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN. Set them in ~/.claude/agent-kit or as environment variables.`
-              }
-            ]
-          };
-        }
         let ws;
         let repo;
         let prId;
@@ -21627,29 +21555,20 @@ function registerIntegrationTools(server2) {
           repo = repoSlug;
         }
         if (!ws) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`
-              }
-            ]
-          };
+          return mcpText(
+            `\u274C workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`
+          );
         }
         if (!repo || !prId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`
-              }
-            ]
-          };
+          return mcpText(
+            `\u274C Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`
+          );
         }
         const safeWs = sanitize(ws);
         const safeRepo = sanitize(repo);
+        const auth = buildBasicAuth("BITBUCKET_USER_EMAIL", "BITBUCKET_API_TOKEN");
         const prUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}`;
-        const jsonData = await callBitbucketRestApi(prUrl);
+        const jsonData = await callRestApi(prUrl, auth);
         const parseResult = BitbucketPrSchema.safeParse(jsonData);
         if (!parseResult.success) {
           throw new Error(`Failed to parse PR response: ${parseResult.error.message}`);
@@ -21663,7 +21582,7 @@ function registerIntegrationTools(server2) {
 ${pr.description || "No description"}`;
         if (includeDiff) {
           const diffUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}/diff`;
-          const diff = await callBitbucketDiffApi(diffUrl);
+          const diff = await callRestApi(diffUrl, auth, "text/plain");
           const DIFF_FILE_THRESHOLD = 5e4;
           if (diff.length < DIFF_FILE_THRESHOLD) {
             output += `
@@ -21691,10 +21610,9 @@ ${diff}
             }
           }
         }
-        return { content: [{ type: "text", text: output }] };
+        return mcpText(output);
       } catch (error2) {
-        const errorMsg = error2 instanceof Error ? error2.message : String(error2);
-        return { content: [{ type: "text", text: errorMsg }] };
+        return mcpText(error2 instanceof Error ? error2.message : String(error2));
       }
     }
   );
@@ -21706,62 +21624,26 @@ ${diff}
     },
     async ({ ticketId }) => {
       try {
-        const cloudId = getCredential("ATLASSIAN_CLOUD_ID");
-        const userEmail = getCredential("ATLASSIAN_USER_EMAIL");
-        const apiToken = getCredential("ATLASSIAN_API_TOKEN");
-        if (!cloudId || !userEmail || !apiToken) {
-          const missing = [
-            !cloudId && "ATLASSIAN_CLOUD_ID",
-            !userEmail && "ATLASSIAN_USER_EMAIL",
-            !apiToken && "ATLASSIAN_API_TOKEN"
-          ].filter(Boolean).join(", ");
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C Missing ${missing}. Create an API Token at id.atlassian.com/manage-profile/security/api-tokens.`
-              }
-            ]
-          };
-        }
         const safeTicketId = ticketId.match(/^[A-Z]+-\d+$/)?.[0];
         if (!safeTicketId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C Invalid ticket ID format: ${ticketId}
+          return mcpText(`\u274C Invalid ticket ID format: ${ticketId}
 
-Expected format: PROJ-123`
-              }
-            ]
-          };
+Expected format: PROJ-123`);
         }
+        const cloudId = getCredential("ATLASSIAN_CLOUD_ID");
+        if (!cloudId) throw new Error("Missing ATLASSIAN_CLOUD_ID");
+        const auth = buildBasicAuth("ATLASSIAN_USER_EMAIL", "ATLASSIAN_API_TOKEN");
         const url = `https://api.atlassian.com/ex/jira/${cloudId}/rest/api/3/issue/${safeTicketId}`;
-        const jsonData = await callAtlassianRestApi(url);
+        const jsonData = await callRestApi(url, auth);
         const parseResult = JiraTicketSchema.safeParse(jsonData);
         if (!parseResult.success) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C Invalid Jira response format: ${parseResult.error.message}`
-              }
-            ]
-          };
+          return mcpText(`\u274C Invalid Jira response format: ${parseResult.error.message}`);
         }
         const ticket = parseResult.data;
         if (ticket.errorMessages && ticket.errorMessages.length > 0) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `\u274C Ticket not found: ${ticketId}
+          return mcpText(`\u274C Ticket not found: ${ticketId}
 
-${ticket.errorMessages.join("\n")}`
-              }
-            ]
-          };
+${ticket.errorMessages.join("\n")}`);
         }
         const output = `## \u{1F3AB} ${ticketId}: ${ticket.fields.summary}
 
@@ -21776,10 +21658,9 @@ ${typeof ticket.fields.description === "string" ? ticket.fields.description : ad
 
 ### Labels
 ${ticket.fields.labels?.join(", ") || "None"}`;
-        return { content: [{ type: "text", text: output }] };
+        return mcpText(output);
       } catch (error2) {
-        const errorMsg = error2 instanceof Error ? error2.message : String(error2);
-        return { content: [{ type: "text", text: `Error: ${errorMsg}` }] };
+        return mcpText(`Error: ${error2 instanceof Error ? error2.message : String(error2)}`);
       }
     }
   );

package/dist/tools/agent.d.ts

@@ -3,7 +3,4 @@
  * Supports handoff file injection and automatic fallback
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-/**
- * Register agent delegation tools with MCP server
- */
 export declare function registerAgentTools(server: McpServer): void;

package/dist/tools/agent.js

@@ -7,14 +7,11 @@ import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import { z } from 'zod';
-import { getWorkspaceRoot } from '../utils/utils.js';
+import { getWorkspaceRoot, mcpJson, mcpText } from '../utils/utils.js';
 import { commandExists, sanitizeOutput, validatePath } from './security.js';
 // Configurable timeout via environment variable (default: 5 minutes)
 const AGENT_TIMEOUT = parseInt(process.env.KIT_AGENT_TIMEOUT || '300000', 10);
 const jobRegistry = new Map();
-/**
- * Generate a URL-safe slug from a task string (first ~6 words, max 48 chars)
- */
 function taskSlug(task) {
     return task
         .toLowerCase()
@@ -25,11 +22,6 @@ function taskSlug(task) {
         .join('-')
         .slice(0, 48);
 }
-/**
- * Initialize a live-streaming log file for an agent job.
- * Writes the header synchronously so the file exists immediately,
- * then opens an append-mode WriteStream for real-time chunk writing.
- */
 function initAgentLog(workspaceRoot, slug, agent) {
     const logsDir = path.join(workspaceRoot, '.agent-kit', 'logs', 'agents');
     fs.mkdirSync(logsDir, { recursive: true });
@@ -41,25 +33,19 @@ function initAgentLog(workspaceRoot, slug, agent) {
     logStream.on('error', () => { });
     return { logPath: path.relative(workspaceRoot, logFile), logStream };
 }
-/**
- * Register agent delegation tools with MCP server
- */
 export function registerAgentTools(server) {
-    // ═══════════════════════════════════════════════════════════════
-    // TOOL: TRIGGER AGENT
-    // Delegates a task to an external agent CLI (gemini or claude).
-    // Auto-detects if task is a file path and reads it as context.
-    // Falls back to the alternate agent if requested one is missing.
-    // ═══════════════════════════════════════════════════════════════
     server.tool('kit_trigger_agent', '!Important: Trigger only when user explicitly asks to delegate a task to an external agent CLI (gemini or claude). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/plans/plan-xyz.md). Falls back to the other agent CLI if the requested one is not installed.', {
         agent: z.enum(['gemini', 'claude']).describe('The agent CLI to invoke: "gemini" or "claude"'),
         task: z
             .string()
             .describe('Task message or path to a handoff file (e.g., ".agent-kit/handoffs/plans/plan-xyz.md")'),
-    }, async ({ agent, task }) => {
+    }, async ({ agent, task }, extra) => {
+        const workspaceRoot = getWorkspaceRoot();
+        let job;
+        let logPath;
+        let killChild;
         try {
-            const workspaceRoot = getWorkspaceRoot();
-            // Detect if task is a file path — resolve and read if it exists
+            // Resolve task: read file if path, otherwise use as-is
             let prompt = task;
             const resolvedTask = path.resolve(workspaceRoot, task);
             if (fs.existsSync(resolvedTask) && fs.statSync(resolvedTask).isFile()) {
@@ -68,12 +54,10 @@ export function registerAgentTools(server) {
                     prompt = fs.readFileSync(resolvedTask, 'utf-8');
                 }
                 catch (err) {
-                    return {
-                        content: [{ type: 'text', text: `Error reading task file: ${err}` }],
-                    };
+                    return mcpText(`Error reading task file: ${err}`);
                 }
             }
-            // Determine which agent to use — fallback if requested not available
+            // Resolve agent with fallback
             let usedAgent = agent;
             let fallbackReason;
             if (!commandExists(agent)) {
@@ -86,105 +70,103 @@ export function registerAgentTools(server) {
                     const installHint = agent === 'gemini'
                         ? 'Install Gemini CLI: https://github.com/google-gemini/gemini-cli'
                         : 'Install Claude CLI: npm install -g @anthropic-ai/claude-code';
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    agent,
-                                    status: 'error',
-                                    output: '',
-                                    error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`,
-                                }, null, 2),
-                            },
-                        ],
-                    };
+                    return mcpJson({
+                        agent,
+                        status: 'error',
+                        output: '',
+                        error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`,
+                    });
                 }
             }
-            // Execute the agent CLI with the prompt
             // Gemini: -y (--yolo) for auto-accept, -p for headless prompt
             // Claude: --dangerously-skip-permissions for auto-accept, -p/--print for headless
             const agentArgs = usedAgent === 'gemini'
                 ? ['-y', '-p', prompt]
                 : ['--dangerously-skip-permissions', '-p', prompt];
-            const slug = taskSlug(task);
-            const { logPath, logStream } = initAgentLog(workspaceRoot, slug, usedAgent);
+            const { logPath: lp, logStream } = initAgentLog(workspaceRoot, taskSlug(task), usedAgent);
+            logPath = lp;
             const jobId = randomUUID();
+            // detached=true on Unix creates a new process group so we can kill the
+            // entire tree (CLI + its sub-agents) with process.kill(-pid, signal).
             const child = spawn(usedAgent, agentArgs, {
                 cwd: workspaceRoot,
                 env: { ...process.env, GEMINI_WORKSPACE: workspaceRoot },
+                detached: process.platform !== 'win32',
             });
-            const job = {
-                id: jobId,
+            const killTree = (sig) => {
+                if (process.platform !== 'win32' && child.pid) {
+                    try {
+                        process.kill(-child.pid, sig);
+                    }
+                    catch {
+                        child.kill(sig);
+                    }
+                }
+                else {
+                    child.kill(sig);
+                }
+            };
+            job = {
                 agent: usedAgent,
                 process: child,
                 startedAt: new Date(),
                 chunks: [],
                 logStream,
-                timeoutHandle: setTimeout(() => {
-                    child.kill('SIGTERM');
-                }, AGENT_TIMEOUT),
+                timeoutHandle: setTimeout(() => killTree('SIGTERM'), AGENT_TIMEOUT),
             };
             jobRegistry.set(jobId, job);
-            try {
-                await new Promise((resolve, reject) => {
-                    child.stdout?.on('data', (data) => {
-                        job.chunks.push(data.toString());
-                        job.logStream.write(data);
-                    });
-                    child.stderr?.on('data', (data) => {
-                        job.chunks.push(data.toString());
-                        job.logStream.write(data);
-                    });
-                    child.on('close', (code) => {
-                        if (code === 0)
-                            resolve();
-                        else
-                            reject(new Error(`Process exited with code ${code}`));
-                    });
-                    child.on('error', reject);
+            // Kill child if the MCP request is cancelled (e.g. user presses ESC)
+            killChild = () => {
+                killTree('SIGTERM');
+                setTimeout(() => killTree('SIGKILL'), 5000).unref();
+            };
+            if (extra.signal.aborted)
+                killChild();
+            else
+                extra.signal.addEventListener('abort', killChild);
+            await new Promise((resolve, reject) => {
+                child.stdout?.on('data', (data) => {
+                    job.chunks.push(data.toString());
+                    job.logStream.write(data);
                 });
-                const output = job.chunks.join('');
-                const safeOutput = sanitizeOutput(output);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                agent: usedAgent,
-                                status: fallbackReason ? 'fallback' : 'success',
-                                log: logPath,
-                                output: safeOutput,
-                                ...(fallbackReason && { fallback_reason: fallbackReason }),
-                            }, null, 2),
-                        },
-                    ],
-                };
-            }
-            catch (error) {
-                throw error;
-            }
-            finally {
-                job.logStream.end();
-                clearTimeout(job.timeoutHandle);
-                jobRegistry.delete(jobId);
-            }
+                child.stderr?.on('data', (data) => {
+                    job.chunks.push(data.toString());
+                    job.logStream.write(data);
+                });
+                child.on('close', (code, signal) => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`Process exited with code ${code}${signal ? ` (signal: ${signal})` : ''}`));
+                });
+                child.on('error', reject);
+            });
+            return mcpJson({
+                agent: usedAgent,
+                status: fallbackReason ? 'fallback' : 'success',
+                log: logPath,
+                output: sanitizeOutput(job.chunks.join('')),
+                ...(fallbackReason && { fallback_reason: fallbackReason }),
+            });
         }
         catch (error) {
+            if (extra.signal.aborted) {
+                return mcpJson({
+                    agent,
+                    status: 'cancelled',
+                    log: logPath,
+                    output: sanitizeOutput(job?.chunks.join('') ?? ''),
+                });
+            }
             const msg = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            agent,
-                            status: 'error',
-                            output: '',
-                            error: msg,
-                        }, null, 2),
-                    },
-                ],
-            };
+            return mcpJson({ agent, status: 'error', output: '', error: msg });
+        }
+        finally {
+            if (killChild)
+                extra.signal.removeEventListener('abort', killChild);
+            job?.logStream.end();
+            if (job)
+                clearTimeout(job.timeoutHandle);
         }
     });
 }

package/dist/tools/core.js

@@ -4,7 +4,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { z } from 'zod';
-import { getWorkspaceRoot } from '../utils/utils.js';
+import { getWorkspaceRoot, mcpText } from '../utils/utils.js';
 import { DEFAULT_EXTENSIONS } from './config.js';
 /**
  * Register core tools with MCP server
@@ -32,14 +32,10 @@ export function registerCoreTools(server) {
             }
             const filePath = path.join(handoffDir, filename);
             fs.writeFileSync(filePath, content, 'utf8');
-            return {
-                content: [{ type: 'text', text: `✅ Saved to: ${filePath}` }],
-            };
+            return mcpText(`✅ Saved to: ${filePath}`);
         }
         catch (error) {
-            return {
-                content: [{ type: 'text', text: `Error saving handoff: ${error}` }],
-            };
+            return mcpText(`Error saving handoff: ${error}`);
         }
     });
 }

package/dist/tools/integration.js

@@ -5,6 +5,7 @@
 import { writeFileSync } from 'fs';
 import { z } from 'zod';
 import { getCredential } from '../utils/credentials.js';
+import { mcpText } from '../utils/utils.js';
 import { adfToMarkdown } from '../utils/parser.js';
 import { sanitize } from './security.js';
 // Zod schema for Bitbucket PR REST API response
@@ -54,63 +55,22 @@ const JiraTicketSchema = z.object({
     errorMessages: z.array(z.string()).optional(),
     fields: JiraFieldsSchema,
 });
-function buildJiraBasicAuth() {
-    const email = getCredential('ATLASSIAN_USER_EMAIL');
-    const token = getCredential('ATLASSIAN_API_TOKEN');
-    if (!email || !token) {
-        throw new Error('Missing ATLASSIAN_USER_EMAIL or ATLASSIAN_API_TOKEN');
-    }
+function buildBasicAuth(emailVar, tokenVar) {
+    const email = getCredential(emailVar);
+    const token = getCredential(tokenVar);
+    if (!email || !token)
+        throw new Error(`Missing ${emailVar} or ${tokenVar}`);
     return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
 }
-function buildBitbucketBasicAuth() {
-    const email = getCredential('BITBUCKET_USER_EMAIL');
-    const token = getCredential('BITBUCKET_API_TOKEN');
-    if (!email || !token) {
-        throw new Error('Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN');
-    }
-    return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
-}
-async function callAtlassianRestApi(url) {
-    const auth = buildJiraBasicAuth();
-    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' } });
-    if (resp.status === 401) {
-        throw new Error('❌ Auth failed: check ATLASSIAN_USER_EMAIL and ATLASSIAN_API_TOKEN');
-    }
-    if (resp.status === 404) {
-        throw new Error(`❌ Not found: ${url}`);
-    }
-    if (!resp.ok) {
-        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
-    }
-    return await resp.json();
-}
-async function callBitbucketRestApi(url) {
-    const auth = buildBitbucketBasicAuth();
-    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' } });
-    if (resp.status === 401) {
-        throw new Error('❌ Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN');
-    }
-    if (resp.status === 404) {
-        throw new Error(`❌ Not found: ${url}`);
-    }
-    if (!resp.ok) {
-        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
-    }
-    return await resp.json();
-}
-async function callBitbucketDiffApi(url) {
-    const auth = buildBitbucketBasicAuth();
-    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'text/plain' } });
-    if (resp.status === 401) {
-        throw new Error('❌ Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN');
-    }
-    if (resp.status === 404) {
+async function callRestApi(url, auth, accept = 'application/json') {
+    const resp = await fetch(url, { headers: { Authorization: auth, Accept: accept } });
+    if (resp.status === 401)
+        throw new Error(`❌ Auth failed (401): ${url}`);
+    if (resp.status === 404)
         throw new Error(`❌ Not found: ${url}`);
-    }
-    if (!resp.ok) {
+    if (!resp.ok)
         throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
-    }
-    return await resp.text();
+    return accept === 'text/plain' ? resp.text() : resp.json();
 }
 export function registerIntegrationTools(server) {
     // TOOL: GET BITBUCKET PR
@@ -128,22 +88,9 @@ export function registerIntegrationTools(server) {
             .describe('Include unified diff in response'),
     }, async ({ input, workspace, repoSlug, includeDiff }) => {
         try {
-            const bbEmail = getCredential('BITBUCKET_USER_EMAIL');
-            const bbToken = getCredential('BITBUCKET_API_TOKEN');
-            if (!bbEmail || !bbToken) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN. Set them in ~/.claude/agent-kit or as environment variables.`,
-                        },
-                    ],
-                };
-            }
             let ws;
             let repo;
             let prId;
-            // Try URL parse
             const urlMatch = input.match(/bitbucket\.org\/([^/]+)\/([^/]+)\/pull-requests\/(\d+)/);
             if (urlMatch) {
                 ws = urlMatch[1];
@@ -156,29 +103,16 @@ export function registerIntegrationTools(server) {
                 repo = repoSlug;
             }
             if (!ws) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`);
             }
             if (!repo || !prId) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`);
             }
             const safeWs = sanitize(ws);
             const safeRepo = sanitize(repo);
+            const auth = buildBasicAuth('BITBUCKET_USER_EMAIL', 'BITBUCKET_API_TOKEN');
             const prUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}`;
-            const jsonData = await callBitbucketRestApi(prUrl);
+            const jsonData = await callRestApi(prUrl, auth);
             const parseResult = BitbucketPrSchema.safeParse(jsonData);
             if (!parseResult.success) {
                 throw new Error(`Failed to parse PR response: ${parseResult.error.message}`);
@@ -192,7 +126,7 @@ export function registerIntegrationTools(server) {
 ${pr.description || 'No description'}`;
             if (includeDiff) {
                 const diffUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}/diff`;
-                const diff = await callBitbucketDiffApi(diffUrl);
+                const diff = (await callRestApi(diffUrl, auth, 'text/plain'));
                 const DIFF_FILE_THRESHOLD = 50_000;
                 if (diff.length < DIFF_FILE_THRESHOLD) {
                     output += `\n\n### Diff\n\`\`\`diff\n${diff}\n\`\`\``;
@@ -208,11 +142,10 @@ ${pr.description || 'No description'}`;
                     }
                 }
             }
-            return { content: [{ type: 'text', text: output }] };
+            return mcpText(output);
         }
         catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
-            return { content: [{ type: 'text', text: errorMsg }] };
+            return mcpText(error instanceof Error ? error.message : String(error));
         }
     });
     // TOOL: JIRA GET TICKET
@@ -220,60 +153,23 @@ ${pr.description || 'No description'}`;
         ticketId: z.string().describe('Jira ticket ID (e.g., PROJ-123)'),
     }, async ({ ticketId }) => {
         try {
-            const cloudId = getCredential('ATLASSIAN_CLOUD_ID');
-            const userEmail = getCredential('ATLASSIAN_USER_EMAIL');
-            const apiToken = getCredential('ATLASSIAN_API_TOKEN');
-            if (!cloudId || !userEmail || !apiToken) {
-                const missing = [
-                    !cloudId && 'ATLASSIAN_CLOUD_ID',
-                    !userEmail && 'ATLASSIAN_USER_EMAIL',
-                    !apiToken && 'ATLASSIAN_API_TOKEN',
-                ]
-                    .filter(Boolean)
-                    .join(', ');
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Missing ${missing}. Create an API Token at id.atlassian.com/manage-profile/security/api-tokens.`,
-                        },
-                    ],
-                };
-            }
             const safeTicketId = ticketId.match(/^[A-Z]+-\d+$/)?.[0];
             if (!safeTicketId) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Invalid ticket ID format: ${ticketId}\n\nExpected format: PROJ-123`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Invalid ticket ID format: ${ticketId}\n\nExpected format: PROJ-123`);
             }
+            const cloudId = getCredential('ATLASSIAN_CLOUD_ID');
+            if (!cloudId)
+                throw new Error('Missing ATLASSIAN_CLOUD_ID');
+            const auth = buildBasicAuth('ATLASSIAN_USER_EMAIL', 'ATLASSIAN_API_TOKEN');
             const url = `https://api.atlassian.com/ex/jira/${cloudId}/rest/api/3/issue/${safeTicketId}`;
-            const jsonData = await callAtlassianRestApi(url);
+            const jsonData = await callRestApi(url, auth);
             const parseResult = JiraTicketSchema.safeParse(jsonData);
             if (!parseResult.success) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Invalid Jira response format: ${parseResult.error.message}`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Invalid Jira response format: ${parseResult.error.message}`);
             }
             const ticket = parseResult.data;
             if (ticket.errorMessages && ticket.errorMessages.length > 0) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Ticket not found: ${ticketId}\n\n${ticket.errorMessages.join('\n')}`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Ticket not found: ${ticketId}\n\n${ticket.errorMessages.join('\n')}`);
             }
             const output = `## 🎫 ${ticketId}: ${ticket.fields.summary}
 
@@ -290,11 +186,10 @@ ${typeof ticket.fields.description === 'string'
 
 ### Labels
 ${ticket.fields.labels?.join(', ') || 'None'}`;
-            return { content: [{ type: 'text', text: output }] };
+            return mcpText(output);
         }
         catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }] };
+            return mcpText(`Error: ${error instanceof Error ? error.message : String(error)}`);
         }
     });
 }

package/dist/utils/utils.d.ts

@@ -1 +1,10 @@
 export declare function getWorkspaceRoot(): string;
+type McpTextResult = {
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+};
+export declare function mcpText(text: string): McpTextResult;
+export declare function mcpJson(obj: unknown): McpTextResult;
+export {};

package/dist/utils/utils.js

@@ -6,3 +6,9 @@ export function getWorkspaceRoot() {
         process.env.PWD ||
         process.cwd());
 }
+export function mcpText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+export function mcpJson(obj) {
+    return mcpText(JSON.stringify(obj, null, 2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanhnd/agent-kit",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "Super Engineer - Team of AI Agents for software development (Claude Code Plugin)",
   "type": "module",
   "main": "dist/kit-server.js",