Unified late-bound tool contract gate with compaction-safe transcript presence

[yh928]

Summary

Extend contract-gating to every late-bound tool surface with a single, compaction-safe gate. #4995 gates per-action Composio tools; this adds the surfaces it does not cover — the generic composio_execute dispatcher, the MCP-registry bridge (mcp_registry_tool_call), and workflows (run_workflow) — and makes per-action gating resilient to context compaction.

Problem

Agents compose late-bound tool calls before the tool's full contract (input JSON schema + description) is in context, so they guess argument formats and slugs — e.g. a Composio Gmail search sent without the quotes the query syntax needs, or an invented GMAIL_LIST_MESSAGES in place of the real GMAIL_FETCH_EMAILS. #4995 (for #4853) fixed this for per-action Composio tools, but:

• The generic composio_execute dispatcher, the MCP-registry bridge, and workflows have the same thin-schema problem and are not gated.
• fix(composio): gate per-action tools on their full contract (#4853) #4995's per-action gate tracks "already surfaced" as an in-memory seen set per tool instance, which — as its own docs note — does not reset when the surfaced schema drops out of context via summarization / microcompact / trim. The model then acts on a schema it can no longer see.

Solution

A single ContractGateMiddleware in the agent harness (assemble_turn_harness) gating all four surfaces:

• Presence is derived from the transcript, not per-tool-instance state: a [contract-gate:<digest>:<key>] marker leads a delivered contract message; before each model call the gate rescans tool-role messages and rebuilds the in-context set. A contract folded away by the summarizer / blanked by microcompact / dropped by trim is no longer present, so it is re-delivered (fail-safe) — closing fix(composio): gate per-action tools on their full contract (#4853) #4995's compaction gap.
• The marker embeds an XXH3-64 digest of the exact contract bytes, so a summarized/rewritten contract fails the digest match and is re-delivered.
• Full-schema discovery tools (describe_workflow, mcp_registry_list_tools, composio_list_tools) pre-credit the contracts they fully render, so there is no redundant re-delivery.
• Per-action Composio is unified onto this gate; fix(composio): gate per-action tools on their full contract (#4853) #4995's tool-layer composio::contract_gate hookup is removed to avoid double-gating (the module is left in place, tracked for removal).

Scope: core (Rust). Kill switch OPENHUMAN_CONTRACT_GATE=0.

Acceptance criteria

• composio_execute / MCP / workflows gated — the first call each turn to each surface, with its contract not in the transcript, is short-circuited with the full contract; the retry runs.
• Compaction-safe presence — a contract dropped from context (summarize / microcompact / trim) is re-delivered; presence is transcript-derived and per-run.
• Contract integrity — a rewritten/summarized contract body fails the payload digest and is re-delivered.
• No double-gating with fix(composio): gate per-action tools on their full contract (#4853) #4995 — per-action Composio is gated exactly once (by the middleware).
• Feature-gate safe — compiles and tests with flows / skills / mcp off (the gate degrades to pass-through).
• Diff coverage >= 80% — the implementing PR meets the changed-lines coverage gate (Vitest + cargo-llvm-cov, enforced by .github/workflows/ci-lite.yml).

Related

• Extends fix(composio): gate per-action tools on their full contract (#4853) #4995 (per-action Composio contract gate) and closes its documented compaction follow-up.
• Original bug Composio Gmail search returns no results because agents call actions before seeing the full parameter schema #4853 (closed by fix(composio): gate per-action tools on their full contract (#4853) #4995).
• Implemented by PR Extend the contract gate to composio_execute, MCP registry, and workflows #4861.

Implementation Plan

Triage Assessment

• The issue specifies extending fix(composio): gate per-action tools on their full contract (#4853) #4995's contract-gating to all late-bound tool surfaces (composio_execute, MCP-registry bridge, workflows) and making presence transcript-derived for compaction safety. PR Extend the contract gate to composio_execute, MCP registry, and workflows #4861 is already open and tracks implementation. Not a duplicate — Unified late-bound tool contract gate with compaction-safe transcript presence #5038 is the spec/plan issue that Extend the contract gate to composio_execute, MCP registry, and workflows #4861 implements.
• Medium-to-high user impact: currently agents guess argument formats for these surfaces, causing wasted inference turns. Compaction gaps are a correctness bug in the existing fix(composio): gate per-action tools on their full contract (#4853) #4995 gate.

Proposed Scope

• Core Rust agent harness: assemble_turn_harness in src/openhuman/agent/.
• ContractGateMiddleware — a single harness middleware replacing per-surface gating.
• Transcript-derived presence using [contract-gate:<digest>:<key>] markers with XXH3-64 payload digest.
• Full-schema discovery tools pre-credit their contracts.
• Remove fix(composio): gate per-action tools on their full contract (#4853) #4995's composio contract_gate hookup (module retained, tracked for removal).
• Kill switch: OPENHUMAN_CONTRACT_GATE=0.

Implementation Steps

1. Implement ContractGateMiddleware in src/openhuman/agent/harness/ — evaluate presence from transcript markers before each model call.
2. Wire into assemble_turn_harness — gate composio_execute, mcp_registry_tool_call, and run_workflow.
3. Integrate XXH3-64 digest on delivered contracts for integrity verification.
4. Pre-credit full-schema discovery tools (describe_workflow, mcp_registry_list_tools, composio_list_tools).
5. Unify per-action Composio onto the middleware; remove composio::contract_gate hookup.
6. Ensure feature-gate safety: flows/skills/mcp off → gate degrades to pass-through.

Verification

• Existing tests in tests/json_rpc_e2e.rs and composio/contract gate tests.
• Both-ways feature-gate tests (compiles with features off).
• Coverage gate: cargo-llvm-cov diff coverage >= 80%.

Risks and Open Questions

• Risk: transcript-derived markers could interfere with prompt formatting if models echo them back. Mitigation: markers are tool-role messages, not user/assistant turns, so models do not see them as instructions.
• Open question: whether the composio::contract_gate module should be deleted outright rather than left in place.

Acceptance Criteria

• As listed in the issue body (six acceptance checkboxes).

[YellowSnnowmann]

Verified on main (6be58a9) — unimplemented, premise confirmed at source, PR #4861 open and the right shape

Nothing from this has landed. No ContractGateMiddleware, no transcript-derived presence, no OPENHUMAN_CONTRACT_GATE kill switch:

$ grep -rIln "ContractGateMiddleware\|contract-gate\|contract_gate" --include='*.rs' src/
src/openhuman/integrations/composio/contract_gate.rs
src/openhuman/integrations/composio/action_tool.rs
src/openhuman/integrations/composio/action_tool_tests.rs
src/openhuman/integrations/composio/mod.rs

$ grep -rIn "OPENHUMAN_CONTRACT_GATE" --include='*.rs' src/
(no output)

Only #4995's per-action Composio gate exists. composio_execute, mcp_registry_tool_call and run_workflow remain ungated.

The compaction gap is documented in-tree, exactly as this issue describes — src/openhuman/integrations/composio/contract_gate.rs:35-46:

One [ContractGate] is held per ComposioActionTool instance … That loop is a single agent turn in the common case, so "seen" behaves as per-turn state without any task-local plumbing — but a long-lived spawn can span multiple turns, and this gate does NOT reset when the surfaced schema drops out of context via compaction (tracked as follow-up; see the module-level note).

with state still held as seen: Mutex<HashSet<String>> (:66). So the model can still act on a schema it can no longer see.

---

One thing this issue predates, and PR #4861 already handles it well

This was filed 2026-07-18. #5119 — "Composio contract-gate never executes in sub-agent path — 'what's my latest email' loops forever (GMAIL_FETCH_EMAILS surfaced 51× never runs)" — was filed 2026-07-22 and closed 2026-07-23, adding an auto-proceed safety net to the very gate this issue replaces (contract_gate.rs:48-62):

A global OnceLock map tracks how many unique gate instances have consulted each slug for the "first time". After 3+ fresh instances have all surfaced the same contract, the next instance auto-proceeds …

That is load-bearing: without it, every fresh integrations_agent spawn re-surfaces the same contract and the action never executes. Any replacement gate that dropped it would regress #5119 straight back into an infinite loop — and it is not mentioned in this issue's Solution or acceptance criteria, since it did not exist yet.

PR #4861 carries it forward, and improves it. The diff deletes composio/contract_gate.rs (-429) and its tests (-342), adds src/openhuman/tools/contract_gate.rs (+1149) and tests (+931) plus agent/tinyagents/middleware.rs (+90) — and keeps auto-proceed while re-scoping it:

auto-proceed accounting is scoped only by the TOP-LEVEL turn

Replacing a process-wide OnceLock with turn-scoped accounting is the better design independently of this issue: a process-global consult counter leaks across unrelated sessions and makes test ordering significant. Worth calling out as a positive in review rather than a risk.

Suggested addition to the acceptance criteria: an explicit "#5119 does not regress" item — i.e. a test that N fresh sub-agent spawns consulting the same slug eventually execute rather than surfacing forever. It is the one behaviour that is easy to lose in a rewrite of this size and that fails in a way users experience directly (an endless loop, not an error).

---

Status

PR #4861 is open, not draft, unmerged, 33 files. It is the right shape for all four surfaces and for the compaction fix. Leaving this issue open until it merges; the main review focus should be the transcript-rescan cost per model call and the #5119 regression test above.