@aryaminus/controlkeel-opencode 0.1.27 → 0.1.29

package/.opencode/agents/controlkeel-operator.md

@@ -11,7 +11,7 @@ and validate them against the project's security, budget, and compliance policie
 
 ## Instructions
 
-1. Use the `ck-validate` tool to run governance checks before providing feedback.
+1. Use `ck_context` first, then `ck_validate` before providing feedback.
 2. Report findings by severity: critical > high > medium > low.
 3. Never approve changes that have unresolved critical or high findings.
 4. Reference specific policy rules when flagging issues.
@@ -19,7 +19,10 @@ and validate them against the project's security, budget, and compliance policie
 
 ## Available MCP Tools
 
+- `ck_context` — Load mission, findings, budget, and proof context
 - `ck_validate` — Run full governance validation
+- `ck_finding` — Record a governed finding when you detect a missed issue
+- `ck_review_submit` — Submit review material for human approval
+- `ck_review_status` — Check review status before execution
 - `ck_budget` — Check remaining budget and spend history
-- `ck_findings` — List open findings for the current session
-- `ck_approve` — Approve a finding (requires operator confirmation)
+- `ck_route` — Ask ControlKeel for the recommended specialist route

package/.opencode/commands/controlkeel-review.md

@@ -3,7 +3,7 @@ description: Run ControlKeel governance review on the current project
 agent: controlkeel-operator
 ---
 
-Review the current project for governance compliance. Run `ck-validate` to check
+Review the current project for governance compliance. Run `ck_validate` to check
 for security findings, budget status, and proof readiness. Summarize the results
 and highlight any blockers that need attention before shipping.
 

package/.opencode/commands/controlkeel-submit-plan.md

@@ -6,7 +6,12 @@ Save the current plan to a markdown file, then submit it through ControlKeel.
 
 Recommended flow:
 1. Save the plan to `.opencode/review-plan.md`
-2. Run `controlkeel review plan submit --body-file .opencode/review-plan.md --submitted-by opencode --json`
-3. Read the returned `review.id` and `browser_url`
-4. Wait with `controlkeel review plan wait --id <review_id> --json`
-4. Do not execute until the review is approved
+2. Ensure `controlkeel version` reports `>= 0.1.26`
+3. Run `controlkeel review plan submit --body-file .opencode/review-plan.md --submitted-by opencode --task-id <task_id> --json` (or use `--session-id <session_id>`)
+4. Read the returned `review.id` and `browser_url`
+5. Wait with `controlkeel review plan wait --id <review_id> --timeout 30 --json`
+6. Do not execute until the review is approved
+
+Fallback when the `submit_plan` tool is stale in a long-running OpenCode session:
+- If the tool returns an error like `ControlKeel CLI [object Object] is too old`, run the CLI flow above directly.
+- Restart OpenCode after plugin updates so `.opencode/plugins/controlkeel-governance.ts` is reloaded.

package/.opencode/mcp.json

@@ -1,12 +1,13 @@
 {
-  "mcpServers": {
+  "mcp": {
     "controlkeel": {
-      "args": [
+      "command": [
+        "controlkeel",
         "mcp",
         "--project-root",
         "."
       ],
-      "command": "controlkeel"
+      "type": "local"
     }
   }
 }

package/.opencode/plugins/controlkeel-governance.ts

@@ -19,29 +19,185 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
     }
   }
 
