refactor: remove CLAUDE_ENV_FILE from ClaudeTool and ClaudeHook scopes

Author: cowwoc

.cat/issues/v2/v2.1/remove-env-file-from-scopes/index.json

@@ -1 +1,4 @@
-{"status": "open"}
+{
+  "status": "closed",
+  "resolution": "implemented"
+}

.cat/issues/v2/v2.1/remove-env-file-from-scopes/plan.md

@@ -25,3 +25,127 @@ is not set outside of SessionStart context.
 - [ ] Tests passing — `mvn -f client/pom.xml verify -e` exits 0
 - [ ] No regressions in existing functionality
 - [ ] E2E: Invoke a CLI tool (e.g., `get-status-output`) and confirm it no longer requires `CLAUDE_ENV_FILE` to be set
+
+## Research Findings
+
+### Current Architecture
+
+The `getEnvFile()` method exists in two parallel interface hierarchies:
+- `ClaudeTool` (for CLI tools) → `AbstractClaudeTool` (stores `envFile` field) → `MainClaudeTool` (reads env var at
+  construction)
+- `ClaudeHook` (for hook handlers) → `AbstractClaudeHook` (declares abstract) → `MainClaudeHook` (reads env var
+  on-demand)
+
+Neither `JvmScope` (the base interface) defines `getEnvFile()` — it's specific to `ClaudeTool` and `ClaudeHook`.
+
+### Single Real Consumer
+
+Only `InjectEnv.java` (line 68) calls `scope.getEnvFile()`. It uses the path to write environment variable export
+statements for subsequent Bash tool invocations. `InjectEnv` receives a `ClaudeTool` scope, so it can simply call
+`System.getenv("CLAUDE_ENV_FILE")` directly instead of going through the scope.
+
+### Files to Modify
+
+| File | Change |
+|------|--------|
+| `client/src/main/java/io/github/cowwoc/cat/hooks/ClaudeTool.java` | Remove `getEnvFile()` method declaration |
+| `client/src/main/java/io/github/cowwoc/cat/hooks/ClaudeHook.java` | Remove `getEnvFile()` method declaration |
+| `client/src/main/java/io/github/cowwoc/cat/hooks/AbstractClaudeTool.java` | Remove `envFile` field, constructor param, `getEnvFile()` impl |
+| `client/src/main/java/io/github/cowwoc/cat/hooks/AbstractClaudeHook.java` | Remove abstract `getEnvFile()` declaration |
+| `client/src/main/java/io/github/cowwoc/cat/hooks/MainClaudeTool.java` | Remove `CLAUDE_ENV_FILE` from constructor |
+| `client/src/main/java/io/github/cowwoc/cat/hooks/MainClaudeHook.java` | Remove `getEnvFile()` implementation |
+| `client/src/main/java/io/github/cowwoc/cat/hooks/session/InjectEnv.java` | Read `CLAUDE_ENV_FILE` via `System.getenv()` directly |
+| `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeTool.java` | Remove envFile constructor params and `withEnvFile()` factory |
+| `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeHook.java` | Remove `getEnvFile()` implementation |
+| `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeToolTest.java` | Remove `getEnvFile()` test assertion |
+| `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeHookTest.java` | Remove `getEnvFile()` test assertions |
+| `client/src/test/java/io/github/cowwoc/cat/hooks/test/EnforceJvmScopeEnvAccessTest.java` | Add `InjectEnv.java` to whitelist |
+
+## Sub-Agent Waves
+
+### Wave 1
+
+Each step below is a discrete edit. Read each file before editing. Commit type: `refactor:`.
+
+**Step 1: Remove `getEnvFile()` from `ClaudeTool` interface**
+- File: `client/src/main/java/io/github/cowwoc/cat/hooks/ClaudeTool.java`
+- Remove the `getEnvFile()` method declaration and its Javadoc comment block
+
+**Step 2: Remove `getEnvFile()` from `ClaudeHook` interface**
+- File: `client/src/main/java/io/github/cowwoc/cat/hooks/ClaudeHook.java`
+- Remove the `getEnvFile()` method declaration and its Javadoc comment block
+
+**Step 3: Remove `envFile` from `AbstractClaudeTool`**
+- File: `client/src/main/java/io/github/cowwoc/cat/hooks/AbstractClaudeTool.java`
+- Remove the `private final Path envFile;` field
+- Remove the `envFile` parameter from the protected constructor and the `this.envFile = envFile;` assignment
+- Remove the entire `getEnvFile()` method implementation
+- Remove the `@Override` annotation above `getEnvFile()` if present
+- Keep all other fields and methods intact
+
+**Step 4: Remove abstract `getEnvFile()` from `AbstractClaudeHook`**
+- File: `client/src/main/java/io/github/cowwoc/cat/hooks/AbstractClaudeHook.java`
+- Remove the `@Override public abstract Path getEnvFile();` declaration
+
+**Step 5: Remove `CLAUDE_ENV_FILE` from `MainClaudeTool` constructor**
+- File: `client/src/main/java/io/github/cowwoc/cat/hooks/MainClaudeTool.java`
+- In the constructor, remove the `Path.of(getEnvVar("CLAUDE_ENV_FILE"))` argument from the `super()` call
+- The super call should become:
+  `super(getEnvVar("CLAUDE_SESSION_ID"), Path.of(getEnvVar("CLAUDE_PROJECT_DIR")), Path.of(getEnvVar("CLAUDE_PLUGIN_ROOT")))`
+
+**Step 6: Remove `getEnvFile()` from `MainClaudeHook`**
+- File: `client/src/main/java/io/github/cowwoc/cat/hooks/MainClaudeHook.java`
+- Remove the entire `getEnvFile()` method (the `@Override` block that reads `System.getenv("CLAUDE_ENV_FILE")`)
+
+**Step 7: Update `InjectEnv` to read `CLAUDE_ENV_FILE` directly**
+- File: `client/src/main/java/io/github/cowwoc/cat/hooks/session/InjectEnv.java`
+- At line 68 (or wherever `Path envPath = scope.getEnvFile();` appears), replace with:
+  ```java
+  String envFileValue = System.getenv("CLAUDE_ENV_FILE");
+  if (envFileValue == null || envFileValue.isBlank())
+      throw new AssertionError("CLAUDE_ENV_FILE is not set");
+  Path envPath = Path.of(envFileValue);
+  ```
+- Update imports if needed (should already have `java.nio.file.Path`)
+
+**Step 8: Update `TestClaudeTool`**
+- File: `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeTool.java`
+- Remove the `envFile` parameter from ALL constructors (there are multiple — check each one)
+- Remove the `withEnvFile()` factory method (around line 194-198)
+- Update `super()` calls to no longer pass `envFile`
+- Remove any constructor that defaults to `claudeProjectPath.resolve(".env")` — remove that default
+
+**Step 9: Update `TestClaudeHook`**
+- File: `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeHook.java`
+- Remove the `getEnvFile()` implementation method
+
+**Step 10: Update `TestClaudeToolTest`**
+- File: `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeToolTest.java`
+- Remove any test assertion that calls `getEnvFile()` (around line 276)
+
+**Step 11: Update `TestClaudeHookTest`**
+- File: `client/src/test/java/io/github/cowwoc/cat/hooks/test/TestClaudeHookTest.java`
+- Remove test assertions that call `getEnvFile()` (around lines 42 and 184)
+- If entire test methods only test `getEnvFile()`, remove the whole test method
+
+**Step 12: Update `EnforceJvmScopeEnvAccessTest` whitelist**
+- File: `client/src/test/java/io/github/cowwoc/cat/hooks/test/EnforceJvmScopeEnvAccessTest.java`
+- Add `io/github/cowwoc/cat/hooks/session/InjectEnv.java` to the whitelist set (around lines 64-73)
+- This authorizes `InjectEnv` to call `System.getenv()` directly
+- If `MainClaudeHook.java` no longer calls `System.getenv("CLAUDE_ENV_FILE")`, verify whether it still
+  needs to be in the whitelist (it may call `System.getenv()` for other variables — check before removing)
+
+**Step 13: Remove unused imports**
+- After all changes, check each modified file for unused imports (especially `java.nio.file.Path` in files
+  that no longer reference `Path`)
+
+**Step 14: Build and test**
+- Run `mvn -f client/pom.xml verify -e` and ensure all tests pass
+- Fix any compilation errors from the changes above
+
+**Step 15: Update `index.json`**
+- Update `.cat/issues/v2/v2.1/remove-env-file-from-scopes/index.json` to set status to `closed`
+
+**Step 16: Commit**
+- Stage all changed files
+- Commit with message: `refactor: remove CLAUDE_ENV_FILE from ClaudeTool and ClaudeHook scopes`

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

