RFC: Delegated-agent handoff contract for cross-system coding tasks

## Primary area

** Cross-cutting / multiple

## Related issue or feature request

_None yet. Complements roadmap **EventBridge / SNS integration** and channel webhooks._

## Summary

Define a stable **handoff payload** and API surface so an external specialist system (incident response, security triage, planning agent) can delegate a coding task to ABCA with high-fidelity context—not a bare issue title. ABCA becomes the delegated coder in a multi-agent ecosystem without absorbing every adjacent domain.

## Use case and motivation

Operators increasingly deploy **several agents** with narrow surfaces. A specialist agent may diagnose a production issue or approve a change plan but should not reimplement CI, git, and PR workflows. Today, webhook create-task accepts a description string; that is insufficient for investigations with evidence, citations, and file pointers. Handoffs must be **high-fidelity** (investigation state, not “please fix this bug”) and respect clear **agent boundaries**—specialist systems delegate coding, they do not reimplement CI/git. A handoff contract reduces re-prompting and context loss at system boundaries.

## Proposal

### Handoff payload (v1 sketch)

JSON document referenced by `POST /tasks` or a dedicated `POST /tasks/delegated`:

- `handoff_id`, `source_system`, `source_principal`
- `intent_summary` (short)
- `evidence[]` — `{ type, uri, excerpt, confidence }`
- `constraints[]` — branches, paths allow/deny, max scope
- `callback` — optional webhook URL for terminal events
- `attachments` — reuse existing attachment schema

### UX before / after

**Before:** External system posts a paragraph; ABCA agent rediscovers context from scratch.

**After:** External system posts a validated handoff document; hydration renders an **Evidence** section; agent starts with cited artifacts; terminal state optionally notifies the source callback.

### Implementation phases

1. Schema + validation in `types.ts` / OpenAPI mirror.
2. Hydration renderer for evidence blocks (`Untrusted hydration content boundaries`).
3. Optional HMAC auth for `source_system` webhooks.
4. Docs: “Integrating as a delegated coding agent.”

## Out of scope

- Building or hosting specialist agents.
- Bidirectional live session sharing (see separate operator-session draft if pursued).
- Auto-merge on behalf of the source system.

## Potential challenges

- Payload size vs. token budget; need truncation strategy with preserved citations.
- Trust: evidence URIs must pass SSRF and Guardrail screening.
- Versioning: handoff schema must evolve without breaking webhook consumers.

## Dependencies and integrations

- `webhook-create-task`, `context-hydration.ts`, `INPUT_GATEWAY.md`
- Optional EventBridge envelope wrapping the same schema

## Alternative solutions

- **Fat markdown in `task_description` only** — simple but unstructured, hard to validate.
- **S3 object reference** — good for large payloads; add in v2 if v1 JSON proves tight.

---

**Note:** Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.

* RFC PR:
* Approved by:
* Reviewed by:

Start by reading the existing webhook-create-task entry point, types.ts, context-hydration.ts, and INPUT_GATEWAY.md to understand current task, attachment, and hydration contracts. Compare those surfaces with the proposed payload, validation, authentication, and callback phases. Done means the v1 contract and implementation scope are agreed and documented, with compatibility and security decisions resolved.

Written by the indexing model from the issue text.