Adapter: record CHAP human-decision events from Pydantic AI tool approvals

[brightbeamarsalan]

Goal

A small adapter so a Pydantic AI app emits a CHAP human-decision record whenever a human approves, edits, or denies a deferred tool call. A merged adapter is strong evidence CHAP is usable in real agent stacks, and Pydantic AI's typed, approval-gated tools map almost one-to-one onto CHAP's record.

Where it hooks

Pydantic AI handles human-in-the-loop through deferred tools. A tool marked requires_approval=True, or gated by an ApprovalRequiredToolset, ends the run with a DeferredToolRequests output whose approvals list holds the pending ToolCallParts. The caller resolves them into DeferredToolResults using ToolApproved or ToolDenied, either after the run or inline via a handle_deferred_tool_calls hook. The adapter records each decision at that resolution point.

Mapping (Pydantic AI to CHAP)

• the pending ToolCallPart (tool name, validated args, tool_call_id) is the referenced artifact the human acts on
• ToolApproved() with no change is an approve, decision kept
• ToolApproved(override_args=...) is a refining override; original args versus override_args is the diff
• ToolDenied(message=...) is a reject or escalate, and the message is the rationale
• DeferredToolResults.metadata[tool_call_id] carries the rationale and the CHAP tags
• records hash-chain, with an optional transparency-log anchor via the audit-scitt profile

Scope

• A helper wrapping the approval-resolution step, or a handle_deferred_tool_calls hook, that emits one CHAP record per decision
• A minimal runnable example: one approval-gated tool, with a human approving, editing args, and denying, producing a valid CHAP chain
• Emitted records pass the CHAP conformance harness
• A short README section showing the integration

Out of scope

Changing Pydantic AI itself, or anything in MCP core. This is application-layer and reads from the existing deferred-tools API.

Pointers

CHAP spec and README in this repo; the protocol-neutral record shape (link the shape issue once it exists); the conformance harness; Pydantic AI's deferred-tools and human-in-the-loop docs at ai.pydantic.dev.

[BrightbeamBogdanCastraveti]

I can help here. Here's the plan:

A small chap-pydantic-ai adapter mirroring the existing chap-langgraph bridge (depends only on chap-coordinator; pydantic-ai optional). It records one CHAP human-decision per resolved approval at the after-the-run resolution point:

• ToolApproved() / True → decide.approve
• ToolApproved(override_args=…) → decide.override (diff = original args_as_dict() vs override_args, intent_preserved=true)
• ToolDenied(message=…) / False → decide.reject (message → rationale)

Targeting the stable deferred_tool_results path rather than the inline handle_deferred_tool_calls hook for now, since inline resolution is still in flux (#3959).

Deliverables per the scope: the helper + a runnable approve/edit/deny example + records passing the conformance harness + a short README section.

[brightbeamarsalan]

This is great Bogdan, and yes please, assigning it to you.

The shape is right: mirroring chap-langgraph with pydantic-ai optional keeps it consistent, the mapping onto decide.approve / decide.override / decide.reject is what I'd want, and targeting the stable deferred_tool_results path over the inline hook while #3959 settles is the right call.

Two things to get right.

intent_preserved is the one field I would not hardcode. It is the human's signal, and editing args is not always intent-preserving, since sometimes the change is a different decision in disguise. Default it to true for ToolApproved(override_args=…) by all means, but let the resolver pass an explicit value, with the metadata dict as the natural channel, so the refine-versus-replace distinction stays meaningful rather than assumed. The same channel can carry tags.

Approver identity is the other. A human-decision record is only as useful as knowing whose decision it was, so let's make sure the approver flows into the record. Does the coordinator session already carry the actor, or does the resolver need to pass it? Either way, have the example show a real approver rather than an anonymous one.

Otherwise the deliverables are spot on, and a runnable approve/edit/deny example that passes the conformance harness is exactly the bar. Ping me when you want a review, and flag anything ambiguous in the spec.

[BrightbeamBogdanCastraveti]

Both well taken.

intent_preserved — agreed, won't hardcode. Confirmed the coordinator passes it straight through (p.get("intent_preserved"), no default), so it's purely the human's signal. I'll default it to true for ToolApproved(override_args=…) but let the resolver override via metadata[tool_call_id], same channel as tags and rationale. The example will show both a refine (true) and a replace-in-disguise (false) so the distinction is visible, not assumed.

Approver identity — the coordinator has no session actor: the decider is whatever's in the envelope from, which it records as decisions[].reviewer, on the override artefact, and in task history. So the resolver passes it. The bridge will take a default approver (like chap-langgraph's reviewer) but allow a per-decision override via metadata[tool_call_id].approver, since a real approval queue has different people approving different calls. The adapter idempotently joins that approver before recording, and the example uses a real named human (and a second approver on one call to show identity flows per-decision).

