feat: Add agent-acp step type with ACP protocol support

- Implement agent-acp step type for spawning external ACP agent subprocesses via Agent Communication Protocol
- Add ACPExecutor with validation, field rendering, and subprocess lifecycle management
- Integrate agent-acp field rendering in StepDispatcher (batch and sequential modes)
- Add run_agent() utility function for workflows to execute ACP agents from steps and JS context
- Add osmedeus agent CLI command for interactive agent execution with --agent, --cwd, --timeout, --stdin, and --list flags
- Add /osm/api/agent/chat/completions REST endpoint with OpenAI-compatible chat format and concurrency control
- Support agent selection via: built-in names (claude-code, codex, opencode, gemini) or custom acp_config.command
- Add step-level configuration: cwd, allowed_paths, acp_config (command, args, env, write_enabled)
- Add comprehensive E2E tests for agent-acp workflows (basic, minimal, config, codex variants)
- Add test workflows in test/testdata/workflows/agent-and-llm/
- Update AGENTS.md documentation with agent-acp examples, CLI usage, and API endpoints

Author: j3ssie

CLAUDE.md

@@ -63,7 +63,7 @@ CLI/API (pkg/cli, pkg/server)
          ↓
 Executor (internal/executor) - coordinates workflow execution
          ↓
-StepDispatcher - routes to: BashExecutor, FunctionExecutor, ForeachExecutor, ParallelExecutor, RemoteBashExecutor, HTTPExecutor, LLMExecutor, AgentExecutor
+StepDispatcher - routes to: BashExecutor, FunctionExecutor, ForeachExecutor, ParallelExecutor, RemoteBashExecutor, HTTPExecutor, LLMExecutor, AgentExecutor, ACPExecutor
          ↓
 Runner (internal/runner) - executes commands via: HostRunner, DockerRunner, SSHRunner
 ```
@@ -92,7 +92,7 @@ Runner (internal/runner) - executes commands via: HostRunner, DockerRunner, SSHR
 
 ```go
 WorkflowKind: "module" | "flow"  // module = single unit, flow = orchestrates modules
-StepType: "bash" | "function" | "parallel-steps" | "foreach" | "remote-bash" | "http" | "llm" | "agent"
+StepType: "bash" | "function" | "parallel-steps" | "foreach" | "remote-bash" | "http" | "llm" | "agent" | "agent-acp"
 RunnerType: "host" | "docker" | "ssh"
 TriggerType: "cron" | "event" | "watch" | "manual"
 ```
@@ -174,6 +174,61 @@ steps:
       findings: "{{agent_content}}"
 ```
 
