@aryaminus/controlkeel-opencode 0.4.2 → 0.4.4

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

@@ -5,4 +5,4 @@ Use this command in OpenCode to reopen the latest ControlKeel review you are tra
 Suggested flow:
 1. Read the last stored review id from your notes or prior command output.
 2. Run `controlkeel review plan open --id <review_id> --json`
-3. If the review is still pending, run `controlkeel review plan wait --id <review_id> --json`
+3. If the review is still pending, ask the user for approval in this conversation, then record it with `controlkeel review plan respond <review_id> --decision approved --json`.

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

@@ -1,5 +1,5 @@
 ---
-description: Submit the current plan to ControlKeel browser review and wait for approval
+description: Submit the current plan to ControlKeel for approval
 ---
 
 Save the current plan to a markdown file, then submit it through ControlKeel.
@@ -8,10 +8,13 @@ Recommended flow:
 1. Save the plan to `.opencode/review-plan.md`
 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. If `browser_url` is available, wait with `controlkeel review plan wait --id <review_id> --timeout 30 --json`
-6. If `browser_url` is missing/unreachable, the browser does not actually open, **or** wait times out while still `pending`, do **not** loop on wait; ask for explicit user approval in chat and record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes "User approved in chat; browser unavailable or timed out" --json` (or `ck_review_feedback`)
-7. Do not execute until the review is approved
+4. Read the returned `review.id`, `browser_url`, and `auto_approved`
+5. If `auto_approved` is true, the plan was approved automatically (low risk, no blocked findings). Proceed.
+6. Otherwise, present the plan summary to the user and ask for approval in this conversation
+7. After the user approves, record it with `controlkeel review plan respond <review_id> --decision approved --feedback-notes "User approved in chat" --json` (or `ck_review_feedback`)
+8. Do not execute until the review is approved
+
+Auto-approval: For low-risk work (small scope, no security concerns, within established patterns), the server may auto-approve. Check `auto_approved` in the response.
 
 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.

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

@@ -68,6 +68,25 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
     }
   }
 
+  // CLI commands emit a `{command, data, status, version}` envelope; unwrap it so
+  // callers can read `review.id`, `session_id`, `browser_url` at the top level.
+  // Older flat payloads pass through unchanged.
+  const parseCliJson = (output: string) => {
+    const payload = parseJson(output)
+
+    if (
+      payload != null &&
+      typeof payload === "object" &&
+      !Array.isArray(payload) &&
+      payload.data != null &&
+      typeof payload.data === "object"
+    ) {
+      return payload.data
+    }
+
+    return payload
+  }
+
   const toText = async (output: unknown) => {
     if (typeof output === "string") {
       return output
@@ -242,7 +261,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
       )
     }
 
-    const contextPayload = parseJson([contextOut, contextErr].filter(Boolean).join("\n"))
+    const contextPayload = parseCliJson([contextOut, contextErr].filter(Boolean).join("\n"))
     const contextTaskId = contextPayload?.current_task?.id
     const contextSessionId = contextPayload?.session_id
 
@@ -316,7 +335,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
         )
       }
 
-      const submitPayload = parseJson([submitOut, submitErr].filter(Boolean).join("\n"))
+      const submitPayload = parseCliJson([submitOut, submitErr].filter(Boolean).join("\n"))
 
       if (typeof submitPayload?.error === "string" && submitPayload.error.includes("session_id")) {
         throw new Error(
@@ -346,7 +365,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
         const openExit = await openProc.exited
 
         if (openExit === 0) {
-          openPayload = parseJson([openOut, openErr].filter(Boolean).join("\n"))
+          openPayload = parseCliJson([openOut, openErr].filter(Boolean).join("\n"))
         } else {
           openPayload = {
             error: `controlkeel review plan open failed with exit code ${openExit}${openErr.trim() ? `: ${openErr.trim()}` : ""}`,
@@ -377,6 +396,22 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
         guidance: overrides.guidance ?? null,
       })
 
+      // If the server auto-approved, skip the entire open/wait flow
+      const autoApproved = submitPayload?.auto_approved === true
+      const autoApproveReason = submitPayload?.auto_approve_reason ?? null
+
+      if (autoApproved) {
+        return buildPlanResult({
+          status: "approved",
+          waitSkipped: true,
+          manualApprovalRequired: false,
+          reason: "auto_approved",
+          guidance: autoApproveReason
+            ? `Plan auto-approved: ${autoApproveReason}`
+            : "Plan was auto-approved by ControlKeel (low risk, no blocked findings, within policy).",
+        })
+      }
+
       const openError = typeof openPayload?.open_error === "string" ? openPayload.open_error.trim() : ""
       const openFailure = typeof openPayload?.error === "string" ? openPayload.error.trim() : ""
       const browserNotOpened = openPayload?.opened !== true
@@ -387,7 +422,11 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
         browserUrl.includes("localhost") &&
         openPayload?.remote === true
 
-      if (!browserUrl || serverUnavailable || openError || openFailure || remoteLocalhostMismatch || browserNotOpened) {
+      // Default: always return inline approval guidance.
+      const browserAvailable =
+        browserUrl && !serverUnavailable && !openError && !openFailure && !remoteLocalhostMismatch && !browserNotOpened
+
+      if (!browserAvailable) {
         return buildPlanResult({
           waitSkipped: true,
           manualApprovalRequired: true,
@@ -400,10 +439,29 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
                   ? "browser_not_opened"
                   : "browser_unreachable",
           guidance:
-            "Browser review is unavailable, the CK review server is not reachable, or the browser did not actually open. Ask the user for explicit approval in chat, then record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat; browser/review server unavailable\" --json` or `ck_review_feedback`.",
+            "Ask the user for explicit approval in this conversation. " +
+            "Present the plan summary and ask: 'Do you approve this plan? (yes/no)'. " +
+            "After the user says yes, record it with: `controlkeel review plan respond <review_id> --decision approved --feedback-notes \"User approved in chat\" --json` " +
+            "or call `ck_review_feedback` with review_id=<review_id> decision=\"approved\".",
         })
       }
 
