Modules · Visa Vulnerability Agentic Harness (VVAH)

Module: backends

↩ architecture.html · generated 2026-08-14

Module: vvaharness/backends

Role. The phone lines to the AI. A single dispatcher routes each role to one of four transports (cli/sdk/openai/deepagents) behind a neutral, swappable contract.

Size. 36 files · ~5,596 LOC.


flowchart LR IN["Input\nA model request {id, via} + prompt"] --> ACT["Action\nDispatch to the matching transport (cli / sdk / openai / deepagents)"] ACT --> VAL["Validation\nPer-route tool allowlist enforcement (Bash only where explicitly listed)"] VAL --> OUT["Output\nModel response (sandboxed tools)"]

Every AI call in VVAH goes through this layer. A dispatcher looks at each role's via: setting and places the call on the right line: the local claude CLI, the Anthropic SDK, an OpenAI-compatible endpoint, or the DeepAgents runtime used for post-scan agents. Detection tools are sandboxed to read-only file access; only fix mode gets edit tools; validation agents are read-only. Swapping models or providers is a config change, not a code change.

About DeepAgents specifically. The repair crew (Stage 10) and inspection panel (Stage 11) need something the earlier stages don't: an agent that can take several actions in a row, not just answer one question. DeepAgents is the engine that runs that multi-step agent — it decides which AI company (Anthropic or OpenAI) answers each request, keeps a hard limit on how long the agent may keep working, and — the important part — gives the repair crew and the inspection panel different toolbelts. The repair crew can read and edit files (never a shell). The inspection panel can only read; it has no way to change anything even if it wanted to.

Explain-it-simply. A switchboard: each stage dials a number (via:) and the switchboard connects it to the right AI, with the right safety limits.

Data-flow (this module)

flowchart LR ST[stage] -->|prompt/agentic| LLM[llm.py dispatcher] LLM --> CLI[claude_cli.py] LLM --> SDK[sdk.py] LLM --> OAI[oai.py] SDK -->|S10 fix| ASDK[agent_sdk.py] CLI & SDK & OAI --> LT[localtools.py sandbox] REG[harness/registry] --> CLAUDE[harness/claude] REG --> DA[harness/deepagents]

Technical details

flowchart LR IN["Input\nA model request {id, via} + prompt"] --> ACT["Action\nDispatch to the matching transport (cli / sdk / openai / deepagents)"] ACT --> VAL["Validation\nPer-route tool allowlist enforcement (Bash only where explicitly listed)"] VAL --> OUT["Output\nModel response (sandboxed tools)"]

llm.py is the dispatcher (resolve, prompt, agentic) every stage imports. Detection transports: claude_cli.py (~1,050 LOC; subprocess wrapper with guardrails and CLI capability detection), sdk.py (Anthropic SDK; temperature/thinking/caching support), oai.py (OpenAI-compatible; transient-retry, history shrinking). localtools.py implements the sandboxed read-only Read/Glob/Grep jail. agent_sdk.py is the Claude Agent SDK backend for mutating S10 work, with path confinement and redaction hooks. The harness/ sub-package is the post-scan abstraction: base.py (abstract Harness), contract/ (neutral message/option/effort/permission types insulated from any SDK), claude/ (Agent SDK implementation + option translation), and deepagents/ (LangGraph implementation, model builders, read-only middleware, tool mapping). registry.py maps via: → lazy Harness factory. _tls.py centralises TLS coercion.

DeepAgents mechanics, precisely. deepagents/options.py::build_model(model_id, env, provider) is the exact model-vendor router: provider == "anthropic" (or provider unset and "claude" is in model_id) → ChatAnthropic; otherwise → ChatOpenAI. This is what the provider: config key actually controls. deepagents/limits.py::RECURSION_HEADROOM = 900 caps how many extra LangGraph steps a session may take beyond max_turns before its partial state is captured rather than lost. S10's tools exclude Bash explicitly (disallowed_tools=("Bash",)) but include Write/Edit against the real target repo; S11's tools (validation/tools/deep_tools.py) are Read/Glob/Grep plus five deterministic, read-only "fact tools" (DiffTouched, ChangedLines, DiffImpactMap, PatternScan, TestInventory) — no Write/Edit/Bash exists in its toolset at all, a structural guarantee rather than a runtime check. registry.py::_make_deepagents() imports lazily specifically because the deepagents package requires Python ≥ 3.11, so via: cli/via: sdk callers on 3.10 are unaffected. Full detail: LLD §9.

