feat(mcp): add a locked-filter merge primitive to search-records

[vishal-bala]

Stack position: 1 of 3. Base is the feat/mcp-custom-tool-profiles integration branch, not main — see the sequencing note at the bottom.

Groundwork for custom tool profiles, split out on its own because it is the security crux of that feature and deserves attention it would not get buried in a 1,900-line PR. Nothing calls the new parameters yet.

What it does

merge_locked_filter(locked, caller) AND-combines an author-locked filter expression with a caller-supplied one, so a caller can only narrow within the locked scope and never widen past it. That rests on two things: FilterExpression.__and__ parenthesizing the combination, so a caller's or/not nests inside the AND rather than reaching the top level; and every filter value staying inside its own clause, which the text escaping already on main provides.

A raw string caller filter is refused outright — strings skip the DSL's field validation and have no safe composition with an expression, since combining them means concatenation.

The backstop, and why it walks the rendering

_reject_escapable_filter sits behind that as a backstop, not the primary defense: a well-formed expression built from escaped values cannot escape, so anything it rejects means a value reached the query string raw.

It walks the rendered string rather than counting delimiters, because several things look like structure and are not:

• \( is an escaped literal, not a group
• a numeric range renders exclusive bounds as [(5 +inf], where ( is a marker
• a tag clause scopes its alternatives in braces, so @category:{sports|health} is one clause rather than a union

Escape pairs are consumed rather than tested against the previous character, so \\| is not misread as a protected delimiter. Both directions of that were wrong in earlier drafts, which is the main reason this is its own PR.

limit_cap

Applied inside _validate_request rather than by the caller, because an omitted limit only resolves to the binding default at that point — capping just the explicit value would let the default sail past the cap. An explicit request above the cap is rejected; an omitted one is capped silently, since the caller never named a number.

Not exposed to the model

Both parameters are keyword-only on search_records and never reach the advertised MCP schema: register_search_tool registers an inner wrapper with its own fixed signature. I verified that rather than assuming it.

Verification

• MCP unit tests: 276 passing
• make check-types: clean
• The backstop accepts every legitimate like pattern (multi-word AND, % fuzzy, wildcards, in-clause |) while keeping the locked clause intact on an injection attempt

Sequencing

This targets the integration branch so that main never receives a config surface that validates but enforces nothing — see the next PR in the stack for why that matters. The integration branch currently also carries #668; once that merges it rebases onto main and drops out.

---

Note

Medium Risk
Security-sensitive filter composition for future profile enforcement; behavior is well-tested and not yet exposed to models, but mistakes in merge/backstop logic could allow filter bypass once profiles land.

Overview
Adds server-only hooks on search_records for upcoming custom tool profiles: locked_filter AND-combined with the caller’s filter, and limit_cap applied in _validate_request. Neither is exposed on the registered MCP tool wrapper.

merge_locked_filter keeps the author lock always in force so callers can only narrow. Object filters are merged via FilterExpression.__and__; raw string caller filters are rejected. _reject_escapable_filter walks the caller’s rendered query as a backstop (top-level |, unbalanced groups/braces, pipes inside numeric ranges, etc.) so crafted renderings cannot break out of the locked AND.

limit_cap: explicit limits above the cap fail with INVALID_REQUEST; omitted limits are silently min(default_limit, cap) so binding defaults cannot bypass the ceiling.

Extensive unit tests cover merge shapes, escape cases, and search_records integration.

^{Reviewed by Cursor Bugbot for commit 561da31. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bee8dd2. Configure here.}