+      // Browser is available. If the caller explicitly passed wait_timeout_seconds,
+      // honor it (opt-in blocking). Otherwise, return immediately with inline guidance.
+      if (waitTimeoutSeconds == null) {
+        return buildPlanResult({
+          waitSkipped: true,
+          manualApprovalRequired: false,
+          reason: "browser_available_inline_default",
+          guidance:
+            "Browser review is available at: " + browserUrl + "\n" +
+            "You can: (a) ask the user to approve inline in this conversation, or (b) pass wait_timeout_seconds to block until the browser review is completed. " +
+            "To record inline approval: `controlkeel review plan respond <review_id> --decision approved --feedback-notes \"User approved in chat\" --json`.",
+        })
+      }
+
+      // Opt-in blocking: caller explicitly asked to wait for browser review.
+
       const waitEnv = process.env.LOGGER_LEVEL
         ? process.env
         : { ...process.env, LOGGER_LEVEL: "warning" }
@@ -416,7 +474,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
       const waitOut = await new Response(waitProc.stdout).text()
       const waitErr = await new Response(waitProc.stderr).text()
       const waitExit = await waitProc.exited
-      const waitPayload = parseJson([waitOut, waitErr].filter(Boolean).join("\n"))
+      const waitPayload = parseCliJson([waitOut, waitErr].filter(Boolean).join("\n"))
       const waitMessage = typeof waitPayload?.message === "string" ? waitPayload.message.toLowerCase() : ""
       const waitError = typeof waitPayload?.error === "string" ? waitPayload.error.toLowerCase() : ""
       const waitTimedOut = waitMessage.includes("timeout") || waitError.includes("timed out")
@@ -433,7 +491,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
             manualApprovalRequired: true,
             reason: "review_timeout",
             guidance:
-              "Plan review is still pending after timeout. Show the `browser_url` to the user if reachable. If browser review is unavailable or the user explicitly approves in chat, record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat after timeout/browser issue\" --json` (or `ck_review_feedback`) before proceeding.",
+              "Plan review is still pending after timeout. Show the `browser_url` to the user if reachable. If browser review is unavailable or the user explicitly approves in chat, record it with `controlkeel review plan respond <review_id> --decision approved --feedback-notes \"User approved in chat after timeout/browser issue\" --json` (or `ck_review_feedback`) before proceeding.",
           })
         }
 

package/.opencode/skills/compliance-audit/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: compliance-audit
-description: "Run a structured compliance audit against active ControlKeel policy packs and domain controls. Use this before shipping regulated data flows, external integrations, or document exports."
-when_to_use: "Activate before exporting data, integrating with external services, or when the user asks about compliance, regulatory requirements, GDPR, SOC2, HIPAA, or policy packs."
-argument-hint: "[data flow, integration, or domain to audit]"
+description: "DEPRECATED — use `security-review` instead (it now covers all of this — regulated flows, policy packs, domain controls). Kept as a thin alias for search (compliance/GDPR/SOC2/HIPAA) so existing `ck_skill_list` queries still surface `security-review`."
+when_to_use: "Do NOT invoke this skill directly — invoke `security-review`, which runs the compliance audit as its policy/domain-pack layer. This file exists only so keyword search for compliance, GDPR, SOC2, HIPAA routes to the consolidated `security-review` path."
+argument-hint: "[use security-review instead]"
 license: Apache-2.0
