refactor: eliminate cwd-worktree assumption, centralize sessionId validation in HookInput

- WorktreeContext now resolved from git rather than assuming cwd is a worktree
- GetDiffOutput, WarnBaseBranchEdit, and other hooks use git-based resolution
- HookInput.validateSessionId() uses requireThat Jackson validator for fail-fast validation
- Remove HookInput.empty() ??? callers now pass valid hard-coded session IDs
- Remove getRequiredSessionId() ??? getSessionId() always returns a valid value
- Rename getCompositeAgentId() to getCatAgentId()
- Remove static SESSION_CACHE from WorktreeLock (caused test contamination)
- All tests updated: inject valid session_id, expect IllegalArgumentException on blank/missing

Author: cowwoc

.claude/cat/issues/v2/v2.1/eliminate-cwd-worktree-assumption/STATE.md

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

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

@@ -63,7 +63,8 @@ public static void main(String[] args) throws Exception
     try (JvmScope scope = new MainJvmScope())
     {
       JsonMapper mapper = scope.getJsonMapper();
-      HookInput input = HookInput.empty(mapper);
+      HookInput input = HookInput.readFrom(mapper, new ByteArrayInputStream(
+        "{\"session_id\": \"aot-training-session\"}".getBytes(StandardCharsets.UTF_8)));
       HookOutput output = new HookOutput(scope);
 
       // Hook handlers with run(HookInput, HookOutput)

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

@@ -6,6 +6,7 @@
  */
 package io.github.cowwoc.cat.hooks;
 
+import static io.github.cowwoc.requirements13.jackson.DefaultJacksonValidators.requireThat;
 import static io.github.cowwoc.requirements13.java.DefaultJavaValidators.requireThat;
 
 import io.github.cowwoc.cat.hooks.util.SkillLoader;
@@ -67,18 +68,18 @@ private HookInput(JsonMapper mapper, JsonNode data)
    * Validates and returns the session ID from the JSON data.
    *
    * @param data the parsed JSON data
-   * @return the session ID, or empty string if missing or empty
-   * @throws IllegalArgumentException if the session_id field is present but contains characters other than
-   *   alphanumerics, hyphens, and underscores
+   * @return the session ID (never empty)
+   * @throws IllegalArgumentException if the session_id field is missing, blank, or contains characters
+   *   other than alphanumerics, hyphens, and underscores
    */
   private static String validateSessionId(JsonNode data)
   {
-    JsonNode node = data.get("session_id");
-    if (node == null || !node.isString())
-      return "";
-    String value = node.asString();
-    if (value == null || value.isBlank())
-      return "";
+    String value = requireThat(data, "data").property("session_id").isString().getValue().asString();
+    if (value.isBlank())
+    {
+      throw new IllegalArgumentException(
+        "sessionId is empty. Hook infrastructure must provide CLAUDE_SESSION_ID.");
+    }
     if (!SESSION_ID_PATTERN.matcher(value).matches())
     {
       throw new IllegalArgumentException("Invalid session_id format: '" + value +
@@ -115,23 +116,22 @@ private static String validateAgentId(JsonNode data)
    * Read and parse JSON input from stdin.
    *
    * @param mapper the JSON mapper to use for parsing
-   * @return parsed hook input, or empty input if stdin is not available or contains invalid JSON
+   * @return parsed hook input
    * @throws NullPointerException if mapper is null
+   * @throws IllegalStateException if stdin has no piped input, contains blank/malformed JSON, or is missing
+   *   a session_id
    */
   public static HookInput readFromStdin(JsonMapper mapper)
   {
     requireThat(mapper, "mapper").isNotNull();
     try
     {
       if (System.console() != null && System.in.available() == 0)
-      {
-        // Interactive terminal with no piped input
-        return new HookInput(mapper, mapper.createObjectNode());
-      }
+        throw new IllegalStateException("No piped input available on stdin.");
     }
-    catch (IOException _)
+    catch (IOException e)
     {
-      return new HookInput(mapper, mapper.createObjectNode());
+      throw new IllegalStateException("Failed to check stdin availability.", e);
     }
     return readFrom(mapper, System.in);
   }
@@ -141,8 +141,9 @@ public static HookInput readFromStdin(JsonMapper mapper)
    *
    * @param mapper the JSON mapper to use for parsing
    * @param inputStream the stream to read from
-   * @return parsed hook input, or empty input if the stream is not available or contains invalid JSON
+   * @return parsed hook input
    * @throws NullPointerException if mapper or inputStream is null
+   * @throws IllegalStateException if the stream contains blank/malformed JSON, or is missing a session_id
    */
   public static HookInput readFrom(JsonMapper mapper, InputStream inputStream)
   {
@@ -153,31 +154,18 @@ public static HookInput readFrom(JsonMapper mapper, InputStream inputStream)
       BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8));
       String raw = reader.lines().collect(Collectors.joining("\n"));
 
-      if (raw == null || raw.isBlank())
-        return new HookInput(mapper, mapper.createObjectNode());
+      if (raw.isBlank())
+        throw new IllegalStateException("Hook input is blank.");
 
       JsonNode node = mapper.readTree(raw);
       return new HookInput(mapper, node);
     }
-    catch (JacksonException _)
+    catch (JacksonException e)
     {
-      return new HookInput(mapper, mapper.createObjectNode());
+      throw new IllegalStateException("Hook input contains malformed JSON.", e);
     }
   }
 
-  /**
-   * Create an empty hook input.
-   *
-   * @param mapper the JSON mapper to use
-   * @return an empty HookInput instance
-   * @throws NullPointerException if mapper is null
-   */
-  public static HookInput empty(JsonMapper mapper)
-  {
-    requireThat(mapper, "mapper").isNotNull();
-    return new HookInput(mapper, mapper.createObjectNode());
-  }
-
   /**
    * Create a HookInput for a bash command with explicit field values.
    * <p>
@@ -358,11 +346,8 @@ public boolean isEmpty()
 
   /**
    * Get the session ID from standard hook input locations.
-   * <p>
-   * Returns empty string if the session ID is missing or empty. Throws if the session ID is present but
-   * contains characters other than alphanumerics, hyphens, and underscores.
    *
-   * @return the session ID, or empty string if not present
+   * @return the session ID (never empty)
    */
   public String getSessionId()
   {
@@ -392,7 +377,7 @@ public String getAgentId()
    * @return the composite agent ID
    * @throws NullPointerException if {@code sessionId} is null
    */
-  public String getCompositeAgentId(String sessionId)
+  public String getCatAgentId(String sessionId)
   {
     requireThat(sessionId, "sessionId").isNotNull();
     String nativeAgentId = getAgentId();

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

@@ -74,9 +74,6 @@ public HookResult run(HookInput input, HookOutput output)
     requireThat(output, "output").isNotNull();
 
     String sessionId = input.getSessionId();
-    if (sessionId.isEmpty())
-      return HookResult.withoutWarnings(output.empty());
-
     // Create handlers using sessionId from HookInput
     Path sessionDirectory = scope.getSessionBasePath().resolve(sessionId);
     List<PostToolHandler> handlers = List.of(

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

@@ -8,6 +8,7 @@
 
 import static io.github.cowwoc.requirements13.java.DefaultJavaValidators.requireThat;
 
+import io.github.cowwoc.cat.hooks.write.EnforceWorktreePathIsolation;
 import tools.jackson.databind.JsonNode;
 
 import java.util.ArrayList;
@@ -41,7 +42,9 @@ public final class PreReadHook implements HookHandler
   public PreReadHook(JvmScope scope)
   {
     requireThat(scope, "scope").isNotNull();
-    this.handlers = List.of(scope.getPredictBatchOpportunity());
+    this.handlers = List.of(
+      scope.getPredictBatchOpportunity(),
+      new EnforceWorktreePathIsolation(scope));
   }
 
   /**

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

@@ -15,8 +15,6 @@
 import java.nio.file.DirectoryStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.ConcurrentMap;
 
 /**
  * Utility for looking up the worktree lock associated with a session.
@@ -27,10 +25,6 @@
  */
 public final class WorktreeLock
 {
-  // Cache from sessionId to issueId. Empty string "" is a sentinel meaning "no lock found".
-  private static final ConcurrentMap<String, String> SESSION_CACHE = new ConcurrentHashMap<>();
-  private static final int MAX_CACHE_SIZE = 100;
-
   /**
    * Prevent instantiation.
    */
@@ -58,20 +52,9 @@ public static String findIssueIdForSession(Path projectCatDir, JsonMapper jsonMa
     requireThat(jsonMapper, "jsonMapper").isNotNull();
     requireThat(sessionId, "sessionId").isNotBlank();
 
-    String cached = SESSION_CACHE.get(sessionId);
-    if (cached != null)
-    {
-      if (cached.isEmpty())
-        return null;
-      return cached;
-    }
-
     Path lockDir = projectCatDir.resolve("locks");
     if (!Files.isDirectory(lockDir))
-    {
-      cacheResult(sessionId, "");
       return null;
-    }
 
     try (DirectoryStream<Path> stream = Files.newDirectoryStream(lockDir, "*.lock"))
     {
@@ -88,9 +71,7 @@ public static String findIssueIdForSession(Path projectCatDir, JsonMapper jsonMa
           if (sessionId.equals(sessionNode.asString()))
           {
             String filename = lockFile.getFileName().toString();
-            String issueId = filename.substring(0, filename.length() - ".lock".length());
-            cacheResult(sessionId, issueId);
-            return issueId;
+            return filename.substring(0, filename.length() - ".lock".length());
           }
         }
         catch (IOException _)
@@ -104,20 +85,6 @@ public static String findIssueIdForSession(Path projectCatDir, JsonMapper jsonMa
       // Lock directory not accessible - no active lock context
     }
 
-    cacheResult(sessionId, "");
     return null;
   }
-
-  /**
-   * Stores a result in the session cache, clearing the cache first if the size limit is reached.
-   *
-   * @param sessionId the session ID to cache
-   * @param value the issue ID, or an empty string to indicate no lock was found
-   */
-  private static void cacheResult(String sessionId, String value)
-  {
-    if (SESSION_CACHE.size() >= MAX_CACHE_SIZE)
-      SESSION_CACHE.clear();
-    SESSION_CACHE.put(sessionId, value);
-  }
 }

client/src/main/java/io/github/cowwoc/cat/hooks/ask/WarnApprovalWithoutRenderDiff.java

@@ -65,9 +65,6 @@ public Result check(JsonNode toolInput, String sessionId)
     if (!Files.isDirectory(catDir))
       return Result.allow();
 
-    if (sessionId.isEmpty())
-      return Result.allow();
-
     Path sessionFile = scope.getSessionBasePath().resolve(sessionId + ".jsonl");
 
     if (!Files.exists(sessionFile))

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

@@ -9,6 +9,7 @@
 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.WorktreeContext;
 import io.github.cowwoc.cat.hooks.util.GitCommands;
 
 import java.io.IOException;
@@ -56,11 +57,12 @@ public Result check(HookInput input)
   {
     String command = input.getCommand();
     String commandLower = GitCommands.toLowerCase(command);
+    String sessionId = input.getSessionId();
 
     // Check for git checkout/switch in main worktree
     if (CHECKOUT_PATTERN.matcher(commandLower).find())
     {
-      Result checkoutResult = checkCheckoutInMainWorktree(command);
+      Result checkoutResult = checkCheckoutInMainWorktree(command, sessionId);
       if (checkoutResult != null)
         return checkoutResult;
     }
@@ -70,7 +72,7 @@ public Result check(HookInput input)
       return Result.allow();
 
     // Check if rebasing on main
-    String currentBranch = getCurrentBranch(command);
+    String currentBranch = getCurrentBranch(command, sessionId);
     if (currentBranch == null)
     {
       return Result.warn(
@@ -106,9 +108,10 @@ public Result check(HookInput input)
    * Checks if a checkout command is targeting the main worktree.
    *
    * @param command the bash command
+   * @param sessionId the session ID for worktree context lookup
    * @return a block result if checkout in main worktree detected, null otherwise
    */
-  private Result checkCheckoutInMainWorktree(String command)
+  private Result checkCheckoutInMainWorktree(String command, String sessionId)
   {
     // Check if command cd's to the project directory
     if (cdProjectPattern.matcher(command).find())
@@ -135,30 +138,17 @@ private Result checkCheckoutInMainWorktree(String command)
       }
     }
 
-    // Check if currently in the project directory (main worktree)
-    String cwd = System.getProperty("user.dir");
-    if (projectDir.toString().equals(cwd))
+    WorktreeContext context = WorktreeContext.forSession(
+      scope.getProjectCatDir(), projectDir, scope.getJsonMapper(), sessionId);
+    if (context == null)
     {
-      boolean mainWorktree;
-      try
-      {
-        mainWorktree = GitCommands.isMainWorktree();
-      }
-      catch (IOException _)
-      {
-        return Result.warn(
-          "Failed to determine if this is the main worktree while checking checkout safety.\n" +
-          "Proceeding without main worktree check.");
-      }
-      if (mainWorktree)
+      // No active worktree for this session — this is the main context; block checkout
+      String target = extractCheckoutTarget(command);
+      if (!isCheckoutFlag(target))
       {
-        String target = extractCheckoutTarget(command);
-        if (!isCheckoutFlag(target))
-        {
-          return Result.block(String.format(
-            "Blocked: Cannot checkout '%s' in main worktree. Use issue worktrees instead.",
-            target));
-        }
+        return Result.block(String.format(
+          "Blocked: Cannot checkout '%s' in main worktree. Use issue worktrees instead.",
+          target));
       }
     }
 
@@ -194,9 +184,10 @@ private String extractCheckoutTarget(String command)
    * Determines the current branch for the command's target directory.
    *
    * @param command the bash command (may contain cd to another directory)
+   * @param sessionId the session ID for worktree context lookup
    * @return the branch name, or {@code null} if branch detection failed
    */
-  private String getCurrentBranch(String command)
+  private String getCurrentBranch(String command, String sessionId)
   {
     // Check if command cd's to the project directory
     if (cdProjectPattern.matcher(command).find())
@@ -217,10 +208,25 @@ private String getCurrentBranch(String command)
       }
     }
 
-    // Fallback to current directory
+    // Use lock-based worktree context to determine branch
+    WorktreeContext context = WorktreeContext.forSession(
+      scope.getProjectCatDir(), projectDir, scope.getJsonMapper(), sessionId);
+    if (context == null)
+    {
+      // No active worktree for this session — commands run in main context
+      try
+      {
+        return GitCommands.getCurrentBranch(projectDir.toString());
+      }
+      catch (IOException _)
+      {
+        return null;
+      }
+    }
+    // In a worktree — determine branch from worktree directory
     try
     {
-      return GitCommands.getCurrentBranch();
+      return GitCommands.getCurrentBranch(context.absoluteWorktreePath().toString());
     }
     catch (IOException _)
     {

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

@@ -105,7 +105,7 @@ public Result check(HookInput input)
     String command = input.getCommand();
     String workingDirectory = input.getString("cwd");
     String sessionId = input.getSessionId();
-    String catAgentId = input.getCompositeAgentId(sessionId);
+    String catAgentId = input.getCatAgentId(sessionId);
 
     try
     {