Runner contract

A runner is a command executed by thespider-agent with sh -c in the target checkout. The agent supplies a rendered prompt file and submits the process's raw output to the server.

Command binding

[[model]]
code = "MODEL_CODE"
command = "COMMAND {prompt_path} {target_path} {model_code} {slice_id}"
timeout_seconds = 900

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.

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.

The first-party agent itself exits 0 when no slices fail submission and 1 when one or more slices fail. A model process's nonzero exit code is included in the result payload; the server still stores output and attempts to parse reports.

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": "sonnet",
  "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": "sonnet",
  "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

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