feat(pydantic): forward session properties to the engine

[lucifer726]

What changes

WrenToolkit.query(), dry_plan() and dry_run() now accept properties and forward
it to the engine, so a caller can supply MDL session properties per call.

WrenEngine.query/dry_plan/dry_run already accept properties (core/wren/src/wren/engine.py)
— the toolkit simply never passed it, so a model guarded by row-level access control could
not be read through the SDK at all: planning fails when a required session property is
missing, and there was no way to supply one.

Closes #2638.

Why the Pydantic AI tools are unchanged

wren_query / wren_dry_plan keep their current signatures on purpose. Their ctx is
documented as ignored because "the toolkit already captures all required state"
(_tools.py), and turning a session property into a model-fillable tool argument would let
the LLM choose the identity that RLAC is keyed on — the model would be deciding which rows
it is allowed to see. Binding session state for agent runs is a separate design question
(toolkit- or run-scoped), so this PR only opens the direct Python API that the issue asks
for.

How this was verified

Scope of the claim: these tests assert the parameter reaches WrenEngine. I did not stand
up a live RLAC project against a real data source, so this PR does not claim an end-to-end
RLAC observation — the engine-side behaviour is the existing, already-tested path.

• 3 new tests assert properties is forwarded by query / dry_plan / dry_run.
• 3 existing delegation assertions updated to record the new call contract
  (properties=None by default), since they pinned the exact kwargs.
• Confirmed the new tests fail without the source change (6 failed with _toolkit.py
  reverted, 8 passed with it).
• pytest tests/unit → 103 passed. ruff check . and ruff format --check . clean.

Summary by CodeRabbit

• New Features

  • Added optional session properties to query, plan preview, and dry-run operations.
  • Session properties are forwarded to the Wren engine, enabling them to influence planning and row-level access control predicates.

• Bug Fixes

  • Preserved existing connector caching behavior for queries.
  • Added coverage ensuring custom session properties are passed through unchanged.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f889214d-807c-4147-8c45-2b7c6a450390

📥 Commits

Reviewing files that changed from the base of the PR and between 2e87902 and 7b144a1.

📒 Files selected for processing (2)

• sdk/wren-pydantic/src/wren_pydantic/_toolkit.py
• sdk/wren-pydantic/tests/unit/test_toolkit_runtime.py

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

Walkthrough

WrenToolkit.query, dry_plan, and dry_run now accept optional MDL session properties and forward them to the Wren engine. Unit tests cover both omitted properties and unchanged custom property forwarding.

Changes

Session property support

Layer / File(s)	Summary
Toolkit session property forwarding sdk/wren-pydantic/src/wren_pydantic/_toolkit.py	query, dry_plan, and dry_run accept optional properties and pass them to the engine.
Forwarding behavior tests sdk/wren-pydantic/tests/unit/test_toolkit_runtime.py	Tests cover properties=None and custom session properties for all three toolkit methods.

Estimated code review effort: 2 (Simple) | ~15 minutes

Merge Risk: ⚪ Minimal · up to 7b144

The PR forwards optional session properties through the toolkit APIs without introducing an actionable merge-blocking risk; it is merge-ready after normal checks and review.

Poem

I’m a rabbit with properties tucked neat,
Forwarding each value from call to engine seat.
Query hops onward, plans follow the trail,
Dry runs carry headers without fail.
RLAC predicates now see what they need.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The toolkit methods meet the core issue, but the linked issue also expects session-property support for the Pydantic AI tools.	Add secure session-property handling for wren_query and wren_dry_plan, or update the linked issue to narrow its scope to the direct toolkit API.
Docstring Coverage	⚠️ Warning	Docstring coverage is 77.78% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: forwarding session properties to the engine.
Description check	✅ Passed	The description explains the behavior change, scope, rationale, and tests, but it omits the template's duplicate-check section.
Out of Scope Changes check	✅ Passed	The code and tests stay within the requested session-property forwarding change.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}