Runner contract

A runner is a command thespider-agent runs with sh -c in the checkout. It gets a prompt file and must write findings on stdout. The agent posts the raw output; the server parses it.

Command binding

A [[model]] block names the MODEL (code) and the AGENT that runs it (agent). Agent-bound names one of the four built-in CLIs and lets TheSpider render the command:

[[model]]
code  = "xai/grok-4.6"
agent = "grok"
timeout_seconds = 1200

Freeform supplies the shell command directly, with or without an agent label. Any agent TheSpider cannot render requires this form:

[[model]]
code    = "MODEL_CODE"
agent   = "pi"                  # optional label; required to be paired with `command`
command = "COMMAND {prompt_path} {target_path} {model_code} {slice_id}"
timeout_seconds = 900

The containing .thespider/config.toml also stores project and profile. The profile selects the campaign methodology; model command bindings remain project-wide.

Supported template variables are {prompt_path}, {target_path}, {model_code}, and {slice_id}. Values are shell-quoted. Unknown identifier-shaped variables fail substitution. The legacy standalone variables {thespider_dir} and {workspace_path} are not supported.

Validity

Precedence

When a block carries both agent and command, command always wins. The agent value is then used only to identify which CLI to probe for auth status, never to render a command. The combination is valid, so no command warns about it: setup prints it as a note, and status, models and check-models show it as the binding's own state: a custom command, with the agent probed only for install and login. THESPIDER_VERBOSE=1 also prints the note on run, daemon, gate, refine, status and models. An effort on such a block is declared, not applied: it still decides which participant's slices the binding claims, but TheSpider does not add it to the command. Put the effort flag in command yourself. check-models and setup show it as effort xhigh (declared; command not checked).

Provenance

code is what the server records. agent and model_id are local: which CLI actually ran. effort is the half of the participant the server records. A built-in agent with no command also runs with it; beside a command, or on any other agent, it is only declared, and the command must set the effort itself.

code can be a lab's own models.dev alias, such as deepseek/deepseek-flash. The server records the alias code. The catalog's alias_of (deepseek/deepseek-v4.1-flash) is advisory: TheSpider can't verify which model the vendor routes an alias to, so its slices and reports stay under the alias and are never moved to its target. Findings dedupe across models as usual.

Participants

A participant is a model code at one effort, (code, effort). A project enables participants, a campaign plans one slice per pass, bucket and enabled participant, and each slice is claimed only by a binding at that participant's effort. So anthropic/claude-opus-5-5 bound twice, once with effort = "low" and once with effort = "xhigh", audits every slice twice, and reports, the model dashboard and finding reports keep the two apart. Both pairs get the same prompt, apart from the slice id.

• A binding with no effort (and no OpenCode variant) is the default participant: the runner's own default effort. TheSpider never claims it ran at any particular level.
• The effort is what the binding was configured with. TheSpider does not verify what the provider actually ran.
• Effort is never folded into code. The code is still the models.dev code, and the same string groups every effort of a model.
• A server without effort participants (no model_effort in server_capabilities on GET /v1/me) only knows default participants. Against one, the agent claims with its bindings that have no effort, warns about the others, and refuses setup --effort.
• An agent before 0.8.0 ignores a lone effort key, so it runs that binding at the default effort and claims only default slices, which is safe. Two blocks with one code are a parse error before 0.8.0, so upgrade every runner that shares the config before you add a second effort of a code.
• From 0.8.0, an OpenCode variant is the effort, so a block that sets variant claims the participant code@variant, not the default one it claimed before. Enable that pair or remove variant when you upgrade (upgrade note).
• Each participant has one binding in a config, so it runs through one agent at a time. A second concurrent agent needs a second enabled participant: another code, or the same code at another effort. The second one is audited separately at its own effort, and its slices are billed on their own.

Process contract

• Working directory: target checkout root.
• Shell: sh -c.
• Stdin: closed.
• Stdout: captured in full unless --redact is enabled.
• Stderr: captured; only the final 4,000 characters are submitted.
• Timeout: the agent stops the child process and reports timeout with no exit code.
• Source tree: read locally by the runner; TheSpider does not upload it.

