feat: add subagent hierarchy runtime visibility and UX

AGENTS.md

@@ -47,3 +47,8 @@ This repository is an npm workspace monorepo:
 - Prefer existing tokens/components from the submodule before building custom UI in `apps/web`.
 - If a needed component does not exist in `design-system/`, pause and consult the user before adding a new component or introducing a non-design-system alternative.
 - In a brand new git worktree, initialize submodules before development (`git submodule update --init --recursive`), or the design-system assets will be missing.
+
+## Subagent Graph Rules
+- Subagent links are tool-delegation edges and do not represent execution flow edges.
+- Subagent hierarchies must remain acyclic (for example, `A -> B -> A` is invalid).
+- Subagent targets are tool-only nodes and cannot participate in regular execution edges.

CLAUDE.md

@@ -44,6 +44,8 @@ npm run build:packages       # Build only shared packages (types + engine)
 
 **Agent backend:** Server agent execution is implemented through OpenAI Agents SDK (`apps/server/src/services/openai-agents-llm.ts`). Agent runs are capped with `maxTurns: 20` to bound loop iterations.
 
+**Subagent hierarchy:** Agent nodes may expose other agent nodes as tools through subagent links. These links are not execution-flow edges. The subagent graph must be acyclic, and subagent targets are tool-only (no regular execution edges).
+
 **Build dependency chain:** `packages/types` → `packages/workflow-engine` → `apps/server` / `apps/web`. Always run `build:packages` before typechecking or building apps.
 
 ## Design System (Git Submodule)

README.md

@@ -23,6 +23,7 @@ data/
 - **Visual Editor** – Canvas, floating palette, zoom controls, and inline node forms for prompts, branching rules, and approval copy.
 - **Run Console** – Chat-style panel that renders agent responses progressively as they arrive via SSE, with per-agent labels, spinner states, and approval requests.
 - **Workflow Engine** – Handles graph traversal, approvals, and LLM invocation (OpenAI Agents SDK).
+- **Subagent Tools** – Agent nodes can expose connected agent nodes as nested subagent tools; these links are tool-delegation edges, not workflow execution edges.
 - **Persistent Audit Trail** – Every run writes `data/runs/run_<timestamp>.json` containing the workflow graph plus raw execution logs, independent of what the UI chooses to display.
 
 ## Getting Started
@@ -65,6 +66,7 @@ Workflow run preflight rules and blocking conditions are documented in `apps/web
 ## Architecture Notes
 
 - **`@agentic/workflow-engine`**: Pure TypeScript package that normalizes graphs, manages state, pauses for approvals, and calls an injected `WorkflowLLM`. It now exposes `getGraph()` so callers can persist what actually ran.
+- **Subagent hierarchy**: Subagent connectors form an acyclic parent/child graph among Agent nodes (`A -> B -> C` allowed, `A -> B -> A` blocked). Subagent targets are tool-only and excluded from execution-flow traversal.
 - **Server (`apps/server`)**: Five Express routes. `/api/run-stream` is the primary execution path — streams each `WorkflowLogEntry` as an SSE event so the UI renders progressively. `/api/run` is the same execution as a single JSON response. `/api/resume` continues paused approval workflows. `/api/config` serves `.config/config.json` (provider/model definitions). `/api/default-workflow` serves `.config/default-workflow.json` if present.
 - **Web (`apps/web`)**: Vite SPA using the CodeSignal design system. Core UI logic lives in `src/app/workflow-editor.ts`; shared helpers (help modal, API client, etc.) live under `src/`.
 - **Shared contracts**: `packages/types` keeps node shapes, graph schemas, log formats, and run-record definitions in sync across the stack.