+redirect_to: security-review
 compatibility:
   - codex
   - claude-standalone
@@ -40,18 +41,13 @@ metadata:
     - ck_context
     - ck_validate
     - ck_finding
+  deprecated: true
+  superseded_by: security-review
 ---
 
-# Compliance Audit Skill
+# Compliance Audit Skill — alias
 
-## Audit flow
-
-1. Call `ck_context` and confirm the active compliance profile for the session.
-2. Review only the pack sections that match the active domain pack and data flows.
-3. Use `ck_validate` for concrete snippets and configs when the checklist points to code.
-4. Persist each failing control with `ck_finding`.
-5. End with packs checked, controls reviewed, blockers, and required approvals.
-
-## Additional resources
-
-- For the full domain-by-domain checklist, see [references/control-matrix.md](references/control-matrix.md)
+> **This skill has moved.** Use `security-review` — it runs the same compliance audit
+> as its policy/domain-pack layer (active compliance profile → pack sections →
+> `ck_validate` → `ck_finding`). This file is a thin keyword alias so search for
+> `compliance`, `GDPR`, `SOC2`, `HIPAA` still surfaces the consolidated path.

package/.opencode/skills/domain-audit/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: domain-audit
-description: "Audit a session against its domain pack, especially the regulated and operations-heavy packs such as HR, legal, marketing, sales, real-estate, government, insurance, logistics, manufacturing, e-commerce, and nonprofit. Use this when domain-specific policy needs a manual pass."
-when_to_use: "Activate before handling data in regulated or sensitive domains, or when the user asks about HR policy, legal compliance, GDPR, healthcare, finance, or any industry-specific governance requirements."
-argument-hint: "[domain or data type to audit]"
+description: "DEPRECATED — use `security-review` instead (it now covers all domain-pack audits — HR, legal, marketing, sales, real-estate, government, insurance, logistics, manufacturing, e-commerce, nonprofit). Kept as a thin alias so `ck_skill_list` for those domains still surfaces `security-review`."
+when_to_use: "Do NOT invoke this skill directly — invoke `security-review`, which runs the domain-pack audit as its policy/domain-pack layer. This file exists only so keyword search for HR, legal, marketing, sales, government, etc. routes to the consolidated `security-review` path."
+argument-hint: "[use security-review instead]"
 license: Apache-2.0
+redirect_to: security-review
 compatibility:
   - codex
   - claude-standalone
@@ -39,26 +40,14 @@ metadata:
   ck_mcp_tools:
     - ck_context
     - ck_finding
+  deprecated: true
+  superseded_by: security-review
 ---
 
-# Domain Audit Skill
+# Domain Audit Skill — alias
 
-Use this skill when the session’s domain pack drives the real risk more than generic software checks.
-
-## Focus areas
-
-- HR: bias, candidate data, compensation visibility
-- Legal: privilege, retention, document handling
-- Marketing: consent, unsubscribe, analytics PII
-- Sales: CRM data, contact deletion, revenue visibility
-- Real estate: fair-housing logic, tenant PII, retention
-- Government: records retention, constituent data, approval chains
-- Insurance: claims fairness, medical-adjacent privacy, denial review
-- E-commerce: card scope, refunds, fraud controls
-- Logistics: shipment custody, dispatch safety, carrier data
-- Manufacturing: QA holds, traceability, plant safety
-- Nonprofit: donor privacy, grant restrictions, beneficiary exports
-
-## Additional resources
-
-- [Domain review matrix](references/domain-review-matrix.md)
+> **This skill has moved.** Use `security-review` — it runs the same domain-pack
+> audit as its policy/domain-pack layer. This file is a thin keyword alias so
+> search for `HR`, `legal`, `marketing`, `sales`, `government`, `insurance`,
+> `logistics`, `manufacturing`, `e-commerce`, or `nonprofit` still surfaces
+> the consolidated path.

