Campaign execution and recovery

End-to-end sequence

1. Create the engagement. Record an authorization reference, exact targets and URL prefixes, exclusions, dates and testing windows. A plan, repository, listening port, or model cannot expand this scope.
2. Save the assessment plan. Record client, title, type, objectives, authorized and prohibited methods, exact allowedToolNames, data handling, audience, stop conditions, work ownership and model policy.
3. Check runtime readiness. Call getRuntimeStatus. Missing optional tools do not block unrelated methods. A selected tool must have a validated binary and any required operator-reviewed data such as wordlists or Nuclei templates.
4. Run the assessment agent. Call runAgentAssessment with a configured assessment profile. The worker discovers tools/list, reads scope and plan, then selects relevant allowed methods. Every call reaches the locked MCP server. An unresolved start receipt blocks another run; after confirming that the prior process stopped, use reconcileAgentAssessment to record the reviewer and rationale and revoke the old worker scope.
5. Review evidence. Use listEngagementRecords and getEngagementRecord. Verify the scope-gate record, call receipts, command outcome, output digest, target, time and imported worker mapping. The model's final prose is stored separately.
6. Draft the report. Call draftAssessmentReport without a profile for a deterministic inventory or with a separate draft profile. The report agent receives evidence summaries and hashes, not the assessment tool connection.
7. Verify candidates. An analyst inspects source evidence and reproduces a claim where authorized. Failed, denied, timed-out, cancelled or ambiguous actions describe coverage and cannot support a finding.
8. Publish deliberately. publishAgentReport requires reviewer attribution and explicit verified findings with evidence IDs, impact, severity, remediation and verification date. It never promotes candidates automatically.
9. Retest as a new bounded action. Preserve the original observation and remediation claim. Record a new scope/window when required and link the retest evidence.

Tool inventory and selection

Purpose	MCP tools
Scope and plan	createEngagement, getEngagement, listEngagements, closeEngagement, saveAssessmentPlan, getAssessmentPlan
Agents	listAgentProfiles, runAgentAssessment, reconcileAgentAssessment
Discovery and web validation	nmapScan, subfinderEnum, httpxProbe, gobuster, nikto, ffufScan, nucleiScan
Capture and credentials	trafficCapture, hydraBruteforce, generateWordlist, runJohnTheRipper, runHashcat
Local review	privEscAudit, extractionSweep
Runtime and control	getRuntimeStatus, listActiveScans, cancelScan
Evidence	recordResearchActivity, listEngagementRecords, getEngagementRecord
Reports	draftAssessmentReport, listAgentReportDrafts, getAgentReportDraft, publishAgentReport, createClientReport, listClientReports, getClientReport

Codex and Claude CLI assessors discover the complete worker catalog, while the worker rejects names omitted from allowedToolNames. Guarded API assessors are shown only the exact plan names that exist in the worker catalog; a hallucinated name terminates the run before MCP dispatch. Use relevant tools, not every tool. The final model output must list each relevant assessment tool as used with record IDs or skipped with a scope, relevance, safety, readiness or dependency reason.

With hostileModelProtection: true, repeated identical successful assessment calls are denied by both the guarded loop and worker. The option defaults to false so planned retests do not trigger the heuristic. Denied calls are logged before any scanner command. The target/time scope gate remains independent of the tool allowlist. Closing the parent engagement cancels active workers and blocks later tool dispatch.

Campaign and recovery controls

The campaign schema is pentest_mcp_campaign/v1. It bounds iterations, token use, tool output and concurrency. Actions carry unique idempotency keys and transition:

pending -> in_progress -> completed | failed | cancelled | blocked

A restart that finds in_progress marks the action blocked: ambiguous-after-crash. At the assessment boundary, a durable agentAssessmentStarted receipt without a matching completed, failed, or reconciled receipt blocks replay. reconcileAgentAssessment requires explicit stopped-process confirmation, reviewer identity, and rationale; it closes the prior worker engagement when that private worker directory is still available. Completed campaign actions are never replayed. Failed actions stay within their attempt budget. Profile-level duplicate tool suppression is opt in through hostileModelProtection. Four consecutive no-progress observations require strategy reflection.

The report and assessment prompts protect scope, evidence IDs, output digests, stop conditions and unresolved uncertainties when context is compressed. Anything summarized or dropped must be accounted for. The current agent CLI performs its own context management; the server-side evidence ledger remains authoritative.

Guarded API loop

OpenAI-compatible and OpenRouter assessment profiles use a host-owned chat-completions loop. The profile endpoint, model and credential source are fixed before the run. The host sends only plan-approved MCP schemas, verifies the served model ID, bounds iterations and calls, truncates oversized tool results, and stops immediately if the model requests an unadvertised tool. Optional hostileModelProtection adds repeated-call rejection, strict unknown-finish handling, and local token estimates. guardedModelRunStarted, guardedModelTurn, guardedModelToolDenied, and guardedModelRunEnded records preserve the tool-schema and message digests, model identity, protection setting, counters and stop reason. Calls that reach the worker also receive the ordinary MCP start/completion audit receipts and server-side scope checks.

This boundary treats model output as hostile data. It does not isolate the llama.cpp or other model-serving process from the host. Use a dedicated account, container, or VM with no repository, home, evidence, credential-agent, or Docker-socket mounts. The complete deployment and profile guidance is in guarded local and OpenRouter models.

Assessment instruction

The versioned prompt is assessment-campaign-v2 in agent-prompts.ts. It requires:

• MCP inventory discovery and scope/plan readback;
• Pentest MCP as the only assessment interface;
• smallest useful next action and no guessed targets or credentials;
• evidence ID and digest verification;
• a research activity record for meaningful decisions;
• elicitation for missing wordlist and identity inputs;
• duplicate/no-progress handling;
• explicit used/skipped coverage for relevant tools;
• immediate stop on scope, data, impact or authorization conditions;
• JSON output with actions, record IDs, candidate observations, limitations and stop reason.

The prompt is guidance to the model. Exact tool schemas, allowlists, target/time gates, parent-status checks, process bounds and evidence publication gates are enforced by code.