fix: render agent deliverables before the success commit so resume preserves them (#376)

docs: distinguish Keygraph (company) from the Keygraph platform (product) across README, docs, and llms files

.claude/commands/debug.md

@@ -135,7 +135,6 @@ shannon <URL> <REPO> --pipeline-testing
 |-------------------|---------|------------|
 | `config` | Configuration file issues | No |
 | `network` | Connection/timeout issues | Yes |
-| `tool` | External tool (nmap, etc.) failed | Yes |
 | `prompt` | Claude SDK/API issues | Sometimes |
 | `filesystem` | File read/write errors | Sometimes |
 | `validation` | Deliverable validation failed | Yes (via retry) |

.dockerignore

@@ -1,5 +1,5 @@
 # Node.js
-node_modules/
+**/node_modules/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
@@ -49,7 +49,7 @@ Thumbs.db
 # CLI package (runs on host, not in container)
 # Keep apps/cli/package.json so pnpm workspaces resolve
 apps/cli/src/
-apps/cli/dist/
+**/dist/
 apps/cli/infra/
 apps/cli/tsconfig.json
 apps/cli/tsdown.config.ts

.env.example

@@ -4,8 +4,14 @@
 # Recommended output token configuration for larger tool outputs
 CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
 
+# Adaptive thinking is enabled automatically on Opus 4.6/4.7/4.8. Set to false to disable.
+# CLAUDE_ADAPTIVE_THINKING=false
+
+# Shannon forwards your machine's /etc/hosts entries into the worker container. Set to false to disable.
+# SHANNON_FORWARD_HOSTS=false
+
 # =============================================================================
-# OPTION 1: Direct Anthropic (default, no router)
+# OPTION 1: Direct Anthropic
 # =============================================================================
 ANTHROPIC_API_KEY=your-api-key-here
 
@@ -19,20 +25,6 @@ ANTHROPIC_API_KEY=your-api-key-here
 # ANTHROPIC_BASE_URL=https://your-proxy.example.com
 # ANTHROPIC_AUTH_TOKEN=your-auth-token   # Auth token for the custom endpoint
 
-# =============================================================================
-# OPTION 3: Router Mode (use alternative providers)
-# =============================================================================
-# Enable router mode by running: ./shannon start ... ROUTER=true
-# Then configure ONE of the providers below:
-
-# --- OpenAI ---
-# OPENAI_API_KEY=sk-your-openai-key
-# ROUTER_DEFAULT=openai,gpt-5.2
-
-# --- OpenRouter (access Gemini 3 models via single API) ---
-# OPENROUTER_API_KEY=sk-or-your-openrouter-key
-# ROUTER_DEFAULT=openrouter,google/gemini-3-flash-preview
-
 # =============================================================================
 # Model Tier Overrides (Anthropic API / OAuth / Custom Base URL / Bedrock)
 # =============================================================================
@@ -40,24 +32,24 @@ ANTHROPIC_API_KEY=your-api-key-here
 # Optional for direct Anthropic and custom base URL modes. Required for Bedrock/Vertex.
 # ANTHROPIC_SMALL_MODEL=...     # Small tier  (default: claude-haiku-4-5-20251001)
 # ANTHROPIC_MEDIUM_MODEL=...    # Medium tier (default: claude-sonnet-4-6)
-# ANTHROPIC_LARGE_MODEL=...     # Large tier  (default: claude-opus-4-6)
+# ANTHROPIC_LARGE_MODEL=...     # Large tier  (default: claude-opus-4-8)
 
 # =============================================================================
-# OPTION 4: AWS Bedrock
+# OPTION 3: AWS Bedrock
 # =============================================================================
 # https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/
 # Requires the model tier overrides above to be set with Bedrock-specific model IDs.
 # Example Bedrock model IDs for us-east-1:
 #   ANTHROPIC_SMALL_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
 #   ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
-#   ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-6
+#   ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-8
 
 # CLAUDE_CODE_USE_BEDROCK=1
 # AWS_REGION=us-east-1
 # AWS_BEARER_TOKEN_BEDROCK=your-bearer-token
 
 # =============================================================================
-# OPTION 5: Google Vertex AI
+# OPTION 4: Google Vertex AI
 # =============================================================================
 # https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models
 # Requires a GCP service account with roles/aiplatform.user.
@@ -66,15 +58,9 @@ ANTHROPIC_API_KEY=your-api-key-here
 # Example Vertex AI model IDs:
 #   ANTHROPIC_SMALL_MODEL=claude-haiku-4-5@20251001
 #   ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6
-#   ANTHROPIC_LARGE_MODEL=claude-opus-4-6
+#   ANTHROPIC_LARGE_MODEL=claude-opus-4-8
 
 # CLAUDE_CODE_USE_VERTEX=1
 # CLOUD_ML_REGION=us-east5
 # ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
 # GOOGLE_APPLICATION_CREDENTIALS=./credentials/google-sa-key.json
-
-# =============================================================================
-# Available Models
-# =============================================================================
-# OpenAI:     gpt-5.2, gpt-5-mini
-# OpenRouter: google/gemini-3-flash-preview

.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -55,7 +55,7 @@ body:
       label: If applicable
       options:
         - label: I have included relevant error messages, stack traces, or failure details.
-        - label: I have checked the audit logs and pasted the relevant errors.
+        - label: I have checked the workspaces folder for logs and pasted the relevant errors.
         - label: I have inspected the failed Temporal workflow run and included the failure reason.
         - label: I have included clear steps to reproduce the issue.
         - label: I have redacted any sensitive information (tokens, URLs, repo names).
@@ -69,7 +69,9 @@ body:
 
         Issues without this information may be difficult to triage.
 
-        - Check the logs at: `./workspaces/target_url_shannon-123/workflow.log`
+        - Check the workflow log:
+            - **npx mode:** `~/.shannon/workspaces/<workspace>/workflow.log`
+            - **Local mode:** `./workspaces/<workspace>/workflow.log`
           Use `grep` or search to identify errors.
           Paste the relevant error output below.
         - Temporal:
@@ -83,13 +85,13 @@ body:
     id: debugging-details
     attributes:
       label: Debugging details
-      description: Paste any error messages, stack traces, or failure details from the audit logs or Temporal UI.
+      description: Paste any error messages, stack traces, or failure details from the workspace logs or Temporal UI.
 
   - type: textarea
     id: screenshots
     attributes:
       label: Screenshots
-      description: If applicable, add screenshots of the audit logs or Temporal failure details.
+      description: If applicable, add screenshots of the workspace logs or Temporal failure details.
 
   - type: markdown
     attributes:
@@ -99,35 +101,36 @@ body:
         Provide the following information (redact sensitive data such as repository names, URLs, and tokens):
 
   - type: dropdown
-    id: auth-method
+    id: cli-mode
     attributes:
-      label: Authentication method used
+      label: CLI mode
       options:
-        - CLAUDE_CODE_OAUTH_TOKEN
-        - ANTHROPIC_API_KEY
+        - "npx (@keygraph/shannon)"
+        - "Local (./shannon)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Provider
+      options:
+        - "Anthropic (API key)"
+        - "Anthropic (OAuth token)"
+        - "Custom base URL (proxy/gateway)"
+        - "AWS Bedrock"
+        - "Google Vertex AI"
     validations:
       required: true
 
   - type: input
     id: shannon-command
     attributes:
-      label: Full ./shannon command with all flags used (with redactions)
-
-  - type: dropdown
-    id: experimental-models
-    attributes:
-      label: Are you using any experimental models or providers other than default Anthropic models?
-      options:
-        - "No"
-        - "Yes"
+      label: Full command with all flags used (with redactions)
+      placeholder: "e.g. npx @keygraph/shannon start -u <url> -r my-repo  OR  ./shannon start -u <url> -r my-repo"
     validations:
       required: true
 
-  - type: input
-    id: experimental-model-details
-    attributes:
-      label: If Yes, which one (model/provider)?
-
   - type: input
     id: os-version
     attributes:
@@ -136,6 +139,14 @@ body:
     validations:
       required: true
 
+  - type: input
+    id: node-version
+    attributes:
+      label: "Node.js version ('node -v')"
+      placeholder: "e.g. 22.12.0"
+    validations:
+      required: true
+
   - type: input
     id: docker-version
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -20,6 +20,15 @@ body:
     validations:
       required: true
 
+  - type: dropdown
+    id: cli-mode
+    attributes:
+      label: Which CLI mode does this apply to?
+      options:
+        - Both
+        - "npx (@keygraph/shannon)"
+        - "Local (./shannon)"
+
   - type: textarea
     id: alternatives-considered
     attributes:

.github/workflows/release-beta.yml

@@ -30,15 +30,17 @@ jobs:
         run: |
           set -euo pipefail
 
+          BASE="2.0.0"
           LATEST=$(npm view "@keygraph/shannon" dist-tags.beta 2>/dev/null || echo "")
 
-          if [[ -z "$LATEST" ]]; then
-            echo "version=1.0.0-beta.1" >> "$GITHUB_OUTPUT"
-          else
-            # Extract N from 1.0.0-beta.N and increment
+          if [[ "$LATEST" == "$BASE-beta."* ]]; then
+            # Same base version — increment the beta counter (e.g. 2.0.0-beta.2 -> 2.0.0-beta.3)
             N=$(echo "$LATEST" | grep -oE 'beta\.([0-9]+)' | grep -oE '[0-9]+')
             NEXT=$((N + 1))
-            echo "version=1.0.0-beta.$NEXT" >> "$GITHUB_OUTPUT"
+            echo "version=$BASE-beta.$NEXT" >> "$GITHUB_OUTPUT"
+          else
+            # No prior beta, or a different base (e.g. last beta was 1.0.0-beta.N) — start over.
+            echo "version=$BASE-beta.1" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Print version

.github/workflows/rollback-beta.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Beta version to roll back to (example: 1.0.0-beta.2)"
+        description: "Beta version to roll back to (example: 2.0.0-beta.2)"
         required: true
         type: string
 
@@ -31,7 +31,7 @@ jobs:
           VERSION="${RAW_VERSION#v}"
 
           if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$ ]]; then
-            echo "Version must be in format X.Y.Z-beta.N (e.g. 1.0.0-beta.2)"
+            echo "Version must be in format X.Y.Z-beta.N (e.g. 2.0.0-beta.2)"
             exit 1
           fi
 

.npmrc

@@ -1,2 +1,4 @@
 auto-install-peers=true
 strict-peer-dependencies=false
+minimum-release-age=10080
+ignore-scripts=true

CLAUDE.md

@@ -4,7 +4,7 @@ AI-powered penetration testing agent for defensive security analysis. Automates
 
 ## Commands
 
-**Prerequisites:** Docker, AI provider credentials (`.env` for local, `shn setup` or env vars for npx)
+**Prerequisites:** Docker, AI provider credentials (`.env` for local, `npx @keygraph/shannon setup` or env vars for npx)
 
 ### Dual CLI
 
@@ -15,8 +15,8 @@ Shannon supports two CLI modes, auto-detected based on the current working direc
 | **Install** | Zero-install via npm | Clone the repo |
 | **Image** | Pulled from Docker Hub (`keygraph/shannon:latest`) | Built locally (`shannon-worker`) |
 | **State** | `~/.shannon/` | Project directory |
-| **Credentials** | `~/.shannon/config.toml` (via `shn setup`) or env vars | `./.env` |
-| **Config** | `~/.shannon/config.toml` (via `shn setup`) | N/A |
+| **Credentials** | `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`) or env vars | `./.env` |
+| **Config** | `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`) | N/A |
 | **Prompts** | Bundled in Docker image | Mounted from `./apps/worker/prompts/` (live-editable) |
 
 Mode auto-detection: local mode activates when env var `SHANNON_LOCAL=1` is set by the `./shannon` entry point (`apps/cli/src/mode.ts`). Otherwise npx mode.
@@ -82,7 +82,7 @@ pnpm biome:fix                       # Auto-fix lint, format, and import sorting
 
 **Monorepo tooling:** pnpm workspaces, Turborepo for task orchestration, Biome for linting/formatting. TypeScript compiler options shared via `tsconfig.base.json` at the root. All packages extend it, overriding only `rootDir` and `outDir`. Shared devDependencies (`typescript`, `@types/node`, `turbo`, `@biomejs/biome`) are hoisted to the root workspace.
 
-**Options:** `-c <file>` (YAML config), `-o <path>` (output directory), `-w <name>` (named workspace; auto-resumes if exists), `--pipeline-testing` (minimal prompts, 10s retries), `--router` (multi-model routing via [claude-code-router](https://github.com/musistudio/claude-code-router))
+**Options:** `-c <file>` (YAML config), `-o <path>` (output directory), `-w <name>` (named workspace; auto-resumes if exists), `--pipeline-testing` (minimal prompts, 10s retries), `--debug` (preserve worker container after exit for log inspection)
 
 ## Architecture
 
@@ -106,16 +106,17 @@ Published as `@keygraph/shannon` on npm. Contains only Docker orchestration logi
 - `apps/cli/src/commands/setup.ts` — Interactive TUI wizard (`@clack/prompts`) for provider credential setup (npx only)
 - `apps/cli/src/paths.ts` — Repo/config path resolution (bare name → `./repos/<name>`, or any absolute/relative path)
 - `apps/cli/src/commands/` — Command handlers
-- `apps/cli/infra/compose.yml` — Bundled Temporal + router compose file for npx mode
+- `apps/cli/infra/compose.yml` — Bundled Temporal compose file for npx mode
 - `apps/cli/tsdown.config.ts` — tsdown bundler config
 - `shannon` — Node.js entry point (`#!/usr/bin/env node`) that delegates to `apps/cli/dist/index.mjs`
 
 ### Docker Architecture
-Infra (Temporal + router) runs via `docker-compose.yml`. Workers are ephemeral `docker run --rm` containers, one per scan, each with a unique task queue and isolated volume mounts.
+Infra (Temporal) runs via `docker-compose.yml`. Workers are ephemeral `docker run --rm` containers, one per scan, each with a unique task queue and isolated volume mounts.
 
-- `docker-compose.yml` — Infra only: `shannon-temporal` (port 7233/8233) and `shannon-router` (port 3456, optional via profile). Network: `shannon-net`
+- `docker-compose.yml` — Infra only: `shannon-temporal` (port 7233/8233). Network: `shannon-net`
 - `Dockerfile` — 2-stage build (builder + Chainguard Wolfi runtime). Uses pnpm. Entrypoint: `CMD ["node", "apps/worker/dist/temporal/worker.js"]`
 - No `docker-compose.docker.yml` — host gateway handled via `--add-host` flag in CLI
+- `/etc/hosts` forwarding — at worker spawn, `forwardEtcHostsFlags` in `apps/cli/src/docker.ts` reads the host's `/etc/hosts` and emits one `--add-host` flag per valid user-added entry. Loopback IPs (`127.x`, `::1`) are rewritten to `host-gateway`; IPv6 addresses are bracketed. Disable per-scan via `SHANNON_FORWARD_HOSTS=false`. No-op on Windows native (WSL2 reads its own `/etc/hosts` via the Linux path).
 
 ### Worker Package (`apps/worker/`)
 - `apps/worker/src/paths.ts` — Centralized path constants (`PROMPTS_DIR`, `CONFIGS_DIR`, `WORKSPACES_DIR`)
@@ -137,16 +138,16 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig
 - `apps/worker/src/temporal/shared.ts` — Types, interfaces, query definitions
 ### Five-Phase Pipeline
 
-1. **Pre-Recon** (`pre-recon`) — External scans (nmap, subfinder, whatweb) + source code analysis
+1. **Pre-Recon** (`pre-recon`) — Source code analysis to build the architectural baseline
 2. **Recon** (`recon`) — Attack surface mapping from initial findings
 3. **Vulnerability Analysis** (5 parallel agents) — injection, xss, auth, authz, ssrf
 4. **Exploitation** (5 parallel agents, conditional) — Exploits confirmed vulnerabilities
 5. **Reporting** (`report`) — Executive-level security report
 
 ### Supporting Systems
-- **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings, MFA/TOTP, and per-app testing parameters. Credential resolution — local mode: env vars → `./.env`; npx mode: env vars → `~/.shannon/config.toml` (via `shn setup`)
-- **Prompts** — Per-phase templates in `apps/worker/prompts/` with variable substitution (`{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`). Shared partials in `apps/worker/prompts/shared/` via `apps/worker/src/services/prompt-manager.ts`
-- **SDK Integration** — Uses `@anthropic-ai/claude-agent-sdk` with `maxTurns: 10_000` and `bypassPermissions` mode. Browser automation via `playwright-cli` with session isolation (`-s=<session>`). TOTP generation via `generate-totp` CLI tool. Login flow template at `apps/worker/prompts/shared/login-instructions.txt` supports form, SSO, API, and basic auth
+- **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings (MFA/TOTP), URL/code rule scoping (`rules.avoid`/`rules.focus`), run-scope steering (`vuln_classes`, `exploit`), free-form `rules_of_engagement`, and post-hoc `report` filters (`min_severity`, `min_confidence`, `guidance`). `code_path` avoid rules are written into `~/.claude/settings.json` `permissions.deny` (`Read`/`Edit`) once per workflow by `apps/worker/src/temporal/activities.ts:syncCodePathDenyRules` so the SDK enforces them at the tool layer even in `bypassPermissions` mode. `vuln_classes`/`exploit` scope is locked into `session.json` on first run; resumes with a different scope fail fast (`persistOrValidateRunScope`). Credential resolution — local mode: env vars → `./.env`; npx mode: env vars → `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`)
+- **Prompts** — Per-phase templates in `apps/worker/prompts/` with variable substitution (`{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`). Shared partials in `apps/worker/prompts/shared/` via `apps/worker/src/services/prompt-manager.ts`, including `_code-path-rules.txt` (focus/avoid `[FILE]`/`[GLOB]` routing) and `_rules-of-engagement.txt` (free-text engagement rules). When `exploit: false`, `apps/worker/src/services/findings-renderer.ts` deterministically converts each `*_exploitation_queue.json` into a `*_findings.md` for report assembly — no LLM in the loop
+- **SDK Integration** — Uses `@anthropic-ai/claude-agent-sdk` with `maxTurns: 10_000` and `bypassPermissions` mode. Adaptive thinking is enabled by default on Opus 4.6/4.7/4.8 (`supportsAdaptiveThinking` in `apps/worker/src/ai/models.ts`); disable per-scan via `CLAUDE_ADAPTIVE_THINKING=false` (env) or `core.adaptive_thinking = false` (npx TOML). Browser automation via `playwright-cli` with session isolation (`-s=<session>`). TOTP generation via `generate-totp` CLI tool. Login flow template at `apps/worker/prompts/shared/login-instructions.txt` supports form, SSO, API, and basic auth. On authenticated whitebox scans, the `validate-authentication` preflight performs the single real login and saves the browser session to `auth-state.json` in the per-session audit directory (path from `authStateFile()` in `apps/worker/src/audit/utils.ts`, derived from `generateAuditPath()`). The validation activity (`apps/worker/src/services/validate-authentication.ts`) removes any stale file from a prior run before the agent runs and verifies the file parses and contains cookies or storage before the preflight is marked complete; `logWorkflowComplete` deletes it when the workflow ends so authenticated cookies don't sit on disk between scans. Agent prompts opt in to session reuse by `@include(shared/_shared-session.txt)` before their `<login_instructions>` block — the partial restores the session and falls through to the full login flow if verification fails. `vuln-auth`/`exploit-auth` omit the include and own their own login
 - **Audit System** — Crash-safe append-only logging in `workspaces/{hostname}_{sessionId}/`. Tracks session metrics, per-agent logs, prompts, and deliverables. WorkflowLogger (`apps/worker/src/audit/workflow-logger.ts`) provides unified human-readable per-workflow logs, backed by LogStream (`apps/worker/src/audit/log-stream.ts`) shared stream primitive
 - **Deliverables** — Saved to `deliverables/` in the target repo via the `save-deliverable` CLI script (`apps/worker/src/scripts/save-deliverable.ts`)
 - **Workspaces & Resume** — Named workspaces via `-w <name>` or auto-named from URL+timestamp. Resume detects completed agents via `session.json`. `loadResumeState()` in `apps/worker/src/temporal/activities.ts` validates deliverable existence, restores git checkpoints, and cleans up incomplete deliverables. Workspace listing via `apps/worker/src/temporal/workspaces.ts`
@@ -227,12 +228,16 @@ Comments must be **timeless** — no references to this conversation, refactorin
 
 **Entry Points:** `apps/worker/src/temporal/workflows.ts`, `apps/worker/src/temporal/activities.ts`, `apps/worker/src/temporal/worker.ts`
 
-**Core Logic:** `apps/worker/src/session-manager.ts`, `apps/worker/src/ai/claude-executor.ts`, `apps/worker/src/config-parser.ts`, `apps/worker/src/services/`, `apps/worker/src/audit/`
+**Core Logic:** `apps/worker/src/session-manager.ts`, `apps/worker/src/ai/claude-executor.ts`, `apps/worker/src/ai/settings-writer.ts` (writes `code_path` deny rules to `~/.claude/settings.json`), `apps/worker/src/config-parser.ts`, `apps/worker/src/services/` (incl. `preflight.ts`, `findings-renderer.ts`, `reporting.ts`), `apps/worker/src/audit/`
 
 **Config:** `docker-compose.yml`, `apps/cli/infra/compose.yml`, `apps/worker/configs/`, `apps/worker/prompts/`, `tsconfig.base.json` (shared compiler options), `turbo.json`, `biome.json`
 
 **CI/CD:** `.github/workflows/release.yml` (Docker Hub push + npm publish + GitHub release, manual dispatch)
 
+## Package Installation
+
+Package managers are configured with a minimum release age (7 days). Requires pnpm >= 10.16.0. If `pnpm install` fails due to a package being too new, **do not attempt to bypass it** — report the blocked package to the user and stop.
+
 ## Troubleshooting
 
 - **"Repository not found"** — Pass a bare name (`-r my-repo`) for `./repos/my-repo`, or a path (`-r /path/to/repo`) for any directory
@@ -240,5 +245,4 @@ Comments must be **timeless** — no references to this conversation, refactorin
 - **Worker not processing** — Check `docker ps --filter "name=shannon-worker-"`
 - **Reset state** — `./shannon stop --clean`
 - **Local apps unreachable** — Use `host.docker.internal` instead of `localhost`
-- **Missing tools** — Use `--pipeline-testing` to skip nmap/subfinder/whatweb (graceful degradation)
 - **Container permissions** — On Linux, may need `sudo` for docker commands

Dockerfile

@@ -13,46 +13,14 @@ RUN apk update && apk add --no-cache \
     curl \
     wget \
     ca-certificates \
-    # Network libraries for Go tools
-    libpcap-dev \
-    linux-headers \
     # Language runtimes
-    go \
     nodejs-22 \
     npm \
-    python3 \
-    py3-pip \
-    ruby \
-    ruby-dev \
-    # Security tools available in Wolfi
-    nmap \
     # Additional utilities
     bash
 
-# Set environment variables for Go
-ENV GOPATH=/go
-ENV PATH=$GOPATH/bin:/usr/local/go/bin:$PATH
-ENV CGO_ENABLED=1
-
-# Create directories
-RUN mkdir -p $GOPATH/bin
-
-# Install Go-based security tools
-RUN go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@v2.13.0
-# Install WhatWeb from release tarball (Ruby-based tool)
-RUN curl -sL https://github.com/urbanadventurer/WhatWeb/archive/refs/tags/v0.6.3.tar.gz | tar xz -C /opt && \
-    mv /opt/WhatWeb-0.6.3 /opt/whatweb && \
-    chmod +x /opt/whatweb/whatweb && \
-    gem install addressable -v 2.8.9 && \
-    echo '#!/bin/bash' > /usr/local/bin/whatweb && \
-    echo 'cd /opt/whatweb && exec ./whatweb "$@"' >> /usr/local/bin/whatweb && \
-    chmod +x /usr/local/bin/whatweb
-
-# Install Python-based tools
-RUN pip3 install --no-cache-dir schemathesis==4.13.0
-
 # Install pnpm
-RUN npm install -g pnpm@10.12.1
+RUN npm install -g --ignore-scripts pnpm@10.33.0
 
 # Build Node.js application in builder to avoid QEMU emulation failures in CI
 WORKDIR /app
@@ -69,7 +37,8 @@ COPY . .
 # Build worker. CLI not needed in Docker
 RUN pnpm --filter @shannon/worker run build
 
-RUN pnpm prune --prod
+# Production-only deps (pnpm recommends install --prod over prune in monorepos)
+RUN rm -rf node_modules apps/*/node_modules && pnpm install --frozen-lockfile --prod
 
 # Runtime stage - Minimal production image
 FROM cgr.dev/chainguard/wolfi-base:latest AS runtime
@@ -82,15 +51,11 @@ RUN apk update && apk add --no-cache \
     bash \
     curl \
     ca-certificates \
-    # Network libraries (runtime)
-    libpcap \
-    # Security tools
-    nmap \
+    shadow \
     # Language runtimes (minimal)
     nodejs-22 \
     npm \
     python3 \
-    ruby \
     # Chromium browser and dependencies for Playwright
     chromium \
     # Additional libraries Chromium needs
@@ -108,20 +73,6 @@ RUN apk update && apk add --no-cache \
     # Font rendering
     fontconfig
 
-# Copy Go binaries from builder
-COPY --from=builder /go/bin/subfinder /usr/local/bin/
-
-# Copy WhatWeb from builder
-COPY --from=builder /opt/whatweb /opt/whatweb
-COPY --from=builder /usr/local/bin/whatweb /usr/local/bin/whatweb
-
-# Install WhatWeb Ruby dependencies in runtime stage
-RUN gem install addressable -v 2.8.9
-
-# Copy Python packages from builder
-COPY --from=builder /usr/lib/python3.*/site-packages /usr/lib/python3.12/site-packages
-COPY --from=builder /usr/bin/schemathesis /usr/bin/
-
 # Create non-root user
 RUN addgroup -g 1001 pentest && \
     adduser -u 1001 -G pentest -s /bin/bash -D pentest
@@ -140,7 +91,7 @@ COPY --from=builder /app/node_modules /app/node_modules
 COPY --from=builder /app/apps/worker /app/apps/worker
 COPY --from=builder /app/apps/cli/package.json /app/apps/cli/package.json
 
-RUN npm install -g @anthropic-ai/claude-code@2.1.84 @playwright/cli@0.1.1
+RUN npm install -g --ignore-scripts @anthropic-ai/claude-code@2.1.84 @playwright/cli@0.1.1
 RUN mkdir -p /tmp/.claude/skills && \
     playwright-cli install --skills && \
     cp -r .claude/skills/playwright-cli /tmp/.claude/skills/ && \
@@ -153,7 +104,7 @@ RUN ln -s /app/apps/worker/dist/scripts/save-deliverable.js /usr/local/bin/save-
     chmod +x /app/apps/worker/dist/scripts/generate-totp.js
 
 # Create directories for session data and ensure proper permissions
-RUN mkdir -p /app/sessions /app/deliverables /app/repos /app/workspaces && \
+RUN mkdir -p /app/sessions /app/repos /app/workspaces && \
     mkdir -p /tmp/.cache /tmp/.config /tmp/.npm && \
     chmod 777 /app && \
     chmod 777 /tmp/.cache && \

SHANNON-PRO.md

@@ -1,256 +0,0 @@
-# Shannon Pro
-
-Shannon Pro is Keygraph's comprehensive AppSec platform, combining SAST, SCA, secrets scanning, business logic security testing, and autonomous pentesting in a single correlated workflow:
-
-- **Agentic static analysis:** CPG-based data flow, SCA with reachability, secrets detection, business logic security testing
-- **Static-dynamic correlation:** static findings are fed into the dynamic pipeline and exploited against the running application, so every reported vulnerability has a working proof-of-concept
-- **Enterprise deployment:** self-hosted runner (code and LLM calls never leave customer infrastructure), CI/CD integration, GitHub PR scanning, service boundary detection
-
-The platform cross-references static and dynamic results to eliminate false positives, prioritize by proven exploitability, and produce pentest-grade reports with reproducible proof-of-concept exploits for every finding.
-
----
-
-## The Problem: Fragmented AppSec and Alert Fatigue
-
-Modern engineering teams face two compounding security challenges. First, traditional static analysis tools (SCA, SAST, and secrets scanners) operate without context, producing high volumes of false positives that erode developer trust. Second, penetration testing remains an expensive, periodic exercise that cannot keep pace with continuous deployment. The result is a fragmented security posture where static tools cry wolf, dynamic assessments arrive too late, and engineering teams treat security as compliance theater rather than a source of genuine protection.
-
-Shannon Pro addresses both problems in a single platform by replacing pattern-based static analysis with LLM-powered reasoning and augmenting it with a fully autonomous AI pentester that validates findings at runtime. The platform supports a self-hosted runner model where source code and LLM interactions never leave the customer's infrastructure.
-
----
-
-## Platform Architecture Overview
-
-Shannon Pro operates as a two-stage pipeline: agentic static analysis of the codebase, followed by autonomous dynamic penetration testing against the running application. Findings from both stages are correlated to produce a unified, high-confidence result set.
-
----
-
-# Stage 1: Agentic Static Analysis (AppSec)
-
-The static analysis stage performs comprehensive code-level security assessment using LLM-powered agents. It comprises five core capabilities: SAST (data flow analysis, point issue detection, and business logic security testing), SCA with reachability analysis, and secrets detection.
-
-## SAST: Data Flow Analysis
-
-Shannon Pro transforms the target codebase into a Code Property Graph (CPG) that combines the abstract syntax tree, control flow graph, and program dependence graph into a unified structure. Nodes represent program constructs (such as expressions, statements, and declarations), and edges capture syntactic, control-flow, and data-dependence relationships. The analysis proceeds in three phases.
-
-### Phase 1: Source and Sink Extraction
-
-For each vulnerability type, the system identifies sources (where untrusted data enters, such as user input, API requests, and file reads) and sinks (where that data could cause harm, such as SQL queries, command execution, and file writes). Deterministic pattern matching establishes a baseline, then an AI agent analyzes the codebase to discover sources and sinks that generic patterns miss, including custom input handlers and framework-specific patterns unique to the target codebase. A filtering agent removes irrelevant results such as test fixtures and mock data.
-
-### Phase 2: Path Tracing with Contextual Reasoning
-
-This is where Shannon Pro's approach differs fundamentally from traditional SAST. The system traces backward from each sink toward potential sources. At every node along the path, an LLM analyzes whether sanitization is applied at that exact point and whether that sanitization is sufficient for this specific vulnerability in this specific context.
-
-The key insight is that security fixes are context-dependent. A function that makes data safe for one SQL query might not protect a different query. A custom sanitizer that a team wrote will not be recognized by pattern-based tools. Traditional tools rely on a hard-coded list of safe functions; Shannon Pro reasons about what the code is actually doing, validating whether the specific sanitization at each node actually addresses the specific risk at the specific sink.
-
-### Phase 3: Path Validation
-
-Each identified vulnerability path is validated by an autonomous Claude agent that confirms control flow correctness (is the path actually executable?) and logic correctness (is the vulnerability real or a false positive?). Agents produce confidence scores, and only validated paths proceed to reporting.
-
-## SAST: Point Issue Detection
-
-Point issues are vulnerabilities where security depends on what is happening at a single location rather than across a data flow path. The system pre-filters and organizes files, then feeds each one to an LLM to identify issues such as:
-
-- Use of weak encryption algorithms
-- Hardcoded credentials or API keys
-- Insecure configuration settings (e.g., debug mode enabled in production)
-- Missing security headers
-- Weak random number generation
-- Disabled certificate validation
-- Overly permissive CORS settings
-
-## SAST: Business Logic Security Testing
-
-Traditional security testing tools cannot reason about application-specific correctness properties. Pattern-based scanners look for known vulnerability signatures; conventional fuzzers (AFL, libFuzzer) find crashes and memory errors through input mutation but operate without awareness of business semantics. Neither can determine whether a syntactically valid response actually violates the application's security model. Shannon Pro bridges this gap with automated invariant-based security testing: LLM agents that understand the business semantics of the codebase, automatically discover application-specific invariants, and generate targeted test scenarios that verify whether those invariants hold under adversarial conditions. This approach draws from property-based testing methodology, applied specifically to security-relevant business logic.
-
-### Why Business Logic Bugs Are Missed
-
-Pattern-based scanners and traditional SAST are structurally incapable of finding business logic vulnerabilities. These bugs do not involve malformed input reaching a dangerous sink. Instead, they involve legitimate operations that violate unstated rules about how the application should behave. A multi-tenant SaaS platform assumes Organization A's data is never accessible to Organization B. An e-commerce application assumes a checkout total cannot go negative. A healthcare platform assumes a patient record is only visible to the assigned provider. These invariants are implicit in the business domain, never encoded in a generic vulnerability database, and invisible to any tool that does not understand what the application is supposed to do.
-
-### How It Works
-
-Shannon Pro's business logic security testing operates in four phases:
-
-**Phase 1: Invariant Discovery.** An LLM agent performs a deep semantic analysis of the codebase, examining data models, API endpoints, authorization logic, and domain-specific patterns. Rather than looking for known vulnerability signatures, the agent reasons about the application's intended behavior and derives business logic invariants: rules that must hold for the application to be secure. For a multi-tenant platform, the agent identifies invariants such as "document access must verify that the document belongs to the requesting user's organization." For a financial application, it might identify "a transfer cannot be initiated where the source and destination accounts have the same owner but different privilege levels." These are security properties that no generic scanner can know about because they are unique to each application.
-
-**Phase 2: Fuzzer Generation.** For each discovered invariant, a second agent generates a targeted fuzzer: a test scenario designed to violate the invariant. These are not random inputs. The agent reads the code, understands the expected authorization checks (or lack thereof), and constructs specific adversarial scenarios. For an authorization invariant, the fuzzer might construct a request where a user from one organization references a resource belonging to another organization. For a state machine invariant, it might craft a sequence of API calls that skips a required approval step.
-
-**Phase 3: Violation Detection.** The generated fuzzers are executed against a stubbed test environment that replicates the application's business logic with mocked dependencies. When a fuzzer succeeds, meaning the invariant does not hold, the system has identified a confirmed business logic vulnerability. The agent traces the violation back to the specific code location where the missing check or flawed logic exists.
-
-**Phase 4: Exploit Synthesis.** For every confirmed violation, the system produces a full proof-of-concept exploit with step-by-step reproduction instructions, the specific API calls or user actions required, the observed versus expected behavior, and the security impact.
-
-### Real-World Example: Cross-Tenant Data Access (CWE-639)
-
-In a production multi-tenant platform, Shannon Pro's business logic security testing discovered a critical Insecure Direct Object Reference (IDOR) vulnerability that no traditional scanner would detect.
-
-**Invariant discovered:** Document access must verify that the document belongs to the requesting user's organization.
-
-**Fuzzer generated:** The agent extracted the `GetDocument` handler logic into a stubbed test environment, mocking the database layer to return documents with known organization IDs. The fuzzer generated combinations of requesting user organizations and document owner organizations, testing whether the handler enforces organizational boundaries.
-
-**Violation confirmed:** An attacker from Organization B can access documents belonging to Organization A by calling the `GetDocument` endpoint with the victim's document ID, without any authorization check preventing cross-organization access.
-
-**Exploit synthesized:**
-
-1. Attacker authenticates as a user in Organization B and obtains valid credentials.
-2. Attacker enumerates or guesses a document ID belonging to Organization A (e.g., through sequential ID guessing, leaked references, or predictable UUID patterns).
-3. Attacker calls `GET /api/document?document_id=victim-doc-123` with their Organization B credentials.
-4. The system retrieves the document without verifying organizational ownership.
-5. The system returns HTTP 200 with the complete document contents, including sensitive data belonging to Organization A.
-
-**Impact:** Complete breach of multi-tenant data isolation. Attackers can read all documents across all organizations, potentially exposing confidential business data, PII, trade secrets, and compliance-sensitive information.
-
-**Expected behavior:** HTTP 403 Forbidden with an error message indicating access is denied, or HTTP 404 Not Found to avoid leaking document existence.
-
-This class of vulnerability, missing authorization at an organizational boundary, is invisible to pattern-based tools because the code is syntactically correct, uses no dangerous functions, and follows normal request-handling patterns. Only a system that understands the business invariant ("documents belong to organizations, and access must respect that boundary") can identify the violation.
-
-### What This Means
-
-Business logic security testing extends Shannon Pro's coverage beyond the limits of traditional static and dynamic analysis. Data flow analysis catches injection, XSS, and other input-driven vulnerabilities. Point issue detection catches configuration and cryptographic weaknesses. Business logic security testing catches the authorization failures, state machine violations, and domain-specific logic errors that represent some of the most severe and most commonly missed vulnerabilities in production applications. Together, these three capabilities provide comprehensive SAST coverage across the full vulnerability spectrum.
-
-## SCA with Reachability Analysis
-
-Traditional SCA flags any library with a known CVE regardless of whether the vulnerable function is called or even reachable. Shannon Pro goes further with a four-step reachability process:
-
-1. An AI agent researches each CVE to identify the exact vulnerable function, framework, or conditions.
-2. For framework-level issues, the system checks whether the application actually uses the affected framework in practice.
-3. For function-level issues, the CPG is queried to extract nodes where the vulnerable function is used. If no nodes are found, the vulnerability is marked as not reachable.
-4. If nodes are found, execution flow is traced from entry points (main functions, API endpoints) to determine whether a path exists. Proven executable vulnerabilities are flagged; code that uses the function but is not currently callable is marked as likely reachable.
-
-## Secrets Detection
-
-Shannon Pro combines three approaches to secrets scanning. Standard regex-based pattern matching catches known formats (AWS keys, API tokens, etc.). Simultaneously, during the point issue detection phase, LLM-based detection catches secrets that standard patterns miss, such as dynamically constructed credentials, custom credential formats, and obfuscated tokens. The LLM layer also filters out test data, placeholders, and documentation examples that regex scanners frequently flag as false positives.
-
-For discovered secrets, Shannon Pro performs liveness validation: an agent determines the API context for each credential and attempts to authenticate against the corresponding service. This distinguishes active, exploitable secrets from revoked or rotated credentials, ensuring teams focus remediation effort on secrets that represent real exposure. Liveness checks use read-only API calls (e.g., identity verification endpoints) to avoid triggering side effects or account lockouts, and in the self-hosted runner deployment, all validation occurs within the customer's network.
-
-## Boundary Analysis
-
-For large-scale or monorepo architectures, Shannon Pro's boundary analysis capability allows organizations to scope scans to specific services or portions of the codebase. An agent analyzes the repository and identifies logical boundaries (by service, frontend vs. backend, microservice, etc.). Users review, confirm, and optionally edit the detected boundaries, then select which to include in a scan. Findings are tagged by boundary, enabling clear routing to the responsible team.
-
-## False Positive Tagging
-
-Any finding can be marked as a false positive. On subsequent scans, the same finding will be flagged as likely false positive, so teams do not repeatedly triage issues they have already dismissed.
-
----
-
-# Stage 2: Autonomous Dynamic Penetration Testing
-
-Shannon Pro's dynamic testing pipeline mirrors the workflow of a professional human penetration tester, implemented as a multi-agent system powered by the Anthropic Claude Agent SDK. The system operates through five phases using 13 specialized agents.
-
-## Execution Model
-
-Phases 1 and 2 (reconnaissance) run sequentially. Phases 3 and 4 (vulnerability analysis and exploitation) run as pipelined parallel: each vulnerability/exploit pair is independent. When a vulnerability agent finishes for a given attack domain, the corresponding exploit agent starts immediately, even if other vulnerability agents are still running. Phase 5 (reporting) runs after all exploitation is complete.
-
-## Phase 1: Pre-Reconnaissance
-
-Pure static analysis of the source code without browser interaction. The pre-recon agent maps the application architecture, identifies security-relevant components (authentication systems, database access patterns, input handling), and catalogs the complete attack surface from a code perspective. Outputs include a comprehensive catalog of all network-accessible entry points, technology stack details, authentication and authorization mechanisms, and all identified sinks (XSS, SSRF, injection) with their locations.
-
-This phase informs everything downstream. If the codebase uses an ORM with parameterized queries everywhere, the injection agents know to focus elsewhere.
-
-## Phase 2: Reconnaissance
-
-Bridges static and dynamic analysis using browser automation. The recon agent correlates code findings with the live application, validating that endpoints actually exist, mapping authentication flows, inventorying input vectors (URL parameters, POST fields, headers, cookies), and documenting the real authorization architecture. This phase may also integrate with infrastructure discovery tools including Nmap, Subfinder, and WhatWeb for network perimeter mapping.
-
-## Phase 3: Vulnerability Analysis
-
-Five parallel agents, each focused on a distinct attack domain, combine code analysis with runtime probing to generate exploitation hypotheses. Each agent produces a detailed analysis deliverable and an exploitation queue -- a structured JSON file listing specific vulnerabilities to attempt, including the type, location, method, parameter, code evidence, and a suggested initial payload.
-
-The five vulnerability analysis agents and their methodologies:
-
-| Agent | Approach | What It Analyzes |
-| --- | --- | --- |
-| **Injection** | Source -> Sink taint | User input reaching SQL, command, file, template, or deserialization sinks without adequate sanitization |
-| **XSS** | Sink -> Source taint | HTML rendering contexts (innerHTML, document.write, event handlers, eval) reachable from user input without proper encoding |
-| **SSRF** | Sink -> Source taint | HTTP client libraries, raw sockets, URL openers, and headless browsers callable with user-controlled URLs |
-| **Auth** | Guard validation | Missing security controls: rate limiting, session management, token entropy, password hashing, HSTS, SSO/OAuth configuration |
-| **Authz** | Guard validation | Missing authorization checks before side effects: horizontal (ownership), vertical (role/capability), and context/workflow violations |
-
-If a vulnerability agent's exploitation queue is empty for a given attack domain, the corresponding exploit agent is skipped entirely, saving significant time and cost.
-
-## Phase 4: Exploitation
-
-Five parallel exploit agents consume the exploitation queues and attempt to verify each hypothesis using full Playwright browser automation. Agents can navigate to endpoints, fill forms with crafted payloads, submit requests, observe responses, take screenshots, and chain multiple requests together to validate complex attack sequences.
-
-**Core principle: POC or it didn't happen.** Shannon Pro never reports a vulnerability without a working proof-of-concept exploit. Exploitation agents classify each finding as EXPLOITED, POTENTIAL, or FALSE POSITIVE. Only EXPLOITED findings (with concrete evidence) make it to the final report. POTENTIAL findings are programmatically stripped before reporting, giving agents a designated space to log uncertain observations without polluting the deliverable.
-
-## Phase 5: Reporting
-
-A reporting agent synthesizes all evidence files into a pentest-grade executive report. The agent only sees confirmed findings (evidence files from Phase 4), never raw hypotheses. It de-duplicates findings, assesses severity, and provides remediation guidance. Every reported vulnerability includes reproducible steps and copy-and-paste commands for verification.
-
----
-
-# Static-Dynamic Correlation
-
-Shannon Pro's distinguishing capability is the correlation between its static and dynamic analysis stages.
-
-## How AppSec Feeds Into Dynamic Testing
-
-After static analysis completes, findings go through an enrichment phase that adds priority, confidence, and application context. CWEs are mapped to Shannon's five attack domains using a best-fit heuristic. Where a CWE maps to multiple domains (e.g., CWE-918 spans both SSRF and injection contexts), the finding is routed to the most exploitation-relevant agent. CWEs that do not map cleanly to any attack domain, such as certain business logic classes, are routed directly to the exploitation queue with their static analysis context preserved rather than forced into an ill-fitting category. Secrets, data flow findings, point issues, and business logic security testing violations are sent to Shannon's exploitation queue, where domain-specific agents attempt to exploit each finding with real proof-of-concept attacks against the running application.
-
-This correlation means that a data flow vulnerability identified in static analysis (e.g., unsanitized user input reaching a SQL query) is not just reported as a theoretical risk -- it is actively exploited against the live application. Similarly, a business logic invariant violation (e.g., missing cross-tenant authorization) identified by the security testing engine is fed directly into the Authz exploitation agent, which attempts to reproduce the exact cross-organization access scenario against the running application. Confirmed exploits are traced back to their source code location, giving developers both the proof that the vulnerability is real and the exact line of code to fix.
-
----
-
-# Key Technical Capabilities
-
-- **Fully Autonomous Operation:** Shannon Pro handles complex workflows including 2FA/TOTP logins and SSO (e.g., Sign in with Google) without human intervention. TOTP is handled via a dedicated MCP server tool.
-- **White-Box Awareness:** Unlike black-box scanners, Shannon Pro reads the source code to intelligently guide its attack strategy, combining code-level insight with runtime validation.
-- **Parallel Processing:** Vulnerability analysis and exploitation phases run concurrently across attack domains, with pipelined parallelism minimizing total execution time.
-- **Tool Orchestration:** Shannon Pro orchestrates existing security tools (e.g., Schemathesis for API testing, Nmap for network discovery) while adding LLM reasoning to interpret results.
-- **Configurable Login Flows:** Authentication configuration specifies login procedures and credentials, which are interpolated into agent prompts for authenticated testing.
-
----
-
-# Container Isolation and Data Security
-
-Shannon Pro is engineered with a secure-by-design philosophy to ensure code privacy and isolation across every stage of the pipeline.
-
-## Per-Organization Infrastructure
-
-Each organization receives its own isolated compute environment. In the managed deployment, Keygraph provisions dedicated ECS infrastructure (containers, IAM roles, task queues) per organization. In the self-hosted runner deployment, the organization provisions and controls the data plane, which handles all code access and LLM calls using the organization's own API keys. The Keygraph control plane receives only aggregate findings. In either model, organizations never share compute environments with other organizations.
-
-## Ephemeral Code Handling
-
-When a scan runs, the target repository is cloned to a temporary workspace inside the isolated container. The scan executes against this local copy. Immediately after the scan completes, the entire workspace is deleted, including all cloned code. Source code is never persisted after a scan finishes. Even if a scan fails or is cancelled, a disconnected cleanup process executes regardless of how the scan terminates.
-
-In the self-hosted runner deployment, all code handling occurs within the customer's own infrastructure. Keygraph's control plane never receives, processes, or stores source code.
-
-## Encrypted Storage
-
-Code snippets associated with findings are encrypted before being written to the database. Deliverables uploaded to S3 are encrypted at rest. Each organization's data is stored in org-specific buckets with org-scoped access policies.
-
-## Network Isolation
-
-Isolated workers run in private subnets with org-specific security groups, ensuring network-level separation between customer workloads.
-
-## Self-Hosted Runner
-
-Shannon Pro supports a self-hosted runner deployment model, following the same architecture as GitHub Actions self-hosted runners. The data plane (the runner that clones code, executes scans, and makes all LLM API calls) runs entirely within the customer's infrastructure using the customer's own LLM API keys. Source code never leaves the customer's network, and no code or LLM interactions pass through Keygraph's systems. The control plane (job orchestration, scan scheduling, and the reporting UI) is hosted by Keygraph and receives only aggregate findings to power dashboards, search, and reporting. This separation ensures that Keygraph never has access to customer source code or raw LLM call content.
-
----
-
-# Deployment and Editions
-
-Shannon is offered in two editions to serve different operational needs:
-
-| Feature | Shannon Lite | Shannon Pro |
-| --- | --- | --- |
-| **Licensing** | AGPL-3.0 (open source) | Commercial |
-| **Static Analysis** | Code review prompting | Full agentic static analysis (SAST, SCA, secrets, business logic security testing) |
-| **Dynamic Testing** | Autonomous AI pentest framework | Autonomous AI pentesting with static-dynamic correlation |
-| **Analysis Engine** | Code review prompting | CPG-based data flow with LLM reasoning at every node |
-| **Business Logic** | N/A | Automated invariant discovery, test scenario generation, and exploit synthesis |
-| **Integration** | Manual / CLI | Native CI/CD, GitHub PR scanning, enterprise support, self-hosted runner |
-| **Deployment** | CLI / manual | Managed cloud or self-hosted runner (customer data plane, Keygraph control plane) |
-| **Boundary Analysis** | N/A | Automatic service boundary detection with team routing |
-| **Best For** | Local testing of own applications | Enterprise application security posture management |
-
----
-
-# Compliance Integration
-
-Within the broader Keygraph ecosystem, Shannon Pro serves as the primary engine for automated compliance evidence generation. By automating penetration testing and static analysis requirements, Shannon Pro generates real-time evidence for frameworks such as SOC 2 and HIPAA, transforming security testing from a periodic audit obligation into a continuous component of the compliance program.
-
----
-
-# Methodology Standards
-
-Shannon Pro follows AI-assisted white-box testing methodology broadly aligned with OWASP Web Security Testing Guide (WSTG) and OWASP Top 10 standards. All dynamic testing produces confirmed, exploitable findings with reproducible proof-of-concept exploits. Static analysis covers established CWE categories with LLM-powered validation to minimize false positive rates.

apps/cli/infra/compose.yml

@@ -4,7 +4,7 @@ networks:
 
 services:
   temporal:
-    image: temporalio/temporal:latest
+    image: temporalio/temporal:1.7.0
     container_name: shannon-temporal
     command: ["server", "start-dev", "--db-filename", "/home/temporal/temporal.db", "--ip", "0.0.0.0"]
     ports:
@@ -19,32 +19,5 @@ services:
       retries: 10
       start_period: 30s
 
-  router:
-    image: node:20-slim
-    container_name: shannon-router
-    profiles: ["router"]
-    command: >
-      sh -c "apt-get update && apt-get install -y gettext-base &&
-             npm install -g @musistudio/claude-code-router &&
-             mkdir -p /root/.claude-code-router &&
-             envsubst < /config/router-config.json > /root/.claude-code-router/config.json &&
-             ccr start"
-    ports:
-      - "127.0.0.1:3456:3456"
-    volumes:
-      - ./router-config.json:/config/router-config.json:ro
-    environment:
-      - HOST=0.0.0.0
-      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
-      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
-      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-}
-      - ROUTER_DEFAULT=${ROUTER_DEFAULT:-openai,gpt-4o}
-    healthcheck:
-      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3456/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-
 volumes:
   temporal-data:

apps/cli/infra/router-config.json

@@ -1,31 +0,0 @@
-{
-  "HOST": "0.0.0.0",
-  "APIKEY": "shannon-router-key",
-  "LOG": true,
-  "LOG_LEVEL": "info",
-  "NON_INTERACTIVE_MODE": true,
-  "API_TIMEOUT_MS": 600000,
-  "Providers": [
-    {
-      "name": "openai",
-      "api_base_url": "https://api.openai.com/v1/chat/completions",
-      "api_key": "$OPENAI_API_KEY",
-      "models": ["gpt-5.2", "gpt-5-mini"],
-      "transformer": {
-        "use": [["maxcompletiontokens", { "max_completion_tokens": 16384 }]]
-      }
-    },
-    {
-      "name": "openrouter",
-      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
-      "api_key": "$OPENROUTER_API_KEY",
-      "models": ["google/gemini-3-flash-preview"],
-      "transformer": {
-        "use": ["openrouter"]
-      }
-    }
-  ],
-  "Router": {
-    "default": "$ROUTER_DEFAULT"
-  }
-}

apps/cli/src/commands/setup.ts

@@ -1,5 +1,5 @@
 /**
- * `shn setup` — interactive TUI wizard for one-time credential configuration.
+ * `npx @keygraph/shannon setup` — interactive TUI wizard for one-time credential configuration.
  *
  * Walks the user through selecting a provider and entering credentials,
  * then persists everything to ~/.shannon/config.toml with 0o600 permissions.
@@ -13,7 +13,7 @@ import { type ShannonConfig, saveConfig } from '../config/writer.js';
 
 const SHANNON_HOME = path.join(os.homedir(), '.shannon');
 
-type Provider = 'anthropic' | 'custom_base_url' | 'bedrock' | 'vertex' | 'router';
+type Provider = 'anthropic' | 'custom_base_url' | 'bedrock' | 'vertex';
 
 export async function setup(): Promise<void> {
   p.intro('Shannon Setup');
@@ -26,14 +26,16 @@ export async function setup(): Promise<void> {
       { value: 'custom_base_url' as const, label: 'Custom Base URL', hint: 'proxies, gateways' },
       { value: 'bedrock' as const, label: 'Claude via AWS Bedrock' },
       { value: 'vertex' as const, label: 'Claude via Google Vertex AI' },
-      { value: 'router' as const, label: 'Router', hint: 'experimental' },
     ],
   });
   if (p.isCancel(provider)) return cancelAndExit();
 
   const config = await setupProvider(provider as Provider);
 
-  // 2. Save config
+  // 2. Adaptive thinking
+  await maybePromptAdaptiveThinking(config);
+
+  // 3. Save config
   saveConfig(config);
 
   const configPath = path.join(SHANNON_HOME, 'config.toml');
@@ -51,8 +53,6 @@ async function setupProvider(provider: Provider): Promise<ShannonConfig> {
       return setupBedrock();
     case 'vertex':
       return setupVertex();
-    case 'router':
-      return setupRouter();
   }
 }
 
@@ -83,7 +83,7 @@ async function setupAnthropic(): Promise<ShannonConfig> {
       'Do you want to change the default models?\n' +
       '    Small  - claude-haiku-4-5-20251001\n' +
       '    Medium - claude-sonnet-4-6\n' +
-      '    Large  - claude-opus-4-6',
+      '    Large  - claude-opus-4-8',
     initialValue: false,
   });
   if (p.isCancel(customizeModels)) return cancelAndExit();
@@ -105,7 +105,7 @@ async function setupAnthropic(): Promise<ShannonConfig> {
 
     const large = await p.text({
       message: 'Large model ID',
-      initialValue: 'claude-opus-4-6',
+      initialValue: 'claude-opus-4-8',
       validate: required('Large model ID is required'),
     });
     if (p.isCancel(large)) return cancelAndExit();
@@ -143,7 +143,7 @@ async function setupCustomBaseUrl(): Promise<ShannonConfig> {
       'Do you want to change the default models?\n' +
       '    Small  - claude-haiku-4-5-20251001\n' +
       '    Medium - claude-sonnet-4-6\n' +
-      '    Large  - claude-opus-4-6',
+      '    Large  - claude-opus-4-8',
     initialValue: false,
   });
   if (p.isCancel(customizeModels)) return cancelAndExit();
@@ -165,7 +165,7 @@ async function setupCustomBaseUrl(): Promise<ShannonConfig> {
 
     const large = await p.text({
       message: 'Large model ID',
-      initialValue: 'claude-opus-4-6',
+      initialValue: 'claude-opus-4-8',
       validate: required('Large model ID is required'),
     });
     if (p.isCancel(large)) return cancelAndExit();
@@ -202,7 +202,7 @@ async function setupBedrock(): Promise<ShannonConfig> {
 
   const large = await p.text({
     message: 'Large model ID',
-    placeholder: 'us.anthropic.claude-opus-4-6',
+    placeholder: 'us.anthropic.claude-opus-4-8',
     validate: required('Large model ID is required'),
   });
   if (p.isCancel(large)) return cancelAndExit();
@@ -265,7 +265,7 @@ async function setupVertex(): Promise<ShannonConfig> {
     large: () =>
       p.text({
         message: 'Large model ID',
-        placeholder: 'claude-opus-4-6',
+        placeholder: 'claude-opus-4-8',
         validate: required('Large model ID is required'),
       }),
   });
@@ -282,52 +282,22 @@ async function setupVertex(): Promise<ShannonConfig> {
   };
 }
 
-async function setupRouter(): Promise<ShannonConfig> {
-  const routerProvider = await p.select({
-    message: 'Router provider',
-    options: [
-      { value: 'openai' as const, label: 'OpenAI' },
-      { value: 'openrouter' as const, label: 'OpenRouter' },
-    ],
-  });
-  if (p.isCancel(routerProvider)) return cancelAndExit();
-
-  const apiKey = await promptSecret(
-    routerProvider === 'openai' ? 'Enter your OpenAI API key' : 'Enter your OpenRouter API key',
-  );
-
-  let defaultModel: string;
-  if (routerProvider === 'openai') {
-    const model = await p.select({
-      message: 'Default model',
-      options: [
-        { value: 'gpt-5.2' as const, label: 'GPT-5.2' },
-        { value: 'gpt-5-mini' as const, label: 'GPT-5 Mini' },
-      ],
-    });
-    if (p.isCancel(model)) return cancelAndExit();
-    defaultModel = `openai,${model}`;
-  } else {
-    const model = await p.select({
-      message: 'Default model',
-      options: [{ value: 'google/gemini-3-flash-preview' as const, label: 'Google Gemini 3 Flash Preview' }],
-    });
-    if (p.isCancel(model)) return cancelAndExit();
-    defaultModel = `openrouter,${model}`;
-  }
-
-  const router: ShannonConfig['router'] = { default: defaultModel };
-  if (routerProvider === 'openai') {
-    router.openai_key = apiKey;
-  } else {
-    router.openrouter_key = apiKey;
-  }
-
-  return { router };
-}
-
 // === Helpers ===
 
+async function maybePromptAdaptiveThinking(config: ShannonConfig): Promise<void> {
+  const m = config.models;
+  const hasAdaptiveModel = !m || [m.small, m.medium, m.large].some((v) => v && /opus-4-[678]/.test(v));
+  if (!hasAdaptiveModel) return;
+
+  const enable = await p.confirm({
+    message: 'Enable adaptive thinking on Opus 4.6/4.7/4.8? Claude decides when and how deeply to reason.',
+    initialValue: true,
+  });
+  if (p.isCancel(enable)) return cancelAndExit();
+
+  config.core = { ...config.core, adaptive_thinking: enable };
+}
+
 async function promptSecret(message: string): Promise<string> {
   const value = await p.password({
     message,

apps/cli/src/commands/start.ts

@@ -9,10 +9,10 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { ensureImage, ensureInfra, randomSuffix, spawnWorker } from '../docker.js';
-import { buildEnvFlags, isRouterConfigured, loadEnv, validateCredentials } from '../env.js';
+import { buildEnvFlags, loadEnv, validateCredentials } from '../env.js';
 import { getCredentialsPath, getWorkspacesDir, initHome } from '../home.js';
 import { isLocal } from '../mode.js';
-import { ensureDeliverables, resolveConfig, resolveRepo } from '../paths.js';
+import { resolveConfig, resolveRepo } from '../paths.js';
 import { displaySplash } from '../splash.js';
 
 export interface StartArgs {
@@ -22,7 +22,7 @@ export interface StartArgs {
   workspace?: string;
   output?: string;
   pipelineTesting: boolean;
-  router: boolean;
+  debug: boolean;
   version: string;
 }
 
@@ -31,44 +31,53 @@ export async function start(args: StartArgs): Promise<void> {
   initHome();
   loadEnv();
 
-  // 2. Validate credentials and auto-detect router mode
+  // 2. Validate credentials
   const creds = validateCredentials();
   if (!creds.valid) {
     console.error(`ERROR: ${creds.error}`);
     process.exit(1);
   }
-  const useRouter = args.router || isRouterConfigured();
 
   // 3. Resolve paths
   const repo = resolveRepo(args.repo);
   const config = args.config ? resolveConfig(args.config) : undefined;
-  ensureDeliverables(repo.hostPath);
 
   // 4. Ensure workspaces dir is writable by container user (UID 1001)
   const workspacesDir = getWorkspacesDir();
   fs.mkdirSync(workspacesDir, { recursive: true });
   fs.chmodSync(workspacesDir, 0o777);
 
-  // 5. Handle router env
-  if (useRouter) {
-    process.env.ANTHROPIC_BASE_URL = 'http://shannon-router:3456';
-    process.env.ANTHROPIC_AUTH_TOKEN = 'shannon-router-key';
-  }
-
-  // 6. Ensure image (auto-build in dev, pull in npx) and start infra
+  // 5. Ensure image (auto-build in dev, pull in npx) and start infra
   ensureImage(args.version);
-  await ensureInfra(useRouter);
+  await ensureInfra();
 
-  // 7. Generate unique task queue and container name
+  // 6. Generate unique task queue and container name
   const suffix = randomSuffix();
   const taskQueue = `shannon-${suffix}`;
   const containerName = `shannon-worker-${suffix}`;
 
-  // 8. Generate workspace name if not provided
+  // 7. Generate workspace name if not provided
   const workspace =
     args.workspace ?? `${new URL(args.url).hostname.replace(/[^a-zA-Z0-9-]/g, '-')}_shannon-${Date.now()}`;
 
-  // 9. Resolve credentials — mount single file to fixed container path
+  // 8. Create writable overlay directories (mounted over :ro repo paths inside container)
+  // Workspace dir must be 0o777 so the container user (UID 1001) can create audit subdirs
+  const workspacePath = path.join(workspacesDir, workspace);
+  fs.mkdirSync(workspacePath, { recursive: true });
+  fs.chmodSync(workspacePath, 0o777);
+  for (const dir of ['deliverables', 'scratchpad', '.playwright-cli', '.playwright']) {
+    const dirPath = path.join(workspacePath, dir);
+    fs.mkdirSync(dirPath, { recursive: true });
+    fs.chmodSync(dirPath, 0o777);
+  }
+
+  // 9. Pre-create overlay mount points (:ro mounts can't auto-create them)
+  const shannonDir = path.join(repo.hostPath, '.shannon');
+  for (const dir of ['deliverables', 'scratchpad', '.playwright-cli']) {
+    fs.mkdirSync(path.join(shannonDir, dir), { recursive: true });
+  }
+  fs.mkdirSync(path.join(repo.hostPath, '.playwright'), { recursive: true });
+
   const credentialsPath = getCredentialsPath();
   const hasCredentials = fs.existsSync(credentialsPath);
 
@@ -101,16 +110,24 @@ export async function start(args: StartArgs): Promise<void> {
     ...(hasCredentials && { credentials: credentialsPath }),
     ...(promptsDir && { promptsDir }),
     ...(outputDir && { outputDir }),
-    ...(workspace && { workspace }),
+    workspace,
     ...(args.pipelineTesting && { pipelineTesting: true }),
+    ...(args.debug && { debug: true }),
   });
 
-  // 14. Wait for workflow to register, then display info
-  proc.on('error', (err) => {
-    console.error(`Failed to start worker: ${err.message}`);
-    process.exit(1);
+  // 14. Bail if `docker run -d` itself fails (mount error, image missing, etc.)
+  const dockerExitCode = await new Promise<number>((resolve) => {
+    proc.once('exit', (code) => resolve(code ?? 1));
+    proc.once('error', (err) => {
+      console.error(`Failed to start worker: ${err.message}`);
+      resolve(1);
+    });
   });
 
+  if (dockerExitCode !== 0) {
+    process.exit(1);
+  }
+
   // Detect whether this is a fresh workspace or a resume by checking session.json existence
   const sessionJson = path.join(workspacesDir, workspace, 'session.json');
   const isResume = fs.existsSync(sessionJson);
@@ -154,7 +171,7 @@ export async function start(args: StartArgs): Promise<void> {
 
         // Clear waiting line and show info
         process.stdout.write('\r\x1b[K');
-        printInfo(args, useRouter, workspace, workflowId, repo.hostPath, workspacesDir);
+        printInfo(args, workspace, workflowId, repo.hostPath, workspacesDir);
         return;
       }
     } catch {
@@ -175,6 +192,9 @@ export async function start(args: StartArgs): Promise<void> {
     } catch {
       // Container may have already exited
     }
+    if (args.debug) {
+      printDebugHint(containerName);
+    }
   };
 
   process.on('SIGINT', () => {
@@ -188,9 +208,16 @@ export async function start(args: StartArgs): Promise<void> {
   process.on('exit', cleanup);
 }
 
+function printDebugHint(containerName: string): void {
+  console.log('');
+  console.log(`  Worker container preserved: ${containerName}`);
+  console.log(`    Inspect logs: docker logs ${containerName}`);
+  console.log(`    Remove:       docker rm ${containerName}`);
+  console.log('');
+}
+
 function printInfo(
   args: StartArgs,
-  routerActive: boolean,
   workspace: string,
   workflowId: string,
   repoPath: string,
@@ -208,9 +235,22 @@ function printInfo(
   if (args.pipelineTesting) {
     console.log('  Mode:       Pipeline Testing');
   }
-  if (routerActive) {
-    console.log('  Router:     Enabled');
+
+  // Surface Fable usage: its safety classifiers route cybersecurity tasks to
+  // Opus 4.8, so those phases run on Opus 4.8 regardless of the tier setting.
+  const fableTiers = (
+    [
+      ['small', process.env.ANTHROPIC_SMALL_MODEL],
+      ['medium', process.env.ANTHROPIC_MEDIUM_MODEL],
+      ['large', process.env.ANTHROPIC_LARGE_MODEL],
+    ] as const
+  ).filter(([, model]) => model && /fable/i.test(model));
+  if (fableTiers.length > 0) {
+    const tierList = fableTiers.map(([tier, model]) => `${tier} (${model})`).join(', ');
+    console.log(`  Note:       ${tierList} set to a Fable model. Fable's safety classifiers`);
+    console.log('              route cybersecurity tasks to Opus 4.8, so those phases run on Opus 4.8.');
   }
+
   console.log('');
   console.log('  Monitor:');
   if (workflowId) {

apps/cli/src/commands/uninstall.ts

@@ -1,5 +1,5 @@
 /**
- * `shn uninstall` command — remove ~/.shannon/ after confirmation (npx only).
+ * `npx @keygraph/shannon uninstall` command — remove ~/.shannon/ after confirmation (npx only).
  */
 
 import fs from 'node:fs';

apps/cli/src/config/resolver.ts

@@ -18,12 +18,14 @@ interface ConfigMapping {
   readonly env: string;
   readonly toml: string;
   readonly type: TOMLType;
+  readonly boolFormat?: 'numeric' | 'literal';
 }
 
 /** Maps every supported env var to its TOML path (section.key) and expected type. */
 const CONFIG_MAP: readonly ConfigMapping[] = [
   // Core
   { env: 'CLAUDE_CODE_MAX_OUTPUT_TOKENS', toml: 'core.max_tokens', type: 'number' },
+  { env: 'CLAUDE_ADAPTIVE_THINKING', toml: 'core.adaptive_thinking', type: 'boolean', boolFormat: 'literal' },
 
   // Anthropic
   { env: 'ANTHROPIC_API_KEY', toml: 'anthropic.api_key', type: 'string' },
@@ -44,11 +46,6 @@ const CONFIG_MAP: readonly ConfigMapping[] = [
   { env: 'ANTHROPIC_BASE_URL', toml: 'custom_base_url.base_url', type: 'string' },
   { env: 'ANTHROPIC_AUTH_TOKEN', toml: 'custom_base_url.auth_token', type: 'string' },
 
-  // Router
-  { env: 'ROUTER_DEFAULT', toml: 'router.default', type: 'string' },
-  { env: 'OPENAI_API_KEY', toml: 'router.openai_key', type: 'string' },
-  { env: 'OPENROUTER_API_KEY', toml: 'router.openrouter_key', type: 'string' },
-
   // Model tiers
   { env: 'ANTHROPIC_SMALL_MODEL', toml: 'models.small', type: 'string' },
   { env: 'ANTHROPIC_MEDIUM_MODEL', toml: 'models.medium', type: 'string' },
@@ -61,9 +58,9 @@ type TOMLValue = string | number | boolean;
 type TOMLSection = Record<string, TOMLValue>;
 type TOMLConfig = Record<string, TOMLSection>;
 
-/** Read a nested TOML value by dotted path (e.g. "anthropic.api_key"). */
-function getTomlValue(config: TOMLConfig, path: string): string | undefined {
-  const [section, key] = path.split('.');
+/** Read a nested TOML value for a given mapping. */
+function getTomlValue(config: TOMLConfig, mapping: ConfigMapping): string | undefined {
+  const [section, key] = mapping.toml.split('.');
   if (!section || !key) return undefined;
 
   const sectionObj = config[section];
@@ -72,8 +69,10 @@ function getTomlValue(config: TOMLConfig, path: string): string | undefined {
   const value = sectionObj[key];
   if (value === undefined || value === null) return undefined;
 
-  // NOTE: env.ts checks bedrock/vertex via `=== '1'`, so booleans must map to "1"/"0"
-  if (typeof value === 'boolean') return value ? '1' : '0';
+  if (typeof value === 'boolean') {
+    if (mapping.boolFormat === 'literal') return value ? 'true' : 'false';
+    return value ? '1' : '0';
+  }
 
   return String(value);
 }
@@ -165,20 +164,6 @@ function validateProviderFields(config: TOMLConfig, provider: string, errors: st
       validateModelTiers(config, 'vertex', errors);
       break;
     }
-
-    case 'router': {
-      if (!keys.includes('default')) {
-        errors.push('[router] missing required key: default');
-      }
-      if (!keys.includes('openai_key') && !keys.includes('openrouter_key')) {
-        errors.push('[router] requires either openai_key or openrouter_key');
-      }
-      const models = config.models as Record<string, unknown> | undefined;
-      if (models && typeof models === 'object' && Object.keys(models).length > 0) {
-        errors.push('[models] is not supported with [router]');
-      }
-      break;
-    }
   }
 }
 
@@ -242,7 +227,7 @@ function validateConfig(config: TOMLConfig): string[] {
   }
 
   // 4. Only one provider section allowed (ignore empty sections)
-  const PROVIDER_SECTIONS = ['anthropic', 'custom_base_url', 'bedrock', 'vertex', 'router'] as const;
+  const PROVIDER_SECTIONS = ['anthropic', 'custom_base_url', 'bedrock', 'vertex'] as const;
   const present = PROVIDER_SECTIONS.filter((s) => {
     const section = config[s];
     return section && typeof section === 'object' && Object.keys(section).length > 0;
@@ -285,14 +270,14 @@ export function resolveConfig(): void {
     for (const err of errors) {
       console.error(`  - ${err}`);
     }
-    console.error(`\nRun 'shn setup' to reconfigure.\n`);
+    console.error(`\nRun 'npx @keygraph/shannon setup' to reconfigure.\n`);
     process.exit(1);
   }
 
   for (const mapping of CONFIG_MAP) {
     if (process.env[mapping.env]) continue;
 
-    const value = getTomlValue(toml, mapping.toml);
+    const value = getTomlValue(toml, mapping);
     if (value) {
       process.env[mapping.env] = value;
     }

apps/cli/src/config/writer.ts

@@ -8,12 +8,11 @@ import { getConfigFile } from '../home.js';
 // === Types ===
 
 export interface ShannonConfig {
-  core?: { max_tokens?: number };
+  core?: { max_tokens?: number; adaptive_thinking?: boolean };
   anthropic?: { api_key?: string; oauth_token?: string };
   custom_base_url?: { base_url?: string; auth_token?: string };
   bedrock?: { use?: boolean; region?: string; token?: string };
   vertex?: { use?: boolean; region?: string; project_id?: string; key_path?: string };
-  router?: { default?: string; openai_key?: string; openrouter_key?: string };
   models?: { small?: string; medium?: string; large?: string };
 }
 

apps/cli/src/docker.ts

@@ -7,6 +7,7 @@
 
 import { type ChildProcess, execFileSync, spawn } from 'node:child_process';
 import crypto from 'node:crypto';
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
@@ -69,65 +70,28 @@ export function isTemporalReady(): boolean {
   return output.includes('SERVING');
 }
 
-/** Check if the router container is running and healthy. */
-function isRouterReady(): boolean {
-  const status = runOutput('docker', ['inspect', '--format', '{{.State.Health.Status}}', 'shannon-router']);
-  return status === 'healthy';
-}
-
 /**
- * Ensure Temporal (and optionally router) are running via compose.
- * If Temporal is already up but router is needed and missing, starts router only.
+ * Ensure Temporal is running via compose.
  */
-export async function ensureInfra(useRouter: boolean): Promise<void> {
-  const temporalReady = isTemporalReady();
-  const routerNeeded = useRouter && !isRouterReady();
-
-  if (temporalReady && !routerNeeded) {
+export async function ensureInfra(): Promise<void> {
+  if (isTemporalReady()) {
     return;
   }
 
   const composeFile = getComposeFile();
-  const composeArgs = ['compose', '-f', composeFile];
-  if (useRouter) composeArgs.push('--profile', 'router');
-  composeArgs.push('up', '-d');
+  console.log('Starting Shannon infrastructure...');
+  execFileSync('docker', ['compose', '-f', composeFile, 'up', '-d'], { stdio: 'inherit' });
 
-  if (temporalReady && routerNeeded) {
-    console.log('Starting router...');
-  } else {
-    console.log('Starting Shannon infrastructure...');
-  }
-  execFileSync('docker', composeArgs, { stdio: 'inherit' });
-
-  // Wait for Temporal if it wasn't already running
-  if (!temporalReady) {
-    console.log('Waiting for Temporal to be ready...');
-    for (let i = 0; i < 30; i++) {
-      if (isTemporalReady()) {
-        console.log('Temporal is ready!');
-        break;
-      }
-      if (i === 29) {
-        console.error('Timeout waiting for Temporal');
-        process.exit(1);
-      }
-      await sleep(2000);
+  console.log('Waiting for Temporal to be ready...');
+  for (let i = 0; i < 30; i++) {
+    if (isTemporalReady()) {
+      console.log('Temporal is ready!');
+      return;
     }
+    await sleep(2000);
   }
-
-  // Wait for router if needed
-  if (routerNeeded) {
-    console.log('Waiting for router to be ready...');
-    for (let i = 0; i < 15; i++) {
-      if (isRouterReady()) {
-        console.log('Router is ready!');
-        return;
-      }
-      await sleep(2000);
-    }
-    console.error('Timeout waiting for router');
-    process.exit(1);
-  }
+  console.error('Timeout waiting for Temporal');
+  process.exit(1);
 }
 
 /**
@@ -182,6 +146,87 @@ function addHostFlag(): string[] {
   return [];
 }
 
+/**
+ * Names whose standard IPs aren't covered by `shouldSkipHostsIp`. Loopback names
+ * stay because their IPs (127.x, ::1) get rewritten — not skipped. Others like
+ * `broadcasthost` and `ip6-mcastprefix` are intentionally omitted: their IPs
+ * (255.255.255.255, ff00::/8) are already dropped at the IP filter.
+ */
+const HOSTS_SKIP_NAMES = new Set([
+  'localhost',
+  'ip6-localhost',
+  'ip6-loopback',
+  'ip6-localnet',
+  'host.docker.internal',
+  'gateway.docker.internal',
+  'kubernetes.docker.internal',
+]);
+
+function isLoopbackIp(ip: string): boolean {
+  return ip.startsWith('127.') || ip === '::1';
+}
+
+function shouldSkipHostsIp(ip: string): boolean {
+  if (ip === '0.0.0.0' || ip === '255.255.255.255') return true;
+  // Cloud metadata range — consistent with Shannon's SSRF guard
+  if (ip.startsWith('169.254.')) return true;
+  const lower = ip.toLowerCase();
+  if (lower.startsWith('fe80:') || lower.startsWith('ff')) return true;
+  return false;
+}
+
+function shouldSkipHostsName(name: string, hostname: string): boolean {
+  const lower = name.toLowerCase();
+  if (HOSTS_SKIP_NAMES.has(lower)) return true;
+  if (lower === hostname.toLowerCase()) return true;
+  if (lower.endsWith('.localhost')) return true;
+  return false;
+}
+
+/**
+ * Read the host's /etc/hosts and emit --add-host flags so the worker resolves
+ * user-added entries the same way. Loopback IPs (127.x, ::1) are rewritten to
+ * `host-gateway` so they target the host's loopback instead of the container's.
+ */
+function forwardEtcHostsFlags(): string[] {
+  if (process.env.SHANNON_FORWARD_HOSTS === 'false') return [];
+  if (os.platform() === 'win32') return [];
+
+  let content: string;
+  try {
+    content = fs.readFileSync('/etc/hosts', 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const hostname = os.hostname();
+  const flags: string[] = [];
+
+  for (const rawLine of content.split('\n')) {
+    const hashIdx = rawLine.indexOf('#');
+    const line = (hashIdx >= 0 ? rawLine.slice(0, hashIdx) : rawLine).trim();
+    if (!line) continue;
+
+    const tokens = line
+      .split(' ')
+      .flatMap((t) => t.split('\t'))
+      .filter(Boolean);
+    const ip = tokens[0];
+    const names = tokens.slice(1);
+    if (!ip || names.length === 0) continue;
+    if (shouldSkipHostsIp(ip)) continue;
+
+    const targetIp = isLoopbackIp(ip) ? 'host-gateway' : ip;
+    const formattedIp = targetIp.includes(':') ? `[${targetIp}]` : targetIp;
+    for (const name of names) {
+      if (shouldSkipHostsName(name, hostname)) continue;
+      flags.push('--add-host', `${name}:${formattedIp}`);
+    }
+  }
+
+  return flags;
+}
+
 export interface WorkerOptions {
   version: string;
   url: string;
@@ -194,19 +239,28 @@ export interface WorkerOptions {
   credentials?: string;
   promptsDir?: string;
   outputDir?: string;
-  workspace?: string;
+  workspace: string;
   pipelineTesting?: boolean;
+  debug?: boolean;
 }
 
 /**
  * Spawn the worker container in detached mode and return the process.
+ * When `opts.debug` is true, omits `--rm` so the container persists for log inspection.
  */
 export function spawnWorker(opts: WorkerOptions): ChildProcess {
-  const args = ['run', '-d', '--rm', '--name', opts.containerName, '--network', 'shannon-net'];
+  const args = ['run', '-d'];
+  if (!opts.debug) {
+    args.push('--rm');
+  }
+  args.push('--name', opts.containerName, '--network', 'shannon-net');
 
   // Add host flag for Linux
   args.push(...addHostFlag());
 
+  // Forward user-added /etc/hosts entries into the worker
+  args.push(...forwardEtcHostsFlags());
+
   // UID remapping for Linux bind mounts
   if (os.platform() === 'linux' && process.getuid && process.getgid) {
     args.push('-e', `SHANNON_HOST_UID=${process.getuid()}`, '-e', `SHANNON_HOST_GID=${process.getgid()}`);
@@ -214,7 +268,14 @@ export function spawnWorker(opts: WorkerOptions): ChildProcess {
 
   // Volume mounts
   args.push('-v', `${opts.workspacesDir}:/app/workspaces`);
-  args.push('-v', `${opts.repo.hostPath}:${opts.repo.containerPath}`);
+  args.push('-v', `${opts.repo.hostPath}:${opts.repo.containerPath}:ro`);
+
+  // Writable overlays: shadow .shannon/ and .playwright/ inside the :ro repo with workspace-backed dirs
+  const workspacePath = path.join(opts.workspacesDir, opts.workspace);
+  args.push('-v', `${path.join(workspacePath, 'deliverables')}:${opts.repo.containerPath}/.shannon/deliverables`);
+  args.push('-v', `${path.join(workspacePath, 'scratchpad')}:${opts.repo.containerPath}/.shannon/scratchpad`);
+  args.push('-v', `${path.join(workspacePath, '.playwright-cli')}:${opts.repo.containerPath}/.shannon/.playwright-cli`);
+  args.push('-v', `${path.join(workspacePath, '.playwright')}:${opts.repo.containerPath}/.playwright`);
 
   // Local mode: mount prompts for live editing
   if (opts.promptsDir) {
@@ -253,16 +314,16 @@ export function spawnWorker(opts: WorkerOptions): ChildProcess {
   if (opts.outputDir) {
     args.push('--output', '/app/output');
   }
-  if (opts.workspace) {
-    args.push('--workspace', opts.workspace);
-  }
+  args.push('--workspace', opts.workspace);
   if (opts.pipelineTesting) {
     args.push('--pipeline-testing');
   }
 
-  // Prevent MSYS/Git Bash from converting Unix paths (e.g. /repos/my-repo) to Windows paths
+  // Inherit stderr so `docker run` daemon errors surface to the user;
+  // ignore stdin/stdout (the container ID is noise).
   return spawn('docker', args, {
-    stdio: 'pipe',
+    stdio: ['ignore', 'ignore', 'inherit'],
+    // Prevent MSYS/Git Bash from converting Unix paths on Windows
     ...(os.platform() === 'win32' && { env: { ...process.env, MSYS_NO_PATHCONV: '1' } }),
   });
 }
@@ -284,7 +345,7 @@ export function stopWorkers(): void {
  */
 export function stopInfra(clean: boolean): void {
   const composeFile = getComposeFile();
-  const args = ['compose', '-f', composeFile, '--profile', 'router', 'down'];
+  const args = ['compose', '-f', composeFile, 'down'];
   if (clean) args.push('-v');
   execFileSync('docker', args, { stdio: 'inherit' });
 }

apps/cli/src/env.ts

@@ -14,7 +14,6 @@ const FORWARD_VARS = [
   'ANTHROPIC_API_KEY',
   'ANTHROPIC_BASE_URL',
   'ANTHROPIC_AUTH_TOKEN',
-  'ROUTER_DEFAULT',
   'CLAUDE_CODE_OAUTH_TOKEN',
   'CLAUDE_CODE_USE_BEDROCK',
   'AWS_REGION',
@@ -27,8 +26,7 @@ const FORWARD_VARS = [
   'ANTHROPIC_MEDIUM_MODEL',
   'ANTHROPIC_LARGE_MODEL',
   'CLAUDE_CODE_MAX_OUTPUT_TOKENS',
-  'OPENAI_API_KEY',
-  'OPENROUTER_API_KEY',
+  'CLAUDE_ADAPTIVE_THINKING',
 ] as const;
 
 /**
@@ -64,12 +62,7 @@ export function buildEnvFlags(): string[] {
 interface CredentialValidation {
   valid: boolean;
   error?: string;
-  mode: 'api-key' | 'oauth' | 'custom-base-url' | 'bedrock' | 'vertex' | 'router';
-}
-
-/** Check if router credentials are present in the environment. */
-export function isRouterConfigured(): boolean {
-  return !!(process.env.ROUTER_DEFAULT && (process.env.OPENAI_API_KEY || process.env.OPENROUTER_API_KEY));
+  mode: 'api-key' | 'oauth' | 'custom-base-url' | 'bedrock' | 'vertex';
 }
 
 /** Check if a custom Anthropic-compatible base URL is configured. */
@@ -85,7 +78,6 @@ function detectProviders(): string[] {
   if (isCustomBaseUrlConfigured()) providers.push('Custom Base URL');
   if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') providers.push('AWS Bedrock');
   if (process.env.CLAUDE_CODE_USE_VERTEX === '1') providers.push('Google Vertex');
-  if (isRouterConfigured()) providers.push('Router');
   return providers;
 }
 
@@ -110,8 +102,6 @@ export function validateCredentials(): CredentialValidation {
     return { valid: true, mode: 'oauth' };
   }
   if (isCustomBaseUrlConfigured()) {
-    // Set auth token as API key so the SDK can initialize
-    process.env.ANTHROPIC_API_KEY = process.env.ANTHROPIC_AUTH_TOKEN;
     return { valid: true, mode: 'custom-base-url' };
   }
   if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') {
@@ -153,11 +143,6 @@ export function validateCredentials(): CredentialValidation {
     }
     return { valid: true, mode: 'vertex' };
   }
-  if (isRouterConfigured()) {
-    // Set a placeholder so the worker doesn't reject the missing key
-    process.env.ANTHROPIC_API_KEY = 'router-mode';
-    return { valid: true, mode: 'router' };
-  }
 
   const hint =
     getMode() === 'local'

apps/cli/src/index.ts

@@ -25,6 +25,25 @@ import { displaySplash } from './splash.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+function blockSudo(): void {
+  const isSudo = !!process.env.SUDO_USER;
+  const isRoot = process.geteuid?.() === 0;
+  if (!isSudo && !isRoot) return;
+
+  if (isSudo) {
+    console.error('ERROR: Shannon must not be run with sudo.');
+    console.error('Re-run this command as your normal user.');
+  } else {
+    console.error('ERROR: Shannon must not be run as the root user.');
+    console.error('Switch to a regular user account and re-run this command.');
+  }
+  if (process.platform === 'linux') {
+    console.error('Configure Docker to run without sudo first:');
+    console.error('https://docs.docker.com/engine/install/linux-postinstall');
+  }
+  process.exit(1);
+}
+
 function getVersion(): string {
   try {
     const pkgPath = path.join(__dirname, '..', 'package.json');
@@ -69,7 +88,7 @@ Options for 'start':
   -o, --output <path>       Copy deliverables to this directory after run
   -w, --workspace <name>    Named workspace (auto-resumes if exists)
       --pipeline-testing    Use minimal prompts for fast testing
-      --router              Route requests through claude-code-router
+      --debug               Preserve worker container after exit for log inspection
 
 Examples:
   ${prefix} start -u https://example.com -r ${mode === 'local' ? 'my-repo' : './my-repo'}
@@ -94,7 +113,7 @@ interface ParsedStartArgs {
   workspace?: string;
   output?: string;
   pipelineTesting: boolean;
-  router: boolean;
+  debug: boolean;
 }
 
 function parseStartArgs(argv: string[]): ParsedStartArgs {
@@ -104,7 +123,7 @@ function parseStartArgs(argv: string[]): ParsedStartArgs {
   let workspace: string | undefined;
   let output: string | undefined;
   let pipelineTesting = false;
-  let router = false;
+  let debug = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -149,8 +168,8 @@ function parseStartArgs(argv: string[]): ParsedStartArgs {
       case '--pipeline-testing':
         pipelineTesting = true;
         break;
-      case '--router':
-        router = true;
+      case '--debug':
+        debug = true;
         break;
       default:
         console.error(`Unknown option: ${arg}`);
@@ -169,7 +188,7 @@ function parseStartArgs(argv: string[]): ParsedStartArgs {
     url,
     repo,
     pipelineTesting,
-    router,
+    debug,
     ...(config && { config }),
     ...(workspace && { workspace }),
     ...(output && { output }),
@@ -178,6 +197,8 @@ function parseStartArgs(argv: string[]): ParsedStartArgs {
 
 // === Main Dispatch ===
 
+blockSudo();
+
 const args = process.argv.slice(2);
 const command = args[0];
 

apps/cli/src/paths.ts

@@ -76,12 +76,3 @@ export function resolveConfig(configArg: string): MountPair {
     containerPath: `/app/configs/${basename}`,
   };
 }
-
-/**
- * Ensure the deliverables directory exists and is writable by the container user.
- */
-export function ensureDeliverables(repoHostPath: string): void {
-  const deliverables = path.join(repoHostPath, 'deliverables');
-  fs.mkdirSync(deliverables, { recursive: true });
-  fs.chmodSync(deliverables, 0o777);
-}

apps/worker/configs/config-schema.json

@@ -39,9 +39,33 @@
               "type": "string",
               "pattern": "^[A-Za-z2-7]+=*$",
               "description": "TOTP secret for two-factor authentication (Base32 encoded, case insensitive)"
+            },
+            "email_login": {
+              "type": "object",
+              "description": "Email account credentials for magic-link or OTP follow-through flows",
+              "properties": {
+                "address": {
+                  "type": "string",
+                  "format": "email",
+                  "description": "Email address used to receive magic links or OTPs"
+                },
+                "password": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 255,
+                  "description": "Password for the email account"
+                },
+                "totp_secret": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z2-7]+=*$",
+                  "description": "TOTP secret for the email account's two-factor authentication (Base32 encoded)"
+                }
+              },
+              "required": ["address", "password"],
+              "additionalProperties": false
             }
           },
-          "required": ["username", "password"],
+          "required": ["username"],
           "additionalProperties": false
         },
         "login_flow": {
@@ -118,6 +142,51 @@
       },
       "additionalProperties": false
     },
+    "vuln_classes": {
+      "type": "array",
+      "description": "Vulnerability classes to test. When omitted, all five classes run. When set, only listed classes run; their vuln+exploit agents and report sections are included.",
+      "items": {
+        "type": "string",
+        "enum": ["injection", "xss", "auth", "authz", "ssrf"]
+      },
+      "minItems": 1,
+      "maxItems": 5,
+      "uniqueItems": true
+    },
+    "exploit": {
+      "type": "string",
+      "enum": ["true", "false"],
+      "description": "Whether to run the exploitation phase (default true). Set false to run only analysis."
+    },
+    "report": {
+      "type": "object",
+      "description": "Report filtering and guidance applied by the report agent.",
+      "properties": {
+        "min_severity": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Minimum severity threshold; findings below are dropped by the report agent."
+        },
+        "min_confidence": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "description": "Minimum confidence threshold; findings below are dropped by the report agent."
+        },
+        "guidance": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "description": "Free-text guidance to the report agent (e.g., 'Drop findings about missing security headers')."
+        }
+      },
+      "additionalProperties": false
+    },
+    "rules_of_engagement": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "Free-text instructions to the agent that render into every prompt."
+    },
     "login": {
       "type": "object",
       "description": "Deprecated: Use 'authentication' section instead",
@@ -135,7 +204,11 @@
     { "required": ["authentication"] },
     { "required": ["rules"] },
     { "required": ["authentication", "rules"] },
-    { "required": ["description"] }
+    { "required": ["description"] },
+    { "required": ["vuln_classes"] },
+    { "required": ["exploit"] },
+    { "required": ["report"] },
+    { "required": ["rules_of_engagement"] }
   ],
   "additionalProperties": false,
   "$defs": {
@@ -151,17 +224,17 @@
         },
         "type": {
           "type": "string",
-          "enum": ["path", "subdomain", "domain", "method", "header", "parameter"],
-          "description": "Type of rule (what aspect of requests to match against)"
+          "enum": ["url_path", "subdomain", "domain", "method", "header", "parameter", "code_path"],
+          "description": "Type of rule (what aspect of requests or source code to match against)"
         },
-        "url_path": {
+        "value": {
           "type": "string",
           "minLength": 1,
           "maxLength": 1000,
-          "description": "URL path pattern or value to match"
+          "description": "Value to match"
         }
       },
-      "required": ["description", "type", "url_path"],
+      "required": ["description", "type", "value"],
       "additionalProperties": false
     }
   }

apps/worker/configs/example-config.yaml

@@ -4,6 +4,27 @@
 # Description of the target environment (optional, max 500 chars)
 description: "Next.js e-commerce app on PostgreSQL. Local dev environment — .env files contain local-only credentials, not deployed to production."
 
+# Limit which vulnerability classes run end-to-end (optional, default: all five)
+# vuln_classes: [injection, xss, auth, authz, ssrf]
+
+# Skip the exploitation phase (optional, default: "true")
+# exploit: "false"
+
+# Free-form engagement rules applied to analysis and exploitation agents (optional).
+# Example below is illustrative; edit, remove, or add sections as needed.
+# rules_of_engagement: |
+#   Forbidden techniques:
+#   - No password brute-force or credential stuffing. Cap login attempts at 5 per account.
+#   - ...
+#
+#   Operational:
+#   - Throttle to under 5 requests per second per endpoint. Back off 60 seconds on any 429 response.
+#   - ...
+#
+#   Data handling:
+#   - Do not include actual values in deliverables — use placeholders like [order_id] or [user_email].
+#   - ...
+
 authentication:
   login_type: form  # Options: 'form' or 'sso'
   login_url: "https://example.com/login"
@@ -12,6 +33,12 @@ authentication:
     password: "testpassword"
     totp_secret: "JBSWY3DPEHPK3PXP"  # Optional TOTP secret for 2FA
   
+    # Optional mailbox credentials for magic-link / email-OTP flows.
+    # email_login:
+    #   address: "inbox@example.com"
+    #   password: "mailbox-password"
+    #   totp_secret: "JBSWY3DPEHPK3PXP"
+
   # Natural language instructions for login flow
   login_flow:
     - "Type $username into the email field"
@@ -25,27 +52,55 @@ authentication:
     value: "/dashboard"
 
 rules:
+  # Supported types: url_path, subdomain, domain, method, header, parameter, code_path
   avoid:
     - description: "Do not test the marketing site subdomain"
       type: subdomain
-      url_path: "www"
+      value: "www"
     
     - description: "Skip logout functionality"
-      type: path
-      url_path: "/logout"
+      type: url_path
+      value: "/logout"
     
     - description: "No DELETE operations on user API"
-      type: path
-      url_path: "/api/v1/users/*"
+      type: url_path
+      value: "/api/v1/users/*"
   
+    # code_path values are repo-relative file paths or globs (e.g. "src/auth.ts", "test/**").
+    # - description: "Test fixtures and specs (not production code)"
+    #   type: code_path
+    #   value: "test/**"
+    #
+    # - description: "Generated migrations"
+    #   type: code_path
+    #   value: "db/migrations/**"
+
   focus:
     - description: "Prioritize beta admin panel subdomain"
       type: subdomain
-      url_path: "beta-admin"
+      value: "beta-admin"
 
     - description: "Focus on user profile updates"
-      type: path
-      url_path: "/api/v2/user-profile"
+      type: url_path
+      value: "/api/v2/user-profile"
+
+    # code_path values are repo-relative file paths or globs (e.g. "src/auth.ts", "routes/*.ts").
+    # - description: "Express route handlers"
+    #   type: code_path
+    #   value: "routes/*.ts"
+    #
+    # - description: "Sequelize ORM model definitions"
+    #   type: code_path
+    #   value: "models/*.ts"
+
+# Report filters applied by the report agent when assembling the final report (optional).
+# Example below is illustrative; edit, remove, or add sections as needed.
+# report:
+#   min_severity: low
+#   min_confidence: low
+#   guidance: |
+#     Drop findings about missing security headers and rate-limit gaps.
+#     ...
 
 # Pipeline execution settings (optional)
 # pipeline:

apps/worker/package.json

@@ -3,6 +3,16 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
+  "exports": {
+    "./interfaces": "./dist/interfaces/index.js",
+    "./types": "./dist/types/index.js",
+    "./types/config": "./dist/types/config.js",
+    "./types/agents": "./dist/types/agents.js",
+    "./pipeline": "./dist/temporal/pipeline.js",
+    "./activities": "./dist/temporal/activities.js",
+    "./services": "./dist/services/index.js",
+    "./config": "./dist/config-parser.js"
+  },
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit",
@@ -18,6 +28,7 @@
     "ajv-formats": "^2.1.1",
     "dotenv": "^16.4.5",
     "js-yaml": "^4.1.0",
+    "zod": "^4.3.6",
     "zx": "^8.0.0"
   },
   "devDependencies": {

apps/worker/prompts/exploit-auth.txt

@@ -105,14 +105,16 @@ If you only confirmed a vulnerability without attempting to weaponize it, you ha
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <starting_context>
-- Your **actionable exploitation queue** is located at `deliverables/auth_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
+- Your **actionable exploitation queue** is located at `.shannon/deliverables/auth_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
 
 **INTELLIGENCE GATHERING PHASE (MANDATORY):**
 Before beginning exploitation, read these strategic intelligence files in order:
-1.  `deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and authentication code locations.
-2.  `deliverables/recon_deliverable.md` - Complete API inventory, user roles, and data flow maps.
-3.  `deliverables/auth_analysis_deliverable.md` - Strategic context from the Auth analysis specialist, including notes on session mechanisms, password policies, and flawed logic paths.
+1.  `.shannon/deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and authentication code locations.
+2.  `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, user roles, and data flow maps.
+3.  `.shannon/deliverables/auth_analysis_deliverable.md` - Strategic context from the Auth analysis specialist, including notes on session mechanisms, password policies, and flawed logic paths.
 
 - You will manage your work using the **TodoWrite tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
 </starting_context>
@@ -122,13 +124,13 @@ Before beginning exploitation, read these strategic intelligence files in order:
 
 **Phase Sequence:** VULN ANALYSIS (Complete) → **AUTH EXPLOITATION (You)** → FINAL REPORT (next phase)
 
-**Your Input:** `deliverables/auth_exploitation_queue.json` (primary exploitation queue)
-**Your Output:** `deliverables/auth_exploitation_evidence.md` (exploitation evidence)
+**Your Input:** `.shannon/deliverables/auth_exploitation_queue.json` (primary exploitation queue)
+**Your Output:** `.shannon/deliverables/auth_exploitation_evidence.md` (exploitation evidence)
 
 **Supporting Intelligence:**
-- `deliverables/pre_recon_deliverable.md` (architecture & code context)
-- `deliverables/recon_deliverable.md` (API inventory & user roles)
-- `deliverables/auth_analysis_deliverable.md` (strategic intel)
+- `.shannon/deliverables/pre_recon_deliverable.md` (architecture & code context)
+- `.shannon/deliverables/recon_deliverable.md` (API inventory & user roles)
+- `.shannon/deliverables/auth_analysis_deliverable.md` (strategic intel)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture and attack surfaces
@@ -143,11 +145,6 @@ You are the **Identity Compromise Specialist** - proving tangible impact of brok
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** Essential for interacting with multi-step authentication flows, injecting stolen session cookies, and verifying account takeover in a real browser context. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Task Agent:** Mandatory coder-executor for brute force batches, credential stuffing, token replay automation, and any scripted workflow.
 - **TodoWrite tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
@@ -189,7 +186,7 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
 
 **1. Initialization:**
-- Read `deliverables/auth_exploitation_queue.json`.
+- Read `.shannon/deliverables/auth_exploitation_queue.json`.
 - Use the TodoWrite tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID and the hypothesis to test.
     Example tasks:
@@ -307,92 +304,19 @@ Prioritize these based on the intelligence from your queue and vulnerability ana
 </attack_patterns>
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When your attack plan is fully explored (all checkboxes are marked `[x]`), your mission is complete. You MUST generate two final files.
+<mcp_tools>
+You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/auth_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
-**1. Your Specialist Deliverable**
+**When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
-First, synthesize all evidence into your specialist section and save it using the save-deliverable CLI with --type AUTH_EVIDENCE. This section will be combined with other specialist reports to form the complete security assessment.
+**Status discriminator.** Set `status: "exploited"` only when you've reached Level 3+ with concrete impact evidence (account takeover demonstrated, session hijacked end-to-end, password reset abused, MFA bypassed). Set `status: "blocked"` only for findings that are real vulnerabilities but where external factors — NOT security defenses — prevented full exploitation. See the Classification Decision Framework in this prompt. Do NOT call `add_exploit` for findings classified FALSE POSITIVE; those go in your `workspace/auth_false_positives.md` tracking file, not the deliverable.
 
-**Section Ordering & Format Requirements:**
-- Use the exact vulnerability IDs from `deliverables/auth_exploitation_queue.json`
-- Within "Successfully Exploited" section: Order by severity of impact (most critical first)
-- Within "Confirmed Vulnerabilities (Attempted Exploitation)" section: Order by severity (most critical first)
-- Within "Potential" section: Order by confidence level (highest confidence first)
+**ID alignment.** `vulnerability_id` must match an ID from `.shannon/deliverables/auth_exploitation_queue.json` exactly (e.g. `AUTH-VULN-03`). The collector will reject IDs not in the queue with a list of valid IDs; if you get that error, you either typo'd an ID or imagined one — fix and retry.
 
-**Critical Documentation Requirements:**
+**Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
-**REPRODUCIBILITY IS MANDATORY:**
-- Every exploitation step must be completely self-contained and reproducible
-- Include full URLs with protocol, domain, port, path, and all parameters
-- Provide complete payloads and commands exactly as they should be used
-- Use clear placeholders for variable values like [SESSION_TOKEN], [PASSWORD], [USERNAME]
-- Write as if the reader has never seen the application before
-- Steps must be detailed enough that someone unfamiliar with the application can follow without additional research
-
----
-# Authentication Exploitation Evidence
-
-## Successfully Exploited Vulnerabilities
-
-### AUTH-VULN-01: Session Hijacking via Non-HttpOnly Cookie
-
-**Summary:**
-- **Vulnerable location:** [Authentication mechanism or endpoint affected]
-- **Overview:** [Breif Summary of the exploit itself]
-- **Impact:** [Business/security impact achieved]
-- **Severity:** [Critical/High/Medium/Low based on impact]
-
-**Prerequisites:** (if any)
-[Required setup, tools, or conditions]
-
-**Exploitation Steps:**
-[Each step must be completely reproducible with full details]
-
-1. [Complete action with all necessary information]
-2. [Next action with full details]
-[Continue as needed...]
-
-**Proof of Impact:**
-[Concrete evidence of successful exploitation]
-
-**Notes:** (optional)
-[Any additional relevant information]
-
-### AUTH-VULN-02: [Another Successfully Exploited Vulnerability]
-... (Repeat for each successfully exploited vulnerability) ...
-
-## Potential Vulnerabilities (Validation Blocked)
-
-### AUTH-VULN-03: Suspected Privilege Escalation via Role Manipulation
-
-**Summary:**
-- **Vulnerable location:** [Endpoint or mechanism where vulnerability exists]
-- **Current Blocker:** [What prevents full exploitation]
-- **Potential Impact:** [What could be achieved if blocker removed]
-- **Confidence:** [HIGH/MEDIUM/LOW]
-
-**Evidence of Vulnerability:**
-[Code snippets, responses, or behavior proving vulnerability exists]
-
-**Attempted Exploitation:**
-[What techniques were tried and why they didn't succeed]
-
-**How This Would Be Exploited:**
-[If the blocker were removed, these steps would achieve exploitation]
-
-If [blocker] were bypassed/removed:
-
-1. [Complete action with all necessary details]
-2. [Next action with full information]
-[Continue as needed...]
-
-**Expected Impact:**
-[Specific data or access that would be compromised]
-
----
-
-</deliverable_instructions>
+**Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
+</mcp_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -405,15 +329,9 @@ If [blocker] were bypassed/removed:
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
 	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the TodoWrite tool.
-	2. Deliverable Generation: The required deliverable must be successfully saved using the save-deliverable CLI:
-	  - **CHUNKED WRITING (MANDATORY):**
-	    1. Use the **Write** tool to create `deliverables/auth_exploitation_evidence.md` with the title and first major section
-	    2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-	    3. Repeat step 2 for all remaining sections
-	    4. Run `save-deliverable` with `--type AUTH_EVIDENCE --file-path "deliverables/auth_exploitation_evidence.md"`
-	    **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
+	2. Evidence Emission: Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/auth_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/auth_false_positives.md`, not via `add_exploit`.
 
-CRITICAL WARNING: Announcing completion before every item in deliverables/auth_exploitation_queue.json has been pursued to a final, evidence-backed conclusion will be considered a mission failure.
+CRITICAL WARNING: Announcing completion before every item in .shannon/deliverables/auth_exploitation_queue.json has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure.
 
 ONLY AFTER fulfilling these exhaustive requirements, announce "AUTH EXPLOITATION COMPLETE" and stop.
 

apps/worker/prompts/exploit-authz.txt

@@ -88,18 +88,22 @@ After exhaustive bypass attempts, determine:
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <starting_context>
-- Your **actionable exploitation queue** is located at `deliverables/authz_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
+- Your **actionable exploitation queue** is located at `.shannon/deliverables/authz_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
 
 **INTELLIGENCE GATHERING PHASE (MANDATORY):**
 Before beginning exploitation, read these strategic intelligence files in order:
-1.  `deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and authorization code locations.
-2.  `deliverables/recon_deliverable.md` - Complete API inventory, user roles, and permission models.
-3.  `deliverables/authz_analysis_deliverable.md` - Strategic context from the Authz analysis specialist, including notes on access control patterns, role hierarchies, and flawed logic paths.
+1.  `.shannon/deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and authorization code locations.
+2.  `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, user roles, and permission models.
+3.  `.shannon/deliverables/authz_analysis_deliverable.md` - Strategic context from the Authz analysis specialist, including notes on access control patterns, role hierarchies, and flawed logic paths.
 
 - You will manage your work using the **TodoWrite tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
 </starting_context>
@@ -109,13 +113,13 @@ Before beginning exploitation, read these strategic intelligence files in order:
 
 **Phase Sequence:** VULN ANALYSIS (Complete) → **AUTHZ EXPLOITATION (You)** → FINAL REPORT (next phase)
 
-**Your Input:** `deliverables/authz_exploitation_queue.json` (primary exploitation queue)
-**Your Output:** `deliverables/authz_exploitation_evidence.md` (exploitation evidence)
+**Your Input:** `.shannon/deliverables/authz_exploitation_queue.json` (primary exploitation queue)
+**Your Output:** `.shannon/deliverables/authz_exploitation_evidence.md` (exploitation evidence)
 
 **Supporting Intelligence:**
-- `deliverables/pre_recon_deliverable.md` (architecture & code context)
-- `deliverables/recon_deliverable.md` (API inventory & user roles)
-- `deliverables/authz_analysis_deliverable.md` (strategic intel)
+- `.shannon/deliverables/pre_recon_deliverable.md` (architecture & code context)
+- `.shannon/deliverables/recon_deliverable.md` (API inventory & user roles)
+- `.shannon/deliverables/authz_analysis_deliverable.md` (strategic intel)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture and attack surfaces
@@ -130,11 +134,6 @@ You are the **Privilege Escalation Specialist** - proving tangible impact of bro
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** Essential for interacting with complex authorization flows, testing role-based access controls in browser contexts, and verifying privilege escalation through UI elements. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Task Agent:** Mandatory coder-executor for IDOR sweeps, role escalation loops, and workflow bypass automation.
 - **TodoWrite tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
@@ -176,7 +175,7 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
 
 **1. Initialization:**
-- Read `deliverables/authz_exploitation_queue.json`.
+- Read `.shannon/deliverables/authz_exploitation_queue.json`.
 - Use the TodoWrite tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID, type, and the hypothesis to test.
     Example tasks:
@@ -313,88 +312,19 @@ Remember: The most effective attacks often come from understanding the specific
 </attack_patterns>
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When your attack plan is fully explored (all checkboxes are marked `[x]`), your mission is complete. You MUST generate two final files.
+<mcp_tools>
+You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/authz_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
-**1. Your Specialist Deliverable**
+**When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
-First, synthesize all evidence into your specialist section and save it using the save-deliverable CLI with --type AUTHZ_EVIDENCE. This section will be combined with other specialist reports to form the complete security assessment and MUST use the following structure:
+**Status discriminator.** Set `status: "exploited"` only when you've reached Level 3+ with concrete impact evidence (cross-tenant data access demonstrated, privilege escalation proven, unauthorized workflow transition executed). Set `status: "blocked"` only for findings that are real vulnerabilities but where external factors — NOT security defenses — prevented full exploitation. See the Classification Decision Framework in this prompt. Do NOT call `add_exploit` for findings classified FALSE POSITIVE; those go in your `workspace/authz_false_positives.md` tracking file, not the deliverable.
 
-**Section Ordering & Format Requirements:**
-- Use the exact vulnerability IDs from `deliverables/authz_exploitation_queue.json`
-- Within "Successfully Exploited" section: Order by severity of impact (most critical first)
-- Within "Potential" section: Order by confidence level (highest confidence first)
+**ID alignment.** `vulnerability_id` must match an ID from `.shannon/deliverables/authz_exploitation_queue.json` exactly (e.g. `AUTHZ-VULN-03`). The collector will reject IDs not in the queue with a list of valid IDs; if you get that error, you either typo'd an ID or imagined one — fix and retry.
 
-**Critical Documentation Requirements:**
+**Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
-**REPRODUCIBILITY IS MANDATORY:**
-- Every exploitation step must be completely self-contained and reproducible
-- Include full URLs with protocol, domain, port, path, and all parameters
-- Provide complete payloads and commands exactly as they should be used
-- Use clear placeholders for variable values like [SESSION_TOKEN], [USER_ID], [ROLE]
-- Write as if the reader has never seen the application before
-- Steps must be detailed enough that someone unfamiliar with the application can follow without additional research
-
----
-# Authorization Exploitation Evidence
-
-## Successfully Exploited Vulnerabilities
-
-### AUTHZ-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Endpoint or mechanism where vulnerability exists]
-- **Overview:** [Breif Summary of the exploit itself]
-- **Impact:** [Business/security impact achieved]
-- **Severity:** [Critical/High/Medium/Low based on impact]
-
-**Prerequisites:** (if any)
-[Required setup, tools, or conditions]
-
-**Exploitation Steps:**
-[Each step must be completely reproducible with full details]
-
-1. [Complete action with all necessary information]
-2. [Next action with full details]
-[Continue as needed...]
-
-**Proof of Impact:**
-[Concrete evidence of successful exploitation]
-
-**Notes:** (optional)
-[Any additional relevant information]
-
-## Potential Vulnerabilities (Validation Blocked)
-
-### AUTHZ-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Endpoint or mechanism where vulnerability exists]
-- **Current Blocker:** [What prevents full exploitation]
-- **Potential Impact:** [What could be achieved if blocker removed]
-- **Confidence:** [HIGH/MEDIUM/LOW]
-
-**Evidence of Vulnerability:**
-[Code snippets, responses, or behavior proving vulnerability exists]
-
-**Attempted Exploitation:**
-[What techniques were tried and why they didn't succeed]
-
-**How This Would Be Exploited:**
-[If the blocker were removed, these steps would achieve exploitation]
-
-If [blocker] were bypassed/removed:
-
-1. [Complete action with all necessary details]
-2. [Next action with full information]
-[Continue as needed...]
-
-**Expected Impact:**
-[Specific data or access that would be compromised]
-
----
-
-</deliverable_instructions>
+**Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
+</mcp_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -407,15 +337,9 @@ If [blocker] were bypassed/removed:
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
 	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the TodoWrite tool.
-	2. Deliverable Generation: The required deliverable must be successfully saved using the save-deliverable CLI:
-	  - **CHUNKED WRITING (MANDATORY):**
-	    1. Use the **Write** tool to create `deliverables/authz_exploitation_evidence.md` with the title and first major section
-	    2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-	    3. Repeat step 2 for all remaining sections
-	    4. Run `save-deliverable` with `--type AUTHZ_EVIDENCE --file-path "deliverables/authz_exploitation_evidence.md"`
-	    **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
+	2. Evidence Emission: Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/authz_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/authz_false_positives.md`, not via `add_exploit`.
 
-CRITICAL WARNING: Announcing completion before every item in deliverables/authz_exploitation_queue.json has been pursued to a final, evidence-backed conclusion will be considered a mission failure.
+CRITICAL WARNING: Announcing completion before every item in .shannon/deliverables/authz_exploitation_queue.json has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure.
 
 ONLY AFTER fulfilling these exhaustive requirements, announce "AUTHZ EXPLOITATION COMPLETE" and stop.
 

apps/worker/prompts/exploit-injection.txt

@@ -65,18 +65,22 @@ Remember: An unproven vulnerability is worse than no finding at all - it wastes
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <starting_context>
-- Your **actionable exploitation queue** is located at `deliverables/injection_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
+- Your **actionable exploitation queue** is located at `.shannon/deliverables/injection_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
 
 **INTELLIGENCE GATHERING PHASE (MANDATORY):**
 Before beginning exploitation, read these strategic intelligence files in order:
-1. `deliverables/pre_recon_deliverable.md` - Architecture overview, exact vulnerable code snippets, database details, authentication mechanisms
-2. `deliverables/recon_deliverable.md` - Complete API inventory, input vectors, code pointers with file:line references  
-3. `deliverables/injection_analysis_deliverable.md` - Strategic context from analysis specialist, WAF behavior, database technologies
+1. `.shannon/deliverables/pre_recon_deliverable.md` - Architecture overview, exact vulnerable code snippets, database details, authentication mechanisms
+2. `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, input vectors, code pointers with file:line references
+3. `.shannon/deliverables/injection_analysis_deliverable.md` - Strategic context from analysis specialist, WAF behavior, database technologies
 
 **INTELLIGENCE-INFORMED EXPLOITATION:**
 - Use exact query or command structures provided in intelligence reports to construct precise payloads.
@@ -91,13 +95,13 @@ Before beginning exploitation, read these strategic intelligence files in order:
 
 **Phase Sequence:** VULN ANALYSIS (Complete) → **INJECTION EXPLOITATION (You)** → FINAL REPORT (next phase)
 
-**Your Input:** `deliverables/injection_exploitation_queue.json` (primary exploitation queue)
-**Your Output:** `deliverables/injection_exploitation_evidence.md` (exploitation evidence)
+**Your Input:** `.shannon/deliverables/injection_exploitation_queue.json` (primary exploitation queue)
+**Your Output:** `.shannon/deliverables/injection_exploitation_evidence.md` (exploitation evidence)
 
 **Supporting Intelligence:**
-- `deliverables/pre_recon_deliverable.md` (architecture & code context)  
-- `deliverables/recon_deliverable.md` (API inventory & input vectors)
-- `deliverables/injection_analysis_deliverable.md` (strategic intel)
+- `.shannon/deliverables/pre_recon_deliverable.md` (architecture & code context)
+- `.shannon/deliverables/recon_deliverable.md` (API inventory & input vectors)
+- `.shannon/deliverables/injection_analysis_deliverable.md` (strategic intel)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture and attack surfaces
@@ -112,11 +116,6 @@ You are the **Proof-of-Impact Generator** - converting theoretical injection fla
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** For testing injection vulnerabilities through browser interactions when needed. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Task Agent:** Mandatory coder-executor for any custom scripting beyond single ad-hoc commands.
 - **TodoWrite tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
@@ -139,7 +138,7 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
 
 **1. Initialization:**
-- Read the `deliverables/injection_exploitation_queue.json` file.
+- Read the `.shannon/deliverables/injection_exploitation_queue.json` file.
 - Use the TodoWrite tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID and the hypothesis to test.
     Example tasks:
@@ -180,17 +179,16 @@ For each root vulnerability in your plan, you will follow this systematic, four-
 ## **Strategic Tool Usage**
 Use the right tool for the job to ensure thoroughness.
 - **Use `curl` (Manual Probing) for:** Initial confirmation, simple UNION/Error-based injections, and crafting specific WAF bypasses.
-- **Use `sqlmap` (Automation) for:** Time-consuming blind injections, automating enumeration **after** manual confirmation, and as a final step to try a wide range of payloads when manual techniques are failing.
 
 ## **Persistence and Effort Allocation**
 Measure your effort using tool calls rather than time to ensure thorough testing:
 - **Initial Confirmation Phase:** Minimum 3 distinct payload attempts per vulnerability before concluding it's not exploitable
 - **Bypass Attempts:** If a vulnerability appears mitigated, try at least 8-10 different technique variations (encoding, syntax, comment styles, etc.) before concluding it's properly defended  
-- **Escalation Trigger:** If manual testing exceeds 10-12 tool calls without progress on a single vulnerability, escalate to automated tools (`sqlmap`) or Task Agent scripting
+- **Escalation Trigger:** If manual testing exceeds 10-12 tool calls without progress on a single vulnerability, escalate to Task Agent scripting
 - **Termination Criteria:** After systematic attempts with multiple different techniques → classify as appropriate level
   
 ## **Using the Task Agent for Custom Scripting**
-You must delegate every injection automation task to the Task Agent. Use manual `curl` or `sqlmap` runs for spot checks, then escalate to scripted payload loops handled by the Task Agent.
+You must delegate every injection automation task to the Task Agent. Use manual `curl` runs for spot checks, then escalate to scripted payload loops handled by the Task Agent.
 
 **TEMPLATE FOR SCRIPTING TASKS (REQUIRED):**
 "
@@ -337,91 +335,19 @@ Prioritize your techniques based on the intelligence from the analysis deliverab
 
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When your attack plan is fully explored (all checkboxes are marked `[x]`), your mission is complete. You MUST generate two final files. Follow these instructions precisely to structure your output.
+<mcp_tools>
+You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/injection_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
-**1. Your Specialist Deliverable**
+**When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
-First, synthesize all of your evidence into your specialist section and save it using the save-deliverable CLI with --type INJECTION_EVIDENCE. This section will be combined with other specialist reports to form the complete security assessment.
+**Status discriminator.** Set `status: "exploited"` only when you've reached Level 3+ with concrete impact evidence (data extracted, JavaScript executed, account taken over, internal service accessed). Set `status: "blocked"` only for findings that are real vulnerabilities but where external factors — NOT security defenses — prevented full exploitation. See the Classification Decision Framework in this prompt. Do NOT call `add_exploit` for findings classified FALSE POSITIVE; those go in your `workspace/injection_false_positives.md` tracking file, not the deliverable.
 
-Your section MUST use the following structure precisely:
+**ID alignment.** `vulnerability_id` must match an ID from `.shannon/deliverables/injection_exploitation_queue.json` exactly (e.g. `INJ-VULN-03`). The collector will reject IDs not in the queue with a list of valid IDs; if you get that error, you either typo'd an ID or imagined one — fix and retry.
 
-**Section Ordering & Format Requirements:**
-- Use the exact vulnerability IDs from `deliverables/injection_exploitation_queue.json`
-- Within "Successfully Exploited" section: Order by severity of impact (most critical first)
-- Within "Potential" section: Order by confidence level (highest confidence first)
+**Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
-**Critical Documentation Requirements:**
-
-**REPRODUCIBILITY IS MANDATORY:**
-- Every exploitation step must be completely self-contained and reproducible
-- Include full URLs with protocol, domain, port, path, and all parameters
-- Provide complete payloads and commands exactly as they should be used
-- Use clear placeholders for variable values like [SESSION_TOKEN], [DATABASE_NAME], [TABLE_NAME]
-- Write as if the reader has never seen the application before
-- Steps must be detailed enough that someone unfamiliar with the application can follow without additional research
-
----
-# Injection Exploitation Evidence
-
-## Successfully Exploited Vulnerabilities
-
-### INJ-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Endpoint or mechanism where vulnerability exists]
-- **Overview:** [Breif Summary of the exploit itself]
-- **Impact:** [Business/security impact achieved]
-- **Severity:** [Critical/High/Medium/Low based on impact]
-
-**Prerequisites:** (if any)
-[Required setup, tools, or conditions]
-
-**Exploitation Steps:**
-[Each step must be completely reproducible with full details]
-
-1. [Complete action with all necessary information]
-2. [Next action with full details]
-[Continue as needed...]
-
-**Proof of Impact:**
-[Concrete evidence of successful exploitation]
-
-**Notes:** (optional)
-[Any additional relevant information]
-
-## Potential Vulnerabilities (Validation Blocked)
-
-### INJ-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Endpoint or mechanism where vulnerability exists]
-- **Current Blocker:** [What prevents full exploitation]
-- **Potential Impact:** [What could be achieved if blocker removed]
-- **Confidence:** [HIGH/MEDIUM/LOW]
-
-**Evidence of Vulnerability:**
-[Code snippets, responses, or behavior proving vulnerability exists]
-
-**Attempted Exploitation:**
-[What techniques were tried and why they didn't succeed]
-
-**How This Would Be Exploited:**
-[If the blocker were removed, these steps would achieve exploitation]
-
-If [blocker] were bypassed/removed:
-
-1. [Complete action with all necessary details]
-2. [Next action with full information]
-[Continue as needed...]
-
-**Expected Impact:**
-[Specific data or access that would be compromised]
-
----
-
-
-</deliverable_instructions>
+**Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
+</mcp_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -434,15 +360,9 @@ If [blocker] were bypassed/removed:
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
 1.  **Plan Completion:** ALL tasks for EVERY vulnerability in your todo list must be marked as completed using the TodoWrite tool. **No vulnerability or task can be left unaddressed.**
-2.  **Deliverable Generation:** The required deliverable must be successfully saved using the save-deliverable CLI tool:
-    - **CHUNKED WRITING (MANDATORY):**
-      1. Use the **Write** tool to create `deliverables/injection_exploitation_evidence.md` with the title and first major section
-      2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-      3. Repeat step 2 for all remaining sections
-      4. Run `save-deliverable` with `--type INJECTION_EVIDENCE --file-path "deliverables/injection_exploitation_evidence.md"`
-      **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
+2.  **Evidence Emission:** Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/injection_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/injection_false_positives.md`, not via `add_exploit`.
 
-**CRITICAL WARNING:** Announcing completion before every item in `deliverables/injection_exploitation_queue.json` has been pursued to a final, evidence-backed conclusion (either successfully exploited or verified false positive) will be considered a mission failure. Superficial testing is not acceptable.
+**CRITICAL WARNING:** Announcing completion before every item in `.shannon/deliverables/injection_exploitation_queue.json` has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure. Superficial testing is not acceptable.
 
 ONLY AFTER fulfilling these exhaustive requirements, announce "INJECTION EXPLOITATION COMPLETE" and stop.
 

apps/worker/prompts/exploit-ssrf.txt

@@ -88,18 +88,22 @@ After exhaustive bypass attempts, determine:
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <starting_context>
-- Your **actionable exploitation queue** is located at `deliverables/ssrf_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
+- Your **actionable exploitation queue** is located at `.shannon/deliverables/ssrf_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
 
 **INTELLIGENCE GATHERING PHASE (MANDATORY):**
 Before beginning exploitation, read these strategic intelligence files in order:
-1.  `deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and network service details.
-2.  `deliverables/recon_deliverable.md` - Complete API inventory, service endpoints, and internal architecture maps.
-3.  `deliverables/ssrf_analysis_deliverable.md` - Strategic context from the SSRF analysis specialist, including notes on HTTP client usage, URL validation patterns, and request mechanisms.
+1.  `.shannon/deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and network service details.
+2.  `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, service endpoints, and internal architecture maps.
+3.  `.shannon/deliverables/ssrf_analysis_deliverable.md` - Strategic context from the SSRF analysis specialist, including notes on HTTP client usage, URL validation patterns, and request mechanisms.
 
 - You will manage your work using the **TodoWrite tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
 </starting_context>
@@ -109,13 +113,13 @@ Before beginning exploitation, read these strategic intelligence files in order:
 
 **Phase Sequence:** VULN ANALYSIS (Complete) → **SSRF EXPLOITATION (You)** → FINAL REPORT (next phase)
 
-**Your Input:** `deliverables/ssrf_exploitation_queue.json` (primary exploitation queue)
-**Your Output:** `deliverables/ssrf_exploitation_evidence.md` (exploitation evidence)
+**Your Input:** `.shannon/deliverables/ssrf_exploitation_queue.json` (primary exploitation queue)
+**Your Output:** `.shannon/deliverables/ssrf_exploitation_evidence.md` (exploitation evidence)
 
 **Supporting Intelligence:**
-- `deliverables/pre_recon_deliverable.md` (architecture & network context)
-- `deliverables/recon_deliverable.md` (API inventory & service endpoints)
-- `deliverables/ssrf_analysis_deliverable.md` (strategic intel)
+- `.shannon/deliverables/pre_recon_deliverable.md` (architecture & network context)
+- `.shannon/deliverables/recon_deliverable.md` (API inventory & service endpoints)
+- `.shannon/deliverables/ssrf_analysis_deliverable.md` (strategic intel)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture and attack surfaces
@@ -129,11 +133,6 @@ You are the **Network Boundary Breaker** - proving tangible impact of SSRF vulne
 </system_architecture>
 
 <cli_tools>
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** Useful for complex multi-step SSRF exploitation that requires browser context or JavaScript execution. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
 - **Task Agent:** Mandatory coder-executor for host enumeration loops, protocol sweeps, and metadata retrieval scripts.
@@ -176,7 +175,7 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
 
 **1. Initialization:**
-- Read `deliverables/ssrf_exploitation_queue.json`.
+- Read `.shannon/deliverables/ssrf_exploitation_queue.json`.
 - Use the TodoWrite tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID and the hypothesis to test.
     Example tasks:
@@ -390,88 +389,19 @@ A successful SSRF doesn't always mean data is immediately exfiltrated. Validatio
 </attack_patterns>
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When your attack plan is fully explored (all checkboxes are marked `[x]`), your mission is complete. You MUST generate two final files.
+<mcp_tools>
+You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/ssrf_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
-**1. Your Specialist Deliverable**
+**When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
-First, synthesize all evidence into your specialist section and save it using the save-deliverable CLI with --type SSRF_EVIDENCE. This section will be combined with other specialist reports to form the complete security assessment and MUST use the following structure:
+**Status discriminator.** Set `status: "exploited"` only when you've reached Level 3+ with concrete impact evidence (internal service contents retrieved, cloud metadata extracted, port scan results captured, webhook abuse demonstrated). Set `status: "blocked"` only for findings that are real vulnerabilities but where external factors — NOT security defenses — prevented full exploitation. See the Classification Decision Framework in this prompt. Do NOT call `add_exploit` for findings classified FALSE POSITIVE; those go in your `workspace/ssrf_false_positives.md` tracking file, not the deliverable.
 
-**Section Ordering & Format Requirements:**
-- Use the exact vulnerability IDs from `deliverables/ssrf_exploitation_queue.json`
-- Within "Successfully Exploited" section: Order by severity of impact (most critical first)
-- Within "Potential" section: Order by confidence level (highest confidence first)
+**ID alignment.** `vulnerability_id` must match an ID from `.shannon/deliverables/ssrf_exploitation_queue.json` exactly (e.g. `SSRF-VULN-03`). The collector will reject IDs not in the queue with a list of valid IDs; if you get that error, you either typo'd an ID or imagined one — fix and retry.
 
-**Critical Documentation Requirements:**
+**Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
-**REPRODUCIBILITY IS MANDATORY:**
-- Every exploitation step must be completely self-contained and reproducible
-- Include full URLs with protocol, domain, port, path, and all parameters
-- Provide complete payloads and commands exactly as they should be used
-- Use clear placeholders for variable values like [SESSION_TOKEN], [INTERNAL_IP], [PORT]
-- Write as if the reader has never seen the application before
-- Steps must be detailed enough that someone unfamiliar with the application can follow without additional research
-
----
-# SSRF Exploitation Evidence
-
-## Successfully Exploited Vulnerabilities
-
-### SSRF-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Endpoint or mechanism where vulnerability exists]
-- **Impact:** [Business/security impact achieved]
-- **Severity:** [Critical/High/Medium/Low based on impact]
-
-**Prerequisites:** (if any)
-[Required setup, tools, or conditions]
-
-**Exploitation Steps:**
-[Each step must be completely reproducible with full details]
-
-1. [Complete action with all necessary information]
-2. [Next action with full details]
-[Continue as needed...]
-
-**Proof of Impact:**
-[Concrete evidence of successful exploitation]
-
-**Notes:** (optional)
-[Any additional relevant information]
-
-## Potential Vulnerabilities (Validation Blocked)
-
-### SSRF-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Endpoint or mechanism where vulnerability exists]
-- **Overview:** [Breif Summary of the exploit itself]
-- **Current Blocker:** [What prevents full exploitation]
-- **Potential Impact:** [What could be achieved if blocker removed]
-- **Confidence:** [HIGH/MEDIUM/LOW]
-
-**Evidence of Vulnerability:**
-[Code snippets, responses, or behavior proving vulnerability exists]
-
-**Attempted Exploitation:**
-[What techniques were tried and why they didn't succeed]
-
-**How This Would Be Exploited:**
-[If the blocker were removed, these steps would achieve exploitation]
-
-If [blocker] were bypassed/removed:
-
-1. [Complete action with all necessary details]
-2. [Next action with full information]
-[Continue as needed...]
-
-**Expected Impact:**
-[Specific data or access that would be compromised]
-
----
-
-</deliverable_instructions>
+**Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
+</mcp_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -484,15 +414,9 @@ If [blocker] were bypassed/removed:
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
 	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the TodoWrite tool.
-	2. Deliverable Generation: The required deliverable must be successfully saved using the save-deliverable CLI:
-	  - **CHUNKED WRITING (MANDATORY):**
-	    1. Use the **Write** tool to create `deliverables/ssrf_exploitation_evidence.md` with the title and first major section
-	    2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-	    3. Repeat step 2 for all remaining sections
-	    4. Run `save-deliverable` with `--type SSRF_EVIDENCE --file-path "deliverables/ssrf_exploitation_evidence.md"`
-	    **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
+	2. Evidence Emission: Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/ssrf_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/ssrf_false_positives.md`, not via `add_exploit`.
 
-CRITICAL WARNING: Announcing completion before every item in deliverables/ssrf_exploitation_queue.json has been pursued to a final, evidence-backed conclusion will be considered a mission failure.
+CRITICAL WARNING: Announcing completion before every item in .shannon/deliverables/ssrf_exploitation_queue.json has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure.
 
 ONLY AFTER fulfilling these exhaustive requirements, announce "SSRF EXPLOITATION COMPLETE" and stop.
 

apps/worker/prompts/exploit-xss.txt

@@ -86,18 +86,22 @@ After exhaustive bypass attempts, determine:
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <starting_context>
-- Your **actionable exploitation queue** is located at `deliverables/xss_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
+- Your **actionable exploitation queue** is located at `.shannon/deliverables/xss_exploitation_queue.json`. This is your to-do list, containing the precise targets identified by the analysis phase. You MUST process every vulnerability in this queue.
 
 **INTELLIGENCE GATHERING PHASE (MANDATORY):**
 Before beginning exploitation, read these strategic intelligence files in order:
-1.  `deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and critical file paths.
-2.  `deliverables/recon_deliverable.md` - Complete API inventory, input vectors, and data flow maps.
-3.  `deliverables/xss_analysis_deliverable.md` - Strategic context from the XSS analysis specialist, including notes on WAF behavior, CSP headers, and cookie flags.
+1.  `.shannon/deliverables/pre_recon_deliverable.md` - Architecture overview, technology stack, and critical file paths.
+2.  `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, input vectors, and data flow maps.
+3.  `.shannon/deliverables/xss_analysis_deliverable.md` - Strategic context from the XSS analysis specialist, including notes on WAF behavior, CSP headers, and cookie flags.
 
 **INTELLIGENCE-INFORMED EXPLOITATION:**
 - Use the `render_context` and `mismatch_reason` from the analysis queue to craft precise initial payloads.
@@ -111,13 +115,13 @@ Before beginning exploitation, read these strategic intelligence files in order:
 
 **Phase Sequence:** VULN ANALYSIS (Complete) → **XSS EXPLOITATION (You)** → FINAL REPORT (next phase)
 
-**Your Input:** `deliverables/xss_exploitation_queue.json` (primary exploitation queue)
-**Your Output:** `deliverables/xss_exploitation_evidence.md` (exploitation evidence)
+**Your Input:** `.shannon/deliverables/xss_exploitation_queue.json` (primary exploitation queue)
+**Your Output:** `.shannon/deliverables/xss_exploitation_evidence.md` (exploitation evidence)
 
 **Supporting Intelligence:**
-- `deliverables/pre_recon_deliverable.md` (architecture & code context)
-- `deliverables/recon_deliverable.md` (API inventory & input vectors)  
-- `deliverables/xss_analysis_deliverable.md` (strategic intel)
+- `.shannon/deliverables/pre_recon_deliverable.md` (architecture & code context)
+- `.shannon/deliverables/recon_deliverable.md` (API inventory & input vectors)
+- `.shannon/deliverables/xss_analysis_deliverable.md` (strategic intel)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture and attack surfaces
@@ -132,11 +136,6 @@ You are the **Client-Side Impact Demonstrator** - converting theoretical XSS fla
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** Your primary tool for testing DOM-based and Stored XSS, confirming script execution in a real browser context, and interacting with the application post-exploitation. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Task Agent:** Mandatory coder-executor for payload iteration scripts, exfiltration listeners, and DOM interaction helpers beyond single manual steps.
 - **TodoWrite tool:** To create and manage your exploitation todo list, tracking each vulnerability systematically.
@@ -183,7 +182,7 @@ For **every single vulnerability** in your queue, systematically work through th
 **Goal:** Set up tracking and understand the pre-analyzed vulnerabilities.
 
 **Actions:**
-- Read `deliverables/xss_exploitation_queue.json` to get your targets with their complete graph analysis
+- Read `.shannon/deliverables/xss_exploitation_queue.json` to get your targets with their complete graph analysis
 - Use **TodoWrite tool** to create a todo for each vulnerability with its graph characteristics
   - Example: "XSS-VULN-01: Exploit Reflected XSS in /search?q= (source: URL param → no sanitization → innerHTML sink)"
 - Study the provided intelligence for each vulnerability:
@@ -323,95 +322,19 @@ POTENTIAL (Report in separate subsection):
 
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When all todos in your list are marked as completed, your mission is complete. You MUST generate two final files.
+<mcp_tools>
+You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/xss_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
-1. Your Specialist Deliverable  
-First, synthesize all of your evidence into your specialist section and save it using the save-deliverable CLI with --type XSS_EVIDENCE. This section will be combined with other specialist reports to form the complete security assessment.  
-Your section MUST use the following structure precisely:
+**When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
-**Section Ordering & Format Requirements:**
-- Use the exact vulnerability IDs from `deliverables/xss_exploitation_queue.json`
-- Within "Successfully Exploited" section: Order by severity of impact (most critical first)
-- Within "Potential" section: Order by confidence level (highest confidence first)
+**Status discriminator.** Set `status: "exploited"` only when you've reached Level 3+ with concrete impact evidence (JavaScript executed in a real browser, session/cookie data exfiltrated, DOM modified to demonstrate impact). Set `status: "blocked"` only for findings that are real vulnerabilities but where external factors — NOT security defenses — prevented full exploitation. See the Classification Decision Framework in this prompt. Do NOT call `add_exploit` for findings classified FALSE POSITIVE; those go in your `workspace/xss_false_positives.md` tracking file, not the deliverable.
 
-**Critical Documentation Requirements:**
+**ID alignment.** `vulnerability_id` must match an ID from `.shannon/deliverables/xss_exploitation_queue.json` exactly (e.g. `XSS-VULN-03`). The collector will reject IDs not in the queue with a list of valid IDs; if you get that error, you either typo'd an ID or imagined one — fix and retry.
 
-**REPRODUCIBILITY IS MANDATORY:**
-- Every exploitation step must be completely self-contained and reproducible
-- Include full URLs with protocol, domain, port, path, and all parameters
-- Provide complete payloads and commands exactly as they should be used
-- Use clear placeholders for variable values like [SESSION_TOKEN], [TARGET_USER_ID]
-- Write as if the reader has never seen the application before
-- Steps must be detailed enough that someone unfamiliar with the application can follow without additional research
+**Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
-**General Requirements:**
-- Focus on business impact and complete reproducibility
-- Write for a security-aware but non-specialist audience
-- Prioritize clarity and actionability over technical depth
-
----
-
-# Cross-Site Scripting (XSS) Exploitation Evidence
-
-## Successfully Exploited Vulnerabilities
-
-### XSS-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Full URL with vulnerable parameter, etc.]
-- **Overview:** [Breif Summary of the exploit itself]
-- **Impact:** [Business impact - what attacker gains]
-- **Severity:** [Critical/High/Medium based on impact]
-
-**Prerequisites:** (if any)
-[Required tools, access level, application state, etc.]
-
-**Exploitation Steps:**
-[Each step must be completely reproducible - include exact URLs, full payloads, and copy-paste ready commands]
-
-1. [First action with all details needed to reproduce]
-2. [Next action with complete information]
-[Continue as needed...]
-
-**Proof of Impact:**
-[Actual data extracted or actions performed, with evidence]
-
-**Notes:** (if any)
-[Special conditions, troubleshooting tips, or other relevant information]
-
-## Potential Vulnerabilities (Validation Blocked)
-
-### XSS-VULN-[ID]: [Vulnerability Title]
-
-**Summary:**
-- **Vulnerable location:** [Full URL with vulnerable parameter, etc.]
-- **Current Blocker:** [What prevents exploitation]
-- **Potential Impact:** [What could happen if exploited]
-- **Confidence:** [HIGH/MEDIUM/LOW]
-
-**Why We Believe This Is Vulnerable:**
-[Brief explanation with code snippet or observed behavior]
-
-**What We Tried:**
-[List of attempts and why they were blocked]
-
-**How This Would Be Exploited:**
-[If the blocker were removed, these exact steps would achieve exploitation. Include complete details as if writing instructions for someone who has never seen the application.]
-
-If [blocker] were bypassed/removed:
-
-1. [Complete action with all necessary details]
-2. [Next action with full information]
-[Continue as needed...]
-
-**Expected Impact:**
-[Specific data or access that would be compromised]
-
-
----
-
-</deliverable_instructions>
+**Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
+</mcp_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -424,17 +347,11 @@ If [blocker] were bypassed/removed:
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
 - Todo List Completion: ALL vulnerabilities from the exploitation queue must have been processed and marked as completed in your todo list.
-- Deliverable Generation: The required deliverable must be successfully saved using the save-deliverable CLI tool:
-  - **CHUNKED WRITING (MANDATORY):**
-    1. Use the **Write** tool to create `deliverables/xss_exploitation_evidence.md` with the title and first major section
-    2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-    3. Repeat step 2 for all remaining sections
-    4. Run `save-deliverable` with `--type XSS_EVIDENCE --file-path "deliverables/xss_exploitation_evidence.md"`
-    **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
+- Evidence Emission: Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/xss_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/xss_false_positives.md`, not via `add_exploit`.
 
-**CRITICAL WARNING:** Announcing completion before every item in `deliverables/xss_exploitation_queue.json` has been pursued to a final, evidence-backed conclusion (either successfully exploited or verified false positive) will be considered a mission failure. Superficial testing is not acceptable.
+**CRITICAL WARNING:** Announcing completion before every item in `.shannon/deliverables/xss_exploitation_queue.json` has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure. Superficial testing is not acceptable.
 
-ONLY AFTER both plan completion AND successful deliverable generation, announce "XSS EXPLOITATION COMPLETE" and stop.
+ONLY AFTER both plan completion AND evidence emission, announce "XSS EXPLOITATION COMPLETE" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/pipeline-testing/exploit-auth.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 ## 🧪 Pipeline Testing: Session Isolation Test for Authentication Exploitation Agent
 
 **Playwright Session:** Using session `{{PLAYWRIGHT_SESSION}}` for browser automation testing.
@@ -10,7 +12,7 @@
 
 2. Take a screenshot to prove isolation:
    ```
-   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "auth-exploit-test.png"
+   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "{{REPO_PATH}}/.shannon/scratchpad/auth-exploit-test.png"
    ```
 
 3. Log the test results:
@@ -24,7 +26,7 @@ Run the save-deliverable CLI:
 save-deliverable --type AUTH_EVIDENCE --content '# Authentication Exploitation Evidence (Pipeline Test)\n\n**Playwright Session:** {{PLAYWRIGHT_SESSION}}\n**Test Site:** https://example.com\n**Screenshot:** auth-exploit-test.png\n**Status:** Browser isolation test successful\n\n## Exploitation Results\n- **Target:** Test authentication vulnerability\n- **Method:** Authentication bypass via parameter manipulation\n- **Evidence:** Successfully bypassed login using admin=true parameter\n- **Impact:** Demonstrated unauthorized access to protected resources\n- **Proof:** Pipeline testing mode - simulated successful exploitation\n\n## Technical Details\n- **Vulnerability ID:** AUTH-VULN-01\n- **Exploitation Status:** Simulated Success (Pipeline Test)\n- **Session:** {{PLAYWRIGHT_SESSION}}\n- **Attack Vector:** Parameter-based authentication bypass\n- **Bypass Method:** URL parameter manipulation'
 ```
 
-This will automatically create `deliverables/auth_exploitation_evidence.md`.
+This will automatically create `.shannon/deliverables/auth_exploitation_evidence.md`.
 
 ### Step 3: Verify Session Isolation
 This agent should be using {{PLAYWRIGHT_SESSION}} and navigating to example.com independently of other parallel exploitation agents.

apps/worker/prompts/pipeline-testing/exploit-authz.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 ## 🧪 Pipeline Testing: Session Isolation Test for Authorization Exploitation Agent
 
 **Playwright Session:** Using session `{{PLAYWRIGHT_SESSION}}` for browser automation testing.
@@ -10,7 +12,7 @@
 
 2. Take a screenshot to prove isolation:
    ```
-   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "authz-exploit-test.png"
+   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "{{REPO_PATH}}/.shannon/scratchpad/authz-exploit-test.png"
    ```
 
 3. Log the test results:
@@ -24,7 +26,7 @@ Run the save-deliverable CLI:
 save-deliverable --type AUTHZ_EVIDENCE --content '# Authorization Exploitation Evidence (Pipeline Test)\n\n**Playwright Session:** {{PLAYWRIGHT_SESSION}}\n**Test Site:** https://example.com\n**Screenshot:** authz-exploit-test.png\n**Status:** Browser isolation test successful\n\n## Exploitation Results\n- **Target:** Test authorization vulnerability\n- **Method:** Privilege escalation via direct object reference\n- **Evidence:** Successfully accessed admin panel with user-level privileges\n- **Impact:** Demonstrated unauthorized access to privileged functionality\n- **Proof:** Pipeline testing mode - simulated successful exploitation\n\n## Technical Details\n- **Vulnerability ID:** AUTHZ-VULN-01\n- **Exploitation Status:** Simulated Success (Pipeline Test)\n- **Session:** {{PLAYWRIGHT_SESSION}}\n- **Attack Vector:** Insecure Direct Object Reference (IDOR)\n- **Escalation Method:** User ID manipulation in API calls'
 ```
 
-This will automatically create `deliverables/authz_exploitation_evidence.md`.
+This will automatically create `.shannon/deliverables/authz_exploitation_evidence.md`.
 
 ### Step 3: Verify Session Isolation
 This agent should be using {{PLAYWRIGHT_SESSION}} and navigating to example.com independently of other parallel exploitation agents.

apps/worker/prompts/pipeline-testing/exploit-injection.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 ## 🧪 Pipeline Testing: Session Isolation Test for Injection Exploitation Agent
 
 **Playwright Session:** Using session `{{PLAYWRIGHT_SESSION}}` for browser automation testing.
@@ -10,7 +12,7 @@
 
 2. Take a screenshot to prove isolation:
    ```
-   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "injection-exploit-test.png"
+   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "{{REPO_PATH}}/.shannon/scratchpad/injection-exploit-test.png"
    ```
 
 3. Log the test results:
@@ -24,7 +26,7 @@ Run the save-deliverable CLI:
 save-deliverable --type INJECTION_EVIDENCE --content '# Injection Exploitation Evidence (Pipeline Test)\n\n**Playwright Session:** {{PLAYWRIGHT_SESSION}}\n**Test Site:** https://example.com\n**Screenshot:** injection-exploit-test.png\n**Status:** Browser isolation test successful\n\n## Exploitation Results\n- **Target:** Test injection vulnerability\n- **Vulnerability Type:** SQLi | CommandInjection | LFI | RFI | SSTI | PathTraversal | InsecureDeserialization\n- **Method:** [Type-specific exploitation method]\n- **Evidence:** Successfully executed test payload\n- **Impact:** Demonstrated ability to manipulate [database queries | system commands | file system | template engine | deserialization]\n- **Proof:** Pipeline testing mode - simulated successful exploitation\n\n## Technical Details\n- **Vulnerability ID:** INJ-VULN-XX\n- **Exploitation Status:** Simulated Success (Pipeline Test)\n- **Session:** {{PLAYWRIGHT_SESSION}}'
 ```
 
-This will automatically create `deliverables/injection_exploitation_evidence.md`.
+This will automatically create `.shannon/deliverables/injection_exploitation_evidence.md`.
 
 ### Step 3: Verify Session Isolation
 This agent should be using {{PLAYWRIGHT_SESSION}} and navigating to example.com independently of other parallel exploitation agents.

apps/worker/prompts/pipeline-testing/exploit-ssrf.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 ## 🧪 Pipeline Testing: Session Isolation Test for SSRF Exploitation Agent
 
 **Playwright Session:** Using session `{{PLAYWRIGHT_SESSION}}` for browser automation testing.
@@ -10,7 +12,7 @@
 
 2. Take a screenshot to prove isolation:
    ```
-   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "ssrf-exploit-test.png"
+   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "{{REPO_PATH}}/.shannon/scratchpad/ssrf-exploit-test.png"
    ```
 
 3. Log the test results:
@@ -24,7 +26,7 @@ Run the save-deliverable CLI:
 save-deliverable --type SSRF_EVIDENCE --content '# SSRF Exploitation Evidence (Pipeline Test)\n\n**Playwright Session:** {{PLAYWRIGHT_SESSION}}\n**Test Site:** https://example.com\n**Screenshot:** ssrf-exploit-test.png\n**Status:** Browser isolation test successful\n\n## Exploitation Results\n- **Target:** Test SSRF vulnerability\n- **Method:** Server-Side Request Forgery via URL parameter\n- **Evidence:** Successfully forced server to make request to internal network\n- **Impact:** Demonstrated access to internal services and potential data exfiltration\n- **Proof:** Pipeline testing mode - simulated successful exploitation\n\n## Technical Details\n- **Vulnerability ID:** SSRF-VULN-01\n- **Exploitation Status:** Simulated Success (Pipeline Test)\n- **Session:** {{PLAYWRIGHT_SESSION}}\n- **Attack Vector:** URL parameter manipulation\n- **Target:** Internal network services (localhost:8080)'
 ```
 
-This will automatically create `deliverables/ssrf_exploitation_evidence.md`.
+This will automatically create `.shannon/deliverables/ssrf_exploitation_evidence.md`.
 
 ### Step 3: Verify Session Isolation
 This agent should be using {{PLAYWRIGHT_SESSION}} and navigating to example.com independently of other parallel exploitation agents.

apps/worker/prompts/pipeline-testing/exploit-xss.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 ## 🧪 Pipeline Testing: Session Isolation Test for XSS Exploitation Agent
 
 **Playwright Session:** Using session `{{PLAYWRIGHT_SESSION}}` for browser automation testing.
@@ -10,7 +12,7 @@
 
 2. Take a screenshot to prove isolation:
    ```
-   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "xss-exploit-test.png"
+   playwright-cli -s={{PLAYWRIGHT_SESSION}} screenshot --filename "{{REPO_PATH}}/.shannon/scratchpad/xss-exploit-test.png"
    ```
 
 3. Log the test results:
@@ -24,7 +26,7 @@ Run the save-deliverable CLI:
 save-deliverable --type XSS_EVIDENCE --content '# XSS Exploitation Evidence (Pipeline Test)\n\n**Playwright Session:** {{PLAYWRIGHT_SESSION}}\n**Test Site:** https://example.com\n**Screenshot:** xss-exploit-test.png\n**Status:** Browser isolation test successful\n\n## Exploitation Results\n- **Target:** Test XSS vulnerability\n- **Method:** Reflected XSS via search parameter\n- **Evidence:** Successfully executed payload `<script>alert('\''XSS'\'')</script>`\n- **Impact:** Demonstrated JavaScript code execution in user context\n- **Proof:** Pipeline testing mode - simulated successful exploitation\n\n## Technical Details\n- **Vulnerability ID:** XSS-VULN-01\n- **Exploitation Status:** Simulated Success (Pipeline Test)\n- **Session:** {{PLAYWRIGHT_SESSION}}\n- **Attack Vector:** Reflected XSS in search functionality'
 ```
 
-This will automatically create `deliverables/xss_exploitation_evidence.md`.
+This will automatically create `.shannon/deliverables/xss_exploitation_evidence.md`.
 
 ### Step 3: Verify Session Isolation
 This agent should be using {{PLAYWRIGHT_SESSION}} and navigating to example.com independently of other parallel exploitation agents.

apps/worker/prompts/pipeline-testing/pre-recon-code.txt

@@ -1 +1,3 @@
+@include(shared/_filesystem.txt)
+
 Run: `save-deliverable --type CODE_ANALYSIS --content 'Pre-recon analysis complete'`. Then say "Done".

apps/worker/prompts/pipeline-testing/recon.txt

@@ -1 +1,3 @@
+@include(shared/_filesystem.txt)
+
 Run: `save-deliverable --type RECON --content 'Reconnaissance analysis complete'`. Then say "Done".

apps/worker/prompts/pipeline-testing/report-executive.txt

@@ -1 +1,3 @@
-Read `deliverables/comprehensive_security_assessment_report.md`, prepend "# Security Assessment Report\n\n**Target:** {{WEB_URL}}\n\n" to the content, and save it back. Say "Done".
+@include(shared/_filesystem.txt)
+
+Read `.shannon/deliverables/comprehensive_security_assessment_report.md`, prepend "# Security Assessment Report\n\n**Target:** {{WEB_URL}}\n\n" to the content, and save it back. Say "Done".

apps/worker/prompts/pipeline-testing/shared/_filesystem.txt

@@ -0,0 +1,4 @@
+Filesystem:
+- {{REPO_PATH}}/ (read only)
+- {{REPO_PATH}}/.shannon/deliverables/ (read-write)
+- {{REPO_PATH}}/.shannon/scratchpad/ (read-write) - screenshots, scripts, scratch work, etc.

apps/worker/prompts/pipeline-testing/validate-authentication.txt

@@ -0,0 +1,4 @@
+Write a stub authenticated session via Bash so the preflight's saved-state check passes:
+  echo '{"cookies":[{"name":"stub","value":"x","domain":"example.com","path":"/"}],"origins":[]}' > {{AUTH_STATE_FILE}}
+
+Then return the structured verdict `{ "login_success": true }` and stop.

apps/worker/prompts/pipeline-testing/vuln-auth.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 Please complete these tasks using your CLI tools:
 
 1. Navigate to https://example.net and take a screenshot:
@@ -8,5 +10,4 @@ Please complete these tasks using your CLI tools:
 2. Save an analysis deliverable:
    - Run: `save-deliverable --type AUTH_ANALYSIS --content '# Auth Analysis Report\n\nAnalysis complete. No authentication vulnerabilities identified.'`
 
-3. Save a queue deliverable:
-   - Run: `save-deliverable --type AUTH_QUEUE --content '{"vulnerabilities": []}'`
+As a final step, return an empty array for vulnerabilities.

apps/worker/prompts/pipeline-testing/vuln-authz.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 Please complete these tasks using your CLI tools:
 
 1. Navigate to https://jsonplaceholder.typicode.com and take a screenshot:
@@ -8,5 +10,4 @@ Please complete these tasks using your CLI tools:
 2. Save an analysis deliverable:
    - Run: `save-deliverable --type AUTHZ_ANALYSIS --content '# Authorization Analysis Report\n\nAnalysis complete. No authorization vulnerabilities identified.'`
 
-3. Save a queue deliverable:
-   - Run: `save-deliverable --type AUTHZ_QUEUE --content '{"vulnerabilities": []}'`
+As a final step, return an empty array for vulnerabilities.

apps/worker/prompts/pipeline-testing/vuln-injection.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 Please complete these tasks using your CLI tools:
 
 1. Navigate to https://example.com and take a screenshot:
@@ -8,5 +10,4 @@ Please complete these tasks using your CLI tools:
 2. Save an analysis deliverable:
    - Run: `save-deliverable --type INJECTION_ANALYSIS --content '# Injection Analysis Report\n\nAnalysis complete. No injection vulnerabilities identified.'`
 
-3. Save a queue deliverable:
-   - Run: `save-deliverable --type INJECTION_QUEUE --content '{"vulnerabilities": []}'`
+As a final step, return an empty array for vulnerabilities.

apps/worker/prompts/pipeline-testing/vuln-ssrf.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 Please complete these tasks using your CLI tools:
 
 1. Navigate to https://httpbin.org and take a screenshot:
@@ -8,5 +10,4 @@ Please complete these tasks using your CLI tools:
 2. Save an analysis deliverable:
    - Run: `save-deliverable --type SSRF_ANALYSIS --content '# SSRF Analysis Report\n\nAnalysis complete. No SSRF vulnerabilities identified.'`
 
-3. Save a queue deliverable:
-   - Run: `save-deliverable --type SSRF_QUEUE --content '{"vulnerabilities": []}'`
+As a final step, return an empty array for vulnerabilities.

apps/worker/prompts/pipeline-testing/vuln-xss.txt

@@ -1,3 +1,5 @@
+@include(shared/_filesystem.txt)
+
 Please complete these tasks using your CLI tools:
 
 1. Navigate to https://example.org and take a screenshot:
@@ -8,5 +10,4 @@ Please complete these tasks using your CLI tools:
 2. Save an analysis deliverable:
    - Run: `save-deliverable --type XSS_ANALYSIS --content '# XSS Analysis Report\n\nAnalysis complete. No XSS vulnerabilities identified.'`
 
-3. Save a queue deliverable:
-   - Run: `save-deliverable --type XSS_QUEUE --content '{"vulnerabilities": []}'`
+As a final step, return an empty array for vulnerabilities.

apps/worker/prompts/pre-recon-code.txt

@@ -10,15 +10,18 @@ Objective: Your task is to analyze the provided source code to generate a securi
 
 **WORKING CONTEXT:** You are currently in the root directory of the target codebase to analyze.
 
+Filesystem:
+- {{REPO_PATH}}/ (read only)
+- {{REPO_PATH}}/.shannon/deliverables/ (read-write)
+- {{REPO_PATH}}/.shannon/scratchpad/ (read-write) - screenshots, scripts, scratch work, etc.
+
 **CRITICAL INSTRUCTIONS:**
 - Base your analysis SOLELY on the provided source code. Do not invent services or infer functionality that is not present.
-- The output MUST be in Markdown format.
 - **ANALYSIS DEPTH:** Provide thorough, actionable security analysis for penetration testers. Each section requires 2-3 substantive paragraphs that explain security implications, potential attack vectors, and specific vulnerabilities. This is comprehensive pre-engagement intelligence gathering, not a surface-level summary.
 - Focus on SECURITY IMPLICATIONS and ACTIONABLE FINDINGS rather than just component listings
 - Identify trust boundaries, privilege escalation paths, and data flow security concerns
 - Include specific examples from the code when discussing security concerns
-- At the end of your report, you MUST include a section listing all the critical file paths mentioned in your analysis.
-- **MANDATORY:** You MUST save your complete analysis report using the `save-deliverable` CLI tool with --type CODE_ANALYSIS.
+- **MANDATORY:** You MUST emit your complete analysis by calling all seven `set_*` MCP tools listed in `<mcp_tools>` before terminating. The host renders the deliverable Markdown from those calls.
 
 **GIT AWARENESS:**
 Read `.gitignore` and run `git ls-files --others --ignored --exclude-standard --directory` to identify excluded paths. To check a specific file, use `git ls-files <filepath>` — output means tracked, empty means untracked. Only flag tracked files as vulnerabilities. Untracked files relevant to security (e.g., secrets, credentials, sensitive configs) may be noted as informational.
@@ -26,13 +29,21 @@ Read `.gitignore` and run `git ls-files --others --ignored --exclude-standard --
 
 {{DESCRIPTION}}
 
+<scope>
+Downstream vulnerability analysis will cover these classes: {{VULN_CLASSES_TESTED}}.
+</scope>
+
+@include(shared/_code-path-rules.txt)
+
+@include(shared/_rules-of-engagement.txt)
+
 <system_architecture>
 **PENTESTING WORKFLOW - YOUR POSITION:**
 
 **Phase Sequence:** **PRE-RECON (You)** → RECON → VULN ANALYSIS (5 agents) → EXPLOITATION (5 agents) → REPORTING
 
-**Your Input:** External scan results from pre-recon tools (nmap, subfinder, whatweb)
-**Your Output:** `deliverables/code_analysis_deliverable.md` (feeds all subsequent analysis phases)
+**Your Input:** Target application source code in the working directory
+**Your Output:** `.shannon/deliverables/pre_recon_deliverable.md` (feeds all subsequent analysis phases)
 **Shared Intelligence:** You create the foundational intelligence baseline that all other agents depend on
 
 **WHAT HAPPENED BEFORE YOU:**
@@ -66,7 +77,6 @@ You are the **Code Intelligence Gatherer** and **Architectural Foundation Builde
 
 <starting_context>
 - You are the **ENTRY POINT** of the comprehensive security assessment - no prior deliverables exist to read
-- External reconnaissance tools have completed and their results are available in the working environment
 - The target application source code has been cloned and is ready for analysis in the current directory
 - You must create the **foundational intelligence baseline** that all subsequent agents depend on
 - **CRITICAL:** This is the ONLY agent with full source code access - your completeness determines whether vulnerabilities are found
@@ -83,11 +93,6 @@ You are the **Code Intelligence Gatherer** and **Architectural Foundation Builde
 **Available Tools:**
 - **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authentication mechanisms, map attack surfaces, and understand architectural patterns. MANDATORY for all source code analysis.
 - **TodoWrite Tool:** Use this to create and manage your analysis task list. Create todo items for each phase and agent that needs execution. Mark items as "in_progress" when working on them and "completed" when done.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 </cli_tools>
 
@@ -126,17 +131,11 @@ After Phase 1 completes, launch all three vulnerability-focused agents in parall
 
 - Combine all agent outputs intelligently
 - Resolve conflicts and eliminate duplicates
-- Generate the final structured markdown report
 - **Schema Management**: Using schemas identified by the Entry Point Mapper Agent:
-  - Create the `outputs/schemas/` directory using mkdir -p
-  - Copy all discovered schema files to `outputs/schemas/` with descriptive names
+  - Create the `.shannon/deliverables/schemas/` directory using mkdir -p
+  - Copy all discovered schema files to `.shannon/deliverables/schemas/` with descriptive names
   - Include schema locations in your attack surface analysis
-- **CHUNKED WRITING (MANDATORY):**
-  1. Use the **Write** tool to create `deliverables/code_analysis_deliverable.md` with the title and first major section
-  2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-  3. Repeat step 2 for all remaining sections
-  4. Run `save-deliverable` with `--type CODE_ANALYSIS --file-path "deliverables/code_analysis_deliverable.md"`
-- **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
+- **Emit findings via MCP tools:** Call every tool listed in `<mcp_tools>` exactly once. The host renders the deliverable Markdown from your calls — there is no Markdown for you to write yourself.
 
 **EXECUTION PATTERN:**
 1. **Use TodoWrite to create task list** tracking: Phase 1 agents, Phase 2 agents, and report synthesis
@@ -161,229 +160,38 @@ After Phase 1 completes, launch all three vulnerability-focused agents in parall
 **CRITICAL RULE:** Do NOT use Read, Glob, or Grep tools for source code analysis. All code examination must be delegated to Task agents.
 </task_agent_strategy>
 
-Please structure your report using the exact following Markdown headings:
-
----
-
-# Penetration Test Scope & Boundaries
-
+<scope_boundaries>
 **Primary Directive:** Your analysis is strictly limited to the **network-accessible attack surface** of the application. All subsequent tasks must adhere to this scope. Before reporting any finding (e.g., an entry point, a vulnerability sink), you must first verify it meets the "In-Scope" criteria.
 
-### In-Scope: Network-Reachable Components
-A component is considered **in-scope** if its execution can be initiated, directly or indirectly, by a network request that the deployed application server is capable of receiving. This includes:
+**In-Scope: Network-Reachable Components.** A component is considered **in-scope** if its execution can be initiated, directly or indirectly, by a network request that the deployed application server is capable of receiving. This includes:
 - Publicly exposed web pages and API endpoints.
 - Endpoints requiring authentication via the application's standard login mechanisms.
 - Any developer utility, debug console, or script that has been mistakenly exposed through a route or is otherwise callable from other in-scope, network-reachable code.
 
-### Out-of-Scope: Locally Executable Only
-A component is **out-of-scope** if it **cannot** be invoked through the running application's network interface and requires an execution context completely external to the application's request-response cycle. This includes tools that must be run via:
+**Out-of-Scope: Locally Executable Only.** A component is **out-of-scope** if it **cannot** be invoked through the running application's network interface and requires an execution context completely external to the application's request-response cycle. This includes tools that must be run via:
 - A command-line interface (e.g., `go run ./cmd/...`, `python scripts/...`).
 - A development environment's internal tooling (e.g., a "run script" button in an IDE).
 - CI/CD pipeline scripts or build tools (e.g., Dagger build definitions).
 - Database migration scripts, backup tools, or maintenance utilities.
 - Local development servers, test harnesses, or debugging utilities.
 - Static files or scripts that require manual opening in a browser (not served by the application).
+</scope_boundaries>
 
----
-  ## 1. Executive Summary
-  Provide a 2-3 paragraph overview of the application's security posture, highlighting the most critical attack surfaces and architectural security decisions.
+<mcp_tools>
+**Emit your findings exclusively via the `pre-recon-collector` MCP tools.** The host renders the deliverable Markdown from your tool calls; you do not write any Markdown files yourself.
 
-  ## 2. Architecture & Technology Stack
-  **TASK AGENT COORDINATION:** Use findings from the **Architecture Scanner Agent** (Phase 1) to populate this section.
+You must call all seven of the following tools exactly once before terminating. Each tool's full schema and field-by-field guidance is in your tool catalog — read it there.
 
-  - **Framework & Language:** [Details with security implications]
-  - **Architectural Pattern:** [Pattern with trust boundary analysis]
-  - **Critical Security Components:** [Focus on auth, authz, data protection]
+- `set_executive_summary` — application's overall security posture (Section 1).
+- `set_application_intelligence` — composite of architecture, data security, attack surface, and infrastructure (Sections 2, 4, 5, 6).
+- `set_auth_deep_dive` — authentication & authorization deep dive (Section 3).
+- `set_codebase_indexing` — directory structure narrative (Section 7).
+- `set_critical_file_paths` — categorized catalog of critical file paths (Section 8).
+- `set_xss_sinks` — XSS sinks grouped by render context (Section 9). Set `applicable: false` only if the application has no web frontend at all.
+- `set_ssrf_sinks` — SSRF sinks grouped by sink category (Section 10). Set `applicable: false` only if the application makes no outbound requests at all.
 
-  ## 3. Authentication & Authorization Deep Dive
-  **TASK AGENT COORDINATION:** Use findings from the **Security Pattern Hunter Agent** (Phase 1) to populate this section.
-
-  Provide detailed analysis of:
-  - Authentication mechanisms and their security properties. **Your analysis MUST include an exhaustive list of all API endpoints used for authentication (e.g., login, logout, token refresh, password reset).**
-  - Session management and token security **Pinpoint the exact file and line(s) of code where session cookie flags (`HttpOnly`, `Secure`, `SameSite`) are configured.**
-  - Authorization model and potential bypass scenarios
-  - Multi-tenancy security implementation
-  - **SSO/OAuth/OIDC Flows (if applicable): Identify the callback endpoints and locate the specific code that validates the `state` and `nonce` parameters.**
-
-  ## 4. Data Security & Storage
-  **TASK AGENT COORDINATION:** Use findings from the **Data Security Auditor Agent** (Phase 2, if databases detected) to populate this section.
-
-  - **Database Security:** Analyze encryption, access controls, query safety
-  - **Data Flow Security:** Identify sensitive data paths and protection mechanisms
-  - **Multi-tenant Data Isolation:** Assess tenant separation effectiveness
-
-  ## 5. Attack Surface Analysis
-  **TASK AGENT COORDINATION:** Use findings from the **Entry Point Mapper Agent** (Phase 1) and **Architecture Scanner Agent** (Phase 1) to populate this section.
-
-  **Instructions:**
-  1. Coordinate with the Entry Point Mapper Agent to identify all potential application entry points.
-  2. For each potential entry point, apply the "Master Scope Definition." Determine if it is network-reachable in a deployed environment or a local-only developer tool.
-  3. Your report must only list entry points confirmed to be **in-scope**.
-  4. (Optional) Create a separate section listing notable **out-of-scope** components and a brief justification for their exclusion (e.g., "Component X is a CLI tool for database migrations and is not network-accessible.").
-
-  - **External Entry Points:** Detailed analysis of each public interface that is network-accessible
-  - **Internal Service Communication:** Trust relationships and security assumptions between network-reachable services
-  - **Input Validation Patterns:** How user input is handled and validated in network-accessible endpoints
-  - **Background Processing:** Async job security and privilege models for jobs triggered by network requests
-
-  ## 6. Infrastructure & Operational Security
-  - **Secrets Management:** How secrets are stored, rotated, and accessed
-  - **Configuration Security:** Environment separation and secret handling **Specifically search for infrastructure configuration (e.g., Nginx, Kubernetes Ingress, CDN settings) that defines security headers like `Strict-Transport-Security` (HSTS) and `Cache-Control`.**
-  - **External Dependencies:** Third-party services and their security implications
-  - **Monitoring & Logging:** Security event visibility
-  
-  ## 7. Overall Codebase Indexing
-  - Provide a detailed, multi-sentence paragraph describing the codebase's directory structure, organization, and any significant tools or 
-    conventions used (e.g., build orchestration, code generation, testing frameworks). Focus on how this structure impacts discoverability of security-relevant components.
-    
-   ## 8. Critical File Paths
-		- List all the specific file paths referenced in the analysis above in a simple bulleted list. This list is for the next agent to use as a starting point.
-	  - List all the specific file paths referenced in your analysis, categorized by their security relevance. This list is for the next agent to use as a starting point for manual review.
-	  - **Configuration:** [e.g., `config/server.yaml`, `Dockerfile`, `docker-compose.yml`]
-	  - **Authentication & Authorization:** [e.g., `auth/jwt_middleware.go`, `internal/user/permissions.go`, `config/initializers/session_store.rb`, `src/services/oauth_callback.js`]
-	  - **API & Routing:** [e.g., `cmd/api/main.go`, `internal/handlers/user_routes.go`, `ts/graphql/schema.graphql`]
-	  - **Data Models & DB Interaction:** [e.g., `db/migrations/001_initial.sql`, `internal/models/user.go`, `internal/repository/sql_queries.go`]
-	  - **Dependency Manifests:** [e.g., `go.mod`, `package.json`, `requirements.txt`]
-	  - **Sensitive Data & Secrets Handling:** [e.g., `internal/utils/encryption.go`, `internal/secrets/manager.go`]
-	  - **Middleware & Input Validation:** [e.g., `internal/middleware/validator.go`, `internal/handlers/input_parsers.go`]
-	  - **Logging & Monitoring:** [e.g., `internal/logging/logger.go`, `config/monitoring.yaml`]
-	  - **Infrastructure & Deployment:** [e.g., `infra/pulumi/main.go`, `kubernetes/deploy.yaml`, `nginx.conf`, `gateway-ingress.yaml`]  
-	 
-	 ## 9. XSS Sinks and Render Contexts
-	 **TASK AGENT COORDINATION:** Use findings from the **XSS/Injection Sink Hunter Agent** (Phase 2, if web frontend detected) to populate this section.
-
-	 **Network Surface Focus:** Only report XSS sinks that are on web app pages or publicly facing components. Exclude sinks in non-network surface pages such as local-only scripts, build tools, developer utilities, or components that require manual file opening.
-
-	 Your output MUST include sufficient information to find the exact location found, such as filepaths with line numbers, or specific references for a downstream agent to find the location exactly.
-	 - **XSS Sink:** A function or property within a web application that renders user-controllable data on a page
-	 - **Render Context:** The specific location within the page's structure (e.g., inside an HTML tag, an attribute, or a script) where data is placed, which dictates the type of sanitization required to prevent XSS.
-	 - HTML Body Context
-				- element.innerHTML
-				- element.outerHTML
-				- document.write()
-				- document.writeln()
-				- element.insertAdjacentHTML()
-				- Range.createContextualFragment()
-				- jQuery Sinks: add(), after(), append(), before(), html(), prepend(), replaceWith(), wrap()
-				-  HTML Attribute Context
-		- Event Handlers: onclick, onerror, onmouseover, onload, onfocus, etc.
-				- URL-based Attributes: href, src, formaction, action, background, data
-				- Style Attribute: style
-				- Iframe Content: srcdoc
-				- General Attributes: value, id, class, name, alt, etc. (when quotes are escaped)
-		- JavaScript Context
-				- eval()
-				- Function() constructor
-				- setTimeout() (with string argument)
-				- setInterval() (with string argument)
-				- Directly writing user data into a <script> tag
-		- CSS Context
-				- element.style properties (e.g., element.style.backgroundImage)
-				- Directly writing user data into a <style> tag
-		-  URL Context
-				- location / window.location
-				- location.href
-				- location.replace()
-				- location.assign()
-				- window.open()
-				- history.pushState()
-				- history.replaceState()
-				- URL.createObjectURL()
-				- jQuery Selector (older versions): $(userInput)
-
-  ## 10. SSRF Sinks
-  **TASK AGENT COORDINATION:** Use findings from the **SSRF/External Request Tracer Agent** (Phase 2, if outbound requests detected) to populate this section.
-
-  **Network Surface Focus:** Only report SSRF sinks that are in web app pages or publicly facing components. Exclude sinks in non-network surface components such as local-only utilities, build scripts, developer tools, or CLI applications.
-
-  Your output MUST include sufficient information to find the exact location found, such as filepaths with line numbers, or specific references for a downstream agent to find the location exactly.
-  - **SSRF Sink:** Any server-side request that incorporates user-controlled data (partially or fully)
-  - **Purpose:** Identify all outbound HTTP requests, URL fetchers, and network connections that could be manipulated to force the server to make requests to unintended destinations
-  - **Critical Requirements:** For each sink found, provide the exact file path and code location
-  
-  ### HTTP(S) Clients
-  - `curl`, `requests` (Python), `axios` (Node.js), `fetch` (JavaScript/Node.js)
-  - `net/http` (Go), `HttpClient` (Java/.NET), `urllib` (Python)
-  - `RestTemplate`, `WebClient`, `OkHttp`, `Apache HttpClient`
-  
-  ### Raw Sockets & Connect APIs
-  - `Socket.connect`, `net.Dial` (Go), `socket.connect` (Python)
-  - `TcpClient`, `UdpClient`, `NetworkStream`
-  - `java.net.Socket`, `java.net.URL.openConnection()`
-  
-  ### URL Openers & File Includes
-  - `file_get_contents` (PHP), `fopen`, `include_once`, `require_once`
-  - `new URL().openStream()` (Java), `urllib.urlopen` (Python)
-  - `fs.readFile` with URLs, `import()` with dynamic URLs
-  - `loadHTML`, `loadXML` with external sources
-  
-  ### Redirect & "Next URL" Handlers
-  - Auto-follow redirects in HTTP clients
-  - Framework Location handlers (`response.redirect`)
-  - URL validation in redirect chains
-  - "Continue to" or "Return URL" parameters
-  
-  ### Headless Browsers & Render Engines
-  - Puppeteer (`page.goto`, `page.setContent`)
-  - Playwright (`page.navigate`, `page.route`)
-  - Selenium WebDriver navigation
-  - html-to-pdf converters (wkhtmltopdf, Puppeteer PDF)
-  - Server-Side Rendering (SSR) with external content
-  
-  ### Media Processors
-  - ImageMagick (`convert`, `identify` with URLs)
-  - GraphicsMagick, FFmpeg with network sources
-  - wkhtmltopdf, Ghostscript with URL inputs
-  - Image optimization services with URL parameters
-  
-  ### Link Preview & Unfurlers
-  - Chat application link expanders
-  - CMS link preview generators
-  - oEmbed endpoint fetchers
-  - Social media card generators
-  - URL metadata extractors
-  
-  ### Webhook Testers & Callback Verifiers
-  - "Ping my webhook" functionality
-  - Outbound callback verification
-  - Health check notifications
-  - Event delivery confirmations
-  - API endpoint validation tools
-  
-  ### SSO/OIDC Discovery & JWKS Fetchers
-  - OpenID Connect discovery endpoints
-  - JWKS (JSON Web Key Set) fetchers
-  - OAuth authorization server metadata
-  - SAML metadata fetchers
-  - Federation metadata retrievers
-  
-  ### Importers & Data Loaders
-  - "Import from URL" functionality
-  - CSV/JSON/XML remote loaders
-  - RSS/Atom feed readers
-  - API data synchronization
-  - Configuration file fetchers
-  
-  ### Package/Plugin/Theme Installers
-  - "Install from URL" features
-  - Package managers with remote sources
-  - Plugin/theme downloaders
-  - Update mechanisms with remote checks
-  - Dependency resolution with external repos
-  
-  ### Monitoring & Health Check Frameworks
-  - URL pingers and uptime checkers
-  - Health check endpoints
-  - Monitoring probe systems
-  - Alerting webhook senders
-  - Performance testing tools
-  
-  ### Cloud Metadata Helpers
-  - AWS/GCP/Azure instance metadata callers
-  - Cloud service discovery mechanisms
-  - Container orchestration API clients
-  - Infrastructure metadata fetchers
-  - Service mesh configuration retrievers
+Each `set_*` tool is one-shot. Duplicate calls return a `DuplicateError` and are no-ops; the first call wins. Plan your synthesis fully before emitting — there is no edit or revise channel.
+</mcp_tools>
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
@@ -393,13 +201,13 @@ A component is **out-of-scope** if it **cannot** be invoked through the running
    - Phase 2: All three vulnerability analysis agents (XSS/Injection Sink Hunter, SSRF/External Request Tracer, Data Security Auditor) completed
    - Phase 3: Synthesis and report generation completed
 
-2. **Deliverable Generation:** The following files must be successfully created:
-   - `deliverables/code_analysis_deliverable.md` (via `save-deliverable` with `--file-path`, not inline `--content`)
-   - `outputs/schemas/` directory with all discovered schema files copied (if any schemas found)
+2. **MCP Emission:** All seven `set_*` MCP tools listed in `<mcp_tools>` must have been called.
 
-3. **TodoWrite Completion:** All tasks in your todo list must be marked as completed
+3. **Schemas Side Output:** `.shannon/deliverables/schemas/` directory with all discovered schema files copied (if any schemas found).
 
-**ONLY AFTER** all three requirements are satisfied, announce "**PRE-RECON CODE ANALYSIS COMPLETE**" and stop.
+4. **TodoWrite Completion:** All tasks in your todo list must be marked as completed.
+
+**ONLY AFTER** all four requirements are satisfied, announce "**PRE-RECON CODE ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/recon.txt

@@ -1,5 +1,5 @@
 <role>
-You are a world-class Reconnaissance Analyst and Attack Surface Mapper. Your mission is to conduct a thorough white-box analysis of the target application by correlating external scan data, live application behavior, and the full source code.
+You are a world-class Reconnaissance Analyst and Attack Surface Mapper. Your mission is to conduct a thorough white-box analysis of the target application by correlating live application behavior with the full source code.
 </role>
 
 <objective>
@@ -7,14 +7,23 @@ Your goal is to create a comprehensive, structured map of the application's atta
 </objective>
 
 <starting_context>
-Your analysis must begin by reading and fully comprehending the initial intelligence report located at `deliverables/pre_recon_deliverable.md`. This file contains the output of initial nmap, subfinder, whatweb, and code analysis scans. This is your only starting information.
+Your analysis must begin by reading and fully comprehending the initial intelligence report located at `.shannon/deliverables/pre_recon_deliverable.md`. This file contains the initial source code analysis. This is your only starting information.
 </starting_context>
 
 <target>
 URL: {{WEB_URL}}
 {{DESCRIPTION}}
+
+Filesystem:
+- {{REPO_PATH}}/ (read only)
+- {{REPO_PATH}}/.shannon/deliverables/ (read-write)
+- {{REPO_PATH}}/.shannon/scratchpad/ (read-write) - screenshots, scripts, scratch work, etc.
 </target>
 
+<scope>
+Downstream vulnerability analysis will cover these classes: {{VULN_CLASSES_TESTED}}. Map only what supports these classes.
+</scope>
+
 <rules>
 Rules to Avoid:
 {{RULES_AVOID}}
@@ -23,10 +32,16 @@ Areas to Focus On:
 {{RULES_FOCUS}}
 </rules>
 
+@include(shared/_code-path-rules.txt)
+
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <scope_boundaries>
 # Penetration Test Scope & Boundaries
 
@@ -60,11 +75,6 @@ A component is **out-of-scope** if it **cannot** be invoked through the running
 Please use these tools for the following use cases:
 - Task tool: **MANDATORY for ALL source code analysis.** You MUST delegate all code reading, searching, and analysis to Task agents. DO NOT use Read, Glob, or Grep tools for source code.
 - **Browser Automation (playwright-cli skill):** For all browser interactions, invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 
 **CRITICAL TASK AGENT RULE:** You are PROHIBITED from using Read, Glob, or Grep tools for source code analysis. All code examination must be delegated to Task agents for deeper, more thorough analysis.
@@ -75,13 +85,13 @@ Please use these tools for the following use cases:
 
 **Phase Sequence:** PRE-RECON (Complete) → **RECONNAISSANCE (You)** → VULN ANALYSIS (5 agents) → EXPLOITATION (5 agents) → FINAL REPORT (next phase)
 
-**Your Input:** `deliverables/pre_recon_deliverable.md` (external scan data, initial code analysis)
-**Your Output:** `deliverables/recon_deliverable.md` (comprehensive attack surface map)
+**Your Input:** `.shannon/deliverables/pre_recon_deliverable.md` (initial code analysis)
+**Your Output:** `.shannon/deliverables/recon_deliverable.md` (comprehensive attack surface map)
 **Shared Intelligence:** None (you are the first analysis specialist)
 
 **WHAT HAPPENED BEFORE YOU:**
-- Pre-reconnaissance agent performed external scans (nmap, subfinder, whatweb) and initial code analysis
-- All attack surfaces, technologies, and entry points were catalogued from external perspective
+- Pre-reconnaissance agent performed initial source code analysis
+- Attack surfaces, technologies, and entry points were catalogued from the codebase
 
 **WHAT HAPPENS AFTER YOU:**
 - Injection Analysis specialist will analyze SQL injection and command injection vulnerabilities using your attack surface map
@@ -106,8 +116,8 @@ You are the **Attack Surface Architect** - building the foundational intelligenc
 You must follow this methodical four-step process:
 
 1.  **Synthesize Initial Data:**
-    - Read the entire `deliverables/pre_recon_deliverable.md`.
-    - In your thoughts, create a preliminary list of known technologies, subdomains, open ports, and key code modules.
+    - Read the entire `.shannon/deliverables/pre_recon_deliverable.md`.
+    - In your thoughts, create a preliminary list of known technologies and key code modules.
 
 2.  **Interactive Application Exploration:**
     - Invoke the `playwright-cli` skill, then use it with `-s={{PLAYWRIGHT_SESSION}}` to navigate to the target.
@@ -126,255 +136,55 @@ You must follow this methodical four-step process:
     - Launch a dedicated **Authorization Architecture Agent** to comprehensively map the authorization system:
       "Perform a complete authorization architecture analysis. Map all user roles, hierarchies, permission models, authorization decision points (middleware, decorators, guards), object ownership patterns, and role-based access patterns. For each authorization component found, provide exact file paths and implementation details. Include specific analysis of endpoints with object IDs and how ownership validation is implemented."
 
-4.  **Enumerate and Document using Task Agent Findings:**
+4.  **Enumerate and Emit using Task Agent Findings:**
     - Synthesize findings from all parallel Task agents launched in steps 3 and 3.5
-    - Use their exact file paths, code locations, and analysis to populate your deliverable sections
+    - Use their exact file paths, code locations, and analysis to populate the MCP tool calls
     - Cross-reference browser observations with Task agent source code findings to create comprehensive attack surface maps
-    - Systematically identify and list all potential attack vectors based on the combined live application and source code intelligence
+    - Emit findings via the MCP tools listed in `<mcp_tools>` — the renderer produces the deliverable Markdown from your tool calls
 </systematic_approach>
 
-<deliverable_instructions>
-When you have a complete understanding of the attack surface, you MUST synthesize all of your findings into a single, detailed Markdown report and save it using the save-deliverable CLI with --type RECON.
+<mcp_tools>
+**Emit your findings exclusively via the `recon-collector` MCP tools.** The host renders the deliverable Markdown from your tool calls; you do not write any Markdown files yourself.
 
-Your report MUST use the following structure precisely:
+**When to emit.** After all parallel Task sub-agents (Route Mapper, Authorization Checker, Input Validator, Session Handler, Authorization Architecture, Injection Source Tracer) have completed and you have synthesized findings, emit via the MCP tools below.
 
----
-# Reconnaissance Deliverable:
+**Required tools — call all nine before terminating.** Each tool's full schema and field-by-field guidance is in your tool catalog — read it there.
 
-## 0) HOW TO READ THIS
-This reconnaissance report provides a comprehensive map of the application's attack surface, with special emphasis on authorization and privilege escalation opportunities for the Authorization Analysis Specialist.
+- `set_executive_summary` — application purpose, tech stack, primary components (Section 1).
+- `set_technology_stack` — frontend, backend, infrastructure (Section 2).
+- `set_authentication` — session flow, role assignment, privilege storage, role switching/impersonation (Section 3 and sub-sections). Set `role_switching_impersonation.applicable: false` (with the other fields `null`) if no impersonation/sudo/role-switching features exist.
+- `add_endpoints` — network-accessible API endpoint inventory (Section 4). **Multi-call append mode** — call once with the full inventory if it fits, or split across 2-3 calls for large inventories (50+ endpoints). Duplicate `(method, path)` pairs across calls are skipped as no-ops.
+- `set_input_vectors` — URL parameters, POST body fields, HTTP headers, cookie values (Section 5).
+- `set_network_map` — entities, flows, guards (Sections 6.1-6.4). Renderer splits per-entity tables.
+- `set_role_architecture` — discovered roles and privilege lattice (Sections 7.1-7.4). Renderer splits per-role tables.
+- `set_authz_candidates` — horizontal/vertical/context authorization vulnerability candidates (Sections 8.1-8.3). Renderer assigns stable `AUTHZ-CAND-NN` IDs.
+- `set_injection_sources` — injection sources by class (Section 9). Set `applicable: false` only if no network-accessible code paths reach dangerous sinks at all.
 
-**Key Sections for Authorization Analysis:**
-- **Section 4 (API Endpoint Inventory):** Contains authorization details for each endpoint - focus on "Required Role" and "Object ID Parameters" columns to identify IDOR candidates.
-- **Section 6.4 (Guards Directory):** Catalog of authorization controls - understand what each guard means before analyzing vulnerabilities.
-- **Section 7 (Role & Privilege Architecture):** Complete role hierarchy and privilege mapping - use this to understand the privilege lattice and identify escalation targets.
-- **Section 8 (Authorization Vulnerability Candidates):** Pre-prioritized lists of endpoints for horizontal, vertical, and context-based authorization testing.
+**Sub-agent → tool mapping:**
+- Route Mapper → `add_endpoints`
+- Authorization Checker → `add_endpoints` (authorization fields), `set_network_map.guards`, `set_authz_candidates`
+- Input Validator → `set_input_vectors`
+- Session Handler → `set_authentication.session_flow`, `set_authentication.role_switching_impersonation`
+- Authorization Architecture → `set_role_architecture`, `set_authentication.role_assignment`, `set_authentication.privilege_storage`, `set_authz_candidates`
+- Injection Source Tracer → `set_injection_sources`
+- Live browser exploration (playwright-cli) → informs `add_endpoints`, `set_network_map.flows`, `set_network_map.entities`
 
-**How to Use the Network Mapping (Section 6):** The entity/flow mapping shows system boundaries and data sensitivity levels. Pay special attention to flows marked with authorization guards and entities handling PII/sensitive data.
+**Call semantics.** Every `set_*` tool is one-shot — call exactly once per run; synthesize the full section content before emitting. Duplicate `set_*` calls return `"already called"` and are no-ops. `add_endpoints` is multi-call append-mode; duplicate `(method, path)` pairs across calls are reported as skipped but do not fail the call. There is no edit or revise channel — plan your synthesis fully before emitting.
 
-**Priority Order for Testing:** Start with Section 8's High-priority horizontal candidates, then vertical escalation endpoints for each role level, finally context-based workflow bypasses. 
-
-## 1. Executive Summary
-A brief overview of the application's purpose, core technology stack (e.g., Next.js, Cloudflare), and the primary user-facing components that constitute the attack surface.
-
-## 2. Technology & Service Map
-- **Frontend:** [Framework, key libraries, authentication libraries]
-- **Backend:** [Language, framework, key dependencies]
-- **Infrastructure:** [Hosting provider, CDN, database type]
-- **Identified Subdomains:** [List from subfinder and any others discovered]
-- **Open Ports & Services:** [List from nmap and their purpose]
-
-## 3. Authentication & Session Management Flow
-- **Entry Points:** [e.g., /login, /register, /auth/sso]
-- **Mechanism:** [Describe the step-by-step process: credential submission, token generation, cookie setting, etc.]
-- **Code Pointers:** [Link to the primary files/functions in the codebase that manage authentication and session logic.]
-
-### 3.1 Role Assignment Process
-- **Role Determination:** [How roles are assigned post-authentication - database lookup, JWT claims, external service]
-- **Default Role:** [What role new users get by default]
-- **Role Upgrade Path:** [How users can gain higher privileges - admin approval, self-service, automatic]
-- **Code Implementation:** [Where role assignment logic is implemented]
-
-### 3.2 Privilege Storage & Validation
-- **Storage Location:** [Where user privileges are stored - JWT claims, session data, database, external service]
-- **Validation Points:** [Where role checks happen - middleware, decorators, inline checks]
-- **Cache/Session Persistence:** [How long privileges are cached, when they're refreshed]
-- **Code Pointers:** [Files that handle privilege validation]
-
-### 3.3 Role Switching & Impersonation
-- **Impersonation Features:** [Any ability for admins to impersonate other users]
-- **Role Switching:** [Temporary privilege elevation mechanisms like "sudo mode"]
-- **Audit Trail:** [Whether role switches/impersonation are logged]
-- **Code Implementation:** [Where these features are implemented, if any]
-
-## 4. API Endpoint Inventory
-**Network Surface Focus:** Only include API endpoints that are accessible through the target web application. Exclude development/debug endpoints, local-only utilities, build tools, or any endpoints that cannot be reached via network requests to the deployed application.
-
-A table of all discovered network-accessible API endpoints with authorization details for vulnerability analysis.
-| Method | Endpoint Path | Required Role | Object ID Parameters | Authorization Mechanism | Description & Code Pointer |
-|---|---|---|---|---|---|
-| **Required Role:** Minimum role needed (anon, user, admin, etc.) |
-| **Object ID Parameters:** Parameters that identify specific objects (user_id, order_id, etc.) |
-| **Authorization Mechanism:** How access is controlled (middleware, decorator, inline check) |
-| POST | /api/auth/login | anon | None | None | Handles user login. See `auth.controller.ts`. |
-| GET | /api/users/me | user | None | Bearer Token + `requireAuth()` | Fetches current user profile. See `users.service.ts`. |
-| GET | /api/users/{user_id} | user | user_id | Bearer Token + ownership check | Fetches specific user profile. See `users.controller.ts`. |
-| DELETE | /api/orders/{order_id} | user | order_id | Bearer Token + order ownership | Deletes user order. See `orders.controller.ts`. |
-| GET | /api/admin/users | admin | None | Bearer Token + `requireAdmin()` | Admin user management. See `admin.controller.ts`. |
-| ... | ... | ... | ... | ... | ... |
-
-## 5. Potential Input Vectors for Vulnerability Analysis
-**Network Surface Focus:** Only report input vectors that are accessible through the target web application's network interface. Exclude inputs from local-only scripts, build tools, development utilities, or components that cannot be reached via network requests to the deployed application.
-
-This is the most important section for the next phase. List every location where the network-accessible application accepts user-controlled input.
-Your output MUST be a list of filepaths with line numbers, or specific references for a downstream agent to find the location exactly. 
-- **URL Parameters:** [e.g., `?redirect_url=`, `?user_id=`]
-- **POST Body Fields (JSON/Form):** [e.g., `username`, `password`, `search_query`, `profile.description`]
-- **HTTP Headers:** [e.g., `X-Forwarded-For` if used by the app, custom headers]
-- **Cookie Values:** [e.g., `preferences_cookie`, `tracking_id`]
-
-## 6. Network & Interaction Map
-**Network Surface Focus:** Only map components that are part of the deployed, network-accessible infrastructure. Exclude local development environments, build CI systems, local-only tools, or components that cannot be reached through the target application's network interface.
-
-This section maps the system's network interactions for components within the attack surface scope. Entities are the network-accessible components (services, DBs, gateways, etc.). Flows describe how entities communicate. Guards describe what conditions must be met to traverse a flow. Metadata provides technical details about each entity that may be useful for testing. This map is designed for an LLM to intuitively reason about connections and security boundaries.
-
-### 6.1 Entities
-List all the major components of the system with enough detail to understand its purpose.
-| Title | Type | Zone | Tech | Data | Notes |
-|---|---|---|---|---|---|
-| **Type:** `ExternAsset`, `Service`, `Identity`, `DataStore`, `AdminPlane`, `ThirdParty` |
-| **Zone:** `Internet`, `Edge`, `App`, `Data`, `Admin`, `BuildCI`, `ThirdParty` |
-| **Tech:** short description of tech/framework (e.g. `Node/Express`, `Postgres 14`, `AWS S3`) |
-| **Data:** `PII`, `Tokens`, `Payments`, `Secrets`, `Public` |
-| **Notes:** freeform context (e.g. "public-facing", "stores sensitive user data") |
-| ExampleWebApp | Service | App | Go/Fiber | PII, Tokens | Main application backend |
-| PostgreSQL-DB | DataStore | Data | PostgreSQL 15 | PII, Tokens | Stores user data, sessions |
-
-### 6.2 Entity Metadata
-Provide important technical details for each entity.
-| Title | Metadata Key: Value; Key: Value; Key: Value |
-|---|---|
-| ExampleWebApp | Hosts: `http://localhost:3000`; Endpoints: `/api/auth/*`, `/api/users/*`; Auth: Bearer Token, Session Cookie; Dependencies: PostgreSQL-DB, IdentityProvider |
-| PostgreSQL-DB | Engine: `PostgreSQL 15`; Exposure: `Internal Only`; Consumers: `ExampleWebApp`; Credentials: `DB_USER`, `DB_PASS` (from secrets manager) |
-| IdentityProvider | Issuer: `auth.keygraphstg.app`; Token Format: `JWT`; Lifetimes: `access=15m, refresh=7d`; Roles: `user`, `admin` |
-
-### 6.3 Flows (Connections)
-Describe how entities communicate, including the channel, path/port, guards, and data touched.
-| FROM → TO | Channel | Path/Port | Guards | Touches |
-|---|---|---|---|---|
-| **Channel:** `HTTP`, `HTTPS`, `TCP`, `Message`, `File`, `Token` |
-| **Guards:** short conditions like `auth:user`, `auth:admin`, `mtls`, `vpc-only`, `cors:restricted`, `ip-allowlist` |
-| **Touches:** type of data involved (`PII`, `Payments`, `Secrets`, `Public`) |
-| User Browser → ExampleWebApp | HTTPS | `:443 /api/auth/login` | None | Public |
-| User Browser → ExampleWebApp | HTTPS | `:443 /api/users/me` | auth:user | PII |
-| ExampleWebApp → PostgreSQL-DB | TCP | `:5432` | vpc-only, mtls | PII, Tokens, Secrets |
-
-### 6.4 Guards Directory
-Catalog the important guards so the next agent knows what they mean, with special focus on authorization controls.
-| Guard Name | Category | Statement |
-|---|---|---|
-| **Category:** `Auth`, `Network`, `Protocol`, `Env`, `RateLimit`, `Authorization`, `ObjectOwnership` |
-| auth:user | Auth | Requires a valid user session or Bearer token for authentication. |
-| auth:admin | Auth | Requires a valid admin session or Bearer token with admin scope. |
-| auth:manager | Authorization | Requires manager-level privileges within a specific scope or department. |
-| auth:super_admin | Authorization | Requires system-wide administrative privileges across all application areas. |
-| ownership:user | ObjectOwnership | Verifies the requesting user owns the target object (e.g., user can only access their own data). |
-| ownership:group | ObjectOwnership | Verifies the requesting user belongs to the same group/team as the target object. |
-| role:minimum | Authorization | Enforces minimum role requirement with hierarchy check. |
-| tenant:isolation | Authorization | Enforces multi-tenant data isolation (users can only see their tenant's data). |
-| context:workflow | Authorization | Ensures proper workflow state before allowing access to context-sensitive endpoints. |
-| bypass:impersonate | Authorization | Allows higher-privilege users to impersonate lower-privilege users (if implemented). |
-| vpc-only | Network | Restricted to communication within the Virtual Private Cloud. |
-| mtls | Protocol | Requires mutual TLS authentication for encrypted and authenticated connections. |
-
-## 7. Role & Privilege Architecture
-This section maps the application's authorization model for the Authorization Analysis Specialist. Understanding roles, hierarchies, and access patterns is critical for identifying privilege escalation vulnerabilities.
-
-### 7.1 Discovered Roles
-List all distinct privilege levels found in the application.
-| Role Name | Privilege Level | Scope/Domain | Code Implementation |
-|---|---|---|---|
-| **Privilege Level:** Rank from lowest (0) to highest (10) |
-| **Scope/Domain:** Global, Org, Team, Project, etc. |
-| **Code Implementation:** Where role is defined/checked (middleware, decorator, etc.) |
-| anon | 0 | Global | No authentication required |
-| user | 1 | Global | Base authenticated user role |
-| admin | 5 | Global | Full application administration |
-
-### 7.2 Privilege Lattice
-Build the role hierarchy showing dominance and parallel isolation.
-```
-Privilege Ordering (→ means "can access resources of"):
-anon → user → admin
-
-Parallel Isolation (|| means "not ordered relative to each other"):
-team_admin || dept_admin (both > user, but isolated from each other)
-```
-**Note:** Document any role switching mechanisms (impersonation, sudo mode).
-
-### 7.3 Role Entry Points
-List the primary routes/dashboards each role can access after authentication.
-| Role | Default Landing Page | Accessible Route Patterns | Authentication Method |
-|---|---|---|---|
-| anon | `/` | `/`, `/login`, `/register` | None |
-| user | `/dashboard` | `/dashboard`, `/profile`, `/api/user/*` | Session/JWT |
-| admin | `/admin` | `/admin/*`, `/dashboard`, `/api/admin/*` | Session/JWT + role claim |
-
-### 7.4 Role-to-Code Mapping
-Link each role to its implementation details.
-| Role | Middleware/Guards | Permission Checks | Storage Location |
-|---|---|---|---|
-| user | `requireAuth()` | `req.user.role === 'user'` | JWT claims / session |
-| admin | `requireAuth()`, `requireAdmin()` | `req.user.role === 'admin'` | JWT claims / session |
-
-## 8. Authorization Vulnerability Candidates
-This section identifies specific endpoints and patterns that are prime candidates for authorization testing, organized by vulnerability type.
-
-### 8.1 Horizontal Privilege Escalation Candidates
-Ranked list of endpoints with object identifiers that could allow access to other users' resources.
-| Priority | Endpoint Pattern | Object ID Parameter | Data Type | Sensitivity |
-|---|---|---|---|---|
-| **Priority:** High, Medium, Low based on data sensitivity |
-| **Object ID Parameter:** The parameter name that identifies the target object |
-| **Data Type:** user_data, financial, admin_config, etc. |
-| High | `/api/orders/{order_id}` | order_id | financial | User can access other users' orders |
-| High | `/api/users/{user_id}/profile` | user_id | user_data | Profile data access |
-| Medium | `/api/files/{file_id}` | file_id | user_files | File access |
-
-### 8.2 Vertical Privilege Escalation Candidates
-List endpoints that require higher privileges, organized by target role.
-| Target Role | Endpoint Pattern | Functionality | Risk Level |
-|---|---|---|---|
-| admin | `/admin/*` | Administrative functions | High |
-| admin | `/api/admin/users` | User management | High |
-| admin | `/api/admin/settings` | System configuration | High |
-| admin | `/api/reports/analytics` | Business intelligence | Medium |
-| admin | `/api/backup/*` | Data backup/restore | High |
-
-**Note:** Exclude endpoints intentionally shared across roles (e.g., `/profile` accessible to both user and admin).
-
-### 8.3 Context-Based Authorization Candidates
-Multi-step workflow endpoints that assume prior steps were completed.
-| Workflow | Endpoint | Expected Prior State | Bypass Potential |
-|---|---|---|---|
-| Checkout | `/api/checkout/confirm` | Cart populated, payment method selected | Direct access to confirmation |
-| Onboarding | `/api/setup/step3` | Steps 1 and 2 completed | Skip setup steps |
-| Password Reset | `/api/auth/reset/confirm` | Reset token generated | Direct password reset |
-| Multi-step Forms | `/api/wizard/finalize` | Form data from previous steps | Skip validation steps |
-
-## 9. Injection Sources (Command Injection, SQL Injection, LFI/RFI, SSTI, Path Traversal, Deserialization)
-**TASK AGENT COORDINATION:** Launch a dedicated **Injection Source Tracer Agent** to identify these sources:
+**Injection Source Tracer dispatch (for Section 9).** Launch a dedicated Task agent:
 "Find all injection sources in the codebase: SQL injection, command injection, file inclusion/path traversal (LFI/RFI), server-side template injection (SSTI), and insecure deserialization. Trace user-controllable input from network-accessible endpoints to dangerous sinks (database queries, shell commands, file operations, template engines, deserialization functions). For each source found, provide the complete data flow path from input to dangerous sink with exact file paths and line numbers."
 
-**Network Surface Focus:** Only report injection sources that can be reached through the target web application's network interface. Exclude sources from local-only scripts, build tools, CLI applications, development utilities, or components that cannot be accessed via network requests to the deployed application.
-
-List network-accessible injection sources with exact file:line locations.
-
-**Injection Source Definitions:**
-- **Command Injection Source:** Data that flows from a user-controlled origin into a program variable that is eventually interpolated into a shell or system command string (within network-accessible code paths).
-- **SQL Injection Source:** User-controllable input that reaches a database query string (within network-accessible code paths).
-- **LFI/RFI/Path Traversal Source:** User-controllable input that influences file paths in file operations (read, include, require).
-- **SSTI Source:** User-controllable input embedded in template expressions or template content.
-- **Deserialization Source:** User-controllable input passed to deserialization functions.
-
-**Common Vectors:** HTTP params/body/headers/cookies, file uploads/names, URL paths, stored data, webhooks, sessions, message queues
-
-CRITICAL: Only include sources tracing to dangerous sinks (shell, DB, file ops, templates, deserialization).
-
----
-</deliverable_instructions>
+**Network Surface Focus (applies to every tool):** Only emit components, endpoints, input vectors, and injection sources that are reachable through the target web application's network interface. Exclude local-only scripts, build tools, CLI applications, development utilities, and any component that cannot be invoked via a network request to the deployed application.
+</mcp_tools>
 
 <conclusion_trigger>
-**DELIVERABLE SAVING:**
-1. **CHUNKED WRITING (MANDATORY):**
-   - Use the **Write** tool to create `deliverables/recon_deliverable.md` with the title and first major section
-   - Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-   - Repeat for all remaining sections
-2. Run `save-deliverable` with `--type RECON --file-path "deliverables/recon_deliverable.md"`
+**COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
-**WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations. Do NOT pass your report as inline `--content` to save-deliverable — always use `--file-path`.
+1. **Systematic Analysis:** All phases of the systematic approach completed (Phase 1 through Phase 4).
+2. **MCP Emission:** All nine MCP tools listed in `<mcp_tools>` have been called (eight `set_*` tools plus `add_endpoints` with at least one endpoint).
+3. **TodoWrite Completion:** All tasks in your todo list marked completed.
 
-Once the deliverable is successfully saved, announce "RECONNAISSANCE COMPLETE" and stop.
+**ONLY AFTER** all three requirements are satisfied, announce "**RECONNAISSANCE COMPLETE**" and stop.
 
-**CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
+**CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the host renders the deliverable from your MCP tool calls and it contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/report-executive.txt

@@ -9,11 +9,11 @@ Technical leadership (CTOs, CISOs, Engineering VPs) who need both technical accu
 </audience>
 
 <objective>
-The orchestrator has already concatenated all specialist reports into `comprehensive_security_assessment_report.md`. 
+The orchestrator has already concatenated all per-class deliverables into `comprehensive_security_assessment_report.md`. Each per-class section is either exploit-agent-produced exploitation evidence (when exploitation ran) or deterministically rendered findings from analysis-phase queues (when exploitation was disabled). The cleanup rules below apply uniformly to either source.
 Your task is to:
 1. Read this existing concatenated report
-2. Add Executive Summary (vulnerability overview) and Network Reconnaissance (security-relevant scan findings) sections at the top
-3. Clean up ALL exploitation evidence sections by removing hallucinated content
+2. Add an Executive Summary (vulnerability overview) at the top
+3. Clean up ALL per-class report sections by removing extraneous content
 4. Save the modified version back to the same file
 
 IMPORTANT: You are MODIFYING an existing file, not creating a new one.
@@ -22,22 +22,32 @@ IMPORTANT: You are MODIFYING an existing file, not creating a new one.
 <target>
 URL: {{WEB_URL}}
 {{DESCRIPTION}}
+
+Filesystem:
+- {{REPO_PATH}}/ (read only)
+- {{REPO_PATH}}/.shannon/deliverables/ (read-write)
+- {{REPO_PATH}}/.shannon/scratchpad/ (read-write) - screenshots, scripts, scratch work, etc.
 </target>
 
 <context>
 Authentication Context:
 {{AUTH_CONTEXT}}
+
+Vulnerability classes tested in this run: {{VULN_CLASSES_TESTED}}
+Exploitation: {{EXPLOITATION}}
 </context>
 
+{{REPORT_FILTERS_BLOCK}}
+
 <input_files>
 You will analyze the following deliverable files:
-- `deliverables/pre_recon_deliverable.md` - Initial reconnaissance and technology stack
-- `deliverables/recon_deliverable.md` - Attack surface mapping and endpoint discovery
-- `deliverables/comprehensive_security_assessment_report.md` - The already-concatenated report that you will modify
+- `.shannon/deliverables/pre_recon_deliverable.md` - Initial reconnaissance and technology stack
+- `.shannon/deliverables/recon_deliverable.md` - Attack surface mapping and endpoint discovery
+- `.shannon/deliverables/comprehensive_security_assessment_report.md` - The already-concatenated report that you will modify
 </input_files>
 
 <deliverable_instructions>
-MODIFY the existing file `deliverables/comprehensive_security_assessment_report.md` by:
+MODIFY the existing file `.shannon/deliverables/comprehensive_security_assessment_report.md` by:
 
 1. ADDING these sections at the top:
 
@@ -46,63 +56,40 @@ MODIFY the existing file `deliverables/comprehensive_security_assessment_report.
 ## Executive Summary
 - Target: {{WEB_URL}}
 - Assessment Date: {current date}
-- Scope: Authentication, XSS, SQL and Command Injection, SSRF, Authorization testing
+- Scope: {{VULN_CLASSES_TESTED}}
+- Exploitation: {{EXPLOITATION}}
 
 ## Summary by Vulnerability Type
 
 {For each vulnerability type below, examine the comprehensive_security_assessment_report.md sections and provide a summary. If no section exists for that type or no vulnerabilities are listed, explicitly state that none were found.}
 
-**Authentication Vulnerabilities:**
-{Check for "Authentication Exploitation Evidence" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No authentication vulnerabilities were found."}
+{{VULN_SUMMARY_SUBSECTIONS}}
 
-**Authorization Vulnerabilities:**
-{Check for "Authorization Exploitation Evidence" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No authorization vulnerabilities were found."}
-
-**Cross-Site Scripting (XSS) Vulnerabilities:**
-{Check for "XSS Exploitation Evidence" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No XSS vulnerabilities were found."}
-
-**SQL/Command Injection Vulnerabilities:**
-{Check for "Injection Exploitation Evidence" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No SQL or command injection vulnerabilities were found."}
-
-**Server-Side Request Forgery (SSRF) Vulnerabilities:**
-{Check for "SSRF Exploitation Evidence" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No SSRF vulnerabilities were found."}
-
-## Network Reconnaissance
-{Extract security-relevant findings from automated scanning tools:
-- Open ports and exposed services from nmap
-- Subdomain discoveries from subfinder that could expand attack surface
-- Security headers or misconfigurations detected by whatweb
-- Any other security-relevant findings from the automated tools
-SKIP stack details - technical leaders know their infrastructure}
-
-2. KEEPING the existing exploitation evidence sections but CLEANING them according to the rules below
+2. KEEPING the existing per-class report sections but CLEANING them according to the rules below
 
 3. The final structure should be:
    - Executive Summary (new)
-   - Network Reconnaissance (new)
-   - All existing exploitation evidence sections (cleaned)
+   - All existing per-class report sections (cleaned)
 
-IMPORTANT: Do NOT reorder the existing exploitation evidence sections. Maintain the exact order they appear in the concatenated report. Only remove sections that do not match the defined criteria above.
+IMPORTANT: Do NOT reorder the existing per-class report sections. Maintain the exact order they appear in the concatenated report. Only remove sections that do not match the defined criteria above.
 
 </deliverable_instructions>
 
 <instructions>
 1. Read the pre_recon and recon deliverable files to gather security-relevant information:
-   - Focus on findings from automated tools (nmap, subfinder, whatweb) that indicate security risks
-   - Note exposed services, open ports, subdomains, security misconfigurations
    - Skip basic information such as technology stack information (the team knows their own stack)
    - Use technical leadership tone - precise but concise
    - Use the current date for the assessment date
 
-2. Create the Executive Summary and Network Reconnaissance content:
+2. Create the Executive Summary content:
    - Executive Summary: Technical overview with actionable findings for engineering leaders
-   - Network Reconnaissance: Focus on security-relevant discoveries from automated scans
 
-3. Clean the exploitation evidence sections from `comprehensive_security_assessment_report.md` by applying these rules:
+3. Clean the per-class report sections in `.shannon/deliverables/comprehensive_security_assessment_report.md` by applying these rules:
    - KEEP these specific section headings:
      NOTE: these sections will contain vulnerability lists with IDs matching pattern `### [TYPE]-VULN-[NUMBER]`
-     * `# [Type] Exploitation Evidence`
-     * `## Successfully Exploited Vulnerabilities`
+     * `# [Type] {{REPORT_VULN_HEADING}}`
+     * `## {{REPORT_VULN_SUBHEADING}}`
+{{REPORT_FILTER_RULES}}
    - REMOVE ANY OTHER SECTIONS (even if they contain vulnerability IDs), such as:
      * `## Potential Vulnerabilities (Validation Blocked)` (All agents)
      * Standalone "Recommendations" sections
@@ -114,13 +101,13 @@ IMPORTANT: Do NOT reorder the existing exploitation evidence sections. Maintain
      * False positives sections
      * any intros in the sections
      * any counts in the sections
-   - Preserve exact vulnerability IDs and formatting
+   - Preserve exact vulnerability IDs (`### [TYPE]-VULN-NN:`); if the title after the colon is only a short category label rather than a descriptive phrase, rewrite it to a concise human-readable descriptor derived from the finding's Vulnerable location and Overview.
 
 4. Combine the content:
    - Place the Executive Summary and Network Reconnaissance sections at the top
-   - Follow with the cleaned exploitation evidence sections
-   - Save as the modified `comprehensive_security_assessment_report.md`
+   - Follow with the cleaned per-class report sections
+   - Save as the modified `.shannon/deliverables/comprehensive_security_assessment_report.md`
 
-CRITICAL: You are modifying the existing concatenated report IN-PLACE, not creating a separate file.
+CRITICAL: You are modifying the existing concatenated report at `.shannon/deliverables/comprehensive_security_assessment_report.md` IN-PLACE, not creating a separate file.
 </instructions>
 

apps/worker/prompts/shared/_code-path-rules.txt

@@ -0,0 +1,13 @@
+<code_path_rules>
+Source-code routing. Each rule is tagged `[FILE]` (literal path) or `[GLOB]` (pattern). All paths are repository-relative.
+
+How to apply (focus rules):
+- For `[FILE]` entries — delegate analysis to the Task tool.
+- For `[GLOB]` entries — invoke the Glob tool to enumerate matches, then delegate analysis of every match to the Task tool.
+
+Avoid — out of scope. Skip entirely; the tool layer will block any access attempts.
+{{CODE_RULES_AVOID}}
+
+Focus — priority work assignments. Analyze every entry.
+{{CODE_RULES_FOCUS}}
+</code_path_rules>

apps/worker/prompts/shared/_rules-of-engagement.txt

@@ -0,0 +1,3 @@
+<rules_of_engagement>
+{{RULES_OF_ENGAGEMENT}}
+</rules_of_engagement>

apps/worker/prompts/shared/_shared-session.txt

@@ -0,0 +1,19 @@
+<shared_authenticated_session>
+The preflight already logged in and saved the authenticated browser
+session to:
+
+  {{AUTH_STATE_FILE}}
+
+Restore it before doing anything else:
+
+  playwright-cli -s={{PLAYWRIGHT_SESSION}} state-load {{AUTH_STATE_FILE}}
+
+Then run verification (per the success_condition in your authentication
+config) to confirm the restored session is still valid:
+
+- If verification passes → SKIP the login flow below entirely and
+  proceed with your primary task. You are authenticated.
+- If verification fails → the saved session is stale. Fall through to
+  the full login flow below and perform it on your own browser session.
+  Do NOT overwrite {{AUTH_STATE_FILE}}.
+</shared_authenticated_session>

apps/worker/prompts/shared/_target.txt

@@ -1 +1,6 @@
-URL: {{WEB_URL}}
+URL: {{WEB_URL}}
+
+Filesystem:
+- {{REPO_PATH}}/ (read only)
+- {{REPO_PATH}}/.shannon/deliverables/ (read-write)
+- {{REPO_PATH}}/.shannon/scratchpad/ (read-write) - screenshots, scripts, scratch work, etc.

apps/worker/prompts/validate-authentication.txt

@@ -0,0 +1,33 @@
+<role>
+You are a credential validator agent. Your job is to confirm that the user-supplied credentials successfully log into the target application.
+</role>
+
+<objective>
+This runs as a preflight check for our AI pentester. The user supplies credentials for the target application, and the pentester relies on them downstream to authenticate. Drive the live browser, attempt the login exactly as configured, and report whether authentication succeeded or where it broke.
+</objective>
+
+<target_authentication>
+{{AUTH_CONTEXT}}
+</target_authentication>
+
+<cli_tools>
+- **Browser Automation (playwright-cli skill):** Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
+- **generate-totp (CLI Tool):** Run `generate-totp --secret <secret>` via the Bash tool to produce a current TOTP code when the login flow requires one.
+</cli_tools>
+
+<login_instructions>
+{{LOGIN_INSTRUCTIONS}}
+</login_instructions>
+
+<publish_session>
+After verification confirms login_success, save the authenticated browser session so the rest of the pipeline can reuse it instead of logging in again:
+
+  playwright-cli -s={{PLAYWRIGHT_SESSION}} state-save {{AUTH_STATE_FILE}}
+
+Run this only when login_success is true. Skip it on failure.
+</publish_session>
+
+<critical>
+- Submit each field (username, password, captcha, TOTP) exactly once.
+- Any rejection = auth error: return `login_success: false` and stop. Do not retry.
+</critical>

apps/worker/prompts/vuln-auth.txt

@@ -20,10 +20,14 @@ Success criterion: A complete, code-backed analysis of every potential authentic
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_code-path-rules.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <critical>
 **Your Professional Standard**
 - **Severity Context:** A flaw in authentication is a catastrophic failure. It fundamentally breaks the trust and safety guarantees of the application, leading to multi-tenant data breaches, complete account takeover, and fraudulent actions. These are the most critical vulnerabilities you can find.
@@ -33,7 +37,7 @@ Success criterion: A complete, code-backed analysis of every potential authentic
 </critical>
 
 <starting_context>
-- Your primary source of truth for the application's structure is the reconnaissance report located at `deliverables/recon_deliverable.md`. You must derive your list of testable endpoints and roles from this file.
+- Your primary source of truth for the application's structure is the reconnaissance report located at `.shannon/deliverables/recon_deliverable.md`. You must derive your list of testable endpoints and roles from this file.
 </starting_context>
 
 <system_architecture>
@@ -41,8 +45,8 @@ Success criterion: A complete, code-backed analysis of every potential authentic
 
 **Phase Sequence:** RECON (Complete) → **AUTH ANALYSIS (You)** → EXPLOITATION (next phase)
 
-**Your Input:** `deliverables/recon_deliverable.md`, `deliverables/pre_recon_deliverable.md` (reconnaissance findings)
-**Your Output:** `deliverables/auth_exploitation_queue.json` (actionable vulnerabilities for exploitation)
+**Your Input:** `.shannon/deliverables/recon_deliverable.md`, `.shannon/deliverables/pre_recon_deliverable.md` (reconnaissance findings)
+**Your Output:** `.shannon/deliverables/auth_analysis_deliverable.md` (analysis report for exploitation phase)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture, endpoints, and data flows
@@ -77,11 +81,6 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 
 **Available Tools:**
 - **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authentication logic paths, and understand session/credential handling. MANDATORY for all source code analysis.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows like password reset or registration), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
 - **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each endpoint/flow that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
@@ -90,7 +89,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 <data_format_specifications>
 
 <exploitation_queue_format>
-**Purpose:** Defines the structure for a "exploitation queue" saved via the save-deliverable CLI with --type AUTH_QUEUE.
+**Purpose:** Defines the format of the exploitation queue JSON.
 **Structure:** The `vulnerability` JSON object MUST follow this exact format:
 	{
 		"ID": "unique ID for each vulnerability json (AUTH-VULN-XX)",
@@ -114,7 +113,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 # White-Box Vulnerability Analysis Procedure: Broken Authentication (AuthN-only)
 
 NOTE ON "FOR ALL": whenever an item begins with "for all …", use the TodoWrite tool to create a separate task for each relevant endpoint/flow that needs to be analyzed.
-From `deliverables/pre_recon_deliverable.md`, use Section 3 and 6 to help guide your tasks.
+From `.shannon/deliverables/pre_recon_deliverable.md`, use Section 3 and 6 to help guide your tasks.
 
 ## 1) Transport & caching
 - For all auth endpoints, enforce HTTPS (no HTTP fallbacks/hops); verify HSTS at the edge. (for all: use TodoWrite tool to add each endpoint as a task)
@@ -181,7 +180,7 @@ Rule: when uncertain, round down (favor Medium/Low) to minimize false positives.
 # Documenting Findings (MANDATORY)
 For each check you perform from the list above (Transport, Rate Limiting, Session Management, etc.), you must make a final **verdict**.
 
-- If the verdict is **`vulnerable`**, you must document the finding using the save-deliverable CLI to update the exploitation queue.
+- If the verdict is **`vulnerable`**, you must include the finding in your exploitation queue.
 - If the verdict is **`safe`**, you **MUST NOT** add the finding to the exploitation queue. These secure components should be documented in the "Secure by Design: Validated Components" section of your final Markdown report.
 </methodology>
 
@@ -195,71 +194,35 @@ For each check you perform from the list above (Transport, Rate Limiting, Sessio
 
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When you have systematically analyzed all relevant endpoints and logic paths, you MUST generate two final files. Follow these instructions precisely.
+<mcp_tools>
+After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 3 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
-**1. Your Specialist Deliverable**
-First, synthesize all of your findings into a detailed Markdown report and save it using the save-deliverable CLI with --type AUTH_ANALYSIS.
-Your report MUST use the following structure precisely:
+**Tool catalog:**
+- `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
+- `set_strategic_intelligence` — Section 3 (Strategic Intelligence for Exploitation, with auth-specific sub-fields: authentication method, session token details, password policy)
+- `set_safe_vectors` — Section 4 (Secure by Design: Validated Components)
 
----
-# Authentication Analysis Report
+The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
 
-## 1. Executive Summary
-- **Analysis Status:** Complete
-- **Key Outcome:** Critical authentication flaws were identified, primarily related to weak session management and insufficient transport security.
-- **Purpose of this Document:** This report provides the strategic context on the application's authentication mechanisms, dominant flaw patterns, and key architectural details necessary to effectively exploit the vulnerabilities listed in the exploitation queue.
+**Call semantics:** All 3 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
-## 2. Dominant Vulnerability Patterns
+**Required vs recommended:**
+- `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-auth` agent reads.
+- `set_safe_vectors` is recommended. An empty array is acceptable on runs with no validated-secure components, but explicit emission is preferred over skipping.
 
-### Pattern 1: Weak Session Management
-- **Description:** A recurring and critical pattern was observed where session cookies lack proper security flags and session identifiers are not rotated after successful authentication.
-- **Implication:** Attackers can hijack user sessions through various vectors including network interception and session fixation attacks.
-- **Representative Findings:** `AUTH-VULN-01`, `AUTH-VULN-02`.
+**Relationship to the exploitation queue:** The exploitation queue (`auth_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 3 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</mcp_tools>
 
-### Pattern 2: Insufficient Rate Limiting on Authentication Endpoints
-- **Description:** Authentication endpoints such as login, password reset, and registration lack proper rate limiting mechanisms.
-- **Implication:** Attackers can perform brute force attacks, credential stuffing, and password spraying without being throttled.
-- **Representative Finding:** `AUTH-VULN-03`.
-
-## 3. Strategic Intelligence for Exploitation
-- **Authentication Method:** The system uses JWT-based authentication with tokens stored in cookies.
-- **Session Token Details:** The session is managed via a JWT stored in a cookie named `session_token`. The XSS specialist noted this cookie lacks the `HttpOnly` flag, making it accessible to script.
-- **Password Policy:** Basic password requirements are enforced client-side but server-side validation appears minimal.
-
-## 4. Secure by Design: Validated Components
-These components were analyzed and found to have robust defenses. They are low-priority for further testing.
-| Component/Flow | Endpoint/File Location | Defense Mechanism Implemented | Verdict |
-|---|---|---|---|
-| Password Hashing | `/controllers/authController.js` | Uses `bcrypt.compare` for constant-time password check. | SAFE |
-| Reset Token Generation | `/services/tokenService.js` | Generates high-entropy cryptographic reset tokens. | SAFE |
----
-
-</deliverable_instructions>
-
-<exploitation_queue_requirements>
-**Exploitation Queue (MANDATORY)**
-Regardless of whether vulnerabilities are found, you MUST create the exploitation queue using the save-deliverable CLI tool:
-- **If vulnerabilities found:** Run save-deliverable CLI with `--type AUTH_QUEUE --content '{"vulnerabilities": [...]}'` with each confirmed hypothesis following the `exploitation_queue_format`. Set `externally_exploitable` to `true` ONLY if exploitable via public internet without internal access.
-- **If no vulnerabilities found:** Run save-deliverable CLI with `--type AUTH_QUEUE --content '{"vulnerabilities": []}'`.
-- **QUEUE INCLUSION CRITERIA:** ONLY include vulnerabilities where `externally_exploitable = true`. Exclude any vulnerability requiring internal network access, VPN, or direct server access.
-This file serves as the handoff mechanism and must always be created to signal completion.
-</exploitation_queue_requirements>
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
 1.  **Systematic Analysis:** ALL relevant API endpoints and user-facing features identified in the reconnaissance deliverable must be analyzed for AuthN/AuthZ flaws.
-2.  **Deliverable Generation:** Both required deliverables must be successfully saved using the save-deliverable CLI tool:
-    - **CHUNKED WRITING (MANDATORY):**
-      1. Use the **Write** tool to create `deliverables/auth_analysis_deliverable.md` with the title and first major section
-      2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-      3. Repeat step 2 for all remaining sections
-      4. Run `save-deliverable` with `--type AUTH_ANALYSIS --file-path "deliverables/auth_analysis_deliverable.md"`
-      **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
-    - Exploitation queue: Run save-deliverable CLI with `--type AUTH_QUEUE --content '{"vulnerabilities": [...]}'`
+2.  **Deliverable Emission:** Call the 3 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` is recommended (an empty array is acceptable but explicit emission is preferred).
 
-**ONLY AFTER** both systematic analysis AND successful deliverable generation, announce "**AUTH ANALYSIS COMPLETE**" and stop.
+**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+
+**ONLY AFTER** both systematic analysis AND the required MCP tool calls have been completed, announce "**AUTH ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/vuln-authz.txt

@@ -19,10 +19,16 @@ Success criterion: A complete, code-backed analysis of every potential authoriza
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_code-path-rules.txt)
+
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <critical>
 **Your Professional Standard**
 - **Severity Context:** A flaw in authorization is a critical security failure. It allows privilege escalation, horizontal and vertical access control bypass, and unauthorized data access. These vulnerabilities enable attackers to access resources they shouldn't, escalate privileges, and compromise multi-tenant data isolation.
@@ -32,7 +38,7 @@ Success criterion: A complete, code-backed analysis of every potential authoriza
 </critical>
 
 <starting_context>
-- Your **primary source of truth** for authorization test targets is the reconnaissance report at `deliverables/recon_deliverable.md`. Look specifically for:
+- Your **primary source of truth** for authorization test targets is the reconnaissance report at `.shannon/deliverables/recon_deliverable.md`. Look specifically for:
   - **"Horizontal" section:** Endpoints where users access resources by ID that might belong to other users
   - **"Vertical" section:** Admin/privileged endpoints that regular users shouldn't access
   - **"Context" section:** Multi-step workflows where order/state matters
@@ -44,8 +50,8 @@ Success criterion: A complete, code-backed analysis of every potential authoriza
 
 **Phase Sequence:** RECON (Complete) → **AUTHZ ANALYSIS (You)** → EXPLOITATION (next phase)
 
-**Your Input:** `deliverables/recon_deliverable.md`, `deliverables/pre_recon_deliverable.md` (reconnaissance findings)
-**Your Output:** `deliverables/authz_exploitation_queue.json` (actionable vulnerabilities for exploitation)
+**Your Input:** `.shannon/deliverables/recon_deliverable.md`, `.shannon/deliverables/pre_recon_deliverable.md` (reconnaissance findings)
+**Your Output:** `.shannon/deliverables/authz_analysis_deliverable.md` (analysis report for exploitation phase)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture, endpoints, and data flows
@@ -80,11 +86,6 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 
 **Available Tools:**
 - **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authorization logic paths, and understand permission models. MANDATORY for all source code analysis.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows and role-based access controls), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
 - **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each endpoint that needs authorization analysis. Mark items as "in_progress" when working on them and "completed" when done.
@@ -93,7 +94,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 <data_format_specifications>
 
 <exploitation_queue_format>
-**Purpose:** Defines the structure for a "exploitation queue" saved via the save-deliverable CLI with --type AUTHZ_QUEUE.
+**Purpose:** Defines the format of the exploitation queue JSON.
 **Structure:** The `vulnerability` JSON object MUST follow this exact format:
 	{
 		"ID": "unique ID for each vulnerability (e.g., AUTHZ-VULN-01)",
@@ -125,7 +126,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 ### 1) Horizontal Authorization Analysis
 
 - **Create To Dos:**
-    For each item listed under **`deliverables/recon_deliverable.md` → section 8 "Horizontal"*, use the TodoWrite tool to create a task entry.
+    For each item listed under **`.shannon/deliverables/recon_deliverable.md` → section 8 "Horizontal"*, use the TodoWrite tool to create a task entry.
     
 - **Process:**
     - Start at the identified endpoint.
@@ -157,7 +158,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 ### 2) Vertical Authorization Analysis
 
 - **Create To Dos:**
-    For each item listed under **`deliverables/recon_deliverable.md` →  section 8 "Vertical"**, use the TodoWrite tool to create a task entry.
+    For each item listed under **`.shannon/deliverables/recon_deliverable.md` →  section 8 "Vertical"**, use the TodoWrite tool to create a task entry.
     
 - **Process:**
     - Start at the identified endpoint.
@@ -183,7 +184,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 ### 3) Context / Workflow Authorization Analysis
 
 - **Create To Dos:**
-    For each item listed under **`deliverables/recon_deliverable.md` → section 8 "Context"**, use the TodoWrite tool to create a task entry.
+    For each item listed under **`.shannon/deliverables/recon_deliverable.md` → section 8 "Context"**, use the TodoWrite tool to create a task entry.
     
 - **Process:**
     - Start at the endpoint that represents a step in a workflow.
@@ -238,7 +239,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 
 For each analysis you perform from the lists above, you must make a final **verdict**:
 
-- If the verdict is **`vulnerable`**, you must document the finding using the save-deliverable CLI to update the exploitation queue.
+- If the verdict is **`vulnerable`**, you must include the finding in your exploitation queue.
 - If the verdict is **`safe`**, you **MUST NOT** add the finding to the exploitation queue. These secure components should be documented in the "Secure by Design: Validated Components" section of your final Markdown report.
 </methodology>
 
@@ -271,100 +272,38 @@ For each analysis you perform from the lists above, you must make a final **verd
 
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When you have systematically analyzed all relevant endpoints and logic paths, you MUST generate three final files. Follow these instructions precisely to structure your output.
+<mcp_tools>
+After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
-**1. Your Specialist Deliverable**
+**Tool catalog:**
+- `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
+- `set_strategic_intelligence` — Section 3 (Strategic Intelligence for Exploitation, with authz-specific sub-fields: session management architecture, role/permission model, resource access patterns, workflow implementation)
+- `set_safe_vectors` — Section 4 (vectors confirmed secure)
+- `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-First, synthesize all of your findings into a single, detailed Markdown report and save it using the save-deliverable CLI with --type AUTHZ_ANALYSIS. This report is the official record of your work.
+The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects. For authz specifically, when populating `set_safe_vectors`, the renderer maps `subject` to the "Endpoint" column header and `location` to the "Guard Location" column header.
 
-Your report MUST use the following structure precisely:
+**Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
----
-# Authorization Analysis Report
+**Required vs recommended:**
+- `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-authz` agent reads.
+- `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure endpoints or no constraint gaps, but explicit emission is preferred over skipping.
 
-## 1. Executive Summary
+**Relationship to the exploitation queue:** The exploitation queue (`authz_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 4 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</mcp_tools>
 
-- **Analysis Status:** Complete  
-- **Key Outcome:** ONLY high-confidence authorization vulnerabilities (horizontal, vertical, and context/workflow) were recorded. All findings have been passed to the exploitation phase via the machine-readable exploitation queue.  
-- **Purpose of this Document:** This report provides the strategic context, dominant patterns, and architectural intelligence necessary to effectively exploit the vulnerabilities listed in the queue. It is intended to be read alongside the JSON deliverable.  
-
-## 2. Dominant Vulnerability Patterns
-
-### Pattern 1: Missing Ownership Validation (Horizontal | Vertical | Context)
-- **Description:** Multiple endpoints accept resource IDs without verifying the requesting user owns or has access to that resource
-- **Implication:** Users can access and modify other users' private data by manipulating ID parameters
-- **Representative:** AUTHZ-VULN-01, AUTHZ-VULN-03, AUTHZ-VULN-07
-
-etc...
-
-## 3. Strategic Intelligence for Exploitation
-examples:
-- **Session Management Architecture:**  
-  - Sessions use JWT tokens stored in cookies with `httpOnly` flag  
-  - User ID is extracted from token but not consistently validated against resource ownership  
-  - **Critical Finding:** The application trusts the user ID from the token without additional checks  
-
-- **Role/Permission Model:**  
-  - Three roles identified: `user`, `moderator`, `admin`  
-  - Role is stored in JWT token and database  
-  - **Critical Finding:** Role checks are inconsistently applied; many admin routes only check for authentication  
-
-- **Resource Access Patterns:**  
-  - Most endpoints use path parameters for resource IDs (e.g., `/api/users/{id}`)  
-  - **Critical Finding:** ID parameters are directly passed to database queries without ownership validation  
-
-- **Workflow Implementation:**  
-  - Multi-step processes use status fields in database  
-  - **Critical Finding:** Status transitions don't verify prior state completion  
-
-## 4. Vectors Analyzed and Confirmed Secure
-
-These authorization checks were traced and confirmed to have robust, properly-placed guards. They are **low-priority** for further testing.
-
-| **Endpoint** | **Guard Location** | **Defense Mechanism** | **Verdict** |
-|--------------|-------------------|----------------------|-------------|
-| `POST /api/auth/logout` | middleware/auth.js:45 | Session validation only (appropriate for logout) | SAFE |
-| `GET /api/public/*` | routes/public.js:12 | Public endpoints, no auth required by design | SAFE |
-| `GET /api/users/me` | controllers/user.js:89 | Uses session user ID, no parameter manipulation possible | SAFE |
-
-## 5. Analysis Constraints and Blind Spots
-examples: 
-- **Untraced Microservice Calls:**  
-  Some endpoints make calls to internal microservices. Authorization checks within these services could not be analyzed without their source code.
-
-- **Dynamic Permission System:**  
-  The application appears to have a dynamic permission system loaded from database. Runtime permission checks could not be fully validated through static analysis.
-
----
-
-</deliverable_instructions>
-
-<exploitation_queue_requirements>
-**Exploitation Queue (MANDATORY)**
-Regardless of whether vulnerabilities are found, you MUST create the exploitation queue using the save-deliverable CLI tool:
-- **If vulnerabilities found:** Run save-deliverable CLI with `--type AUTHZ_QUEUE --content '{"vulnerabilities": [...]}'` with each confirmed hypothesis following the `exploitation_queue_format`. Set `externally_exploitable` to `true` ONLY if exploitable via public internet without internal access.
-- **If no vulnerabilities found:** Run save-deliverable CLI with `--type AUTHZ_QUEUE --content '{"vulnerabilities": []}'`.
-- **QUEUE INCLUSION CRITERIA:** ONLY include vulnerabilities where `externally_exploitable = true`. Exclude any vulnerability requiring internal network access, VPN, or direct server access.
-This file serves as the handoff mechanism and must always be created to signal completion.
-</exploitation_queue_requirements>
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
-1. **Todo Completion:** ALL tasks in your TodoWrite list must be marked as "completed"
-2. **Deliverable Generation:** Both required deliverables must be successfully saved using the save-deliverable CLI tool:
-   - **CHUNKED WRITING (MANDATORY):**
-     1. Use the **Write** tool to create `deliverables/authz_analysis_deliverable.md` with the title and first major section
-     2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-     3. Repeat step 2 for all remaining sections
-     4. Run `save-deliverable` with `--type AUTHZ_ANALYSIS --file-path "deliverables/authz_analysis_deliverable.md"`
-     **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
-   - Exploitation queue: Run save-deliverable CLI with `--type AUTHZ_QUEUE --content '{"vulnerabilities": [...]}'`
+1. **Todo Completion:** ALL tasks in your TodoWrite list must be marked as "completed".
+2. **Deliverable Emission:** Call the 4 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
 
-**ONLY AFTER** both todo completion AND successful deliverable generation, announce "**AUTHORIZATION ANALYSIS COMPLETE**" and stop.
+**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+
+**ONLY AFTER** both todo completion AND the required MCP tool calls have been completed, announce "**AUTHORIZATION ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 
-**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you generate deliverables before completing comprehensive testing of all authorization vectors.
+**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you emit MCP deliverable calls before completing comprehensive testing of all authorization vectors.
 </conclusion_trigger>

apps/worker/prompts/vuln-injection.txt

@@ -20,10 +20,16 @@ Success criterion: Complete source-to-sink traces detailing path, sanitizers, si
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_code-path-rules.txt)
+
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <critical>
 **Your Professional Standard**
 -   **Severity Context:** A structural flaw in a backend command, whether an SQL query or a shell command, is one of the most severe classes of vulnerability in a SaaS application. It undermines the foundational trust of the system by creating the *potential* for data exposure (SQLi) or direct server compromise (Command Injection).
@@ -33,7 +39,7 @@ Success criterion: Complete source-to-sink traces detailing path, sanitizers, si
 </critical>
 
 <starting_context>
-- Your **single source of truth** for the application's structure is the reconnaissance report located at `deliverables/recon_deliverable.md`. You must derive your list of testable targets from this file.
+- Your **single source of truth** for the application's structure is the reconnaissance report located at `.shannon/deliverables/recon_deliverable.md`. You must derive your list of testable targets from this file.
 
 </starting_context>
 
@@ -42,8 +48,8 @@ Success criterion: Complete source-to-sink traces detailing path, sanitizers, si
 
 **Phase Sequence:** RECON (Complete) → **INJECTION ANALYSIS (You)** → EXPLOITATION (next phase)
 
-**Your Input:** `deliverables/recon_deliverable.md` (reconnaissance findings)
-**Your Output:** `deliverables/injection_exploitation_queue.json` (actionable vulnerabilities for exploitation)
+**Your Input:** `.shannon/deliverables/recon_deliverable.md` (reconnaissance findings)
+**Your Output:** `.shannon/deliverables/injection_analysis_deliverable.md` (analysis report for exploitation phase)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture, attack surfaces, endpoints, input vectors
@@ -80,11 +86,6 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 
 **Available Tools:**
 - **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, map query/command construction paths, and verify sanitization coverage. MANDATORY for all source code analysis.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows like password reset or registration), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
 - **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each injection source that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
@@ -93,7 +94,7 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 <data_format_specifications>
 
   <exploitation_queue_format>
-  **Purpose:** Defines the structure for a "exploitation queue" saved via the save-deliverable CLI with --type INJECTION_QUEUE.
+  **Purpose:** Defines the format of the exploitation queue JSON.
 
   **Structure:** The `vulnerability` JSON object MUST follow this exact format:
 		{
@@ -124,7 +125,7 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 
   - **Goal:** Prove whether untrusted input can influence the **structure** of a backend command (SQL or Shell) or reach sensitive **slots** without the correct defense. No live exploitation in this phase.
   - **1) Create a To Do for each Injection Source found in the Pre-Recon Deliverable
-		  - inside of deliverables/pre_recon_deliverable.md under the section "7. Injection Sources (Command Injection and SQL Injection)" use the TodoWrite tool to create a task for each discovered Injection Source. 
+		  - inside of .shannon/deliverables/pre_recon_deliverable.md under the section "7. Injection Sources (Command Injection and SQL Injection)" use the TodoWrite tool to create a task for each discovered Injection Source. 
 		  - Note: All sources are marked as Tainted until they Hit a Santiization that matches the sink context. normalizers (lowercasing, trimming, JSON parse, schema decode) — still **tainted**.
     - **2) Trace Data Flow Paths from Source to Sink**
 		    - For each source, your goal is to identify every unique "Data Flow Path" to a database sink. A path is a distinct route the data takes through the code.
@@ -147,8 +148,8 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
     - Include a short rationale (e.g., "context mismatch: regex escape on ORDER BY keyword slot").
     - If concat occurred **after** sanitization, treat that sanitization as **non-effective** for this path.
   - **6) Append to findings list (consistent fields)**
-	  -  **If the verdict is `vulnerable`:** Use the Write tool to log the finding in `deliverables/injection_exploitation_queue.json`. Set `externally_exploitable` to `true` ONLY if exploitable via public internet without internal access. Ensure all fields in the `exploitation_queue_format`, including a minimal `witness_payload`, are populated.
-    - **If the verdict is `safe`:** DO NOT add the finding to the exploitation queue. These secure vectors must be documented later in the "Vectors Analyzed and Confirmed Secure" section of your final Markdown report (`deliverables/injection_analysis_deliverable.md`).
+	  -  **If the verdict is `vulnerable`:** Include the finding in your exploitation queue. Set `externally_exploitable` to `true` ONLY if exploitable via public internet without internal access. Ensure all fields in the `exploitation_queue_format`, including a minimal `witness_payload`, are populated.
+    - **If the verdict is `safe`:** DO NOT add the finding to the exploitation queue. These secure vectors must be documented later in the "Vectors Analyzed and Confirmed Secure" section of your final Markdown report (`.shannon/deliverables/injection_analysis_deliverable.md`).
     - **If a single source is found to be vulnerable via multiple, distinct paths to different sinks, you must create a separate vulnerability entry in the exploitation queue for each unique vulnerable path.**
     - **QUEUE INCLUSION CRITERIA:** ONLY include vulnerabilities where `externally_exploitable = true`. Exclude any vulnerability requiring internal network access, VPN, or direct server access.
 
@@ -282,96 +283,38 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When you have systematically analyzed all input vectors, you MUST generate two final files. Follow these instructions precisely to structure your output.
+<mcp_tools>
+After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
-**1. Your Specialist Deliverable**
+**Tool catalog:**
+- `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
+- `set_strategic_intelligence` — Section 3 (Strategic Intelligence for Exploitation, with injection-specific sub-fields: defensive evasion / WAF analysis, error-based injection potential, confirmed database technology)
+- `set_safe_vectors` — Section 4 (vectors confirmed secure)
+- `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-First, synthesize all of your findings into a single, detailed Markdown report located at `deliverables/injection_analysis_deliverable.md`. This report is the official record of your work.
+The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
 
-Your report MUST use the following structure precisely:
+**Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
----
-#Injection Analysis Report (SQLi & Command Injection)
+**Required vs recommended:**
+- `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-injection` agent reads.
+- `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure vectors or no constraint gaps, but explicit emission is preferred over skipping.
 
-## 1. Executive Summary
+**Relationship to the exploitation queue:** The exploitation queue (`injection_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 4 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</mcp_tools>
 
-- **Analysis Status:** Complete  
-- **Key Outcome:** Several high-confidence SQL injection injection vulnerabilities (both SQLi and Command Injection) were identified. All findings have been passed to the exploitation phase via the machine-readable queue at `deliverables/injection_exploitation_queue.json`.  
-- **Purpose of this Document:** This report provides the strategic context, dominant patterns, and environmental intelligence necessary to effectively exploit the vulnerabilities listed in the queue. It is intended to be read alongside the JSON deliverable.  
-
-
-## 2. Dominant Vulnerability Patterns
--**Description:** descirption of the pattern found in the codebase
--**Implication:** implication of the pattern 
--**representative:** ID of a vulnerbaility that exhibits this pattern
-
-
-## 3. Strategic Intelligence for Exploitation
-
-- **Defensive Evasion (WAF Analysis):**  
-  - A Web Application Firewall is active and blocks common payloads containing boolean logic (`' OR '1'='1`) and `UNION SELECT`.  
-  - **Critical Bypass:** The WAF failed to block **time-based blind injection** payloads (e.g., `pg_sleep()`). It also does not inspect the structure of complex, nested queries.  
-  - **Recommendation:** Start with **time-based techniques** for exploitation.  
-
-- **Error-Based Injection Potential:**  
-  - The `/api/products` endpoint returns verbose PostgreSQL error messages to the client.  
-  - **Recommendation:** This endpoint is a prime target for **error-based exploitation** to rapidly extract schema and data.  
-
-- **Confirmed Database Technology:**  
-  - Database is **PostgreSQL**, confirmed via error syntax and function calls (`pg_sleep`).  
-  - All payloads should be PostgreSQL-specific.  
-
-## 4. Vectors Analyzed and Confirmed Secure
-
-These input vectors were traced and confirmed to have robust, context-appropriate defenses. They are **low-priority** for further testing.
-
-| **Source (Parameter/Key)** | **Endpoint/File Location**      | **Defense Mechanism Implemented**         | **Verdict** |
-|-----------------------------|--------------------------------|-------------------------------------------|-------------|
-| `username`                  | `/api/login`                  | Prepared Statement (Parameter Binding)     | SAFE        |
-| `user_id`                   | `/api/users/{user_id}`        | Input correctly cast to an Integer         | SAFE        |
-| `status`                    | `/api/orders`                 | Strict Whitelist Validation                | SAFE        |
-
-## 5. Analysis Constraints and Blind Spots
-
-- **Untraced Asynchronous Flows:**  
-  Analysis of a background job triggered by file uploads was inconclusive. The data flow passes through **RabbitMQ**, and static analysis could not confirm whether tainted data reaches a DB sink. This remains a blind spot.  
-
-- **Limited Visibility into Stored Procedures:**  
-  The application calls a stored procedure: `sp_calculate_report`. Source code for this procedure was not available. While inputs appear correctly typed, injection inside the procedure cannot be ruled out.  
-
----
-
-
-</deliverable_instructions>
-
-<exploitation_queue_requirements>
-**Exploitation Queue (MANDATORY)**
-
-Regardless of whether vulnerabilities are found, you MUST create the exploitation queue using the save-deliverable CLI tool:
-
-- **If vulnerabilities found:** Run save-deliverable CLI with `--type INJECTION_QUEUE --content '{"vulnerabilities": [...]}'` with each exploitable injection vulnerability (verdict: "vulnerable") following the exploitation_queue_format
-- **If no vulnerabilities found:** Run save-deliverable CLI with `--type INJECTION_QUEUE --content '{"vulnerabilities": []}'`
-
-This file serves as the handoff mechanism to the Exploitation phase and must always be created to signal completion of your analysis.
-</exploitation_queue_requirements>
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
-1. **Todo Completion:** ALL tasks in your TodoWrite list must be marked as "completed"
-2. **Deliverable Generation:** Both required deliverables must be successfully saved using the save-deliverable CLI tool:
-   - **CHUNKED WRITING (MANDATORY):**
-     1. Use the **Write** tool to create `deliverables/injection_analysis_deliverable.md` with the title and first major section
-     2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-     3. Repeat step 2 for all remaining sections
-     4. Run `save-deliverable` with `--type INJECTION_ANALYSIS --file-path "deliverables/injection_analysis_deliverable.md"`
-     **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
-   - Exploitation queue: Run save-deliverable CLI with `--type INJECTION_QUEUE --content '{"vulnerabilities": [...]}'`
+1. **Todo Completion:** ALL tasks in your TodoWrite list must be marked as "completed".
+2. **Deliverable Emission:** Call the 4 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
 
-**ONLY AFTER** both todo completion AND successful deliverable generation, announce "**INJECTION ANALYSIS COMPLETE**" and stop.
+**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+
+**ONLY AFTER** both todo completion AND the required MCP tool calls have been completed, announce "**INJECTION ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 
-**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you generate deliverables before completing comprehensive testing of all input vectors.
+**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you emit MCP deliverable calls before completing comprehensive testing of all input vectors.
 </conclusion_trigger>

apps/worker/prompts/vuln-ssrf.txt

@@ -19,10 +19,16 @@ Success criterion: A complete source-to-sink trace for every identified SSRF vul
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_code-path-rules.txt)
+
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <critical>
 **Your Professional Standard**
 - **Severity Context:** An SSRF flaw is a breach of network segmentation and trust boundaries. It allows attackers to leverage the application server as a proxy to access internal services, cloud metadata endpoints, or perform reconnaissance of internal networks. These vulnerabilities can lead to data exposure, privilege escalation, and complete network compromise.
@@ -32,7 +38,7 @@ Success criterion: A complete source-to-sink trace for every identified SSRF vul
 </critical>
 
 <starting_context>
-- Your primary source of truth for the application's structure is the reconnaissance report located at `deliverables/recon_deliverable.md`. You must derive your list of testable endpoints from this file.
+- Your primary source of truth for the application's structure is the reconnaissance report located at `.shannon/deliverables/recon_deliverable.md`. You must derive your list of testable endpoints from this file.
 </starting_context>
 
 <system_architecture>
@@ -40,8 +46,8 @@ Success criterion: A complete source-to-sink trace for every identified SSRF vul
 
 **Phase Sequence:** RECON (Complete) → **SSRF ANALYSIS (You)** → EXPLOITATION (next phase)
 
-**Your Input:** `deliverables/recon_deliverable.md`, `deliverables/pre_recon_deliverable.md` (reconnaissance findings)
-**Your Output:** `deliverables/ssrf_exploitation_queue.json` (actionable vulnerabilities for exploitation)
+**Your Input:** `.shannon/deliverables/recon_deliverable.md`, `.shannon/deliverables/pre_recon_deliverable.md` (reconnaissance findings)
+**Your Output:** `.shannon/deliverables/ssrf_analysis_deliverable.md` (analysis report for exploitation phase)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture, endpoints, and data flows
@@ -76,11 +82,6 @@ An **exploitable vulnerability** is a data flow where user-controlled input infl
 
 **Available Tools:**
 - **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace data flows, and understand HTTP client usage. MANDATORY for all source code analysis.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows involving URL redirection or proxy functionality), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
 - **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each SSRF sink that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
@@ -89,7 +90,7 @@ An **exploitable vulnerability** is a data flow where user-controlled input infl
 <data_format_specifications>
 
 <exploitation_queue_format>
-**Purpose:** Defines the structure for a "exploitation queue" saved via the save-deliverable CLI with --type SSRF_QUEUE.
+**Purpose:** Defines the format of the exploitation queue JSON.
 **Structure:** The `vulnerability` JSON object MUST follow this exact format:
 	{
 		"ID": "unique ID for each vulnerability json (SSRF-VULN-XX)",
@@ -114,7 +115,7 @@ An **exploitable vulnerability** is a data flow where user-controlled input infl
 # White-Box Vulnerability Analysis Procedure: Server-Side Request Forgery (SSRF)
 
 NOTE ON "FOR ALL": whenever an item begins with "for all …", use the TodoWrite tool to create a separate task for each relevant endpoint/flow that needs to be analyzed.
-From `deliverables/pre_recon_deliverable.md`, use Section 10 (SSRF Sinks) to guide your tasks.
+From `.shannon/deliverables/pre_recon_deliverable.md`, use Section 10 (SSRF Sinks) to guide your tasks.
 
 ## 1) Identify HTTP Client Usage Patterns
 - For all endpoints that accept URL parameters, callback URLs, webhook URLs, or file paths, trace how these inputs are processed.
@@ -166,7 +167,7 @@ From `deliverables/pre_recon_deliverable.md`, use Section 10 (SSRF Sinks) to gui
 
 ### **1) Create a To-Do Item for Each SSRF Sink**
 
-Inside `deliverables/pre_recon_deliverable.md` under section `##10. SSRF Sinks##`.
+Inside `.shannon/deliverables/pre_recon_deliverable.md` under section `##10. SSRF Sinks##`.
 
 Use the TodoWrite tool to create a task for each discovered sink (any server-side request composed even partially from user input).
 
@@ -228,7 +229,7 @@ Rule: when uncertain, round down (favor Medium/Low) to minimize false positives.
 # Documenting Findings (MANDATORY)
 For each check you perform from the list above, you must make a final **verdict**.
 
-- If the verdict is **`vulnerable`**, you must document the finding using the save-deliverable CLI to update the exploitation queue.
+- If the verdict is **`vulnerable`**, you must include the finding in your exploitation queue.
 - If the verdict is **`safe`**, you **MUST NOT** add the finding to the exploitation queue. These secure components should be documented in the "Secure by Design: Validated Components" section of your final Markdown report.
 </methodology>
 
@@ -242,71 +243,35 @@ For each check you perform from the list above, you must make a final **verdict*
 
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
-When you have systematically analyzed all relevant endpoints and request-making functions, you MUST generate two final files. Follow these instructions precisely.
+<mcp_tools>
+After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 3 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
-**1. Your Specialist Deliverable**
-First, synthesize all of your findings into a detailed Markdown report and save it using the save-deliverable CLI with --type SSRF_ANALYSIS.
-Your report MUST use the following structure precisely:
+**Tool catalog:**
+- `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
+- `set_strategic_intelligence` — Section 3 (Strategic Intelligence for Exploitation, with SSRF-specific sub-fields: HTTP client library, request architecture, internal services)
+- `set_safe_vectors` — Section 4 (Secure by Design: Validated Components)
 
----
-# SSRF Analysis Report
+The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
 
-## 1. Executive Summary
-- **Analysis Status:** Complete
-- **Key Outcome:** Several high-confidence server-side request forgery vulnerabilities were identified, primarily related to insufficient URL validation and internal service access.
-- **Purpose of this Document:** This report provides the strategic context on the application's outbound request mechanisms, dominant flaw patterns, and key architectural details necessary to effectively exploit the vulnerabilities listed in the exploitation queue.
+**Call semantics:** All 3 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
-## 2. Dominant Vulnerability Patterns
+**Required vs recommended:**
+- `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-ssrf` agent reads.
+- `set_safe_vectors` is recommended. An empty array is acceptable on runs with no validated-secure components, but explicit emission is preferred over skipping.
 
-### Pattern 1: Insufficient URL Validation  
-- **Description:** A recurring and critical pattern was observed where user-supplied URLs are not properly validated before being used in outbound HTTP requests.
-- **Implication:** Attackers can force the server to make requests to internal services, cloud metadata endpoints, or arbitrary external resources.
-- **Representative Findings:** `SSRF-VULN-01`, `SSRF-VULN-02`.
+**Relationship to the exploitation queue:** The exploitation queue (`ssrf_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 3 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</mcp_tools>
 
-### Pattern 2: Missing Protocol Restrictions
-- **Description:** Endpoints accepting URL parameters do not restrict the protocol schemes that can be used.
-- **Implication:** Attackers can use dangerous schemes like file:// or gopher:// to access local files or perform protocol smuggling.
-- **Representative Finding:** `SSRF-VULN-03`.
-
-## 3. Strategic Intelligence for Exploitation
-- **HTTP Client Library:** The application uses [HTTP_CLIENT_LIBRARY] for outbound requests.
-- **Request Architecture:** [DETAILS_ABOUT_REQUEST_PATTERNS]
-- **Internal Services:** [DISCOVERED_INTERNAL_SERVICES_OR_ENDPOINTS]
-
-## 4. Secure by Design: Validated Components
-These components were analyzed and found to have robust defenses. They are low-priority for further testing.
-| Component/Flow | Endpoint/File Location | Defense Mechanism Implemented | Verdict |
-|---|---|---|---|
-| Image Upload Processing | `/controllers/uploadController.js` | Uses strict allowlist for image URLs with protocol validation. | SAFE |
-| Webhook Configuration | `/services/webhookService.js` | Implements comprehensive IP address blocklist and timeout controls. | SAFE |
----
-
-</deliverable_instructions>
-
-<exploitation_queue_requirements>
-**Exploitation Queue (MANDATORY)**
-Regardless of whether vulnerabilities are found, you MUST create the exploitation queue using the save-deliverable CLI tool:
-- **If vulnerabilities found:** Run save-deliverable CLI with `--type SSRF_QUEUE --content '{"vulnerabilities": [...]}'` with each confirmed hypothesis following the `exploitation_queue_format`. Set `externally_exploitable` to `true` ONLY if exploitable via public internet without internal access.
-- **If no vulnerabilities found:** Run save-deliverable CLI with `--type SSRF_QUEUE --content '{"vulnerabilities": []}'`.
-- **QUEUE INCLUSION CRITERIA:** ONLY include vulnerabilities where `externally_exploitable = true`. Exclude any vulnerability requiring internal network access, VPN, or direct server access.
-This file serves as the handoff mechanism and must always be created to signal completion.
-</exploitation_queue_requirements>
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
 1.  **Systematic Analysis:** ALL relevant API endpoints and request-making features identified in the reconnaissance deliverable must be analyzed for SSRF vulnerabilities.
-2.  **Deliverable Generation:** Both required deliverables must be successfully saved using the save-deliverable CLI tool:
-    - **CHUNKED WRITING (MANDATORY):**
-      1. Use the **Write** tool to create `deliverables/ssrf_analysis_deliverable.md` with the title and first major section
-      2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-      3. Repeat step 2 for all remaining sections
-      4. Run `save-deliverable` with `--type SSRF_ANALYSIS --file-path "deliverables/ssrf_analysis_deliverable.md"`
-      **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
-    - Exploitation queue: Run save-deliverable CLI with `--type SSRF_QUEUE --content '{"vulnerabilities": [...]}'`
+2.  **Deliverable Emission:** Call the 3 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` is recommended (an empty array is acceptable but explicit emission is preferred).
 
-**ONLY AFTER** both systematic analysis AND successful deliverable generation, announce "**SSRF ANALYSIS COMPLETE**" and stop.
+**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+
+**ONLY AFTER** both systematic analysis AND the required MCP tool calls have been completed, announce "**SSRF ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/vuln-xss.txt

@@ -19,10 +19,16 @@ Success criterion: Live confirmation of XSS execution for every vulnerability th
 @include(shared/_rules.txt)
 </rules>
 
+@include(shared/_code-path-rules.txt)
+
+@include(shared/_shared-session.txt)
+
 <login_instructions>
 {{LOGIN_INSTRUCTIONS}}
 </login_instructions>
 
+@include(shared/_rules-of-engagement.txt)
+
 <critical>
 **Your Professional Standard**
 - Severity Context: An XSS flaw is a breach of trust between the user and the application. It grants an attacker the ability to execute arbitrary code within a victim's browser, leading to session hijacking, credential theft, and complete compromise of the user's account and data within the application.
@@ -32,7 +38,7 @@ Success criterion: Live confirmation of XSS execution for every vulnerability th
 </critical>
 
 <starting_context>
-- Your primary source of truth for the application's structure is the reconnaissance report located at deliverables/recon_deliverable.md. You must derive your list of testable targets from this file.
+- Your primary source of truth for the application's structure is the reconnaissance report located at .shannon/deliverables/recon_deliverable.md. You must derive your list of testable targets from this file.
 </starting_context>
 
 <system_architecture>
@@ -40,8 +46,8 @@ Success criterion: Live confirmation of XSS execution for every vulnerability th
 
 **Phase Sequence:** RECON (Complete) → **XSS ANALYSIS (You)** → EXPLOITATION (next phase)
 
-**Your Input:** `deliverables/recon_deliverable.md`, `deliverables/pre_recon_deliverable.md` (reconnaissance findings)
-**Your Output:** `deliverables/xss_exploitation_queue.json` (actionable vulnerabilities for exploitation)
+**Your Input:** `.shannon/deliverables/recon_deliverable.md`, `.shannon/deliverables/pre_recon_deliverable.md` (reconnaissance findings)
+**Your Output:** `.shannon/deliverables/xss_analysis_deliverable.md` (analysis report for exploitation phase)
 
 **WHAT HAPPENED BEFORE YOU:**
 - Reconnaissance agent mapped application architecture
@@ -72,7 +78,7 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 
 **CRITICAL TOOL USAGE RESTRICTIONS:**
 - NEVER use the Read tool for application source code analysis - ALWAYS delegate to Task agents for examining .js, .ts, .py, .php files and application logic. You MAY use Read
-  tool directly for these files: `deliverables/pre_recon_deliverable.md`, `deliverables/recon_deliverable.md`
+  tool directly for these files: `.shannon/deliverables/pre_recon_deliverable.md`, `.shannon/deliverables/recon_deliverable.md`
 - Direct the Task Agent to trace render contexts, sanitization coverage, and template/component boundaries before deciding on exploitability.
 - **ALWAYS delegate code analysis to Task agents**
 
@@ -81,18 +87,13 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 - **Terminal (curl):** MANDATORY for testing HTTP-based XSS vectors and observing raw HTML responses. Use for reflected XSS testing and JSONP injection testing.
 - **Browser Automation (playwright-cli skill):** MANDATORY for testing DOM-based XSS and form submission vectors. Invoke the `playwright-cli` skill to learn available commands. Use for stored XSS testing and client-side payload execution verification. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
 - **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each sink you need to analyze.
-- **save-deliverable (CLI Tool):** Saves your deliverable files with automatic validation.
-  - **Usage:** `save-deliverable --type <TYPE> --file-path <path>` or `--content '<json>'`
-  - **Returns:** JSON to stdout: `{"status":"success","filepath":"...","validated":true}` or `{"status":"error","message":"...","retryable":true}`
-  - **For large reports:** Write to disk first, then use `--file-path`. Do NOT pass large reports via `--content`.
-  - **For JSON queues:** You may use `--content '{"vulnerabilities": [...]}'`. Queue files are validated automatically.
 - **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
 </cli_tools>
 
 <data_format_specifications>
 
 <exploitation_queue_format>
-Purpose: Defines the structure for a "exploitation queue" saved via the save-deliverable CLI with --type XSS_QUEUE.
+Purpose: Defines the structure of the agent's final structured response.
 Structure: The vulnerability JSON object MUST follow this exact format:
 	{
 		"ID": "unique ID for each vulnerability json (XSS-VULN-XX)",
@@ -124,7 +125,7 @@ Structure: The vulnerability JSON object MUST follow this exact format:
 - **Core Principle:** Data is assumed to be tainted until a context-appropriate output encoder (sanitization) is encountered on its path to the sink.
 
 ### **1) Create a todo item for each XSS sink using the TodoWrite tool**
-Read deliverables/pre_recon_deliverable.md section ##9. XSS Sinks and Render Contexts## and use the **TodoWrite tool** to create a todo item for each discovered sink-context pair that needs analysis.
+Read .shannon/deliverables/pre_recon_deliverable.md section ##9. XSS Sinks and Render Contexts## and use the **TodoWrite tool** to create a todo item for each discovered sink-context pair that needs analysis.
 
 ### **2) Trace Each Sink Backward (Backward Taint Analysis)**
 For each pending item in your todo list (managed via TodoWrite tool), trace the origin of the data variable backward from the sink through the application logic. Your goal is to find either a valid sanitizer or an untrusted source. Mark each todo item as completed after you've fully analyzed that sink.
@@ -177,7 +178,7 @@ This rulebook is used for the **Early Termination** check in Step 2.
 - Include both safe and vulnerable paths to demonstrate **full coverage**.  
 - Craft a minimal `witness_payload` that proves control over the render context.  
 - For every path analyzed, you must document the outcome. The location of the documentation depends on the verdict:
-		- If the verdict is 'vulnerable', you MUST use the save-deliverable CLI to save the finding to the exploitation queue, including complete source-to-sink information.
+		- If the verdict is 'vulnerable', you MUST include the finding in your final structured response's exploitation queue, including complete source-to-sink information.
 		- If the verdict is 'safe', you MUST NOT add it to the exploitation queue. Instead, you will document these secure paths in the "Vectors Analyzed and Confirmed Secure" table of your final analysis report.
 - For vulnerable findings, craft a minimal witness_payload that proves control over the render context.
 
@@ -204,98 +205,36 @@ This rulebook is used for the **Early Termination** check in Step 2.
 
 </methodology_and_domain_expertise>
 
-<deliverable_instructions>
+<mcp_tools>
+After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
-When you have systematically analyzed all input vectors, you MUST generate two final files. Follow these instructions precisely.
+**Tool catalog:**
+- `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
+- `set_strategic_intelligence` — Section 3 (Strategic Intelligence for Exploitation, with XSS-specific sub-fields: CSP analysis, cookie security)
+- `set_safe_vectors` — Section 4 (vectors confirmed secure)
+- `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-## 1. Your Specialist Deliverable
+The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects. For XSS specifically, when populating `set_safe_vectors`, include the optional `render_context` field on each entry (HTML_BODY, HTML_ATTRIBUTE, JAVASCRIPT_STRING, URL_PARAM, or CSS_VALUE).
 
-- First, synthesize all of your findings into a single, detailed Markdown report located at  
-  `deliverables/xss_analysis_deliverable.md`.
+**Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
-- Your report MUST use the following structure precisely:
+**Required vs recommended:**
+- `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-xss` agent reads.
+- `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure vectors or no constraint gaps, but explicit emission is preferred over skipping.
 
+**Relationship to the exploitation queue:** The exploitation queue (`xss_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 4 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</mcp_tools>
 
-# Cross-Site Scripting (XSS) Analysis Report
-
-## 1. Executive Summary
-- **Analysis Status:** Complete  
-- **Key Outcome:** Several high-confidence XSS vulnerabilities were identified. All findings have been passed to the exploitation phase via `deliverables/xss_exploitation_queue.json`.  
-- **Purpose of this Document:** This report provides the strategic context, dominant patterns, and environmental intelligence necessary to effectively exploit the vulnerabilities.  
-
-## 2. Dominant Vulnerability Patterns
-
-**Pattern 1: Reflected XSS in Search Parameter**  
-- **Description:** A recurring pattern was observed where the main search parameter (`?q=`) is reflected directly into the HTML body without any output encoding.  
-- **Implication:** Any page with a search bar is likely vulnerable to basic reflected XSS. This is the easiest vector for exploitation.  
-- **Representative Findings:** XSS-VULN-01, XSS-VULN-03.  
-
-**Pattern 2: DOM-based XSS in URL Hash**  
-- **Description:** Client-side JavaScript reads from `location.hash` and writes the value into a div using `innerHTML` to dynamically load content, without sanitization.  
-- **Implication:** This allows for script execution without the payload ever being sent to the server, potentially bypassing server-side logs and WAFs.  
-- **Representative Finding:** XSS-VULN-02.  
-
-## 3. Strategic Intelligence for Exploitation
-
-**Content Security Policy (CSP) Analysis**  
-- **Current CSP:** `script-src 'self' https://trusted-cdn.com;`  
-- **Critical Bypass:** The trusted CDN hosts an old version of AngularJS, which is vulnerable to client-side template injection. This provides a clear path to bypass the CSP.  
-- **Recommendation:** Exploitation should focus on crafting AngularJS sandbox escape payloads.  
-
-**Cookie Security**  
-- **Observation:** The primary session cookie (`sessionid`) is missing the `HttpOnly` flag.  
-- **Recommendation:** This is a high-impact finding. The primary goal of exploitation should be to steal this cookie via `document.cookie`.  
-
-## 4. Vectors Analyzed and Confirmed Secure
-
-These input vectors were traced and confirmed to have robust, context-appropriate defenses.
-
-| Source (Parameter/Key) | Endpoint/File Location | Defense Mechanism Implemented | Render Context | Verdict |
-|--------------------------|-------------------------|--------------------------------|----------------|---------|
-| `username`              | `/profile`             | HTML Entity Encoding            | HTML_BODY      | SAFE    |
-| `redirect_url`          | `/login`               | Strict URL Whitelist Validation | URL_PARAM      | SAFE    |
-
-## 5. Analysis Constraints and Blind Spots
-
-- **Minified JavaScript:** Analysis of the primary client-side bundle (`app.min.js`) was difficult. Some DOM XSS vulnerabilities may have been missed due to obfuscated code.  
-
----
-
-  
-
-</deliverable_instructions>
-
-<exploitation_queue_requirements>
-
-## Exploitation Queue (MANDATORY)
-
-Regardless of whether vulnerabilities are found, you MUST create the exploitation queue using the save-deliverable CLI tool.
-
-- **If exploitable vulnerabilities found:**
-  Run save-deliverable CLI with `--type XSS_QUEUE --content '{"vulnerabilities": [...]}'` with each exploitable XSS vulnerability (verdict: "vulnerable") following the `exploitation_queue_format`. Set `externally_exploitable` to `true` ONLY if exploitable via public internet without internal access.
-
-- **If no exploitable vulnerabilities found:**
-  Run save-deliverable CLI with `--type XSS_QUEUE --content '{"vulnerabilities": []}'`
-
-- **QUEUE INCLUSION CRITERIA:** ONLY include vulnerabilities where `externally_exploitable = true`. Exclude any vulnerability requiring internal network access, VPN, or direct server access.
-
-This file is the mandatory handoff to the Exploitation phase.
-</exploitation_queue_requirements>
 
 <conclusion_trigger>
 COMPLETION REQUIREMENTS (ALL must be satisfied):
 
 1. Systematic Analysis: ALL input vectors identified from the reconnaissance deliverable must be analyzed.
-2. Deliverable Generation: Both required deliverables must be successfully saved using the save-deliverable CLI tool:
-   - **CHUNKED WRITING (MANDATORY):**
-     1. Use the **Write** tool to create `deliverables/xss_analysis_deliverable.md` with the title and first major section
-     2. Use the **Edit** tool to append each remaining section — match the last few lines of the file, then replace with those lines plus the new section content
-     3. Repeat step 2 for all remaining sections
-     4. Run `save-deliverable` with `--type XSS_ANALYSIS --file-path "deliverables/xss_analysis_deliverable.md"`
-     **WARNING:** Do NOT write the entire report in a single tool call — exceeds 32K output token limit. Split into multiple Write/Edit operations.
-   - Exploitation queue: Run save-deliverable CLI with `--type XSS_QUEUE --content '{"vulnerabilities": [...]}'`
+2. Deliverable Emission: Call the 4 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
 
-ONLY AFTER both systematic analysis AND successful deliverable generation, announce "XSS ANALYSIS COMPLETE" and stop.
+**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+
+ONLY AFTER both systematic analysis AND the required MCP tool calls have been completed, announce "XSS ANALYSIS COMPLETE" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

apps/worker/src/ai/audit-logger.ts

@@ -14,6 +14,7 @@ export interface AuditLogger {
   logToolStart(toolName: string, parameters: unknown): Promise<void>;
   logToolEnd(result: unknown): Promise<void>;
   logError(error: Error, duration: number, turns: number): Promise<void>;
+  logNote(category: string, message: string): Promise<void>;
 }
 
 class RealAuditLogger implements AuditLogger {
@@ -56,6 +57,10 @@ class RealAuditLogger implements AuditLogger {
       timestamp: formatTimestamp(),
     });
   }
+
+  async logNote(category: string, message: string): Promise<void> {
+    await this.auditSession.logWorkflowNote(category, message);
+  }
 }
 
 /** Null Object implementation - all methods are safe no-ops */
@@ -67,6 +72,8 @@ class NullAuditLogger implements AuditLogger {
   async logToolEnd(_result: unknown): Promise<void> {}
 
   async logError(_error: Error, _duration: number, _turns: number): Promise<void> {}
+
+  async logNote(_category: string, _message: string): Promise<void> {}
 }
 
 // Returns no-op when auditSession is null

apps/worker/src/ai/claude-executor.ts

@@ -6,9 +6,10 @@
 
 // Production Claude agent execution with retry, git checkpoints, and audit logging
 
-import { query } from '@anthropic-ai/claude-agent-sdk';
+import { type JsonSchemaOutputFormat, query } from '@anthropic-ai/claude-agent-sdk';
 import { fs, path } from 'zx';
 import type { AuditSession } from '../audit/index.js';
+import { deliverablesDir } from '../paths.js';
 import { isRetryableError, PentestError } from '../services/error-handling.js';
 import { AGENT_VALIDATORS } from '../session-manager.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
@@ -17,10 +18,9 @@ import { formatTimestamp } from '../utils/formatting.js';
 import { Timer } from '../utils/metrics.js';
 import { createAuditLogger } from './audit-logger.js';
 import { dispatchMessage } from './message-handlers.js';
-import { type ModelTier, resolveModel } from './models.js';
+import { type ModelTier, resolveModel, supportsAdaptiveThinking } from './models.js';
 import { detectExecutionContext, formatCompletionMessage, formatErrorOutput } from './output-formatters.js';
 import { createProgressManager } from './progress-manager.js';
-import { getActualModelName } from './router-utils.js';
 
 declare global {
   var SHANNON_DISABLE_LOADER: boolean | undefined;
@@ -39,6 +39,7 @@ export interface ClaudePromptResult {
   errorType?: string | undefined;
   prompt?: string | undefined;
   retryable?: boolean | undefined;
+  structuredOutput?: unknown;
 }
 
 function outputLines(lines: string[]): void {
@@ -71,7 +72,7 @@ async function writeErrorLog(
       },
       duration,
     };
-    const logPath = path.join(sourceDir, 'error.log');
+    const logPath = path.join(deliverablesDir(sourceDir), 'error.log');
     await fs.appendFile(logPath, `${JSON.stringify(errorLog)}\n`);
   } catch {
     // Best-effort error log writing - don't propagate failures
@@ -87,8 +88,8 @@ export async function validateAgentOutput(
   logger.info(`Validating ${agentName} agent output`);
 
   try {
-    // Check if agent completed successfully
-    if (!result.success || !result.result) {
+    // Check if agent completed successfully (text result OR structured output)
+    if (!result.success || (!result.result && result.structuredOutput === undefined)) {
       logger.error('Validation failed: Agent execution was unsuccessful');
       return false;
     }
@@ -132,6 +133,11 @@ export async function runClaudePrompt(
   auditSession: AuditSession | null = null,
   logger: ActivityLogger,
   modelTier: ModelTier = 'medium',
+  outputFormat?: JsonSchemaOutputFormat,
+  apiKey?: string,
+  deliverablesSubdir?: string,
+  providerConfig?: import('../types/config.js').ProviderConfig,
+  mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>,
 ): Promise<ClaudePromptResult> {
   // 1. Initialize timing and prompt
   const timer = new Timer(`agent-${description.toLowerCase().replace(/\s+/g, '-')}`);
@@ -150,22 +156,55 @@ export async function runClaudePrompt(
   // 3. Build env vars to pass to SDK subprocesses
   const sdkEnv: Record<string, string> = {
     CLAUDE_CODE_MAX_OUTPUT_TOKENS: process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS || '64000',
+    PLAYWRIGHT_MCP_OUTPUT_DIR: deliverablesSubdir
+      ? path.join(sourceDir, path.dirname(deliverablesSubdir), '.playwright-cli')
+      : path.join(sourceDir, '.shannon', '.playwright-cli'),
+    // apiKey from ContainerConfig takes precedence over process.env
+    ...(apiKey && { ANTHROPIC_API_KEY: apiKey }),
+    // Deliverables subdir for save-deliverable CLI tool
+    ...(deliverablesSubdir && { SHANNON_DELIVERABLES_SUBDIR: deliverablesSubdir }),
   };
+
+  // 3a. Apply structured provider config directly to sdkEnv (no process.env mutation)
+  if (providerConfig) {
+    switch (providerConfig.providerType) {
+      case 'bedrock':
+        sdkEnv.CLAUDE_CODE_USE_BEDROCK = '1';
+        if (providerConfig.awsRegion) sdkEnv.AWS_REGION = providerConfig.awsRegion;
+        if (providerConfig.awsAccessKeyId) sdkEnv.AWS_ACCESS_KEY_ID = providerConfig.awsAccessKeyId;
+        if (providerConfig.awsSecretAccessKey) sdkEnv.AWS_SECRET_ACCESS_KEY = providerConfig.awsSecretAccessKey;
+        break;
+      case 'vertex':
+        sdkEnv.CLAUDE_CODE_USE_VERTEX = '1';
+        if (providerConfig.gcpRegion) sdkEnv.CLOUD_ML_REGION = providerConfig.gcpRegion;
+        if (providerConfig.gcpProjectId) sdkEnv.ANTHROPIC_VERTEX_PROJECT_ID = providerConfig.gcpProjectId;
+        if (providerConfig.gcpCredentialsPath)
+          sdkEnv.GOOGLE_APPLICATION_CREDENTIALS = providerConfig.gcpCredentialsPath;
+        break;
+      case 'litellm_router':
+        if (providerConfig.baseUrl) sdkEnv.ANTHROPIC_BASE_URL = providerConfig.baseUrl;
+        if (providerConfig.authToken) sdkEnv.ANTHROPIC_AUTH_TOKEN = providerConfig.authToken;
+        break;
+      default:
+        // 'anthropic_api' or unset — apiKey already handled above
+        if (providerConfig.apiKey && !apiKey) sdkEnv.ANTHROPIC_API_KEY = providerConfig.apiKey;
+        break;
+    }
+  }
+
+  // 3b. Passthrough env vars not already set by providerConfig or apiKey
   const passthroughVars = [
-    'ANTHROPIC_API_KEY',
+    ...(!sdkEnv.ANTHROPIC_API_KEY ? ['ANTHROPIC_API_KEY'] : []),
     'CLAUDE_CODE_OAUTH_TOKEN',
-    'ANTHROPIC_BASE_URL',
-    'ANTHROPIC_AUTH_TOKEN',
-    'CLAUDE_CODE_USE_BEDROCK',
-    'AWS_REGION',
+    ...(!sdkEnv.ANTHROPIC_BASE_URL ? ['ANTHROPIC_BASE_URL'] : []),
+    ...(!sdkEnv.ANTHROPIC_AUTH_TOKEN ? ['ANTHROPIC_AUTH_TOKEN'] : []),
+    ...(!sdkEnv.CLAUDE_CODE_USE_BEDROCK ? ['CLAUDE_CODE_USE_BEDROCK'] : []),
+    ...(!sdkEnv.AWS_REGION ? ['AWS_REGION'] : []),
     'AWS_BEARER_TOKEN_BEDROCK',
-    'CLAUDE_CODE_USE_VERTEX',
-    'CLOUD_ML_REGION',
-    'ANTHROPIC_VERTEX_PROJECT_ID',
-    'GOOGLE_APPLICATION_CREDENTIALS',
-    'ANTHROPIC_SMALL_MODEL',
-    'ANTHROPIC_MEDIUM_MODEL',
-    'ANTHROPIC_LARGE_MODEL',
+    ...(!sdkEnv.CLAUDE_CODE_USE_VERTEX ? ['CLAUDE_CODE_USE_VERTEX'] : []),
+    ...(!sdkEnv.CLOUD_ML_REGION ? ['CLOUD_ML_REGION'] : []),
+    ...(!sdkEnv.ANTHROPIC_VERTEX_PROJECT_ID ? ['ANTHROPIC_VERTEX_PROJECT_ID'] : []),
+    ...(!sdkEnv.GOOGLE_APPLICATION_CREDENTIALS ? ['GOOGLE_APPLICATION_CREDENTIALS'] : []),
     'HOME',
     'PATH',
     'PLAYWRIGHT_MCP_EXECUTABLE_PATH',
@@ -178,14 +217,20 @@ export async function runClaudePrompt(
   }
 
   // 4. Configure SDK options
+  // Model override from providerConfig takes precedence over env-based resolveModel
+  const model = providerConfig?.modelOverrides?.[modelTier] ?? resolveModel(modelTier);
+  const adaptiveThinking = supportsAdaptiveThinking(model) && process.env.CLAUDE_ADAPTIVE_THINKING !== 'false';
   const options = {
-    model: resolveModel(modelTier),
+    model,
     maxTurns: 10_000,
     cwd: sourceDir,
     permissionMode: 'bypassPermissions' as const,
     allowDangerouslySkipPermissions: true,
     settingSources: ['user'] as ('user' | 'project' | 'local')[],
     env: sdkEnv,
+    ...(adaptiveThinking && { thinking: { type: 'adaptive' as const } }),
+    ...(outputFormat && { outputFormat }),
+    ...(mcpServers && Object.keys(mcpServers).length > 0 && { mcpServers }),
   };
 
   if (!execContext.useCleanOutput) {
@@ -243,6 +288,9 @@ export async function runClaudePrompt(
       model,
       partialCost: totalCost,
       apiErrorDetected,
+      ...(messageLoopResult.structuredOutput !== undefined && {
+        structuredOutput: messageLoopResult.structuredOutput,
+      }),
     };
   } catch (error) {
     // 9. Handle errors — log, write error file, return failure
@@ -273,6 +321,7 @@ interface MessageLoopResult {
   apiErrorDetected: boolean;
   cost: number;
   model?: string | undefined;
+  structuredOutput?: unknown;
 }
 
 interface MessageLoopDeps {
@@ -297,6 +346,7 @@ async function processMessageStream(
   let apiErrorDetected = false;
   let cost = 0;
   let model: string | undefined;
+  let structuredOutput: unknown | undefined;
   let lastHeartbeat = Date.now();
 
   for await (const message of query({ prompt: fullPrompt, options })) {
@@ -327,6 +377,9 @@ async function processMessageStream(
     if (dispatchResult.type === 'complete') {
       result = dispatchResult.result;
       cost = dispatchResult.cost;
+      if (dispatchResult.structuredOutput !== undefined) {
+        structuredOutput = dispatchResult.structuredOutput;
+      }
       break;
     }
 
@@ -334,12 +387,18 @@ async function processMessageStream(
       if (dispatchResult.apiErrorDetected) {
         apiErrorDetected = true;
       }
-      // Capture model from SystemInitMessage, but override with router model if applicable
       if (dispatchResult.model) {
-        model = getActualModelName(dispatchResult.model);
+        model = dispatchResult.model;
       }
     }
   }
 
-  return { turnCount, result, apiErrorDetected, cost, model };
+  return {
+    turnCount,
+    result,
+    apiErrorDetected,
+    cost,
+    model,
+    ...(structuredOutput !== undefined && { structuredOutput }),
+  };
 }

apps/worker/src/ai/message-handlers.ts

@@ -19,13 +19,13 @@ import {
   formatToolUseOutput,
 } from './output-formatters.js';
 import type { ProgressManager } from './progress-manager.js';
-import { getActualModelName } from './router-utils.js';
 import type {
   ApiErrorDetection,
   AssistantMessage,
   AssistantResult,
   ContentBlock,
   ExecutionContext,
+  ModelRefusalFallbackMessage,
   ResultData,
   ResultMessage,
   SystemInitMessage,
@@ -40,7 +40,10 @@ function extractMessageContent(message: AssistantMessage): string {
   const messageContent = message.message;
 
   if (Array.isArray(messageContent.content)) {
-    return messageContent.content.map((c: ContentBlock) => c.text || JSON.stringify(c)).join('\n');
+    return messageContent.content
+      .filter((c: ContentBlock) => c.type !== 'thinking' && c.type !== 'redacted_thinking')
+      .map((c: ContentBlock) => c.text || JSON.stringify(c))
+      .join('\n');
   }
 
   return String(messageContent.content);
@@ -162,6 +165,33 @@ function handleStructuredError(errorType: SDKAssistantMessageError, content: str
           true, // Retryable - may succeed with different content
         ),
       };
+    case 'overloaded':
+      return {
+        detected: true,
+        shouldThrow: new PentestError(
+          `Anthropic API overloaded (structured): ${content.slice(0, 100)}`,
+          'network',
+          true, // Retryable with backoff
+        ),
+      };
+    case 'model_not_found':
+      return {
+        detected: true,
+        shouldThrow: new PentestError(
+          `Model not found: ${content.slice(0, 100)}`,
+          'config',
+          false, // Not retryable - model ID is misconfigured
+        ),
+      };
+    case 'oauth_org_not_allowed':
+      return {
+        detected: true,
+        shouldThrow: new PentestError(
+          `Organization not allowed for this credential: ${content.slice(0, 100)}`,
+          'config',
+          false, // Not retryable - needs credential/org fix
+        ),
+      };
     default:
       return { detected: true };
   }
@@ -223,6 +253,10 @@ function handleResultMessage(message: ResultMessage): ResultData {
     }
   }
 
+  if (message.structured_output !== undefined) {
+    result.structuredOutput = message.structured_output;
+  }
+
   return result;
 }
 
@@ -259,7 +293,7 @@ function outputLines(lines: string[]): void {
 
 export type MessageDispatchAction =
   | { type: 'continue'; apiErrorDetected?: boolean | undefined; model?: string | undefined }
-  | { type: 'complete'; result: string | null; cost: number }
+  | { type: 'complete'; result: string | null; cost: number; structuredOutput?: unknown }
   | { type: 'throw'; error: Error };
 
 export interface MessageDispatchDeps {
@@ -305,12 +339,19 @@ export async function dispatchMessage(
     case 'system': {
       if (message.subtype === 'init') {
         const initMsg = message as SystemInitMessage;
-        const actualModel = getActualModelName(initMsg.model);
         if (!execContext.useCleanOutput) {
-          logger.info(`Model: ${actualModel}, Permission: ${initMsg.permissionMode}`);
+          logger.info(`Model: ${initMsg.model}, Permission: ${initMsg.permissionMode}`);
         }
-        // Return actual model for tracking in audit logs
-        return { type: 'continue', model: actualModel };
+        return { type: 'continue', model: initMsg.model };
+      }
+      if (message.subtype === 'model_refusal_fallback') {
+        const fallback = message as ModelRefusalFallbackMessage;
+        const category = fallback.api_refusal_category ?? 'policy';
+        await auditLogger.logNote(
+          'model-fallback',
+          `Model refused (${category}); fell back ${fallback.original_model} → ${fallback.fallback_model}`,
+        );
+        return { type: 'continue' };
       }
       return { type: 'continue' };
     }
@@ -338,7 +379,26 @@ export async function dispatchMessage(
     case 'result': {
       const resultData = handleResultMessage(message as ResultMessage);
       outputLines(formatResultOutput(resultData, !execContext.useCleanOutput));
-      return { type: 'complete', result: resultData.result, cost: resultData.cost };
+
+      if (resultData.subtype === 'error_max_structured_output_retries') {
+        return {
+          type: 'throw',
+          error: new PentestError(
+            'Structured output validation failed after max retries',
+            'validation',
+            true,
+            {},
+            ErrorCode.OUTPUT_VALIDATION_FAILED,
+          ),
+        };
+      }
+
+      return {
+        type: 'complete' as const,
+        result: resultData.result,
+        cost: resultData.cost,
+        ...(resultData.structuredOutput !== undefined && { structuredOutput: resultData.structuredOutput }),
+      };
     }
 
     default:

apps/worker/src/ai/models.ts

@@ -21,7 +21,7 @@ export type ModelTier = 'small' | 'medium' | 'large';
 const DEFAULT_MODELS: Readonly<Record<ModelTier, string>> = {
   small: 'claude-haiku-4-5-20251001',
   medium: 'claude-sonnet-4-6',
-  large: 'claude-opus-4-6',
+  large: 'claude-opus-4-8',
 };
 
 /** Resolve a model tier to a concrete model ID. */
@@ -35,3 +35,17 @@ export function resolveModel(tier: ModelTier = 'medium'): string {
       return process.env.ANTHROPIC_MEDIUM_MODEL || DEFAULT_MODELS.medium;
   }
 }
+
+/** Whether a model supports adaptive thinking. Opus 4.6, 4.7, and 4.8 only. */
+export function supportsAdaptiveThinking(model: string): boolean {
+  return /opus-4-[678]/.test(model);
+}
+
+/**
+ * Whether a model is in the Fable family. Fable's safety classifiers flag
+ * cybersecurity tasks and route them to Opus 4.8, so a security scan on Fable
+ * largely runs on Opus 4.8 anyway.
+ */
+export function isFableModel(model: string): boolean {
+  return /fable/i.test(model);
+}

apps/worker/src/ai/playwright-config-writer.ts

@@ -0,0 +1,90 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Writes <sourceDir>/.playwright/cli.config.json with stealth defaults so
+ * `playwright-cli open` auto-loads them from the agent's cwd. Skipped when a
+ * config already exists so user-provided files are never clobbered.
+ *
+ * NOTE: Playwright's MCP browser config treats `initScript` entries as file
+ * paths, not inline source. The stealth script is written alongside the config
+ * and referenced by absolute path. Inline strings silently fail the daemon.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const STEALTH_INIT_SCRIPT = `delete Object.getPrototypeOf(navigator).webdriver;
+
+Object.defineProperty(navigator, 'plugins', {
+  get: () => {
+    const arr = [
+      { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+      { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '' },
+      { name: 'Native Client', filename: 'internal-nacl-plugin', description: '' },
+    ];
+    arr.__proto__ = PluginArray.prototype;
+    return arr;
+  },
+});
+
+window.chrome = window.chrome || {};
+window.chrome.runtime = window.chrome.runtime || {
+  PlatformOs: { MAC: 'mac', WIN: 'win', ANDROID: 'android', CROS: 'cros', LINUX: 'linux', OPENBSD: 'openbsd' },
+  PlatformArch: { ARM: 'arm', X86_32: 'x86-32', X86_64: 'x86-64' },
+  PlatformNaclArch: { ARM: 'arm', X86_32: 'x86-32', X86_64: 'x86-64' },
+  RequestUpdateCheckStatus: { THROTTLED: 'throttled', NO_UPDATE: 'no_update', UPDATE_AVAILABLE: 'update_available' },
+  OnInstalledReason: { INSTALL: 'install', UPDATE: 'update', CHROME_UPDATE: 'chrome_update', SHARED_MODULE_UPDATE: 'shared_module_update' },
+  OnRestartRequiredReason: { APP_UPDATE: 'app_update', OS_UPDATE: 'os_update', PERIODIC: 'periodic' },
+};
+`;
+
+function buildStealthConfig(initScriptPath: string) {
+  return {
+    browser: {
+      browserName: 'chromium',
+      launchOptions: {
+        headless: true,
+        args: ['--disable-blink-features=AutomationControlled'],
+        ignoreDefaultArgs: ['--enable-automation'],
+      },
+      contextOptions: {
+        viewport: { width: 1920, height: 1080 },
+        locale: 'en-US',
+        extraHTTPHeaders: { 'Accept-Language': 'en-US,en;q=0.9' },
+        userAgent:
+          'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+      },
+      initScript: [initScriptPath],
+    },
+  };
+}
+
+export type StealthConfigWriteResult = 'wrote' | 'skipped-existing';
+
+export async function writePlaywrightStealthConfig(
+  sourceDir: string,
+): Promise<{ result: StealthConfigWriteResult; configPath: string }> {
+  const playwrightDir = path.join(sourceDir, '.playwright');
+  const configPath = path.join(playwrightDir, 'cli.config.json');
+  if (await pathExists(configPath)) {
+    return { result: 'skipped-existing', configPath };
+  }
+  const initScriptPath = path.join(playwrightDir, 'scripts', 'stealth.js');
+  await fs.mkdir(path.dirname(initScriptPath), { recursive: true });
+  await fs.writeFile(initScriptPath, STEALTH_INIT_SCRIPT);
+  await fs.writeFile(configPath, JSON.stringify(buildStealthConfig(initScriptPath), null, 2));
+  return { result: 'wrote', configPath };
+}

apps/worker/src/ai/queue-schemas.ts

@@ -0,0 +1,215 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Zod schema definitions for vulnerability exploitation queue structured outputs.
+ *
+ * Each vuln agent returns a structured JSON response matching its schema.
+ * The SDK validates the output against the JSON Schema generated from these Zod definitions.
+ */
+
+import type { JsonSchemaOutputFormat } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import type { AgentName } from '../types/agents.js';
+
+// === Common Fields ===
+
+const ANALYSIS_NOTES_DESCRIPTION = 'Plain context for defenders (caveats, scope, what is at risk). Not attack steps.';
+
+function notesField(exploit: boolean) {
+  const f = z.string().optional();
+  return exploit ? f : f.describe(ANALYSIS_NOTES_DESCRIPTION);
+}
+
+function makeBase(exploit: boolean) {
+  return z.object({
+    ID: z.string(),
+    vulnerability_type: z.string(),
+    externally_exploitable: z.boolean(),
+    confidence: z.string(),
+    notes: notesField(exploit),
+  });
+}
+
+// === Per-Vuln-Type Schemas (used for type inference; notes description is mode-agnostic for types) ===
+
+const baseVulnerability = makeBase(true);
+
+const InjectionVulnerability = baseVulnerability.extend({
+  source: z.string().optional(),
+  combined_sources: z.string().optional(),
+  path: z.string().optional(),
+  sink_call: z.string().optional(),
+  slot_type: z.string().optional(),
+  sanitization_observed: z.string().optional(),
+  concat_occurrences: z.string().optional(),
+  verdict: z.string().optional(),
+  mismatch_reason: z.string().optional(),
+  witness_payload: z.string().optional(),
+});
+
+const XssVulnerability = baseVulnerability.extend({
+  source: z.string().optional(),
+  source_detail: z.string().optional(),
+  path: z.string().optional(),
+  sink_function: z.string().optional(),
+  render_context: z.string().optional(),
+  encoding_observed: z.string().optional(),
+  verdict: z.string().optional(),
+  mismatch_reason: z.string().optional(),
+  witness_payload: z.string().optional(),
+});
+
+const AuthVulnerability = baseVulnerability.extend({
+  source_endpoint: z.string().optional(),
+  vulnerable_code_location: z.string().optional(),
+  missing_defense: z.string().optional(),
+  exploitation_hypothesis: z.string().optional(),
+  suggested_exploit_technique: z.string().optional(),
+});
+
+const SsrfVulnerability = baseVulnerability.extend({
+  source_endpoint: z.string().optional(),
+  vulnerable_parameter: z.string().optional(),
+  vulnerable_code_location: z.string().optional(),
+  missing_defense: z.string().optional(),
+  exploitation_hypothesis: z.string().optional(),
+  suggested_exploit_technique: z.string().optional(),
+});
+
+const AuthzVulnerability = baseVulnerability.extend({
+  endpoint: z.string().optional(),
+  vulnerable_code_location: z.string().optional(),
+  role_context: z.string().optional(),
+  guard_evidence: z.string().optional(),
+  side_effect: z.string().optional(),
+  reason: z.string().optional(),
+  minimal_witness: z.string().optional(),
+});
+
+// === Inferred Entry Types (consumed by renderer) ===
+
+export type InjectionFinding = z.infer<typeof InjectionVulnerability>;
+export type XssFinding = z.infer<typeof XssVulnerability>;
+export type AuthFinding = z.infer<typeof AuthVulnerability>;
+export type SsrfFinding = z.infer<typeof SsrfVulnerability>;
+export type AuthzFinding = z.infer<typeof AuthzVulnerability>;
+
+// === Convert to JSON Schema for SDK ===
+
+// NOTE: The SDK's AJV validator expects draft-07. Zod defaults to draft-2020-12 which
+// causes the SDK to silently skip structured output.
+function toOutputFormat(zodSchema: z.ZodType): JsonSchemaOutputFormat {
+  return { type: 'json_schema', schema: z.toJSONSchema(zodSchema, { target: 'draft-07' }) as Record<string, unknown> };
+}
+
+// === Per-Mode Output Format Builders ===
+// Two maps cached at module load; the only per-mode difference is the
+// description on the `notes` field, which steers the LLM's writing.
+
+function buildOutputFormats(exploit: boolean): Partial<Record<AgentName, JsonSchemaOutputFormat>> {
+  const base = makeBase(exploit);
+  return {
+    'injection-vuln': toOutputFormat(
+      z.object({
+        vulnerabilities: z.array(
+          base.extend({
+            source: z.string().optional(),
+            combined_sources: z.string().optional(),
+            path: z.string().optional(),
+            sink_call: z.string().optional(),
+            slot_type: z.string().optional(),
+            sanitization_observed: z.string().optional(),
+            concat_occurrences: z.string().optional(),
+            verdict: z.string().optional(),
+            mismatch_reason: z.string().optional(),
+            witness_payload: z.string().optional(),
+          }),
+        ),
+      }),
+    ),
+    'xss-vuln': toOutputFormat(
+      z.object({
+        vulnerabilities: z.array(
+          base.extend({
+            source: z.string().optional(),
+            source_detail: z.string().optional(),
+            path: z.string().optional(),
+            sink_function: z.string().optional(),
+            render_context: z.string().optional(),
+            encoding_observed: z.string().optional(),
+            verdict: z.string().optional(),
+            mismatch_reason: z.string().optional(),
+            witness_payload: z.string().optional(),
+          }),
+        ),
+      }),
+    ),
+    'auth-vuln': toOutputFormat(
+      z.object({
+        vulnerabilities: z.array(
+          base.extend({
+            source_endpoint: z.string().optional(),
+            vulnerable_code_location: z.string().optional(),
+            missing_defense: z.string().optional(),
+            exploitation_hypothesis: z.string().optional(),
+            suggested_exploit_technique: z.string().optional(),
+          }),
+        ),
+      }),
+    ),
+    'ssrf-vuln': toOutputFormat(
+      z.object({
+        vulnerabilities: z.array(
+          base.extend({
+            source_endpoint: z.string().optional(),
+            vulnerable_parameter: z.string().optional(),
+            vulnerable_code_location: z.string().optional(),
+            missing_defense: z.string().optional(),
+            exploitation_hypothesis: z.string().optional(),
+            suggested_exploit_technique: z.string().optional(),
+          }),
+        ),
+      }),
+    ),
+    'authz-vuln': toOutputFormat(
+      z.object({
+        vulnerabilities: z.array(
+          base.extend({
+            endpoint: z.string().optional(),
+            vulnerable_code_location: z.string().optional(),
+            role_context: z.string().optional(),
+            guard_evidence: z.string().optional(),
+            side_effect: z.string().optional(),
+            reason: z.string().optional(),
+            minimal_witness: z.string().optional(),
+          }),
+        ),
+      }),
+    ),
+  };
+}
+
+const OUTPUT_FORMATS_EXPLOIT = buildOutputFormats(true);
+const OUTPUT_FORMATS_ANALYSIS = buildOutputFormats(false);
+
+const VULN_AGENT_QUEUE_FILENAMES: Partial<Record<AgentName, string>> = {
+  'injection-vuln': 'injection_exploitation_queue.json',
+  'xss-vuln': 'xss_exploitation_queue.json',
+  'auth-vuln': 'auth_exploitation_queue.json',
+  'ssrf-vuln': 'ssrf_exploitation_queue.json',
+  'authz-vuln': 'authz_exploitation_queue.json',
+};
+
+/** Returns the structured output format for a vuln agent, or undefined for non-vuln agents. */
+export function getOutputFormat(agentName: AgentName, exploit = true): JsonSchemaOutputFormat | undefined {
+  return (exploit ? OUTPUT_FORMATS_EXPLOIT : OUTPUT_FORMATS_ANALYSIS)[agentName];
+}
+
+/** Returns the queue filename for a vuln agent, or undefined for non-vuln agents. */
+export function getQueueFilename(agentName: AgentName): string | undefined {
+  return VULN_AGENT_QUEUE_FILENAMES[agentName];
+}

apps/worker/src/ai/router-utils.ts

@@ -1,27 +0,0 @@
-// Copyright (C) 2025 Keygraph, Inc.
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License version 3
-// as published by the Free Software Foundation.
-
-/**
- * Get the actual model name being used.
- * When using claude-code-router, the SDK reports its configured model (claude-sonnet)
- * but the actual model is determined by ROUTER_DEFAULT env var.
- */
-export function getActualModelName(sdkReportedModel?: string): string | undefined {
-  const routerBaseUrl = process.env.ANTHROPIC_BASE_URL;
-  const routerDefault = process.env.ROUTER_DEFAULT;
-
-  // If router mode is active and ROUTER_DEFAULT is set, use that
-  if (routerBaseUrl && routerDefault) {
-    // ROUTER_DEFAULT format: "provider,model" (e.g., "gemini,gemini-2.5-pro")
-    const parts = routerDefault.split(',');
-    if (parts.length >= 2) {
-      return parts.slice(1).join(','); // Handle model names with commas
-    }
-  }
-
-  // Fall back to SDK-reported model
-  return sdkReportedModel;
-}

apps/worker/src/ai/settings-writer.ts

@@ -0,0 +1,41 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Writes ~/.claude/settings.json with permissions.deny rules derived from
+ * `code_path` avoid patterns. The SDK reads this via `settingSources: ['user']`;
+ * deny rules fire even in `bypassPermissions` mode.
+ */
+
+import os from 'node:os';
+import { fs, path } from 'zx';
+import type { DistributedConfig } from '../types/config.js';
+
+const FILE_TOOLS = ['Read', 'Edit'] as const;
+
+function denyEntriesFor(pattern: string): string[] {
+  const arg = `./${pattern.replace(/^[./]+/, '')}`;
+  return FILE_TOOLS.map((tool) => `${tool}(${arg})`);
+}
+
+export async function writeUserSettingsForCodePathAvoids(config: DistributedConfig | null): Promise<void> {
+  const avoidPatterns = (config?.avoid ?? []).filter((r) => r.type === 'code_path').map((r) => r.value);
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+
+  if (avoidPatterns.length === 0) {
+    await fs.remove(settingsPath);
+    return;
+  }
+
+  const settings = {
+    permissions: {
+      deny: avoidPatterns.flatMap(denyEntriesFor),
+    },
+  };
+
+  await fs.ensureDir(path.dirname(settingsPath));
+  await fs.writeJson(settingsPath, settings, { spaces: 2 });
+}

apps/worker/src/ai/types.ts

@@ -34,6 +34,7 @@ export interface ResultData {
   subtype?: string;
   stop_reason?: string | null;
   permissionDenials: number;
+  structuredOutput?: unknown;
 }
 
 export interface ToolUseData {
@@ -51,6 +52,8 @@ export interface ToolResultData {
 export interface ContentBlock {
   type?: string;
   text?: string;
+  thinking?: string;
+  data?: string;
 }
 
 export interface AssistantMessage {
@@ -69,6 +72,7 @@ export interface ResultMessage {
   subtype?: string;
   stop_reason?: string | null;
   permission_denials?: unknown[];
+  structured_output?: unknown;
 }
 
 export interface ToolUseMessage {
@@ -94,6 +98,15 @@ export interface SystemInitMessage {
   permissionMode?: string;
 }
 
+/** Emitted when a model refuses a request and the SDK falls back to another model (e.g. Fable 5 routing cybersecurity tasks to Opus 4.8). */
+export interface ModelRefusalFallbackMessage {
+  type: 'system';
+  subtype: 'model_refusal_fallback';
+  original_model: string;
+  fallback_model: string;
+  api_refusal_category?: string | null;
+}
+
 export interface UserMessage {
   type: 'user';
 }

apps/worker/src/audit/audit-session.ts

@@ -28,7 +28,7 @@ const sessionMutex = new SessionMutex();
  * AuditSession - Main audit system facade
  */
 export class AuditSession {
-  private sessionMetadata: SessionMetadata;
+  readonly sessionMetadata: SessionMetadata;
   private sessionId: string;
   private metricsTracker: MetricsTracker;
   private workflowLogger: WorkflowLogger;
@@ -158,6 +158,14 @@ export class AuditSession {
     }
   }
 
+  /**
+   * Write a human-readable note to the unified workflow log (e.g. a model
+   * refusal fallback). Independent of agent event logging.
+   */
+  async logWorkflowNote(category: string, message: string): Promise<void> {
+    await this.workflowLogger.logEvent(category, message);
+  }
+
   /**
    * End agent execution (mutex-protected)
    */
@@ -202,7 +210,7 @@ export class AuditSession {
   /**
    * Update session status
    */
-  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed'): Promise<void> {
+  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed' | 'cancelled'): Promise<void> {
     await this.ensureInitialized();
 
     const unlock = await sessionMutex.lock(this.sessionId);

apps/worker/src/audit/metrics-tracker.ts

@@ -57,7 +57,7 @@ interface SessionData {
     id: string;
     webUrl: string;
     repoPath?: string;
-    status: 'in-progress' | 'completed' | 'failed';
+    status: 'in-progress' | 'completed' | 'failed' | 'cancelled';
     createdAt: string;
     completedAt?: string;
     originalWorkflowId?: string; // First workflow that created this workspace
@@ -232,12 +232,12 @@ export class MetricsTracker {
   /**
    * Update session status
    */
-  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed'): Promise<void> {
+  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed' | 'cancelled'): Promise<void> {
     if (!this.data) return;
 
     this.data.session.status = status;
 
-    if (status === 'completed' || status === 'failed') {
+    if (status === 'completed' || status === 'failed' || status === 'cancelled') {
       this.data.session.completedAt = formatTimestamp();
     }
 

apps/worker/src/audit/utils.ts

@@ -11,7 +11,6 @@
  * All functions are pure and crash-safe.
  */
 
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { WORKSPACES_DIR } from '../paths.js';
 import { ensureDirectory } from '../utils/file-io.js';
@@ -75,6 +74,14 @@ export function generateSessionJsonPath(sessionMetadata: SessionMetadata): strin
   return path.join(auditPath, 'session.json');
 }
 
+/**
+ * Path to the shared authenticated browser session saved by the preflight
+ * validator and consumed by downstream agents via `_shared-session.txt`.
+ */
+export function authStateFile(sessionMetadata: SessionMetadata): string {
+  return path.join(generateAuditPath(sessionMetadata), 'auth-state.json');
+}
+
 /**
  * Generate path to workflow.log file
  */
@@ -98,33 +105,3 @@ export async function initializeAuditStructure(sessionMetadata: SessionMetadata)
   await ensureDirectory(promptsPath);
   await ensureDirectory(deliverablesPath);
 }
-
-/**
- * Copy deliverable files from repo to workspaces for self-contained audit trail.
- * No-ops if source directory doesn't exist. Idempotent and parallel-safe.
- */
-export async function copyDeliverablesToAudit(sessionMetadata: SessionMetadata, repoPath: string): Promise<void> {
-  const sourceDir = path.join(repoPath, 'deliverables');
-  const destDir = path.join(generateAuditPath(sessionMetadata), 'deliverables');
-
-  let entries: string[];
-  try {
-    entries = await fs.readdir(sourceDir);
-  } catch {
-    // Source directory doesn't exist yet — nothing to copy
-    return;
-  }
-
-  await ensureDirectory(destDir);
-
-  for (const entry of entries) {
-    const sourcePath = path.join(sourceDir, entry);
-    const destPath = path.join(destDir, entry);
-
-    // Only copy files, skip subdirectories
-    const stat = await fs.stat(sourcePath);
-    if (stat.isFile()) {
-      await fs.copyFile(sourcePath, destPath);
-    }
-  }
-}

apps/worker/src/audit/workflow-logger.ts

@@ -12,6 +12,7 @@
  */
 
 import fs from 'node:fs/promises';
+import { isFableModel, resolveModel } from '../ai/models.js';
 import { formatDuration, formatTimestamp } from '../utils/formatting.js';
 import { LogStream } from './log-stream.js';
 import { generateWorkflowLogPath, type SessionMetadata } from './utils.js';
@@ -30,7 +31,7 @@ export interface AgentMetricsSummary {
 }
 
 export interface WorkflowSummary {
-  status: 'completed' | 'failed';
+  status: 'completed' | 'failed' | 'cancelled';
   totalDurationMs: number;
   totalCostUsd: number;
   completedAgents: string[];
@@ -77,18 +78,31 @@ export class WorkflowLogger {
    * Write header to log file
    */
   private async writeHeader(): Promise<void> {
-    const header = [
+    const lines = [
       `================================================================================`,
       `Shannon Pentest - Workflow Log`,
       `================================================================================`,
       `Workflow ID: ${this.workflowId ?? this.sessionMetadata.id}`,
       `Target URL:  ${this.sessionMetadata.webUrl}`,
       `Started:     ${formatTimestamp()}`,
-      `================================================================================`,
-      ``,
-    ].join('\n');
+    ];
 
-    return this.logStream.write(header);
+    // Surface Fable usage: its safety classifiers route cybersecurity tasks to
+    // Opus 4.8, so those phases run on Opus 4.8 regardless of the tier setting.
+    const fableTiers = (['small', 'medium', 'large'] as const)
+      .map((tier) => ({ tier, model: resolveModel(tier) }))
+      .filter(({ model }) => isFableModel(model));
+    if (fableTiers.length > 0) {
+      const tierList = fableTiers.map(({ tier, model }) => `${tier} (${model})`).join(', ');
+      lines.push(
+        `Note:        ${tierList} set to a Fable model. Fable's safety classifiers`,
+        `             route cybersecurity tasks to Opus 4.8, so those phases run on Opus 4.8.`,
+      );
+    }
+
+    lines.push(`================================================================================`, ``);
+
+    return this.logStream.write(lines.join('\n'));
   }
 
   /**

apps/worker/src/config-parser.ts

@@ -10,7 +10,13 @@ import type { FormatsPlugin } from 'ajv-formats';
 import yaml from 'js-yaml';
 import { fs } from 'zx';
 import { PentestError } from './services/error-handling.js';
-import type { Authentication, Config, DistributedConfig, Rule } from './types/config.js';
+import {
+  ALL_VULN_CLASSES,
+  type Authentication,
+  type Config,
+  type DistributedConfig,
+  type Rule,
+} from './types/config.js';
 import { ErrorCode } from './types/errors.js';
 
 // Handle ESM/CJS interop for ajv-formats using require
@@ -258,6 +264,87 @@ export const parseConfig = async (configPath: string): Promise<Config> => {
   }
 };
 
+/**
+ * Parse a raw YAML string into a validated Config object.
+ *
+ * Same validation as parseConfig but accepts a string instead of a file path.
+ * Used when config YAML is passed inline (e.g., from a parent workflow).
+ */
+export const parseConfigYAML = (yamlContent: string): Config => {
+  if (!yamlContent.trim()) {
+    throw new PentestError(
+      'Configuration YAML string is empty',
+      'config',
+      false,
+      {},
+      ErrorCode.CONFIG_VALIDATION_FAILED,
+    );
+  }
+
+  let config: unknown;
+  try {
+    config = yaml.load(yamlContent, {
+      schema: yaml.FAILSAFE_SCHEMA,
+      json: false,
+    });
+  } catch (yamlError) {
+    const errMsg = yamlError instanceof Error ? yamlError.message : String(yamlError);
+    throw new PentestError(
+      `YAML parsing failed: ${errMsg}`,
+      'config',
+      false,
+      { originalError: errMsg },
+      ErrorCode.CONFIG_PARSE_ERROR,
+    );
+  }
+
+  if (config === null || config === undefined) {
+    throw new PentestError(
+      'Configuration YAML resulted in null/undefined after parsing',
+      'config',
+      false,
+      {},
+      ErrorCode.CONFIG_PARSE_ERROR,
+    );
+  }
+
+  validateConfig(config as Config);
+  return config as Config;
+};
+
+function checkDeprecatedFields(config: Config): void {
+  const messages: string[] = [];
+
+  const checkRules = (rules: unknown, where: string): void => {
+    if (!Array.isArray(rules)) return;
+    rules.forEach((rule, idx) => {
+      if (typeof rule !== 'object' || rule === null) return;
+      const r = rule as Record<string, unknown>;
+      if (r.type === 'path') {
+        messages.push(`rules.${where}[${idx}].type: 'path' has been renamed to 'url_path'.`);
+      }
+      if ('url_path' in r && !('value' in r)) {
+        messages.push(`rules.${where}[${idx}]: the rule field 'url_path' has been renamed to 'value'.`);
+      }
+    });
+  };
+
+  const raw = config as Record<string, unknown>;
+  const rules = raw.rules as { avoid?: unknown; focus?: unknown } | undefined;
+  checkRules(rules?.avoid, 'avoid');
+  checkRules(rules?.focus, 'focus');
+
+  if (messages.length > 0) {
+    throw new PentestError(
+      `Configuration uses deprecated fields. Please update:\n  - ${messages.join('\n  - ')}`,
+      'config',
+      false,
+      { deprecatedFields: messages },
+      ErrorCode.CONFIG_VALIDATION_FAILED,
+    );
+  }
+}
+
 const validateConfig = (config: Config): void => {
   if (!config || typeof config !== 'object') {
     throw new PentestError(
@@ -279,6 +366,8 @@ const validateConfig = (config: Config): void => {
     );
   }
 
+  checkDeprecatedFields(config);
+
   const isValid = validateSchema(config);
   if (!isValid) {
     const errors = validateSchema.errors || [];
@@ -294,10 +383,16 @@ const validateConfig = (config: Config): void => {
 
   performSecurityValidation(config);
 
-  if (!config.rules && !config.authentication && !config.description) {
-    console.warn(
-      '⚠️  Configuration file contains no rules, authentication, or description. The pentest will run without any scoping restrictions or login capabilities.',
-    );
+  const hasAnySteering =
+    !!config.rules ||
+    !!config.authentication ||
+    !!config.description ||
+    !!config.vuln_classes ||
+    config.exploit !== undefined ||
+    !!config.report ||
+    !!config.rules_of_engagement;
+  if (!hasAnySteering) {
+    console.warn('⚠️  Configuration file contains no steering fields. The pentest will run with all defaults.');
   } else if (config.rules && !config.rules.avoid && !config.rules.focus) {
     console.warn('⚠️  Configuration file contains no rules. The pentest will run without any scoping restrictions.');
   }
@@ -333,15 +428,6 @@ const performSecurityValidation = (config: Config): void => {
             ErrorCode.CONFIG_VALIDATION_FAILED,
           );
         }
-        if (pattern.test(auth.credentials.password)) {
-          throw new PentestError(
-            `authentication.credentials.password contains potentially dangerous pattern: ${pattern.source}`,
-            'config',
-            false,
-            { field: 'credentials.password', pattern: pattern.source },
-            ErrorCode.CONFIG_VALIDATION_FAILED,
-          );
-        }
       }
     }
 
@@ -384,6 +470,34 @@ const performSecurityValidation = (config: Config): void => {
       }
     }
   }
+
+  if (config.rules_of_engagement) {
+    for (const pattern of DANGEROUS_PATTERNS) {
+      if (pattern.test(config.rules_of_engagement)) {
+        throw new PentestError(
+          `rules_of_engagement contains potentially dangerous pattern: ${pattern.source}`,
+          'config',
+          false,
+          { field: 'rules_of_engagement', pattern: pattern.source },
+          ErrorCode.CONFIG_VALIDATION_FAILED,
+        );
+      }
+    }
+  }
+
+  if (config.report?.guidance) {
+    for (const pattern of DANGEROUS_PATTERNS) {
+      if (pattern.test(config.report.guidance)) {
+        throw new PentestError(
+          `report.guidance contains potentially dangerous pattern: ${pattern.source}`,
+          'config',
+          false,
+          { field: 'report.guidance', pattern: pattern.source },
+          ErrorCode.CONFIG_VALIDATION_FAILED,
+        );
+      }
+    }
+  }
 };
 
 const validateRulesSecurity = (rules: Rule[] | undefined, ruleType: string): void => {
@@ -391,12 +505,12 @@ const validateRulesSecurity = (rules: Rule[] | undefined, ruleType: string): voi
 
   rules.forEach((rule, index) => {
     for (const pattern of DANGEROUS_PATTERNS) {
-      if (pattern.test(rule.url_path)) {
+      if (pattern.test(rule.value)) {
         throw new PentestError(
-          `rules.${ruleType}[${index}].url_path contains potentially dangerous pattern: ${pattern.source}`,
+          `rules.${ruleType}[${index}].value contains potentially dangerous pattern: ${pattern.source}`,
           'config',
           false,
-          { field: `rules.${ruleType}[${index}].url_path`, pattern: pattern.source },
+          { field: `rules.${ruleType}[${index}].value`, pattern: pattern.source },
           ErrorCode.CONFIG_VALIDATION_FAILED,
         );
       }
@@ -416,13 +530,25 @@ const validateRulesSecurity = (rules: Rule[] | undefined, ruleType: string): voi
 };
 
 const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number): void => {
-  const field = `rules.${ruleType}[${index}].url_path`;
+  const field = `rules.${ruleType}[${index}].value`;
 
   switch (rule.type) {
-    case 'path':
-      if (!rule.url_path.startsWith('/')) {
+    case 'url_path':
+      if (!rule.value.startsWith('/')) {
         throw new PentestError(
-          `${field} for type 'path' must start with '/'`,
+          `${field} for type 'url_path' must start with '/'`,
+          'config',
+          false,
+          { field, ruleType: rule.type },
+          ErrorCode.CONFIG_VALIDATION_FAILED,
+        );
+      }
+      break;
+
+    case 'code_path':
+      if (rule.value.includes('://')) {
+        throw new PentestError(
+          `${field} for type 'code_path' must not contain a URL protocol (got '${rule.value}')`,
           'config',
           false,
           { field, ruleType: rule.type },
@@ -434,7 +560,7 @@ const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number):
     case 'subdomain':
     case 'domain':
       // Basic domain validation - no slashes allowed
-      if (rule.url_path.includes('/')) {
+      if (rule.value.includes('/')) {
         throw new PentestError(
           `${field} for type '${rule.type}' cannot contain '/' characters`,
           'config',
@@ -444,7 +570,7 @@ const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number):
         );
       }
       // Must contain at least one dot for domains
-      if (rule.type === 'domain' && !rule.url_path.includes('.')) {
+      if (rule.type === 'domain' && !rule.value.includes('.')) {
         throw new PentestError(
           `${field} for type 'domain' must be a valid domain name`,
           'config',
@@ -457,7 +583,7 @@ const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number):
 
     case 'method': {
       const allowedMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
-      if (!allowedMethods.includes(rule.url_path.toUpperCase())) {
+      if (!allowedMethods.includes(rule.value.toUpperCase())) {
         throw new PentestError(
           `${field} for type 'method' must be one of: ${allowedMethods.join(', ')}`,
           'config',
@@ -470,7 +596,7 @@ const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number):
     }
 
     case 'header':
-      if (!rule.url_path.match(/^[a-zA-Z0-9\-_]+$/)) {
+      if (!rule.value.match(/^[a-zA-Z0-9\-_]+$/)) {
         throw new PentestError(
           `${field} for type 'header' must be a valid header name (alphanumeric, hyphens, underscores only)`,
           'config',
@@ -482,7 +608,7 @@ const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number):
       break;
 
     case 'parameter':
-      if (!rule.url_path.match(/^[a-zA-Z0-9\-_]+$/)) {
+      if (!rule.value.match(/^[a-zA-Z0-9\-_]+$/)) {
         throw new PentestError(
           `${field} for type 'parameter' must be a valid parameter name (alphanumeric, hyphens, underscores only)`,
           'config',
@@ -498,13 +624,13 @@ const validateRuleTypeSpecific = (rule: Rule, ruleType: string, index: number):
 const checkForDuplicates = (rules: Rule[], ruleType: string): void => {
   const seen = new Set<string>();
   rules.forEach((rule, index) => {
-    const key = `${rule.type}:${rule.url_path}`;
+    const key = `${rule.type}:${rule.value}`;
     if (seen.has(key)) {
       throw new PentestError(
-        `Duplicate rule found in rules.${ruleType}[${index}]: ${rule.type} '${rule.url_path}'`,
+        `Duplicate rule found in rules.${ruleType}[${index}]: ${rule.type} '${rule.value}'`,
         'config',
         false,
-        { field: `rules.${ruleType}[${index}]`, ruleType: rule.type, urlPath: rule.url_path },
+        { field: `rules.${ruleType}[${index}]`, ruleType: rule.type, value: rule.value },
         ErrorCode.CONFIG_VALIDATION_FAILED,
       );
     }
@@ -513,16 +639,16 @@ const checkForDuplicates = (rules: Rule[], ruleType: string): void => {
 };
 
 const checkForConflicts = (avoidRules: Rule[] = [], focusRules: Rule[] = []): void => {
-  const avoidSet = new Set(avoidRules.map((rule) => `${rule.type}:${rule.url_path}`));
+  const avoidSet = new Set(avoidRules.map((rule) => `${rule.type}:${rule.value}`));
 
   focusRules.forEach((rule, index) => {
-    const key = `${rule.type}:${rule.url_path}`;
+    const key = `${rule.type}:${rule.value}`;
     if (avoidSet.has(key)) {
       throw new PentestError(
-        `Conflicting rule found: rules.focus[${index}] '${rule.url_path}' also exists in rules.avoid`,
+        `Conflicting rule found: rules.focus[${index}] '${rule.value}' also exists in rules.avoid`,
         'config',
         false,
-        { field: `rules.focus[${index}]`, urlPath: rule.url_path },
+        { field: `rules.focus[${index}]`, value: rule.value },
         ErrorCode.CONFIG_VALIDATION_FAILED,
       );
     }
@@ -533,7 +659,7 @@ const sanitizeRule = (rule: Rule): Rule => {
   return {
     description: rule.description.trim(),
     type: rule.type.toLowerCase().trim() as Rule['type'],
-    url_path: rule.url_path.trim(),
+    value: rule.value.trim(),
   };
 };
 
@@ -543,11 +669,28 @@ export const distributeConfig = (config: Config | null): DistributedConfig => {
   const authentication = config?.authentication || null;
   const description = config?.description?.trim() || '';
 
+  const vuln_classes =
+    config?.vuln_classes && config.vuln_classes.length > 0 ? [...config.vuln_classes] : [...ALL_VULN_CLASSES];
+
+  const exploit = config?.exploit !== undefined ? config.exploit === 'true' : true;
+
+  const report = {
+    ...(config?.report?.min_severity && { min_severity: config.report.min_severity }),
+    ...(config?.report?.min_confidence && { min_confidence: config.report.min_confidence }),
+    ...(config?.report?.guidance && { guidance: config.report.guidance.trim() }),
+  };
+
+  const rules_of_engagement = config?.rules_of_engagement?.trim() ?? '';
+
   return {
     avoid: avoid.map(sanitizeRule),
     focus: focus.map(sanitizeRule),
     authentication: authentication ? sanitizeAuthentication(authentication) : null,
     description,
+    vuln_classes,
+    exploit,
+    report,
+    rules_of_engagement,
   };
 };
 
@@ -557,8 +700,17 @@ const sanitizeAuthentication = (auth: Authentication): Authentication => {
     login_url: auth.login_url.trim(),
     credentials: {
       username: auth.credentials.username.trim(),
-      password: auth.credentials.password,
+      ...(auth.credentials.password && { password: auth.credentials.password }),
       ...(auth.credentials.totp_secret && { totp_secret: auth.credentials.totp_secret.trim() }),
+      ...(auth.credentials.email_login && {
+        email_login: {
+          address: auth.credentials.email_login.address.trim(),
+          password: auth.credentials.email_login.password,
+          ...(auth.credentials.email_login.totp_secret && {
+            totp_secret: auth.credentials.email_login.totp_secret.trim(),
+          }),
+        },
+      }),
     },
     ...(auth.login_flow && { login_flow: auth.login_flow.map((step) => step.trim()) }),
     success_condition: {

apps/worker/src/interfaces/checkpoint-provider.ts

@@ -0,0 +1,51 @@
+/**
+ * CheckpointProvider — injectable interface for external state persistence.
+ *
+ * Called before and after each agent to support skip-guard (resume) and
+ * post-agent artifact persistence. During the concurrent vulnerability-exploitation
+ * phase, 5 pipelines run in parallel — methods fire per-agent for granular control.
+ *
+ * Default: no-op (skip nothing, persist nothing).
+ */
+
+import type { AgentMetrics, PipelineState } from '../temporal/shared.js';
+
+/** Result of a pre-agent skip check. */
+export interface SkipDecision {
+  readonly skip: boolean;
+  readonly metrics?: AgentMetrics; // Required when skip=true
+}
+
+/** File-system context passed after agent completion for artifact persistence. */
+export interface CheckpointContext {
+  readonly repoPath: string;
+  readonly sessionId: string;
+  readonly deliverablesSubdir: string;
+  readonly outputPath?: string;
+}
+
+export interface CheckpointProvider {
+  /**
+   * Called before an agent activity executes.
+   * Return { skip: true, metrics } to skip the agent (e.g., output files already exist).
+   * Return { skip: false } to run normally.
+   */
+  shouldSkipAgent(agentName: string, repoPath: string, deliverablesSubdir: string): Promise<SkipDecision>;
+
+  /**
+   * Called after an agent activity succeeds.
+   * Receives pipeline state and optional file context for artifact persistence.
+   */
+  onAgentComplete(agentName: string, phase: string, state: PipelineState, context?: CheckpointContext): Promise<void>;
+}
+
+/** Default no-op implementation — no external checkpointing. */
+export class NoOpCheckpointProvider implements CheckpointProvider {
+  async shouldSkipAgent(): Promise<SkipDecision> {
+    return { skip: false };
+  }
+
+  async onAgentComplete(): Promise<void> {
+    // No-op
+  }
+}

apps/worker/src/interfaces/findings-provider.ts

@@ -0,0 +1,22 @@
+/**
+ * FindingsProvider — injectable interface for external findings integration.
+ *
+ * Allows external security data from consumer-supplied sources to be merged
+ * into the exploitation pipeline between vulnerability analysis and exploitation.
+ *
+ * Default: no-op returning { mergedCount: 0 }.
+ */
+
+import type { ActivityInput } from '../temporal/activities.js';
+import type { VulnType } from '../types/agents.js';
+
+export interface FindingsProvider {
+  mergeFindingsIntoQueue(repoPath: string, vulnType: VulnType, input: ActivityInput): Promise<{ mergedCount: number }>;
+}
+
+/** Default no-op implementation — no external findings to merge. */
+export class NoOpFindingsProvider implements FindingsProvider {
+  async mergeFindingsIntoQueue(): Promise<{ mergedCount: number }> {
+    return { mergedCount: 0 };
+  }
+}

apps/worker/src/interfaces/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Injectable interfaces for extending the pentest pipeline.
+ *
+ * All interfaces have default no-op implementations.
+ * Consumers can provide alternate implementations via the DI container.
+ */
+
+export type { CheckpointContext, CheckpointProvider, SkipDecision } from './checkpoint-provider.js';
+export { NoOpCheckpointProvider } from './checkpoint-provider.js';
+export type { FindingsProvider } from './findings-provider.js';
+export { NoOpFindingsProvider } from './findings-provider.js';
+export type { ReportOutputProvider } from './report-output-provider.js';
+export { NoOpReportOutputProvider } from './report-output-provider.js';

apps/worker/src/interfaces/report-output-provider.ts

@@ -0,0 +1,22 @@
+/**
+ * ReportOutputProvider — injectable interface for emitting an optional
+ * additional artifact alongside the assembled markdown report.
+ *
+ * Runs after the report agent has finalized
+ * `comprehensive_security_assessment_report.md`. Consumers can override to
+ * produce derived outputs; the default no-op produces nothing.
+ */
+
+import type { ActivityInput } from '../temporal/activities.js';
+import type { ActivityLogger } from '../types/activity-logger.js';
+
+export interface ReportOutputProvider {
+  generate(input: ActivityInput, logger: ActivityLogger): Promise<{ outputPath?: string }>;
+}
+
+/** Default no-op implementation — no additional output produced. */
+export class NoOpReportOutputProvider implements ReportOutputProvider {
+  async generate(): Promise<{ outputPath?: string }> {
+    return {};
+  }
+}

apps/worker/src/mcp-server/exploit-collector.ts

@@ -0,0 +1,473 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Exploit Collector MCP Server (factory parameterized by vulnerability class
+ * and per-run valid-ID set).
+ *
+ * Exposes a single Zod-validated MCP tool `add_exploit`, called once per
+ * processed vulnerability by the 5 exploit-* agents (injection, xss, auth,
+ * ssrf, authz). After the agent terminates, the host harvests
+ * collector.getAll() and runs exploit-renderer to produce
+ * {class}_exploitation_evidence.md. The collector state is the structured
+ * output.
+ *
+ * Schema shape:
+ *   - The SDK tool() helper consumes a ZodRawShape (flat object), not a
+ *     top-level discriminated union. The visible shape is therefore a single
+ *     z.object with common fields required, status as a string enum, and
+ *     per-status fields marked optional at the SDK layer. Each field's
+ *     `.describe()` text explains when it applies.
+ *   - True per-status field enforcement runs inside the tool handler via a
+ *     z.discriminatedUnion('status', ...). Missing-field errors come back to
+ *     the agent as structured Zod issues with retryable=true so it can fix
+ *     and retry the call.
+ *
+ * Strict queue-ID validation: vulnerability_id is refined against the per-run
+ * queue's known IDs at schema-build time. Hallucinated or typo'd IDs are
+ * rejected with a structured Zod error that includes the valid-ID list,
+ * letting the agent recover locally.
+ *
+ * Each Zod schema's field-level descriptions carry the bullet labels and
+ * reproducibility guidance, so the SDK injects it into the agent's tool
+ * catalog.
+ */
+
+import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+// ============================================================================
+// CLASS DISCRIMINATOR
+// ============================================================================
+
+export const EXPLOIT_VULN_CLASSES = ['injection', 'xss', 'auth', 'ssrf', 'authz'] as const;
+export type VulnClass = (typeof EXPLOIT_VULN_CLASSES)[number];
+
+// ============================================================================
+// SCHEMA CONSTANTS
+// ============================================================================
+
+const SEVERITY_VALUES = ['critical', 'high', 'medium', 'low'] as const;
+const CONFIDENCE_VALUES = ['high', 'medium', 'low'] as const;
+
+const VALID_IDS_PREVIEW_LIMIT = 8;
+
+function formatValidIdsPreview(validIds: ReadonlySet<string>): string {
+  const list = [...validIds];
+  const head = list.slice(0, VALID_IDS_PREVIEW_LIMIT).join(', ');
+  return list.length > VALID_IDS_PREVIEW_LIMIT ? `${head}, … (${list.length} total)` : head;
+}
+
+// ============================================================================
+// PUBLIC TYPES (discriminated union — what consumers see)
+// ============================================================================
+
+export type ExploitedExploit = {
+  status: 'exploited';
+  vulnerability_id: string;
+  title: string;
+  vulnerable_location: string;
+  overview: string;
+  prerequisites?: string | null;
+  severity: (typeof SEVERITY_VALUES)[number];
+  impact: string;
+  exploitation_steps: string[];
+  proof_of_impact: string;
+  notes?: string | null;
+};
+
+export type BlockedExploit = {
+  status: 'blocked';
+  vulnerability_id: string;
+  title: string;
+  vulnerable_location: string;
+  prerequisites?: string | null;
+  confidence: (typeof CONFIDENCE_VALUES)[number];
+  current_blocker: string;
+  potential_impact: string;
+  evidence_of_vulnerability: string;
+  what_we_tried: string;
+  how_this_would_be_exploited: string[];
+  expected_impact: string;
+  notes?: string | null;
+};
+
+export type AddExploitInput = ExploitedExploit | BlockedExploit;
+
+// ============================================================================
+// SCHEMA BUILDER
+// ============================================================================
+
+function buildSchemas(validIds: ReadonlySet<string>) {
+  const vulnerabilityIdField = z
+    .string()
+    .min(1)
+    .describe(
+      'Vulnerability identifier (e.g. "INJ-VULN-03"). Must match an ID from this run\'s ' +
+        '{class}_exploitation_queue.json exactly — the collector rejects IDs not in the queue. ' +
+        `Valid IDs for this run: ${formatValidIdsPreview(validIds)}.`,
+    )
+    .refine((id: string) => validIds.has(id), {
+      message:
+        `Vulnerability ID not in this run's queue. Valid IDs: ` +
+        `${formatValidIdsPreview(validIds)}. ` +
+        'Check the queue.json for the canonical ID — likely a typo or hallucinated ID.',
+    });
+
+  const titleField = z
+    .string()
+    .min(1)
+    .describe(
+      'Descriptive vulnerability title (e.g. "SQL Injection — User Search", "IDOR — Unauthorized ' +
+        'Access to User Orders"). Concise; encodes the vulnerability category and where it lives.',
+    );
+
+  const vulnerableLocationField = z
+    .string()
+    .min(1)
+    .describe(
+      'Endpoint or mechanism where the vulnerability exists (e.g. "GET /api/products?id=", ' +
+        '"POST /login", or a code location like "controllers/userController.js:42").',
+    );
+
+  const overviewField = z
+    .string()
+    .min(1)
+    .describe(
+      'Brief summary of the exploit itself — what the vulnerability is and how it was demonstrated ' +
+        '(or how it would be demonstrated, for blocked findings). 1-3 sentences.',
+    );
+
+  const prerequisitesField = z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      'Required setup, tools, or conditions to reproduce the exploit (e.g. authentication, ' +
+        'specific role, prior application state). Omit or pass null when no prerequisites apply.',
+    );
+
+  const notesField = z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      'Optional supplementary context — caveats, related findings, environmental observations. ' +
+        'Free-form Markdown. Omit or pass null when N/A.',
+    );
+
+  const statusField = z
+    .enum(['exploited', 'blocked'])
+    .describe(
+      'Verdict bucket. Set to "exploited" only after reaching Proof of Exploitation Level 3+ with ' +
+        'concrete impact evidence (extracted data, executed JavaScript, account takeover, internal ' +
+        'service access). Set to "blocked" only for real vulnerabilities where external factors ' +
+        '(NOT security defenses) prevented full exploitation. Findings where a security defense ' +
+        'successfully prevented exploitation after exhaustive bypass attempts are FALSE POSITIVE — ' +
+        'route those to your workspace tracking file, not this tool.',
+    );
+
+  // Per-status fields. All optional at the SDK shape layer because a single
+  // ZodRawShape cannot express a top-level discriminated union; the handler
+  // re-validates against the discriminated union below for true enforcement.
+  const severityField = z
+    .enum(SEVERITY_VALUES)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="exploited". Severity of the demonstrated impact. Critical = Level 4 ' +
+        '(admin credentials extracted, sensitive data dumped, system commands executed, full account ' +
+        'takeover). High = Level 3 (data extraction proven, authentication bypass confirmed, ' +
+        'internal service access). Medium/Low based on impact narrowness or read-only access. Must ' +
+        'reflect demonstrated impact, not theoretical potential.',
+    );
+
+  const impactField = z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="exploited". Business/security impact achieved by the exploit ' +
+        '(e.g. "Extracted full user table including bcrypt password hashes for 1,247 users", ' +
+        '"Achieved RCE as the application user; arbitrary shell commands executed"). Must describe ' +
+        'what was actually demonstrated, not what could theoretically happen.',
+    );
+
+  const exploitationStepsField = z
+    .array(z.string().min(1))
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="exploited". Ordered, reproducible exploitation steps — one Markdown ' +
+        'blob per numbered step. Each step must include full URLs (protocol + domain + port + path ' +
+        '+ params), complete payloads, and copy-paste-ready commands. Use clear placeholders for ' +
+        'variable values like [SESSION_TOKEN], [DATABASE_NAME], [TABLE_NAME], [TARGET_USER_ID]. ' +
+        'Write each step as natural Markdown — interleave prose with fenced code blocks (```bash, ' +
+        '```http, etc.) as you would in a write-up. Steps must be detailed enough that someone ' +
+        'unfamiliar with the application can follow without additional research.',
+    );
+
+  const proofOfImpactField = z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="exploited". Concrete evidence of successful exploitation — extracted ' +
+        'data, achieved actions, captured request/response pairs, log excerpts. Markdown blob; ' +
+        'interleave prose with fenced code blocks. Must show what the exploit demonstrably achieved, ' +
+        'not theoretical impact.',
+    );
+
+  const confidenceField = z
+    .enum(CONFIDENCE_VALUES)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="blocked". Confidence that this finding is a real vulnerability that ' +
+        'would be exploited if the external blocker were removed. High = code analysis strongly ' +
+        'confirms vulnerability and partial exploitation (Level 1-2) succeeded. Medium = code ' +
+        'analysis confirms but live evidence is partial. Low = signal-only; revisit if blocker is ' +
+        'removed in a future run.',
+    );
+
+  const currentBlockerField = z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="blocked". What prevents full exploitation (e.g. "Server crashes after ' +
+        '5 requests, blocking enumeration", "OAuth callback requires verified third-party email ' +
+        'account we could not provision"). Must be an external operational constraint, not a ' +
+        'security defense.',
+    );
+
+  const potentialImpactField = z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="blocked". What could be achieved if the blocker were removed (e.g. ' +
+        '"Full database read access", "Account takeover of arbitrary user via reset-token leak"). ' +
+        'Distinct from impact — this is the hypothetical outcome, not a demonstrated one.',
+    );
+
+  const evidenceOfVulnerabilityField = z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="blocked". Code snippets, response excerpts, or observed behavior ' +
+        'proving the vulnerability is real. Markdown blob; interleave prose with fenced code blocks. ' +
+        'This is what convinces the reader the finding is not a false positive despite incomplete ' +
+        'exploitation.',
+    );
+
+  const whatWeTriedField = z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="blocked". Log of attempted exploitation techniques and why each was ' +
+        'blocked. Each attempt should document the payload, the observed result, and the inferred ' +
+        'blocker. Markdown blob; multiple attempts as a list or distinct paragraphs. Demonstrates ' +
+        'exhaustive bypass effort per the Bypass Exhaustion Protocol.',
+    );
+
+  const howThisWouldBeExploitedField = z
+    .array(z.string().min(1))
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="blocked". Ordered hypothetical exploitation steps assuming the blocker ' +
+        'is removed — one Markdown blob per numbered step. Same reproducibility requirements as ' +
+        'exploitation_steps: full URLs, complete payloads, copy-paste-ready commands. Frame the ' +
+        'first step as "If [blocker] were removed: …".',
+    );
+
+  const expectedImpactField = z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      'REQUIRED when status="blocked". Specific data or access that would be compromised if ' +
+        'exploitation succeeded (e.g. "Read access to all user profile data including PII; write ' +
+        'access to user-owned resources"). Markdown blob.',
+    );
+
+  // The flat shape passed to tool(). The SDK uses this to build the agent's
+  // tool catalog. Per-status enforcement happens in the handler via the
+  // discriminated union below.
+  const flatShape = {
+    status: statusField,
+    vulnerability_id: vulnerabilityIdField,
+    title: titleField,
+    vulnerable_location: vulnerableLocationField,
+    overview: overviewField,
+    prerequisites: prerequisitesField,
+    notes: notesField,
+    severity: severityField,
+    impact: impactField,
+    exploitation_steps: exploitationStepsField,
+    proof_of_impact: proofOfImpactField,
+    confidence: confidenceField,
+    current_blocker: currentBlockerField,
+    potential_impact: potentialImpactField,
+    evidence_of_vulnerability: evidenceOfVulnerabilityField,
+    what_we_tried: whatWeTriedField,
+    how_this_would_be_exploited: howThisWouldBeExploitedField,
+    expected_impact: expectedImpactField,
+  };
+
+  // Strict per-status validation. Re-runs in the handler so missing fields
+  // for the chosen status return a retryable Zod error to the agent.
+  const ExploitedSchema = z.object({
+    status: z.literal('exploited'),
+    vulnerability_id: vulnerabilityIdField,
+    title: titleField,
+    vulnerable_location: vulnerableLocationField,
+    overview: overviewField,
+    prerequisites: prerequisitesField,
+    severity: z.enum(SEVERITY_VALUES),
+    impact: z.string().min(1),
+    exploitation_steps: z.array(z.string().min(1)).min(1),
+    proof_of_impact: z.string().min(1),
+    notes: notesField,
+  });
+
+  const BlockedSchema = z.object({
+    status: z.literal('blocked'),
+    vulnerability_id: vulnerabilityIdField,
+    title: titleField,
+    vulnerable_location: vulnerableLocationField,
+    prerequisites: prerequisitesField,
+    confidence: z.enum(CONFIDENCE_VALUES),
+    current_blocker: z.string().min(1),
+    potential_impact: z.string().min(1),
+    evidence_of_vulnerability: z.string().min(1),
+    what_we_tried: z.string().min(1),
+    how_this_would_be_exploited: z.array(z.string().min(1)).min(1),
+    expected_impact: z.string().min(1),
+    notes: notesField,
+  });
+
+  const StrictSchema = z.discriminatedUnion('status', [ExploitedSchema, BlockedSchema]);
+
+  return { flatShape, StrictSchema };
+}
+
+// ============================================================================
+// RESPONSE HELPERS
+// ============================================================================
+
+interface ToolResult {
+  [x: string]: unknown;
+  content: Array<{ type: 'text'; text: string }>;
+  isError: boolean;
+}
+
+function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+    isError: response.status === 'error',
+  };
+}
+
+function successResult(data: Record<string, unknown>): ToolResult {
+  return createToolResult({ status: 'success', ...data });
+}
+
+function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
+  return createToolResult({ status: 'error', message, errorType, retryable });
+}
+
+function formatZodIssues(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+      return `- ${path}: ${issue.message}`;
+    })
+    .join('\n');
+}
+
+// ============================================================================
+// SERVER FACTORY
+// ============================================================================
+
+export interface ExploitCollectorServer {
+  server: McpSdkServerConfigWithInstance;
+  getAll(): AddExploitInput[];
+}
+
+export interface CreateExploitCollectorOptions {
+  vulnClass: VulnClass;
+  validIds: ReadonlySet<string>;
+}
+
+export function createExploitCollector(options: CreateExploitCollectorOptions): ExploitCollectorServer {
+  const { vulnClass, validIds } = options;
+  const exploits: AddExploitInput[] = [];
+  const { flatShape, StrictSchema } = buildSchemas(validIds);
+
+  const addExploitTool = tool(
+    'add_exploit',
+    `Record a single processed ${vulnClass} vulnerability as structured exploitation evidence. ` +
+      'Call this once per vulnerability in your queue.json after reaching a definitive verdict ' +
+      '(either successfully exploited or potential-but-blocked). The status field discriminates the ' +
+      "two report buckets; required sub-fields differ per status (see each field's description for " +
+      'which status requires it). Duplicate vulnerability_id calls are rejected — each vuln may only ' +
+      'be recorded once. Vulnerability IDs not in the queue.json are rejected with a list of valid ' +
+      'IDs. FALSE POSITIVE findings do NOT use this tool — they go to your workspace tracking file. ' +
+      'After all queue vulnerabilities have been emitted, the host renderer assembles the ' +
+      'deliverable Markdown from your recorded calls.',
+    flatShape,
+    async (input): Promise<ToolResult> => {
+      // Re-validate against the strict discriminated union for per-status enforcement.
+      const parsed = StrictSchema.safeParse(input);
+      if (!parsed.success) {
+        return errorResult(
+          `Schema validation failed for status="${(input as { status?: string }).status}". ` +
+            'Required-field issues:\n' +
+            formatZodIssues(parsed.error),
+          'ValidationError',
+          true,
+        );
+      }
+      const typed = parsed.data as AddExploitInput;
+      const existing = exploits.find((e) => e.vulnerability_id === typed.vulnerability_id);
+      if (existing) {
+        return errorResult(
+          `Vulnerability ${typed.vulnerability_id} has already been recorded. Each vulnerability ` +
+            'may only be added once. Reach a final verdict before emitting.',
+          'DuplicateError',
+          false,
+        );
+      }
+      exploits.push(typed);
+      return successResult({ added: [typed.vulnerability_id], recorded_status: typed.status });
+    },
+  );
+
+  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
+    name: 'exploit-collector',
+    version: '1.0.0',
+    tools: [addExploitTool],
+  });
+
+  return {
+    server,
+    getAll: (): AddExploitInput[] => [...exploits],
+  };
+}

apps/worker/src/mcp-server/pre-recon-collector.ts

@@ -0,0 +1,620 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Pre-Recon Collector MCP Server
+ *
+ * Exposes seven Zod-validated MCP tools, one per section of the
+ * pre_recon_deliverable.md report. Every tool is one-shot (write-once;
+ * duplicate calls return DuplicateError). A skipped tool renders a placeholder
+ * rather than failing the activity. After the agent finishes, the host calls
+ * getAll() to harvest the typed payload bag, getCallStatus() to log the
+ * per-run call pattern, and runs the deterministic renderer to produce the
+ * deliverable Markdown.
+ *
+ * Each Zod schema's field-level descriptions carry the section guidance, so
+ * the SDK injects it into the agent's tool catalog.
+ */
+
+import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+// ============================================================================
+// SHARED SCHEMA
+// ============================================================================
+
+export const SinkRefSchema = z.object({
+  location: z
+    .string()
+    .min(1)
+    .describe(
+      'File path with line number (e.g., "templates/render.js:34") or richer prose ' +
+        '(e.g., "innerHTML at templates/render.js:34", "lines 45-67"). Must contain enough ' +
+        'detail for a downstream agent to find the exact location.',
+    ),
+  sink_function: z
+    .string()
+    .min(1)
+    .describe('The sink function or property name (e.g., "innerHTML", "axios.get", "eval", "document.write").'),
+  notes: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      'Optional context — render-context detail, attribute name, scope hints, or anything ' +
+        'a downstream agent needs to act on this sink. Omit when the location and sink_function ' +
+        'are sufficient on their own.',
+    ),
+});
+
+export type SinkRef = z.infer<typeof SinkRefSchema>;
+
+// ============================================================================
+// PER-TOOL INPUT SCHEMAS
+// ============================================================================
+
+export const ExecutiveSummaryInputSchema = z.object({
+  text: z
+    .string()
+    .min(1)
+    .describe(
+      "Provide a 2-3 paragraph overview of the application's security posture, highlighting " +
+        'the most critical attack surfaces and architectural security decisions. Becomes ' +
+        'Section 1 of the rendered deliverable.',
+    ),
+});
+
+const ArchitectureSchema = z.object({
+  framework_and_language: z
+    .string()
+    .min(1)
+    .describe('Framework and language details with their security implications.'),
+  architectural_pattern: z
+    .string()
+    .min(1)
+    .describe('Architectural pattern (monolith, microservices, hybrid) with trust boundary analysis.'),
+  critical_security_components: z
+    .string()
+    .min(1)
+    .describe('Critical security components with focus on auth, authz, and data protection.'),
+});
+
+const DataSecuritySchema = z.object({
+  database_security: z
+    .string()
+    .min(1)
+    .describe('Analyze encryption, access controls, and query safety in database interactions.'),
+  data_flow_security: z
+    .string()
+    .min(1)
+    .describe('Identify sensitive data paths and the protection mechanisms applied along them.'),
+  multi_tenant_isolation: z
+    .string()
+    .min(1)
+    .describe(
+      'Assess tenant separation effectiveness. If the application is single-tenant, state that ' +
+        'explicitly rather than leaving the field thin.',
+    ),
+});
+
+const AttackSurfaceSchema = z.object({
+  external_entry_points: z
+    .string()
+    .min(1)
+    .describe('Detailed analysis of each public interface that is network-accessible.'),
+  internal_service_communication: z
+    .string()
+    .min(1)
+    .describe(
+      'Trust relationships and security assumptions between network-reachable services. ' +
+        'If the application is a single service with no internal RPC fabric, state that.',
+    ),
+  input_validation_patterns: z
+    .string()
+    .min(1)
+    .describe('How user input is handled and validated in network-accessible endpoints.'),
+  background_processing: z
+    .string()
+    .min(1)
+    .describe(
+      'Async job security and privilege models for jobs triggered by network requests. ' +
+        'If no async/background processing exists, state that.',
+    ),
+});
+
+const InfrastructureSchema = z.object({
+  secrets_management: z.string().min(1).describe('How secrets are stored, rotated, and accessed.'),
+  configuration_security: z
+    .string()
+    .min(1)
+    .describe(
+      'Environment separation and secret handling. Specifically search for infrastructure ' +
+        'configuration (e.g., Nginx, Kubernetes Ingress, CDN settings) that defines security ' +
+        'headers like Strict-Transport-Security (HSTS) and Cache-Control, and report what was found.',
+    ),
+  external_dependencies: z.string().min(1).describe('Third-party services and their security implications.'),
+  monitoring_and_logging: z
+    .string()
+    .min(1)
+    .describe('Security event visibility — what is logged, where it goes, and who can see it.'),
+});
+
+export const ApplicationIntelligenceInputSchema = z.object({
+  architecture: ArchitectureSchema.describe(
+    'Architecture & Technology Stack — driven by the Architecture Scanner sub-agent. ' +
+      'Becomes Section 2 of the rendered deliverable.',
+  ),
+  data_security: DataSecuritySchema.describe(
+    'Data Security & Storage — driven by the Data Security Auditor sub-agent. ' +
+      'Becomes Section 4 of the rendered deliverable.',
+  ),
+  attack_surface: AttackSurfaceSchema.describe(
+    'Attack Surface Analysis — driven by Entry Point Mapper + Architecture Scanner sub-agents. ' +
+      'Only include entry points confirmed to be in-scope (network-reachable). ' +
+      'Becomes Section 5 of the rendered deliverable.',
+  ),
+  infrastructure: InfrastructureSchema.describe(
+    'Infrastructure & Operational Security. Becomes Section 6 of the rendered deliverable.',
+  ),
+});
+
+export const AuthDeepDiveInputSchema = z.object({
+  authentication_mechanisms: z
+    .string()
+    .min(1)
+    .describe(
+      'Authentication mechanisms and their security properties. MUST include an exhaustive list of ' +
+        'all API endpoints used for authentication (e.g., login, logout, token refresh, password reset).',
+    ),
+  session_management: z
+    .string()
+    .min(1)
+    .describe(
+      'Session management and token security. Pinpoint the exact file and line(s) of code where ' +
+        'session cookie flags (HttpOnly, Secure, SameSite) are configured.',
+    ),
+  authz_model: z.string().min(1).describe('Authorization model and potential bypass scenarios.'),
+  multi_tenancy: z
+    .string()
+    .min(1)
+    .describe('Multi-tenancy security implementation. If the application is single-tenant, state that explicitly.'),
+  sso_oauth_oidc: z
+    .string()
+    .nullable()
+    .describe(
+      'SSO/OAuth/OIDC flows: identify the callback endpoints and locate the specific code that ' +
+        'validates the state and nonce parameters. Set null only if the application has no SSO/OAuth/OIDC ' +
+        'integration at all.',
+    ),
+});
+
+export const CodebaseIndexingInputSchema = z.object({
+  text: z
+    .string()
+    .min(1)
+    .describe(
+      "A detailed, multi-sentence paragraph describing the codebase's directory structure, " +
+        'organization, and significant tools or conventions used (e.g., build orchestration, code ' +
+        'generation, testing frameworks). Focus on how this structure impacts discoverability of ' +
+        'security-relevant components.',
+    ),
+});
+
+export const CriticalFilePathsInputSchema = z.object({
+  configuration: z
+    .array(z.string().min(1))
+    .describe('Configuration files (e.g., config/server.yaml, Dockerfile, docker-compose.yml).'),
+  authentication_and_authorization: z
+    .array(z.string().min(1))
+    .describe(
+      'Auth/authz files (e.g., auth/jwt_middleware.go, internal/user/permissions.go, ' +
+        'config/initializers/session_store.rb, src/services/oauth_callback.js).',
+    ),
+  api_and_routing: z
+    .array(z.string().min(1))
+    .describe(
+      'API and routing files (e.g., cmd/api/main.go, internal/handlers/user_routes.go, ' +
+        'ts/graphql/schema.graphql).',
+    ),
+  data_models_and_db: z
+    .array(z.string().min(1))
+    .describe(
+      'Data model and DB interaction files (e.g., db/migrations/001_initial.sql, ' +
+        'internal/models/user.go, internal/repository/sql_queries.go).',
+    ),
+  dependency_manifests: z
+    .array(z.string().min(1))
+    .describe('Dependency manifests (e.g., go.mod, package.json, requirements.txt).'),
+  sensitive_data_and_secrets: z
+    .array(z.string().min(1))
+    .describe(
+      'Sensitive data and secrets handling (e.g., internal/utils/encryption.go, ' + 'internal/secrets/manager.go).',
+    ),
+  middleware_and_input_validation: z
+    .array(z.string().min(1))
+    .describe(
+      'Middleware and input validation (e.g., internal/middleware/validator.go, ' +
+        'internal/handlers/input_parsers.go).',
+    ),
+  logging_and_monitoring: z
+    .array(z.string().min(1))
+    .describe('Logging and monitoring (e.g., internal/logging/logger.go, config/monitoring.yaml).'),
+  infrastructure_and_deployment: z
+    .array(z.string().min(1))
+    .describe(
+      'Infrastructure and deployment (e.g., infra/pulumi/main.go, kubernetes/deploy.yaml, ' +
+        'nginx.conf, gateway-ingress.yaml).',
+    ),
+});
+
+export const XssSinksInputSchema = z.object({
+  applicable: z
+    .boolean()
+    .describe(
+      'False only if the application has no web frontend at all. Otherwise true, even if no ' +
+        'sinks were found in a given category — empty arrays mean "scanned this category, no sinks found".',
+    ),
+  html_body: z
+    .array(SinkRefSchema)
+    .describe(
+      'HTML Body Context sinks: element.innerHTML, element.outerHTML, document.write(), ' +
+        'document.writeln(), element.insertAdjacentHTML(), Range.createContextualFragment(), ' +
+        'and jQuery sinks like add(), after(), append(), before(), html(), prepend(), replaceWith(), wrap().',
+    ),
+  html_attribute: z
+    .array(SinkRefSchema)
+    .describe(
+      'HTML Attribute Context sinks: event handlers (onclick, onerror, onmouseover, onload, onfocus), ' +
+        'URL-based attributes (href, src, formaction, action, background, data), the style attribute, ' +
+        'iframe srcdoc, and general attributes (value, id, class, name, alt) when quotes are escaped.',
+    ),
+  javascript: z
+    .array(SinkRefSchema)
+    .describe(
+      'JavaScript Context sinks: eval(), Function() constructor, setTimeout() / setInterval() ' +
+        'with string arguments, and direct writes of user data into a <script> tag.',
+    ),
+  css: z
+    .array(SinkRefSchema)
+    .describe(
+      'CSS Context sinks: element.style properties (e.g., element.style.backgroundImage) and ' +
+        'direct writes of user data into a <style> tag.',
+    ),
+  url: z
+    .array(SinkRefSchema)
+    .describe(
+      'URL Context sinks: location / window.location, location.href, location.replace(), ' +
+        'location.assign(), window.open(), history.pushState(), history.replaceState(), ' +
+        'URL.createObjectURL(), and jQuery selector $(userInput) in older versions.',
+    ),
+});
+
+export const SsrfSinksInputSchema = z.object({
+  applicable: z
+    .boolean()
+    .describe(
+      'False only if the application makes no outbound requests at all. Otherwise true, even if ' +
+        'no sinks were found in a given category — empty arrays mean "scanned this category, no sinks found".',
+    ),
+  http_clients: z
+    .array(SinkRefSchema)
+    .describe(
+      'HTTP(S) clients: curl, requests (Python), axios (Node.js), fetch (JavaScript/Node.js), ' +
+        'net/http (Go), HttpClient (Java/.NET), urllib (Python), RestTemplate, WebClient, OkHttp, Apache HttpClient.',
+    ),
+  raw_sockets: z
+    .array(SinkRefSchema)
+    .describe(
+      'Raw sockets and connect APIs: Socket.connect, net.Dial (Go), socket.connect (Python), ' +
+        'TcpClient, UdpClient, NetworkStream, java.net.Socket, java.net.URL.openConnection().',
+    ),
+  url_openers: z
+    .array(SinkRefSchema)
+    .describe(
+      'URL openers and file includes: file_get_contents (PHP), fopen, include_once, require_once, ' +
+        'new URL().openStream() (Java), urllib.urlopen (Python), fs.readFile with URLs, ' +
+        'import() with dynamic URLs, loadHTML / loadXML with external sources.',
+    ),
+  redirect_handlers: z
+    .array(SinkRefSchema)
+    .describe(
+      'Redirect and "next URL" handlers: auto-follow redirects in HTTP clients, framework Location ' +
+        'handlers (response.redirect), URL validation in redirect chains, "Continue to" / "Return URL" parameters.',
+    ),
+  headless_browsers: z
+    .array(SinkRefSchema)
+    .describe(
+      'Headless browsers and render engines: Puppeteer (page.goto, page.setContent), ' +
+        'Playwright (page.navigate, page.route), Selenium WebDriver navigation, html-to-pdf converters ' +
+        '(wkhtmltopdf, Puppeteer PDF), and SSR with external content.',
+    ),
+  media_processors: z
+    .array(SinkRefSchema)
+    .describe(
+      'Media processors: ImageMagick (convert, identify with URLs), GraphicsMagick, FFmpeg with ' +
+        'network sources, wkhtmltopdf, Ghostscript with URL inputs, image optimization services with URL parameters.',
+    ),
+  link_preview: z
+    .array(SinkRefSchema)
+    .describe(
+      'Link preview and unfurlers: chat application link expanders, CMS link preview generators, ' +
+        'oEmbed endpoint fetchers, social media card generators, URL metadata extractors.',
+    ),
+  webhook_testers: z
+    .array(SinkRefSchema)
+    .describe(
+      'Webhook testers and callback verifiers: "ping my webhook" functionality, outbound callback ' +
+        'verification, health check notifications, event delivery confirmations, API endpoint validation tools.',
+    ),
+  sso_oidc_discovery: z
+    .array(SinkRefSchema)
+    .describe(
+      'SSO/OIDC discovery and JWKS fetchers: OpenID Connect discovery endpoints, JWKS fetchers, ' +
+        'OAuth authorization server metadata, SAML metadata fetchers, federation metadata retrievers.',
+    ),
+  importers: z
+    .array(SinkRefSchema)
+    .describe(
+      'Importers and data loaders: "import from URL" functionality, CSV/JSON/XML remote loaders, ' +
+        'RSS/Atom feed readers, API data synchronization, configuration file fetchers.',
+    ),
+  package_installers: z
+    .array(SinkRefSchema)
+    .describe(
+      'Package/plugin/theme installers: "install from URL" features, package managers with remote ' +
+        'sources, plugin/theme downloaders, update mechanisms with remote checks, dependency resolution ' +
+        'with external repos.',
+    ),
+  monitoring_and_health: z
+    .array(SinkRefSchema)
+    .describe(
+      'Monitoring and health check frameworks: URL pingers and uptime checkers, health check ' +
+        'endpoints, monitoring probe systems, alerting webhook senders, performance testing tools.',
+    ),
+  cloud_metadata: z
+    .array(SinkRefSchema)
+    .describe(
+      'Cloud metadata helpers: AWS/GCP/Azure instance metadata callers, cloud service discovery ' +
+        'mechanisms, container orchestration API clients, infrastructure metadata fetchers, service mesh ' +
+        'configuration retrievers.',
+    ),
+});
+
+// ============================================================================
+// EXPORTED TYPES
+// ============================================================================
+
+export type ExecutiveSummaryInput = z.infer<typeof ExecutiveSummaryInputSchema>;
+export type ApplicationIntelligenceInput = z.infer<typeof ApplicationIntelligenceInputSchema>;
+export type AuthDeepDiveInput = z.infer<typeof AuthDeepDiveInputSchema>;
+export type CodebaseIndexingInput = z.infer<typeof CodebaseIndexingInputSchema>;
+export type CriticalFilePathsInput = z.infer<typeof CriticalFilePathsInputSchema>;
+export type XssSinksInput = z.infer<typeof XssSinksInputSchema>;
+export type SsrfSinksInput = z.infer<typeof SsrfSinksInputSchema>;
+
+export interface PreReconData {
+  readonly executive_summary?: ExecutiveSummaryInput;
+  readonly application_intelligence?: ApplicationIntelligenceInput;
+  readonly auth_deep_dive?: AuthDeepDiveInput;
+  readonly codebase_indexing?: CodebaseIndexingInput;
+  readonly critical_file_paths?: CriticalFilePathsInput;
+  readonly xss_sinks?: XssSinksInput;
+  readonly ssrf_sinks?: SsrfSinksInput;
+}
+
+export const PRE_RECON_ONE_SHOT_TOOLS = [
+  'set_executive_summary',
+  'set_application_intelligence',
+  'set_auth_deep_dive',
+  'set_codebase_indexing',
+  'set_critical_file_paths',
+  'set_xss_sinks',
+  'set_ssrf_sinks',
+] as const;
+
+export type PreReconToolName = (typeof PRE_RECON_ONE_SHOT_TOOLS)[number];
+
+export type PreReconToolStatus = 'called' | 'skipped';
+
+export type PreReconCallStatus = Readonly<Record<PreReconToolName, PreReconToolStatus>>;
+
+// ============================================================================
+// RESPONSE HELPERS
+// ============================================================================
+
+interface ToolResult {
+  [x: string]: unknown;
+  content: Array<{ type: 'text'; text: string }>;
+  isError: boolean;
+}
+
+function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+    isError: response.status === 'error',
+  };
+}
+
+function successResult(data: Record<string, unknown>): ToolResult {
+  return createToolResult({ status: 'success', ...data });
+}
+
+function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
+  return createToolResult({ status: 'error', message, errorType, retryable });
+}
+
+// ============================================================================
+// SERVER FACTORY
+// ============================================================================
+
+export interface PreReconCollectorServer {
+  server: McpSdkServerConfigWithInstance;
+  getAll(): PreReconData;
+  getCallStatus(): PreReconCallStatus;
+}
+
+export function createPreReconCollectorServer(): PreReconCollectorServer {
+  const state: {
+    executive_summary?: ExecutiveSummaryInput;
+    application_intelligence?: ApplicationIntelligenceInput;
+    auth_deep_dive?: AuthDeepDiveInput;
+    codebase_indexing?: CodebaseIndexingInput;
+    critical_file_paths?: CriticalFilePathsInput;
+    xss_sinks?: XssSinksInput;
+    ssrf_sinks?: SsrfSinksInput;
+  } = {};
+
+  function alreadyCalled(toolName: PreReconToolName): ToolResult {
+    return errorResult(
+      `${toolName} has already been called. Each set_* tool may only be called once per run.`,
+      'DuplicateError',
+      false,
+    );
+  }
+
+  const setExecutiveSummary = tool(
+    'set_executive_summary',
+    "Record the application's overall security posture as a short executive summary. " +
+      'Call exactly once before terminating. Becomes Section 1 of the rendered deliverable. ' +
+      'Duplicate calls are rejected.',
+    ExecutiveSummaryInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.executive_summary) return alreadyCalled('set_executive_summary');
+      state.executive_summary = input;
+      return successResult({ set: 'set_executive_summary' });
+    },
+  );
+
+  const setApplicationIntelligence = tool(
+    'set_application_intelligence',
+    'Record the composite application intelligence — architecture, data security, attack surface, ' +
+      'and infrastructure — in a single call. Call exactly once before terminating. ' +
+      'Becomes Sections 2, 4, 5, and 6 of the rendered deliverable. Duplicate calls are rejected.',
+    ApplicationIntelligenceInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.application_intelligence) return alreadyCalled('set_application_intelligence');
+      state.application_intelligence = input;
+      return successResult({ set: 'set_application_intelligence' });
+    },
+  );
+
+  const setAuthDeepDive = tool(
+    'set_auth_deep_dive',
+    'Record the authentication & authorization deep dive. Call exactly once before terminating. ' +
+      'Becomes Section 3 of the rendered deliverable. Duplicate calls are rejected.',
+    AuthDeepDiveInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.auth_deep_dive) return alreadyCalled('set_auth_deep_dive');
+      state.auth_deep_dive = input;
+      return successResult({ set: 'set_auth_deep_dive' });
+    },
+  );
+
+  const setCodebaseIndexing = tool(
+    'set_codebase_indexing',
+    'Record the overall codebase indexing narrative. Call exactly once before terminating. ' +
+      'Becomes Section 7 of the rendered deliverable. Duplicate calls are rejected.',
+    CodebaseIndexingInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.codebase_indexing) return alreadyCalled('set_codebase_indexing');
+      state.codebase_indexing = input;
+      return successResult({ set: 'set_codebase_indexing' });
+    },
+  );
+
+  const setCriticalFilePaths = tool(
+    'set_critical_file_paths',
+    'Record the catalog of critical file paths grouped by security relevance. Call exactly once ' +
+      'before terminating. Becomes Section 8 of the rendered deliverable. The next agent uses this ' +
+      'as a starting point for manual review. Duplicate calls are rejected.',
+    CriticalFilePathsInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.critical_file_paths) return alreadyCalled('set_critical_file_paths');
+      state.critical_file_paths = input;
+      return successResult({ set: 'set_critical_file_paths' });
+    },
+  );
+
+  const setXssSinks = tool(
+    'set_xss_sinks',
+    'Record discovered XSS sinks grouped by render context. Call exactly once before terminating. ' +
+      'If the application has no web frontend at all, set applicable=false; otherwise populate each ' +
+      'render-context array (empty arrays mean "scanned, no sinks of this kind"). This list drives ' +
+      "the vuln-xss agent's testing todos downstream. Becomes Section 9 of the rendered deliverable. " +
+      'Duplicate calls are rejected.',
+    XssSinksInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.xss_sinks) return alreadyCalled('set_xss_sinks');
+      state.xss_sinks = input;
+      return successResult({ set: 'set_xss_sinks' });
+    },
+  );
+
+  const setSsrfSinks = tool(
+    'set_ssrf_sinks',
+    'Record discovered SSRF sinks grouped by sink category. Call exactly once before terminating. ' +
+      'If the application makes no outbound requests at all, set applicable=false; otherwise populate ' +
+      'each category array (empty arrays mean "scanned, no sinks of this kind"). This list drives ' +
+      "the vuln-ssrf agent's testing todos downstream. Becomes Section 10 of the rendered deliverable. " +
+      'Duplicate calls are rejected.',
+    SsrfSinksInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.ssrf_sinks) return alreadyCalled('set_ssrf_sinks');
+      state.ssrf_sinks = input;
+      return successResult({ set: 'set_ssrf_sinks' });
+    },
+  );
+
+  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
+    name: 'pre-recon-collector',
+    version: '1.0.0',
+    tools: [
+      setExecutiveSummary,
+      setApplicationIntelligence,
+      setAuthDeepDive,
+      setCodebaseIndexing,
+      setCriticalFilePaths,
+      setXssSinks,
+      setSsrfSinks,
+    ],
+  });
+
+  function statusOf<K extends PreReconToolName>(key: K): PreReconToolStatus {
+    const flagMap: Record<PreReconToolName, unknown> = {
+      set_executive_summary: state.executive_summary,
+      set_application_intelligence: state.application_intelligence,
+      set_auth_deep_dive: state.auth_deep_dive,
+      set_codebase_indexing: state.codebase_indexing,
+      set_critical_file_paths: state.critical_file_paths,
+      set_xss_sinks: state.xss_sinks,
+      set_ssrf_sinks: state.ssrf_sinks,
+    };
+    return flagMap[key] ? 'called' : 'skipped';
+  }
+
+  return {
+    server,
+    getAll: (): PreReconData => ({
+      ...(state.executive_summary && { executive_summary: state.executive_summary }),
+      ...(state.application_intelligence && { application_intelligence: state.application_intelligence }),
+      ...(state.auth_deep_dive && { auth_deep_dive: state.auth_deep_dive }),
+      ...(state.codebase_indexing && { codebase_indexing: state.codebase_indexing }),
+      ...(state.critical_file_paths && { critical_file_paths: state.critical_file_paths }),
+      ...(state.xss_sinks && { xss_sinks: state.xss_sinks }),
+      ...(state.ssrf_sinks && { ssrf_sinks: state.ssrf_sinks }),
+    }),
+    getCallStatus: (): PreReconCallStatus => ({
+      set_executive_summary: statusOf('set_executive_summary'),
+      set_application_intelligence: statusOf('set_application_intelligence'),
+      set_auth_deep_dive: statusOf('set_auth_deep_dive'),
+      set_codebase_indexing: statusOf('set_codebase_indexing'),
+      set_critical_file_paths: statusOf('set_critical_file_paths'),
+      set_xss_sinks: statusOf('set_xss_sinks'),
+      set_ssrf_sinks: statusOf('set_ssrf_sinks'),
+    }),
+  };
+}

apps/worker/src/mcp-server/recon-collector.ts

@@ -0,0 +1,818 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Recon Collector MCP Server
+ *
+ * Exposes nine Zod-validated MCP tools that feed the recon_deliverable.md
+ * renderer — eight one-shot `set_*` tools, one per deliverable section, plus a
+ * multi-call `add_endpoints` tool that lets the agent split a large API
+ * inventory across calls (the only catalog whose realistic payload threatens
+ * the per-turn output cap).
+ *
+ * A skipped tool renders a "not provided" placeholder in that section rather
+ * than failing the activity. getCallStatus() exposes the per-run call pattern
+ * for logging. Each Zod schema's field-level descriptions carry the section
+ * guidance, so the SDK injects it into the agent's tool catalog.
+ */
+
+import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { type SinkRef, SinkRefSchema } from './pre-recon-collector.js';
+
+// ============================================================================
+// PER-TOOL INPUT SCHEMAS
+// ============================================================================
+
+export const ExecutiveSummaryInputSchema = z.object({
+  text: z
+    .string()
+    .min(1)
+    .describe(
+      "A brief overview of the application's purpose, core technology stack " +
+        '(e.g., Next.js, Cloudflare), and the primary user-facing components that ' +
+        'constitute the attack surface. Becomes Section 1 of the rendered deliverable.',
+    ),
+});
+
+export const TechnologyStackInputSchema = z.object({
+  frontend: z.string().min(1).describe('Framework, key libraries, and authentication libraries used on the frontend.'),
+  backend: z.string().min(1).describe('Language, framework, and key dependencies used on the backend.'),
+  infrastructure: z
+    .string()
+    .min(1)
+    .describe('Hosting provider, CDN, database type, and other infrastructure components.'),
+});
+
+const SessionFlowSchema = z.object({
+  entry_points: z.string().min(1).describe('Authentication entry points (e.g., /login, /register, /auth/sso).'),
+  mechanism: z
+    .string()
+    .min(1)
+    .describe(
+      'Describe the step-by-step authentication process: credential submission, token generation, ' +
+        'cookie setting, redirects, etc.',
+    ),
+  code_pointers: z
+    .string()
+    .min(1)
+    .describe(
+      'Pointers to the primary files and functions in the codebase that manage authentication and ' + 'session logic.',
+    ),
+});
+
+const RoleAssignmentSchema = z.object({
+  role_determination: z
+    .string()
+    .min(1)
+    .describe('How roles are assigned post-authentication — database lookup, JWT claims, external service, etc.'),
+  default_role: z.string().min(1).describe('What role new users get by default.'),
+  role_upgrade_path: z
+    .string()
+    .min(1)
+    .describe(
+      'How users can gain higher privileges — admin approval, self-service, automatic, etc. ' +
+        'If no upgrade path exists, state that.',
+    ),
+  code_implementation: z
+    .string()
+    .min(1)
+    .describe('Where role assignment logic is implemented (file paths and functions).'),
+});
+
+const PrivilegeStorageSchema = z.object({
+  storage_location: z
+    .string()
+    .min(1)
+    .describe('Where user privileges are stored — JWT claims, session data, database, external service.'),
+  validation_points: z.string().min(1).describe('Where role checks happen — middleware, decorators, inline checks.'),
+  cache_session_persistence: z.string().min(1).describe('How long privileges are cached, and when they are refreshed.'),
+  code_pointers: z.string().min(1).describe('Files that handle privilege validation.'),
+});
+
+const RoleSwitchingImpersonationSchema = z.object({
+  applicable: z
+    .boolean()
+    .describe(
+      'False only if the application has no impersonation, sudo-mode, or role-switching features ' +
+        'at all. When false, the other fields in this object may be null.',
+    ),
+  impersonation_features: z
+    .string()
+    .nullable()
+    .describe(
+      'Any ability for admins or higher-privilege users to impersonate other users. Pass null when ' +
+        'applicable is false.',
+    ),
+  role_switching: z
+    .string()
+    .nullable()
+    .describe('Temporary privilege elevation mechanisms like "sudo mode". Pass null when applicable is false.'),
+  audit_trail: z
+    .string()
+    .nullable()
+    .describe(
+      'Whether role switches or impersonation events are logged, and where. Pass null when applicable is false.',
+    ),
+  code_implementation: z
+    .string()
+    .nullable()
+    .describe('Where these features are implemented (file paths and functions). Pass null when applicable is false.'),
+});
+
+export const AuthenticationInputSchema = z.object({
+  session_flow: SessionFlowSchema.describe(
+    'Authentication & Session Management Flow — overall entry points, mechanism, and code pointers. ' +
+      'Becomes Section 3 of the rendered deliverable.',
+  ),
+  role_assignment: RoleAssignmentSchema.describe(
+    'Role Assignment Process — how roles are determined post-authentication. ' + 'Becomes Section 3.1.',
+  ),
+  privilege_storage: PrivilegeStorageSchema.describe(
+    'Privilege Storage & Validation — where privileges live and where they are checked. ' + 'Becomes Section 3.2.',
+  ),
+  role_switching_impersonation: RoleSwitchingImpersonationSchema.describe(
+    'Role Switching & Impersonation — impersonation, sudo mode, audit trails. Becomes Section 3.3. ' +
+      'Set applicable=false if no such features exist; the other fields may be null in that case.',
+  ),
+});
+
+const HTTP_METHOD_VALUES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD', 'WS'] as const;
+
+const EndpointSchema = z.object({
+  method: z.enum(HTTP_METHOD_VALUES).describe('HTTP method. Use WS for WebSocket upgrade endpoints.'),
+  path: z.string().min(1).describe('Endpoint path with parameter placeholders, e.g. "/api/users/{user_id}".'),
+  required_role: z.string().min(1).describe('Minimum role needed (anon, user, admin, etc.).'),
+  object_id_parameters: z
+    .array(z.string())
+    .describe('Parameters that identify specific objects (user_id, order_id, etc.). Empty array if none.'),
+  authorization_mechanism: z
+    .string()
+    .min(1)
+    .describe(
+      'How access is controlled — middleware, decorator, inline check. ' +
+        'E.g. "Bearer Token + ownership check", "requireAuth() + requireAdmin()", "None".',
+    ),
+  description: z.string().min(1).describe("Brief description of the endpoint's purpose."),
+  code_pointer: z
+    .string()
+    .min(1)
+    .describe('File path and (where possible) line number of the handler. E.g. "auth.controller.ts:45".'),
+});
+
+export const AddEndpointsInputSchema = z.object({
+  endpoints: z
+    .array(EndpointSchema)
+    .describe(
+      'A batch of network-accessible API endpoints to append to the catalog. Include only endpoints ' +
+        'reachable through the deployed application — exclude CLI tools, dev-only routes, build scripts. ' +
+        'Duplicate (method, path) pairs across calls are skipped as no-ops; the response reports which ' +
+        'were added vs. skipped.',
+    ),
+});
+
+export const InputVectorsInputSchema = z.object({
+  url_parameters: z
+    .array(z.string().min(1))
+    .describe(
+      'URL parameter input vectors — each entry should identify the parameter and (where possible) ' +
+        'the file:line of the handler. E.g. "?redirect_url= @ auth.controller.ts:88".',
+    ),
+  post_body_fields: z
+    .array(z.string().min(1))
+    .describe(
+      'POST/PUT body field input vectors (JSON or form). E.g. "username @ login.handler.ts:34", ' +
+        '"profile.description @ users.controller.ts:120".',
+    ),
+  http_headers: z
+    .array(z.string().min(1))
+    .describe(
+      'HTTP header input vectors. Include both standard headers consumed by app code (e.g., ' +
+        'X-Forwarded-For) and custom application headers.',
+    ),
+  cookie_values: z
+    .array(z.string().min(1))
+    .describe('Cookie-based input vectors. E.g. "preferences_cookie @ middleware/prefs.ts:22".'),
+});
+
+const ENTITY_TYPE_VALUES = ['ExternAsset', 'Service', 'Identity', 'DataStore', 'AdminPlane', 'ThirdParty'] as const;
+
+const ENTITY_ZONE_VALUES = ['Internet', 'Edge', 'App', 'Data', 'Admin', 'BuildCI', 'ThirdParty'] as const;
+
+const DATA_LABEL_VALUES = ['PII', 'Tokens', 'Payments', 'Secrets', 'Public'] as const;
+
+const FLOW_CHANNEL_VALUES = ['HTTP', 'HTTPS', 'TCP', 'Message', 'File', 'Token'] as const;
+
+const GUARD_CATEGORY_VALUES = [
+  'Auth',
+  'Network',
+  'Protocol',
+  'Env',
+  'RateLimit',
+  'Authorization',
+  'ObjectOwnership',
+] as const;
+
+const EntityMetadataPairSchema = z.object({
+  key: z.string().min(1).describe('Metadata key (e.g., "Hosts", "Endpoints", "Engine", "Issuer").'),
+  value: z.string().min(1).describe('Metadata value for this key.'),
+});
+
+const EntitySchema = z.object({
+  title: z
+    .string()
+    .min(1)
+    .describe('Unique short name for the entity (e.g., "ExampleWebApp", "PostgreSQL-DB", "IdentityProvider").'),
+  type: z
+    .enum(ENTITY_TYPE_VALUES)
+    .describe(
+      'Entity type. ExternAsset = client-side asset; Service = backend service; Identity = identity ' +
+        'provider; DataStore = database / cache / object store; AdminPlane = admin/control surface; ' +
+        'ThirdParty = external integration.',
+    ),
+  zone: z
+    .enum(ENTITY_ZONE_VALUES)
+    .describe(
+      'Trust zone. Internet = public; Edge = CDN/WAF/reverse-proxy tier; App = application/business logic; ' +
+        'Data = persistent storage; Admin = administrative surface; BuildCI = build/CI/CD infrastructure; ' +
+        'ThirdParty = external trust domain.',
+    ),
+  tech: z
+    .string()
+    .min(1)
+    .describe('Short technology/framework description (e.g., "Node/Express", "Postgres 14", "AWS S3").'),
+  data: z
+    .array(z.enum(DATA_LABEL_VALUES))
+    .describe('Data labels handled by this entity. Empty array if the entity handles only Public data.'),
+  notes: z
+    .string()
+    .describe('Freeform context (e.g., "public-facing", "stores sensitive user data"). Empty string if none.'),
+  metadata: z
+    .array(EntityMetadataPairSchema)
+    .describe(
+      'Ordered key/value pairs of technical metadata for this entity. Becomes the Section 6.2 row ' +
+        'rendered as "Key: Value; Key: Value; …". Example pairs for a service: Hosts, Endpoints, Auth, ' +
+        'Dependencies; for a datastore: Engine, Exposure, Consumers, Credentials.',
+    ),
+});
+
+const FlowSchema = z.object({
+  from: z.string().min(1).describe('Source entity title — must match a title from the entities array.'),
+  to: z.string().min(1).describe('Destination entity title — must match a title from the entities array.'),
+  channel: z.enum(FLOW_CHANNEL_VALUES).describe('Transport channel for this flow.'),
+  path_port: z
+    .string()
+    .min(1)
+    .describe('Path and/or port for this flow. E.g. ":443 /api/users/me", ":5432", "queue: orders".'),
+  guards: z
+    .array(z.string().min(1))
+    .describe(
+      'Guard names that gate this flow. Each should match a name from the guards array. Empty array ' +
+        'means no guards apply (publicly accessible).',
+    ),
+  touches: z
+    .array(z.enum(DATA_LABEL_VALUES))
+    .describe('Data labels this flow carries. Empty array if only Public data flows.'),
+});
+
+const GuardSchema = z.object({
+  name: z.string().min(1).describe('Short guard identifier (e.g., "auth:user", "ownership:user", "vpc-only", "mtls").'),
+  category: z
+    .enum(GUARD_CATEGORY_VALUES)
+    .describe(
+      'Guard category. Auth = authentication identity; Authorization = role/scope check; ' +
+        'ObjectOwnership = ownership-based check; Network = network-level restriction; ' +
+        'Protocol = protocol-level requirement; Env = environment-bound restriction; ' +
+        'RateLimit = throttling.',
+    ),
+  statement: z.string().min(1).describe('One-sentence description of what this guard enforces.'),
+});
+
+export const NetworkMapInputSchema = z.object({
+  entities: z
+    .array(EntitySchema)
+    .describe(
+      'All major components of the system. Becomes Section 6.1 (Entities) and Section 6.2 ' +
+        '(Entity Metadata, split per-entity from the metadata field).',
+    ),
+  flows: z
+    .array(FlowSchema)
+    .describe(
+      'How entities communicate. Becomes Section 6.3. The from/to fields cross-reference entities ' +
+        'by title; the guards field cross-references guards by name.',
+    ),
+  guards: z.array(GuardSchema).describe('Catalog of guards referenced by flows. Becomes Section 6.4.'),
+});
+
+const RoleSchema = z.object({
+  name: z.string().min(1).describe('Role name (e.g., "anon", "user", "admin", "team_admin").'),
+  privilege_level: z
+    .number()
+    .int()
+    .min(0)
+    .max(10)
+    .describe('Privilege rank from 0 (lowest, anonymous) to 10 (highest, full admin).'),
+  scope_domain: z.string().min(1).describe('Scope of this role: Global, Org, Team, Project, etc.'),
+  code_implementation: z
+    .string()
+    .min(1)
+    .describe('Where this role is defined or checked (middleware, decorator, file:line, etc.).'),
+  default_landing_page: z
+    .string()
+    .min(1)
+    .describe('Default landing page or route after authentication. Use "N/A" for roles without a UI.'),
+  accessible_route_patterns: z
+    .array(z.string().min(1))
+    .describe('Route patterns this role can access. Empty array if the role has no UI access.'),
+  authentication_method: z
+    .string()
+    .min(1)
+    .describe('How this role authenticates: "None" (anon), "Session/JWT", "Session/JWT + role claim", etc.'),
+  middleware_guards: z
+    .string()
+    .min(1)
+    .describe('Middleware and guards that enforce this role (e.g., "requireAuth() + requireAdmin()").'),
+  permission_checks: z
+    .string()
+    .min(1)
+    .describe('How permission checks are expressed in code (e.g., "req.user.role === \'admin\'").'),
+  storage_location: z
+    .string()
+    .min(1)
+    .describe('Where this role is stored at runtime (JWT claims, session data, etc.).'),
+});
+
+const PrivilegeLatticeSchema = z.object({
+  ordering_diagram: z
+    .string()
+    .min(1)
+    .describe(
+      'ASCII diagram showing role ordering. Use → for "can access resources of". ' + 'E.g. "anon → user → admin".',
+    ),
+  parallel_isolation_notes: z
+    .string()
+    .describe(
+      'Notes on parallel isolation between roles using ||. E.g. "team_admin || dept_admin (both > user, ' +
+        'but isolated from each other)". Empty string if no parallel isolation exists.',
+    ),
+  role_switching_notes: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      'Optional pointer to impersonation, sudo mode, or role-switching mechanisms documented in ' +
+        'set_authentication.role_switching_impersonation. Null/omitted if no such mechanisms exist.',
+    ),
+});
+
+export const RoleArchitectureInputSchema = z.object({
+  roles: z
+    .array(RoleSchema)
+    .describe(
+      'All distinct privilege levels found in the application. Becomes Sections 7.1 (Discovered Roles), ' +
+        '7.3 (Role Entry Points), and 7.4 (Role-to-Code Mapping), split by the renderer per-role.',
+    ),
+  privilege_lattice: PrivilegeLatticeSchema.describe(
+    'The role hierarchy showing dominance and parallel isolation. Becomes Section 7.2.',
+  ),
+});
+
+const PRIORITY_VALUES = ['High', 'Medium', 'Low'] as const;
+
+const HorizontalCandidateSchema = z.object({
+  priority: z
+    .enum(PRIORITY_VALUES)
+    .describe('Priority: High, Medium, or Low, based on data sensitivity (title-case literals).'),
+  endpoint_pattern: z
+    .string()
+    .min(1)
+    .describe('Endpoint pattern with the object identifier. E.g. "/api/orders/{order_id}".'),
+  object_id_parameter: z
+    .string()
+    .min(1)
+    .describe('The parameter name that identifies the target object (e.g., "order_id", "user_id").'),
+  data_type: z.string().min(1).describe('Type of data exposed: user_data, financial, admin_config, user_files, etc.'),
+  sensitivity: z
+    .string()
+    .min(1)
+    .describe('One-line description of what is at risk (e.g., "User can access other users\' orders").'),
+});
+
+const VerticalCandidateSchema = z.object({
+  target_role: z.string().min(1).describe('Role required to access this endpoint (the role being escalated to).'),
+  endpoint_pattern: z
+    .string()
+    .min(1)
+    .describe('Endpoint pattern that requires elevated privileges. E.g. "/admin/*", "/api/admin/users".'),
+  functionality: z
+    .string()
+    .min(1)
+    .describe('What the endpoint does (e.g., "Administrative functions", "User management").'),
+  risk_level: z.enum(PRIORITY_VALUES).describe('Risk level: High, Medium, or Low (title-case literals).'),
+});
+
+const ContextCandidateSchema = z.object({
+  workflow: z.string().min(1).describe('Multi-step workflow name (e.g., "Checkout", "Onboarding", "Password Reset").'),
+  endpoint: z.string().min(1).describe('Endpoint that assumes a prior workflow state. E.g. "/api/checkout/confirm".'),
+  expected_prior_state: z.string().min(1).describe('What state should already exist before this endpoint is called.'),
+  bypass_potential: z.string().min(1).describe('What an attacker could achieve by skipping the prior state.'),
+});
+
+export const AuthzCandidatesInputSchema = z.object({
+  horizontal: z
+    .array(HorizontalCandidateSchema)
+    .describe(
+      "Endpoints with object identifiers that could allow horizontal access to other users' " +
+        'resources. Becomes Section 8.1. The renderer assigns stable AUTHZ-CAND-NN IDs.',
+    ),
+  vertical: z
+    .array(VerticalCandidateSchema)
+    .describe(
+      'Endpoints that require higher privileges and could be targets for vertical escalation. ' +
+        'Becomes Section 8.2. Exclude endpoints intentionally shared across roles.',
+    ),
+  context: z
+    .array(ContextCandidateSchema)
+    .describe('Multi-step workflow endpoints that assume prior steps were completed. Becomes Section 8.3.'),
+});
+
+export const InjectionSourcesInputSchema = z.object({
+  applicable: z
+    .boolean()
+    .describe(
+      'False only if the application has no network-accessible code paths reaching dangerous sinks ' +
+        'at all. Otherwise true, even if no sources were found in a given category — empty arrays mean ' +
+        '"scanned this category, no sources found".',
+    ),
+  command_injection: z
+    .array(SinkRefSchema)
+    .describe(
+      'Command injection sources: data flowing from a user-controlled origin into a program variable ' +
+        'that is eventually interpolated into a shell or system command string (within network-accessible ' +
+        'code paths).',
+    ),
+  sql_injection: z
+    .array(SinkRefSchema)
+    .describe(
+      'SQL injection sources: user-controllable input that reaches a database query string (within ' +
+        'network-accessible code paths).',
+    ),
+  lfi_rfi: z
+    .array(SinkRefSchema)
+    .describe(
+      'Local/Remote File Inclusion sources: user-controllable input passed to include/require/load ' +
+        'functions that resolve to filesystem or remote paths (within network-accessible code paths).',
+    ),
+  path_traversal: z
+    .array(SinkRefSchema)
+    .describe(
+      'Path traversal sources: user-controllable input that influences file paths in read/write ' +
+        'operations (fopen, readFile, etc.) within network-accessible code paths.',
+    ),
+  ssti: z
+    .array(SinkRefSchema)
+    .describe(
+      'Server-Side Template Injection sources: user-controllable input embedded in template ' +
+        'expressions or template content within network-accessible code paths.',
+    ),
+  deserialization: z
+    .array(SinkRefSchema)
+    .describe(
+      'Insecure deserialization sources: user-controllable input passed to deserialization functions ' +
+        'within network-accessible code paths.',
+    ),
+});
+
+// ============================================================================
+// EXPORTED TYPES
+// ============================================================================
+
+export type ExecutiveSummaryInput = z.infer<typeof ExecutiveSummaryInputSchema>;
+export type TechnologyStackInput = z.infer<typeof TechnologyStackInputSchema>;
+export type AuthenticationInput = z.infer<typeof AuthenticationInputSchema>;
+export type AddEndpointsInput = z.infer<typeof AddEndpointsInputSchema>;
+export type Endpoint = z.infer<typeof EndpointSchema>;
+export type InputVectorsInput = z.infer<typeof InputVectorsInputSchema>;
+export type NetworkMapInput = z.infer<typeof NetworkMapInputSchema>;
+export type Entity = z.infer<typeof EntitySchema>;
+export type Flow = z.infer<typeof FlowSchema>;
+export type Guard = z.infer<typeof GuardSchema>;
+export type RoleArchitectureInput = z.infer<typeof RoleArchitectureInputSchema>;
+export type Role = z.infer<typeof RoleSchema>;
+export type PrivilegeLattice = z.infer<typeof PrivilegeLatticeSchema>;
+export type AuthzCandidatesInput = z.infer<typeof AuthzCandidatesInputSchema>;
+export type HorizontalCandidate = z.infer<typeof HorizontalCandidateSchema>;
+export type VerticalCandidate = z.infer<typeof VerticalCandidateSchema>;
+export type ContextCandidate = z.infer<typeof ContextCandidateSchema>;
+export type InjectionSourcesInput = z.infer<typeof InjectionSourcesInputSchema>;
+export type Priority = (typeof PRIORITY_VALUES)[number];
+
+export interface ReconData {
+  readonly executive_summary?: ExecutiveSummaryInput;
+  readonly technology_stack?: TechnologyStackInput;
+  readonly authentication?: AuthenticationInput;
+  readonly endpoints?: readonly Endpoint[];
+  readonly input_vectors?: InputVectorsInput;
+  readonly network_map?: NetworkMapInput;
+  readonly role_architecture?: RoleArchitectureInput;
+  readonly authz_candidates?: AuthzCandidatesInput;
+  readonly injection_sources?: InjectionSourcesInput;
+}
+
+export const RECON_ONE_SHOT_TOOLS = [
+  'set_executive_summary',
+  'set_technology_stack',
+  'set_authentication',
+  'set_input_vectors',
+  'set_network_map',
+  'set_role_architecture',
+  'set_authz_candidates',
+  'set_injection_sources',
+] as const;
+
+export type ReconOneShotToolName = (typeof RECON_ONE_SHOT_TOOLS)[number];
+
+export type ReconToolStatus = 'called' | 'skipped';
+
+export interface ReconCallStatus {
+  readonly set_executive_summary: ReconToolStatus;
+  readonly set_technology_stack: ReconToolStatus;
+  readonly set_authentication: ReconToolStatus;
+  readonly add_endpoints: { readonly calls: number; readonly endpoints_seen: number };
+  readonly set_input_vectors: ReconToolStatus;
+  readonly set_network_map: ReconToolStatus;
+  readonly set_role_architecture: ReconToolStatus;
+  readonly set_authz_candidates: ReconToolStatus;
+  readonly set_injection_sources: ReconToolStatus;
+}
+
+// ============================================================================
+// RESPONSE HELPERS
+// ============================================================================
+
+interface ToolResult {
+  [x: string]: unknown;
+  content: Array<{ type: 'text'; text: string }>;
+  isError: boolean;
+}
+
+function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+    isError: response.status === 'error',
+  };
+}
+
+function successResult(data: Record<string, unknown>): ToolResult {
+  return createToolResult({ status: 'success', ...data });
+}
+
+function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
+  return createToolResult({ status: 'error', message, errorType, retryable });
+}
+
+function endpointKey(method: string, path: string): string {
+  return `${method} ${path}`;
+}
+
+// ============================================================================
+// SERVER FACTORY
+// ============================================================================
+
+export interface ReconCollectorServer {
+  server: McpSdkServerConfigWithInstance;
+  getAll(): ReconData;
+  getCallStatus(): ReconCallStatus;
+}
+
+export function createReconCollectorServer(): ReconCollectorServer {
+  const state: {
+    executive_summary?: ExecutiveSummaryInput;
+    technology_stack?: TechnologyStackInput;
+    authentication?: AuthenticationInput;
+    input_vectors?: InputVectorsInput;
+    network_map?: NetworkMapInput;
+    role_architecture?: RoleArchitectureInput;
+    authz_candidates?: AuthzCandidatesInput;
+    injection_sources?: InjectionSourcesInput;
+  } = {};
+
+  const endpoints: Endpoint[] = [];
+  const seenEndpointKeys = new Set<string>();
+  let addEndpointsCalls = 0;
+
+  function alreadyCalled(toolName: ReconOneShotToolName): ToolResult {
+    return errorResult(
+      `${toolName} has already been called. Each set_* tool may only be called once per run.`,
+      'DuplicateError',
+      false,
+    );
+  }
+
+  const setExecutiveSummary = tool(
+    'set_executive_summary',
+    "Record the application's executive summary: purpose, core technology stack, and primary " +
+      'user-facing components. Call exactly once before terminating. Becomes Section 1 of the rendered ' +
+      'deliverable. Duplicate calls are rejected.',
+    ExecutiveSummaryInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.executive_summary) return alreadyCalled('set_executive_summary');
+      state.executive_summary = input;
+      return successResult({ set: 'set_executive_summary' });
+    },
+  );
+
+  const setTechnologyStack = tool(
+    'set_technology_stack',
+    'Record the technology and service map: frontend, backend, and infrastructure. Call exactly once ' +
+      'before terminating. Becomes Section 2 of the rendered deliverable. Duplicate calls are rejected.',
+    TechnologyStackInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.technology_stack) return alreadyCalled('set_technology_stack');
+      state.technology_stack = input;
+      return successResult({ set: 'set_technology_stack' });
+    },
+  );
+
+  const setAuthentication = tool(
+    'set_authentication',
+    'Record the authentication and session management architecture: session flow, role assignment, ' +
+      'privilege storage, and role switching/impersonation. Call exactly once before terminating. ' +
+      'Becomes Sections 3, 3.1, 3.2, and 3.3 of the rendered deliverable. Set ' +
+      'role_switching_impersonation.applicable=false (with the other fields null) if no such features ' +
+      'exist. Duplicate calls are rejected.',
+    AuthenticationInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.authentication) return alreadyCalled('set_authentication');
+      state.authentication = input;
+      return successResult({ set: 'set_authentication' });
+    },
+  );
+
+  const addEndpoints = tool(
+    'add_endpoints',
+    'Append a batch of network-accessible API endpoints to the catalog. May be called multiple times — ' +
+      'each call appends. Use a single call for small inventories, or split across 2-3 calls for large ' +
+      'inventories (50+ endpoints) to keep individual payloads comfortable. Duplicate (method, path) ' +
+      'pairs across calls are skipped as no-ops; the response reports added vs. skipped. Becomes ' +
+      'Section 4 of the rendered deliverable and drives vuln-authz / vuln-injection todos downstream. ' +
+      'The renderer sorts by (path, method) before rendering, so emission order does not affect output.',
+    AddEndpointsInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      addEndpointsCalls += 1;
+      const added: string[] = [];
+      const skipped: string[] = [];
+      for (const ep of input.endpoints) {
+        const key = endpointKey(ep.method, ep.path);
+        if (seenEndpointKeys.has(key)) {
+          skipped.push(key);
+          continue;
+        }
+        seenEndpointKeys.add(key);
+        endpoints.push(ep);
+        added.push(key);
+      }
+      return successResult({
+        set: 'add_endpoints',
+        added: added.length,
+        duplicates_skipped: skipped,
+        total_accumulated: endpoints.length,
+      });
+    },
+  );
+
+  const setInputVectors = tool(
+    'set_input_vectors',
+    'Record potential input vectors grouped by source: URL parameters, POST body fields, HTTP headers, ' +
+      'and cookie values. Call exactly once before terminating. Becomes Section 5 of the rendered ' +
+      'deliverable. Drives downstream vulnerability analysis. Duplicate calls are rejected.',
+    InputVectorsInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.input_vectors) return alreadyCalled('set_input_vectors');
+      state.input_vectors = input;
+      return successResult({ set: 'set_input_vectors' });
+    },
+  );
+
+  const setNetworkMap = tool(
+    'set_network_map',
+    'Record the network and interaction map: entities, flows, and guards. Call exactly once before ' +
+      'terminating. Becomes Sections 6.1 (Entities), 6.2 (Entity Metadata), 6.3 (Flows), and 6.4 ' +
+      '(Guards Directory) of the rendered deliverable. The renderer splits the entities array into ' +
+      'the 6.1 and 6.2 tables and sorts each array deterministically. Duplicate calls are rejected.',
+    NetworkMapInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.network_map) return alreadyCalled('set_network_map');
+      state.network_map = input;
+      return successResult({ set: 'set_network_map' });
+    },
+  );
+
+  const setRoleArchitecture = tool(
+    'set_role_architecture',
+    'Record the role and privilege architecture: discovered roles and the privilege lattice. Call ' +
+      'exactly once before terminating. Becomes Sections 7.1 (Discovered Roles), 7.2 (Privilege Lattice), ' +
+      '7.3 (Role Entry Points), and 7.4 (Role-to-Code Mapping) of the rendered deliverable. The renderer ' +
+      'splits the roles array into the per-section tables. Duplicate calls are rejected.',
+    RoleArchitectureInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.role_architecture) return alreadyCalled('set_role_architecture');
+      state.role_architecture = input;
+      return successResult({ set: 'set_role_architecture' });
+    },
+  );
+
+  const setAuthzCandidates = tool(
+    'set_authz_candidates',
+    'Record authorization vulnerability candidates: horizontal escalation, vertical escalation, and ' +
+      'context-based candidates. Call exactly once before terminating. Becomes Sections 8.1, 8.2, and ' +
+      '8.3 of the rendered deliverable. The renderer assigns stable AUTHZ-CAND-NN IDs across the three ' +
+      'sub-arrays in horizontal → vertical → context order, which vuln-authz reads as its todo list. ' +
+      'Duplicate calls are rejected.',
+    AuthzCandidatesInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.authz_candidates) return alreadyCalled('set_authz_candidates');
+      state.authz_candidates = input;
+      return successResult({ set: 'set_authz_candidates' });
+    },
+  );
+
+  const setInjectionSources = tool(
+    'set_injection_sources',
+    'Record discovered injection sources grouped by vulnerability class. Call exactly once before ' +
+      'terminating. If the application has no network-accessible code paths to dangerous sinks, set ' +
+      'applicable=false; otherwise populate each category array (empty arrays mean "scanned, no sources ' +
+      'of this kind"). Becomes Section 9 of the rendered deliverable. Drives the vuln-injection agent\'s ' +
+      'todos downstream. Duplicate calls are rejected.',
+    InjectionSourcesInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.injection_sources) return alreadyCalled('set_injection_sources');
+      state.injection_sources = input;
+      return successResult({ set: 'set_injection_sources' });
+    },
+  );
+
+  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
+    name: 'recon-collector',
+    version: '1.0.0',
+    tools: [
+      setExecutiveSummary,
+      setTechnologyStack,
+      setAuthentication,
+      addEndpoints,
+      setInputVectors,
+      setNetworkMap,
+      setRoleArchitecture,
+      setAuthzCandidates,
+      setInjectionSources,
+    ],
+  });
+
+  function statusOf<K extends ReconOneShotToolName>(key: K): ReconToolStatus {
+    const flagMap: Record<ReconOneShotToolName, unknown> = {
+      set_executive_summary: state.executive_summary,
+      set_technology_stack: state.technology_stack,
+      set_authentication: state.authentication,
+      set_input_vectors: state.input_vectors,
+      set_network_map: state.network_map,
+      set_role_architecture: state.role_architecture,
+      set_authz_candidates: state.authz_candidates,
+      set_injection_sources: state.injection_sources,
+    };
+    return flagMap[key] ? 'called' : 'skipped';
+  }
+
+  return {
+    server,
+    getAll: (): ReconData => ({
+      ...(state.executive_summary && { executive_summary: state.executive_summary }),
+      ...(state.technology_stack && { technology_stack: state.technology_stack }),
+      ...(state.authentication && { authentication: state.authentication }),
+      ...(endpoints.length > 0 && { endpoints }),
+      ...(state.input_vectors && { input_vectors: state.input_vectors }),
+      ...(state.network_map && { network_map: state.network_map }),
+      ...(state.role_architecture && { role_architecture: state.role_architecture }),
+      ...(state.authz_candidates && { authz_candidates: state.authz_candidates }),
+      ...(state.injection_sources && { injection_sources: state.injection_sources }),
+    }),
+    getCallStatus: (): ReconCallStatus => ({
+      set_executive_summary: statusOf('set_executive_summary'),
+      set_technology_stack: statusOf('set_technology_stack'),
+      set_authentication: statusOf('set_authentication'),
+      add_endpoints: { calls: addEndpointsCalls, endpoints_seen: endpoints.length },
+      set_input_vectors: statusOf('set_input_vectors'),
+      set_network_map: statusOf('set_network_map'),
+      set_role_architecture: statusOf('set_role_architecture'),
+      set_authz_candidates: statusOf('set_authz_candidates'),
+      set_injection_sources: statusOf('set_injection_sources'),
+    }),
+  };
+}
+
+// Re-exported here so the renderer can import the shared sink type without
+// depending on pre-recon's collector by name.
+export type { SinkRef };

apps/worker/src/mcp-server/vuln-collector.ts

@@ -0,0 +1,512 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Vuln Collector MCP Server (factory parameterized by vulnerability class).
+ *
+ * Exposes 4 one-shot, Zod-validated MCP tools per vuln agent (injection, xss,
+ * auth, ssrf, authz) that feed a deterministic renderer producing
+ * {class}_analysis_deliverable.md:
+ *   - set_findings_summary       — §1 executive summary + §2 dominant patterns
+ *   - set_strategic_intelligence — §3, per-class schema
+ *   - set_safe_vectors           — §4, shared schema across classes
+ *   - set_blind_spots            — §5, shared schema across classes
+ *
+ * Only set_strategic_intelligence varies by class; the collector branches on
+ * vulnClass to assemble the right schema. The other 3 tools are identical
+ * across classes.
+ *
+ * Skipped tools surface as renderer placeholders, not activity failures.
+ * getCallStatus() exposes the per-run call pattern for logging. Each Zod
+ * schema's field-level descriptions carry the section guidance, so the SDK
+ * injects it into the agent's tool catalog.
+ */
+
+import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { type ZodRawShape, z } from 'zod';
+
+// ============================================================================
+// CLASS DISCRIMINATOR
+// ============================================================================
+
+export const VULN_CLASSES = ['injection', 'xss', 'auth', 'ssrf', 'authz'] as const;
+export type VulnClass = (typeof VULN_CLASSES)[number];
+
+// Classes whose deliverables carry a Section 5 (blind spots). The auth and ssrf
+// analyses have no blind-spots section, so the set_blind_spots tool is withheld
+// from those agents and the renderer omits the section. Single source of truth
+// for both the tool registration and the rendering gate.
+export const BLIND_SPOTS_CLASSES: ReadonlySet<VulnClass> = new Set<VulnClass>(['injection', 'xss', 'authz']);
+
+// ============================================================================
+// SHARED SCHEMAS — set_findings_summary, set_safe_vectors, set_blind_spots
+// ============================================================================
+
+const PatternSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .describe(
+      'Concise pattern name, e.g. "Weak Session Management", "Reflected XSS in Search Parameter", ' +
+        '"Insufficient URL Validation".',
+    ),
+  description: z.string().min(1).describe('One- to two-sentence description of the pattern observed in the codebase.'),
+  implication: z
+    .string()
+    .min(1)
+    .describe('One- to two-sentence implication for exploitation — what does this pattern enable an attacker to do.'),
+  representative_finding_ids: z
+    .array(z.string().min(1))
+    .min(1)
+    .describe(
+      'IDs of findings that exhibit this pattern (e.g. ["AUTH-VULN-01", "AUTH-VULN-02"]). Must match ' +
+        'IDs the agent has assigned in the structured-output exploitation queue.',
+    ),
+});
+
+export const FindingsSummaryInputSchema = z.object({
+  key_outcome: z
+    .string()
+    .min(1)
+    .describe(
+      'One to two sentences capturing the headline result of your analysis — what was found and its ' +
+        'severity profile (e.g. "Several high-confidence SQL injection vulnerabilities were identified; ' +
+        'all findings have been passed to the exploitation phase"). Becomes Section 1 of the rendered ' +
+        'deliverable.',
+    ),
+  patterns: z
+    .array(PatternSchema)
+    .describe(
+      'Complete list of dominant patterns observed across findings. Pass all patterns in one call. ' +
+        'Empty array is acceptable if no recurring patterns were observed — the deliverable will render ' +
+        '"No dominant patterns identified" for Section 2 in that case.',
+    ),
+});
+
+export const SafeVectorInputSchema = z.object({
+  subject: z
+    .string()
+    .min(1)
+    .describe(
+      'The specific subject of analysis. For injection/xss runs, the input parameter name (e.g. ' +
+        '"username", "redirect_url"). For auth/ssrf runs, the component or flow name (e.g. ' +
+        '"Password Hashing", "Webhook Configuration"). For authz runs, the endpoint (e.g. ' +
+        '"POST /api/auth/logout"). The renderer maps this to the class-appropriate column header.',
+    ),
+  location: z
+    .string()
+    .min(1)
+    .describe(
+      'File path with line number (e.g. "controllers/authController.js:45") or endpoint URL (e.g. ' +
+        '"/profile"). For authz runs, this is the guard location specifically (e.g. ' +
+        '"middleware/auth.js:45"). The renderer maps this to the class-appropriate column header.',
+    ),
+  defense_mechanism: z
+    .string()
+    .min(1)
+    .describe(
+      'The robust defense observed (e.g. "Prepared Statement (Parameter Binding)", "HTML Entity ' +
+        'Encoding", "Strict URL Whitelist Validation", "bcrypt.compare for constant-time check").',
+    ),
+  render_context: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      'XSS-only: the DOM render context for the validated vector — one of HTML_BODY, HTML_ATTRIBUTE, ' +
+        'JAVASCRIPT_STRING, URL_PARAM, CSS_VALUE. Omit (or pass null) for non-XSS classes; the renderer ' +
+        'only emits this column for the XSS deliverable.',
+    ),
+});
+
+export const SafeVectorsInputSchema = z.object({
+  vectors: z
+    .array(SafeVectorInputSchema)
+    .describe(
+      'All input vectors / components / endpoints that were analyzed and confirmed to have robust, ' +
+        'context-appropriate defenses. Empty array is acceptable but unusual — the deliverable will ' +
+        'render "No vectors confirmed secure during analysis" for Section 4 in that case. Becomes ' +
+        'Section 4 of the rendered deliverable. The renderer sorts by (subject, location) before ' +
+        'rendering, so emission order does not affect output.',
+    ),
+});
+
+export const BlindSpotItemSchema = z.object({
+  heading: z
+    .string()
+    .min(1)
+    .describe(
+      'Short heading for the blind spot (e.g. "Untraced Asynchronous Flows", ' +
+        '"Limited Visibility into Stored Procedures", "Minified JavaScript Bundle").',
+    ),
+  description: z
+    .string()
+    .min(1)
+    .describe(
+      'One to three sentences describing the analysis gap — what could not be traced, why, and what ' +
+        'the residual risk is.',
+    ),
+});
+
+export const BlindSpotsInputSchema = z.object({
+  items: z
+    .array(BlindSpotItemSchema)
+    .describe(
+      'Analysis constraints, untraced code paths, or other coverage gaps that should be noted. ' +
+        'Empty array is acceptable on high-coverage runs — the deliverable will render "No analysis ' +
+        'constraints or blind spots identified" for Section 5 in that case. Becomes Section 5 of the ' +
+        'rendered deliverable.',
+    ),
+});
+
+// ============================================================================
+// PER-CLASS set_strategic_intelligence SCHEMAS (flat — no nesting)
+// ============================================================================
+
+const InjectionStrategicIntelSchema = z.object({
+  defensive_evasion_waf: z
+    .string()
+    .min(1)
+    .describe(
+      'WAF behavior observed during analysis: active rules, common payloads blocked, identified ' +
+        'bypasses (e.g. "WAF blocks UNION SELECT but not time-based blind injection"). Write ' +
+        '"Not applicable — no WAF observed" if none was detected.',
+    ),
+  error_based_potential: z
+    .string()
+    .min(1)
+    .describe(
+      'Whether endpoints leak verbose database errors that enable error-based injection (e.g. ' +
+        '"/api/products returns verbose PostgreSQL error messages, prime target for error-based ' +
+        'exploitation"). Write "Not applicable" if no injection findings exist.',
+    ),
+  confirmed_database_technology: z
+    .string()
+    .min(1)
+    .describe(
+      'Database engine(s) confirmed via error syntax or function calls (e.g. "PostgreSQL, confirmed ' +
+        'via pg_sleep() and verbose error syntax"). Drives payload selection downstream. Write ' +
+        '"Not applicable" if no DB sinks in scope.',
+    ),
+});
+
+const XssStrategicIntelSchema = z.object({
+  csp_analysis: z
+    .string()
+    .min(1)
+    .describe(
+      'Content Security Policy observed and its bypassability: current policy text, critical bypasses ' +
+        "(e.g. \"script-src 'self' https://trusted-cdn.com — the trusted CDN hosts vulnerable AngularJS, " +
+        'enabling client-side template injection bypass"). Write "Not applicable — no CSP header served" ' +
+        'if none.',
+    ),
+  cookie_security: z
+    .string()
+    .min(1)
+    .describe(
+      'Session cookie security observations: HttpOnly, Secure, SameSite flags, and storage mechanism ' +
+        '(e.g. "Primary session cookie `sessionid` is missing HttpOnly; tokens are also stored in ' +
+        'localStorage, both accessible to JavaScript"). Drives exfiltration strategy.',
+    ),
+});
+
+const AuthStrategicIntelSchema = z.object({
+  authentication_method: z
+    .string()
+    .min(1)
+    .describe(
+      'How users authenticate: JWT, session cookie, OAuth, SAML, etc. Include any algorithm or library ' +
+        'details (e.g. "JWT (RS256) with hardcoded private key in lib/insecurity.ts:23").',
+    ),
+  session_token_details: z
+    .string()
+    .min(1)
+    .describe(
+      'Where tokens live and how they are protected: cookie name, storage mechanism (cookie vs ' +
+        'localStorage), cookie flags, expiration (e.g. "JWT stored in localStorage under key `token`; ' +
+        'cookie copy lacks HttpOnly/Secure/SameSite; 6-hour TTL with no revocation").',
+    ),
+  password_policy: z
+    .string()
+    .min(1)
+    .describe(
+      'Observed server-side password policy and storage: complexity rules, hashing algorithm, salt, ' +
+        '(e.g. "MD5 without salt via crypto.createHash; no server-side complexity policy; client-side ' +
+        '5-char minimum trivially bypassed").',
+    ),
+});
+
+const SsrfStrategicIntelSchema = z.object({
+  http_client_library: z
+    .string()
+    .min(1)
+    .describe(
+      'HTTP client library/libraries used for outbound requests (e.g. "axios 1.6", "node-fetch", ' +
+        '"requests", "HttpClient (Spring)"). Include version where it informs known bypass techniques.',
+    ),
+  request_architecture: z
+    .string()
+    .min(1)
+    .describe(
+      'How outbound requests are constructed and routed: proxy/middleware patterns, internal routing ' +
+        'rules (e.g. "Webhook URLs are POSTed directly without an outbound proxy; redirects are ' +
+        'followed by default with no maxRedirects limit").',
+    ),
+  internal_services: z
+    .string()
+    .min(1)
+    .describe(
+      'Internal endpoints, services, or cloud-metadata addresses discovered during analysis that an ' +
+        'SSRF could reach (e.g. "169.254.169.254 (AWS IMDS), internal admin API at admin.internal:8443, ' +
+        'PostgreSQL on localhost:5432").',
+    ),
+});
+
+const AuthzStrategicIntelSchema = z.object({
+  session_management_architecture: z
+    .string()
+    .min(1)
+    .describe(
+      'Session and authentication architecture relevant to authorization decisions: where user identity ' +
+        'comes from, whether the user ID is trusted by downstream guards (e.g. "JWT tokens in cookies; ' +
+        'user ID extracted from `req.user.id` and used directly in DB queries without ownership ' +
+        're-validation").',
+    ),
+  role_permission_model: z
+    .string()
+    .min(1)
+    .describe(
+      'Roles, capabilities, and where they live: identified roles, their privilege levels, and where ' +
+        'role/permission data is stored (e.g. "Three roles: user, moderator, admin. Role embedded in ' +
+        'JWT and database; checks inconsistent — many admin routes only check `req.user` presence").',
+    ),
+  resource_access_patterns: z
+    .string()
+    .min(1)
+    .describe(
+      'How resource IDs flow through the system and ownership patterns: e.g. "Most endpoints use path ' +
+        'parameters for resource IDs (/api/users/{id}); IDs are passed to DB queries without ownership ' +
+        'validation". Critical for IDOR exploitation.',
+    ),
+  workflow_implementation: z
+    .string()
+    .min(1)
+    .describe(
+      'Multi-step processes and state transitions: how workflow stages are tracked, whether prior-state ' +
+        'checks are enforced (e.g. "Multi-step processes use status fields in database; status ' +
+        'transitions do not verify prior state completion"). Drives context-based authz exploitation.',
+    ),
+});
+
+const STRATEGIC_INTEL_SCHEMAS: Record<VulnClass, z.ZodObject<ZodRawShape>> = {
+  injection: InjectionStrategicIntelSchema,
+  xss: XssStrategicIntelSchema,
+  auth: AuthStrategicIntelSchema,
+  ssrf: SsrfStrategicIntelSchema,
+  authz: AuthzStrategicIntelSchema,
+};
+
+// ============================================================================
+// EXPORTED TYPES
+// ============================================================================
+
+export type Pattern = z.infer<typeof PatternSchema>;
+export type FindingsSummaryInput = z.infer<typeof FindingsSummaryInputSchema>;
+export type SafeVectorInput = z.infer<typeof SafeVectorInputSchema>;
+export type SafeVectorsInput = z.infer<typeof SafeVectorsInputSchema>;
+export type BlindSpotItem = z.infer<typeof BlindSpotItemSchema>;
+export type BlindSpotsInput = z.infer<typeof BlindSpotsInputSchema>;
+
+export type InjectionStrategicIntel = z.infer<typeof InjectionStrategicIntelSchema>;
+export type XssStrategicIntel = z.infer<typeof XssStrategicIntelSchema>;
+export type AuthStrategicIntel = z.infer<typeof AuthStrategicIntelSchema>;
+export type SsrfStrategicIntel = z.infer<typeof SsrfStrategicIntelSchema>;
+export type AuthzStrategicIntel = z.infer<typeof AuthzStrategicIntelSchema>;
+
+// Discriminated by the agent class context — the renderer reads only the
+// sub-fields that apply to the active class.
+export type StrategicIntelligenceInput =
+  | InjectionStrategicIntel
+  | XssStrategicIntel
+  | AuthStrategicIntel
+  | SsrfStrategicIntel
+  | AuthzStrategicIntel;
+
+export interface VulnCollectorData {
+  readonly findings_summary?: FindingsSummaryInput;
+  readonly strategic_intelligence?: StrategicIntelligenceInput;
+  readonly safe_vectors?: SafeVectorsInput;
+  readonly blind_spots?: BlindSpotsInput;
+}
+
+export const VULN_TOOLS = [
+  'set_findings_summary',
+  'set_strategic_intelligence',
+  'set_safe_vectors',
+  'set_blind_spots',
+] as const;
+
+export type VulnToolName = (typeof VULN_TOOLS)[number];
+
+export type VulnToolStatus = 'called' | 'skipped';
+
+export type VulnCallStatus = Readonly<Record<VulnToolName, VulnToolStatus>>;
+
+// ============================================================================
+// RESPONSE HELPERS
+// ============================================================================
+
+interface ToolResult {
+  [x: string]: unknown;
+  content: Array<{ type: 'text'; text: string }>;
+  isError: boolean;
+}
+
+function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+    isError: response.status === 'error',
+  };
+}
+
+function successResult(data: Record<string, unknown>): ToolResult {
+  return createToolResult({ status: 'success', ...data });
+}
+
+function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
+  return createToolResult({ status: 'error', message, errorType, retryable });
+}
+
+// ============================================================================
+// SERVER FACTORY
+// ============================================================================
+
+export interface VulnCollectorServer {
+  server: McpSdkServerConfigWithInstance;
+  getAll(): VulnCollectorData;
+  getCallStatus(): VulnCallStatus;
+}
+
+export function createVulnCollector(vulnClass: VulnClass): VulnCollectorServer {
+  const state: {
+    findings_summary?: FindingsSummaryInput;
+    strategic_intelligence?: StrategicIntelligenceInput;
+    safe_vectors?: SafeVectorsInput;
+    blind_spots?: BlindSpotsInput;
+  } = {};
+
+  function alreadyCalled(toolName: VulnToolName): ToolResult {
+    return errorResult(
+      `${toolName} has already been called. Each tool may only be called once per run.`,
+      'DuplicateError',
+      false,
+    );
+  }
+
+  const setFindingsSummary = tool(
+    'set_findings_summary',
+    'Record the executive summary headline and the dominant vulnerability patterns observed across ' +
+      'your findings. Call exactly once before terminating. Becomes Section 1 (key outcome) and ' +
+      'Section 2 (patterns) of the rendered deliverable — this is the load-bearing emission for the ' +
+      'narrative .md and is required. Duplicate calls return "already called" and are no-ops. Empty ' +
+      'patterns array is acceptable (renders as "No dominant patterns identified") but key_outcome ' +
+      'is always required.',
+    FindingsSummaryInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.findings_summary) return alreadyCalled('set_findings_summary');
+      state.findings_summary = input;
+      return successResult({ set: 'set_findings_summary' });
+    },
+  );
+
+  const intelSchema = STRATEGIC_INTEL_SCHEMAS[vulnClass];
+  const setStrategicIntelligence = tool(
+    'set_strategic_intelligence',
+    `Record the environmental and defensive intelligence relevant to exploiting the ${vulnClass} ` +
+      'findings. Call exactly once before terminating. Becomes Section 3 of the rendered deliverable ' +
+      `and is the section the downstream exploit-${vulnClass} agent reads for strategic context. ` +
+      'Required. Duplicate calls return "already called" and are no-ops. Write "Not applicable" as ' +
+      'the field value when a sub-field does not apply to this run (rather than omitting).',
+    intelSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.strategic_intelligence) return alreadyCalled('set_strategic_intelligence');
+      state.strategic_intelligence = input as unknown as StrategicIntelligenceInput;
+      return successResult({ set: 'set_strategic_intelligence' });
+    },
+  );
+
+  const setSafeVectors = tool(
+    'set_safe_vectors',
+    'Record the input vectors, components, or endpoints that were analyzed and confirmed to have ' +
+      'robust, context-appropriate defenses. Call exactly once before terminating. Becomes Section 4 ' +
+      'of the rendered deliverable. Recommended (empty array is acceptable on runs where no vectors ' +
+      'were validated as safe, but explicit emission is preferred). The renderer sorts by ' +
+      '(subject, location) before rendering, so emission order does not affect output. Duplicate ' +
+      'calls return "already called" and are no-ops.',
+    SafeVectorsInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.safe_vectors) return alreadyCalled('set_safe_vectors');
+      state.safe_vectors = input;
+      return successResult({ set: 'set_safe_vectors', count: input.vectors.length });
+    },
+  );
+
+  const setBlindSpots = tool(
+    'set_blind_spots',
+    'Record analysis constraints, untraced code paths, or other coverage gaps. Call exactly once ' +
+      'before terminating. Becomes Section 5 of the rendered deliverable. Recommended (empty array ' +
+      'is acceptable on high-coverage runs, but explicit emission is preferred — readers expect ' +
+      'either documented gaps or an explicit "no gaps" signal). Duplicate calls return "already ' +
+      'called" and are no-ops.',
+    BlindSpotsInputSchema.shape,
+    async (input): Promise<ToolResult> => {
+      if (state.blind_spots) return alreadyCalled('set_blind_spots');
+      state.blind_spots = input;
+      return successResult({ set: 'set_blind_spots', count: input.items.length });
+    },
+  );
+
+  // set_blind_spots is withheld from classes without a Section 5 (auth, ssrf).
+  const tools = [
+    setFindingsSummary,
+    setStrategicIntelligence,
+    setSafeVectors,
+    ...(BLIND_SPOTS_CLASSES.has(vulnClass) ? [setBlindSpots] : []),
+  ];
+
+  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
+    name: 'vuln-collector',
+    version: '1.0.0',
+    tools,
+  });
+
+  function statusOf<K extends VulnToolName>(key: K): VulnToolStatus {
+    const flagMap: Record<VulnToolName, unknown> = {
+      set_findings_summary: state.findings_summary,
+      set_strategic_intelligence: state.strategic_intelligence,
+      set_safe_vectors: state.safe_vectors,
+      set_blind_spots: state.blind_spots,
+    };
+    return flagMap[key] ? 'called' : 'skipped';
+  }
+
+  return {
+    server,
+    getAll: (): VulnCollectorData => ({
+      ...(state.findings_summary && { findings_summary: state.findings_summary }),
+      ...(state.strategic_intelligence && { strategic_intelligence: state.strategic_intelligence }),
+      ...(state.safe_vectors && { safe_vectors: state.safe_vectors }),
+      ...(state.blind_spots && { blind_spots: state.blind_spots }),
+    }),
+    getCallStatus: (): VulnCallStatus => ({
+      set_findings_summary: statusOf('set_findings_summary'),
+      set_strategic_intelligence: statusOf('set_strategic_intelligence'),
+      set_safe_vectors: statusOf('set_safe_vectors'),
+      set_blind_spots: statusOf('set_blind_spots'),
+    }),
+  };
+}

apps/worker/src/paths.ts

@@ -9,6 +9,21 @@ const WORKER_ROOT = path.resolve(import.meta.dirname, '..');
 export const PROMPTS_DIR = path.join(WORKER_ROOT, 'prompts');
 export const CONFIGS_DIR = path.join(WORKER_ROOT, 'configs');
 
+/** Default deliverables subdirectory relative to repoPath */
+export const DEFAULT_DELIVERABLES_SUBDIR = '.shannon/deliverables';
+
+/** Default audit log directory */
+export const DEFAULT_AUDIT_DIR = './workspaces';
+
+/**
+ * Resolve the deliverables directory for a given repoPath and optional subdir override.
+ * @param repoPath - Absolute path to the target repository
+ * @param subdir - Subdirectory relative to repoPath (default: '.shannon/deliverables')
+ */
+export function deliverablesDir(repoPath: string, subdir: string = DEFAULT_DELIVERABLES_SUBDIR): string {
+  return path.join(repoPath, ...subdir.split('/'));
+}
+
 /**
  * Repository root — walk up from WORKER_ROOT looking for pnpm-workspace.yaml.
  * Falls back to two levels up (apps/worker/ → repo root) if not found.

apps/worker/src/scripts/generate-totp.ts

@@ -82,6 +82,26 @@ function generateTOTP(secret: string, timeStep: number = 30, digits: number = 6)
   return generateHOTP(secret, counter, digits);
 }
 
+// === Help ===
+
+function printHelp(): void {
+  console.log(
+    `generate-totp - emit a current 6-digit TOTP code for a base32-encoded secret.
+
+Usage:
+  generate-totp --secret <BASE32>
+  generate-totp --help
+
+Options:
+  --secret      Base32-encoded TOTP shared secret (characters A-Z, 2-7).
+  -h, --help    Show this help and exit.
+
+Output:
+  JSON to stdout. On success: {"status":"success","totpCode":"123456","expiresIn":<sec>}.
+  On error:   {"status":"error","message":"...","retryable":false} (exit 1).`,
+  );
+}
+
 // === Argument Parsing ===
 
 function parseSecret(argv: string[]): string {
@@ -97,6 +117,11 @@ function parseSecret(argv: string[]): string {
 // === Main ===
 
 function main(): void {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    printHelp();
+    return;
+  }
+
   const secret = parseSecret(process.argv);
 
   if (!secret) {

apps/worker/src/scripts/save-deliverable.ts

@@ -9,17 +9,40 @@
 /**
  * save-deliverable CLI
  *
- * Standalone script to save deliverable files with validation.
- * Replaces the MCP save_deliverable tool.
+ * Standalone script to save deliverable files.
  *
  * Usage:
- *   node save-deliverable.js --type INJECTION_QUEUE --content '{"vulnerabilities": [...]}'
  *   node save-deliverable.js --type INJECTION_ANALYSIS --file-path deliverables/injection_analysis_deliverable.md
  */
 
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { DELIVERABLE_FILENAMES, type DeliverableType, isQueueType } from '../types/deliverables.js';
+import { DELIVERABLE_FILENAMES, type DeliverableType } from '../types/deliverables.js';
+
+// === Help ===
+
+function printHelp(): void {
+  const types = Object.keys(DELIVERABLE_FILENAMES).join(', ');
+  console.log(
+    `save-deliverable - save a Shannon pentest deliverable under its canonical filename.
+
+Usage:
+  save-deliverable --type <TYPE> --file-path <path>
+  save-deliverable --type <TYPE> --content '<text>'
+  save-deliverable --help
+
+Options:
+  --type        Deliverable type (required). One of:
+                  ${types}
+  --file-path   Path of a file whose contents to save (preferred for large content).
+  --content     Inline content string to save.
+  -h, --help    Show this help and exit.
+
+Output:
+  JSON to stdout. On success: {"status":"success","filepath":"..."}.
+  On error:   {"status":"error","message":"...","retryable":true|false} (exit 1).`,
+  );
+}
 
 // === Argument Parsing ===
 
@@ -51,53 +74,11 @@ function parseArgs(argv: string[]): ParsedArgs {
   return args;
 }
 
-// === Queue Validation ===
-
-interface ValidationResult {
-  valid: boolean;
-  message?: string;
-}
-
-function validateQueueJson(content: string): ValidationResult {
-  try {
-    const parsed = JSON.parse(content) as unknown;
-
-    if (typeof parsed !== 'object' || parsed === null) {
-      return {
-        valid: false,
-        message: `Invalid queue structure: Expected an object. Got: ${typeof parsed}`,
-      };
-    }
-
-    const obj = parsed as Record<string, unknown>;
-
-    if (!('vulnerabilities' in obj)) {
-      return {
-        valid: false,
-        message: `Invalid queue structure: Missing 'vulnerabilities' property. Expected: {"vulnerabilities": [...]}`,
-      };
-    }
-
-    if (!Array.isArray(obj.vulnerabilities)) {
-      return {
-        valid: false,
-        message: `Invalid queue structure: 'vulnerabilities' must be an array. Expected: {"vulnerabilities": [...]}`,
-      };
-    }
-
-    return { valid: true };
-  } catch (error) {
-    return {
-      valid: false,
-      message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-}
-
 // === File Operations ===
 
 function saveDeliverableFile(targetDir: string, filename: string, content: string): string {
-  const deliverablesDir = join(targetDir, 'deliverables');
+  const subdir = process.env.SHANNON_DELIVERABLES_SUBDIR || '.shannon/deliverables';
+  const deliverablesDir = join(targetDir, ...subdir.split('/'));
   const filepath = join(deliverablesDir, filename);
 
   try {
@@ -113,6 +94,11 @@ function saveDeliverableFile(targetDir: string, filename: string, content: strin
 // === Main ===
 
 function main(): void {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    printHelp();
+    return;
+  }
+
   const args = parseArgs(process.argv);
 
   // 1. Validate --type
@@ -165,22 +151,11 @@ function main(): void {
     process.exit(1);
   }
 
-  // 3. Validate queue types
-  let validated = false;
-  if (isQueueType(args.type)) {
-    const validation = validateQueueJson(content);
-    if (!validation.valid) {
-      console.log(JSON.stringify({ status: 'error', message: validation.message, retryable: true }));
-      process.exit(1);
-    }
-    validated = true;
-  }
-
-  // 4. Save the file
+  // 3. Save the file
   try {
     const targetDir = process.cwd();
     const filepath = saveDeliverableFile(targetDir, filename, content);
-    console.log(JSON.stringify({ status: 'success', filepath, validated }));
+    console.log(JSON.stringify({ status: 'success', filepath }));
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
     console.log(JSON.stringify({ status: 'error', message: `Failed to save: ${msg}`, retryable: true }));

apps/worker/src/services/agent-execution.ts

@@ -16,13 +16,17 @@
  * - Spending cap check using isSpendingCapBehavior
  * - Handle failure (rollback, audit)
  * - Validate output using AGENTS[agentName].deliverableFilename
+ * - Render the deliverable to disk via the writeDeliverable hook (if provided)
  * - Commit on success, log metrics
  *
  * No Temporal dependencies - pure domain logic.
  */
 
+import { fs, path } from 'zx';
 import { type ClaudePromptResult, runClaudePrompt, validateAgentOutput } from '../ai/claude-executor.js';
+import { getOutputFormat, getQueueFilename } from '../ai/queue-schemas.js';
 import type { AuditSession } from '../audit/index.js';
+import { authStateFile } from '../audit/utils.js';
 import { AGENTS } from '../session-manager.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
 import type { AgentName } from '../types/agents.js';
@@ -42,9 +46,18 @@ import { loadPrompt } from './prompt-manager.js';
 export interface AgentExecutionInput {
   webUrl: string;
   repoPath: string;
+  deliverablesPath: string;
   configPath?: string | undefined;
+  configData?: import('../types/config.js').DistributedConfig | undefined;
+  configYAML?: string | undefined;
   pipelineTestingMode?: boolean | undefined;
   attemptNumber: number;
+  apiKey?: string | undefined;
+  promptDir?: string | undefined;
+  providerConfig?: import('../types/config.js').ProviderConfig | undefined;
+  mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>;
+  // Renders the deliverable to disk; invoked after validation, before the success commit.
+  writeDeliverable?: (deliverablesPath: string) => Promise<void>;
 }
 
 interface FailAgentOpts {
@@ -87,10 +100,24 @@ export class AgentExecutionService {
     auditSession: AuditSession,
     logger: ActivityLogger,
   ): Promise<Result<AgentEndResult, PentestError>> {
-    const { webUrl, repoPath, configPath, pipelineTestingMode = false, attemptNumber } = input;
+    const {
+      webUrl,
+      repoPath,
+      deliverablesPath,
+      configPath,
+      configData,
+      configYAML,
+      pipelineTestingMode = false,
+      attemptNumber,
+      apiKey,
+      promptDir,
+      providerConfig,
+      mcpServers,
+      writeDeliverable,
+    } = input;
 
-    // 1. Load config (if provided)
-    const configResult = await this.configLoader.loadOptional(configPath);
+    // 1. Load config (pre-parsed configData → raw YAML → file path)
+    const configResult = await this.configLoader.loadOptional(configPath, configData, configYAML);
     if (isErr(configResult)) {
       return configResult;
     }
@@ -100,7 +127,14 @@ export class AgentExecutionService {
     const promptTemplate = AGENTS[agentName].promptTemplate;
     let prompt: string;
     try {
-      prompt = await loadPrompt(promptTemplate, { webUrl, repoPath }, distributedConfig, pipelineTestingMode, logger);
+      prompt = await loadPrompt(
+        promptTemplate,
+        { webUrl, repoPath, AUTH_STATE_FILE: authStateFile(auditSession.sessionMetadata) },
+        distributedConfig,
+        pipelineTestingMode,
+        logger,
+        promptDir,
+      );
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       return err(
@@ -116,7 +150,7 @@ export class AgentExecutionService {
 
     // 3. Create git checkpoint before execution
     try {
-      await createGitCheckpoint(repoPath, agentName, attemptNumber, logger);
+      await createGitCheckpoint(deliverablesPath, agentName, attemptNumber, logger);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       return err(
@@ -124,7 +158,7 @@ export class AgentExecutionService {
           `Failed to create git checkpoint for ${agentName}: ${errorMessage}`,
           'filesystem',
           false,
-          { agentName, repoPath, originalError: errorMessage },
+          { agentName, deliverablesPath, originalError: errorMessage },
           ErrorCode.GIT_CHECKPOINT_FAILED,
         ),
       );
@@ -134,6 +168,7 @@ export class AgentExecutionService {
     await auditSession.startAgent(agentName, prompt, attemptNumber);
 
     // 5. Execute agent
+    const outputFormat = getOutputFormat(agentName, distributedConfig?.exploit ?? true);
     const result: ClaudePromptResult = await runClaudePrompt(
       prompt,
       repoPath,
@@ -143,13 +178,18 @@ export class AgentExecutionService {
       auditSession,
       logger,
       AGENTS[agentName].modelTier,
+      outputFormat,
+      apiKey,
+      path.relative(repoPath, deliverablesPath),
+      providerConfig,
+      mcpServers,
     );
 
     // 6. Spending cap check - defense-in-depth
     if (result.success && (result.turns ?? 0) <= 2 && (result.cost || 0) === 0) {
       const resultText = result.result || '';
       if (isSpendingCapBehavior(result.turns ?? 0, result.cost || 0, resultText)) {
-        return this.failAgent(agentName, repoPath, auditSession, logger, {
+        return this.failAgent(agentName, deliverablesPath, auditSession, logger, {
           attemptNumber,
           result,
           rollbackReason: 'spending cap detected',
@@ -164,7 +204,7 @@ export class AgentExecutionService {
 
     // 7. Handle execution failure
     if (!result.success) {
-      return this.failAgent(agentName, repoPath, auditSession, logger, {
+      return this.failAgent(agentName, deliverablesPath, auditSession, logger, {
         attemptNumber,
         result,
         rollbackReason: 'execution failure',
@@ -176,10 +216,19 @@ export class AgentExecutionService {
       });
     }
 
-    // 8. Validate output
-    const validationPassed = await validateAgentOutput(result, agentName, repoPath, logger);
+    // 8. Write structured output to disk (vuln agents only)
+    const queueFilename = getQueueFilename(agentName);
+    if (result.structuredOutput !== undefined && queueFilename) {
+      await fs.ensureDir(deliverablesPath);
+      const queuePath = path.join(deliverablesPath, queueFilename);
+      await fs.writeFile(queuePath, JSON.stringify(result.structuredOutput, null, 2), 'utf8');
+      logger.info(`Wrote structured output queue to ${queueFilename}`);
+    }
+
+    // 9. Validate output
+    const validationPassed = await validateAgentOutput(result, agentName, deliverablesPath, logger);
     if (!validationPassed) {
-      return this.failAgent(agentName, repoPath, auditSession, logger, {
+      return this.failAgent(agentName, deliverablesPath, auditSession, logger, {
         attemptNumber,
         result,
         rollbackReason: 'validation failure',
@@ -191,9 +240,14 @@ export class AgentExecutionService {
       });
     }
 
-    // 9. Success - commit deliverables, then capture checkpoint hash
-    await commitGitSuccess(repoPath, agentName, logger);
-    const commitHash = await getGitCommitHash(repoPath);
+    // 10. Render the deliverable to disk so the success commit below stages it
+    if (writeDeliverable) {
+      await writeDeliverable(deliverablesPath);
+    }
+
+    // 11. Success - commit deliverables, then capture checkpoint hash
+    await commitGitSuccess(deliverablesPath, agentName, logger);
+    const commitHash = await getGitCommitHash(deliverablesPath);
 
     const endResult: AgentEndResult = {
       attemptNumber,
@@ -210,12 +264,12 @@ export class AgentExecutionService {
 
   private async failAgent(
     agentName: AgentName,
-    repoPath: string,
+    deliverablesPath: string,
     auditSession: AuditSession,
     logger: ActivityLogger,
     opts: FailAgentOpts,
   ): Promise<Result<AgentEndResult, PentestError>> {
-    await rollbackGitWorkspace(repoPath, opts.rollbackReason, logger);
+    await rollbackGitWorkspace(deliverablesPath, opts.rollbackReason, logger);
 
     const endResult: AgentEndResult = {
       attemptNumber: opts.attemptNumber,

apps/worker/src/services/config-loader.ts

@@ -11,7 +11,7 @@
  * Pure service with no Temporal dependencies.
  */
 
-import { distributeConfig, parseConfig } from '../config-parser.js';
+import { distributeConfig, parseConfig, parseConfigYAML } from '../config-parser.js';
 import type { DistributedConfig } from '../types/config.js';
 import { ErrorCode } from '../types/errors.js';
 import { err, ok, type Result } from '../types/result.js';
@@ -60,11 +60,37 @@ export class ConfigLoaderService {
 
   /**
    * Load config if path is provided, otherwise return null config.
+   * If configData is provided (pre-parsed), returns it directly without file I/O.
    *
    * @param configPath - Optional path to the YAML configuration file
+   * @param configData - Optional pre-parsed config (bypasses file loading)
    * @returns Result containing DistributedConfig (or null) on success, PentestError on failure
    */
-  async loadOptional(configPath: string | undefined): Promise<Result<DistributedConfig | null, PentestError>> {
+  async loadOptional(
+    configPath: string | undefined,
+    configData?: DistributedConfig,
+    configYAML?: string,
+  ): Promise<Result<DistributedConfig | null, PentestError>> {
+    if (configData) {
+      return ok(configData);
+    }
+    if (configYAML) {
+      try {
+        const config = parseConfigYAML(configYAML);
+        return ok(distributeConfig(config));
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return err(
+          new PentestError(
+            `Failed to parse config YAML: ${errorMessage}`,
+            'config',
+            false,
+            { originalError: errorMessage },
+            ErrorCode.CONFIG_PARSE_ERROR,
+          ),
+        );
+      }
+    }
     if (!configPath) {
       return ok(null);
     }

apps/worker/src/services/container.ts

@@ -18,6 +18,13 @@
  */
 
 import type { SessionMetadata } from '../audit/utils.js';
+import type { CheckpointProvider } from '../interfaces/checkpoint-provider.js';
+import { NoOpCheckpointProvider } from '../interfaces/checkpoint-provider.js';
+import type { FindingsProvider } from '../interfaces/findings-provider.js';
+import { NoOpFindingsProvider } from '../interfaces/findings-provider.js';
+import type { ReportOutputProvider } from '../interfaces/report-output-provider.js';
+import { NoOpReportOutputProvider } from '../interfaces/report-output-provider.js';
+import type { ContainerConfig } from '../types/config.js';
 import { AgentExecutionService } from './agent-execution.js';
 import { ConfigLoaderService } from './config-loader.js';
 import { ExploitationCheckerService } from './exploitation-checker.js';
@@ -32,6 +39,10 @@ import { ExploitationCheckerService } from './exploitation-checker.js';
  */
 export interface ContainerDependencies {
   readonly sessionMetadata: SessionMetadata;
+  readonly config: ContainerConfig;
+  readonly findingsProvider?: FindingsProvider;
+  readonly checkpointProvider?: CheckpointProvider;
+  readonly reportOutputProvider?: ReportOutputProvider;
 }
 
 /**
@@ -45,17 +56,27 @@ export interface ContainerDependencies {
  */
 export class Container {
   readonly sessionMetadata: SessionMetadata;
+  readonly config: ContainerConfig;
   readonly agentExecution: AgentExecutionService;
   readonly configLoader: ConfigLoaderService;
   readonly exploitationChecker: ExploitationCheckerService;
+  readonly findingsProvider: FindingsProvider;
+  readonly checkpointProvider: CheckpointProvider;
+  readonly reportOutputProvider: ReportOutputProvider;
 
   constructor(deps: ContainerDependencies) {
     this.sessionMetadata = deps.sessionMetadata;
+    this.config = deps.config;
 
     // Wire services with explicit constructor injection
     this.configLoader = new ConfigLoaderService();
     this.exploitationChecker = new ExploitationCheckerService();
     this.agentExecution = new AgentExecutionService(this.configLoader);
+
+    // Wire providers with default no-ops when not provided
+    this.findingsProvider = deps.findingsProvider ?? new NoOpFindingsProvider();
+    this.checkpointProvider = deps.checkpointProvider ?? new NoOpCheckpointProvider();
+    this.reportOutputProvider = deps.reportOutputProvider ?? new NoOpReportOutputProvider();
   }
 }
 
@@ -65,6 +86,34 @@ export class Container {
  */
 const containers = new Map<string, Container>();
 
+/** Default container config — OSS standalone defaults */
+const DEFAULT_CONFIG: ContainerConfig = {
+  deliverablesSubdir: '.shannon/deliverables',
+  auditDir: './workspaces',
+};
+
+/**
+ * Factory function for creating containers.
+ *
+ * Default: creates a plain Container with NoOp providers. Consumers can call
+ * setContainerFactory() at worker startup to inject custom provider
+ * implementations into every container.
+ */
+type ContainerFactory = (workflowId: string, sessionMetadata: SessionMetadata, config: ContainerConfig) => Container;
+
+let containerFactory: ContainerFactory = (_workflowId, sessionMetadata, config) =>
+  new Container({ sessionMetadata, config });
+
+/**
+ * Override the default container factory.
+ *
+ * Call once at worker startup to inject providers into all containers
+ * created during the worker's lifetime.
+ */
+export function setContainerFactory(factory: ContainerFactory): void {
+  containerFactory = factory;
+}
+
 /**
  * Get or create a Container for a workflow.
  *
@@ -73,13 +122,18 @@ const containers = new Map<string, Container>();
  *
  * @param workflowId - Unique workflow identifier
  * @param sessionMetadata - Session metadata for audit paths
+ * @param config - Runtime configuration (defaults to OSS standalone config)
  * @returns Container instance for the workflow
  */
-export function getOrCreateContainer(workflowId: string, sessionMetadata: SessionMetadata): Container {
+export function getOrCreateContainer(
+  workflowId: string,
+  sessionMetadata: SessionMetadata,
+  config: ContainerConfig = DEFAULT_CONFIG,
+): Container {
   let container = containers.get(workflowId);
 
   if (!container) {
-    container = new Container({ sessionMetadata });
+    container = containerFactory(workflowId, sessionMetadata, config);
     containers.set(workflowId, container);
   }
 

apps/worker/src/services/error-handling.ts

@@ -138,6 +138,9 @@ function classifyByErrorCode(code: ErrorCode, retryableFromError: boolean): { ty
     case ErrorCode.AUTH_FAILED:
       return { type: 'AuthenticationError', retryable: false };
 
+    case ErrorCode.AUTH_LOGIN_FAILED:
+      return { type: 'AuthLoginFailedError', retryable: false };
+
     case ErrorCode.BILLING_ERROR:
       return { type: 'BillingError', retryable: true };
 

apps/worker/src/services/exploit-renderer.ts

@@ -0,0 +1,196 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Deterministic exploit collector → markdown renderer.
+ *
+ * Single entry point renderExploitDeliverable(vulnClass, state, idToType)
+ * covers all 5 exploitation agents (injection, xss, auth, ssrf, authz). The
+ * per-class deltas are limited to title and ID prefix; every section, label,
+ * and sort rule is class-agnostic. Section headers and bolded field labels
+ * give downstream report-executive — which reads prose with bolded labels —
+ * a consistent structure to parse, with a single canonical label per field
+ * across all classes.
+ *
+ * Sort order is owned by the renderer:
+ *   - Successfully Exploited: severity desc (critical → low), then ID asc.
+ *   - Potential / Validation Blocked: confidence desc (high → low), then ID asc.
+ */
+
+import type { AddExploitInput, VulnClass } from '../mcp-server/exploit-collector.js';
+
+// ============================================================================
+// PER-CLASS CONSTANTS
+// ============================================================================
+
+const TITLES: Record<VulnClass, string> = {
+  injection: 'Injection Exploitation Evidence',
+  xss: 'Cross-Site Scripting (XSS) Exploitation Evidence',
+  auth: 'Authentication Exploitation Evidence',
+  ssrf: 'SSRF Exploitation Evidence',
+  authz: 'Authorization Exploitation Evidence',
+};
+
+// ============================================================================
+// SORT ORDER
+// ============================================================================
+
+const SEVERITY_ORDER: Record<'critical' | 'high' | 'medium' | 'low', number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+};
+
+const CONFIDENCE_ORDER: Record<'high' | 'medium' | 'low', number> = {
+  high: 0,
+  medium: 1,
+  low: 2,
+};
+
+type ExploitedEntry = Extract<AddExploitInput, { status: 'exploited' }>;
+type BlockedEntry = Extract<AddExploitInput, { status: 'blocked' }>;
+
+function sortExploited(entries: readonly ExploitedEntry[]): ExploitedEntry[] {
+  return [...entries].sort((a, b) => {
+    const sevDiff = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return a.vulnerability_id.localeCompare(b.vulnerability_id);
+  });
+}
+
+function sortBlocked(entries: readonly BlockedEntry[]): BlockedEntry[] {
+  return [...entries].sort((a, b) => {
+    const confDiff = CONFIDENCE_ORDER[a.confidence] - CONFIDENCE_ORDER[b.confidence];
+    if (confDiff !== 0) return confDiff;
+    return a.vulnerability_id.localeCompare(b.vulnerability_id);
+  });
+}
+
+// ============================================================================
+// FIELD FORMATTERS
+// ============================================================================
+
+function capitalize(value: string): string {
+  if (value.length === 0) return value;
+  return value[0]!.toUpperCase() + value.slice(1);
+}
+
+function renderNumberedList(steps: readonly string[]): string {
+  return steps.map((step, idx) => `${idx + 1}. ${step}`).join('\n\n');
+}
+
+// ============================================================================
+// PER-FINDING RENDERERS
+// ============================================================================
+
+function renderExploitedFinding(entry: ExploitedEntry): string {
+  const lines: string[] = [];
+  lines.push(`### ${entry.vulnerability_id}: ${entry.title}`);
+  lines.push('');
+  lines.push('**Summary:**');
+  lines.push(`- **Vulnerable location:** ${entry.vulnerable_location}`);
+  lines.push(`- **Overview:** ${entry.overview}`);
+  lines.push(`- **Impact:** ${entry.impact}`);
+  lines.push(`- **Severity:** ${capitalize(entry.severity)}`);
+  lines.push('');
+  if (entry.prerequisites != null && entry.prerequisites.length > 0) {
+    lines.push('**Prerequisites:**');
+    lines.push(entry.prerequisites);
+    lines.push('');
+  }
+  lines.push('**Exploitation Steps:**');
+  lines.push(renderNumberedList(entry.exploitation_steps));
+  lines.push('');
+  lines.push('**Proof of Impact:**');
+  lines.push(entry.proof_of_impact);
+  if (entry.notes != null && entry.notes.length > 0) {
+    lines.push('');
+    lines.push('**Notes:**');
+    lines.push(entry.notes);
+  }
+  return lines.join('\n');
+}
+
+function renderBlockedFinding(entry: BlockedEntry): string {
+  const lines: string[] = [];
+  lines.push(`### ${entry.vulnerability_id}: ${entry.title}`);
+  lines.push('');
+  lines.push('**Summary:**');
+  lines.push(`- **Vulnerable location:** ${entry.vulnerable_location}`);
+  lines.push(`- **Current Blocker:** ${entry.current_blocker}`);
+  lines.push(`- **Potential Impact:** ${entry.potential_impact}`);
+  lines.push(`- **Confidence:** ${entry.confidence.toUpperCase()}`);
+  lines.push('');
+  if (entry.prerequisites != null && entry.prerequisites.length > 0) {
+    lines.push('**Prerequisites:**');
+    lines.push(entry.prerequisites);
+    lines.push('');
+  }
+  lines.push('**Evidence of Vulnerability:**');
+  lines.push(entry.evidence_of_vulnerability);
+  lines.push('');
+  lines.push('**What We Tried:**');
+  lines.push(entry.what_we_tried);
+  lines.push('');
+  lines.push('**How This Would Be Exploited:**');
+  lines.push(renderNumberedList(entry.how_this_would_be_exploited));
+  lines.push('');
+  lines.push('**Expected Impact:**');
+  lines.push(entry.expected_impact);
+  if (entry.notes != null && entry.notes.length > 0) {
+    lines.push('');
+    lines.push('**Notes:**');
+    lines.push(entry.notes);
+  }
+  return lines.join('\n');
+}
+
+// ============================================================================
+// SECTION RENDERERS
+// ============================================================================
+
+function renderExploitedSection(entries: readonly ExploitedEntry[]): string {
+  const heading = '## Successfully Exploited Vulnerabilities';
+  if (entries.length === 0) {
+    return [heading, '', '*No findings reached a definitive verdict in this category.*'].join('\n');
+  }
+  const blocks = sortExploited(entries).map(renderExploitedFinding);
+  return [heading, '', blocks.join('\n\n')].join('\n');
+}
+
+function renderBlockedSection(entries: readonly BlockedEntry[]): string {
+  const heading = '## Potential Vulnerabilities (Validation Blocked)';
+  if (entries.length === 0) {
+    return [heading, '', '*No findings reached a definitive verdict in this category.*'].join('\n');
+  }
+  const blocks = sortBlocked(entries).map(renderBlockedFinding);
+  return [heading, '', blocks.join('\n\n')].join('\n');
+}
+
+// ============================================================================
+// PUBLIC ENTRY POINT
+// ============================================================================
+
+export function renderExploitDeliverable(
+  vulnClass: VulnClass,
+  state: readonly AddExploitInput[],
+  idToType: ReadonlyMap<string, string>,
+): string {
+  const title = `# ${TITLES[vulnClass]}`;
+
+  if (state.length === 0 && idToType.size === 0) {
+    const body = '*No vulnerabilities were available in the queue for exploitation.*';
+    return `${title}\n\n${body}\n`;
+  }
+
+  const exploited = state.filter((e): e is ExploitedEntry => e.status === 'exploited');
+  const blocked = state.filter((e): e is BlockedEntry => e.status === 'blocked');
+
+  const sections: string[] = [title, '', renderExploitedSection(exploited), '', renderBlockedSection(blocked)];
+
+  return `${sections.join('\n').trimEnd()}\n`;
+}

apps/worker/src/services/findings-renderer.ts

@@ -0,0 +1,239 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Deterministic queue-JSON to findings-MD renderer.
+ *
+ * Used when exploit=false: the exploit agents didn't run, so there is no
+ * `*_exploitation_evidence.md` to concatenate into the report. This module
+ * reads each `*_exploitation_queue.json` (already SDK-validated against the
+ * schemas in ../ai/queue-schemas.ts) and writes a `*_findings.md` per class
+ * in the canonical body shape that report-executive.txt's cleanup expects.
+ *
+ * No LLM in the loop — every field maps directly from a JSON key.
+ */
+
+import { fs, path } from 'zx';
+import type { AuthFinding, AuthzFinding, InjectionFinding, SsrfFinding, XssFinding } from '../ai/queue-schemas.js';
+import { deliverablesDir } from '../paths.js';
+import type { ActivityLogger } from '../types/activity-logger.js';
+import type { VulnClass } from '../types/config.js';
+
+const DISCLAIMER = [
+  '> Exploitation phase was not run for this assessment. Each entry documents a',
+  '> vulnerability identified through static analysis; live exploitation steps and',
+  '> proof of impact are not included.',
+].join('\n');
+
+interface ClassConfig<T> {
+  readonly heading: string;
+  readonly noneFoundLabel: string;
+  readonly queueFile: string;
+  readonly findingsFile: string;
+  readonly renderEntry: (entry: T) => string;
+}
+
+interface QueueDocument<T> {
+  vulnerabilities?: T[];
+}
+
+// === Common Render Helpers ===
+
+function summaryRow(label: string, value: string | undefined | null | boolean): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'string' && value.trim() === '') return null;
+  return `- **${label}:** ${value}`;
+}
+
+function formatLocation(endpoint: string | undefined, codeLocation: string | undefined): string {
+  if (endpoint && codeLocation) return `${endpoint} (${codeLocation})`;
+  return endpoint ?? codeLocation ?? '';
+}
+
+function buildEntry(
+  id: string,
+  title: string,
+  summaryRows: ReadonlyArray<string | null>,
+  notes: string | undefined,
+): string {
+  const lines: string[] = [];
+  lines.push(`### ${id}: ${title}`);
+  lines.push('');
+  lines.push('**Summary:**');
+  for (const row of summaryRows) {
+    if (row !== null) lines.push(row);
+  }
+  lines.push('');
+  if (notes && notes.trim() !== '') {
+    lines.push(`**Notes:** ${notes.trim()}`);
+  }
+  return lines.join('\n').trimEnd();
+}
+
+// === Per-Class Renderers ===
+
+function renderAuthEntry(e: AuthFinding): string {
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', formatLocation(e.source_endpoint, e.vulnerable_code_location)),
+      summaryRow('Overview', e.missing_defense),
+      summaryRow('Impact', e.exploitation_hypothesis),
+    ],
+    e.notes,
+  );
+}
+
+function renderSsrfEntry(e: SsrfFinding): string {
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', formatLocation(e.source_endpoint, e.vulnerable_code_location)),
+      summaryRow('Overview', e.missing_defense),
+      summaryRow('Impact', e.exploitation_hypothesis),
+    ],
+    e.notes,
+  );
+}
+
+function renderAuthzEntry(e: AuthzFinding): string {
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [
+      summaryRow('Vulnerable location', formatLocation(e.endpoint, e.vulnerable_code_location)),
+      summaryRow('Overview', e.guard_evidence),
+      summaryRow('Impact', e.side_effect),
+    ],
+    e.notes,
+  );
+}
+
+function renderInjectionEntry(e: InjectionFinding): string {
+  const location = e.path && e.sink_call ? `${e.sink_call} (path: ${e.path})` : (e.sink_call ?? e.path);
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [summaryRow('Vulnerable location', location), summaryRow('Overview', e.mismatch_reason)],
+    e.notes,
+  );
+}
+
+function renderXssEntry(e: XssFinding): string {
+  const location = e.path && e.sink_function ? `${e.sink_function} (path: ${e.path})` : (e.sink_function ?? e.path);
+  return buildEntry(
+    e.ID,
+    e.vulnerability_type,
+    [summaryRow('Vulnerable location', location), summaryRow('Overview', e.mismatch_reason)],
+    e.notes,
+  );
+}
+
+// === Class Registry ===
+
+const CLASSES: Record<VulnClass, ClassConfig<unknown>> = {
+  auth: {
+    heading: 'Authentication',
+    noneFoundLabel: 'authentication',
+    queueFile: 'auth_exploitation_queue.json',
+    findingsFile: 'auth_findings.md',
+    renderEntry: (e) => renderAuthEntry(e as AuthFinding),
+  },
+  authz: {
+    heading: 'Authorization',
+    noneFoundLabel: 'authorization',
+    queueFile: 'authz_exploitation_queue.json',
+    findingsFile: 'authz_findings.md',
+    renderEntry: (e) => renderAuthzEntry(e as AuthzFinding),
+  },
+  injection: {
+    heading: 'Injection',
+    noneFoundLabel: 'injection',
+    queueFile: 'injection_exploitation_queue.json',
+    findingsFile: 'injection_findings.md',
+    renderEntry: (e) => renderInjectionEntry(e as InjectionFinding),
+  },
+  xss: {
+    heading: 'XSS',
+    noneFoundLabel: 'XSS',
+    queueFile: 'xss_exploitation_queue.json',
+    findingsFile: 'xss_findings.md',
+    renderEntry: (e) => renderXssEntry(e as XssFinding),
+  },
+  ssrf: {
+    heading: 'SSRF',
+    noneFoundLabel: 'SSRF',
+    queueFile: 'ssrf_exploitation_queue.json',
+    findingsFile: 'ssrf_findings.md',
+    renderEntry: (e) => renderSsrfEntry(e as SsrfFinding),
+  },
+};
+
+// === Class File Assembly ===
+
+function renderClassFile(config: ClassConfig<unknown>, entries: readonly unknown[]): string {
+  const sections: string[] = [];
+  sections.push(`# ${config.heading} Findings`);
+  sections.push('');
+  sections.push(DISCLAIMER);
+  sections.push('');
+  sections.push('## Identified Vulnerabilities');
+  sections.push('');
+  if (entries.length === 0) {
+    sections.push(`No ${config.noneFoundLabel} vulnerabilities were identified.`);
+    sections.push('');
+  } else {
+    for (const entry of entries) {
+      sections.push(config.renderEntry(entry));
+      sections.push('');
+    }
+  }
+  return `${sections.join('\n').trimEnd()}\n`;
+}
+
+// === Public Entry Point ===
+
+/**
+ * Render `*_findings.md` per class from each `*_exploitation_queue.json`.
+ *
+ * Idempotent: skips classes whose findings file already exists, or whose queue
+ * is missing (class out of scope this run). Per-class failures are logged and
+ * other classes still proceed.
+ */
+export async function renderFindingsFromQueues(
+  sourceDir: string,
+  deliverablesSubdir: string | undefined,
+  logger: ActivityLogger,
+): Promise<void> {
+  const dir = deliverablesDir(sourceDir, deliverablesSubdir);
+
+  for (const config of Object.values(CLASSES)) {
+    const queuePath = path.join(dir, config.queueFile);
+    const findingsPath = path.join(dir, config.findingsFile);
+
+    if (await fs.pathExists(findingsPath)) {
+      logger.info(`${config.heading}: ${config.findingsFile} already exists, skipping`);
+      continue;
+    }
+    if (!(await fs.pathExists(queuePath))) {
+      logger.info(`${config.heading}: no queue file (class out of scope), skipping`);
+      continue;
+    }
+
+    try {
+      const doc = (await fs.readJson(queuePath)) as QueueDocument<unknown>;
+      const entries = doc.vulnerabilities ?? [];
+      const markdown = renderClassFile(config, entries);
+      await fs.writeFile(findingsPath, markdown);
+      logger.info(`${config.heading}: rendered ${entries.length} finding(s) to ${config.findingsFile}`);
+    } catch (error) {
+      const err = error as Error;
+      logger.warn(`${config.heading}: failed to render findings from ${config.queueFile}: ${err.message}`);
+    }
+  }
+}

apps/worker/src/services/index.ts

@@ -11,12 +11,13 @@
  * Services are pure domain logic with no Temporal dependencies.
  */
 
+export type { ClaudePromptResult } from '../ai/claude-executor.js';
+export { runClaudePrompt } from '../ai/claude-executor.js';
 export type { AgentExecutionInput } from './agent-execution.js';
 export { AgentExecutionService } from './agent-execution.js';
-
 export { ConfigLoaderService } from './config-loader.js';
 export type { ContainerDependencies } from './container.js';
-export { Container, getOrCreateContainer, removeContainer } from './container.js';
+export { Container, getContainer, getOrCreateContainer, removeContainer, setContainerFactory } from './container.js';
 export { ExploitationCheckerService } from './exploitation-checker.js';
 export { loadPrompt } from './prompt-manager.js';
 export { assembleFinalReport, injectModelIntoReport } from './reporting.js';

apps/worker/src/services/pre-recon-renderer.ts

@@ -0,0 +1,328 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Deterministic pre-recon collector → markdown renderer.
+ *
+ * Converts the typed payload bag harvested from the pre-recon-collector MCP
+ * server into the pre_recon_deliverable.md Markdown layout. No LLM in the
+ * loop; section ordering, headings, and template are owned here.
+ *
+ * Any tool the agent skips becomes a `[Section X: not provided]` placeholder
+ * rather than an activity failure. Every section renderer accepts the
+ * corresponding collected field as possibly undefined and falls back to the
+ * placeholder helper when absent.
+ */
+
+import type {
+  ApplicationIntelligenceInput,
+  AuthDeepDiveInput,
+  CodebaseIndexingInput,
+  CriticalFilePathsInput,
+  ExecutiveSummaryInput,
+  PreReconData,
+  SinkRef,
+  SsrfSinksInput,
+  XssSinksInput,
+} from '../mcp-server/pre-recon-collector.js';
+
+// ============================================================================
+// STATIC PROSE
+// ============================================================================
+
+const SCOPE_AND_BOUNDARIES = `# Penetration Test Scope & Boundaries
+
+**Primary Directive:** Your analysis is strictly limited to the **network-accessible attack surface** of the application. All subsequent tasks must adhere to this scope. Before reporting any finding (e.g., an entry point, a vulnerability sink), you must first verify it meets the "In-Scope" criteria.
+
+### In-Scope: Network-Reachable Components
+A component is considered **in-scope** if its execution can be initiated, directly or indirectly, by a network request that the deployed application server is capable of receiving. This includes:
+- Publicly exposed web pages and API endpoints.
+- Endpoints requiring authentication via the application's standard login mechanisms.
+- Any developer utility, debug console, or script that has been mistakenly exposed through a route or is otherwise callable from other in-scope, network-reachable code.
+
+### Out-of-Scope: Locally Executable Only
+A component is **out-of-scope** if it **cannot** be invoked through the running application's network interface and requires an execution context completely external to the application's request-response cycle. This includes tools that must be run via:
+- A command-line interface (e.g., \`go run ./cmd/...\`, \`python scripts/...\`).
+- A development environment's internal tooling (e.g., a "run script" button in an IDE).
+- CI/CD pipeline scripts or build tools (e.g., Dagger build definitions).
+- Database migration scripts, backup tools, or maintenance utilities.
+- Local development servers, test harnesses, or debugging utilities.
+- Static files or scripts that require manual opening in a browser (not served by the application).`;
+
+// ============================================================================
+// SHARED HELPERS
+// ============================================================================
+
+function placeholder(sectionLabel: string, toolName: string): string {
+  return `_[${sectionLabel}: not provided — \`${toolName}\` was not called]_`;
+}
+
+function bulletField(label: string, value: string): string {
+  return `- **${label}:** ${value}`;
+}
+
+function bulletPaths(label: string, paths: readonly string[]): string {
+  if (paths.length === 0) {
+    return `- **${label}:** *(none identified)*`;
+  }
+  const formatted = paths.map((p) => `\`${p}\``).join(', ');
+  return `- **${label}:** ${formatted}`;
+}
+
+function renderSinkList(sinks: readonly SinkRef[]): string {
+  if (sinks.length === 0) {
+    return '*(scanned, no sinks of this kind found)*';
+  }
+  return sinks
+    .map((sink) => {
+      const head = `- **${sink.sink_function}** at \`${sink.location}\``;
+      if (sink.notes && sink.notes.trim() !== '') {
+        return `${head} — ${sink.notes.trim()}`;
+      }
+      return head;
+    })
+    .join('\n');
+}
+
+// ============================================================================
+// SECTION RENDERERS
+// ============================================================================
+
+function renderExecutiveSummarySection(data: ExecutiveSummaryInput | undefined): string {
+  if (!data) {
+    return ['## 1. Executive Summary', '', placeholder('Section 1', 'set_executive_summary')].join('\n');
+  }
+  return ['## 1. Executive Summary', '', data.text].join('\n');
+}
+
+function renderArchitectureSection(intel: ApplicationIntelligenceInput | undefined): string {
+  if (!intel) {
+    return ['## 2. Architecture & Technology Stack', '', placeholder('Section 2', 'set_application_intelligence')].join(
+      '\n',
+    );
+  }
+  const { architecture: a } = intel;
+  return [
+    '## 2. Architecture & Technology Stack',
+    '',
+    bulletField('Framework & Language', a.framework_and_language),
+    bulletField('Architectural Pattern', a.architectural_pattern),
+    bulletField('Critical Security Components', a.critical_security_components),
+  ].join('\n');
+}
+
+function renderAuthSection(auth: AuthDeepDiveInput | undefined): string {
+  if (!auth) {
+    return ['## 3. Authentication & Authorization Deep Dive', '', placeholder('Section 3', 'set_auth_deep_dive')].join(
+      '\n',
+    );
+  }
+  const ssoLine = auth.sso_oauth_oidc
+    ? bulletField('SSO/OAuth/OIDC Flows', auth.sso_oauth_oidc)
+    : bulletField('SSO/OAuth/OIDC Flows', 'Not applicable — no SSO/OAuth/OIDC integration detected.');
+  return [
+    '## 3. Authentication & Authorization Deep Dive',
+    '',
+    bulletField('Authentication Mechanisms', auth.authentication_mechanisms),
+    bulletField('Session Management', auth.session_management),
+    bulletField('Authorization Model', auth.authz_model),
+    bulletField('Multi-tenancy', auth.multi_tenancy),
+    ssoLine,
+  ].join('\n');
+}
+
+function renderDataSecuritySection(intel: ApplicationIntelligenceInput | undefined): string {
+  if (!intel) {
+    return ['## 4. Data Security & Storage', '', placeholder('Section 4', 'set_application_intelligence')].join('\n');
+  }
+  const { data_security: d } = intel;
+  return [
+    '## 4. Data Security & Storage',
+    '',
+    bulletField('Database Security', d.database_security),
+    bulletField('Data Flow Security', d.data_flow_security),
+    bulletField('Multi-tenant Data Isolation', d.multi_tenant_isolation),
+  ].join('\n');
+}
+
+function renderAttackSurfaceSection(intel: ApplicationIntelligenceInput | undefined): string {
+  if (!intel) {
+    return ['## 5. Attack Surface Analysis', '', placeholder('Section 5', 'set_application_intelligence')].join('\n');
+  }
+  const { attack_surface: s } = intel;
+  return [
+    '## 5. Attack Surface Analysis',
+    '',
+    bulletField('External Entry Points', s.external_entry_points),
+    bulletField('Internal Service Communication', s.internal_service_communication),
+    bulletField('Input Validation Patterns', s.input_validation_patterns),
+    bulletField('Background Processing', s.background_processing),
+  ].join('\n');
+}
+
+function renderInfrastructureSection(intel: ApplicationIntelligenceInput | undefined): string {
+  if (!intel) {
+    return [
+      '## 6. Infrastructure & Operational Security',
+      '',
+      placeholder('Section 6', 'set_application_intelligence'),
+    ].join('\n');
+  }
+  const { infrastructure: i } = intel;
+  return [
+    '## 6. Infrastructure & Operational Security',
+    '',
+    bulletField('Secrets Management', i.secrets_management),
+    bulletField('Configuration Security', i.configuration_security),
+    bulletField('External Dependencies', i.external_dependencies),
+    bulletField('Monitoring & Logging', i.monitoring_and_logging),
+  ].join('\n');
+}
+
+function renderCodebaseIndexingSection(data: CodebaseIndexingInput | undefined): string {
+  if (!data) {
+    return ['## 7. Overall Codebase Indexing', '', placeholder('Section 7', 'set_codebase_indexing')].join('\n');
+  }
+  return ['## 7. Overall Codebase Indexing', '', data.text].join('\n');
+}
+
+function renderCriticalFilePathsSection(paths: CriticalFilePathsInput | undefined): string {
+  if (!paths) {
+    return ['## 8. Critical File Paths', '', placeholder('Section 8', 'set_critical_file_paths')].join('\n');
+  }
+  return [
+    '## 8. Critical File Paths',
+    '',
+    bulletPaths('Configuration', paths.configuration),
+    bulletPaths('Authentication & Authorization', paths.authentication_and_authorization),
+    bulletPaths('API & Routing', paths.api_and_routing),
+    bulletPaths('Data Models & DB Interaction', paths.data_models_and_db),
+    bulletPaths('Dependency Manifests', paths.dependency_manifests),
+    bulletPaths('Sensitive Data & Secrets Handling', paths.sensitive_data_and_secrets),
+    bulletPaths('Middleware & Input Validation', paths.middleware_and_input_validation),
+    bulletPaths('Logging & Monitoring', paths.logging_and_monitoring),
+    bulletPaths('Infrastructure & Deployment', paths.infrastructure_and_deployment),
+  ].join('\n');
+}
+
+function renderXssSection(xss: XssSinksInput | undefined): string {
+  if (!xss) {
+    return ['## 9. XSS Sinks and Render Contexts', '', placeholder('Section 9', 'set_xss_sinks')].join('\n');
+  }
+  if (!xss.applicable) {
+    return [
+      '## 9. XSS Sinks and Render Contexts',
+      '',
+      '*(N/A — the application has no web frontend; XSS sink analysis does not apply.)*',
+    ].join('\n');
+  }
+  return [
+    '## 9. XSS Sinks and Render Contexts',
+    '',
+    '### HTML Body Context',
+    renderSinkList(xss.html_body),
+    '',
+    '### HTML Attribute Context',
+    renderSinkList(xss.html_attribute),
+    '',
+    '### JavaScript Context',
+    renderSinkList(xss.javascript),
+    '',
+    '### CSS Context',
+    renderSinkList(xss.css),
+    '',
+    '### URL Context',
+    renderSinkList(xss.url),
+  ].join('\n');
+}
+
+function renderSsrfSection(ssrf: SsrfSinksInput | undefined): string {
+  if (!ssrf) {
+    return ['## 10. SSRF Sinks', '', placeholder('Section 10', 'set_ssrf_sinks')].join('\n');
+  }
+  if (!ssrf.applicable) {
+    return [
+      '## 10. SSRF Sinks',
+      '',
+      '*(N/A — the application makes no outbound requests; SSRF sink analysis does not apply.)*',
+    ].join('\n');
+  }
+  return [
+    '## 10. SSRF Sinks',
+    '',
+    '### HTTP(S) Clients',
+    renderSinkList(ssrf.http_clients),
+    '',
+    '### Raw Sockets & Connect APIs',
+    renderSinkList(ssrf.raw_sockets),
+    '',
+    '### URL Openers & File Includes',
+    renderSinkList(ssrf.url_openers),
+    '',
+    '### Redirect & "Next URL" Handlers',
+    renderSinkList(ssrf.redirect_handlers),
+    '',
+    '### Headless Browsers & Render Engines',
+    renderSinkList(ssrf.headless_browsers),
+    '',
+    '### Media Processors',
+    renderSinkList(ssrf.media_processors),
+    '',
+    '### Link Preview & Unfurlers',
+    renderSinkList(ssrf.link_preview),
+    '',
+    '### Webhook Testers & Callback Verifiers',
+    renderSinkList(ssrf.webhook_testers),
+    '',
+    '### SSO/OIDC Discovery & JWKS Fetchers',
+    renderSinkList(ssrf.sso_oidc_discovery),
+    '',
+    '### Importers & Data Loaders',
+    renderSinkList(ssrf.importers),
+    '',
+    '### Package/Plugin/Theme Installers',
+    renderSinkList(ssrf.package_installers),
+    '',
+    '### Monitoring & Health Check Frameworks',
+    renderSinkList(ssrf.monitoring_and_health),
+    '',
+    '### Cloud Metadata Helpers',
+    renderSinkList(ssrf.cloud_metadata),
+  ].join('\n');
+}
+
+// ============================================================================
+// PUBLIC ENTRY POINT
+// ============================================================================
+
+export function renderPreRecon(data: PreReconData): string {
+  const sections: string[] = [
+    SCOPE_AND_BOUNDARIES,
+    '---',
+    '',
+    renderExecutiveSummarySection(data.executive_summary),
+    '',
+    renderArchitectureSection(data.application_intelligence),
+    '',
+    renderAuthSection(data.auth_deep_dive),
+    '',
+    renderDataSecuritySection(data.application_intelligence),
+    '',
+    renderAttackSurfaceSection(data.application_intelligence),
+    '',
+    renderInfrastructureSection(data.application_intelligence),
+    '',
+    renderCodebaseIndexingSection(data.codebase_indexing),
+    '',
+    renderCriticalFilePathsSection(data.critical_file_paths),
+    '',
+    renderXssSection(data.xss_sinks),
+    '',
+    renderSsrfSection(data.ssrf_sinks),
+    '',
+  ];
+  return `${sections.join('\n').trimEnd()}\n`;
+}

apps/worker/src/services/preflight.ts

@@ -12,21 +12,26 @@
  * time and API costs compared to failing mid-pipeline.
  *
  * Checks run sequentially, cheapest first:
- * 1. Repository path exists and contains .git
+ * 1. Repository path exists and is a directory
  * 2. Config file parses and validates (if provided)
- * 3. Credentials validate via Claude Agent SDK query (API key, OAuth, Bedrock, Vertex AI, or router mode)
- * 4. Target URL is reachable from the container (DNS + HTTP)
+ * 3. code_path rules match real entries in the repo (filesystem only)
+ * 4. Credentials validate via Claude Agent SDK query (API key, OAuth, Bedrock, or Vertex AI)
+ * 5. Target URL resolves, is not link-local (cloud metadata), and is reachable (DNS + HTTP)
  */
 
+import type { LookupAddress } from 'node:dns';
 import { lookup } from 'node:dns/promises';
 import fs from 'node:fs/promises';
 import http from 'node:http';
 import https from 'node:https';
+import net, { type LookupFunction } from 'node:net';
 import type { SDKAssistantMessageError } from '@anthropic-ai/claude-agent-sdk';
 import { query } from '@anthropic-ai/claude-agent-sdk';
+import { glob } from 'zx';
 import { resolveModel } from '../ai/models.js';
 import { parseConfig } from '../config-parser.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
+import type { Config, Rule } from '../types/config.js';
 import { ErrorCode } from '../types/errors.js';
 import { err, ok, type Result } from '../types/result.js';
 import { isRetryableError, PentestError } from './error-handling.js';
@@ -37,12 +42,48 @@ function isLoopbackAddress(address: string): boolean {
   return address === '127.0.0.1' || address === '::1' || address === '0.0.0.0';
 }
 
+// 169.254.0.0/16 hosts the cloud metadata service. RFC1918 and loopback are
+// intentionally allowed — scanning local targets is a supported Shannon use case.
+const metadataBlockList = new net.BlockList();
+metadataBlockList.addSubnet('169.254.0.0', 16, 'ipv4');
+
+function isBlockedAddress(address: string): boolean {
+  switch (net.isIP(address)) {
+    case 4:
+      return metadataBlockList.check(address, 'ipv4');
+    case 6:
+      return metadataBlockList.check(address, 'ipv6');
+    default:
+      return false;
+  }
+}
+
+/** DNS lookup pinned to already-validated `addresses`, so the socket cannot be re-pointed after validation (DNS rebinding). */
+function pinnedLookup(addresses: LookupAddress[]): LookupFunction {
+  return (hostname, options, callback) => {
+    const matching = options.family ? addresses.filter((a) => a.family === options.family) : addresses;
+    const pool = matching.length > 0 ? matching : addresses;
+    if (options.all) {
+      callback(null, pool);
+      return;
+    }
+    const first = pool[0];
+    if (!first) {
+      callback(new Error(`no resolved address for ${hostname}`), '', 0);
+      return;
+    }
+    callback(null, first.address, first.family);
+  };
+}
+
 // === Repository Validation ===
 
 async function validateRepo(repoPath: string, logger: ActivityLogger): Promise<Result<void, PentestError>> {
   logger.info('Checking repository path...', { repoPath });
 
-  // 1. Check repo directory exists
+  // Check repo directory exists. The repo is not required to be a git repository:
+  // multi-repo targets (a parent directory containing several repos) have no top-level
+  // .git, and git-based checkpoint/rollback in git-manager already no-ops on non-git dirs.
   try {
     const stats = await fs.stat(repoPath);
     if (!stats.isDirectory()) {
@@ -68,45 +109,19 @@ async function validateRepo(repoPath: string, logger: ActivityLogger): Promise<R
     );
   }
 
-  // 2. Check .git directory exists
-  try {
-    const gitStats = await fs.stat(`${repoPath}/.git`);
-    if (!gitStats.isDirectory()) {
-      return err(
-        new PentestError(
-          `Not a git repository (no .git directory): ${repoPath}`,
-          'config',
-          false,
-          { repoPath },
-          ErrorCode.REPO_NOT_FOUND,
-        ),
-      );
-    }
-  } catch {
-    return err(
-      new PentestError(
-        `Not a git repository (no .git directory): ${repoPath}`,
-        'config',
-        false,
-        { repoPath },
-        ErrorCode.REPO_NOT_FOUND,
-      ),
-    );
-  }
-
   logger.info('Repository path OK');
   return ok(undefined);
 }
 
 // === Config Validation ===
 
-async function validateConfig(configPath: string, logger: ActivityLogger): Promise<Result<void, PentestError>> {
+async function validateConfig(configPath: string, logger: ActivityLogger): Promise<Result<Config, PentestError>> {
   logger.info('Validating configuration file...', { configPath });
 
   try {
-    await parseConfig(configPath);
+    const config = await parseConfig(configPath);
     logger.info('Configuration file OK');
-    return ok(undefined);
+    return ok(config);
   } catch (error) {
     if (error instanceof PentestError) {
       return err(error);
@@ -124,6 +139,73 @@ async function validateConfig(configPath: string, logger: ActivityLogger): Promi
   }
 }
 
+// === code_path Existence Validation ===
+
+const CODE_PATH_IGNORE = ['.git/**', '.shannon/**'];
+
+async function patternMatchesAny(repoPath: string, pattern: string): Promise<boolean> {
+  const stream = glob.globbyStream(pattern, {
+    cwd: repoPath,
+    dot: true,
+    onlyFiles: false,
+    followSymbolicLinks: false,
+    ignore: CODE_PATH_IGNORE,
+  });
+  for await (const _ of stream) {
+    return true;
+  }
+  return false;
+}
+
+type RuleKind = 'avoid' | 'focus';
+interface MissingCodePath {
+  kind: RuleKind;
+  value: string;
+  description: string;
+}
+
+async function validateCodePathsExist(
+  config: Config,
+  repoPath: string,
+  logger: ActivityLogger,
+): Promise<Result<void, PentestError>> {
+  const tagged: Array<{ kind: RuleKind; rule: Rule }> = [
+    ...(config.rules?.avoid ?? []).map((rule) => ({ kind: 'avoid' as const, rule })),
+    ...(config.rules?.focus ?? []).map((rule) => ({ kind: 'focus' as const, rule })),
+  ].filter(({ rule }) => rule.type === 'code_path');
+
+  if (tagged.length === 0) {
+    return ok(undefined);
+  }
+
+  logger.info(`Validating ${tagged.length} code_path rule(s) against repo...`);
+
+  // ≥1 match is the only property enforced — malformed globs simply match nothing.
+  const missing: MissingCodePath[] = [];
+  for (const { kind, rule } of tagged) {
+    if (!(await patternMatchesAny(repoPath, rule.value))) {
+      missing.push({ kind, value: rule.value, description: rule.description });
+    }
+  }
+
+  if (missing.length > 0) {
+    const lines = missing.map((m) => `[${m.kind}] '${m.value}' — ${m.description}`);
+    return err(
+      new PentestError(
+        `code_path rules don't match any file or directory in the repo:\n  - ${lines.join('\n  - ')}\n` +
+          `Fix the patterns or remove the rules.`,
+        'config',
+        false,
+        { missing },
+        ErrorCode.CONFIG_VALIDATION_FAILED,
+      ),
+    );
+  }
+
+  logger.info('All code_path rules matched');
+  return ok(undefined);
+}
+
 // === Credential Validation ===
 
 /** Map SDK error type to a human-readable preflight PentestError. */
@@ -166,6 +248,32 @@ function classifySdkError(sdkError: SDKAssistantMessageError, authType: string):
           sdkError,
         }),
       );
+    case 'overloaded':
+      return err(
+        new PentestError(`Anthropic API is overloaded. Wait a few moments and try again.`, 'network', true, {
+          authType,
+          sdkError,
+        }),
+      );
+    case 'model_not_found':
+      return err(
+        new PentestError(
+          `Configured model is not available for this account. Check ANTHROPIC_*_MODEL in .env.`,
+          'config',
+          false,
+          { authType, sdkError },
+        ),
+      );
+    case 'oauth_org_not_allowed':
+      return err(
+        new PentestError(
+          `This credential's organization is not allowed. Check your ${authType} in .env.`,
+          'config',
+          false,
+          { authType, sdkError },
+          ErrorCode.AUTH_FAILED,
+        ),
+      );
     default:
       return err(
         new PentestError(
@@ -180,11 +288,29 @@ function classifySdkError(sdkError: SDKAssistantMessageError, authType: string):
 }
 
 /** Validate credentials via a minimal Claude Agent SDK query. */
-async function validateCredentials(logger: ActivityLogger): Promise<Result<void, PentestError>> {
+async function validateCredentials(
+  logger: ActivityLogger,
+  apiKey?: string,
+  providerConfig?: import('../types/config.js').ProviderConfig,
+): Promise<Result<void, PentestError>> {
+  // 0. If providerConfig is present, credentials are managed by the caller.
+  //    The executor will map providerConfig directly to sdkEnv — no process.env needed.
+  if (providerConfig) {
+    logger.info(
+      `Provider config present (type: ${providerConfig.providerType || 'anthropic_api'}) — skipping env-based credential validation`,
+    );
+    return ok(undefined);
+  }
+
+  // 0b. If apiKey provided via config, set it in env for SDK validation
+  //     This avoids requiring process.env.ANTHROPIC_API_KEY when key is threaded via input
+  if (apiKey) {
+    process.env.ANTHROPIC_API_KEY = apiKey;
+  }
   // 1. Custom base URL — validate endpoint is reachable via SDK query
-  if (process.env.ANTHROPIC_BASE_URL) {
+  if (process.env.ANTHROPIC_BASE_URL && process.env.ANTHROPIC_AUTH_TOKEN) {
     const baseUrl = process.env.ANTHROPIC_BASE_URL;
-    logger.info(`Validating custom base URL: ${baseUrl}`);
+    logger.info('Validating custom base URL');
 
     try {
       for await (const message of query({ prompt: 'hi', options: { model: resolveModel('small'), maxTurns: 1 } })) {
@@ -289,7 +415,7 @@ async function validateCredentials(logger: ActivityLogger): Promise<Result<void,
   }
 
   // 4. Check that at least one credential is present
-  if (!process.env.ANTHROPIC_API_KEY && !process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+  if (!process.env.ANTHROPIC_API_KEY && !process.env.CLAUDE_CODE_OAUTH_TOKEN && !process.env.ANTHROPIC_AUTH_TOKEN) {
     return err(
       new PentestError(
         'No API credentials found. Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in .env (or use CLAUDE_CODE_USE_BEDROCK=1 for AWS Bedrock, or CLAUDE_CODE_USE_VERTEX=1 for Google Vertex AI)',
@@ -338,7 +464,7 @@ async function validateCredentials(logger: ActivityLogger): Promise<Result<void,
 // === Target URL Validation ===
 
 /** HTTP HEAD with TLS verification disabled — we check reachability, not certificate validity. */
-function httpHead(url: string, timeoutMs: number): Promise<number> {
+function httpHead(url: string, timeoutMs: number, addresses: LookupAddress[]): Promise<number> {
   return new Promise((resolve, reject) => {
     const parsed = new URL(url);
     const isHttps = parsed.protocol === 'https:';
@@ -349,6 +475,7 @@ function httpHead(url: string, timeoutMs: number): Promise<number> {
       {
         method: 'HEAD',
         timeout: timeoutMs,
+        lookup: pinnedLookup(addresses),
         ...(isHttps && { rejectUnauthorized: false }),
       },
       (res) => {
@@ -368,7 +495,7 @@ function httpHead(url: string, timeoutMs: number): Promise<number> {
 
 /** Check that the target URL is reachable from inside the container. */
 async function validateTargetUrl(targetUrl: string, logger: ActivityLogger): Promise<Result<void, PentestError>> {
-  logger.info('Checking target URL reachability...', { targetUrl });
+  logger.info('Checking target URL reachability...');
 
   // 1. Parse URL
   let parsed: URL;
@@ -386,12 +513,11 @@ async function validateTargetUrl(targetUrl: string, logger: ActivityLogger): Pro
     );
   }
 
-  // 2. DNS lookup — detect loopback addresses early for a better hint
+  // 2. Resolve all records once — reused (pinned) for the connection below.
   const hostname = parsed.hostname;
-  let resolvedAddress: string | undefined;
+  let addresses: LookupAddress[];
   try {
-    const result = await lookup(hostname);
-    resolvedAddress = result.address;
+    addresses = await lookup(hostname, { all: true });
   } catch {
     return err(
       new PentestError(
@@ -404,25 +530,40 @@ async function validateTargetUrl(targetUrl: string, logger: ActivityLogger): Pro
     );
   }
 
-  // 3. HTTP reachability check
+  // 3. Reject the link-local metadata range (169.254.0.0/16).
+  const blocked = addresses.find((entry) => isBlockedAddress(entry.address));
+  if (blocked) {
+    return err(
+      new PentestError(
+        `Target URL ${targetUrl} resolves to ${blocked.address}, a link-local address ` +
+          `(169.254.0.0/16). This range hosts the cloud instance metadata service and cannot be scanned.`,
+        'config',
+        false,
+        { targetUrl, hostname, address: blocked.address },
+        ErrorCode.TARGET_UNREACHABLE,
+      ),
+    );
+  }
+
+  // 4. HTTP reachability check (socket pinned to the resolved addresses).
   try {
-    await httpHead(targetUrl, TARGET_URL_TIMEOUT_MS);
+    await httpHead(targetUrl, TARGET_URL_TIMEOUT_MS, addresses);
 
     logger.info('Target URL OK');
     return ok(undefined);
   } catch (error) {
-    const isLoopback = isLoopbackAddress(resolvedAddress);
     const detail = error instanceof Error ? error.message : String(error);
+    const isLoopback = addresses.some((entry) => isLoopbackAddress(entry.address));
 
     if (isLoopback) {
       const suggestion = targetUrl.replace(hostname, 'host.docker.internal');
       return err(
         new PentestError(
-          `Target URL ${targetUrl} resolves to ${resolvedAddress} (loopback) and is not reachable. ` +
+          `Target URL ${targetUrl} resolves to a loopback address and is not reachable. ` +
             `For local services, use host.docker.internal instead of ${hostname} (e.g., ${suggestion})`,
           'network',
           false,
-          { targetUrl, resolvedAddress, hostname },
+          { targetUrl, hostname },
           ErrorCode.TARGET_UNREACHABLE,
         ),
       );
@@ -433,7 +574,7 @@ async function validateTargetUrl(targetUrl: string, logger: ActivityLogger): Pro
         `Target URL ${targetUrl} is not reachable: ${detail}`,
         'network',
         false,
-        { targetUrl, resolvedAddress },
+        { targetUrl },
         ErrorCode.TARGET_UNREACHABLE,
       ),
     );
@@ -445,10 +586,11 @@ async function validateTargetUrl(targetUrl: string, logger: ActivityLogger): Pro
 /**
  * Run all preflight checks sequentially (cheapest first).
  *
- * 1. Repository path exists and contains .git
+ * 1. Repository path exists and is a directory
  * 2. Config file parses and validates (if configPath provided)
- * 3. Credentials validate (API key, OAuth, or router mode)
- * 4. Target URL is reachable from the container
+ * 3. code_path rules match at least one entry in the repo (skipped without config)
+ * 4. Credentials validate (API key, OAuth, Bedrock, or Vertex AI)
+ * 5. Target URL is reachable from the container
  *
  * Returns on first failure.
  */
@@ -457,6 +599,8 @@ export async function runPreflightChecks(
   repoPath: string,
   configPath: string | undefined,
   logger: ActivityLogger,
+  apiKey?: string,
+  providerConfig?: import('../types/config.js').ProviderConfig,
 ): Promise<Result<void, PentestError>> {
   // 1. Repository check (free — filesystem only)
   const repoResult = await validateRepo(repoPath, logger);
@@ -465,20 +609,31 @@ export async function runPreflightChecks(
   }
 
   // 2. Config check (free — filesystem + CPU)
+  let parsedConfig: Config | null = null;
   if (configPath) {
     const configResult = await validateConfig(configPath, logger);
     if (!configResult.ok) {
       return configResult;
     }
+    parsedConfig = configResult.value;
   }
 
-  // 3. Credential check (cheap — 1 SDK round-trip)
-  const credResult = await validateCredentials(logger);
+  // 3. code_path rules must match real entries in the repo (filesystem only).
+  // Runs after both repo and config are valid, before any network round-trip.
+  if (parsedConfig) {
+    const codePathResult = await validateCodePathsExist(parsedConfig, repoPath, logger);
+    if (!codePathResult.ok) {
+      return codePathResult;
+    }
+  }
+
+  // 4. Credential check (cheap — 1 SDK round-trip, skipped when providerConfig present)
+  const credResult = await validateCredentials(logger, apiKey, providerConfig);
   if (!credResult.ok) {
     return credResult;
   }
 
-  // 4. Target URL reachability check (cheap — 1 HTTP round-trip)
+  // 5. Target URL reachability check (cheap — 1 HTTP round-trip)
   const urlResult = await validateTargetUrl(targetUrl, logger);
   if (!urlResult.ok) {
     return urlResult;

apps/worker/src/services/prompt-manager.ts

@@ -8,12 +8,117 @@ import { fs, path } from 'zx';
 import { PROMPTS_DIR } from '../paths.js';
 import { PLAYWRIGHT_SESSION_MAPPING } from '../session-manager.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
-import type { Authentication, DistributedConfig } from '../types/config.js';
+import type { Authentication, DistributedConfig, ReportConfig, Rule, VulnClass } from '../types/config.js';
+import { isGlobPattern } from '../utils/glob.js';
 import { handlePromptError, PentestError } from './error-handling.js';
 
+function renderCodePathRules(rules: Rule[]): string {
+  const filtered = rules.filter((r) => r.type === 'code_path');
+  if (filtered.length === 0) return 'None';
+  return filtered
+    .map((r) => {
+      const kind = isGlobPattern(r.value) ? '[GLOB]' : '[FILE]';
+      return `- ${r.value} ${kind} — ${r.description}`;
+    })
+    .join('\n');
+}
+
+interface VulnSummarySpec {
+  readonly heading: string;
+  readonly evidenceSection: string;
+  readonly noneFoundLabel: string;
+}
+
+const VULN_SUMMARY_SPECS: Record<VulnClass, VulnSummarySpec> = {
+  auth: {
+    heading: 'Authentication Vulnerabilities',
+    evidenceSection: 'Authentication Exploitation Evidence',
+    noneFoundLabel: 'authentication',
+  },
+  authz: {
+    heading: 'Authorization Vulnerabilities',
+    evidenceSection: 'Authorization Exploitation Evidence',
+    noneFoundLabel: 'authorization',
+  },
+  xss: {
+    heading: 'Cross-Site Scripting (XSS) Vulnerabilities',
+    evidenceSection: 'XSS Exploitation Evidence',
+    noneFoundLabel: 'XSS',
+  },
+  injection: {
+    heading: 'SQL/Command Injection Vulnerabilities',
+    evidenceSection: 'Injection Exploitation Evidence',
+    noneFoundLabel: 'SQL or command injection',
+  },
+  ssrf: {
+    heading: 'Server-Side Request Forgery (SSRF) Vulnerabilities',
+    evidenceSection: 'SSRF Exploitation Evidence',
+    noneFoundLabel: 'SSRF',
+  },
+};
+
+function renderVulnSummarySubsections(selected: readonly VulnClass[]): string {
+  const classes = selected.length > 0 ? selected : (Object.keys(VULN_SUMMARY_SPECS) as VulnClass[]);
+  return classes
+    .map((cls) => {
+      const spec = VULN_SUMMARY_SPECS[cls];
+      return `**${spec.heading}:**\n{Check for "${spec.evidenceSection}" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No ${spec.noneFoundLabel} vulnerabilities were found."}`;
+    })
+    .join('\n\n');
+}
+
+/**
+ * Renders the top-level <report_filters> block. Empty when no filters are set —
+ * each filter is included only when the operator configured it, so the agent
+ * never sees `none` placeholders or instructions for filters that don't apply.
+ */
+function renderReportFiltersBlock(report: ReportConfig | undefined): string {
+  if (!report) return '';
+  const guidance = report.guidance?.trim();
+  if (!report.min_severity && !report.min_confidence && !guidance) return '';
+
+  const lines: string[] = [
+    '<report_filters>',
+    'The filters below are user-supplied and binding for this assessment. Honor each strictly when assembling the final report.',
+    '',
+  ];
+  if (report.min_severity) {
+    lines.push(
+      `- Minimum severity: ${report.min_severity} — keep only findings rated this severity or higher (scale: low < medium < high < critical).`,
+    );
+  }
+  if (report.min_confidence) {
+    lines.push(
+      `- Minimum confidence: ${report.min_confidence} — keep only findings rated this confidence or higher (scale: low < medium < high).`,
+    );
+  }
+  if (guidance) {
+    lines.push('');
+    lines.push('User guidance — apply throughout the report as binding directives for finding selection:');
+    lines.push(guidance);
+  }
+  lines.push('</report_filters>');
+  return lines.join('\n');
+}
+
+/**
+ * Renders the per-finding DROP rules used inside the cleanup step. Severity and
+ * confidence inline as concrete thresholds; guidance is referenced by pointer
+ * so the actual text only lives in <report_filters>, avoiding double-statement.
+ */
+function renderReportFilterRules(report: ReportConfig | undefined): string {
+  const drops: string[] = [];
+  if (report?.min_severity) drops.push(`* severity is below ${report.min_severity}`);
+  if (report?.min_confidence) drops.push(`* confidence is below ${report.min_confidence}`);
+  if (report?.guidance?.trim()) drops.push('* topic matches an exclusion in the user guidance');
+  if (drops.length === 0) return '';
+  return ['   - DROP any `### [TYPE]-VULN-[NUMBER]` finding whose:', ...drops.map((d) => `     ${d}`)].join('\n');
+}
+
 interface PromptVariables {
   webUrl: string;
   repoPath: string;
+  AUTH_STATE_FILE: string;
   PLAYWRIGHT_SESSION?: string;
 }
 
@@ -23,10 +128,14 @@ interface IncludeReplacement {
 }
 
 // Pure function: Build complete login instructions from config
-async function buildLoginInstructions(authentication: Authentication, logger: ActivityLogger): Promise<string> {
+async function buildLoginInstructions(
+  authentication: Authentication,
+  logger: ActivityLogger,
+  promptsBaseDir: string = PROMPTS_DIR,
+): Promise<string> {
   try {
     // 1. Load the login instructions template
-    const loginInstructionsPath = path.join(PROMPTS_DIR, 'shared', 'login-instructions.txt');
+    const loginInstructionsPath = path.join(promptsBaseDir, 'shared', 'login-instructions.txt');
 
     if (!(await fs.pathExists(loginInstructionsPath))) {
       throw new PentestError('Login instructions template not found', 'filesystem', false, { loginInstructionsPath });
@@ -72,6 +181,21 @@ async function buildLoginInstructions(authentication: Authentication, logger: Ac
           `generated TOTP code using secret "${authentication.credentials.totp_secret}"`,
         );
       }
+      if (authentication.credentials.email_login?.address) {
+        userInstructions = userInstructions.replace(/\$email_address/g, authentication.credentials.email_login.address);
+      }
+      if (authentication.credentials.email_login?.password) {
+        userInstructions = userInstructions.replace(
+          /\$email_password/g,
+          authentication.credentials.email_login.password,
+        );
+      }
+      if (authentication.credentials.email_login?.totp_secret) {
+        userInstructions = userInstructions.replace(
+          /\$email_totp/g,
+          `generated TOTP code using secret "${authentication.credentials.email_login.totp_secret}"`,
+        );
+      }
     }
 
     loginInstructions = loginInstructions.replace(/{{user_instructions}}/g, userInstructions);
@@ -148,6 +272,7 @@ async function interpolateVariables(
   variables: PromptVariables,
   config: DistributedConfig | null = null,
   logger: ActivityLogger,
+  promptsBaseDir: string = PROMPTS_DIR,
 ): Promise<string> {
   try {
     if (!template || typeof template !== 'string') {
@@ -170,36 +295,69 @@ async function interpolateVariables(
       .replace(/{{AUTH_CONTEXT}}/g, buildAuthContext(config))
       .replace(/{{DESCRIPTION}}/g, config?.description ? `Description: ${config.description}` : '');
 
-    if (config) {
-      // Handle rules section - if both are empty, use cleaner messaging
-      const hasAvoidRules = config.avoid && config.avoid.length > 0;
-      const hasFocusRules = config.focus && config.focus.length > 0;
-
-      if (!hasAvoidRules && !hasFocusRules) {
-        // Replace the entire rules section with a clean message
-        const cleanRulesSection = '<rules>\nNo specific rules or focus areas provided for this test.\n</rules>';
-        result = result.replace(/<rules>[\s\S]*?<\/rules>/g, cleanRulesSection);
-      } else {
-        const avoidRules = hasAvoidRules ? config.avoid?.map((r) => `- ${r.description}`).join('\n') : 'None';
-        const focusRules = hasFocusRules ? config.focus?.map((r) => `- ${r.description}`).join('\n') : 'None';
-
-        result = result.replace(/{{RULES_AVOID}}/g, avoidRules).replace(/{{RULES_FOCUS}}/g, focusRules);
-      }
-
-      // Extract and inject login instructions from config
-      if (config.authentication?.login_flow) {
-        const loginInstructions = await buildLoginInstructions(config.authentication, logger);
-        result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, loginInstructions);
-      } else {
-        result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, '');
-      }
+    const avoidUrlRules = config?.avoid?.filter((r) => r.type !== 'code_path') ?? [];
+    const focusUrlRules = config?.focus?.filter((r) => r.type !== 'code_path') ?? [];
+    if (avoidUrlRules.length === 0 && focusUrlRules.length === 0) {
+      result = result.replace(/<rules>[\s\S]*?<\/rules>\s*/g, '');
+    } else {
+      const avoidStr = avoidUrlRules.length > 0 ? avoidUrlRules.map((r) => `- ${r.description}`).join('\n') : 'None';
+      const focusStr = focusUrlRules.length > 0 ? focusUrlRules.map((r) => `- ${r.description}`).join('\n') : 'None';
+      result = result.replace(/{{RULES_AVOID}}/g, avoidStr).replace(/{{RULES_FOCUS}}/g, focusStr);
+    }
+
+    const avoidCodeRules = (config?.avoid ?? []).filter((r) => r.type === 'code_path');
+    const focusCodeRules = (config?.focus ?? []).filter((r) => r.type === 'code_path');
+    if (avoidCodeRules.length === 0 && focusCodeRules.length === 0) {
+      result = result.replace(/<code_path_rules>[\s\S]*?<\/code_path_rules>\s*/g, '');
+    } else {
+      result = result
+        .replace(/{{CODE_RULES_AVOID}}/g, renderCodePathRules(config?.avoid ?? []))
+        .replace(/{{CODE_RULES_FOCUS}}/g, renderCodePathRules(config?.focus ?? []));
+    }
+
+    const roe = config?.rules_of_engagement?.trim() ?? '';
+    if (roe) {
+      result = result.replace(/{{RULES_OF_ENGAGEMENT}}/g, roe);
+    } else {
+      result = result.replace(/<rules_of_engagement>[\s\S]*?<\/rules_of_engagement>\s*/g, '');
+    }
+
+    if (!config?.authentication) {
+      result = result.replace(/<shared_authenticated_session>[\s\S]*?<\/shared_authenticated_session>\s*/g, '');
+    } else {
+      result = result.replace(/{{AUTH_STATE_FILE}}/g, variables.AUTH_STATE_FILE);
+    }
+
+    if (config?.authentication?.login_flow) {
+      const loginInstructions = await buildLoginInstructions(config.authentication, logger, promptsBaseDir);
+      result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, loginInstructions);
     } else {
-      // Replace the entire rules section with a clean message when no config provided
-      const cleanRulesSection = '<rules>\nNo specific rules or focus areas provided for this test.\n</rules>';
-      result = result.replace(/<rules>[\s\S]*?<\/rules>/g, cleanRulesSection);
       result = result.replace(/{{LOGIN_INSTRUCTIONS}}/g, '');
     }
 
+    const vulnClasses = config?.vuln_classes ?? [];
+    result = result.replace(
+      /{{VULN_CLASSES_TESTED}}/g,
+      vulnClasses.length > 0 ? vulnClasses.join(', ') : 'injection, xss, auth, authz, ssrf',
+    );
+    result = result.replace(/{{VULN_SUMMARY_SUBSECTIONS}}/g, renderVulnSummarySubsections(vulnClasses));
+
+    const exploitEnabled = config?.exploit ?? true;
+    result = result
+      .replace(/{{EXPLOITATION}}/g, exploitEnabled ? 'enabled' : 'disabled')
+      .replace(/{{REPORT_VULN_HEADING}}/g, exploitEnabled ? 'Exploitation Evidence' : 'Findings')
+      .replace(
+        /{{REPORT_VULN_SUBHEADING}}/g,
+        exploitEnabled ? 'Successfully Exploited Vulnerabilities' : 'Identified Vulnerabilities',
+      );
+
+    result = result
+      .replace(/{{REPORT_FILTERS_BLOCK}}/g, renderReportFiltersBlock(config?.report))
+      .replace(/{{REPORT_FILTER_RULES}}/g, renderReportFilterRules(config?.report));
+
+    // Collapse runs of 3+ newlines (left behind by tag-strip and empty-fragment substitutions).
+    result = result.replace(/\n{3,}/g, '\n\n');
+
     // Validate that all placeholders have been replaced (excluding instructional text)
     const remainingPlaceholders = result.match(/\{\{[^}]+\}\}/g);
     if (remainingPlaceholders) {
@@ -216,6 +374,14 @@ async function interpolateVariables(
   }
 }
 
+// Resolve promptDir override against SHANNON_WORKER_ROOT so relative paths
+// from callers stay cwd-independent.
+function resolvePromptDir(promptDir: string | undefined): string {
+  if (!promptDir) return PROMPTS_DIR;
+  if (path.isAbsolute(promptDir)) return promptDir;
+  return path.resolve(process.env.SHANNON_WORKER_ROOT ?? process.cwd(), promptDir);
+}
+
 // Pure function: Load and interpolate prompt template
 export async function loadPrompt(
   promptName: string,
@@ -223,10 +389,11 @@ export async function loadPrompt(
   config: DistributedConfig | null = null,
   pipelineTestingMode: boolean = false,
   logger: ActivityLogger,
+  promptDir?: string,
 ): Promise<string> {
   try {
-    // 1. Resolve prompt file path
-    const promptsDir = pipelineTestingMode ? path.join(PROMPTS_DIR, 'pipeline-testing') : PROMPTS_DIR;
+    const basePromptsDir = resolvePromptDir(promptDir);
+    const promptsDir = pipelineTestingMode ? path.join(basePromptsDir, 'pipeline-testing') : basePromptsDir;
     const promptPath = path.join(promptsDir, `${promptName}.txt`);
 
     if (pipelineTestingMode) {
@@ -256,7 +423,7 @@ export async function loadPrompt(
     template = await processIncludes(template, promptsDir);
 
     // 5. Interpolate variables and return final prompt
-    return await interpolateVariables(template, enhancedVariables, config, logger);
+    return await interpolateVariables(template, enhancedVariables, config, logger, basePromptsDir);
   } catch (error) {
     if (error instanceof PentestError) {
       throw error;

apps/worker/src/services/queue-validation.ts

@@ -5,6 +5,7 @@
 // as published by the Free Software Foundation.
 
 import { fs, path } from 'zx';
+
 import type { ExploitationDecision, VulnType } from '../types/agents.js';
 import { ErrorCode } from '../types/errors.js';
 import { err, ok, type Result } from '../types/result.js';
@@ -114,12 +115,12 @@ function getExistenceErrorMessage(existence: FileExistence): string {
   const { deliverableExists, queueExists } = existence;
 
   if (!deliverableExists && !queueExists) {
-    return 'Analysis failed: Neither deliverable nor queue file exists. Analysis agent must create both files.';
+    return 'Analysis failed: Neither deliverable nor queue file exists. Both are required.';
   }
   if (!queueExists) {
-    return 'Analysis incomplete: Deliverable exists but queue file missing. Analysis agent must create both files.';
+    return 'Analysis incomplete: Deliverable exists but queue file missing. Both are required.';
   }
-  return 'Analysis incomplete: Queue exists but deliverable file missing. Analysis agent must create both files.';
+  return 'Analysis incomplete: Queue exists but deliverable file missing. Both are required.';
 }
 
 // Pure function to create file paths
@@ -133,8 +134,8 @@ const createPaths = (vulnType: VulnType, sourceDir: string): PathsBase | PathsWi
 
   return Object.freeze({
     vulnType,
-    deliverable: path.join(sourceDir, 'deliverables', config.deliverable),
-    queue: path.join(sourceDir, 'deliverables', config.queue),
+    deliverable: path.join(sourceDir, config.deliverable),
+    queue: path.join(sourceDir, config.queue),
     sourceDir,
   });
 };

apps/worker/src/services/recon-renderer.ts

@@ -0,0 +1,561 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Deterministic recon collector → markdown renderer.
+ *
+ * Converts the typed payload bag harvested from the recon-collector MCP server
+ * into the recon_deliverable.md Markdown layout. No LLM in the loop; section
+ * ordering, headings, sort, and the Section 0 boilerplate are owned here.
+ *
+ * Any tool the agent skips becomes a `[Section X: not provided]` placeholder
+ * rather than an activity failure. Every section renderer accepts its input as
+ * optional.
+ */
+
+import type {
+  AuthenticationInput,
+  AuthzCandidatesInput,
+  ContextCandidate,
+  Endpoint,
+  Entity,
+  ExecutiveSummaryInput,
+  Flow,
+  Guard,
+  HorizontalCandidate,
+  InjectionSourcesInput,
+  InputVectorsInput,
+  NetworkMapInput,
+  Priority,
+  ReconData,
+  Role,
+  RoleArchitectureInput,
+  SinkRef,
+  TechnologyStackInput,
+  VerticalCandidate,
+} from '../mcp-server/recon-collector.js';
+
+type RoleSwitchingImpersonation = AuthenticationInput['role_switching_impersonation'];
+type EntityZone = Entity['zone'];
+
+// ============================================================================
+// STATIC PROSE
+// ============================================================================
+
+const HOW_TO_READ_THIS = `## 0) HOW TO READ THIS
+This reconnaissance report provides a comprehensive map of the application's attack surface, with special emphasis on authorization and privilege escalation opportunities for the Authorization Analysis Specialist.
+
+**Key Sections for Authorization Analysis:**
+- **Section 4 (API Endpoint Inventory):** Contains authorization details for each endpoint - focus on "Required Role" and "Object ID Parameters" columns to identify IDOR candidates.
+- **Section 6.4 (Guards Directory):** Catalog of authorization controls - understand what each guard means before analyzing vulnerabilities.
+- **Section 7 (Role & Privilege Architecture):** Complete role hierarchy and privilege mapping - use this to understand the privilege lattice and identify escalation targets.
+- **Section 8 (Authorization Vulnerability Candidates):** Pre-prioritized lists of endpoints for horizontal, vertical, and context-based authorization testing.
+
+**How to Use the Network Mapping (Section 6):** The entity/flow mapping shows system boundaries and data sensitivity levels. Pay special attention to flows marked with authorization guards and entities handling PII/sensitive data.
+
+**Priority Order for Testing:** Start with Section 8's High-priority horizontal candidates, then vertical escalation endpoints for each role level, finally context-based workflow bypasses.`;
+
+// ============================================================================
+// SORT ORDER CONSTANTS
+// ============================================================================
+
+// Zones are sorted by exposure (Internet → Edge → ... → ThirdParty), not alphabetically,
+// per the design doc's "clusters by zone" requirement. A reader scanning the entities
+// table sees external surface first, internal trust core last.
+const ZONE_ORDER: Record<EntityZone, number> = {
+  Internet: 0,
+  Edge: 1,
+  App: 2,
+  Data: 3,
+  Admin: 4,
+  BuildCI: 5,
+  ThirdParty: 6,
+};
+
+const PRIORITY_ORDER: Record<Priority, number> = {
+  High: 0,
+  Medium: 1,
+  Low: 2,
+};
+
+// ============================================================================
+// SHARED HELPERS
+// ============================================================================
+
+function placeholder(sectionLabel: string, toolName: string): string {
+  return `_[${sectionLabel}: not provided — \`${toolName}\` was not called]_`;
+}
+
+function bulletField(label: string, value: string): string {
+  return `- **${label}:** ${value}`;
+}
+
+function bulletList(label: string, items: readonly string[]): string {
+  if (items.length === 0) {
+    return `- **${label}:** *(none identified)*`;
+  }
+  return `- **${label}:**\n${items.map((entry) => `  - ${entry}`).join('\n')}`;
+}
+
+function escapePipe(value: string): string {
+  return value.replace(/\|/g, '\\|');
+}
+
+function renderTable(headers: readonly string[], rows: readonly (readonly string[])[]): string {
+  const headerRow = `| ${headers.map(escapePipe).join(' | ')} |`;
+  const separator = `| ${headers.map(() => '---').join(' | ')} |`;
+  const body = rows.map((row) => `| ${row.map(escapePipe).join(' | ')} |`).join('\n');
+  return [headerRow, separator, body].filter((line) => line.length > 0).join('\n');
+}
+
+function renderSinkList(sinks: readonly SinkRef[]): string {
+  if (sinks.length === 0) {
+    return '*(scanned, no sources of this kind found)*';
+  }
+  return sinks
+    .map((sink) => {
+      const head = `- **${sink.sink_function}** at \`${sink.location}\``;
+      if (sink.notes && sink.notes.trim() !== '') {
+        return `${head} — ${sink.notes.trim()}`;
+      }
+      return head;
+    })
+    .join('\n');
+}
+
+// ============================================================================
+// SECTION RENDERERS
+// ============================================================================
+
+function renderHowToReadThis(): string {
+  return HOW_TO_READ_THIS;
+}
+
+function renderExecutiveSummary(data: ExecutiveSummaryInput | undefined): string {
+  if (!data) {
+    return ['## 1. Executive Summary', '', placeholder('Section 1', 'set_executive_summary')].join('\n');
+  }
+  return ['## 1. Executive Summary', '', data.text].join('\n');
+}
+
+function renderTechnologyStack(data: TechnologyStackInput | undefined): string {
+  if (!data) {
+    return ['## 2. Technology & Service Map', '', placeholder('Section 2', 'set_technology_stack')].join('\n');
+  }
+  return [
+    '## 2. Technology & Service Map',
+    '',
+    bulletField('Frontend', data.frontend),
+    bulletField('Backend', data.backend),
+    bulletField('Infrastructure', data.infrastructure),
+  ].join('\n');
+}
+
+function renderRoleSwitching(rs: RoleSwitchingImpersonation): string {
+  if (!rs.applicable) {
+    return [
+      '### 3.3 Role Switching & Impersonation',
+      '',
+      '*(Not applicable — no impersonation, sudo mode, or role-switching features were identified.)*',
+    ].join('\n');
+  }
+  return [
+    '### 3.3 Role Switching & Impersonation',
+    '',
+    bulletField('Impersonation Features', rs.impersonation_features ?? '*(not specified)*'),
+    bulletField('Role Switching', rs.role_switching ?? '*(not specified)*'),
+    bulletField('Audit Trail', rs.audit_trail ?? '*(not specified)*'),
+    bulletField('Code Implementation', rs.code_implementation ?? '*(not specified)*'),
+  ].join('\n');
+}
+
+function renderAuthentication(data: AuthenticationInput | undefined): string {
+  if (!data) {
+    return ['## 3. Authentication & Session Management Flow', '', placeholder('Section 3', 'set_authentication')].join(
+      '\n',
+    );
+  }
+  const { session_flow: sf, role_assignment: ra, privilege_storage: ps } = data;
+  return [
+    '## 3. Authentication & Session Management Flow',
+    '',
+    bulletField('Entry Points', sf.entry_points),
+    bulletField('Mechanism', sf.mechanism),
+    bulletField('Code Pointers', sf.code_pointers),
+    '',
+    '### 3.1 Role Assignment Process',
+    '',
+    bulletField('Role Determination', ra.role_determination),
+    bulletField('Default Role', ra.default_role),
+    bulletField('Role Upgrade Path', ra.role_upgrade_path),
+    bulletField('Code Implementation', ra.code_implementation),
+    '',
+    '### 3.2 Privilege Storage & Validation',
+    '',
+    bulletField('Storage Location', ps.storage_location),
+    bulletField('Validation Points', ps.validation_points),
+    bulletField('Cache/Session Persistence', ps.cache_session_persistence),
+    bulletField('Code Pointers', ps.code_pointers),
+    '',
+    renderRoleSwitching(data.role_switching_impersonation),
+  ].join('\n');
+}
+
+function sortEndpoints(endpoints: readonly Endpoint[]): Endpoint[] {
+  return [...endpoints].sort((a, b) => {
+    if (a.path !== b.path) return a.path.localeCompare(b.path);
+    return a.method.localeCompare(b.method);
+  });
+}
+
+function renderEndpoints(endpoints: readonly Endpoint[] | undefined): string {
+  if (!endpoints || endpoints.length === 0) {
+    return ['## 4. API Endpoint Inventory', '', placeholder('Section 4', 'add_endpoints')].join('\n');
+  }
+  const sorted = sortEndpoints(endpoints);
+  const rows = sorted.map((e) => [
+    e.method,
+    e.path,
+    e.required_role,
+    e.object_id_parameters.length > 0 ? e.object_id_parameters.join(', ') : 'None',
+    e.authorization_mechanism,
+    `${e.description} (${e.code_pointer})`,
+  ]);
+  return [
+    '## 4. API Endpoint Inventory',
+    '',
+    renderTable(
+      [
+        'Method',
+        'Endpoint Path',
+        'Required Role',
+        'Object ID Parameters',
+        'Authorization Mechanism',
+        'Description & Code Pointer',
+      ],
+      rows,
+    ),
+  ].join('\n');
+}
+
+function renderInputVectors(data: InputVectorsInput | undefined): string {
+  if (!data) {
+    return [
+      '## 5. Potential Input Vectors for Vulnerability Analysis',
+      '',
+      placeholder('Section 5', 'set_input_vectors'),
+    ].join('\n');
+  }
+  return [
+    '## 5. Potential Input Vectors for Vulnerability Analysis',
+    '',
+    bulletList('URL Parameters', data.url_parameters),
+    bulletList('POST Body Fields (JSON/Form)', data.post_body_fields),
+    bulletList('HTTP Headers', data.http_headers),
+    bulletList('Cookie Values', data.cookie_values),
+  ].join('\n');
+}
+
+function sortEntities(entities: readonly Entity[]): Entity[] {
+  return [...entities].sort((a, b) => {
+    const zoneDiff = ZONE_ORDER[a.zone] - ZONE_ORDER[b.zone];
+    if (zoneDiff !== 0) return zoneDiff;
+    if (a.type !== b.type) return a.type.localeCompare(b.type);
+    return a.title.localeCompare(b.title);
+  });
+}
+
+function sortFlows(flows: readonly Flow[]): Flow[] {
+  return [...flows].sort((a, b) => {
+    if (a.from !== b.from) return a.from.localeCompare(b.from);
+    if (a.to !== b.to) return a.to.localeCompare(b.to);
+    return a.path_port.localeCompare(b.path_port);
+  });
+}
+
+function sortGuards(guards: readonly Guard[]): Guard[] {
+  return [...guards].sort((a, b) => {
+    if (a.category !== b.category) return a.category.localeCompare(b.category);
+    return a.name.localeCompare(b.name);
+  });
+}
+
+function renderEntitiesTable(entities: readonly Entity[]): string {
+  const rows = entities.map((e) => [e.title, e.type, e.zone, e.tech, e.data.join(', '), e.notes]);
+  return renderTable(['Title', 'Type', 'Zone', 'Tech', 'Data', 'Notes'], rows);
+}
+
+function renderEntityMetadataTable(entities: readonly Entity[]): string {
+  const rows = entities.map((e) => {
+    const metadataLine =
+      e.metadata.length > 0 ? e.metadata.map(({ key, value }) => `${key}: ${value}`).join('; ') : '*(none)*';
+    return [e.title, metadataLine];
+  });
+  return renderTable(['Title', 'Metadata'], rows);
+}
+
+function renderFlowsTable(flows: readonly Flow[]): string {
+  const rows = flows.map((f) => [
+    `${f.from} → ${f.to}`,
+    f.channel,
+    f.path_port,
+    f.guards.length > 0 ? f.guards.join(', ') : 'None',
+    f.touches.length > 0 ? f.touches.join(', ') : 'Public',
+  ]);
+  return renderTable(['FROM → TO', 'Channel', 'Path/Port', 'Guards', 'Touches'], rows);
+}
+
+function renderGuardsTable(guards: readonly Guard[]): string {
+  const rows = guards.map((g) => [g.name, g.category, g.statement]);
+  return renderTable(['Guard Name', 'Category', 'Statement'], rows);
+}
+
+function renderNetworkMap(data: NetworkMapInput | undefined): string {
+  if (!data) {
+    return ['## 6. Network & Interaction Map', '', placeholder('Section 6', 'set_network_map')].join('\n');
+  }
+  const entities = sortEntities(data.entities);
+  const flows = sortFlows(data.flows);
+  const guards = sortGuards(data.guards);
+  return [
+    '## 6. Network & Interaction Map',
+    '',
+    '### 6.1 Entities',
+    '',
+    entities.length > 0 ? renderEntitiesTable(entities) : '*(no entities recorded)*',
+    '',
+    '### 6.2 Entity Metadata',
+    '',
+    entities.length > 0 ? renderEntityMetadataTable(entities) : '*(no entities recorded)*',
+    '',
+    '### 6.3 Flows (Connections)',
+    '',
+    flows.length > 0 ? renderFlowsTable(flows) : '*(no flows recorded)*',
+    '',
+    '### 6.4 Guards Directory',
+    '',
+    guards.length > 0 ? renderGuardsTable(guards) : '*(no guards recorded)*',
+  ].join('\n');
+}
+
+function sortRoles(roles: readonly Role[]): Role[] {
+  return [...roles].sort((a, b) => {
+    if (a.privilege_level !== b.privilege_level) return a.privilege_level - b.privilege_level;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+function renderRoleArchitecture(data: RoleArchitectureInput | undefined): string {
+  if (!data) {
+    return ['## 7. Role & Privilege Architecture', '', placeholder('Section 7', 'set_role_architecture')].join('\n');
+  }
+  const roles = sortRoles(data.roles);
+  const discoveredRows = roles.map((r) => [r.name, String(r.privilege_level), r.scope_domain, r.code_implementation]);
+  const entryPointRows = roles.map((r) => [
+    r.name,
+    r.default_landing_page,
+    r.accessible_route_patterns.length > 0 ? r.accessible_route_patterns.join(', ') : 'None',
+    r.authentication_method,
+  ]);
+  const codeMappingRows = roles.map((r) => [r.name, r.middleware_guards, r.permission_checks, r.storage_location]);
+  const lattice = data.privilege_lattice;
+  const latticeBlock = [
+    '```',
+    `Privilege Ordering (→ means "can access resources of"):`,
+    lattice.ordering_diagram,
+    '',
+    `Parallel Isolation (|| means "not ordered relative to each other"):`,
+    lattice.parallel_isolation_notes,
+    '```',
+  ].join('\n');
+  const sections = [
+    '## 7. Role & Privilege Architecture',
+    '',
+    '### 7.1 Discovered Roles',
+    '',
+    roles.length > 0
+      ? renderTable(['Role Name', 'Privilege Level', 'Scope/Domain', 'Code Implementation'], discoveredRows)
+      : '*(no roles recorded)*',
+    '',
+    '### 7.2 Privilege Lattice',
+    '',
+    latticeBlock,
+  ];
+  if (lattice.role_switching_notes && lattice.role_switching_notes.trim() !== '') {
+    sections.push('', `**Note:** ${lattice.role_switching_notes.trim()}`);
+  }
+  sections.push(
+    '',
+    '### 7.3 Role Entry Points',
+    '',
+    roles.length > 0
+      ? renderTable(
+          ['Role', 'Default Landing Page', 'Accessible Route Patterns', 'Authentication Method'],
+          entryPointRows,
+        )
+      : '*(no roles recorded)*',
+    '',
+    '### 7.4 Role-to-Code Mapping',
+    '',
+    roles.length > 0
+      ? renderTable(['Role', 'Middleware/Guards', 'Permission Checks', 'Storage Location'], codeMappingRows)
+      : '*(no roles recorded)*',
+  );
+  return sections.join('\n');
+}
+
+function sortHorizontal(items: readonly HorizontalCandidate[]): HorizontalCandidate[] {
+  return [...items].sort((a, b) => {
+    const pri = PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority];
+    if (pri !== 0) return pri;
+    return a.endpoint_pattern.localeCompare(b.endpoint_pattern);
+  });
+}
+
+function sortVertical(items: readonly VerticalCandidate[]): VerticalCandidate[] {
+  return [...items].sort((a, b) => {
+    const pri = PRIORITY_ORDER[a.risk_level] - PRIORITY_ORDER[b.risk_level];
+    if (pri !== 0) return pri;
+    return a.endpoint_pattern.localeCompare(b.endpoint_pattern);
+  });
+}
+
+function sortContext(items: readonly ContextCandidate[]): ContextCandidate[] {
+  return [...items].sort((a, b) => a.endpoint.localeCompare(b.endpoint));
+}
+
+function renderAuthzCandidates(data: AuthzCandidatesInput | undefined): string {
+  if (!data) {
+    return ['## 8. Authorization Vulnerability Candidates', '', placeholder('Section 8', 'set_authz_candidates')].join(
+      '\n',
+    );
+  }
+  const horizontal = sortHorizontal(data.horizontal);
+  const vertical = sortVertical(data.vertical);
+  const context = sortContext(data.context);
+
+  let idCounter = 0;
+  const nextId = (): string => {
+    idCounter += 1;
+    return `AUTHZ-CAND-${String(idCounter).padStart(2, '0')}`;
+  };
+
+  const horizontalRows = horizontal.map((c) => [
+    nextId(),
+    c.priority,
+    c.endpoint_pattern,
+    c.object_id_parameter,
+    c.data_type,
+    c.sensitivity,
+  ]);
+  const verticalRows = vertical.map((c) => [
+    nextId(),
+    c.target_role,
+    c.endpoint_pattern,
+    c.functionality,
+    c.risk_level,
+  ]);
+  const contextRows = context.map((c) => [
+    nextId(),
+    c.workflow,
+    c.endpoint,
+    c.expected_prior_state,
+    c.bypass_potential,
+  ]);
+
+  return [
+    '## 8. Authorization Vulnerability Candidates',
+    '',
+    '### 8.1 Horizontal Privilege Escalation Candidates',
+    '',
+    horizontal.length > 0
+      ? renderTable(
+          ['ID', 'Priority', 'Endpoint Pattern', 'Object ID Parameter', 'Data Type', 'Sensitivity'],
+          horizontalRows,
+        )
+      : '*(no horizontal candidates identified)*',
+    '',
+    '### 8.2 Vertical Privilege Escalation Candidates',
+    '',
+    vertical.length > 0
+      ? renderTable(['ID', 'Target Role', 'Endpoint Pattern', 'Functionality', 'Risk Level'], verticalRows)
+      : '*(no vertical candidates identified)*',
+    '',
+    '### 8.3 Context-Based Authorization Candidates',
+    '',
+    context.length > 0
+      ? renderTable(['ID', 'Workflow', 'Endpoint', 'Expected Prior State', 'Bypass Potential'], contextRows)
+      : '*(no context-based candidates identified)*',
+  ].join('\n');
+}
+
+function renderInjectionSources(data: InjectionSourcesInput | undefined): string {
+  const heading =
+    '## 9. Injection Sources (Command Injection, SQL Injection, LFI/RFI, SSTI, Path Traversal, Deserialization)';
+  if (!data) {
+    return [heading, '', placeholder('Section 9', 'set_injection_sources')].join('\n');
+  }
+  if (!data.applicable) {
+    return [
+      heading,
+      '',
+      '*(Not applicable — this application has no network-accessible code paths to dangerous sinks.)*',
+    ].join('\n');
+  }
+  return [
+    heading,
+    '',
+    '### Command Injection',
+    renderSinkList(data.command_injection),
+    '',
+    '### SQL Injection',
+    renderSinkList(data.sql_injection),
+    '',
+    '### LFI/RFI',
+    renderSinkList(data.lfi_rfi),
+    '',
+    '### Path Traversal',
+    renderSinkList(data.path_traversal),
+    '',
+    '### SSTI',
+    renderSinkList(data.ssti),
+    '',
+    '### Deserialization',
+    renderSinkList(data.deserialization),
+  ].join('\n');
+}
+
+// ============================================================================
+// PUBLIC ENTRY POINT
+// ============================================================================
+
+export function renderRecon(data: ReconData): string {
+  const sections: string[] = [
+    '# Reconnaissance Deliverable:',
+    '',
+    renderHowToReadThis(),
+    '',
+    renderExecutiveSummary(data.executive_summary),
+    '',
+    renderTechnologyStack(data.technology_stack),
+    '',
+    renderAuthentication(data.authentication),
+    '',
+    renderEndpoints(data.endpoints),
+    '',
+    renderInputVectors(data.input_vectors),
+    '',
+    renderNetworkMap(data.network_map),
+    '',
+    renderRoleArchitecture(data.role_architecture),
+    '',
+    renderAuthzCandidates(data.authz_candidates),
+    '',
+    renderInjectionSources(data.injection_sources),
+    '',
+  ];
+  return `${sections.join('\n').trimEnd()}\n`;
+}

apps/worker/src/services/reporting.ts

@@ -5,62 +5,73 @@
 // as published by the Free Software Foundation.
 
 import { fs, path } from 'zx';
+import { deliverablesDir } from '../paths.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
 import { ErrorCode } from '../types/errors.js';
 import { PentestError } from './error-handling.js';
 
 interface DeliverableFile {
   name: string;
-  path: string;
+  /** Candidate filenames in priority order. First one that exists wins. */
+  paths: readonly string[];
   required: boolean;
 }
 
-// Pure function: Assemble final report from specialist deliverables
-export async function assembleFinalReport(sourceDir: string, logger: ActivityLogger): Promise<string> {
-  const deliverableFiles: DeliverableFile[] = [
-    { name: 'Injection', path: 'injection_exploitation_evidence.md', required: false },
-    { name: 'XSS', path: 'xss_exploitation_evidence.md', required: false },
-    { name: 'Authentication', path: 'auth_exploitation_evidence.md', required: false },
-    { name: 'SSRF', path: 'ssrf_exploitation_evidence.md', required: false },
-    { name: 'Authorization', path: 'authz_exploitation_evidence.md', required: false },
+// Pure function: Assemble final report from specialist deliverables.
+// Per class, prefer the exploit-agent's evidence file; fall back to renderer-produced findings.
+// Both never coexist for a workspace because scope (exploit flag) is locked.
+export async function assembleFinalReport(
+  sourceDir: string,
+  deliverablesSubdir: string | undefined,
+  logger: ActivityLogger,
+): Promise<string> {
+  const deliverableFiles: readonly DeliverableFile[] = [
+    { name: 'Injection', paths: ['injection_exploitation_evidence.md', 'injection_findings.md'], required: false },
+    { name: 'XSS', paths: ['xss_exploitation_evidence.md', 'xss_findings.md'], required: false },
+    { name: 'Authentication', paths: ['auth_exploitation_evidence.md', 'auth_findings.md'], required: false },
+    { name: 'SSRF', paths: ['ssrf_exploitation_evidence.md', 'ssrf_findings.md'], required: false },
+    { name: 'Authorization', paths: ['authz_exploitation_evidence.md', 'authz_findings.md'], required: false },
   ];
 
+  const dir = deliverablesDir(sourceDir, deliverablesSubdir);
   const sections: string[] = [];
 
   for (const file of deliverableFiles) {
-    const filePath = path.join(sourceDir, 'deliverables', file.path);
-    try {
-      if (await fs.pathExists(filePath)) {
-        const content = await fs.readFile(filePath, 'utf8');
-        sections.push(content);
-        logger.info(`Added ${file.name} findings`);
-      } else if (file.required) {
+    let added = false;
+    for (const candidate of file.paths) {
+      const filePath = path.join(dir, candidate);
+      try {
+        if (await fs.pathExists(filePath)) {
+          const content = await fs.readFile(filePath, 'utf8');
+          sections.push(content);
+          logger.info(`Added ${file.name} section from ${candidate}`);
+          added = true;
+          break;
+        }
+      } catch (error) {
+        const err = error as Error;
+        logger.warn(`Could not read ${candidate}: ${err.message}`);
+      }
+    }
+    if (!added) {
+      if (file.required) {
         throw new PentestError(
-          `Required deliverable file not found: ${file.path}`,
+          `Required deliverable file not found: ${file.paths.join(' or ')}`,
           'filesystem',
           false,
-          { deliverableFile: file.path, sourceDir },
+          { deliverableFile: file.paths, sourceDir },
           ErrorCode.DELIVERABLE_NOT_FOUND,
         );
-      } else {
-        logger.info(`No ${file.name} deliverable found`);
       }
-    } catch (error) {
-      if (file.required) {
-        throw error;
-      }
-      const err = error as Error;
-      logger.warn(`Could not read ${file.path}: ${err.message}`);
+      logger.info(`No ${file.name} deliverable found`);
     }
   }
 
   const finalContent = sections.join('\n\n');
-  const deliverablesDir = path.join(sourceDir, 'deliverables');
-  const finalReportPath = path.join(deliverablesDir, 'comprehensive_security_assessment_report.md');
+  const finalReportPath = path.join(dir, 'comprehensive_security_assessment_report.md');
 
   try {
-    // Ensure deliverables directory exists
-    await fs.ensureDir(deliverablesDir);
+    await fs.ensureDir(dir);
     await fs.writeFile(finalReportPath, finalContent);
     logger.info(`Final report assembled at ${finalReportPath}`);
   } catch (error) {
@@ -81,6 +92,7 @@ export async function assembleFinalReport(sourceDir: string, logger: ActivityLog
  */
 export async function injectModelIntoReport(
   repoPath: string,
+  deliverablesSubdir: string | undefined,
   outputPath: string,
   logger: ActivityLogger,
 ): Promise<void> {
@@ -117,7 +129,10 @@ export async function injectModelIntoReport(
   logger.info(`Injecting model info into report: ${modelStr}`);
 
   // 3. Read the final report
-  const reportPath = path.join(repoPath, 'deliverables', 'comprehensive_security_assessment_report.md');
+  const reportPath = path.join(
+    deliverablesDir(repoPath, deliverablesSubdir),
+    'comprehensive_security_assessment_report.md',
+  );
 
   if (!(await fs.pathExists(reportPath))) {
     logger.warn('Final report not found, skipping model injection');

apps/worker/src/services/validate-authentication.ts

@@ -0,0 +1,262 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Authentication validation service.
+ *
+ * Drives a real browser via the playwright-cli skill to confirm
+ * user-supplied credentials log in successfully, before the pentest
+ * pipeline burns hours on broken auth.
+ */
+
+import { readFile, rm } from 'node:fs/promises';
+import type { JsonSchemaOutputFormat } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { runClaudePrompt } from '../ai/claude-executor.js';
+import type { AuditSession } from '../audit/index.js';
+import { authStateFile } from '../audit/utils.js';
+import type { ActivityLogger } from '../types/activity-logger.js';
+import type { AgentEndResult } from '../types/audit.js';
+import type { DistributedConfig, ProviderConfig } from '../types/config.js';
+import { ErrorCode } from '../types/errors.js';
+import { err, ok, type Result } from '../types/result.js';
+import { PentestError } from './error-handling.js';
+import { loadPrompt } from './prompt-manager.js';
+
+const FAILURE_POINTS = ['username_or_password', 'totp_secret', 'out_of_band'] as const;
+type AuthFailurePoint = (typeof FAILURE_POINTS)[number];
+
+function isAuthFailurePoint(v: unknown): v is AuthFailurePoint {
+  return typeof v === 'string' && (FAILURE_POINTS as readonly string[]).includes(v);
+}
+
+// NOTE: SDK's AJV validator expects draft-07; Zod defaults to draft-2020-12,
+// which causes the SDK to silently skip structured output.
+const AuthValidationSchema = z.object({
+  login_success: z.boolean(),
+  failure_point: z.enum(FAILURE_POINTS).optional(),
+  failure_detail: z
+    .string()
+    .max(250)
+    .optional()
+    .describe(
+      'Free-form 1-2 sentence diagnostic of what the page showed (error messages, page state) when login failed. Required when login_success is false. Mask any sensitive values.',
+    ),
+});
+
+type AuthValidationVerdict = z.infer<typeof AuthValidationSchema>;
+
+const VALIDATION_SCHEMA: JsonSchemaOutputFormat = {
+  type: 'json_schema',
+  schema: z.toJSONSchema(AuthValidationSchema, { target: 'draft-07' }) as Record<string, unknown>,
+};
+
+const AGENT_NAME = 'validate-authentication';
+
+export interface ValidateAuthInput {
+  readonly distributedConfig: DistributedConfig;
+  readonly repoPath: string;
+  readonly webUrl: string;
+  readonly logger: ActivityLogger;
+  readonly auditSession: AuditSession;
+  readonly attemptNumber: number;
+  readonly apiKey?: string;
+  readonly providerConfig?: ProviderConfig;
+  readonly deliverablesSubdir?: string;
+  readonly promptDir?: string;
+  readonly pipelineTestingMode?: boolean;
+}
+
+export async function validateAuthentication(input: ValidateAuthInput): Promise<Result<void, PentestError>> {
+  const {
+    distributedConfig,
+    repoPath,
+    webUrl,
+    logger,
+    auditSession,
+    attemptNumber,
+    apiKey,
+    providerConfig,
+    deliverablesSubdir,
+    promptDir,
+    pipelineTestingMode,
+  } = input;
+
+  const authentication = distributedConfig.authentication;
+  if (!authentication) {
+    return ok(undefined);
+  }
+
+  logger.info('Validating authentication credentials with live browser...', {
+    loginUrl: authentication.login_url,
+    loginType: authentication.login_type,
+  });
+
+  const stateFile = authStateFile(auditSession.sessionMetadata);
+  await rm(stateFile, { force: true });
+
+  const prompt = await loadPrompt(
+    AGENT_NAME,
+    { webUrl, repoPath, AUTH_STATE_FILE: stateFile },
+    distributedConfig,
+    pipelineTestingMode ?? false,
+    logger,
+    promptDir,
+  );
+
+  await auditSession.startAgent(AGENT_NAME, prompt, attemptNumber);
+  const startTime = Date.now();
+
+  const result = await runClaudePrompt(
+    prompt,
+    repoPath,
+    '',
+    'Authentication validation',
+    AGENT_NAME,
+    auditSession,
+    logger,
+    'medium',
+    VALIDATION_SCHEMA,
+    apiKey,
+    deliverablesSubdir,
+    providerConfig,
+  );
+
+  let classification = classifyResult(result, authentication);
+
+  if (classification.ok) {
+    const sessionCheck = await verifySavedAuthState(stateFile, logger);
+    if (!sessionCheck.ok) {
+      classification = sessionCheck;
+    }
+  }
+
+  const endResult: AgentEndResult = {
+    attemptNumber,
+    duration_ms: Date.now() - startTime,
+    cost_usd: result.cost || 0,
+    success: classification.ok,
+    ...(result.model !== undefined && { model: result.model }),
+    ...(!classification.ok && { error: classification.error.message }),
+  };
+  await auditSession.endAgent(AGENT_NAME, endResult);
+
+  return classification;
+}
+
+async function verifySavedAuthState(stateFile: string, logger: ActivityLogger): Promise<Result<void, PentestError>> {
+  let contents: string;
+  try {
+    contents = await readFile(stateFile, 'utf8');
+  } catch {
+    return err(
+      new PentestError(
+        `Preflight reported login success but did not save the authenticated session to ${stateFile}.`,
+        'validation',
+        true,
+        { stateFile },
+        ErrorCode.AGENT_EXECUTION_FAILED,
+      ),
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (parseErr) {
+    const detail = parseErr instanceof Error ? parseErr.message : String(parseErr);
+    return err(
+      new PentestError(
+        `Preflight saved an authenticated session to ${stateFile}, but the file is not valid JSON: ${detail}`,
+        'validation',
+        true,
+        { stateFile, parseError: detail },
+        ErrorCode.AGENT_EXECUTION_FAILED,
+      ),
+    );
+  }
+
+  const cookieCount = countStorageEntries(parsed, 'cookies');
+  const originCount = countStorageEntries(parsed, 'origins');
+  if (cookieCount === 0 && originCount === 0) {
+    return err(
+      new PentestError(
+        `Preflight saved an authenticated session to ${stateFile}, but it contains no cookies or origins — the browser was not actually logged in.`,
+        'validation',
+        true,
+        { stateFile, cookieCount, originCount },
+        ErrorCode.AGENT_EXECUTION_FAILED,
+      ),
+    );
+  }
+
+  logger.info('Preflight authenticated session saved', { stateFile, cookieCount, originCount });
+  return ok(undefined);
+}
+
+function countStorageEntries(parsed: unknown, key: 'cookies' | 'origins'): number {
+  if (typeof parsed !== 'object' || parsed === null) return 0;
+  const value = (parsed as Record<string, unknown>)[key];
+  return Array.isArray(value) ? value.length : 0;
+}
+
+function classifyResult(
+  result: import('../ai/claude-executor.js').ClaudePromptResult,
+  authentication: NonNullable<DistributedConfig['authentication']>,
+): Result<void, PentestError> {
+  if (!result.success) {
+    const detail = result.error ?? 'Validator agent terminated unexpectedly.';
+    return err(
+      new PentestError(
+        `Authentication validator failed to run: ${detail}`,
+        'validation',
+        result.retryable ?? true,
+        { originalError: detail, errorType: result.errorType, cost: result.cost },
+        ErrorCode.AGENT_EXECUTION_FAILED,
+      ),
+    );
+  }
+
+  if (!result.structuredOutput || typeof result.structuredOutput !== 'object') {
+    return err(
+      new PentestError(
+        'Authentication validator did not return a structured verdict.',
+        'validation',
+        true,
+        { cost: result.cost },
+        ErrorCode.AGENT_EXECUTION_FAILED,
+      ),
+    );
+  }
+
+  const verdict = result.structuredOutput as Partial<AuthValidationVerdict>;
+
+  if (verdict.login_success === true) {
+    return ok(undefined);
+  }
+
+  const failurePoint: AuthFailurePoint = isAuthFailurePoint(verdict.failure_point)
+    ? verdict.failure_point
+    : 'out_of_band';
+  const failureDetail =
+    verdict.failure_detail?.trim() || 'Login failed without a specific diagnostic from the validator agent.';
+
+  return err(
+    new PentestError(
+      `Authentication failed at "${failurePoint}": ${failureDetail}`,
+      'config',
+      false,
+      {
+        failurePoint,
+        failureDetail,
+        loginUrl: authentication.login_url,
+        loginType: authentication.login_type,
+        cost: result.cost,
+      },
+      ErrorCode.AUTH_LOGIN_FAILED,
+    ),
+  );
+}

apps/worker/src/services/vuln-renderer.ts

@@ -0,0 +1,229 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Deterministic vuln collector → markdown renderer.
+ *
+ * Single entry point renderVulnDeliverable(vulnClass, data) covers all 5
+ * vulnerability classes (injection, xss, auth, ssrf, authz). Per-class title,
+ * §3 sub-header set, §4 column shape, and §4 section heading are selected by
+ * branching on vulnClass.
+ *
+ * Missing tools surface as placeholder sections, not activity failures.
+ * Required tools (set_findings_summary, set_strategic_intelligence) produce
+ * loud `[Section X: not provided]` placeholders; recommended tools
+ * (set_safe_vectors, set_blind_spots) produce quiet "None identified" prose.
+ */
+
+import type {
+  BlindSpotsInput,
+  FindingsSummaryInput,
+  SafeVectorsInput,
+  StrategicIntelligenceInput,
+  VulnClass,
+  VulnCollectorData,
+} from '../mcp-server/vuln-collector.js';
+import { BLIND_SPOTS_CLASSES } from '../mcp-server/vuln-collector.js';
+
+// ============================================================================
+// PER-CLASS CONSTANTS
+// ============================================================================
+
+const TITLES: Record<VulnClass, string> = {
+  injection: 'Injection Analysis Report',
+  xss: 'Cross-Site Scripting (XSS) Analysis Report',
+  auth: 'Authentication Analysis Report',
+  ssrf: 'SSRF Analysis Report',
+  authz: 'Authorization Analysis Report',
+};
+
+const SECTION_FOUR_HEADING: Record<VulnClass, string> = {
+  injection: '4. Vectors Analyzed and Confirmed Secure',
+  xss: '4. Vectors Analyzed and Confirmed Secure',
+  auth: '4. Secure by Design: Validated Components',
+  ssrf: '4. Secure by Design: Validated Components',
+  authz: '4. Vectors Analyzed and Confirmed Secure',
+};
+
+const STRATEGIC_INTEL_SUBHEADERS: Record<VulnClass, ReadonlyArray<readonly [string, string]>> = {
+  injection: [
+    ['defensive_evasion_waf', 'Defensive Evasion (WAF Analysis)'],
+    ['error_based_potential', 'Error-Based Injection Potential'],
+    ['confirmed_database_technology', 'Confirmed Database Technology'],
+  ],
+  xss: [
+    ['csp_analysis', 'Content Security Policy (CSP) Analysis'],
+    ['cookie_security', 'Cookie Security'],
+  ],
+  auth: [
+    ['authentication_method', 'Authentication Method'],
+    ['session_token_details', 'Session Token Details'],
+    ['password_policy', 'Password Policy'],
+  ],
+  ssrf: [
+    ['http_client_library', 'HTTP Client Library'],
+    ['request_architecture', 'Request Architecture'],
+    ['internal_services', 'Internal Services'],
+  ],
+  authz: [
+    ['session_management_architecture', 'Session Management Architecture'],
+    ['role_permission_model', 'Role/Permission Model'],
+    ['resource_access_patterns', 'Resource Access Patterns'],
+    ['workflow_implementation', 'Workflow Implementation'],
+  ],
+};
+
+// Per-class column shape for §4. The first label is the subject column name
+// (varies by class — "Source" vs "Component/Flow" vs "Endpoint"); the location
+// column name also varies for authz ("Guard Location"); XSS gets an extra
+// "Render Context" column between defense and verdict.
+interface ColumnSpec {
+  readonly subject: string;
+  readonly location: string;
+  readonly includeRenderContext: boolean;
+}
+
+const SECTION_FOUR_COLUMNS: Record<VulnClass, ColumnSpec> = {
+  injection: { subject: 'Source', location: 'Endpoint/File Location', includeRenderContext: false },
+  xss: { subject: 'Source', location: 'Endpoint/File Location', includeRenderContext: true },
+  auth: { subject: 'Component/Flow', location: 'Endpoint/File Location', includeRenderContext: false },
+  ssrf: { subject: 'Component/Flow', location: 'Endpoint/File Location', includeRenderContext: false },
+  authz: { subject: 'Endpoint', location: 'Guard Location', includeRenderContext: false },
+};
+
+// ============================================================================
+// SHARED HELPERS
+// ============================================================================
+
+function placeholder(sectionLabel: string, toolName: string): string {
+  return `_[${sectionLabel}: not provided — \`${toolName}\` was not called]_`;
+}
+
+function escapePipe(value: string): string {
+  return value.replace(/\|/g, '\\|');
+}
+
+function renderTable(headers: readonly string[], rows: readonly (readonly string[])[]): string {
+  const headerRow = `| ${headers.map(escapePipe).join(' | ')} |`;
+  const separator = `| ${headers.map(() => '---').join(' | ')} |`;
+  const body = rows.map((row) => `| ${row.map(escapePipe).join(' | ')} |`).join('\n');
+  return [headerRow, separator, body].filter((line) => line.length > 0).join('\n');
+}
+
+// ============================================================================
+// SECTION RENDERERS
+// ============================================================================
+
+function renderTitle(vulnClass: VulnClass): string {
+  return `# ${TITLES[vulnClass]}`;
+}
+
+function renderExecutiveSummary(summary: FindingsSummaryInput | undefined): string {
+  if (!summary) {
+    return ['## 1. Executive Summary', '', placeholder('Section 1', 'set_findings_summary')].join('\n');
+  }
+  return ['## 1. Executive Summary', '', summary.key_outcome].join('\n');
+}
+
+function renderDominantPatterns(summary: FindingsSummaryInput | undefined): string {
+  if (!summary) {
+    return ['## 2. Dominant Vulnerability Patterns', '', placeholder('Section 2', 'set_findings_summary')].join('\n');
+  }
+  if (summary.patterns.length === 0) {
+    return ['## 2. Dominant Vulnerability Patterns', '', '*No dominant patterns identified.*'].join('\n');
+  }
+  const blocks = summary.patterns.map((p, index) => {
+    const ids = p.representative_finding_ids.map((id) => `\`${id}\``).join(', ');
+    return [
+      `### Pattern ${index + 1}: ${p.name}`,
+      `- **Description:** ${p.description}`,
+      `- **Implication:** ${p.implication}`,
+      `- **Representative Findings:** ${ids}`,
+    ].join('\n');
+  });
+  return ['## 2. Dominant Vulnerability Patterns', '', blocks.join('\n\n')].join('\n');
+}
+
+function renderStrategicIntelligence(vulnClass: VulnClass, intel: StrategicIntelligenceInput | undefined): string {
+  if (!intel) {
+    return [
+      '## 3. Strategic Intelligence for Exploitation',
+      '',
+      placeholder('Section 3', 'set_strategic_intelligence'),
+    ].join('\n');
+  }
+  const subheaders = STRATEGIC_INTEL_SUBHEADERS[vulnClass];
+  const intelRecord = intel as unknown as Record<string, string>;
+  const blocks = subheaders.map(([fieldName, header]) => {
+    const value = intelRecord[fieldName] ?? '*(not provided)*';
+    return [`### ${header}`, value].join('\n');
+  });
+  return ['## 3. Strategic Intelligence for Exploitation', '', blocks.join('\n\n')].join('\n');
+}
+
+function sortSafeVectors(vectors: SafeVectorsInput['vectors']): SafeVectorsInput['vectors'] {
+  return [...vectors].sort((a, b) => {
+    if (a.subject !== b.subject) return a.subject.localeCompare(b.subject);
+    return a.location.localeCompare(b.location);
+  });
+}
+
+function renderSafeVectors(vulnClass: VulnClass, data: SafeVectorsInput | undefined): string {
+  const heading = `## ${SECTION_FOUR_HEADING[vulnClass]}`;
+  if (!data || data.vectors.length === 0) {
+    return [heading, '', '*No vectors confirmed secure during analysis.*'].join('\n');
+  }
+  const cols = SECTION_FOUR_COLUMNS[vulnClass];
+  const headers: string[] = [cols.subject, cols.location, 'Defense Mechanism'];
+  if (cols.includeRenderContext) {
+    headers.push('Render Context');
+  }
+  headers.push('Verdict');
+
+  const sorted = sortSafeVectors(data.vectors);
+  const rows = sorted.map((v) => {
+    const row: string[] = [v.subject, v.location, v.defense_mechanism];
+    if (cols.includeRenderContext) {
+      row.push(v.render_context ?? '');
+    }
+    row.push('SAFE');
+    return row;
+  });
+
+  return [heading, '', renderTable(headers, rows)].join('\n');
+}
+
+function renderBlindSpots(data: BlindSpotsInput | undefined): string {
+  const heading = '## 5. Analysis Constraints and Blind Spots';
+  if (!data || data.items.length === 0) {
+    return [heading, '', '*No analysis constraints or blind spots identified.*'].join('\n');
+  }
+  const blocks = data.items.map((item) => [`### ${item.heading}`, item.description].join('\n'));
+  return [heading, '', blocks.join('\n\n')].join('\n');
+}
+
+// ============================================================================
+// PUBLIC ENTRY POINT
+// ============================================================================
+
+export function renderVulnDeliverable(vulnClass: VulnClass, data: VulnCollectorData): string {
+  const sections: string[] = [
+    renderTitle(vulnClass),
+    '',
+    renderExecutiveSummary(data.findings_summary),
+    '',
+    renderDominantPatterns(data.findings_summary),
+    '',
+    renderStrategicIntelligence(vulnClass, data.strategic_intelligence),
+    '',
+    renderSafeVectors(vulnClass, data.safe_vectors),
+    '',
+  ];
+  if (BLIND_SPOTS_CLASSES.has(vulnClass)) {
+    sections.push(renderBlindSpots(data.blind_spots), '');
+  }
+  return `${sections.join('\n').trimEnd()}\n`;
+}