feat: add PreToolUse hook to block non-PATH ctx invocations

Agents were using ./dist/ctx and go run ./cmd/ctx despite documentation
saying to use ctx from PATH. This adds runtime enforcement via a
PreToolUse hook that blocks forbidden patterns and returns a clear
error message pointing to CONSTITUTION.md.

- Add block-non-path-ctx.sh hook script (blocks ./ctx, ./dist/ctx, go run ./cmd/ctx)
- Embed script in ctx binary for ctx init bootstrapping
- Update CreateDefaultHooks to include Bash matcher for blocking hook
- Update init.go to write the hook during ctx init

Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>

Author: josealekhine

.claude/hooks/block-non-path-ctx.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+#   /    Context:                     https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2025-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+# Block non-PATH ctx invocations
+# This enforces the CONSTITUTION.md rule: "ALWAYS use ctx from PATH"
+#
+# BLOCKED PATTERNS:
+# - ./ctx, ./dist/ctx, ./dist/ctx-*  (relative paths)
+# - go run ./cmd/ctx                  (build-and-run)
+# - /absolute/path/to/ctx             (hardcoded absolute paths)
+#
+# ALLOWED:
+# - ctx status, ctx agent, etc.       (PATH-based invocation)
+
+# Read hook input from stdin (JSON)
+HOOK_INPUT=$(cat)
+
+# Extract the command being run
+COMMAND=$(echo "$HOOK_INPUT" | jq -r '.tool_input.command // empty')
+
+# If no command, allow (not a Bash call we care about)
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Check for forbidden patterns
+BLOCKED_REASON=""
+
+# Pattern 1: ./ctx or ./dist/ctx or ./dist/ctx-*
+if echo "$COMMAND" | grep -qE '(\./ctx|\./dist/ctx)'; then
+    BLOCKED_REASON="Use 'ctx' from PATH, not './ctx' or './dist/ctx'. Install with: sudo make install"
+fi
+
+# Pattern 2: go run ./cmd/ctx
+if echo "$COMMAND" | grep -qE 'go run \./cmd/ctx'; then
+    BLOCKED_REASON="Use 'ctx' from PATH, not 'go run ./cmd/ctx'. Install with: sudo make install"
+fi
+
+# Pattern 3: Absolute paths to ctx binary (but not just 'ctx' or paths in /usr/local/bin, /usr/bin)
+# Match things like /home/user/project/ctx or /tmp/ctx-test but allow /usr/local/bin/ctx
+if echo "$COMMAND" | grep -qE '(/home/|/tmp/|/var/)[^ ]*ctx[^ ]* '; then
+    # Exception: allow /tmp/ctx-test for integration tests
+    if ! echo "$COMMAND" | grep -qE '/tmp/ctx-test'; then
+        BLOCKED_REASON="Use 'ctx' from PATH, not absolute paths. Install with: sudo make install"
+    fi
+fi
+
+# If blocked, output JSON that tells Claude Code to reject
+if [ -n "$BLOCKED_REASON" ]; then
+    cat << EOF
+{"decision": "block", "reason": "$BLOCKED_REASON\n\nSee CONSTITUTION.md: ctx Invocation Invariants"}
+EOF
+    exit 0
+fi
+
+# Allow the command
+exit 0

internal/claude/embed.go

@@ -12,7 +12,7 @@ import (
 	"fmt"
 )
 
-//go:embed tpl/auto-save-session.sh
+//go:embed tpl/auto-save-session.sh tpl/block-non-path-ctx.sh
 var FS embed.FS
 
 // GetAutoSaveScript returns the auto-save session script.
@@ -24,6 +24,15 @@ func GetAutoSaveScript() ([]byte, error) {
 	return content, nil
 }
 
