feature: add RequireSkillForCommand BashHandler with JSON registry

Author: cowwoc

.claude/cat/issues/v2/v2.1/enforce-skill-loading-via-hook/STATE.md

@@ -1,6 +1,7 @@
 # State
 
-- **Status:** open
-- **Progress:** 0%
+- **Status:** closed
+- **Progress:** 100%
 - **Dependencies:** []
 - **Blocks:** []
+- **Target Branch:** v2.1

client/src/main/java/io/github/cowwoc/cat/hooks/PreToolUseHook.java

@@ -20,6 +20,7 @@
 import io.github.cowwoc.cat.hooks.bash.BlockWrongBranchCommit;
 import io.github.cowwoc.cat.hooks.bash.ComputeBoxLines;
 import io.github.cowwoc.cat.hooks.bash.RemindGitSquash;
+import io.github.cowwoc.cat.hooks.bash.RequireSkillForCommand;
 import io.github.cowwoc.cat.hooks.bash.ValidateCommitType;
 import io.github.cowwoc.cat.hooks.bash.ValidateGitFilterBranch;
 import io.github.cowwoc.cat.hooks.bash.ValidateGitOperations;
@@ -79,7 +80,8 @@ public PreToolUseHook(JvmScope scope)
       new ValidateGitOperations(),
       new VerifyStateInCommit(),
       new WarnFileExtraction(),
-      new WarnMainWorkspaceCommit(scope));
+      new WarnMainWorkspaceCommit(scope),
+      new RequireSkillForCommand(scope));
   }
 
   /**

client/src/main/java/io/github/cowwoc/cat/hooks/bash/RequireSkillForCommand.java

@@ -0,0 +1,198 @@
+/*
+ * Copyright (c) 2026 Gili Tzabari. All rights reserved.
+ *
+ * Licensed under the CAT Commercial License.
+ * See LICENSE.md in the project root for license terms.
+ */
+package io.github.cowwoc.cat.hooks.bash;
+
+import static io.github.cowwoc.requirements13.java.DefaultJavaValidators.requireThat;
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import io.github.cowwoc.cat.hooks.BashHandler;
+import io.github.cowwoc.cat.hooks.HookInput;
+import io.github.cowwoc.cat.hooks.JvmScope;
+import io.github.cowwoc.cat.hooks.util.SkillLoader;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import tools.jackson.databind.JsonNode;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.NoSuchFileException;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Blocks guarded Bash commands unless the required skill has already been loaded in the current agent's
+ * session.
+ * <p>
+ * A JSON registry file at {@code CLAUDE_PLUGIN_ROOT/config/skill-triggers.json} maps regex patterns
+ * to required skill names. When a command matches a pattern, this handler checks whether the corresponding
+ * skill is present in the agent's {@code skills-loaded} marker file. If the skill has not been loaded, the
+ * command is blocked with an actionable error message.
+ * <p>
+ * This handler fails open: if the registry file or marker file cannot be read due to an I/O error, the
+ * command is allowed to proceed. This prevents blocking legitimate work during setup errors.
+ */
+public final class RequireSkillForCommand implements BashHandler
+{
+  private final Logger log = LoggerFactory.getLogger(RequireSkillForCommand.class);
+  private final JvmScope scope;
+  private final List<GuardEntry> guards;
+
+  /**
+   * A mapping from a compiled regex pattern to the required skill name.
+   *
+   * @param pattern the compiled regex pattern to match against bash commands
+   * @param skill the fully-qualified skill name required when the pattern matches (e.g. {@code cat:git-rebase-agent})
+   */
+  private record GuardEntry(Pattern pattern, String skill)
+  {
+  }
+
+  /**
+   * Creates a new handler that reads the registry from the plugin root at construction time.
+   *
+   * @param scope the JVM scope providing access to shared resources including the plugin root and JSON mapper
+   * @throws NullPointerException if {@code scope} is null
+   */
+  public RequireSkillForCommand(JvmScope scope)
+  {
+    requireThat(scope, "scope").isNotNull();
+    this.scope = scope;
+    this.guards = loadGuards();
+  }
+
+  /**
+   * Loads guard entries from the skill-triggers.json file.
+   * <p>
+   * If the file cannot be read or parsed, logs the error and returns an empty list (fail-open).
+   *
+   * @return the list of guard entries, never null
+   */
+  private List<GuardEntry> loadGuards()
+  {
+    Path registryFile = scope.getClaudePluginRoot().resolve("config").resolve("skill-triggers.json");
+    List<GuardEntry> result = new ArrayList<>();
+    try
+    {
+      if (!Files.exists(registryFile))
+      {
+        log.warn("RequireSkillForCommand: registry file not found: {}", registryFile);
+        return result;
+      }
+      String content = Files.readString(registryFile, UTF_8);
+      JsonNode root = scope.getJsonMapper().readTree(content);
+      JsonNode guardsNode = root.get("guards");
+      if (guardsNode == null || !guardsNode.isArray())
+      {
+        log.warn("RequireSkillForCommand: registry file missing 'guards' array: {}", registryFile);
+        return result;
+      }
+      for (JsonNode entry : guardsNode)
+      {
+        JsonNode patternNode = entry.get("pattern");
+        JsonNode skillNode = entry.get("skill");
+        if (patternNode == null || !patternNode.isString() || skillNode == null || !skillNode.isString())
+        {
+          log.warn("RequireSkillForCommand: skipping invalid guard entry: {}", entry);
+          continue;
+        }
+        String patternString = patternNode.asString();
+        String skillName = skillNode.asString();
+        Pattern compiled = Pattern.compile(patternString, Pattern.CASE_INSENSITIVE);
+        result.add(new GuardEntry(compiled, skillName));
+      }
+    }
+    catch (IOException e)
+    {
+      log.error("RequireSkillForCommand: failed to load registry from {}: {}", registryFile,
+        e.getMessage(), e);
+    }
+    return result;
+  }
+
+  /**
+   * Checks whether the bash command requires a skill that has not yet been loaded.
+   * <p>
+   * The agent's {@code skills-loaded} marker file is read once before the guard loop. Each guard whose
+   * pattern matches the command is then checked against the in-memory skill set. If any required skill is
+   * absent, the command is blocked. If the command matches no pattern, it is allowed.
+   * <p>
+   * This handler fails open: I/O errors reading the marker file or unexpected agent ID formats cause the
+   * command to be allowed rather than blocked.
+   *
+   * @param input the hook input containing the bash command and session information
+   * @return a block result if a required skill is not loaded, or an allow result otherwise
+   * @throws NullPointerException if {@code input} is null
+   */
+  @Override
+  public Result check(HookInput input)
+  {
+    requireThat(input, "input").isNotNull();
+    String command = input.getCommand();
+    if (command.isBlank())
+      return Result.allow();
+
+    String sessionId = input.getSessionId();
+    String catAgentId = input.getCatAgentId(sessionId);
+    Path baseDir = scope.getSessionBasePath().toAbsolutePath().normalize();
+    Set<String> loadedSkills;
+    try
+    {
+      Path agentDir = SkillLoader.resolveAndValidateContainment(baseDir, catAgentId, "catAgentId");
+      Path markerFile = agentDir.resolve("skills-loaded");
+      String content = Files.readString(markerFile, UTF_8);
+      loadedSkills = SkillLoader.parseSkillNames(content);
+    }
+    catch (NoSuchFileException _)
+    {
+      loadedSkills = Set.of();
+    }
+    catch (IllegalArgumentException e)
+    {
+      log.error("RequireSkillForCommand: unexpected catAgentId format '{}': {}", catAgentId,
+        e.getMessage(), e);
+      return Result.allow();
+    }
+    catch (IOException e)
+    {
+      log.error("RequireSkillForCommand: failed to read skills-loaded marker for agent '{}': {}",
+        catAgentId, e.getMessage(), e);
+      return Result.allow();
+    }
+
+    for (GuardEntry guard : guards)
+    {
+      if (!guard.pattern().matcher(command).find())
+        continue;
+      if (!loadedSkills.contains(guard.skill()))
+        return buildBlockResult(guard.skill());
+    }
+
+    return Result.allow();
+  }
+
+  /**
+   * Builds a block result with an actionable message naming the required skill.
+   *
+   * @param skillName the fully-qualified skill name that must be loaded (e.g. {@code cat:git-rebase-agent})
+   * @return a block result with the formatted message
+   */
+  private Result buildBlockResult(String skillName)
+  {
+    String skillBaseName = SkillLoader.stripPrefix(skillName);
+    String message = """
+      BLOCKED: This command requires the %s skill.
+
+      Load the skill first:
+        /cat:%s
+
+      Then retry the command.""".formatted(skillName, skillBaseName);
+    return Result.block(message);
+  }
+}

