Implement executable agent execution model-routing decisions

[mdheller]

Goal

Turn the new AgentExecutionModelRoutingPolicy contract into an executable route-decision path for agent execution chains.

Context

model-router now owns the canonical policy contract:

• schemas/agent-execution-model-routing-policy.schema.json
• examples/agent-execution-model-routing-policy.default.json
• tools/validate_agent_execution_model_routing_policies.py
• docs/agent-execution-model-routing-policy.md

The policy rule is: use the cheapest lane that can safely complete the next irreversible decision.

Required behavior

1. Add a small route-decision CLI or library function that accepts:
   • task class
   • chain stage
   • requested model lane
   • escalation reason, optional
   • tool/network/write flags, optional
2. Emit a normalized decision containing:
   • selected lane
   • requested lane
   • downgrade/escalation result
   • reason
   • evidence fields required by the policy
   • violation behavior when denied/deferred
3. Deny or defer high-end/pro use unless the request includes an allowed escalation reason.
4. Downgrade routine chores to cheap/standard lanes.
5. Preserve hash-only prompt evidence.
6. Keep local-first and hosted-fallback policy gates intact.

Acceptance criteria

• python3 tools/validate_agent_execution_model_routing_policies.py passes.
• A new example decision fixture exists for routine-code, architecture-decision, security-review, and formatting-rewrite.
• Unit tests prove:
  • formatting cannot escalate directly to high-end
  • routine execution defaults to standard or cheaper
  • high-end without reason is denied/deferred
  • pro without reason is denied/deferred
  • verification defaults to no-model
• README or docs show the CLI usage.

Non-goals

• Do not implement provider-specific API calls here.
• Do not store raw prompts.
• Do not replace AgentPlane evidence or Guardrail Fabric decisions.

[mdheller]

Budget/resource optimization is now part of the route-decision scope.

Additional contract files added on main:

• schemas/agent-execution-budget-resource-optimizer.schema.json
• examples/agent-execution-budget-resource-optimizer.default.json
• tools/validate_agent_execution_budget_resource_optimizers.py
• docs/budget-resource-optimizer.md

The executable route decision should now consider both:

1. AgentExecutionModelRoutingPolicy — which lanes are allowed.
2. AgentExecutionBudgetResourceOptimizer — which allowed lane is optimal under budget, quota, latency, quality floor, privacy, local resource health, and provider health constraints.

Route output should include candidate set, selected candidate, budget decision, quota snapshot, resource snapshot, and downgrade/deny/defer reason when constraints bind.