Developing Shield
Shield is one Cargo package (canonic-shield), library shield, and executable
shield. Rust 1.99.0 is pinned with rustfmt, Clippy and llvm-tools. Cargo.lock
owns dependency versions; there is no root Cargo workspace.
Fast iteration
From this package directory:
make dev
make test-focus FILTER='policy::'
# Select integration tests explicitly when needed:
make test-focus FILTER='selected_test_name' TEST_TARGET='--test integration'
dev writes an incremental build to target/debug/shield; run it directly to
try changes. test-focus uses nextest with a required substring filter and
defaults to library tests. Replace the integration example’s placeholder with
a real test name; nextest fails if nothing matches.
Keep target/ between iterations to reuse Cargo’s cache. Use release builds
for performance measurements.
Source ownership
Shield separates policy decisions from filesystem observations, host adapters, and operator workflows. Start with the module for the behavior you are changing:
| Area | Source |
|---|---|
| Operator commands and routing | src/cli/public.rs, src/cli.rs, src/lib.rs |
| Policy documents, selectors, requirements | src/policy.rs, policy/model.rs, policy/rules.rs, policy/argument_rules.rs |
| Typed requests and resource-evidence interface | policy/normalized.rs, policy/resources.rs |
| Filesystem observations and supported command effects | src/location.rs, location/text.rs, location/node.rs |
| Shell parsing, expansion, control flow, and PID provenance | src/shell.rs and shell/ |
| Declared directory options | policy/directories.rs |
| Compiled plans, indexes, and policy comparison | policy/compiled.rs, policy/index.rs, policy/partition.rs, policy/profile_comparison.rs, policy/symbolic.rs |
| Project composition, captured source, and evaluation | src/configuration.rs and configuration/ |
| Shared project, policy and request inspection | review/project.rs, review/history.rs, review/approvals.rs |
| Pack discovery, acquisition and candidate preparation | review/packs.rs, review/packs/, review/registries.rs |
| Confirmed publication and project-file repair | review/publication.rs, review/publication/projections.rs, review/changes/diff.rs |
| CLI questions, reviews and confirmation | review/operator/ |
| Agent configuration ownership and repair mechanics | review/integrations.rs, review/integrations/, review/path_access.rs |
| Approval clocks and request-specific grants | review/clock.rs, review/read_approval.rs, review/run_approval.rs |
| Durable source, disposable cache, and history | review/storage/sources.rs, review/cache.rs, review/storage/history.rs, history/correlation.rs |
| Agent payloads, setup codecs, and replies | src/agents.rs, agents/claude_code.rs, agents/codex.rs, agents/setup.rs |
| Shared hook dispatch and feedback | agents/hook.rs, agents/feedback.rs, src/agent_message.rs |
| Host-specific MCP confirmation | agents/review.rs, agents/*/review.rs |
| MCP startup, transport handler, and output | src/mcp_io.rs, src/mcp.rs, mcp/response.rs, mcp/messages.rs |
| MCP tools, schemas, snapshots, and cursors | review/mcp/ |
| Bundled Markdown guides | build.rs, review/mcp/documentation.rs |
| Runtime snapshots and protected handoff | src/runtime.rs, review/runtime/consumer.rs, src/enforcement.rs |
| Supported native launches and cleanup | src/execution.rs and execution/ |
| Document validation and pack fixtures | src/application.rs |
| Private process diagnostics | src/diagnostics.rs |
CLI and MCP map their inputs into shared review operations. History queries use an application-owned query type; pack operations expose direct list, show, search, info and preparation functions. Shared owners can read files and acquire registry artifacts, including retaining verification checkpoints, without opening a terminal. CLI prompts and host confirmation run before calling the common publication workflow. MCP retains its own paging, diagnostic handles and response projection.
The policy core performs no filesystem I/O and contains no command permission
tables. Packs and custom rules supply permissions; location/ supplies fresh
request facts. Shell analysis uses submitted source and available context,
without attesting execution.
build.rs compresses the guides into one DEFLATE bundle in OUT_DIR, with a
page-range index. Docs tools decompress it in memory when called. Both steps
use pure Rust code; no host compression tools or shared libraries are needed.
The canonic-registry dependency handles registry identity, authentication,
acquisition, checkpoints, resolution, and UTC timestamps. Shield owns pack
declarations and the review that activates acquired artifacts. canonic-mcp
handles framing, lifecycle, validation, cancellation, deadlines, and confirmation
requests; Shield’s handler supplies its tools and limits.
Agent adapters translate vendor payloads and setup formats. They cannot bypass
core policy or activation checks. To add an agent, implement its adapter and
registry entry, then verify payload mapping, setup, and real host behavior.
CLI detection belongs in the adapter’s is_installed method; it inspects PATH
without starting the tool.
adapters/ contains private Node 24+ ESM modules: process-transport/ handles
subprocess I/O and cancellation, enforcement-response/ validates receipts,
and claude-read-only/ maps SDK callbacks. adapters/sdk-tests/ pins the SDK
dependencies. Rust integration tests share tests/integration/main.rs.
Check tools
Install the developer tools:
cargo install --locked cargo-nextest@0.9.146 cargo-deny@0.20.2 cargo-llvm-cov@0.9.1 cargo-insta@1.49.0
Tests use assert_cmd, assert_fs, predicates, insta, and proptest. Tool versions and dependencies are pinned in the package configuration.
Checks
The default nextest profile runs four tests at a time. Run process-heavy Node, SDK and Rust suites separately so fixture startup does not compete across runners. Do not rebuild a shared executable while installation fixtures run: registrations pin its digest, and replacing it changes the fixture’s protection diagnostics. In an agent sandbox, request host access before running integration checks: PTY fixtures need controlling terminals and process signals, HTTP/TLS fixtures need loopback listeners, and cargo-deny needs its advisory cache. A sandbox permission refusal requires the same check with host access; product policy changes cannot grant that access.
Run the Make targets below from this package directory, where rustup selects the pinned toolchain.
cargo test --locked also runs the behavioral tests. cargo llvm-cov nextest --locked produces a coverage report; it is not a coverage threshold. Cargo
nextest, deny, and llvm-cov are optional developer tools installed separately.
Use ~/.cargo/bin/cargo when Cargo is not on PATH and --offline only with a
populated dependency cache.
| Area | Configuration and behavior |
|---|---|
| Lint | Manifest-owned unsafe-code prohibition, unreachable-public-item warnings, Clippy pedantic/unwrap/self-named-module checks; warnings fail the check |
| Test runner | nextest reports every failure; slow tests are flagged after 30 seconds and terminated after two minutes |
| CLI fixtures | assert_cmd/predicates check status/output; assert_fs owns temporary projects and cleanup |
| Property tests | proptest exercises unknown-command refusal and literal argv exact-match boundaries |
| Snapshots | insta records command help and settled human output under tests/integration/ |
| API docs | [lints.rustdoc] in Cargo.toml: a doc comment linking to a missing or private item fails cargo doc |
| Dependencies | cargo-deny checks advisories, licenses, duplicate versions, and crates.io-only sources; wildcard versions fail |
| Coverage | cargo-llvm-cov reports line, region, and function coverage; no minimum threshold |
Clippy’s too_many_lines remains enabled. Use narrow
#[expect(..., reason = "...")] annotations when justified. Public fallible APIs
must document their errors.
Failure fixtures control transport timing while keeping evaluation and subprocess I/O real. Wait for readiness before measuring deadlines, and keep setup budgets separate from cleanup assertions. SDK acceptance uses production deadlines.
Output review and deeper testing
For intended output changes, run cargo insta test, then cargo insta review
and commit the reviewed snapshots. Snapshots complement status and filesystem
assertions; they do not replace them. Keep paths and secrets out of snapshots;
insta filters are available when context-dependent output is implemented.
Human-output fixtures drive the shared TUI in an owned terminal and snapshot
settled reviews, choices and results. Separate terminal tests verify live regions,
input safety and mode restoration.
cargo llvm-cov nextest --locked --html writes a browsable report under
target/llvm-cov/html/. Generated API documentation is written to target/doc/. Reports and generated
docs remain under ignored target/.
Local build and adapter checks
From the repository root:
make -C packages/shield build
npm --prefix packages/shield/adapters test
npm --prefix packages/shield/adapters/sdk-tests test
make -C packages/shield install-local installs into ~/.local/bin; PREFIX
selects another root. From this package use make build and make install-local.
CARGO overrides Cargo discovery and CARGO_FLAGS=--offline uses cached dependencies.
Make prefers ~/.cargo/bin/cargo so rustup selects the pinned toolchain,
falling back to Cargo on PATH.
Debug builds and diagnostics
make -C packages/shield build-debug builds target/diagnostic/shield with release
optimization, debug symbols, debug assertions and automatic JSONL logging. Native
hook deadlines also apply to diagnostic builds. make -C packages/shield install-local-debug
installs that build into ~/.local/bin. make -C packages/shield install-local
installs the release build, which has logging disabled by default. After replacing
the installed executable, run shield mcp setup --agent codex --project /path/to/project
(or --agent claude) to refresh its pinned digest, then restart the agent.
Automatic logs live in the OS temporary directory under
shield-logs/shield-<timestamp>-<pid>.jsonl. On macOS, inspect them with
ls -lt "${TMPDIR%/}/shield-logs". Each native hook gets its own file; the MCP
server keeps a file for its process lifetime. Operator commands print their log
path on stderr. Native hooks and MCP omit that startup message so protocol output
and ordinary agent feedback remain clean.
MCP frame logging uses a separate worker with an eight-frame queue. The dispatcher submits frames without waiting for parsing or file writes; a full queue drops diagnostic frames. Tool names are cached once per process. The logging worker drains accepted frames and is joined when its observer is dropped, so slow storage can delay shutdown but does not block live ping or cancellation dispatch. Frame sizes remain bounded by the MCP input and output limits.
Both builds accept --debug-log-dir DIRECTORY to enable logging into another
directory and --no-debug-log to disable it. SHIELD_DEBUG_LOG_DIR also selects
the directory for child processes that inherit it; export it before starting the
agent. Hosts can filter child environments. The CLI directory overrides the environment, and opt-out overrides the
environment and debug default. Shield uses a directory rather than a single
file because concurrent native callbacks start separate processes.
Files are uniquely created, use mode 0600 on Unix, and stop at 8 MiB with a limit marker. Logs remain until you delete them or the OS clears temporary files; total directory size is not automatically capped. A logging failure reports a warning on stderr and disables logging without changing authorization or transport output.
Records include elapsed milliseconds and PID/version/build type,
native agent/event/tool and session/turn/tool-call IDs, captured input bytes,
input validity and overflow, project/snapshot preparation, evaluation, native
handoff and history stage timings, policy decision/fallback/disposition, completion
history status, response event/decision/context shape, and MCP method/tool/ID,
request/response sizes and error status. Commands, arguments, tool results,
policy content, credentials and raw error text are omitted. Large truncated hook
input cannot supply parsed IDs; its overflow and captured size are still recorded.
Pair input/output records by PID and MCP messages by request ID to inspect timing.
These logs are diagnostic evidence, separate from request history and execution
attestation. RUST_BACKTRACE=1 enables panic backtraces on stderr; debug symbols
also support native debuggers.
Adapter and host checks
The dependency-free adapter suite requires the actual package release executable.
The SDK runner executes one test file at a time; each file retains its own
concurrency assertions and owns its host processes and loopback provider.
Codex fixtures disable plugin discovery in their isolated host so background
marketplace clones cannot race project cleanup. Their teardown closes the local
provider before removing the project, including after a failed assertion.
The SDK suite uses locked MCP SDK 1.32.1 and Claude Agent SDK 0.3.292 dependencies.
Its temporary projects and scripted loopback provider exercise canonical MCP
inspection/proposals, dense deadline/cancellation behavior, supported native reads,
exact retries, state/operator refusals, host discovery and completion privacy. Native command-hook fixtures also exercise
Claude native Ask permission callbacks (approval and refusal), policy Deny bypassing
ordinary approval, Codex approval-unavailable blocking, explicit denial, startup
failure, and the host’s timeout continuation boundary. Confirmed automatic Ask
allowance has distinct history/dispatch assertions. Codex’s unsupported Ask and
ignored approval-field rewrites have separate disposable marker probes.
PermissionRequest boundary tests cover complete-context Allow, Ask abstention,
Deny, missing IDs and workdir, mixed batches and event-pinned input failures.
Codex shell approval with an omitted workdir uses reported session cwd and follows
policy Allow, Ask or Deny. Missing context remains recorded independently of handoff.
Do not describe callback translation as a verified human approval flow.
adapters/sdk-tests/claude-interactive.test.mjs separately runs the installed
Claude CLI in an owned PTY with the ordinary terminal renderer. Its local provider
requests policy apply in auto and bypassPermissions; actual keyboard input
answers Accept, Decline and Escape. The fixture observes the host’s permission
mode and verifies unchanged policy while input is withheld. It uses neither an
SDK elicitation callback nor an Elicitation hook. Run it independently with
node --test --test-concurrency=1 packages/shield/adapters/sdk-tests/claude-interactive.test.mjs
after make -C packages/shield build. It requires the installed claude command,
Python 3, PTYs, loopback access and permission to reap its owned child processes.
For a fresh checkout install SDK test dependencies with
npm --prefix packages/shield/adapters/sdk-tests ci --ignore-scripts --no-fund --no-audit.
Native host checks are verified on macOS; Linux/Windows behavior is unverified.
Individual Rust verification
Choose the checks needed for your change; there is no aggregate target.
docs generates HTML in target/doc/; doctest runs documentation examples.
Rustdoc may recheck dependencies even with --no-deps, which only suppresses
their generated pages. Keep Cargo caches between runs.
| Category | Command from this package |
|---|---|
| Apply formatting | make format |
| Verify formatting | make format-check |
| Strict Clippy | make lint |
| Type checking | make types |
| Tests | make test |
| Documentation examples | make doctest |
| API reference HTML | make docs |
| Dependency audit | make deps |
make format FORMAT_FILES='src/cli/public.rs' formats the named files and their
out-of-line child modules. Name only leaf files (files with no out-of-line child
modules) to keep edits limited to those files. For example, naming src/agents.rs
also formats modules under src/agents/.