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. Every command that runs models — run, daemon, gate, setup, status, models, check-models — emits a warning when it loads such a block, not only setup, because these files are hand-edited.

Provenance

code is what the server records and what reports group by. agent and model_id are local: which CLI actually ran. One enabled code points at one agent at a time. A second concurrent agent needs a second enabled code.

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, and cweCodes. Bug reports can include reproductionSteps, expectedBehavior, actualBehavior, rootCause, and testSuggestion. The server normalizes aliases and computes identity.

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",
  "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"
}

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.