Tool argument array constraints are stricter than docs imply

[MaestroError]

Summary

assertToolUsed($tool, [...]) currently uses strict array equality for argument matching, which makes tool assertions brittle in realistic runs.

Why this matters

Agent tool arguments are often associative arrays where key order may vary, or where the actual invocation includes additional harmless fields. Strict equality makes the simple array constraint form fail more often than users are likely to expect.

Evidence

• src/Concerns/HasToolAssertions.php:135-137 uses $invocation->arguments === $constraint.
• The README presents the array form as a straightforward argument constraint:
  • README.md:494-497

Current risk

These assertions can fail even when the invocation contains the expected arguments, for example because:

• keys are in a different order, or
• the invocation includes extra metadata alongside the expected subset.

That makes the array shorthand much less ergonomic than it appears in docs.

Suggested fix

This is only a suggestion; the actual fix should be planned carefully.

Possible directions:

• Treat array constraints as subset matches rather than full strict equality.
• Or introduce/document two explicit modes, for example exact-match vs subset-match.
• Keep the closure-based form as the escape hatch for advanced constraints.
• Add tests covering key-order differences and additional invocation arguments.

Notes

This is mostly a developer-experience issue, but it can also cause confusing false negatives in test suites that rely on tool assertions.

[MaestroError]

Implementation plan based on the current 4.x branch:

1. Change the array-constraint semantics in src/Concerns/HasToolAssertions.php so assertToolUsed($tool, [...]) treats the provided array as an expected subset of ToolInvocation::$arguments, not as a full strict-equality check.
2. Keep closure constraints unchanged. They already serve as the escape hatch for exact or custom matching, so the array shorthand should optimize for the common ergonomic case.
3. Implement the subset check recursively so nested associative structures also behave predictably when callers assert only the keys they care about. The check should still require exact value equality for the keys that are provided.
4. Preserve current tool-name / tool-class matching and avoid changing assertToolUsedTimes, assertToolUsedAtLeast, and assertToolUsedAtMost behavior beyond the fact that they all reuse toolMatchesConstraint() and would automatically inherit the improved array semantics.
5. Add focused tests in tests/EvalBuilderTest.php covering:

• array constraint passes when invocation has extra arguments
• array constraint passes when associative keys are in a different order
• array constraint fails when an expected key is missing
• array constraint fails when an expected value differs
• nested array subset matching, if recursive support is added
• one count-based assertion using an array constraint, to confirm the shared matcher path works consistently outside assertToolUsed()

6. Update the README tool-assertion section to explicitly say the array form matches expected argument subsets, and keep the closure example as the option for stricter/custom inspection.

Why this plan:

• The issue is real in 4.x: toolMatchesConstraint() currently does $invocation->arguments === $constraint, which is what causes the brittle false negatives.
• The README currently presents the array shorthand as the simple/default form, so changing it to subset semantics is the smallest fix that aligns implementation with likely user expectation without adding new API surface.
• A new exact-match mode does not seem necessary unless there is a proven need, because closures already cover that use case.

Suggested implementation shape:

• Add a small private helper in HasToolAssertions dedicated to recursive subset matching, and call it from the is_array($constraint) branch.
• Keep the change local to this trait so the behavior remains easy to review and low-risk.

Risks to watch during implementation:

• Numeric-list arrays may need an explicit decision: whether they should remain exact matches or also be treated as subsets. I would recommend documenting and testing the chosen rule rather than leaving it implicit.
• If nested matching is introduced, tests should prove that scalar comparisons stay strict and do not silently coerce values.

This plan looks ready for implementation as a small bug-fix PR on 4.x.