cortex-agents 3.4.0 → 4.0.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import * as path from "path";
 import { fileURLToPath } from "url";
 import prompts from "prompts";
 import { PRIMARY_AGENTS, SUBAGENTS, ALL_AGENTS, DISABLED_BUILTIN_AGENTS, STALE_AGENT_FILES, getPrimaryChoices, getSubagentChoices, } from "./registry.js";
-const VERSION = "3.4.0";
+const VERSION = "4.0.0";
 const PLUGIN_NAME = "cortex-agents";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -395,7 +395,7 @@ async function promptModelSelection() {
         description: "provider/model format",
         value: "__custom__",
     });
-    console.log("Primary agents (implement, architect, fix, audit) handle complex tasks.\nUse your best available model.\n");
+    console.log("Primary agents (architect, implement, fix) handle complex tasks.\nUse your best available model.\n");
     const { primaryModel } = await prompts({
         type: "select",
         name: "primaryModel",
@@ -429,7 +429,7 @@ async function promptModelSelection() {
         description: "provider/model format",
         value: "__custom__",
     });
-    console.log("Subagents (crosslayer, qa, guard, ship) handle focused tasks.\nA faster/cheaper model works great here.\n");
+    console.log("Subagents (debug, coder, testing, security, devops, audit) handle focused tasks.\nA faster/cheaper model works great here.\n");
     const { subagentModel } = await prompts({
         type: "select",
         name: "subagentModel",
@@ -631,20 +631,17 @@ EXAMPLES:
   npx ${PLUGIN_NAME} status                     # Check status
 
 AGENTS:
-  Primary (implement, architect, fix, audit):
+  Primary (architect, implement, fix):
     Handle complex tasks — select your best model.
 
-  Subagents (crosslayer, qa, guard, ship):
+  Subagents (debug, coder, testing, security, devops, audit):
     Handle focused tasks — a fast/cheap model works great.
 
-TOOLS (32):
+TOOLS (29):
   cortex_init, cortex_status      .cortex directory management
   cortex_configure                Per-project model configuration
   worktree_create, worktree_list  Git worktree management
   worktree_remove, worktree_open
-  worktree_launch                 Launch worktree (terminal/PTY/background)
-  detect_environment              Detect IDE/terminal for launch options
-  get_environment_info            Quick environment info for agents
   branch_create, branch_status    Git branch operations
   branch_switch
   plan_save, plan_list            Plan persistence

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAiLlD,eAAO,MAAM,YAAY,EAAE,MAsK1B,CAAC;AAGF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AA+LlD,eAAO,MAAM,YAAY,EAAE,MAkJ1B,CAAC;AAGF,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -6,19 +6,23 @@ import * as plan from "./tools/plan";
 import * as session from "./tools/session";
 import * as docs from "./tools/docs";
 import * as task from "./tools/task";
-import * as environment from "./tools/environment";
 import * as github from "./tools/github";
 import * as repl from "./tools/repl";
+import * as qualityGate from "./tools/quality-gate";
 // ─── Agent Descriptions (for handover toasts) ───────────────────────────────
 const AGENT_DESCRIPTIONS = {
     implement: "Development mode — ready to implement",
     architect: "Planning mode — read-only analysis",
-    fix: "Debug mode — troubleshooting and fixes",
-    audit: "Review mode — code quality assessment",
-    crosslayer: "Crosslayer subagent — end-to-end implementation",
-    qa: "QA subagent — writing tests",
-    guard: "Security subagent — vulnerability audit",
-    ship: "DevOps subagent — CI/CD and deployment",
+    fix: "Quick fix mode — fast turnaround",
+    debug: "Debug subagent — root cause analysis",
+    coder: "Coder subagent — multi-layer implementation",
+    testing: "Testing subagent — writing tests",
+    security: "Security subagent — vulnerability audit",
+    devops: "DevOps subagent — CI/CD and deployment",
+    audit: "Audit subagent — code quality assessment",
+    refactor: "Refactor subagent — behavior-preserving restructuring",
+    "docs-writer": "Docs subagent — documentation generation",
+    perf: "Perf subagent — performance analysis",
 };
 const TOOL_NOTIFICATIONS = {
     task_finalize: {
@@ -44,6 +48,7 @@ const TOOL_NOTIFICATIONS = {
         errorTitle: "Plan Delete Failed",
         errorMsg: (_, out) => out.substring(0, 100),
     },
+    // plan_commit — excluded: uses factory-based toasts in createCommit()
     session_save: {
         successTitle: "Session Saved",
         successMsg: () => "Session summary recorded",
@@ -107,6 +112,16 @@ const TOOL_NOTIFICATIONS = {
         errorTitle: "Report Failed",
         errorMsg: (_, out) => out.substring(0, 100),
     },
+    quality_gate_summary: {
+        successTitle: "Quality Gate",
+        successMsg: (_args, output) => {
+            const recMatch = output.match(/\*\*Recommendation:\s*(GO|NO-GO|GO-WITH-WARNINGS)\*\*/);
+            return recMatch ? `Recommendation: ${recMatch[1]}` : "Summary generated";
+        },
+        errorTitle: "Quality Gate Failed",
+        errorMsg: (_, out) => out.substring(0, 100),
+        successDuration: 5000,
+    },
 };
 // ─── Error Message Extraction ────────────────────────────────────────────────
 //
@@ -145,7 +160,6 @@ export const CortexPlugin = async (ctx) => {
             worktree_list: worktree.list,
             worktree_remove: worktree.createRemove(ctx.client),
             worktree_open: worktree.open,
-            worktree_launch: worktree.createLaunch(ctx.client, ctx.$),
             // Branch tools - git branch operations (factory for toast notifications)
             branch_create: branch.createCreate(ctx.client),
             branch_status: branch.status,
@@ -155,6 +169,7 @@ export const CortexPlugin = async (ctx) => {
             plan_list: plan.list,
             plan_load: plan.load,
             plan_delete: plan.delete_,
+            plan_commit: plan.createCommit(ctx.client),
             // Session tools - session summaries with decisions
             session_save: session.save,
             session_list: session.list,
@@ -166,9 +181,6 @@ export const CortexPlugin = async (ctx) => {
             docs_index: docs.index,
             // Task tools - finalize workflow (commit, push, PR)
             task_finalize: task.finalize,
-            // Environment tools - IDE/terminal detection for contextual options
-            detect_environment: environment.detectEnvironment,
-            get_environment_info: environment.getEnvironmentInfo,
             // GitHub integration tools - work item listing, issue selection, project boards
             github_status: github.status,
             github_issues: github.issues,
@@ -177,7 +189,10 @@ export const CortexPlugin = async (ctx) => {
             repl_init: repl.init,
             repl_status: repl.status,
             repl_report: repl.report,
+            repl_resume: repl.resume,
             repl_summary: repl.summary,
+            // Quality gate aggregation tool
+            quality_gate_summary: qualityGate.qualityGateSummary,
         },
         // ── Post-execution toast notifications ────────────────────────────────
         //
@@ -256,23 +271,6 @@ export const CortexPlugin = async (ctx) => {
                         },
                     });
                 }
-                // PTY exited notifications (relevant for worktree terminal sessions)
-                if (event.type === "pty.exited") {
-                    const rawExitCode = event.properties.exitCode;
-                    const exitCode = typeof rawExitCode === "number" && Number.isInteger(rawExitCode)
-                        ? rawExitCode
-                        : -1;
-                    await ctx.client.tui.showToast({
-                        body: {
-                            title: "Terminal Exited",
-                            message: exitCode === 0
-                                ? "Terminal session completed successfully"
-                                : `Terminal exited with code ${exitCode}`,
-                            variant: exitCode === 0 ? "success" : "warning",
-                            duration: exitCode === 0 ? 4000 : 8000,
-                        },
-                    });
-                }
             }
             catch {
                 // Toast failure is non-fatal — silently ignore

package/dist/registry.d.ts

@@ -19,16 +19,16 @@ export interface ModelEntry {
 }
 export declare const MODEL_REGISTRY: ModelEntry[];
 /** Primary agents receive the best available model */
-export declare const PRIMARY_AGENTS: readonly ["implement", "architect", "fix", "audit"];
+export declare const PRIMARY_AGENTS: readonly ["architect", "implement", "fix"];
 /** Subagents receive a fast/cost-effective model */
-export declare const SUBAGENTS: readonly ["crosslayer", "qa", "guard", "ship"];
+export declare const SUBAGENTS: readonly ["debug", "coder", "testing", "security", "devops", "audit", "refactor", "docs-writer", "perf"];
 /** All agent names combined */
-export declare const ALL_AGENTS: readonly ["implement", "architect", "fix", "audit", "crosslayer", "qa", "guard", "ship"];
+export declare const ALL_AGENTS: readonly ["architect", "implement", "fix", "debug", "coder", "testing", "security", "devops", "audit", "refactor", "docs-writer", "perf"];
 /** OpenCode built-in agents disabled when cortex-agents is installed.
  *  Replaced by cortex equivalents: build → implement, plan → architect */
 export declare const DISABLED_BUILTIN_AGENTS: readonly ["build", "plan"];
 /** Old agent files to clean up from previous cortex-agents versions */
-export declare const STALE_AGENT_FILES: readonly ["build.md", "plan.md", "debug.md", "review.md", "fullstack.md", "testing.md", "security.md", "devops.md"];
+export declare const STALE_AGENT_FILES: readonly ["build.md", "plan.md", "review.md", "fullstack.md", "crosslayer.md", "qa.md", "guard.md", "ship.md"];
 /**
  * Build the interactive choices list for primary model selection.
  * Shows premium and standard tier models (excluding fast).

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,cAAc,EAAE,UAAU,EAuGtC,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,cAAc,qDAAsD,CAAC;AAElF,oDAAoD;AACpD,eAAO,MAAM,SAAS,gDAAiD,CAAC;AAExE,+BAA+B;AAC/B,eAAO,MAAM,UAAU,0FAA6C,CAAC;AAErE;0EAC0E;AAC1E,eAAO,MAAM,uBAAuB,4BAA6B,CAAC;AAElE,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,qHASpB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,iBAAiB;;;;IAMhC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM;;;;IAcxD"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,cAAc,EAAE,UAAU,EAuGtC,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,cAAc,4CAA6C,CAAC;AAEzE,oDAAoD;AACpD,eAAO,MAAM,SAAS,0GAA2G,CAAC;AAElI,+BAA+B;AAC/B,eAAO,MAAM,UAAU,2IAA6C,CAAC;AAErE;0EAC0E;AAC1E,eAAO,MAAM,uBAAuB,4BAA6B,CAAC;AAElE,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,gHASpB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,iBAAiB;;;;IAMhC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM;;;;IAcxD"}

package/dist/registry.js

@@ -105,9 +105,9 @@ export const MODEL_REGISTRY = [
     },
 ];
 /** Primary agents receive the best available model */
-export const PRIMARY_AGENTS = ["implement", "architect", "fix", "audit"];
+export const PRIMARY_AGENTS = ["architect", "implement", "fix"];
 /** Subagents receive a fast/cost-effective model */
-export const SUBAGENTS = ["crosslayer", "qa", "guard", "ship"];
+export const SUBAGENTS = ["debug", "coder", "testing", "security", "devops", "audit", "refactor", "docs-writer", "perf"];
 /** All agent names combined */
 export const ALL_AGENTS = [...PRIMARY_AGENTS, ...SUBAGENTS];
 /** OpenCode built-in agents disabled when cortex-agents is installed.
@@ -117,12 +117,12 @@ export const DISABLED_BUILTIN_AGENTS = ["build", "plan"];
 export const STALE_AGENT_FILES = [
     "build.md",
     "plan.md",
-    "debug.md",
     "review.md",
     "fullstack.md",
-    "testing.md",
-    "security.md",
-    "devops.md",
+    "crosslayer.md",
+    "qa.md",
+    "guard.md",
+    "ship.md",
 ];
 /**
  * Build the interactive choices list for primary model selection.

package/dist/tools/branch.d.ts

@@ -9,10 +9,10 @@ export declare function createCreate(client: Client): {
     args: {
         name: import("zod").ZodString;
         type: import("zod").ZodEnum<{
+            refactor: "refactor";
             feature: "feature";
             bugfix: "bugfix";
             hotfix: "hotfix";
-            refactor: "refactor";
             docs: "docs";
             test: "test";
             chore: "chore";
@@ -20,7 +20,7 @@ export declare function createCreate(client: Client): {
     };
     execute(args: {
         name: string;
-        type: "feature" | "bugfix" | "hotfix" | "refactor" | "docs" | "test" | "chore";
+        type: "refactor" | "feature" | "bugfix" | "hotfix" | "docs" | "test" | "chore";
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const status: {

package/dist/tools/docs.d.ts

@@ -35,13 +35,13 @@ export declare const list: {
     args: {
         type: import("zod").ZodOptional<import("zod").ZodEnum<{
             feature: "feature";
-            all: "all";
             decision: "decision";
+            all: "all";
             flow: "flow";
         }>>;
     };
     execute(args: {
-        type?: "feature" | "all" | "decision" | "flow" | undefined;
+        type?: "feature" | "decision" | "all" | "flow" | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const index: {

package/dist/tools/github.d.ts

@@ -7,9 +7,9 @@ export declare const issues: {
     description: string;
     args: {
         state: import("zod").ZodOptional<import("zod").ZodEnum<{
-            closed: "closed";
-            open: "open";
             all: "all";
+            open: "open";
+            closed: "closed";
         }>>;
         labels: import("zod").ZodOptional<import("zod").ZodString>;
         milestone: import("zod").ZodOptional<import("zod").ZodString>;
@@ -18,7 +18,7 @@ export declare const issues: {
         detailed: import("zod").ZodOptional<import("zod").ZodBoolean>;
     };
     execute(args: {
-        state?: "closed" | "open" | "all" | undefined;
+        state?: "all" | "open" | "closed" | undefined;
         labels?: string | undefined;
         milestone?: string | undefined;
         assignee?: string | undefined;

package/dist/tools/plan.d.ts

@@ -1,32 +1,36 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+type Client = PluginInput["client"];
 export declare const save: {
     description: string;
     args: {
         title: import("zod").ZodString;
         type: import("zod").ZodEnum<{
+            refactor: "refactor";
             feature: "feature";
             bugfix: "bugfix";
-            refactor: "refactor";
             spike: "spike";
             docs: "docs";
             architecture: "architecture";
         }>;
         content: import("zod").ZodString;
         tasks: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        branch: import("zod").ZodOptional<import("zod").ZodString>;
     };
     execute(args: {
         title: string;
-        type: "feature" | "bugfix" | "refactor" | "spike" | "docs" | "architecture";
+        type: "refactor" | "feature" | "bugfix" | "spike" | "docs" | "architecture";
         content: string;
         tasks?: string[] | undefined;
+        branch?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const list: {
     description: string;
     args: {
         type: import("zod").ZodOptional<import("zod").ZodEnum<{
+            refactor: "refactor";
             feature: "feature";
             bugfix: "bugfix";
-            refactor: "refactor";
             spike: "spike";
             docs: "docs";
             architecture: "architecture";
@@ -34,7 +38,7 @@ export declare const list: {
         }>>;
     };
     execute(args: {
-        type?: "feature" | "bugfix" | "refactor" | "spike" | "docs" | "architecture" | "all" | undefined;
+        type?: "refactor" | "feature" | "bugfix" | "spike" | "docs" | "architecture" | "all" | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 export declare const load: {
@@ -55,5 +59,25 @@ export declare const delete_: {
         filename: string;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
+/**
+ * Factory function that creates the plan_commit tool with access
+ * to the OpenCode client for toast notifications.
+ *
+ * Creates a git branch from plan metadata, stages .cortex/ artifacts,
+ * commits them, and writes the branch name back into the plan frontmatter.
+ */
+export declare function createCommit(client: Client): {
+    description: string;
+    args: {
+        planFilename: import("zod").ZodString;
+        branchType: import("zod").ZodOptional<import("zod").ZodString>;
+        branchName: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        planFilename: string;
+        branchType?: string | undefined;
+        branchName?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
 export { delete_ as delete };
 //# sourceMappingURL=plan.d.ts.map

package/dist/tools/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;CA2Df,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;CAkEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CAuBf,CAAC;AAEH,eAAO,MAAM,OAAO;;;;;;;;CAkBlB,CAAC;AAGH,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAgBvD,KAAK,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AA2BpC,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;CAgEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;CAkEf,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;CA6Bf,CAAC;AAEH,eAAO,MAAM,OAAO;;;;;;;;CAwBlB,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM;;;;;;;;;;;;EAsN1C;AAGD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC"}

package/dist/tools/plan.js

@@ -1,8 +1,11 @@
 import { tool } from "@opencode-ai/plugin";
 import * as fs from "fs";
 import * as path from "path";
+import { git } from "../utils/shell.js";
+import { TYPE_TO_PREFIX, parseFrontmatter, upsertFrontmatterField, } from "../utils/plan-extract.js";
 const CORTEX_DIR = ".cortex";
 const PLANS_DIR = "plans";
+const PROTECTED_BRANCHES = ["main", "master", "develop", "production", "staging"];
 function slugify(text) {
     return text
         .toLowerCase()
@@ -37,20 +40,25 @@ export const save = tool({
             .array(tool.schema.string())
             .optional()
             .describe("Optional list of tasks"),
+        branch: tool.schema
+            .string()
+            .optional()
+            .describe("Optional branch name to store in frontmatter (set by plan_commit)"),
     },
     async execute(args, context) {
-        const { title, type, content, tasks } = args;
+        const { title, type, content, tasks, branch } = args;
         const plansPath = ensureCortexDir(context.worktree);
         const datePrefix = getDatePrefix();
         const slug = slugify(title);
         const filename = `${datePrefix}-${type}-${slug}.md`;
         const filepath = path.join(plansPath, filename);
         // Build frontmatter
+        const branchLine = branch ? `\nbranch: ${branch}` : "";
         const frontmatter = `---
 title: "${title}"
 type: ${type}
 created: ${new Date().toISOString()}
-status: draft
+status: draft${branchLine}
 ---
 
 `;
@@ -144,7 +152,12 @@ export const load = tool({
     async execute(args, context) {
         const { filename } = args;
         const plansPath = path.join(context.worktree, CORTEX_DIR, PLANS_DIR);
-        const filepath = path.join(plansPath, filename);
+        const filepath = path.resolve(plansPath, filename);
+        const resolvedPlansDir = path.resolve(plansPath);
+        // Prevent path traversal (../ or absolute paths)
+        if (!filepath.startsWith(resolvedPlansDir + path.sep)) {
+            return `✗ Invalid plan filename: path traversal not allowed`;
+        }
         if (!fs.existsSync(filepath)) {
             return `✗ Plan not found: ${filename}
 
@@ -165,7 +178,12 @@ export const delete_ = tool({
     async execute(args, context) {
         const { filename } = args;
         const plansPath = path.join(context.worktree, CORTEX_DIR, PLANS_DIR);
-        const filepath = path.join(plansPath, filename);
+        const filepath = path.resolve(plansPath, filename);
+        const resolvedPlansDir = path.resolve(plansPath);
+        // Prevent path traversal (../ or absolute paths)
+        if (!filepath.startsWith(resolvedPlansDir + path.sep)) {
+            return `✗ Invalid plan filename: path traversal not allowed`;
+        }
         if (!fs.existsSync(filepath)) {
             return `✗ Plan not found: ${filename}`;
         }
@@ -173,5 +191,215 @@ export const delete_ = tool({
         return `✓ Deleted plan: ${filename}`;
     },
 });
+/**
+ * Factory function that creates the plan_commit tool with access
+ * to the OpenCode client for toast notifications.
+ *
+ * Creates a git branch from plan metadata, stages .cortex/ artifacts,
+ * commits them, and writes the branch name back into the plan frontmatter.
+ */
+export function createCommit(client) {
+    return tool({
+        description: "Create a git branch from a saved plan, commit .cortex/ artifacts to it, and " +
+            "write the branch name into the plan frontmatter. Keeps main clean.",
+        args: {
+            planFilename: tool.schema
+                .string()
+                .describe("Plan filename from .cortex/plans/ (e.g., '2026-02-26-feature-auth.md')"),
+            branchType: tool.schema
+                .string()
+                .optional()
+                .describe("Override branch prefix (default: derived from plan type)"),
+            branchName: tool.schema
+                .string()
+                .optional()
+                .describe("Override branch slug (default: derived from plan title)"),
+        },
+        async execute(args, context) {
+            const { planFilename, branchType, branchName: nameOverride } = args;
+            const cwd = context.worktree;
+            // ── 1. Validate: git repo ─────────────────────────────────
+            try {
+                await git(cwd, "rev-parse", "--git-dir");
+            }
+            catch {
+                return "✗ Error: Not in a git repository. Initialize git first.";
+            }
+            // ── 2. Read and parse the plan ────────────────────────────
+            const plansPath = path.join(cwd, CORTEX_DIR, PLANS_DIR);
+            const filepath = path.resolve(plansPath, planFilename);
+            const resolvedPlansDir = path.resolve(plansPath);
+            // Prevent path traversal (../ or absolute paths)
+            if (!filepath.startsWith(resolvedPlansDir + path.sep)) {
+                return `✗ Invalid plan filename: path traversal not allowed`;
+            }
+            if (!fs.existsSync(filepath)) {
+                return `✗ Plan not found: ${planFilename}
+
+Use plan_list to see available plans.`;
+            }
+            let planContent = fs.readFileSync(filepath, "utf-8");
+            const fm = parseFrontmatter(planContent);
+            if (!fm) {
+                return `✗ Plan has no frontmatter: ${planFilename}
+
+Expected YAML frontmatter with title and type fields.`;
+            }
+            const planTitle = fm.title || "untitled";
+            const planType = fm.type || "feature";
+            // ── 3. Determine branch name ──────────────────────────────
+            const VALID_PREFIXES = Object.values(TYPE_TO_PREFIX);
+            const rawPrefix = branchType || TYPE_TO_PREFIX[planType] || "feature";
+            const prefix = VALID_PREFIXES.includes(rawPrefix) ? rawPrefix : "feature";
+            // Always sanitize name through slugify (even overrides)
+            const slug = slugify(nameOverride || planTitle);
+            const fullBranchName = `${prefix}/${slug}`;
+            // ── 4. Check current branch ───────────────────────────────
+            let currentBranch = "";
+            try {
+                const { stdout } = await git(cwd, "branch", "--show-current");
+                currentBranch = stdout.trim();
+            }
+            catch {
+                currentBranch = "";
+            }
+            const isOnProtected = PROTECTED_BRANCHES.includes(currentBranch);
+            let branchCreated = false;
+            // ── 5. Create or switch to branch ─────────────────────────
+            if (isOnProtected || !currentBranch) {
+                // Try to create the branch
+                try {
+                    await git(cwd, "checkout", "-b", fullBranchName);
+                    branchCreated = true;
+                }
+                catch {
+                    // Branch may already exist — try switching to it
+                    try {
+                        await git(cwd, "checkout", fullBranchName);
+                    }
+                    catch (switchErr) {
+                        try {
+                            await client.tui.showToast({
+                                body: {
+                                    title: `Plan Commit: ${planFilename}`,
+                                    message: `Failed to create/switch branch: ${switchErr.message || switchErr}`,
+                                    variant: "error",
+                                    duration: 8000,
+                                },
+                            });
+                        }
+                        catch {
+                            // Toast failure is non-fatal
+                        }
+                        return `✗ Error creating branch '${fullBranchName}': ${switchErr.message || switchErr}
+
+You may have uncommitted changes. Commit or stash them first.`;
+                    }
+                }
+            }
+            // If already on a non-protected branch, skip branch creation
+            // ── 6. Update plan frontmatter with branch ────────────────
+            // If we created/switched to a new branch → use that name
+            // If already on a non-protected branch → use whatever we're on
+            const targetBranch = (isOnProtected || branchCreated) ? fullBranchName : currentBranch;
+            planContent = upsertFrontmatterField(planContent, "branch", targetBranch);
+            fs.writeFileSync(filepath, planContent);
+            // ── 7. Stage .cortex/ directory ───────────────────────────
+            try {
+                await git(cwd, "add", path.join(cwd, CORTEX_DIR));
+            }
+            catch (stageErr) {
+                return `✗ Error staging .cortex/ directory: ${stageErr.message || stageErr}`;
+            }
+            // ── 8. Commit ─────────────────────────────────────────────
+            const commitMsg = `chore(plan): ${planTitle}`;
+            let commitHash = "";
+            try {
+                // Check if there's anything staged
+                const { stdout: statusOut } = await git(cwd, "status", "--porcelain");
+                const stagedLines = statusOut
+                    .trim()
+                    .split("\n")
+                    .filter((l) => l && l[0] !== " " && l[0] !== "?");
+                if (stagedLines.length === 0) {
+                    // Nothing to commit — plan already committed
+                    try {
+                        const { stdout: hashOut } = await git(cwd, "rev-parse", "--short", "HEAD");
+                        commitHash = hashOut.trim();
+                    }
+                    catch {
+                        commitHash = "(unknown)";
+                    }
+                    try {
+                        await client.tui.showToast({
+                            body: {
+                                title: `Plan: ${targetBranch}`,
+                                message: "Already committed — no new changes",
+                                variant: "info",
+                                duration: 4000,
+                            },
+                        });
+                    }
+                    catch {
+                        // Toast failure is non-fatal
+                    }
+                    return `✓ Plan already committed on branch: ${targetBranch}
+
+Branch: ${targetBranch}
+Commit: ${commitHash} (no new changes)
+Plan: ${planFilename}
+
+The plan branch is ready for implementation.
+Use worktree_create or switch to the Implement agent.`;
+                }
+                await git(cwd, "commit", "-m", commitMsg);
+                const { stdout: hashOut } = await git(cwd, "rev-parse", "--short", "HEAD");
+                commitHash = hashOut.trim();
+            }
+            catch (commitErr) {
+                try {
+                    await client.tui.showToast({
+                        body: {
+                            title: `Plan Commit`,
+                            message: `Commit failed: ${commitErr.message || commitErr}`,
+                            variant: "error",
+                            duration: 8000,
+                        },
+                    });
+                }
+                catch {
+                    // Toast failure is non-fatal
+                }
+                return `✗ Error committing: ${commitErr.message || commitErr}`;
+            }
+            // ── 9. Success notification ───────────────────────────────
+            try {
+                await client.tui.showToast({
+                    body: {
+                        title: `Plan Committed`,
+                        message: `${targetBranch} — ${commitHash}`,
+                        variant: "success",
+                        duration: 5000,
+                    },
+                });
+            }
+            catch {
+                // Toast failure is non-fatal
+            }
+            return `✓ Plan committed to branch
+
+Branch: ${targetBranch}${branchCreated ? " (created)" : ""}
+Commit: ${commitHash} — ${commitMsg}
+Plan: ${planFilename}
+
+The plan and .cortex/ artifacts are committed on '${targetBranch}'.
+Main branch is clean.
+
+Next steps:
+  • Switch to Implement agent to begin coding
+  • Or use worktree_create to work in an isolated copy`;
+        },
+    });
+}
 // Export with underscore suffix to avoid reserved word
 export { delete_ as delete };