package/.opencode/skills/end-of-shift/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: end-of-shift
-description: "Close a governed work session with validation, proof, findings, budget, digest, learning, and handoff checks. Use when the user asks to wrap up, stop for the day, or leave work ready for another agent."
-when_to_use: "Activate only at an explicit session stop point or when the user asks for end-of-shift validation. Do not run expensive full-suite or benchmark work unless project policy or the approved plan requires it."
+description: "Close a governed work session — the unified session-close path (validation + proof + findings + budget + digest + learning) that ends with the `handoff` delegation step when work remains. Prefer this over bare `handoff` for any end-of-shift wrap-up. Use when the user asks to wrap up, stop for the day, or leave work ready for another agent."
+when_to_use: "Activate at any explicit session stop point (wrap up, stop for the day, leave work for another agent). It subsumes the bare `handoff` flow — `handoff` is just this skill's final delegation step, kept callable alone for mid-session delegation. Activate only at for end-of-shift validation. Do not run expensive full-suite or benchmark work unless project policy or the approved plan requires it."
 argument-hint: "[completed work or remaining task]"
 disable-model-invocation: true
 license: Apache-2.0
@@ -27,8 +27,10 @@ result-schema:
     handoff_reference: {type: [string, "null"]}
 metadata:
   author: controlkeel
-  version: "1.0"
+  version: "1.1"
   category: execution
+  supersedes: handoff
+  subsumes: handoff
   ck_mcp_tools:
     - ck_context
     - ck_git_status
@@ -42,7 +44,9 @@ metadata:
     - ck_checkpoint_create
 ---
 
-# End of Shift
+# End of Shift — unified session-close
+
+> `handoff` is step 7 of this skill (mid-session delegation without the earlier validation/proof/digest/learning gates). Use bare `handoff` only for mid-session delegation; this skill is the full close — it validates, finalizes proof, checks budget, synthesizes learnings, then hands off if work remains.
 
 Close work with enough verified state that the next human or agent can continue without reconstructing the session from chat.
 

package/.opencode/skills/handoff/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: handoff
-description: "Persist session state and hand off in-progress work to a background agent or delegated execution. Use when work outgrows the current session, context is near limit, or a task needs to continue unattended."
-when_to_use: "Activate when the user says 'hand off', 'delegate this', 'continue in background', 'pass this off', or when context pressure is high and significant work remains. Also activate when ck_route recommends a different agent for the remaining work."
+description: "Persist session state and hand off in-progress work to a background agent — the *delegation step* of `end-of-shift`. Use when work outgrows the current session or must continue unattended; for a full session close (validation + proof + findings + budget + digest + learning before handoff) prefer `end-of-shift`."
+when_to_use: "Activate ONLY for mid-session delegation (context near limit, `ck_route` recommends a different agent/runtime, user says hand off/delegate/pass off). For an end-of-shift wrap-up (validate remaining work, finalize proofs, synthesize learnings), use `end-of-shift` instead — `handoff` is that skill's final step."
 argument-hint: "[optional: specific task or remaining work to hand off]"
 disable-model-invocation: true
 license: Apache-2.0
+redirect_to: end-of-shift
 compatibility:
   - codex
   - claude-standalone
@@ -35,8 +36,9 @@ compatibility:
   - forge-acp
 metadata:
   author: controlkeel
-  version: "1.0"
+  version: "1.1"
   category: execution
+  superseded_by: end-of-shift
   ck_mcp_tools:
     - ck_context
     - ck_memory_record
@@ -46,7 +48,12 @@ metadata:
     - ck_goal
 ---
 
-# Handoff Skill
+# Handoff Skill — delegation step
+
+> This skill is the **delegation sub-step** of `end-of-shift`. A full end-of-shift
+> run validates remaining work, finalizes proofs, records digests/learnings, and THEN
+> hands off. Use this skill alone only for mid-session delegation; otherwise prefer
+> `end-of-shift`.
 
 Transfer in-progress work to another agent or execution context with full state preservation, so work continues seamlessly after the current session ends or context runs out.
 

package/.opencode/skills/parallel-review/SKILL.md

@@ -1,9 +1,12 @@
 ---
 name: parallel-review
-description: "Run security + code quality reviews concurrently, synthesize deduplicated findings. Trigger: 'full review', 'parallel review', 'both reviews', comprehensive pre-merge check."
-when_to_use: "Activate ONLY when explicitly asked for comprehensive security+quality review. Do NOT use when only one review type is needed."
+description: "DEPRECATED for inline use — this is now a CLI composite (`controlkeel review --parallel`). Kept callable only for explicitly requested comprehensive security+quality orchestration; otherwise invoke security-review + deep-code-quality-review separately or via that CLI."
+when_to_use: "Do NOT invoke via skills when possible — use `controlkeel review --parallel` (CLI). Invoke this skill only when explicitly asked for comprehensive security+quality orchestration."
+
 argument-hint: "[PR, branch, or diff]"
 disable-model-invocation: true
