adaptive subagent dispatch: first run sequential, subsequent runs parallel

Author: AdamBien

zsmith/src/main/java/airhacks/zsmith/subagent/control/SubAgentTool.java

@@ -1,14 +1,20 @@
 package airhacks.zsmith.subagent.control;
 
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
 import org.json.JSONObject;
 
 import airhacks.zsmith.agent.boundary.Agent;
+import airhacks.zsmith.configuration.control.ZCfg;
 import airhacks.zsmith.logging.control.Log;
 import airhacks.zsmith.tools.control.Tool;
 
 public class SubAgentTool implements Tool {
 
     static final int DEFAULT_MAX_DEPTH = 3;
+    static final String FIRST_RUN_MARKER = ".first_run_completed";
     static final ScopedValue<Integer> DEPTH = ScopedValue.newInstance();
 
     private final Agent subAgent;
@@ -68,7 +74,7 @@ public String inputSchema() {
 
     @Override
     public boolean parallel() {
-        return this.runParallel;
+        return this.runParallel && firstRunCompleted();
     }
 
     @Override
@@ -83,9 +89,32 @@ public String execute(JSONObject input) {
             var result = ScopedValue.where(DEPTH, currentDepth + 1)
                     .call(() -> this.subAgent.chat(task));
             Log.subagent("sub-agent '%s' completed".formatted(this.subAgent.name()));
+            markFirstRunCompleted();
             return result;
         } catch (Exception e) {
             return "Error: Sub-agent '%s' failed: %s".formatted(this.subAgent.name(), e.getMessage());
         }
     }
+
+    boolean firstRunCompleted() {
+        return Files.exists(markerPath());
+    }
+
+    void markFirstRunCompleted() {
+        var path = markerPath();
+        try {
+            Files.createDirectories(path.getParent());
+            if (!Files.exists(path)) {
+                Files.writeString(path, "");
+            }
+        } catch (IOException e) {
+            Log.warning("could not write first-run marker for "
+                    + this.subAgent.name() + ": " + e.getMessage());
+        }
+    }
+
+    Path markerPath() {
+        var userHome = System.getProperty("user.home");
+        return Path.of(userHome, "." + ZCfg.APP_NAME, this.subAgent.name(), FIRST_RUN_MARKER);
+    }
 }

zsmith/src/main/resources/version.txt

@@ -1 +1 @@
-2026.04.24.03
+2026.04.27.01

zsmith/src/test/java/SubAgentToolTest.java

@@ -1,7 +1,11 @@
+import java.nio.file.Files;
+import java.nio.file.Path;
+
 import airhacks.zsmith.agent.boundary.Agent;
+import airhacks.zsmith.configuration.control.ZCfg;
 import airhacks.zsmith.subagent.control.SubAgentTool;
 
-void main() {
+void main() throws Exception {
     var child = new Agent("researcher", "You are a research assistant.");
     var tool = new SubAgentTool(child);
 
@@ -35,4 +39,34 @@ void main() {
     var result = shallowTool.execute(new org.json.JSONObject().put("task", "test"));
     assert result.contains("Error") && result.contains("depth")
             : "expected depth error but got: " + result;
+
+    // adaptive parallel: first run sequential, subsequent runs parallel
+    var sandboxHome = Files.createTempDirectory("zsmith-subagent-test");
+    var originalHome = System.getProperty("user.home");
+    System.setProperty("user.home", sandboxHome.toString());
+    try {
+        var firstRunChild = new Agent("first-run-probe", "test");
+        var firstRunTool = new SubAgentTool(firstRunChild);
+
+        var markerPath = Path.of(sandboxHome.toString(), "." + ZCfg.APP_NAME,
+                "first-run-probe", ".first_run_completed");
+        Files.deleteIfExists(markerPath);
+
+        // runParallel=true but no marker yet → sequential
+        assert !firstRunTool.parallel()
+                : "expected parallel()=false on first run (no marker)";
+
+        // simulate completion of a first successful run
+        Files.createDirectories(markerPath.getParent());
+        Files.writeString(markerPath, "");
+        assert firstRunTool.parallel()
+                : "expected parallel()=true once marker exists";
+
+        // sequential override always wins, even with marker
+        var sequentialTool = new SubAgentTool(firstRunChild, false);
+        assert !sequentialTool.parallel()
+                : "expected parallel()=false when runParallel=false regardless of marker";
+    } finally {
+        System.setProperty("user.home", originalHome);
+    }
 }