File map (quick scan)

File LOC Purpose
backends/__init__.py 15 —
backends/_tls.py 47 Shared TLS-config coercion for the backend clients.
backends/agent_sdk.py 345 Claude Agent SDK backend for mutating agentic roles (the Remediation Agent's
backends/claude_cli.py 1052 Wrapper around the claude CLI. All model calls go through here.
backends/harness/__init__.py 71 Shared agent-harness abstraction.
backends/harness/base.py 40 Abstract Harness contract every agent runtime must implement.
backends/harness/claude/__init__.py 20 Claude Agent SDK backend for validation harness.
backends/harness/claude/client.py 190 ClaudeHarness: Claude Agent SDK concrete implementation of Harness.
backends/harness/claude/options.py 185 Translate harness option dataclasses into ClaudeAgentOptions.
backends/harness/claude/translate.py 116 SDK message translation: Claude Agent SDK types → HarnessMessage variants.
backends/harness/contract/__init__.py 65 Neutral contract types shared across all backend implementations.
backends/harness/contract/_compat.py 27 StrEnum re-export for the shared harness contract.
backends/harness/contract/effort.py 38 Agent reasoning-effort vocabulary passed through to the SDK.
backends/harness/contract/errors.py 51 Harness-owned exception hierarchy wrapping SDK-specific error classes.
backends/harness/contract/messages.py 114 Harness-owned message types for streaming sessions.
backends/harness/contract/options.py 102 Harness-level options for one-shot and streaming invocations.
backends/harness/contract/permissions/__init__.py 23 Permission gate components for validation sessions.
backends/harness/contract/permissions/_decision.py 29 Immutable result of a permission evaluation.
backends/harness/contract/permissions/_evaluate.py 70 Permission evaluation predicates used by PermissionsPolicy.
backends/harness/contract/permissions/_policy.py 71 PermissionsPolicy dataclass + defaults for the deny-by-default validation gate.
backends/harness/contract/setting_source.py 28 Claude settings-source vocabulary passed through to the SDK.
backends/harness/contract/subagents.py 39 Harness-owned mirror of SDK AgentDefinition, insulated from SDK imports.
backends/harness/contract/tool_policy.py 31 Declarative allowed/denied tool-list policy for harness sessions.
backends/harness/deepagents/__init__.py 37 DeepAgents validation backend (additive alternative to claude_agent_sdk).
backends/harness/deepagents/client.py 117 DeepAgents implementation of the validation Harness contract.
backends/harness/deepagents/limits.py 27 Loop-budget constants for the DeepAgents backend.
backends/harness/deepagents/options.py 575 Translate harness options into DeepAgents / LangGraph configuration.
backends/harness/deepagents/redaction.py 119 Read-only session middleware: redact file content, remove the write tools.
backends/harness/deepagents/tools.py 81 Logical->native tool-name mapping for the DeepAgents backend.
backends/harness/deepagents/translate.py 166 Translate DeepAgents / LangGraph state and messages into HarnessMessage types.
backends/harness/genai.py 22 Shared constants for the deepagents backend.
backends/harness/registry.py 80 Backend registry: maps via strings to lazy Harness factory callables.
backends/llm.py 110 Backend dispatcher. All step files import prompt()/agentic() from HERE,
backends/localtools.py 289 Local, sandboxed implementations of the READ-ONLY Read / Glob / Grep tools
backends/oai.py 623 OpenAI backend. Third via: option alongside cli/sdk — same public surface:
backends/sdk.py 581 Anthropic SDK backend. Mirrors the public surface of backends/claude_cli.py:

Files & functions, explained

Every class and function below has a one-line plain-English note — readable whether you write code or not. _name marks an internal helper.

backends/__init__.py

15 LOC. Utility / support module.

No top-level classes or functions (package init / constants).

backends/_tls.py

47 LOC. Shared TLS-config coercion for the backend clients.

Functions - coerce_verify() — Reads and cleans up the verify value.

backends/agent_sdk.py

345 LOC. Claude Agent SDK backend for mutating agentic roles (the Remediation Agent's

Functions - _resolve_within_root() — (internal helper) checks / decides the within root step. - _within_root() — (internal helper) Provides the “within root” logic. - _sdk_env() — (internal helper) Provides the “AI-model connection environment settings” logic. - _redact_tool_output() — (internal helper) hides sensitive data in the tool output step. - _build_redaction_hooks() — (internal helper) builds / writes the redaction hooks step. - _build_options() — (internal helper) builds / writes the options value. - _run() — (internal helper) runs the run value. - agentic() — Provides the “agentic” logic.

backends/claude_cli.py

1052 LOC. Wrapper around the claude CLI. All model calls go through here.

Classes - GuardrailBlocked — Represents the “GuardrailBlocked” data/behaviour used in this file.

Functions - aborted() — Sets up / maintains the aborted value. - _kill_tree() — (internal helper) sets up / maintains the tree value. - abort() — Sets up / maintains the abort value. - reset_abort() — Sets up / maintains the abort value. - _check_guardrail() — (internal helper) checks / decides the safety block value. - _parse_envelope() — (internal helper) reads and cleans up the wrapper message value. - _find_claude_cmd() — (internal helper) looks up / reads the claude cmd step. - _cli_capabilities() — (internal helper) Provides the “command-line tool capabilities” logic. - _safe_permission_mode() — (internal helper) Provides the “safe permission mode” logic. - _tail() — (internal helper) Provides the “tail” logic. - _short_cmd() — (internal helper) Provides the “short cmd” logic. - _extract_envelope_error() — (internal helper) reads and cleans up the wrapper message error step. - _format_cli_error() — (internal helper) builds / writes the command-line tool error step. - _build_tls_env() — (internal helper) builds / writes the secure connection environment settings step. - configure() — Sets up / maintains the configure value. - _run() — (internal helper) runs the run value. - _run_streaming() — (internal helper) runs the streaming value. - stream_trace() — Provides the “stream trace” logic. - _is_pending_result() — (internal helper) checks / decides the pending result step. - _terminal_result_fields() — (internal helper) Provides the “terminal result fields” logic. - _is_transient_failure() — (internal helper) checks / decides the transient failure step. - _run_with_retry() — (internal helper) runs the with retry step. - prompt() — Provides the “prompt” logic. - agentic() — Provides the “agentic” logic. - parse_json_response() — Reads and cleans up the data file response step.

backends/harness/__init__.py

71 LOC. Shared agent-harness abstraction.

No top-level classes or functions (package init / constants).

backends/harness/base.py

40 LOC. Abstract Harness contract every agent runtime must implement.

Classes - Harness — Represents the “Harness” data/behaviour used in this file. - run_oneshot() — Runs the oneshot value. - run_streaming() — Runs the streaming value.

backends/harness/claude/__init__.py

20 LOC. Claude Agent SDK backend for validation harness.

No top-level classes or functions (package init / constants).

backends/harness/claude/client.py

190 LOC. ClaudeHarness: Claude Agent SDK concrete implementation of Harness.

Classes - ClaudeHarness — Represents the “ClaudeHarness” data/behaviour used in this file. - run_oneshot() — Runs the oneshot value. - run_streaming() — Runs the streaming value.

Functions - _extract_sdk_persona_reports() — (internal helper) reads and cleans up the AI-model connection AI reviewer reports step. - _wrap_sdk_error() — (internal helper) Provides the “wrap AI-model connection error” logic.

backends/harness/claude/options.py

185 LOC. Translate harness option dataclasses into ClaudeAgentOptions.

Functions - _to_effort() — (internal helper) Provides the “to effort” logic. - _to_setting_sources() — (internal helper) Provides the “to setting untrusted input points” logic. - _permissions_callback() — (internal helper) Provides the “permissions callback” logic. - _to_agent_definition() — (internal helper) Provides the “to agent definition” logic. - _build_output_format() — (internal helper) builds / writes the output format step. - _sanitize_schema() — (internal helper) hides sensitive data in the schema value. - _resolve_output_schema() — (internal helper) checks / decides the output schema step. - _base_opts() — (internal helper) Provides the “base opts” logic. - _apply_agents() — (internal helper) runs the agents value. - build_oneshot_sdk_options() — Builds / writes the oneshot AI-model connection options step. - build_streaming_sdk_options() — Builds / writes the streaming AI-model connection options step.

backends/harness/claude/translate.py

116 LOC. SDK message translation: Claude Agent SDK types → HarnessMessage variants.

Functions - translate_init() — Reads and cleans up the init value. - translate_assistant() — Reads and cleans up the assistant value. - translate_tool_result() — Reads and cleans up the tool result step. - translate_result() — Reads and cleans up the result value. - _translate_system() — (internal helper) reads and cleans up the system value. - _translate_user() — (internal helper) reads and cleans up the user value. - translate() — Reads and cleans up the translate value.

backends/harness/contract/__init__.py

65 LOC. Neutral contract types shared across all backend implementations.

No top-level classes or functions (package init / constants).

backends/harness/contract/_compat.py

27 LOC. StrEnum re-export for the shared harness contract.

No top-level classes or functions (package init / constants).

backends/harness/contract/effort.py

38 LOC. Agent reasoning-effort vocabulary passed through to the SDK.

Classes - EffortLevel — Represents the “EffortLevel” data/behaviour used in this file. - parse() — Reads and cleans up the parse value.

backends/harness/contract/errors.py

51 LOC. Harness-owned exception hierarchy wrapping SDK-specific error classes.

Classes - HarnessError — Represents the “HarnessError” data/behaviour used in this file. - HarnessCLINotFoundError — Represents the “HarnessCLINotFoundError” data/behaviour used in this file. - HarnessConnectionError — Represents the “HarnessConnectionError” data/behaviour used in this file. - HarnessProcessError — Represents the “HarnessProcessError” data/behaviour used in this file. - HarnessJSONDecodeError — Represents the “HarnessJSONDecodeError” data/behaviour used in this file. - HarnessMessageParseError — Represents the “HarnessMessageParseError” data/behaviour used in this file.

backends/harness/contract/messages.py

114 LOC. Harness-owned message types for streaming sessions.

Classes - HarnessSessionInit — Represents the “HarnessSessionInit” data/behaviour used in this file. - HarnessAssistantText — Represents the “HarnessAssistantText” data/behaviour used in this file. - HarnessToolUse — Represents the “HarnessToolUse” data/behaviour used in this file. - HarnessToolResult — Represents the “HarnessToolResult” data/behaviour used in this file. - HarnessResult — Represents the “HarnessResult” data/behaviour used in this file. - OneShotResult — Represents the “OneShotResult” data/behaviour used in this file.

backends/harness/contract/options.py

102 LOC. Harness-level options for one-shot and streaming invocations.

Classes - OneShotOptions — Represents the “OneShotOptions” data/behaviour used in this file. - StreamingOptions — Represents the “StreamingOptions” data/behaviour used in this file.

backends/harness/contract/permissions/__init__.py

23 LOC. Permission gate components for validation sessions.

No top-level classes or functions (package init / constants).

backends/harness/contract/permissions/_decision.py

29 LOC. Immutable result of a permission evaluation.

Classes - PermissionDecision — Represents the “PermissionDecision” data/behaviour used in this file.

backends/harness/contract/permissions/_evaluate.py

70 LOC. Permission evaluation predicates used by PermissionsPolicy.

Functions - _resolve_write_path() — (internal helper) checks / decides the write path step. - _under_target() — (internal helper) Provides the “under target” logic. - evaluate_write() — Provides the “evaluate write” logic.

backends/harness/contract/permissions/_policy.py

71 LOC. PermissionsPolicy dataclass + defaults for the deny-by-default validation gate.

Classes - PermissionsPolicy — Represents the “PermissionsPolicy” data/behaviour used in this file. - _evaluate_simple() — (internal helper) Provides the “evaluate simple” logic. - evaluate() — Provides the “evaluate” logic.

backends/harness/contract/setting_source.py

28 LOC. Claude settings-source vocabulary passed through to the SDK.

Classes - SettingSource — Represents the “SettingSource” data/behaviour used in this file.

backends/harness/contract/subagents.py

39 LOC. Harness-owned mirror of SDK AgentDefinition, insulated from SDK imports.

Classes - SubagentDefinition — Represents the “SubagentDefinition” data/behaviour used in this file.

backends/harness/contract/tool_policy.py

31 LOC. Declarative allowed/denied tool-list policy for harness sessions.

Classes - ToolPolicy — Represents the “ToolPolicy” data/behaviour used in this file.

backends/harness/deepagents/__init__.py

37 LOC. DeepAgents validation backend (additive alternative to claude_agent_sdk).

Functions - __getattr__() — Python built-in method (__getattr__).

backends/harness/deepagents/client.py

117 LOC. DeepAgents implementation of the validation Harness contract.

Classes - DeepAgentHarness — Represents the “DeepAgentHarness” data/behaviour used in this file. - run_oneshot() — Runs the oneshot value. - run_streaming() — Runs the streaming value.

Functions - _safe_get_snapshot() — (internal helper) Provides the “safe get snapshot” logic.

backends/harness/deepagents/limits.py

27 LOC. Loop-budget constants for the DeepAgents backend.

No top-level classes or functions (package init / constants).

backends/harness/deepagents/options.py

575 LOC. Translate harness options into DeepAgents / LangGraph configuration.

Classes - _ModelKey — (internal) Represents the “ModelKey” data/behaviour used in this file. - __eq__() — Python built-in method (__eq__). - __hash__() — Python built-in method (__hash__). - _RecursionCounter — (internal) Represents the “RecursionCounter” data/behaviour used in this file. - next() — Provides the “next” logic.

Functions - _anthropic_key() — (internal helper) Provides the “anthropic key” logic. - _anthropic_base() — (internal helper) Provides the “anthropic base” logic. - _openai_key() — (internal helper) Provides the “openai key” logic. - _openai_base() — (internal helper) Provides the “openai base” logic. - _openai_ssl_context() — (internal helper) Provides the “openai secure connection context” logic. - _openai_http_client() — (internal helper) Provides the “openai http client” logic. - _openai_http_async_client() — (internal helper) Provides the “openai http async client” logic. - build_model() — Builds / writes the model value. - build_model_cached() — Builds / writes the model cached step. - _tool_policy() — (internal helper) Provides the “tool rules” logic. - _build_session_tools() — (internal helper) builds / writes the session tools step. - _subagent_tools() — (internal helper) Provides the “helper AI reviewer tools” logic. - _subagent_tool_names() — (internal helper) Provides the “helper AI reviewer tool names” logic. - get_subagent_specs() — Looks up / reads the helper AI reviewer specs step. - _filesystem_permissions() — (internal helper) Provides the “filesystem permissions” logic. - _session_backend() — (internal helper) Provides the “session backend” logic. - _skill_sources() — (internal helper) Provides the “skill untrusted input points” logic. - _make_config() — (internal helper) builds / writes the config value. - _create_agent() — (internal helper) builds / writes the agent value. - build_subagents() — Builds / writes the helper AI reviewers value. - _pydantic_response_format() — (internal helper) Provides the “pydantic response format” logic. - _strategy_for() — (internal helper) Provides the “strategy for” logic. - _response_format() — (internal helper) Provides the “response format” logic. - _build_streaming_graph() — (internal helper) builds / writes the streaming code relationship map step. - build_streaming_agent() — Builds / writes the streaming agent step. - _oneshot_response_format() — (internal helper) Provides the “oneshot response format” logic. - _build_oneshot_graph() — (internal helper) builds / writes the oneshot code relationship map step. - build_oneshot_options() — Builds / writes the oneshot options step.

backends/harness/deepagents/redaction.py

119 LOC. Read-only session middleware: redact file content, remove the write tools.

Classes - RedactToolResults — Represents the “RedactToolResults” data/behaviour used in this file. - wrap_tool_call() — Provides the “wrap tool call” logic. - awrap_tool_call() — Provides the “awrap tool call” logic. - ExcludeTools — Represents the “ExcludeTools” data/behaviour used in this file. - _filter() — (internal helper) checks / decides the filter value. - wrap_model_call() — Provides the “wrap model call” logic. - awrap_model_call() — Provides the “awrap model call” logic.

Functions - _redact_message() — (internal helper) hides sensitive data in the message value. - _tool_name() — (internal helper) Provides the “tool name” logic. - read_only_middleware() — Looks up / reads the only middleware step.

backends/harness/deepagents/tools.py

81 LOC. Logical->native tool-name mapping for the DeepAgents backend.

Functions - _allowed_tool_names() — (internal helper) Provides the “allowed tool names” logic. - native_tool_names() — Provides the “native tool names” logic. - build_tools() — Builds / writes the tools value.

backends/harness/deepagents/translate.py

166 LOC. Translate DeepAgents / LangGraph state and messages into HarnessMessage types.

Functions - _extract_text() — (internal helper) reads and cleans up the text value. - _tool_calls() — (internal helper) Provides the “tool calls” logic. - translate_final_state() — Reads and cleans up the final state step. - _messages_from_event() — (internal helper) Provides the “messages from event” logic. - translate_stream_events() — Reads and cleans up the stream events step. - make_terminal_result() — Builds / writes the terminal result step.

backends/harness/genai.py

22 LOC. Shared constants for the deepagents backend.

No top-level classes or functions (package init / constants).

backends/harness/registry.py

80 LOC. Backend registry: maps via strings to lazy Harness factory callables.

Functions - _make_claude() — (internal helper) builds / writes the claude value. - _make_deepagents() — (internal helper) builds / writes the deepagents value. - get_harness() — Looks up / reads the harness value.

backends/llm.py

110 LOC. Backend dispatcher. All step files import prompt()/agentic() from HERE,

Functions - resolve() — Checks / decides the resolve value. - prompt() — Provides the “prompt” logic. - agentic() — Provides the “agentic” logic.

backends/localtools.py

289 LOC. Local, sandboxed implementations of the READ-ONLY Read / Glob / Grep tools

Functions - _jail() — (internal helper) Provides the “jail” logic. - _read() — (internal helper) looks up / reads the read value. - _glob() — (internal helper) Provides the “file pattern” logic. - _grep() — (internal helper) Provides the “text search” logic. - schemas_for() — Provides the “schemas for” logic. - anthropic_schemas_for() — Provides the “anthropic schemas for” logic. - supported() — Provides the “supported” logic. - execute() — Runs the execute value.

backends/oai.py

623 LOC. OpenAI backend. Third via: option alongside cli/sdk — same public surface:

Functions - _summarise_status_error() — (internal helper) Provides the “summarise status error” logic. - _scrub_secrets() — (internal helper) hides sensitive data in the secrets value. - _cause_chain() — (internal helper) Provides the “cause chain” logic. - configure() — Sets up / maintains the configure value. - _get_client() — (internal helper) looks up / reads the client value. - _is_transient_status() — (internal helper) checks / decides the transient status step. - prompt() — Provides the “prompt” logic. - _record_usage() — (internal helper) Provides the “record usage” logic. - _cap_tool_result() — (internal helper) checks / decides the tool result step. - _shrink_history() — (internal helper) Provides the “shrink history” logic. - agentic() — Provides the “agentic” logic. - _summ() — (internal helper) Provides the “summ” logic.

backends/sdk.py

581 LOC. Anthropic SDK backend. Mirrors the public surface of backends/claude_cli.py:

Functions - configure() — Sets up / maintains the configure value. - _get_client() — (internal helper) looks up / reads the client value. - _supports_temperature() — (internal helper) checks / decides the temperature value. - _is_transient_sdk() — (internal helper) checks / decides the transient AI-model connection step. - prompt() — Provides the “prompt” logic. - _assistant_blocks() — (internal helper) Provides the “assistant blocks” logic. - _with_cache_marker() — (internal helper) Provides the “with cache marker” logic. - _summ() — (internal helper) Provides the “summ” logic. - agentic() — Provides the “agentic” logic.


See also: HLD · LLD · Data Flow · module index.