Audit planning-only advisor escalation without granting execution authority #246

Context

Advisor escalation is a useful pattern for agent systems: a cheap/default executor handles normal loop turns and a stronger model is called only for hard planning decisions. For agent-kernel, this should not mean routing or model orchestration lives in the kernel.

The kernel's role should be narrower and stricter: represent and audit that advisory escalation happened, while preserving the invariant that advice is not execution authority.

Problem

If advisor calls are invisible to the execution boundary, audit traces become incomplete:

• a tool execution may be influenced by advice that is not recorded;
• a strong model may effectively steer sensitive decisions without an audit event;
• reviewers cannot tell whether a policy decision followed normal routing, human instruction, or external advisor advice;
• malformed or policy-incompatible advice may be accepted silently by the host.

At the same time, agent-kernel should not become a model router or advisor orchestrator. It should only expose the minimal hooks needed to record, validate, and constrain advisor-influenced execution.

Proposal

Add support for advisor-related audit metadata and policy semantics.

Possible additions:

Advisor metadata on requests / traces

Allow a capability request or ActionTrace to include optional advisor context:

{
  "advisor": {
    "advisor_request_id": "adv_123",
    "trigger_reason": "low_confidence_route",
    "advice_status": "accepted",
    "advice_type": "choose_flow",
    "recommended_id": "refund_review_flow",
    "confidence": 0.81
  }
}

Policy checks

Add helper checks or documented policy patterns for:

• advisor advice cannot mint capability tokens;
• advisor advice cannot expand an existing token scope;
• advisor advice cannot bypass approval requirements;
• advisor-influenced writes remain subject to normal policy;
• malformed or forbidden advice can be marked as rejected/blocked in the trace.

Explainability

kernel.explain() should make advisor involvement visible when present:

Advisor: called for low_confidence_route; advice accepted; recommended refund_review_flow; policy still required approval.

Non-goals

• Do not call LLMs from agent-kernel.
• Do not choose when escalation happens.
• Do not store raw advisor prompts or full model outputs by default.
• Do not grant authority based only on advisor confidence.

Acceptance criteria

• ActionTrace or equivalent trace surface can record advisor involvement.
• Advisor metadata is redacted / bounded consistently with existing trace policies.
• Tests prove advisor advice cannot bypass deny/approval policy outcomes.
• kernel.explain() exposes advisor involvement in a reviewer-friendly way.
• Docs include a short "planning-only advisor" integration note.

Test plan

• Unit test accepted advisor metadata on a read action.
• Unit test advisor-recommended write still requires approval.
• Unit test advisor-recommended forbidden/destructive action is denied or held by normal policy.
• Unit test malformed advisor metadata is rejected or recorded as malformed.
• Snapshot test for explain() output.

Suggested labels

enhancement, audit, policy, governance, ai