Edge

Evaluate an Edge action with Safety Kernel policy

Changed on

Classifies a bounded, redacted agent action for an existing Edge session/execution, calls the Safety Kernel using the Edge policy topic, persists a redacted policy decision or degraded event, and returns hook-friendly allow/deny fields. Raw tool_input, raw transcripts, and unredacted payloads are rejected; large evidence must use artifact pointers.

post/api/v1/edge/evaluate

Request

  • Base URL: http://localhost:8081
  • URL: http://localhost:8081/api/v1/edge/evaluate
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Headers

X-Tenant-IDstring required

Tenant isolation header (required on all protected routes).

Request body

event_idstring

Optional caller-supplied event ID; omitted values are generated by the server.

tenant_idstring

Optional body tenant; when present it must match X-Tenant-ID.

principal_idstring required
session_idstring required
execution_idstring required
agent_productstring
layer'hook' | 'mcp' | 'llm' | 'runtime' | 'workflow' | 'system' required
kindstring required

Non-empty Edge event kind such as hook.pre_tool_use.

tool_namestring

Hook tool name such as Bash; required for hook-layer tool evaluations.

tool_use_idstring
input_redactedobject nullable

Bounded, redacted action input. The server re-redacts and computes the persisted input_hash.

tool_input_redactedobject nullable

Claude-hook-friendly alias for input_redacted.

input_hashstring

Optional client hash. When redacted input is supplied, the server computes/overwrites the persisted sha256: hash from accepted redacted input.

tool_input_hashstring

Claude-hook-friendly alias for input_hash.

cwdstring
repostring
git_remotestring
git_branchstring
git_shastring
action_namestring

Optional client hint; ignored/overridden by the server-side classifier when derivable.

capabilitystring

Optional client hint; ignored/overridden by the server-side classifier when derivable.

risk_tagsstring[]

Optional client hints. Server-side classifier output is authoritative.

labelsEdgeLabels
approval_ttl_secondsinteger

Optional override of the default 5-minute approval TTL when policy returns REQUIRE_APPROVAL (EDGE-059). Bound to [1, 300] seconds server-side; values outside this range or omitted use the 5-minute default. Callers can ONLY shorten the TTL — values >300 are silently capped at the default. Used by e2e tests that need to exercise approval expiration inside a bounded sleep window.

Example request

{
  "approval_ttl_seconds": 2
}

Response

Hook-friendly Edge policy decision. Safety outages may still return 200 with degraded=true when policy mode permits and degraded evidence was persisted.

decision'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL' | 'THROTTLE' | 'CONSTRAIN' required
reasonstring
rule_idstring
policy_snapshotstring
approval_refstring

Opaque approval reference from the Safety Kernel/approval integration. This endpoint does not create approval records.

constraintsobject nullable
updated_inputobject nullable
event_idstring

Persisted Edge decision/degraded event ID.

degradedboolean

True when Safety was unavailable and the response follows policy-mode degraded behavior.

error_code'safety_unavailable'
error_messagestring

Sanitized bounded error guidance; upstream secret-bearing error strings are not returned.

permission_decision'allow' | 'deny' required

Hook-friendly permission decision.

permission_decision_reasonstring
exit_codeinteger required

Hook/terminal-friendly exit code; zero for allow-like responses and non-zero for deny/block guidance.

terminal_titlestring
terminal_messagestring
wait_strategy'manual_approval' | 'backoff' | 'retry'
timeout_msinteger

Changes

  • 12120aad0bfeRevision changes
    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new replay_window_full enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

    • warning

      added the new step_up_required enum value to the response property for the response status

  • 9f66383d6e95Revision changes
    • info

      endpoint added