refactor: add ClaudeRequest builder and strengthen CLI validation

Author: Dariusz Debowczyk

.beads/issues.jsonl

@@ -203,7 +203,7 @@
 {"id":"instructor-php-5u4","title":"Introduce InferenceAttemptId value object and migrate polyglot attempt identity","description":"Create InferenceAttemptId and migrate polyglot inference attempt identity usage and serialization.","acceptance_criteria":"- Introduce the new XxxId value object as a thin wrapper delegating UUID generation/validation to Cognesy\\Utils\\Uuid.\\n- Refactor the target bounded context to use the typed ID internally (entities, state objects, repositories/stores, serializers).\\n- Do boundary normalization in one place only; avoid scattering XxxId|string across domain internals and store contracts.\\n- Remove temporary normalization helpers made obsolete by full typing.\\n- Update/adjust tests and ensure relevant test suites pass.\\n- Update package docs under ./packages/*/docs and root ./examples to reflect typed IDs and migration usage patterns.","status":"closed","priority":2,"issue_type":"task","owner":"ddebowczyk@guidewire.com","created_at":"2026-02-21T10:34:21.99745+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T19:28:24.262843+01:00","closed_at":"2026-02-21T19:28:24.262843+01:00","close_reason":"Completed InferenceAttemptId migration across inference attempt state with typed IDs, boundary serialization, docs note, and passing inference unit tests"}
 {"id":"instructor-php-5vi","title":"Analyze Claude Code hooks for execution control","description":"Review hooks-reference to understand lifecycle events, matcher patterns, decision outputs, environment handling, and how to gate/modify tool usage for controlled CLI automation.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-02T03:14:43.697285886+01:00","updated_at":"2025-12-02T03:18:08.831864483+01:00","closed_at":"2025-12-02T03:18:08.831867268+01:00"}
 {"id":"instructor-php-6pf","title":"Clean up duplicate CLAUDE.md in .taskmaster/","description":"Remove or symlink the duplicate CLAUDE.md file in .taskmaster/ directory to avoid maintenance overhead.","status":"closed","priority":2,"issue_type":"chore","created_at":"2025-11-28T12:26:27.320373256+01:00","updated_at":"2025-11-28T12:41:16.772435233+01:00","closed_at":"2025-11-28T12:41:16.772435233+01:00"}