+deprecated: true
+prefer_cli: "controlkeel review --parallel"
 license: Apache-2.0
 compatibility:
   - opencode-native

package/.opencode/skills/security-review/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: security-review
-description: "Run a structured security review before marking a task done. Use this for code, config, architecture, or release reviews that need OWASP, baseline pack, and domain-pack coverage."
-when_to_use: "Use before merging, deploying, or signing off on code, config, or architecture changes. Activate when reviewing auth, input handling, secrets, or third-party dependencies."
-argument-hint: "[file, PR, or area to review]"
+description: "Run a structured security review before marking a task done. Services as the single audit skill for OWASP, baseline pack, domain-pack (HR/legal/marketing/sales/real-estate/government/insurance/logistics/manufacturing/e-commerce/nonprofit), and compliance (GDPR/SOC2/HIPAA/policy packs) — subsumes the deprecated `compliance-audit` and `domain-audit` aliases. Use this for code, config, architecture, or release reviews; the domain/compliance layer is triggered by the session's active domain pack and data flows."
+when_to_use: "Use before merging, deploying, or signing off on code, config, or architecture changes (including regulated data flows, external integrations, exports, and any session whose domain pack is HR/legal/marketing/sales/real-estate/government/insurance/logistics/manufacturing/e-commerce/nonprofit). Activates for auth/input/secrets/deps and for domain/compliance coverage — the policy/domain-pack layer is driven by `ck_context`'s active compliance profile."
+argument-hint: "[file, PR, area, or domain-pack scope to review]"
 license: Apache-2.0
+redirect_to: security-review
 compatibility:
   - codex
   - claude-standalone
@@ -36,6 +37,10 @@ metadata:
   author: controlkeel
   version: "2.1"
   category: security
+  subsumes:
+    - compliance-audit
+    - domain-audit
+    - agent-pattern-verification
   ck_mcp_tools:
     - ck_validate
     - ck_context

package/index.js

@@ -64,6 +64,25 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
     }
   }
 
+  // CLI commands emit a `{command, data, status, version}` envelope; unwrap it so
+  // callers can read `review.id`, `session_id`, `browser_url` at the top level.
+  // Older flat payloads pass through unchanged.
+  const parseCliJson = (output) => {
+    const payload = parseJson(output)
+
+    if (
+      payload != null &&
+      typeof payload === "object" &&
+      !Array.isArray(payload) &&
+      payload.data != null &&
+      typeof payload.data === "object"
+    ) {
+      return payload.data
+    }
+
+    return payload
+  }
+
   const toText = async (output) => {
     if (typeof output === "string") {
       return output
@@ -232,7 +251,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
       )
     }
 
-    const contextPayload = parseJson([contextOut, contextErr].filter(Boolean).join("\n"))
+    const contextPayload = parseCliJson([contextOut, contextErr].filter(Boolean).join("\n"))
     const contextTaskId = contextPayload?.current_task?.id
     const contextSessionId = contextPayload?.session_id
 
@@ -299,7 +318,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
         )
       }
 
