Sign in
hooks

Check Policy

Changed on

Evaluate a submitted policy against submitted evidence.

Authenticated with either an API key or the master key (the router-level gate), like POST /api/v1/usage/external-events: this identifies who sent the request, not whether its evidence is true. blocked is set when a required gate's outcome is not pass/not_applicable (an unresolved gate never counts as a pass).

The actual parse-and-evaluate work is otari_agent.domain.check.run_policy_check, shared with otari hook's own local evaluation: this route's own job is authentication, translating that function's tri-state request fields into its own typed ones, and turning PolicyCheckError into a 422.

post/api/v1/hooks/check

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header Otari-Key
    • API key in header x-api-key

Request body

command_scope'call' | 'session'

What commands covers: call for the single tool call about to run, session for every command the session has run so far.

commandsstring[] nullable

Shell commands the caller observed run or is about to run.

path_source'pre_tool_use.edit_target' | 'pre_tool_use.read_target' | 'pre_tool_use.command' | 'stop.working_tree' | 'stop.session' | 'stop.verifier' nullable

Which moment paths was read at, matching the runs values a path gate declares. Only three of the six runs values are legal here, because only those three are moments a path can be read at: pre_tool_use.edit_target for a write tool's own target before it runs, pre_tool_use.read_target for a read tool's, and stop.working_tree for git status once the turn is over. Required whenever paths is non-empty, and rejected with a 422 if omitted or set to any other value: either would resolve every path gate not_applicable, which loses enforcement without reporting anything. An empty paths needs no source.

pathsstring[] nullable

Repo-relative paths this moment of the session puts in scope: what git status --porcelain reports, or the single target a tool call is about to write or read. path_source says which.

policy_yamlstring required

Response

Successful Response

blockedboolean required
policy_idstring required
provenancestring
schema_versionstring required

Changes

  • fbee488d4d9fRevision changes
    • info

      added the optional property to the response with the status

  • 60992aa6abf8Revision changes
    • warning

      removed the request property

    • warning

      removed the request property

    • info

      added the new optional request property

    • info

      added the new optional request property