-{"id":"instructor-php-6xl","title":"ClaudeRequest constructor is becoming unwieldy - needs builder pattern","description":"ClaudeRequest constructor now has 13+ parameters making it hard to use and understand. Should implement builder pattern: ClaudeRequestBuilder-\u003ewithPrompt()-\u003ewithOutputFormat()-\u003ebuild(). Current approach violates clean code principles and will become harder to maintain.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-02T03:43:25.623620042+01:00","updated_at":"2025-12-02T03:43:25.623620042+01:00"}
+{"id":"instructor-php-6xl","title":"ClaudeRequest constructor is becoming unwieldy - needs builder pattern","description":"ClaudeRequest constructor now has 13+ parameters making it hard to use and understand. Should implement builder pattern: ClaudeRequestBuilder-\u003ewithPrompt()-\u003ewithOutputFormat()-\u003ebuild(). Current approach violates clean code principles and will become harder to maintain.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-02T03:43:25.623620042+01:00","updated_at":"2026-02-21T21:32:20.682877+01:00","closed_at":"2026-02-21T21:32:20.682877+01:00","close_reason":"Implemented ClaudeRequestBuilder with fluent API, added ClaudeRequest::builder(), migrated ClaudeCodeBridge request construction, and covered builder flow in unit tests."}
 {"id":"instructor-php-7cr","title":"Audit and update documentation references","description":"Scan all documentation files for references to moved files and update paths. Check CLAUDE.md, AGENTS.md, CONTRIBUTOR_GUIDE.md, and docs-internal/README.md.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-28T12:26:23.552483857+01:00","updated_at":"2025-11-28T12:40:59.28781579+01:00","closed_at":"2025-11-28T12:40:59.28781579+01:00","dependencies":[{"issue_id":"instructor-php-7cr","depends_on_id":"instructor-php-jnb","type":"blocks","created_at":"2025-11-28T12:26:40.418982566+01:00","created_by":"daemon","metadata":"{}"},{"issue_id":"instructor-php-7cr","depends_on_id":"instructor-php-bn3","type":"blocks","created_at":"2025-11-28T12:26:43.252260006+01:00","created_by":"daemon","metadata":"{}"},{"issue_id":"instructor-php-7cr","depends_on_id":"instructor-php-xsh","type":"blocks","created_at":"2025-11-28T12:26:45.717213567+01:00","created_by":"daemon","metadata":"{}"}]}
 {"id":"instructor-php-7o7","title":"Phase 1: Move general CLI infrastructure from ClaudeCodeCli to Sandbox","description":"Move CommandSpec, Argv, and SandboxDriver enum from ClaudeCodeCli to Sandbox package as they are general CLI infrastructure. Update all references and maintain backward compatibility.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-02T11:21:36.67206592+01:00","updated_at":"2026-02-21T21:02:11.114667+01:00","closed_at":"2026-02-21T21:02:11.114667+01:00","close_reason":"Moved general CLI infrastructure types to Sandbox namespace (Argv, CommandSpec, SandboxDriver), updated references across agent-ctrl/auxiliary/laravel, and kept existing agent-ctrl classes for backward compatibility.","dependencies":[{"issue_id":"instructor-php-7o7","depends_on_id":"instructor-php-2i3","type":"discovered-from","created_at":"2025-12-02T11:21:45.575737158+01:00","created_by":"daemon","metadata":"{}"}]}
 {"id":"instructor-php-7uq","title":"PEER REVIEW: Latest ClaudeCodeCli work assessment","description":"CRITICAL ASSESSMENT: Team addressed most feedback but has significant quality issues. POSITIVES: Fixed type bug, added comprehensive CLI support, good test coverage, functional implementation. NEGATIVES: Tests in wrong location (P0), poor error handling, missing integration tests, architectural debt forming. Grade: C+ - Works but needs quality improvements before production.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-02T03:43:37.534397+01:00","updated_at":"2025-12-02T03:46:38.390343357+01:00","closed_at":"2025-12-02T03:46:38.390346704+01:00"}
@@ -228,7 +228,7 @@
 {"id":"instructor-php-d8h","title":"Test existing OpenAICompatibleDriver with Bedrock endpoint","description":"Validate if existing OpenAI driver can work with Bedrock's OpenAI-compatible API endpoint by testing with a Bedrock API key","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-28T22:58:11.115198496+01:00","updated_at":"2025-11-28T23:23:16.098211143+01:00","closed_at":"2025-11-28T23:23:16.098211143+01:00","dependencies":[{"issue_id":"instructor-php-d8h","depends_on_id":"instructor-php-lh5","type":"parent-child","created_at":"2025-11-28T22:58:33.357210227+01:00","created_by":"daemon","metadata":"{}"}]}
 {"id":"instructor-php-dbyp","title":"Add integration test for full hook flow through AgentBuilder","description":"End-to-end test:\n- Create agent via AgentBuilder with hooks registered\n- Register onBeforeToolUse that logs and modifies\n- Register onAfterToolUse that logs result\n- Register onBeforeStep and onAfterStep\n- Execute agent with tool calls\n- Verify hooks execute in correct order\n- Verify modifications propagate correctly\n\nExample from hooks-middleware-plan.md:364-406","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-23T08:28:48.018426+01:00","created_by":"ddebowczyk","updated_at":"2026-01-23T08:38:49.690804+01:00","closed_at":"2026-01-23T08:38:49.690804+01:00","close_reason":"Integration verified via existing Agent test suite - all 178 tests pass"}
 {"id":"instructor-php-det","title":"Test issue: Verify bd/bv setup","description":"This is a test issue to verify that bd/bv is properly set up for instructor-php project","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-28T11:50:02.993015494+01:00","updated_at":"2025-11-28T11:54:37.916089393+01:00","closed_at":"2025-11-28T11:54:37.916089393+01:00"}