-      const submitPayload = parseJson([submitOut, submitErr].filter(Boolean).join("\n"))
+      const submitPayload = parseCliJson([submitOut, submitErr].filter(Boolean).join("\n"))
 
       if (typeof submitPayload?.error === "string" && submitPayload.error.includes("session_id")) {
         throw new Error(
@@ -329,7 +348,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
         const openExit = await openProc.exited
 
         if (openExit === 0) {
-          openPayload = parseJson([openOut, openErr].filter(Boolean).join("\n"))
+          openPayload = parseCliJson([openOut, openErr].filter(Boolean).join("\n"))
         } else {
           openPayload = {
             error: `controlkeel review plan open failed with exit code ${openExit}${openErr.trim() ? `: ${openErr.trim()}` : ""}`,
@@ -360,6 +379,22 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
         guidance: overrides.guidance ?? null,
       })
 
+      // If the server auto-approved, skip the entire open/wait flow
+      const autoApproved = submitPayload?.auto_approved === true
+      const autoApproveReason = submitPayload?.auto_approve_reason ?? null
+
+      if (autoApproved) {
+        return buildPlanResult({
+          status: "approved",
+          waitSkipped: true,
+          manualApprovalRequired: false,
+          reason: "auto_approved",
+          guidance: autoApproveReason
+            ? `Plan auto-approved: ${autoApproveReason}`
+            : "Plan was auto-approved by ControlKeel (low risk, no blocked findings, within policy).",
+        })
+      }
+
       const openError = typeof openPayload?.open_error === "string" ? openPayload.open_error.trim() : ""
       const openFailure = typeof openPayload?.error === "string" ? openPayload.error.trim() : ""
       const browserNotOpened = openPayload?.opened !== true
@@ -370,7 +405,11 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
         browserUrl.includes("localhost") &&
         openPayload?.remote === true
 
-      if (!browserUrl || serverUnavailable || openError || openFailure || remoteLocalhostMismatch || browserNotOpened) {
+      // Default: always return inline approval guidance.
+      const browserAvailable =
+        browserUrl && !serverUnavailable && !openError && !openFailure && !remoteLocalhostMismatch && !browserNotOpened
+
+      if (!browserAvailable) {
         return buildPlanResult({
           waitSkipped: true,
           manualApprovalRequired: true,
@@ -383,10 +422,29 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
                   ? "browser_not_opened"
                   : "browser_unreachable",
           guidance:
-            "Browser review is unavailable, the CK review server is not reachable, or the browser did not actually open. Ask the user for explicit approval in chat, then record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat; browser/review server unavailable\" --json` or `ck_review_feedback`.",
+            "Ask the user for explicit approval in this conversation. " +
+            "Present the plan summary and ask: 'Do you approve this plan? (yes/no)'. " +
+            "After the user says yes, record it with: `controlkeel review plan respond <review_id> --decision approved --feedback-notes \"User approved in chat\" --json` " +
+            "or call `ck_review_feedback` with review_id=<review_id> decision=\"approved\".",
         })
       }
 
+      // Browser is available. If the caller explicitly passed wait_timeout_seconds,
+      // honor it (opt-in blocking). Otherwise, return immediately with inline guidance.
+      if (waitTimeoutSeconds == null) {
+        return buildPlanResult({
+          waitSkipped: true,
+          manualApprovalRequired: false,
+          reason: "browser_available_inline_default",
+          guidance:
+            "Browser review is available at: " + browserUrl + "\n" +
+            "You can: (a) ask the user to approve inline in this conversation, or (b) pass wait_timeout_seconds to block until the browser review is completed. " +
+            "To record inline approval: `controlkeel review plan respond <review_id> --decision approved --feedback-notes \"User approved in chat\" --json`.",
+        })
+      }
+
+      // Opt-in blocking: caller explicitly asked to wait for browser review.
+
       const waitEnv = process.env.LOGGER_LEVEL
         ? process.env
         : { ...process.env, LOGGER_LEVEL: "warning" }
@@ -399,7 +457,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
       const waitOut = await new Response(waitProc.stdout).text()
       const waitErr = await new Response(waitProc.stderr).text()
       const waitExit = await waitProc.exited
-      const waitPayload = parseJson([waitOut, waitErr].filter(Boolean).join("\n"))
+      const waitPayload = parseCliJson([waitOut, waitErr].filter(Boolean).join("\n"))
       const waitMessage = typeof waitPayload?.message === "string" ? waitPayload.message.toLowerCase() : ""
       const waitError = typeof waitPayload?.error === "string" ? waitPayload.error.toLowerCase() : ""
       const waitTimedOut = waitMessage.includes("timeout") || waitError.includes("timed out")
@@ -416,7 +474,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
             manualApprovalRequired: true,
             reason: "review_timeout",
             guidance:
-              "Plan review is still pending after timeout. Show the `browser_url` to the user if reachable. If browser review is unavailable or the user explicitly approves in chat, record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat after timeout/browser issue\" --json` (or `ck_review_feedback`) before proceeding.",
+              "Plan review is still pending after timeout. Show the `browser_url` to the user if reachable. If browser review is unavailable or the user explicitly approves in chat, record it with `controlkeel review plan respond <review_id> --decision approved --feedback-notes \"User approved in chat after timeout/browser issue\" --json` (or `ck_review_feedback`) before proceeding.",
           })
         }
 

package/package.json

@@ -35,5 +35,5 @@
     "url": "git+https://github.com/aryaminus/controlkeel.git"
   },
   "type": "module",
-  "version": "0.4.2"
+  "version": "0.4.4"
 }