@@ -175,19 +175,6 @@ private static String validateAgentId(JsonNode data)
     return value;
   }
 
-  /**
-   * Returns the path to the Claude environment file.
-   * <p>
-   * Subclasses must implement this to provide the env file path from {@code CLAUDE_ENV_FILE}
-   * or an injected value.
-   *
-   * @return the path to the env file
-   * @throws AssertionError if {@code CLAUDE_ENV_FILE} is not set in the environment
-   * @throws IllegalStateException if this scope is closed
-   */
-  @Override
-  public abstract Path getEnvFile();
-
   @Override
   public Path getProjectPath()
   {

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

@@ -25,29 +25,25 @@ public abstract class AbstractClaudeTool extends AbstractJvmScope implements Cla
   private final String sessionId;
   private final Path projectPath;
   private final Path pluginRoot;
-  private final Path envFile;
 
   /**
    * Creates a new abstract Claude tool scope with the given environment values.
    *
    * @param sessionId the Claude session ID
    * @param projectPath the project's root directory path (must be absolute)
    * @param pluginRoot the Claude plugin root directory path (must be absolute)
-   * @param envFile the path to the Claude environment file
    * @throws IllegalArgumentException if {@code sessionId} is blank, or if {@code projectPath} or
    *   {@code pluginRoot} are not absolute paths
-   * @throws NullPointerException if {@code projectPath}, {@code pluginRoot}, or {@code envFile} are null
+   * @throws NullPointerException if {@code projectPath} or {@code pluginRoot} are null
    */
-  protected AbstractClaudeTool(String sessionId, Path projectPath, Path pluginRoot, Path envFile)
+  protected AbstractClaudeTool(String sessionId, Path projectPath, Path pluginRoot)
   {
     requireThat(sessionId, "sessionId").isNotBlank();
     requireThat(projectPath, "projectPath").isNotNull().isAbsolute();
     requireThat(pluginRoot, "pluginRoot").isNotNull().isAbsolute();
-    requireThat(envFile, "envFile").isNotNull();
     this.sessionId = sessionId;
     this.projectPath = projectPath;
     this.pluginRoot = pluginRoot;
-    this.envFile = envFile;
   }
 
   @Override
@@ -70,11 +66,4 @@ public Path getPluginRoot()
     ensureOpen();
     return pluginRoot;
   }
