fix(agent-mesh): preserve full sub-resource path in capability parsing

[liamcrumm]

Summary

CapabilityGrant.parse_capability truncated the qualifier to a single segment, so a leaf capability grant authorized its parent and its siblings. This preserves the full sub-resource path so a narrow grant only authorizes what it names. Closes #3180.

Problem

parse_capability did qualifier = parts[2] if len(parts) > 2 else None, discarding parts[3:]. A grant scoped to write:database:table_users:row_1 was stored and compared as write:database:table_users, so it authorized:

• its parent write:database:table_users, and
• its siblings write:database:table_users:row_2.

This is the 4+-segment variant and is independent of #3176 (which fixed the 3-segment matcher under-restriction). It lives in the parser, not the matcher, and reproduced on the pulled tree.

Reproduction (before -> after)

For a write:database:table_users:row_1 grant:

Check	Before	After
exact leaf write:database:table_users:row_1	True	True
parent write:database:table_users	True	False
sibling write:database:table_users:row_2	True	False

Security model (blast radius)

This is a capability data-model change; the chosen approach and its blast radius:

• Approach (option a): parse_capability now preserves the full remainder via qualifier = ":".join(parts[2:]). matches() is unchanged because it already treats qualifier as an opaque exact-match token, and the broad-satisfies-narrower direction is handled by the separate requested.startswith(capability + ":") branch (which reads the untruncated capability string).
• Consistency hardening: a Pydantic model_validator(mode="before") re-derives action/resource/qualifier from capability on every construction and revalidation (including model_validate/deserialization). Without it, a grant built as CapabilityGrant(capability="a:b:c:d", qualifier="c") would keep a stale truncated qualifier and re-open the escalation, since matches() trusts the stored qualifier. No such path exists in the tree today, but this makes the model correct-by-construction and satisfies the "no half-migrated comparison paths" requirement.
• Grammar decisions (pinned by tests): only whole-segment * (action/resource) and a trailing :* are wildcards. A * in the middle of the remainder (e.g. write:database:*:row) is now a literal qualifier segment (stricter / fail-closed vs the old accidentally-permissive parse). Empty/trailing-segment behavior (write:database:) is pinned.
• Rejected: option (b) fail-closed reject of >3-segment grants (functional regression: removes deep-capability granting instead of making it correct); and rewriting matches() to a variable-length component list (larger blast radius on the security-critical matcher, no behavioral gain).
• Out of scope: integrations/mcp/__init__.py::_check_capability is a separate, stricter matcher (exact + trailing wildcard only), never calls parse_capability, and is not vulnerable.

Maintainer decision points

• Option (a) extends the 3-component action:resource[:qualifier] spec grammar to treat the qualifier as a full colon-containing remainder. Spec sec 8.2/8.5 were updated to document this. Alternative (b) would instead reject >3 segments.
• Whether to additionally reject empty segments at parse time (left out to keep scope on CapabilityGrant.parse_capability truncates 4+ segment capabilities, enabling parent/sibling privilege escalation #3180; current behavior pinned by tests).

Changes

File	What changed
agent-governance-python/agent-mesh/src/agentmesh/trust/capability.py	parse_capability preserves full remainder; add model_validator re-deriving components from capability; create() no longer passes derived fields; docstrings updated
agent-governance-python/agent-mesh/tests/test_coverage_boost.py	New TestCapabilityFourSegmentEscalation matrix: exact leaf / parent / siblings, deeper nesting, resource_ids, delegation (require_grantor_capability), registry check(), get_capabilities/deny, wildcard + empty-segment grammar pins, validator self-heal, retained #3176 regressions
docs/specs/AGENTMESH-TRUST-COORDINATION-1.0.md	sec 8.2/8.5: qualifier is the full sub-resource path compared as one opaque token; conformance sec 8.1-8.3 unaffected

Testing

• Repro shows parent/sibling checks flip True -> False while exact-leaf stays True.
• pytest full agent-mesh suite: 3424 passed, 73 skipped; the only failures are 4 pre-existing ModuleNotFoundError: agentrust_trace env failures in tests/governance/test_trace_sink.py, unrelated to this change.
• New matrix + test_trust.py + test_spec_mesh_trust_conformance.py: all green; fix(capability): reject narrow grants satisfying broad capability checks #3176 and spec S8.1-S8.3 preserved.
• ruff check --select E,F,W --ignore E501 clean on changed lines.
• Docs link check: 0 new broken links.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None