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:

Inizia leggendo l’entry point webhook-create-task esistente, types.ts, context-hydration.ts e INPUT_GATEWAY.md per comprendere i contratti attuali relativi a task, allegati e hydration. Confronta queste superfici con le fasi proposte per payload, validazione, autenticazione e callback. Il lavoro è completato quando il contratto v1 e l’ambito dell’implementazione sono concordati e documentati, e le decisioni relative a compatibilità e sicurezza sono state risolte.

Scritto dal modello di indicizzazione a partire dal testo della issue.