Hooks
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.
Enter your API key here (sent as Otari-Key header).
A policy body plus the evidence to check it against, both caller-supplied.
What commands covers: call for the single tool call about to run, session for every command the session has run so far.
callPossible values: Shell commands the caller observed run or is about to run.
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.
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.
Successful Response
client_reportedValidation Error
POST /api/v1/hooks/check HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 258
{
"check_results": [
{
"detail": "",
"gate_id": "text",
"outcome": "pass"
}
],
"command_scope": "call",
"commands": [
"text"
],
"judge_results": [
{
"gate_id": "text",
"outcome": "pass",
"reasoning": ""
}
],
"path_source": "pre_tool_use.edit_target",
"paths": [
"text"
],
"policy_yaml": "text"
}{
"blocked": true,
"policy_id": "text",
"provenance": "client_reported",
"results": [
{
"detail": "text",
"enforcement": "text",
"gate_id": "text",
"message": "text",
"outcome": "text"
}
],
"schema_version": "text"
}Keep one version of an agent guardrail, so the gate spans that name it can say what each gate is for.
otari hook sends this once per version, the first time it reports a check against it. The fingerprint is recomputed from the gates, and one that does not match the one sent is refused, so a version cannot be stored under another's name. Sending a version again changes nothing. A workspace keeps at most 1,000 versions, and a new one past that is refused with a 409. It is stored in the API key's workspace, beside that key's traces, and takes the same key a trace export does: a budget-exempt API key, never the master key.
Enter your API key here (sent as Otari-Key header).
^[0-9a-f]{64}$Successful Response
The workspace already keeps the most guardrail versions it may, and this one is new.
Validation Error
POST /api/v1/hooks/guardrails HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 162
{
"digest": "text",
"gates": [
{
"enforcement": "required",
"gate_id": "text",
"gate_type": "command",
"message": "text",
"origin": "repo",
"runs": [
"pre_tool_use.edit_target"
]
}
]
}{
"digest": "text"
}Last updated
Was this helpful?