One spec thing while I'm here: decide.* / decide.override don't verify from is a joined member — they check the workspace, the task, and review_requested state, but not membership. So a decision could currently name an approver who never joined. The adapter sidesteps this by joining first, but for a human-decision record it might be worth tightening in core. Happy to file a separate issue.

Will ping you for review once the approve/edit/deny example is green against the harness.

[BrightbeamBogdanCastraveti]

The adapter for this issue is built and verified — but I can't get it in front of you for review because of repo access. Details below.

What's ready (chap-pydantic-ai, mirroring chap-langgraph):

• record_decision / record_results — at the deferred_tool_results resolution point:
  ToolApproved() → decide.approve, ToolApproved(override_args=…) → decide.override (RFC 6902 diff of the args), ToolDenied(message=…) → decide.reject.
• pydantic-ai is an optional dependency; resolution objects are read structurally, so the bridge and tests run without it installed.
• Both review points are in: intent_preserved defaults to true on an edit but is overridable via results.metadata[tool_call_id] (same channel as rationale/tags); approver identity flows per-decision, participant type follows the URI scheme, approver joined just-in-time. The example uses real named approvers.
• 17 unit tests pass with no pydantic-ai installed; examples/01-approve-edit-deny.py runs all three decisions against real pydantic-ai 2.0 via TestModel (offline) and resuming with the override confirms the edited args take effect.
• 6 files, +875: package, bridge, example, tests, README.

Two spec things I noticed (not changed): decide.approve/decide.reject record the note as comment while decide.override uses rationale; and decide.* don't verify from is a joined member.

What I tried, and the blocker:

1. Pushed the branch to BrightbeamAI/chap directly → denied (no write access).
2. Forked and pushed there → works: https://github.com/BrightbeamBogdanCastraveti/chap/tree/adapter/pydantic-ai
3. Tried to open the PR from the fork → blocked: "An owner of this repository has limited the ability to open a pull request to users that are collaborators on this repository."

Ask: could you add BrightbeamBogdanCastraveti as a Write collaborator? Then I'll push the branch straight to the repo and open the PR here so you can compare and approve in-repo — no fork needed. Read-as-collaborator would at least unblock opening the fork PR, but Write gives us the clean flow.

[brightbeamarsalan]

Thanks a million, Bogdan - that's great.

I did assign you this issue but I will recheck the permissions tomorrow and make sure you are able to push.

Also on verification, this is a sharp catch. I dug into the tree to confirm scope: the gap isn't unique to decide.* (none of the actor-action methods verify from is a member), and it turns out SPECIFICATION.md already defines -32403 unknown_participant for exactly this case, so the implementations have had issue that were diverging from the normative text. So I'll be treating it as a spec-conformance fix, not a new feature.

Updates are underway across the spec, both reference implementations, the schemas, and the conformance vectors, with the member-vs-reviewer-set and break-glass questions settled first since the exact check depends on them. I'll ping you when the approve/edit/deny example is green so you can review. Appreciate you flagging it.