-
-  @Override
-  public Path getEnvFile()
-  {
-    ensureOpen();
-    return envFile;
-  }
 }

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

@@ -83,7 +83,7 @@ public static void main(String[] args) throws Exception
       new PreWriteHook(scope).run(scope);
       new PreIssueHook(scope).run(scope);
       new SessionEndHook(scope).run(scope);
-      new SessionStartHook(scope).run(scope);
+      new SessionStartHook(scope, Path.of("/tmp/aot-training-env")).run(scope);
       new SubagentStartHook(scope).run(scope);
 
       // Skill handlers - construct to load class graphs.

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

@@ -10,8 +10,6 @@
 import tools.jackson.databind.json.JsonMapper;
 import tools.jackson.databind.node.ObjectNode;
 
-import java.nio.file.Path;
-
 /**
  * A {@link JvmScope} for hook handler processes that combines the Claude session environment
  * (project path, plugin root, config dir), hook input data, and hook output building in a single
@@ -30,15 +28,6 @@ public interface ClaudeHook extends JvmScope
    */
   String getSessionId();
 
-  /**
-   * Returns the path to the Claude environment file.
-   *
-   * @return the path to the env file
-   * @throws AssertionError if {@code CLAUDE_ENV_FILE} is not set in the environment
-   * @throws IllegalStateException if this scope is closed
-   */
-  Path getEnvFile();
-
   // Hook input methods
 
   /**

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

@@ -45,13 +45,4 @@ public interface ClaudeTool extends JvmScope
    */
   @Override
   Path getPluginRoot();