-{"id":"instructor-php-dfg","title":"Validation in ClaudeCommandBuilder needs improvement","description":"Current validation only checks basic conflicts but misses: 1) File path existence for systemPromptFile, 2) JSON syntax validation for agentsJson, 3) Directory existence for additionalDirs, 4) Model name format validation, 5) sessionId format validation. Should fail fast with clear error messages.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-02T03:43:30.778259416+01:00","updated_at":"2025-12-02T03:43:30.778259416+01:00"}
+{"id":"instructor-php-dfg","title":"Validation in ClaudeCommandBuilder needs improvement","description":"Current validation only checks basic conflicts but misses: 1) File path existence for systemPromptFile, 2) JSON syntax validation for agentsJson, 3) Directory existence for additionalDirs, 4) Model name format validation, 5) sessionId format validation. Should fail fast with clear error messages.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-02T03:43:30.778259416+01:00","updated_at":"2026-02-21T21:32:25.067071+01:00","closed_at":"2026-02-21T21:32:25.067071+01:00","close_reason":"Expanded ClaudeCommandBuilder validation for system prompt files, agents JSON, additional dirs, model/session ID formats, and added failure-path test coverage."}
 {"id":"instructor-php-h0d","title":"ID Domain Model Completion: Owned vs External Identifiers","description":"Complete the typed-ID migration by explicitly separating IDs we own (generated/validated by us) from IDs owned by external providers/systems. This avoids overusing raw strings while not forcing UUID semantics on externally-issued identifiers.","acceptance_criteria":"- Clear distinction is enforced in code and docs between owned IDs and external IDs.\\n- Owned IDs use Uuid-backed thin value objects where appropriate.\\n- External IDs use opaque typed wrappers (non-UUID), never raw strings in domain internals.\\n- Boundary-only string normalization is consistent across stores/events/HTTP DTOs.\\n- Migration plan is executed package-by-package with tests green.","status":"closed","priority":2,"issue_type":"epic","owner":"ddebowczyk@guidewire.com","created_at":"2026-02-21T19:39:20.333174+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T20:50:02.974949+01:00","closed_at":"2026-02-21T20:50:02.974949+01:00","close_reason":"Completed owned vs external ID migration plan across agents/polyglot/messages/instructor/agent-ctrl with boundary policy, tests, and follow-up sweep."}
 {"id":"instructor-php-h0d.1","title":"Define ID taxonomy and coding standard (OwnedId vs ExternalId vs ReferenceKey)","description":"Create a compact architecture decision record and coding standard for IDs. Explicitly classify IDs into: (1) Owned IDs (aggregate/entity IDs we generate), (2) External IDs (provider-issued opaque identifiers), and (3) Reference keys/labels (human/system keys not treated as domain IDs).","acceptance_criteria":"- ADR/docs updated with decision matrix and examples from agents/polyglot/messages/agent-ctrl.\\n- Rule states when to use Uuid-backed value objects and when not to.\\n- Rule states external IDs must be typed wrappers without UUID validation/generation.\\n- Rule states reference keys remain strings where value objects add no domain value.\\n- Lintable checklist added to PR/review guidance.","status":"closed","priority":1,"issue_type":"task","owner":"ddebowczyk@guidewire.com","created_at":"2026-02-21T19:39:43.475069+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T19:56:04.975045+01:00","closed_at":"2026-02-21T19:56:04.975045+01:00","close_reason":"Added ID taxonomy and coding standard docs (owned UUID IDs, external opaque IDs, reference keys) with migration checklist and contributor guide link","labels":["status:in_progress"],"dependencies":[{"issue_id":"instructor-php-h0d.1","depends_on_id":"instructor-php-h0d","type":"parent-child","created_at":"2026-02-21T19:39:43.475706+01:00","created_by":"Dariusz Debowczyk"}]}
 {"id":"instructor-php-h0d.1.1","title":"State change: status → in_progress","description":"Set status to in_progress\n\nReason: Starting ID taxonomy and coding standard task","status":"closed","priority":4,"issue_type":"event","created_at":"2026-02-21T19:53:06.1688+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T21:00:31.464065+01:00","closed_at":"2026-02-21T21:00:31.464065+01:00","close_reason":"Superseded by completion and closure of the full h0d migration epic.","dependencies":[{"issue_id":"instructor-php-h0d.1.1","depends_on_id":"instructor-php-h0d.1","type":"parent-child","created_at":"2026-02-21T19:53:06.169403+01:00","created_by":"Dariusz Debowczyk"}]}

packages/agent-ctrl/src/Bridge/ClaudeCodeBridge.php

