glove/AGENTS.md

description	argument-hint
Glove repository supplement for security-sensitive C++ work	[TASK=<description>] [PHASE=<start|checkpoint|complete>]

Glove contributor instructions

Glove contains untrusted agent processes with platform sandboxing and mediates their tool access. Security-sensitive changes must preserve fail-closed behavior and the documented capability boundary.

The retrieval, execution, checkpoint, and handoff contract is in docs/prompts/PROMPT-eng-codex.md. This file contains only Glove-specific rules and validation requirements.

Read docs/architecture.md before changing process, filesystem, control, or protocol boundaries. Read docs/threat-model.md before changing an enforcement claim.

Repository rules

• Read affected code and tests before editing.
• Keep patches small and reversible.
• Do not add dependencies or push commits without explicit approval.
• Do not weaken a sanitizer, warning, policy, permission, limit, or validation check to make a test pass.
• Do not add a TODO or FIXME without a named owner and concrete reason.
• Treat paths, JSON-RPC frames, session plans, journals, receipts, terminal bytes, and agent output as untrusted input.
• Capability discovery must report constructed enforcement, not planned work.

Required gate

Run:

./scripts/preflight.sh

It must complete all stages:

1. actionlint 1.7.12;
2. clang-format 22.1.8;
3. clang-tidy over the configured compilation database;
4. ASan and UBSan build and tests;
5. TSan build and tests.

For narrow iteration:

cmake --preset dev
cmake --build --preset dev
ctest --preset dev

Linux namespace and mount tests may require the provided privileged Docker environment. Do not treat a skipped platform test as evidence for that platform.

Code conventions

• Compile as C++23; isolate experimental reflection behind its build option.
• Use .hpp for headers and .cpp for sources.
• Put public headers under include/glove/<module>/ and mirror modules in src/.
• Use glove::<module> namespaces.
• Use value semantics and RAII. Raw delete is forbidden. Raw new is allowed only in a private-constructor factory when immediately owned by std::unique_ptr.
• Use std::expected<T, E> at recoverable module boundaries. Exceptions are reserved for invariant violations and top-level containment.
• Prefer std::jthread and std::stop_token where cooperative cancellation fits. Make other thread shutdown and join ownership explicit.
• Bound allocations, frame sizes, collections, retries, deadlines, and journal growth at trust boundaries.
• Resolve security-sensitive filesystem objects through descriptors. Reject symlinks, identity drift, unsafe ownership/mode/link count, and path overlap.
• Never use PID alone as process identity.
• Comments explain invariants and rationale, not line-by-line behavior.

Layout

Path	Purpose
include/glove/	public module headers
src/container/	platform sandbox, limits, output, receipts
src/control/	Unix protocol, sessions, lifecycle, recovery
src/supervisor/	canonical plans, aliases, bundles
src/mcp/	bounded MCP and JSON-RPC transport
src/policy/	tool and argument authorization
src/kernel/	extension dispatch
src/audit/	local activity records
tests/	CTest targets organized by module
cmake/	warnings, sanitizers, dependencies
scripts/preflight.sh	repository gate

Change checklist

For a new control method or capability:

1. define a strict bounded wire type;
2. authenticate before state access;
3. specify idempotency and timeout behavior;
4. enforce the operation in the owning module;
5. make persistence and crash recovery explicit;
6. advertise the capability only when its dependencies are constructed;
7. add malformed-input, denial, replay, concurrency, and recovery tests;
8. update architecture, session policy, and threat model if a guarantee changes.

For a new MCP tool, add the typed descriptor, registration, policy tests, dispatch tests, and audit assertions. Glaze remains a private implementation dependency; public headers must not require it.