-
-  /**
-   * Returns the path to the Claude environment file.
-   *
-   * @return the environment file path
-   * @throws AssertionError if {@code CLAUDE_ENV_FILE} is not set in the environment
-   * @throws IllegalStateException if this scope is closed
-   */
-  Path getEnvFile();
 }

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

@@ -103,16 +103,6 @@ private static Path readConfigDir()
     return Path.of(System.getProperty("user.home"), ".claude");
   }
 
-  @Override
-  public Path getEnvFile()
-  {
-    ensureOpen();
-    String value = System.getenv("CLAUDE_ENV_FILE");
-    if (value == null || value.isBlank())
-      throw new AssertionError("CLAUDE_ENV_FILE is not set");
-    return Path.of(value);
-  }
-
   @Override
   public Path getWorkDir()
   {

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

@@ -16,8 +16,8 @@
  * Production implementation of {@link JvmScope} for CLI tool processes.
  * <p>
  * Reads session environment values ({@code CLAUDE_SESSION_ID}, {@code CLAUDE_PROJECT_DIR},
- * {@code CLAUDE_PLUGIN_ROOT}, {@code CLAUDE_ENV_FILE}) from {@code System.getenv()} at
- * construction time and passes them to {@link AbstractClaudeTool}.
+ * {@code CLAUDE_PLUGIN_ROOT}) from {@code System.getenv()} at construction time and passes
+ * them to {@link AbstractClaudeTool}.
  * <p>
  * <b>Thread Safety:</b> This class is thread-safe.
  */
@@ -34,7 +34,7 @@ public final class MainClaudeTool extends AbstractClaudeTool
   /**
    * Creates a new production Claude tool scope.
    * <p>
-   * Reads the four required environment variables from {@code System.getenv()} and fails
+   * Reads the three required environment variables from {@code System.getenv()} and fails
    * immediately with {@link AssertionError} if any are unset or blank.
    *
    * @throws AssertionError if any required environment variable is not set
@@ -43,8 +43,7 @@ public MainClaudeTool()
   {
     super(getEnvVar("CLAUDE_SESSION_ID"),
       Path.of(getEnvVar("CLAUDE_PROJECT_DIR")),
-      Path.of(getEnvVar("CLAUDE_PLUGIN_ROOT")),
-      Path.of(getEnvVar("CLAUDE_ENV_FILE")));
+      Path.of(getEnvVar("CLAUDE_PLUGIN_ROOT")));
   }
 
   /**

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

@@ -23,7 +23,7 @@
  * <p>
  * This scope is appropriate for CLI tools like {@code GetSkill} that are invoked by the skill
  * preprocessor before a Claude session is established and therefore do not have access to
- * session-specific variables ({@code CLAUDE_SESSION_ID}, {@code CLAUDE_ENV_FILE}).
+ * session-specific variables ({@code CLAUDE_SESSION_ID}).
  * <p>
  * <b>Thread Safety:</b> This class is thread-safe.
  */