@@ -236,19 +236,19 @@ public function executeStreaming(string $prompt, ?StreamHandler $handler): Agent
 
     private function buildRequest(string $prompt): ClaudeRequest
     {
-        return new ClaudeRequest(
-            prompt: $prompt,
-            outputFormat: OutputFormat::StreamJson,
-            permissionMode: $this->permissionMode,
-            maxTurns: $this->maxTurns,
-            model: $this->model,
-            systemPrompt: $this->systemPrompt,
-            appendSystemPrompt: $this->appendSystemPrompt,
-            additionalDirs: $this->additionalDirs,
-            includePartialMessages: $this->includePartialMessages,
-            verbose: $this->verbose,
-            resumeSessionId: $this->resumeSessionId,
-            continueMostRecent: $this->continueMostRecent,
-        );
+        return ClaudeRequest::builder()
+            ->withPrompt($prompt)
+            ->withOutputFormat(OutputFormat::StreamJson)
+            ->withPermissionMode($this->permissionMode)
+            ->withMaxTurns($this->maxTurns)
+            ->withModel($this->model)
+            ->withSystemPrompt($this->systemPrompt)
+            ->withAppendSystemPrompt($this->appendSystemPrompt)
+            ->withAdditionalDirs($this->additionalDirs)
+            ->withIncludePartialMessages($this->includePartialMessages)
+            ->withVerbose($this->verbose)
+            ->withResumeSessionId($this->resumeSessionId)
+            ->withContinueMostRecent($this->continueMostRecent)
+            ->build();
     }
 }

packages/agent-ctrl/src/ClaudeCode/Application/Builder/ClaudeCommandBuilder.php

@@ -173,9 +173,14 @@ private function validate(ClaudeRequest $request) : void {
         if ($request->systemPrompt() !== null && $request->systemPromptFile() !== null) {
             throw new \InvalidArgumentException('systemPrompt and systemPromptFile cannot be used together');
         }
+        $this->validateSystemPromptFile($request->systemPromptFile());
         if ($request->continueMostRecent() && $request->resumeSessionId() !== null) {
             throw new \InvalidArgumentException('Cannot set both continueMostRecent and resumeSessionId');
         }
+        $this->validateSessionId($request->resumeSessionId());
+        $this->validateModel($request->model());
+        $this->validateAgentsJson($request->agentsJson());
+        $this->validateAdditionalDirs($request->additionalDirs()->toArray());
         if ($request->includePartialMessages() && $request->outputFormat() !== OutputFormat::StreamJson) {
             throw new \InvalidArgumentException('--include-partial-messages requires output format stream-json');
         }
@@ -184,6 +189,54 @@ private function validate(ClaudeRequest $request) : void {
         }
     }
 
+    private function validateSystemPromptFile(?string $path) : void {
+        if ($path === null || trim($path) === '') {
+            return;
+        }
+        if (!is_file($path)) {
+            throw new \InvalidArgumentException("systemPromptFile does not exist or is not a file: {$path}");
+        }
+    }
+
+    private function validateAgentsJson(?string $agentsJson) : void {
+        if ($agentsJson === null || trim($agentsJson) === '') {
+            return;
+        }
+        json_decode($agentsJson, true);
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            throw new \InvalidArgumentException('agentsJson must be valid JSON');
+        }
+    }
+
+    private function validateAdditionalDirs(array $dirs) : void {
+        foreach ($dirs as $dir) {
+            if (is_dir($dir)) {
+                continue;
+            }
+            throw new \InvalidArgumentException("additionalDirs entry is not an existing directory: {$dir}");
+        }
+    }
+
+    private function validateModel(?string $model) : void {
+        if ($model === null || trim($model) === '') {
+            return;
+        }
+        if (preg_match('/^[A-Za-z0-9._:\\/-]+$/', $model) === 1) {
+            return;
+        }
+        throw new \InvalidArgumentException("model contains unsupported characters: {$model}");
+    }
+
+    private function validateSessionId(?string $sessionId) : void {
+        if ($sessionId === null || trim($sessionId) === '') {
+            return;
+        }
+        if (preg_match('/^[A-Za-z0-9._:\\/-]+$/', $sessionId) === 1) {
+            return;
+        }
+        throw new \InvalidArgumentException("resumeSessionId contains unsupported characters: {$sessionId}");
+    }
+
     /**
      * @param list<string> $command
      */