+### Agent-ACP Step Type
+
+The `agent-acp` step type spawns an external AI coding agent as a subprocess and communicates via the Agent Communication Protocol (ACP). Unlike the `agent` step type (which uses the internal LLM loop), `agent-acp` delegates to real agent binaries.
+
+Built-in agents (defined in `internal/executor/acp_executor.go`):
+- `claude-code` — `npx -y @zed-industries/claude-code-acp@latest`
+- `codex` — `npx -y @zed-industries/codex-acp`
+- `opencode` — `opencode acp`
+- `gemini` — `gemini --experimental-acp`
+
+Key YAML fields:
+- `agent` - Built-in agent name (required unless `acp_config.command` is set)
+- `messages` - Conversation messages (role + content) used as the prompt
+- `cwd` - Working directory for the ACP session
+- `allowed_paths` - Restrict file reads to these directories
+- `acp_config.command` - Custom agent command (overrides built-in registry)
+- `acp_config.args` - Custom agent command arguments
+- `acp_config.env` - Environment variables for the agent process
+- `acp_config.write_enabled` - Allow file writes (default: false)
+
+Available exports: `acp_output`, `acp_stderr`, `acp_agent`
+
+```yaml
+steps:
+  - name: acp-agent
+    type: agent-acp
+    agent: claude-code
+    cwd: "{{Output}}"
+    allowed_paths:
+      - "{{Output}}"
+    acp_config:
+      env:
+        CUSTOM_VAR: "hello"
+      write_enabled: true
+    messages:
+      - role: system
+        content: "You are a security analyst."
+      - role: user
+        content: "Analyze the scan results in {{Output}} and create a summary."
+    exports:
+      analysis: "{{acp_output}}"
+```
+
+### Agent CLI Command
+
+Run an ACP agent interactively from the terminal:
+```bash
+osmedeus agent "your message here"              # Run with claude-code (default)
+osmedeus agent --agent codex "your message"     # Use a specific agent
+osmedeus agent --list                            # List available agents
+osmedeus agent --cwd /path/to/project "msg"     # Set working directory
+osmedeus agent --timeout 1h "msg"               # Custom timeout (default: 30m)
+echo "message" | osmedeus agent --stdin          # Read from stdin
+```
+
 ## CLI Commands
 
 ```bash
@@ -230,6 +285,12 @@ osmedeus assets --stats -w <workspace>           # Stats filtered by workspace
 osmedeus assets --columns url,title,status_code  # Custom columns
 osmedeus assets --limit 100 --offset 50          # Pagination
 osmedeus assets --json                           # JSON output
+osmedeus agent "your prompt"                     # Run ACP agent (default: claude-code)
+osmedeus agent --agent codex "your prompt"       # Use a specific agent
+osmedeus agent --list                            # List available agents
+osmedeus agent --cwd /path/to/project "prompt"   # Set working directory
+osmedeus agent --timeout 1h "prompt"             # Custom timeout (default: 30m)
+echo "prompt" | osmedeus agent --stdin           # Read from stdin
 ```
 
 ### Event Trigger Input Syntax
@@ -268,6 +329,7 @@ REST API documentation with curl examples is in `docs/api/`. Key endpoint catego
 - **Functions**: Execute utility functions via API
 - **Snapshots**: Export/import workspace archives
 - **LLM**: OpenAI-compatible chat completions and embeddings
+- **Agent ACP**: OpenAI-compatible endpoint that spawns local ACP agent subprocesses (`POST /osm/api/agent/chat/completions`)
 - **Install**: Binary registry and installation management
 
 ## Cloud Documentation

HACKING.md

