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.
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)
Technical details
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"(orproviderunset and"claude"is inmodel_id) →ChatAnthropic; otherwise →ChatOpenAI. This is what theprovider:config key actually controls.deepagents/limits.py::RECURSION_HEADROOM = 900caps how many extra LangGraph steps a session may take beyondmax_turnsbefore its partial state is captured rather than lost. S10's tools excludeBashexplicitly (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 thedeepagentspackage requires Python ≥ 3.11, sovia: cli/via: sdkcallers 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.