HTTP API: guard

Whether a write to a file of this checkout is covered by a claim: the active task's scope, or a live mesh claim of the writing session. The judgement a provider's pre-tool hook asks before every edit (majordomus guard hook), switched by session.edits_require_claim.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

guard

GET /api/v1/guard/edit guard.edit

Judge one edit

Whether the given session may write the given path now: allowed when the policy's session.edits_require_claim is off, the path is outside the checkout or its local state, the repository declares no enabled mesh, the active task's scope covers it, or a live mesh claim of the session covers it; refused as unclaimed otherwise, with the remedy. What cannot be read — the policy, the mesh — is let through and named, never refused.

query
experimental
benchmark required
cache disabled
MCP tool majordomus_guard_edit

Query parameters

name	type	required	description	examples
path	string	yes	The path about to be written: absolute, or relative to the repository root.	in-repository: "docs/MESH.md"outside: "/nonexistent/outside.txt"
session	string	no	The writing session's id on the mesh (`claude-code-<session id>` for Claude Code); without it only the active task's scope can cover the write.	in-repository: "claude-code-bench"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/guard/edit?path=docs%2FMESH.md&session=claude-code-bench"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	EditVerdict	Judge one edit: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

EditVerdict

object

The answer to one edit: whether it may proceed, the one word it was decided on, the sentence a person reads and, for a refusal, what would allow it. guard.edit returns it as it is; guard hook turns it into an exit code.

use majordomus_cli::guard::{judge_facts, ClaimSource, EditFacts, EditVerdict};

let facts = EditFacts {
    required: Ok(false),
    mesh_enabled: true,
    task: None,
    session: None,
    claims: ClaimSource::Claims(vec![]),
};
let v: EditVerdict = judge_facts("a.md", Some("a.md"), facts);
assert!(v.allowed);
assert_eq!(v.ground, "off");
let json = serde_json::to_value(&v).unwrap();
assert!(json.get("remedy").is_none(), "an allowed edit carries no remedy");

property	type	required	description
allowed	boolean	yes	Whether the edit may proceed.
path	string	yes	The path asked about, repository-relative when it is inside the checkout.
ground	string	yes	Why, as one word: `off`, `outside`, `local`, `no_mesh`, `task`, `claim`, `undecided` or `unclaimed`. Only `unclaimed` refuses.
detail	string	yes	The sentence a person reads.
remedy	string \| null	no	What makes the edit allowed, when it is refused.

Used by guard.edit