@@ -9,6 +9,7 @@ This document describes the technical architecture and development practices for
 - [Core Components](#core-components)
 - [Workflow Engine](#workflow-engine)
 - [Agent Step Type](#agent-step-type)
+- [Agent-ACP Step Type](#agent-acp-step-type)
 - [Execution Pipeline](#execution-pipeline)
 - [Runner System](#runner-system)
 - [Authentication Middleware](#authentication-middleware)
@@ -138,7 +139,7 @@ type Workflow struct {
 
 type Step struct {
     Name             string
-    Type             StepType      // bash, function, foreach, parallel-steps, remote-bash, http, llm, agent
+    Type             StepType      // bash, function, foreach, parallel-steps, remote-bash, http, llm, agent, agent-acp
     PreCondition     string        // Skip condition
     Command          string        // For bash/remote-bash
     Commands         []string      // Multiple commands
@@ -167,6 +168,12 @@ type Step struct {
     OnToolStart       string             // JS hook before each tool call
     OnToolEnd         string             // JS hook after each tool call
 
+    // Agent-ACP step fields
+    Agent            string             // Built-in ACP agent name (claude-code, codex, etc.)
+    Cwd              string             // Working directory for ACP session
+    AllowedPaths     []string           // Restrict file access to these directories
+    ACPConfig        *ACPStepConfig     // Custom agent command, env, write permissions
+
     Exports          map[string]string
     OnSuccess        []Action
     OnError          []Action
@@ -400,6 +407,115 @@ Hook expressions receive these variables:
 - `iteration` - Current agent iteration number
 - `error` - Error string (empty if no error)
 
+## Agent-ACP Step Type
+
+The `agent-acp` step type spawns an external AI coding agent as a subprocess and communicates via the Agent Communication Protocol (ACP). Unlike the `agent` step type (which uses the internal LLM loop), `agent-acp` delegates to real agent binaries.
+
+### Built-in Agents
+
+| Agent Name | Command | Args |
+|------------|---------|------|
+| `claude-code` | `npx` | `-y @zed-industries/claude-code-acp@latest` |
+| `codex` | `npx` | `-y @zed-industries/codex-acp` |
+| `opencode` | `opencode` | `acp` |
+| `gemini` | `gemini` | `--experimental-acp` |
+
+Defined in `builtinACPAgents` map in `internal/executor/acp_executor.go`.
+
+### Architecture
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  ACPExecutor.Execute()                                         │
+│    1. Resolve agent name → command + args                      │
+│    2. Build prompt from step.Messages                          │
+│    3. Call RunAgentACP() standalone function                   │
+│       a. Spawn subprocess with stdin/stdout pipes              │
+│       b. Create ACP client (acpClient) for callbacks           │
+│       c. ACP Initialize → NewSession → Prompt                 │
+│       d. Collect agent output via SessionUpdate callbacks      │
+│    4. Return output as StepResult with exports                 │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### YAML Structure
+
+```yaml
+steps:
+  - name: acp-agent
+    type: agent-acp
+    agent: claude-code          # Built-in agent name
+    cwd: "{{Output}}"          # Working directory
+    allowed_paths:
+      - "{{Output}}"
+    acp_config:
+      env:
+        CUSTOM_VAR: "value"
+      write_enabled: true       # Allow file writes (default: false)
+    messages:
+      - role: system
+        content: "You are a security analyst."
+      - role: user
+        content: "Analyze the scan results."
+    exports:
+      analysis: "{{acp_output}}"
+```
+
+### ACP Client Callbacks
+
+The `acpClient` (`internal/executor/acp_client.go`) implements the `acp.Client` interface:
+
+| Method | Behavior |
+|--------|----------|
+| `SessionUpdate` | Accumulates agent text output, logs tool calls and thoughts |
+| `RequestPermission` | Auto-approves by selecting `allow_once` → `allow_always` → first option |
+| `ReadTextFile` | Reads files scoped to `allowedPaths` |
+| `WriteTextFile` | Writes files if `writeEnabled` is true |
+| `CreateTerminal` / `KillTerminalCommand` / etc. | No-op stubs |
+
+### Available Exports
+
+| Export | Description |
+|--------|-------------|
+| `acp_output` | Collected agent text output |
+| `acp_stderr` | Agent process stderr |
+| `acp_agent` | Agent name used |
+
+### Standalone Function
+
+`RunAgentACP(ctx, prompt, agentName, cfg)` can be called independently from workflow execution (used by the CLI `agent` command and the API endpoint):
+
+```go
+output, stderr, err := executor.RunAgentACP(ctx, "your prompt", "claude-code", &executor.RunAgentACPConfig{
+    Cwd:          "/workspace",
+    AllowedPaths: []string{"/workspace"},
+    WriteEnabled: false,
+})
+```
+
+### Agent CLI Command
+
+```bash
+osmedeus agent "your message"                    # Default agent (claude-code)
+osmedeus agent --agent codex "your message"     # Specific agent
+osmedeus agent --list                            # List available agents
+osmedeus agent --cwd /path "message"            # Set working directory
+osmedeus agent --timeout 1h "message"           # Custom timeout
+echo "message" | osmedeus agent --stdin          # Read from stdin
+```
+
+### API Endpoint
+
+`POST /osm/api/agent/chat/completions` provides an OpenAI-compatible interface:
+
+```bash
+curl -X POST http://localhost:8000/osm/api/agent/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"claude-code","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+The `model` field maps to a built-in agent name. Only one ACP agent can run at a time (returns `409 Conflict` if busy).
+
 ### Execution Context
 
 
@@ -479,6 +595,9 @@ Lookup order:
              ┌──────────────┐            ┌──────────────┐            ┌──────────────┐
              │ HTTPExecutor │            │ LLMExecutor  │            │AgentExecutor │
              └──────────────┘            └──────────────┘            └──────────────┘
+             ┌──────────────┐
+             │ ACPExecutor  │
+             └──────────────┘
                     │                            │                            │
                     └────────────────────────────┼────────────────────────────┘
                                                  ▼
@@ -551,6 +670,7 @@ Built-in executors registered at startup:
 - `HTTPExecutor` - handles `http` steps
 - `LLMExecutor` - handles `llm` steps
 - `AgentExecutor` - handles `agent` steps (agentic LLM loop with tool calling)
+- `ACPExecutor` - handles `agent-acp` steps (ACP subprocess agents)
 
 ## Run Control Plane
 
@@ -1674,6 +1794,7 @@ test/e2e/                                # E2E CLI tests
 ├── ssh_test.go                          # SSH runner e2e tests (module & step level)
 ├── api_test.go                          # API endpoint e2e tests (all routes)
 ├── agent_test.go                        # Agent step e2e tests
+├── agent_acp_test.go                    # Agent-ACP step e2e tests
 ├── canary_test.go                       # Canary tests (real-world scans in Docker)
 ├── cloud_test.go                        # Cloud CLI e2e tests
 ├── db_clean_test.go                     # Database cleanup e2e tests

README.md

@@ -26,7 +26,7 @@ Built for both beginners and experts, it delivers powerful, composable automatio
 - **Distributed Execution** - Redis-based master-worker pattern with queue system, webhook triggers, and file sync across workers
 - **Rich Function Library** - 80+ utility functions including nmap integration, tmux sessions, SSH execution, TypeScript/Python scripting, SARIF parsing, and CDN/WAF classification
 - **Event-Driven Scheduling** - Cron, file-watch, and event triggers with filtering, deduplication, and delayed task queues
-- **Agentic LLM Steps** - Tool-calling agent loops with sub-agent orchestration, memory management, and structured output
+- **Agentic LLM Steps** - Tool-calling agent loops with sub-agent orchestration, memory management, and structured output; plus ACP subprocess agents (Claude Code, Codex, OpenCode, Gemini)
 - **Cloud Infrastructure** - Provision and run scans across DigitalOcean, AWS, GCP, Linode, and Azure with cost controls and automatic cleanup
 - **Rich CLI Interface** - Interactive database queries, bulk function evaluation, workflow linting, progress bars, and comprehensive usage examples
 - **REST API & Web UI** - Full API server with webhook triggers, database queries, and embedded dashboard for visualization
@@ -99,6 +99,11 @@ osmedeus worker queue run --concurrency 5              # Process queue
 osmedeus worker status                          # Show workers
 osmedeus worker eval -e 'ssh_exec("host", "whoami")'  # Eval with distributed hooks
 
+# Run an ACP agent interactively
+osmedeus agent "analyze this codebase"
+osmedeus agent --agent codex "explain main.go"
+osmedeus agent --list
+
 # Show all usage examples
 osmedeus --usage-example
 ```
@@ -133,7 +138,7 @@ For more CLI usage and example commands, refer to the [CLI Reference](https://do
 │  │ CONFIG ──▶ PARSER ──▶ EXECUTOR ──▶ STEP DISPATCHER ──▶ RUNNER       │  │
 │  │                          │                                          │  │
 │  │  Step Executors: bash | function | parallel | foreach | remote-bash │  │
-│  │                  http | llm | agent | SARIF/SAST integration        │  │
+│  │                  http | llm | agent | agent-acp | SARIF/SAST       │  │
 │  │  Hooks: pre_scan_steps → [main steps] → post_scan_steps             │  │
 │  │                          │                                          │  │
 │  │  Runners: HostRunner | DockerRunner | SSHRunner                     │  │

cmd/osmedeus/main.go

@@ -12,7 +12,7 @@ var (
 )
 
 // @title Osmedeus API
-// @version 5.0.0
+// @version 5.0.1
 // @description Workflow Engine for Offensive Security - REST API for managing security automation workflows, scans, and distributed task execution.
 // @termsOfService https://docs.osmedeus.org/terms/
 

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/glamour v0.10.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
+	github.com/coder/acp-go-sdk v0.6.3
 	github.com/creativeprojects/go-selfupdate v1.5.2
 	github.com/dgraph-io/ristretto v0.2.0
 	github.com/digitalocean/godo v1.175.0
@@ -19,7 +20,7 @@ require (
 	github.com/go-telegram-bot-api/telegram-bot-api/v5 v5.5.1
 	github.com/goccy/go-yaml v1.19.1
 	github.com/gofiber/adaptor/v2 v2.2.1
-	github.com/gofiber/fiber/v2 v2.52.10
+	github.com/gofiber/fiber/v2 v2.52.12
 	github.com/gofiber/swagger v1.1.1
 	github.com/golang-jwt/jwt/v5 v5.3.0
 	github.com/google/uuid v1.6.0

go.sum

@@ -97,6 +97,8 @@ github.com/clipperhouse/uax29/v2 v2.3.0 h1:SNdx9DVUqMoBuBoW3iLOj4FQv3dN5mDtuqwuh
 github.com/clipperhouse/uax29/v2 v2.3.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
 github.com/cloudflare/circl v1.6.1 h1:zqIqSPIndyBh1bjLVVDHMPpVKqp8Su/V+6MeDzzQBQ0=
 github.com/cloudflare/circl v1.6.1/go.mod h1:uddAzsPgqdMAYatqJ0lsjX1oECcQLIlRpzZh3pJrofs=
+github.com/coder/acp-go-sdk v0.6.3 h1:LsXQytehdjKIYJnoVWON/nf7mqbiarnyuyE3rrjBsXQ=
+github.com/coder/acp-go-sdk v0.6.3/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/creativeprojects/go-selfupdate v1.5.2 h1:3KR3JLrq70oplb9yZzbmJ89qRP78D1AN/9u+l3k0LJ4=
@@ -174,8 +176,8 @@ github.com/goccy/go-yaml v1.19.1 h1:3rG3+v8pkhRqoQ/88NYNMHYVGYztCOCIZ7UQhu7H+NE=
 github.com/goccy/go-yaml v1.19.1/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
 github.com/gofiber/adaptor/v2 v2.2.1 h1:givE7iViQWlsTR4Jh7tB4iXzrlKBgiraB/yTdHs9Lv4=
 github.com/gofiber/adaptor/v2 v2.2.1/go.mod h1:AhR16dEqs25W2FY/l8gSj1b51Azg5dtPDmm+pruNOrc=
-github.com/gofiber/fiber/v2 v2.52.10 h1:jRHROi2BuNti6NYXmZ6gbNSfT3zj/8c0xy94GOU5elY=
-github.com/gofiber/fiber/v2 v2.52.10/go.mod h1:YEcBbO/FB+5M1IZNBP9FO3J9281zgPAreiI1oqg8nDw=
+github.com/gofiber/fiber/v2 v2.52.12 h1:0LdToKclcPOj8PktUdIKo9BUohjjwfnQl42Dhw8/WUw=
+github.com/gofiber/fiber/v2 v2.52.12/go.mod h1:YEcBbO/FB+5M1IZNBP9FO3J9281zgPAreiI1oqg8nDw=
 github.com/gofiber/swagger v1.1.1 h1:FZVhVQQ9s1ZKLHL/O0loLh49bYB5l1HEAgxDlcTtkRA=
 github.com/gofiber/swagger v1.1.1/go.mod h1:vtvY/sQAMc/lGTUCg0lqmBL7Ht9O7uzChpbvJeJQINw=
 github.com/gogo/protobuf v1.3.1/go.mod h1:SlYgWuQ5SjCEi6WLHjHCa1yvBfUnHcTbrrZtXPKa29o=

internal/core/constants.go

@@ -3,7 +3,7 @@ package core
 // Project metadata constants
 const (
 	// VERSION of this project
-	VERSION = "v5.0.0"
+	VERSION = "v5.0.1"
 	// DESC description of the tool
 	DESC = "A Modern Orchestration Engine for Security"
 	// BINARY name of osmedeus