client/src/main/java/io/github/cowwoc/cat/hooks/util/SkillLoader.java

@@ -245,13 +245,30 @@ public SkillLoader(JvmScope scope, List<String> skillArgs) throws IOException
     if (Files.exists(agentMarkerFile))
     {
       String content = Files.readString(agentMarkerFile, StandardCharsets.UTF_8);
-      for (String line : content.split("\n"))
-      {
-        String trimmed = line.strip();
-        if (!trimmed.isEmpty())
-          loadedSkills.add(trimmed);
-      }
+      loadedSkills.addAll(parseSkillNames(content));
+    }
+  }
+
+  /**
+   * Parses a skills-loaded marker file's content into a set of skill names.
+   * <p>
+   * Each non-blank line in the content is treated as a skill name after stripping surrounding whitespace.
+   *
+   * @param content the content of a {@code skills-loaded} marker file
+   * @return the set of skill names present in the content
+   * @throws NullPointerException if {@code content} is null
+   */
+  public static Set<String> parseSkillNames(String content)
+  {
+    requireThat(content, "content").isNotNull();
+    Set<String> skills = new HashSet<>();
+    for (String line : content.split("\n"))
+    {
+      String stripped = line.strip();
+      if (!stripped.isEmpty())
+        skills.add(stripped);
     }
+    return skills;
   }
 
   /**
@@ -383,7 +400,7 @@ private String loadRawContent(String skillName) throws IOException
    * @param qualifiedName the qualified skill name
    * @return the bare skill name without the prefix
    */
-  private static String stripPrefix(String qualifiedName)
+  public static String stripPrefix(String qualifiedName)
   {
     int colonIndex = qualifiedName.indexOf(':');
     if (colonIndex >= 0)