Because stdin is closed, every command must reach the prompt through the {prompt_path} file rather than expecting it on standard input. Each built-in agent template does this itself: Grok reads it with --prompt-file, Claude and Codex use a shell redirect from {prompt_path}, and OpenCode attaches it with -f after the positional instruction (OpenCode's -f is variadic).

The first-party agent itself exits 0 when every submitted result is valid coverage and 1 when one or more slices fail. A model process's nonzero exit is included in the result payload and stored as an artifact, but it is not valid coverage. The server still attempts to parse the marker so the warning is useful; the slice stays retryable.

Marker protocol

The claim response contains marker, and the rendered prompt states the corresponding output schema. The default marker is THESPIDER_FINDINGS_JSON.

A valid result block has this shape:

<THESPIDER_FINDINGS_JSON>
[
  {
    "title": "Concrete issue title",
    "severity": "high",
    "categories": ["authz"],
    "files": [{ "path": "src/http.ts", "line": 42 }],
    "evidence": "Exact evidence",
    "impact": "User-visible or security consequence",
    "recommendation": "Specific remediation"
  }
]
</THESPIDER_FINDINGS_JSON>

Rules:

1. Use the marker from the prompt; do not hardcode the default when custom methodologies can change it.
2. Include both opening and closing tags.
3. The first non-whitespace character after the opening tag must be [.
4. The enclosed value must be valid JSON.
5. Write an empty array when there are no findings.
6. Text outside the block is retained in the raw output artifact but is not a finding.

Security reports can include confidence, exploitScenario, cvssV4Score, cvssV4Vector, cweCodes, and evidenceBasis. Bug reports can include reproductionSteps, expectedBehavior, actualBehavior, rootCause, and testSuggestion. The server normalizes aliases and computes identity.

Hygiene and Pipeline reports carry two profile fields each. The model writes camelCase (snake_case is also accepted); finding reads return the snake_case key, and only for reports of that profile:

For Hygiene, recommendation is the removal plan and impact the cost of keeping the item. For Pipeline, impact is the structural saving (never minutes) and recommendation the change plus what preserves coverage. Neither profile emits exploitScenario, cweCodes or CVSS.

evidenceBasis (also accepted as evidence_basis) is optional: "demonstrated" when the cited evidence shows the problem concretely (an exploit or failure path for Security and Bugs, an item proven unused or stale for Hygiene, avoidable work visible in the pipeline files for Pipeline), "speculative" for a hardening observation, a removal that could not be fully confirmed, or a cost that depends on runtime behaviour. Any other value is ignored. It never changes a finding's identity. severity is matched case-insensitively against critical, high, medium (also moderate, med), low, info (also informational, information, note) and crit; anything else counts as no severity.

Truncation and size limits

The result block should appear well before these limits. A truncation that removes the closing marker prevents parsing.

Claim and result fields

The host receives:

{
  "lease_id": 9001,
  "slice_id": 501,
  "model_code": "anthropic/claude-sonnet-5",
  "effort": null,
  "pass_code": "http",
  "bucket_code": "auth",
  "prompt": "FULL_RENDERED_PROMPT",
  "prompt_hash": "SHA256_HEX",
  "marker": "THESPIDER_FINDINGS_JSON",
  "timeout_seconds": 900,
  "lease_expires_at": "2026-07-22T12:00:00Z"
}

The host submits:

{
  "exit_code": 0,
  "duration_ms": 18422,
  "model_code": "anthropic/claude-sonnet-5",
  "client_version": "thespider-agent/0.1.0",
  "prompt_hash": "SHA256_HEX_FROM_CLAIM",
  "stdout": "RAW_STDOUT",
  "stderr_tail": "TAIL"
}

effort is the slice's participant effort (null for the default participant). The agent runs the lease with the binding of exactly that (model_code, effort) and never falls back to another effort of the same code; with no such binding the lease fails as an unbound code does. The result carries no effort: attribution comes from the slice.

prompt_hash protects prompt integrity. The result endpoint is idempotent on (lease_id, prompt_hash).

Submission dispositions

An artifact can be received successfully while the audit execution fails. accepted means valid coverage, not merely that the POST arrived.

Repair historic invalid completions with thespider-agent repair --campaign ID. --dry-run lists valid / invalid / unverified without changing anything.

See custom runners for setup and external agents for implementing the lease protocol.