-  const submitPlan = async (body: string, submittedBy: string) => {
-    const result = await $`controlkeel review plan submit --stdin --submitted-by ${submittedBy} --json`
-      .text(body)
-    const submitPayload = parseJson(result)
-    const reviewId = submitPayload?.review?.id
-    if (!reviewId) {
-      throw new Error("ControlKeel did not return a review id")
+  const toText = async (output: unknown) => {
+    if (typeof output === "string") {
+      return output
     }
-    const waitPayload = parseJson(await $`controlkeel review plan wait --id ${reviewId} --json`)
+
+    if (output instanceof Uint8Array) {
+      return new TextDecoder().decode(output)
+    }
+
+    if (output instanceof ArrayBuffer) {
+      return new TextDecoder().decode(new Uint8Array(output))
+    }
+
+    if (output == null) {
+      return ""
+    }
+
+    if (typeof output === "object") {
+      if (typeof (output as { text?: unknown }).text === "function") {
+        try {
+          const direct = await (output as { text: () => Promise<string> }).text()
+          if (typeof direct === "string") {
+            return direct
+          }
+        } catch (_error) {
+        }
+      }
+
+      const stdout = (output as { stdout?: unknown }).stdout
+      if (typeof stdout === "string") {
+        return stdout
+      }
+
+      if (stdout instanceof Uint8Array) {
+        return new TextDecoder().decode(stdout)
+      }
+
+      if (stdout instanceof ArrayBuffer) {
+        return new TextDecoder().decode(new Uint8Array(stdout))
+      }
+
+      if (stdout && typeof (stdout as { text?: unknown }).text === "function") {
+        try {
+          const streamed = await (stdout as { text: () => Promise<string> }).text()
+          if (typeof streamed === "string") {
+            return streamed
+          }
+        } catch (_error) {
+        }
+      }
+    }
+
+    return String(output)
+  }
+
+  const parseVersion = (output: string) => {
+    const match = output.match(/(\d+)\.(\d+)\.(\d+)/)
+    if (!match) {
+      return null
+    }
+
     return {
-      reviewId,
-      submitPayload,
-      waitPayload,
-      browserUrl: submitPayload?.browser_url,
-      status: waitPayload?.review?.status,
-      feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
+      major: Number(match[1]),
+      minor: Number(match[2]),
+      patch: Number(match[3]),
+    }
+  }
+
+  const versionAtLeast = (
+    current: { major: number; minor: number; patch: number },
+    required: { major: number; minor: number; patch: number }
+  ) => {
+    if (current.major !== required.major) {
+      return current.major > required.major
+    }
+
+    if (current.minor !== required.minor) {
+      return current.minor > required.minor
+    }
+
+    return current.patch >= required.patch
+  }
+
+  const ensurePlanSubmitSupport = async () => {
+    let versionOutput = ""
+
+    try {
+      const versionProc = Bun.spawn(["controlkeel", "version"], {
+        stdout: "pipe",
+        stderr: "pipe",
+      })
+      versionOutput = await new Response(versionProc.stdout).text()
+      const versionExit = await versionProc.exited
+      if (versionExit !== 0) {
+        throw new Error(`controlkeel version exited with code ${versionExit}`)
+      }
+    } catch (error) {
+      throw new Error(
+        "Failed to run `controlkeel version`. Install ControlKeel >= 0.1.26 and ensure `controlkeel` is on PATH."
+      )
+    }
+
+    const parsed = parseVersion(versionOutput)
+    const required = { major: 0, minor: 1, patch: 26 }
+
+    if (!parsed || !versionAtLeast(parsed, required)) {
+      throw new Error(
+        `ControlKeel CLI ${versionOutput.trim() || "unknown"} is too old for plan-review submit. Install >= 0.1.26.`
+      )
+    }
+  }
+
+  const submitPlan = async (
+    body: string,
+    submittedBy: string,
+    title?: string,
+    waitTimeoutSeconds?: number
+  ) => {
+    await ensurePlanSubmitSupport()
+
+    const envTaskId = process.env.CONTROLKEEL_TASK_ID
+    const envSessionId = process.env.CONTROLKEEL_SESSION_ID
+    const waitTimeout = Number(waitTimeoutSeconds ?? process.env.CONTROLKEEL_REVIEW_WAIT_TIMEOUT ?? 30)
+    const waitTimeoutSecondsSafe = Number.isFinite(waitTimeout) && waitTimeout > 0 ? waitTimeout : 30
+
+    // Write body to temp file to avoid stdin piping issues
+    const tmpFile = `${directory}/.opencode/review-plan-${Date.now()}.md`
+    await Bun.write(tmpFile, body)
+
+    try {
+      const submitArgs = ["controlkeel", "review", "plan", "submit", "--body-file", tmpFile, "--submitted-by", submittedBy, "--json"]
+      if (title) submitArgs.push("--title", title)
+      if (envTaskId) submitArgs.push("--task-id", envTaskId)
+      else if (envSessionId) submitArgs.push("--session-id", envSessionId)
+
+      const submitProc = Bun.spawn(submitArgs, { stdout: "pipe", stderr: "pipe" })
+      const submitOut = await new Response(submitProc.stdout).text()
+      await submitProc.exited
+
+      const submitPayload = parseJson(submitOut)
+
+      if (typeof submitPayload?.error === "string" && submitPayload.error.includes("session_id")) {
+        throw new Error(
+          "ControlKeel plan submission requires review context. Set CONTROLKEEL_TASK_ID (preferred) or CONTROLKEEL_SESSION_ID, or pass --task-id/--session-id manually."
+        )
+      }
+
+      const reviewId = submitPayload?.review?.id
+      if (!reviewId) {
+        throw new Error("ControlKeel did not return a review id")
+      }
+
+      const waitProc = Bun.spawn(["controlkeel", "review", "plan", "wait", "--id", String(reviewId), "--timeout", String(waitTimeoutSecondsSafe), "--json"], { stdout: "pipe", stderr: "pipe" })
+      const waitOut = await new Response(waitProc.stdout).text()
+      await waitProc.exited
+
+      const waitPayload = parseJson(waitOut)
+      return {
+        reviewId,
+        submitPayload,
+        waitPayload,
+        browserUrl: submitPayload?.browser_url,
+        status: waitPayload?.review?.status,
+        feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
+      }
+    } finally {
+      // Clean up temp file
+      try { await Bun.file(tmpFile).unlink?.() ?? (await $`rm -f ${tmpFile}`.quiet()) } catch {}
     }
   }
 
   return {
-    "shell.env": async (_input, output) => {
+    "shell.env": async (input, output) => {
       output.env.CONTROLKEEL_PROJECT_ROOT = directory
       output.env.CONTROLKEEL_AGENT_ID = "opencode"
+
+      if (input.sessionID) {
+        output.env.CONTROLKEEL_THREAD_ID = input.sessionID
+      }
     },
 
     config: async (config) => {
@@ -74,9 +230,15 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
         args: {
           plan: tool.schema.string().describe("Markdown plan body to submit for review."),
           title: tool.schema.string().optional(),
+          wait_timeout_seconds: tool.schema.number().int().positive().optional(),
         },
         async execute(args) {
-          const result = await submitPlan(args.plan, "opencode")
+          const result = await submitPlan(
+            args.plan,
+            "opencode",
+            args.title,
+            args.wait_timeout_seconds
+          )
           return JSON.stringify(result, null, 2)
         },
       }),

package/index.js

@@ -1,3 +1,5 @@
+import { tool } from "@opencode-ai/plugin"
+
 /**
  * Published OpenCode package entrypoint for ControlKeel.
  *
@@ -13,29 +15,177 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
     }
   }
 
-  const submitPlan = async (body, submittedBy) => {
-    const result = await $`controlkeel review plan submit --stdin --submitted-by ${submittedBy} --json`
-      .text(body)
-    const submitPayload = parseJson(result)
-    const reviewId = submitPayload?.review?.id
-    if (!reviewId) {
-      throw new Error("ControlKeel did not return a review id")
+  const toText = async (output) => {
+    if (typeof output === "string") {
+      return output
+    }
+
+    if (output instanceof Uint8Array) {
+      return new TextDecoder().decode(output)
+    }
+
+    if (output instanceof ArrayBuffer) {
+      return new TextDecoder().decode(new Uint8Array(output))
+    }
+
+    if (output == null) {
+      return ""
+    }
+
+    if (typeof output === "object") {
+      if (typeof output.text === "function") {
+        try {
+          const direct = await output.text()
+          if (typeof direct === "string") {
+            return direct
+          }
+        } catch (_error) {
+        }
+      }
+
+      const stdout = output.stdout
+      if (typeof stdout === "string") {
+        return stdout
+      }
+
+      if (stdout instanceof Uint8Array) {
+        return new TextDecoder().decode(stdout)
+      }
+
+      if (stdout instanceof ArrayBuffer) {
+        return new TextDecoder().decode(new Uint8Array(stdout))
+      }
+
+      if (stdout && typeof stdout.text === "function") {
+        try {
+          const streamed = await stdout.text()
+          if (typeof streamed === "string") {
+            return streamed
+          }
+        } catch (_error) {
+        }
+      }
+    }
+
+    return String(output)
+  }
+
+  const parseVersion = (output) => {
+    const match = output.match(/(\d+)\.(\d+)\.(\d+)/)
+    if (!match) {
+      return null
     }
-    const waitPayload = parseJson(await $`controlkeel review plan wait --id ${reviewId} --json`)
+
     return {
-      reviewId,
-      submitPayload,
-      waitPayload,
-      browserUrl: submitPayload?.browser_url,
-      status: waitPayload?.review?.status,
-      feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
+      major: Number(match[1]),
+      minor: Number(match[2]),
+      patch: Number(match[3]),
+    }
+  }
+
+  const versionAtLeast = (current, required) => {
+    if (current.major !== required.major) {
+      return current.major > required.major
+    }
+
+    if (current.minor !== required.minor) {
+      return current.minor > required.minor
+    }
+
+    return current.patch >= required.patch
+  }
+
+  const ensurePlanSubmitSupport = async () => {
+    let versionOutput = ""
+
+    try {
+      const versionProc = Bun.spawn(["controlkeel", "version"], {
+        stdout: "pipe",
+        stderr: "pipe",
+      })
+      versionOutput = await new Response(versionProc.stdout).text()
+      const versionExit = await versionProc.exited
+      if (versionExit !== 0) {
+        throw new Error(`controlkeel version exited with code ${versionExit}`)
+      }
+    } catch (_error) {
+      throw new Error(
+        "Failed to run `controlkeel version`. Install ControlKeel >= 0.1.26 and ensure `controlkeel` is on PATH."
+      )
+    }
+
+    const parsed = parseVersion(versionOutput)
+    const required = { major: 0, minor: 1, patch: 26 }
+
+    if (!parsed || !versionAtLeast(parsed, required)) {
+      throw new Error(
+        `ControlKeel CLI ${versionOutput.trim() || "unknown"} is too old for plan-review submit. Install >= 0.1.26.`
+      )
+    }
+  }
+
+  const submitPlan = async (body, submittedBy, title, waitTimeoutSeconds) => {
+    await ensurePlanSubmitSupport()
+
+    const envTaskId = process.env.CONTROLKEEL_TASK_ID
+    const envSessionId = process.env.CONTROLKEEL_SESSION_ID
+    const waitTimeout = Number(waitTimeoutSeconds ?? process.env.CONTROLKEEL_REVIEW_WAIT_TIMEOUT ?? 30)
+    const waitTimeoutSecondsSafe = Number.isFinite(waitTimeout) && waitTimeout > 0 ? waitTimeout : 30
+
+    // Write body to temp file to avoid stdin piping issues
+    const tmpFile = `${directory}/.opencode/review-plan-${Date.now()}.md`
+    await Bun.write(tmpFile, body)
+
+    try {
+      const submitArgs = ["controlkeel", "review", "plan", "submit", "--body-file", tmpFile, "--submitted-by", submittedBy, "--json"]
+      if (title) submitArgs.push("--title", title)
+      if (envTaskId) submitArgs.push("--task-id", envTaskId)
+      else if (envSessionId) submitArgs.push("--session-id", envSessionId)
+
+      const submitProc = Bun.spawn(submitArgs, { stdout: "pipe", stderr: "pipe" })
+      const submitOut = await new Response(submitProc.stdout).text()
+      await submitProc.exited
+
+      const submitPayload = parseJson(submitOut)
+
+      if (typeof submitPayload?.error === "string" && submitPayload.error.includes("session_id")) {
+        throw new Error(
+          "ControlKeel plan submission requires review context. Set CONTROLKEEL_TASK_ID (preferred) or CONTROLKEEL_SESSION_ID, or pass --task-id/--session-id manually."
+        )
+      }
+
+      const reviewId = submitPayload?.review?.id
+      if (!reviewId) {
+        throw new Error("ControlKeel did not return a review id")
+      }
+
+      const waitProc = Bun.spawn(["controlkeel", "review", "plan", "wait", "--id", String(reviewId), "--timeout", String(waitTimeoutSecondsSafe), "--json"], { stdout: "pipe", stderr: "pipe" })
+      const waitOut = await new Response(waitProc.stdout).text()
+      await waitProc.exited
+
+      const waitPayload = parseJson(waitOut)
+      return {
+        reviewId,
+        submitPayload,
+        waitPayload,
+        browserUrl: submitPayload?.browser_url,
+        status: waitPayload?.review?.status,
+        feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
+      }
+    } finally {
+      // Clean up temp file
+      try { await Bun.file(tmpFile).unlink?.() ?? (await $`rm -f ${tmpFile}`.quiet()) } catch {}
     }
   }
 
   return {
-    "shell.env": async (_input, output) => {
+    "shell.env": async (input, output) => {
       output.env.CONTROLKEEL_PROJECT_ROOT = directory
       output.env.CONTROLKEEL_AGENT_ID = "opencode"
+
+      if (input.sessionID) {
+        output.env.CONTROLKEEL_THREAD_ID = input.sessionID
+      }
     },
 
     config: async (config) => {
@@ -55,37 +205,32 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
       }
     },
 
-    "tool.execute": async (input, output) => {
-      if (input.toolID !== "submit_plan") {
-        return
-      }
-
-      const planBody = typeof input.args?.plan === "string" ? input.args.plan : ""
-      const review = await submitPlan(planBody, "opencode")
-      output.metadata = {
-        reviewId: review.reviewId,
-        browserUrl: review.browserUrl,
-        status: review.status,
-        feedbackNotes: review.feedbackNotes,
-      }
-      output.result = JSON.stringify(output.metadata, null, 2)
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(
+        "Use submit_plan when you are ready for human review. Do not proceed with implementation until ControlKeel approves the plan."
+      )
     },
 
-    tools: async () => ({
-      submit_plan: {
-        description: "Submit the current plan to ControlKeel and wait for browser review approval.",
-        parameters: {
-          type: "object",
-          properties: {
-            plan: {
-              type: "string",
-              description: "Markdown plan body to submit to ControlKeel review.",
-            },
-          },
-          required: ["plan"],
+    tool: {
+      "submit_plan": tool({
+        description:
+          "Submit a plan to ControlKeel for browser review. The tool waits for approval before execution continues.",
+        args: {
+          plan: tool.schema.string().describe("Markdown plan body to submit for review."),
+          title: tool.schema.string().optional(),
+          wait_timeout_seconds: tool.schema.number().int().positive().optional(),
         },
-      },
-    }),
+        async execute(args) {
+          const result = await submitPlan(
+            args.plan,
+            "opencode",
+            args.title,
+            args.wait_timeout_seconds
+          )
+          return JSON.stringify(result, null, 2)
+        },
+      }),
+    },
   }
 }
 

package/package.json

@@ -2,6 +2,9 @@
   "bugs": {
     "url": "https://github.com/aryaminus/controlkeel/issues"
   },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.3.13"
+  },
   "description": "ControlKeel OpenCode adapter bundle",
   "exports": {
     ".": "./index.js",
@@ -32,5 +35,5 @@
     "url": "git+https://github.com/aryaminus/controlkeel.git"
   },
   "type": "module",
-  "version": "0.1.27"
+  "version": "0.1.29"
 }