Agent Integration

Any external Agent or CLI can use the harness as a local evidence boundary. The harness is vendor-neutral: it does not import an Agent SDK, host a model, require a model provider, or embed an LLM. Agent identity is descriptive provenance, not authorization.

Integration sequence

1. Call smcub capture-run with an offline command or the toy preset plus --agent-name, optional --agent-version, and --agent-interface.
2. Read the returned run directory and validate its run_envelope.json with smcub validate-envelope.
3. Add delayed D1/D3 outcome data from a local source and build a frozen pack with smcub build-evidence-pack.
4. Verify integrity and recomputed results with smcub replay-evidence-pack.
5. Present eligible evidence to a human. Do not promote a challenger or mutate core rules automatically.

See the Run Envelope schema and Evidence Pack schema for machine-readable contracts.

Permission scope

The Run Envelope records the caller's intended scope as a declarative policy:

Capability	Allowed value
Network	false
Broker access	false
Account mutation	false
Order / cancel / trade	false
Embedded LLM	false
Writes	run_directory_only
Enforcement	declarative
Verified	false

These fields are provenance, not a sandbox attestation. capture-run does not isolate or inspect an arbitrary subprocess deeply enough to prove network, broker, account, or filesystem compliance. Its --sandbox option only selects the tmp/sandbox output namespace. Put untrusted commands inside an OS/container sandbox and record that separately; the harness deliberately reports its own policy as unverified.

Do not interpret access to local notes, screenshots, or exported data as permission to act. Public examples must remain toy-only and must not contain private watchlists, account identifiers, credentials, cookies, personal trading records, or local absolute paths.

Output evidence

Each tool call records its name, timestamps, return code, timeout flag, attempt number, reconciled success/failure status, and relative paths to stdout, stderr, and metadata. output_evidence lists those paths. The harness hashes frozen Evidence Pack artifacts and replay recomputes validation, evaluation, metrics, and failure counts instead of trusting the external Agent's claims. It also writes evidence_pack.sha256 over the exact manifest bytes. This is local tamper evidence, not an authenticated signature; replay fails closed to pending_review when the seal or manifest contract is invalid.

An Agent may summarize or challenge this evidence. It must not rewrite frozen evidence, convert ALERT or another action_label into an instruction, or claim that review eligibility equals promotion.

Failure handling

Context	Status	Required caller behavior
Run Envelope	completed	Continue to evidence construction when delayed outcome data is available.
Run Envelope	pending_review	Surface one or more tool failures; do not silently continue.
Run Envelope	blocked	Stop the workflow after three or more trailing failures.
Evidence Pack	challenger	Preserve as a proposal; metrics do not meet the human-review gate.
Evidence Pack	ready_for_review	Present to a human; do not mutate the registry.
Evidence Pack	pending_review	Surface failed samples or inconsistencies.
Evidence Pack	blocked	Stop after three or more trailing sample failures.
Replay report	verified	Integrity and deterministic recomputation passed.
Replay report	pending_review / blocked	Surface hash/result mismatches or failures and do not promote.

These are workflow statuses, not trading action labels.

Optional external adapters

Optional TradingAgents reports may enter this flow as user-configured external LLM analysis artifacts. The adapter is outside the trusted core: credentials stay outside this repository, network/model access requires explicit acknowledgement, and imported output remains review evidence only. It cannot place or cancel orders, mutate accounts, promote rules, or bypass the Run Envelope and human review gates. See the adapter boundary and the integration matrix.

Agent responsibilities

• Preserve invalidation, time stop, give-up conditions, source availability, and data quality for every non-silent observation.
• Treat available_at > decision_time as a validation failure.
• Generate opposing-evidence questions before strengthening a thesis.
• Keep challenger-to-champion promotion behind explicit human confirmation.
• Preserve the safety declaration on applicable artifacts and outputs:

READ_ONLY_NO_ORDER_NO_CANCEL_NO_TRADE