+// GetBlockNonPathCtxScript returns the script that blocks non-PATH ctx invocations.
+func GetBlockNonPathCtxScript() ([]byte, error) {
+	content, err := FS.ReadFile("tpl/block-non-path-ctx.sh")
+	if err != nil {
+		return nil, fmt.Errorf("failed to read block-non-path-ctx.sh: %w", err)
+	}
+	return content, nil
+}
+
 // SettingsHooks represents the hooks section of settings.local.json
 type SettingsHooks struct {
 	PreToolUse []HookMatcher `json:"PreToolUse,omitempty"`
@@ -59,6 +68,17 @@ func CreateDefaultHooks(projectDir string) SettingsHooks {
 	return SettingsHooks{
 		PreToolUse: []HookMatcher{
 			{
+				// Block non-PATH ctx invocations (./ctx, ./dist/ctx, go run ./cmd/ctx)
+				Matcher: "Bash",
+				Hooks: []Hook{
+					{
+						Type:    "command",
+						Command: fmt.Sprintf("%s/block-non-path-ctx.sh", hooksDir),
+					},
+				},
+			},
+			{
+				// Auto-load context on every tool use
 				Matcher: ".*",
 				Hooks: []Hook{
 					{

internal/claude/tpl/block-non-path-ctx.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+#   /    Context:                     https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2025-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+# Block non-PATH ctx invocations
+# This enforces the CONSTITUTION.md rule: "ALWAYS use ctx from PATH"
+#
+# Generated by: ctx init
+#
+# BLOCKED PATTERNS:
+# - ./ctx, ./dist/ctx, ./dist/ctx-*  (relative paths)
+# - go run ./cmd/ctx                  (build-and-run)
+# - /absolute/path/to/ctx             (hardcoded absolute paths)
+#
+# ALLOWED:
+# - ctx status, ctx agent, etc.       (PATH-based invocation)
+
+# Read hook input from stdin (JSON)
+HOOK_INPUT=$(cat)
+
+# Extract the command being run
+COMMAND=$(echo "$HOOK_INPUT" | jq -r '.tool_input.command // empty')
+
+# If no command, allow (not a Bash call we care about)
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Check for forbidden patterns
+BLOCKED_REASON=""
+
+# Pattern 1: ./ctx or ./dist/ctx or ./dist/ctx-*
+if echo "$COMMAND" | grep -qE '(\./ctx|\./dist/ctx)'; then
+    BLOCKED_REASON="Use 'ctx' from PATH, not './ctx' or './dist/ctx'. Install with: sudo make install"
+fi
+
+# Pattern 2: go run ./cmd/ctx
+if echo "$COMMAND" | grep -qE 'go run \./cmd/ctx'; then
+    BLOCKED_REASON="Use 'ctx' from PATH, not 'go run ./cmd/ctx'. Install with: sudo make install"
+fi
+
+# Pattern 3: Absolute paths to ctx binary (but not just 'ctx' or paths in /usr/local/bin, /usr/bin)
+# Match things like /home/user/project/ctx or /tmp/ctx-test but allow /usr/local/bin/ctx
+if echo "$COMMAND" | grep -qE '(/home/|/tmp/|/var/)[^ ]*ctx[^ ]* '; then
+    # Exception: allow /tmp/ctx-test for integration tests
+    if ! echo "$COMMAND" | grep -qE '/tmp/ctx-test'; then
+        BLOCKED_REASON="Use 'ctx' from PATH, not absolute paths. Install with: sudo make install"
+    fi
+fi
+
+# If blocked, output JSON that tells Claude Code to reject
+if [ -n "$BLOCKED_REASON" ]; then
+    cat << EOF
+{"decision": "block", "reason": "$BLOCKED_REASON\n\nSee CONSTITUTION.md: ctx Invocation Invariants"}
+EOF
+    exit 0
+fi
+
+# Allow the command
+exit 0

internal/cli/init.go

@@ -24,14 +24,15 @@ import (
 )
 
 const (
-	contextDirName     = ".context"
-	claudeDirName      = ".claude"
-	claudeHooksDirName = ".claude/hooks"
-	settingsFileName   = ".claude/settings.local.json"
-	autoSaveScriptName = "auto-save-session.sh"
-	claudeMdFileName   = "CLAUDE.md"
-	ctxMarkerStart     = "<!-- ctx:context -->"
-	ctxMarkerEnd       = "<!-- ctx:end -->"
+	contextDirName         = ".context"
+	claudeDirName          = ".claude"
+	claudeHooksDirName     = ".claude/hooks"
+	settingsFileName       = ".claude/settings.local.json"
+	autoSaveScriptName     = "auto-save-session.sh"
+	blockNonPathScriptName = "block-non-path-ctx.sh"
+	claudeMdFileName       = "CLAUDE.md"
+	ctxMarkerStart         = "<!-- ctx:context -->"
+	ctxMarkerEnd           = "<!-- ctx:end -->"
 )
 
 var (
@@ -209,6 +210,21 @@ func createClaudeHooks(cmd *cobra.Command, force bool) error {
 		cmd.Printf("  %s %s\n", green("✓"), scriptPath)
 	}
 
+	// Create block-non-path-ctx.sh script (enforces CONSTITUTION.md ctx invocation rules)
+	blockScriptPath := filepath.Join(claudeHooksDirName, blockNonPathScriptName)
+	if _, err := os.Stat(blockScriptPath); err == nil && !force {
+		cmd.Printf("  %s %s (exists, skipped)\n", yellow("○"), blockScriptPath)
+	} else {
+		blockScriptContent, err := claude.GetBlockNonPathCtxScript()
+		if err != nil {
+			return fmt.Errorf("failed to get block-non-path-ctx script: %w", err)
+		}
+		if err := os.WriteFile(blockScriptPath, blockScriptContent, 0755); err != nil {
+			return fmt.Errorf("failed to write %s: %w", blockScriptPath, err)
+		}
+		cmd.Printf("  %s %s\n", green("✓"), blockScriptPath)
+	}
+
 	// Handle settings.local.json - merge rather than overwrite
 	if err := mergeSettingsHooks(cmd, cwd, force); err != nil {
 		return err