hooks: Show install guidance when sce is missing

Add fail-open missing-CLI guidance for generated Claude hook commands, OpenCode plugin wrappers, and the git post-commit hook. Preserve normal hook delegation when sce is installed while surfacing the install URL when hook runtime cannot find the CLI.

Co-authored-by: SCE <sce@crocoder.dev>

Author: stefanskoricdev

.claude/hooks/run-sce-or-show-install-guidance.sh

@@ -3,6 +3,11 @@ set -eu
 
 remote_url="$(git remote get-url origin 2>/dev/null || true)"
 
+if ! command -v sce >/dev/null 2>&1; then
+  echo "sce CLI not found. Install it from https://sce.crocoder.dev/docs/getting-started#install-cli" >&2
+  exit 0
+fi
+
 if [ -n "$remote_url" ]; then
   exec sce hooks post-commit --vcs git --remote-url "$remote_url" "$@"
 fi

.claude/settings.json

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v sce >/dev/null 2>&1; then
+  echo "sce CLI not found. Install it from https://sce.crocoder.dev/docs/getting-started#install-cli" >&2
+  exit 0
+fi
+
+exec "$@"

.opencode/plugins/sce-agent-trace.ts

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sce hooks session-model"
+            "command": "bash .claude/hooks/run-sce-or-show-install-guidance.sh sce hooks session-model"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sce policy bash"
+            "command": "bash .claude/hooks/run-sce-or-show-install-guidance.sh sce policy bash"
           }
         ]
       }
@@ -28,15 +28,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sce hooks diff-trace"
+            "command": "bash .claude/hooks/run-sce-or-show-install-guidance.sh sce hooks diff-trace"
           }
         ]
       },
       {
         "hooks": [
           {
             "type": "command",
-            "command": "sce hooks conversation-trace"
+            "command": "bash .claude/hooks/run-sce-or-show-install-guidance.sh sce hooks conversation-trace"
           }
         ]
       }
@@ -46,7 +46,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sce hooks conversation-trace"
+            "command": "bash .claude/hooks/run-sce-or-show-install-guidance.sh sce hooks conversation-trace"
           }
         ]
       }
@@ -56,7 +56,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sce hooks conversation-trace"
+            "command": "bash .claude/hooks/run-sce-or-show-install-guidance.sh sce hooks conversation-trace"
           }
         ]
       }

.opencode/plugins/sce-bash-policy.ts

@@ -3,6 +3,9 @@ import type { Hooks, Plugin } from "@opencode-ai/plugin";
 
 type OpenCodeEvent = Parameters<NonNullable<Hooks["event"]>>[0]["event"];
 
+const SCE_INSTALL_URL =
+	"https://sce.crocoder.dev/docs/getting-started#install-cli";
+
 const REQUIRED_EVENTS: Set<OpenCodeEvent["type"]> = new Set([
 	"message.updated",
 	"message.part.updated",
@@ -332,7 +335,14 @@ async function runDiffTraceHook(
 			stdio: ["pipe", "ignore", "ignore"],
 		});
 
-		child.on("error", () => resolve());
+		child.on("error", (err: NodeJS.ErrnoException) => {
+			if (err.code === "ENOENT") {
+				console.warn(
+					`sce CLI not found. Install it from ${SCE_INSTALL_URL}`,
+				);
+			}
+			resolve();
+		});
 		child.on("close", () => resolve());
 
 		child.stdin.end(`${JSON.stringify(payload)}\n`);
@@ -352,7 +362,14 @@ async function runConversationTraceHook(
 			stdio: ["pipe", "ignore", "ignore"],
 		});
 
-		child.on("error", () => resolve());
+		child.on("error", (err: NodeJS.ErrnoException) => {
+			if (err.code === "ENOENT") {
+				console.warn(
+					`sce CLI not found. Install it from ${SCE_INSTALL_URL}`,
+				);
+			}
+			resolve();
+		});
 		child.on("close", () => resolve());
 
 		child.stdin.end(`${JSON.stringify(payload)}\n`);

cli/assets/hooks/post-commit

@@ -10,6 +10,9 @@ interface JsonPolicyResult {
 	policy_id?: string;
 }
 
+const SCE_INSTALL_URL =
+	"https://sce.crocoder.dev/docs/getting-started#install-cli";
+
 /**
  * Evaluate a bash command against SCE bash-tool policy by delegating to the
  * Rust `sce policy bash` command. Returns the parsed JSON result, or null if
@@ -28,6 +31,11 @@ function evaluateBashCommandPolicy(command: string): JsonPolicyResult | null {
 		);
 
 		if (result.error) {
+			if ((result.error as NodeJS.ErrnoException).code === "ENOENT") {
+				console.warn(
+					`sce CLI not found. Install it from ${SCE_INSTALL_URL}`,
+				);
+			}
 			return null;
 		}
 

config/.claude/hooks/run-sce-or-show-install-guidance.sh

@@ -3,6 +3,9 @@ import type { Hooks, Plugin } from "@opencode-ai/plugin";
 
 type OpenCodeEvent = Parameters<NonNullable<Hooks["event"]>>[0]["event"];
 
+const SCE_INSTALL_URL =
+	"https://sce.crocoder.dev/docs/getting-started#install-cli";
+
 const REQUIRED_EVENTS: Set<OpenCodeEvent["type"]> = new Set([
 	"message.updated",
 	"message.part.updated",
@@ -332,7 +335,14 @@ async function runDiffTraceHook(
 			stdio: ["pipe", "ignore", "ignore"],
 		});
 
-		child.on("error", () => resolve());
+		child.on("error", (err: NodeJS.ErrnoException) => {
+			if (err.code === "ENOENT") {
+				console.warn(
+					`sce CLI not found. Install it from ${SCE_INSTALL_URL}`,
+				);
+			}
+			resolve();
+		});
 		child.on("close", () => resolve());
 
 		child.stdin.end(`${JSON.stringify(payload)}\n`);
@@ -352,7 +362,14 @@ async function runConversationTraceHook(
 			stdio: ["pipe", "ignore", "ignore"],
 		});
 
-		child.on("error", () => resolve());
+		child.on("error", (err: NodeJS.ErrnoException) => {
+			if (err.code === "ENOENT") {
+				console.warn(
+					`sce CLI not found. Install it from ${SCE_INSTALL_URL}`,
+				);
+			}
+			resolve();
+		});
 		child.on("close", () => resolve());
 
 		child.stdin.end(`${JSON.stringify(payload)}\n`);