[Extension Proposal]: Learnables — declaring what an agent can be taught

### Summary

An opt-in extension that lets an agent declare **what it can be taught**, and defines what happens to a human's answer after the task that prompted it ends.

A2A specifies the moment an agent cannot decide: the task moves to `input-required`, a human answers, the task resumes. It does not specify the moment after. The answer was evidence about the world, and the protocol gives it nowhere to go — so the same question is asked again on the next task.

The extension adds four things, none of which change the meaning of a core request:

1. **Declaration** — the agent publishes a learnable surface in `capabilities.extensions[].params`: what it recognises, how it decides *today*, and the shape of a valid answer (`lessonFields`).
2. **Teach block** — when the agent asks a question, it MAY attach a teachable proposal in the question Message's `metadata`, keyed by the extension URI, so a client can offer "remember this" without knowing the agent's internals.
3. **Absorption semantics** — a lesson is judged by the learnable being taught, is idempotent, and produces a new immutable version carrying an author and a reason. A task already running stays pinned to the version it started on.
4. **Show-back** — a read-only re-evaluation of the same input under the current definition, so a person sees what the agent now makes of it rather than the word "saved".

Extension URI: `https://rsaxb.com/a2a/learnables/v1`
Specification: https://www.rsaxb.com/a2a/learnables/v1 (machine-readable descriptor and JSON Schema at `/extension.json`)

### Motivation

Without something in this shape, implementations resolve the after-the-answer moment in one of three ways, all of which are in production somewhere:

- **Discard it.** The agent is exactly as ignorant on the next task.
- **Write it into a prompt or config and redeploy.** The knowledge reaches production days after the person who held it answered, through a process that person cannot initiate.
- **Let the agent self-modify.** Fast and unauditable: nobody can say what the agent knew when it made a given decision, and nothing can be reversed.

This cannot be done in core, and we are not asking for it to be. It requires an agent to publish a vocabulary specific to its own domain (`lessonFields` for one agent are patterns; for another, spreadsheet column mappings), which is exactly the kind of thing the extension mechanism exists for. It is also opt-in by construction: `required` is fixed at `false`, and a client that ignores the extension sees one extra entry in `capabilities.extensions` and one extra key in a question's `metadata`.

### Design, in brief

Declaration on the Agent Card:

```json
{
"uri": "https://rsaxb.com/a2a/learnables/v1",
"required": false,
"params": {
"learnables": [{
"collection": "customers",
"entry": "customer",
"teaches": "which customer a message belongs to",
"how": "Each customer carries marks - text that gives them away. Every mark that matches scores; the highest score wins if it clears the identification margin.",
"decidedBy": "rules",
"lessonFields": [
{ "name": "pattern", "label": "Text that gives it away", "kind": "text" },
{ "name": "where", "label": "Where to look for it", "kind": "choice",
"choices": ["from", "subject", "body", "attachments", "any"], "default": "from" }
]
}]
}
}
```

Three requirements are load-bearing, and are the parts we would most like argued with:

**A client MUST render an unrecognised `kind` as `"text"`, and MUST NOT drop the field.** This is what makes a client generic. A client rendering blind from `lessonFields` needs no change when an agent that reads spreadsheets asks to be taught a column instead of a pattern.

**The lesson `value` MUST be opaque to every party except the learnable being taught.** No transport, authority, or storage layer may read a named key out of it. The moment one of them reads `value.pattern`, adding a learnable that is not about text requires a coordinated release of every component in the chain.

**A lesson MUST produce a new immutable version and MUST NOT mutate one in place**, and a task running against version *n* MUST complete against version *n*. Without pinning, "the agent learns" and "the agent changes unpredictably under a running task" describe the same behaviour.

One concrete case for why suggestion scope is normative rather than cosmetic: our reference implementation's suggestion engine looked at a shipment reference `PA-2026-0901` and offered to remember `PA-2026`. Confirming that would have taught the directory to claim every reference issued that year. The person ticking the box is doing another job and trusts the prefill, which makes the scope of a suggestion a correctness property. §8 therefore requires that a suggested value MUST NOT be wider in scope than the evidence it was drawn from.

### Relationship to existing issues

- **#958 (feedback / agent rewards)** is the nearest neighbour and is solving a different problem. That issue is about returning reward signals as training data for a model with learnable weights. This proposal is about a deterministic, human-authored, versioned change to what an agent knows, attributable to a named person and reversible. The two compose rather than compete: `decidedBy` (`rules` | `model` | `hybrid`) exists precisely so a client can tell which kind of learning it is talking to, and can honestly promise a deterministic effect only in the `rules` case.
- **#2061 (multi-turn semantics, `input-required` + context persistence)** covers what persists *within* a conversation. This covers what survives *after* it — the two would want to agree on where a teach block sits relative to context.
- **#1976 (acceptance criteria)** is adjacent human judgement on a task, but is gating completion rather than changing future behaviour.
- **#1991 (coherent task history)** overlaps on versioning and observability; a definition version id is the natural join key between "what the agent knew" and "what the task did".

### Out of scope

- **The transport for writing a lesson.** Deliberately unspecified. The agent recognises, the client holds the human, and in many deployments a third party holds the definitions; mandating "POST the lesson to the agent" would exclude that topology. A self-owning agent MAY expose a method (`teachMethod`) instead.
- **How an agent stores its knowledge.** The extension constrains the effect of a write, not its implementation.
- **Authorization.** The `A2A-Extensions` header carries no authority. The spec requires an authority to authorize the writer independently and scope every lesson to one tenant, but does not define the mechanism.

### Status, and what we are asking for

This is a **draft**, published under a URI we control, which the governance document permits without registration. It is not endorsed by or affiliated with the A2A project, and it does not use an `a2aproject` prefix.

Implementation status, plainly: there is one implementation, ours, in a private codebase — an email triage agent, a pre-alert application, and a separate control plane holding definitions, which is where the design pressure came from (in particular the opacity rule, which we got wrong first). It is not yet a public reference implementation, so we do not meet the graduation bar in the governance doc and are not asking to.

What we are asking for at this stage is **discussion, and a maintainer willing to sponsor an `experimental-ext-learnables` repository** if the direction seems worth pursuing. Specific critique most wanted on §10 (absorption semantics) and §13 (security considerations); if the field names are wrong, we would rather find out before anyone builds on them.