sondera-coding-agent-hooks: Instructions file for Codex

AGENTS.md

Rust workspace: a reference monitor for AI coding agents. Hook adapters normalize each agent's events, a gRPC harness adjudicates them against Cedar policies, and the decision goes back to the agent.

Commands

The local gate is fmt plus clippy scoped to what you touched. Run these, and only these, before handing work back:

cargo fmt --all                                       # no build; sub-second
cargo clippy -p <crate> --all-targets -- -D warnings  # once per crate you changed

cargo check -p <crate> is the faster signal while iterating; clippy subsumes it at the end.

Run only when the change calls for it:

cargo doc --no-deps -p <crate>   # you renamed a public item or edited a [`Type`] link

Leave these to CI unless you are explicitly asked to run them. Each is a full workspace build and is not part of the local loop:

cargo clippy --all-features -- -D warnings         # the gate CI enforces
cargo doc --no-deps --workspace                    # CI enforces doc links
cargo test --workspace                             # CI runs this

A cold target/ — first build after a branch switch or a cargo update — makes even a scoped clippy take minutes. That is the build, not the gate: do not respond to it by skipping the gate or by widening the scope to amortize it.

Provider-gated integration tests are #[ignore]d and need a live model provider. Do not enable them to "check your work"; CI does not run them either.

Run the stack locally:

cargo run -p sondera -- serve -v                   # harness + console gRPC on 127.0.0.1:50051
cargo run -p sondera -- tui                        # read-only view of a running server
cargo run -p sondera -- hook claude install        # wire hooks into .claude/settings.local.json
cargo run -p sondera -- mcp                        # Cedar policy-authoring MCP server on stdio

Where things live

You're changing	Go to	Read first
A Cedar policy or the schema	.sondera/policies/cedar/	.agents/skills/autoformalize/SKILL.md
How an event becomes a Cedar context	crates/policy/cedar/src/transform.rs	base.cedarschema, which documents every field
One agent's hook wiring or response shape	crates/hooks/<provider>/	crates/hooks/README.md
Behaviour shared by all providers	crates/hooks/core/	same
Domain types crossing crate boundaries	crates/types/	—
Shared LLM provider support	crates/provider/	crates/provider/src/lib.rs
What .sondera/ means and how it resolves	crates/settings/	crates/settings/src/lib.rs, which owns the config semantics
The gRPC wire format	crates/schema/proto/	regenerate via crates/schema/build.rs