Why Seal exists

Seal gives a project an explicit snapshot of its installed agent files and a command to check that snapshot. It is most useful when those files can change independently of the review that approved them: through installers, local edits, generated files, or updates to third-party bundles.

If I already use Git, what does Seal add?

Git already records file contents and supports reviewed changes. If all your agent files are tracked, reviewed, and used from a clean checkout, a Git-based check may be enough. Seal adds a dedicated manifest, bundle-level reporting, and a consistent pin/verify workflow across selected agent assets.

The difference is the baseline being checked:

• Git status compares the working tree, index, and HEAD. Untracked files are normally reported; ignored files are excluded unless requested. A clean checkout describes its relationship to a commit, not whether that commit was approved.
• Seal verify compares local bundle contents against seal.json, regardless of whether those files are tracked by Git. It also discovers new bundles under the configured discovery patterns. Files ignored by Git are still hashed when they are inside a sealed root, apart from Seal’s explicit exclusions such as .git metadata.

A carefully configured Git check can cover much of the same ground. Seal packages a specific approval-snapshot workflow; it does not make Git’s integrity guarantees obsolete. See the Git status documentation for its exact behavior.

A concrete workflow

Suppose your team reviews .agents/skills/code-review/, including SKILL.md and scripts/review.sh.

1. Run seal init, inspect the proposed .agents/skills/* discovery pattern, and review and commit the generated lockfile.
2. An installer later changes scripts/review.sh without updating the approved snapshot.
3. Run seal verify after installation and before the pipeline uses those files. The bundle reports Mismatch and verification exits 1 under the default block policy.
4. If the update is intentional, review its contents, run seal pin .agents/skills/code-review, and review the lockfile diff before committing it.

A new skill under .agents/skills/* is Unverified until pinned. A new skill somewhere outside the configured discovery paths is outside the CLI’s coverage.

The CLI checks files when invoked. It does not intercept agent loads or protect against subsequent writes. Native integration is required to enforce verification immediately before loading.

Alternatives and complementary controls

Approach	What it controls	How Seal fits
Git review and clean-checkout checks	Versioned contents, change history, and working-tree drift.	Seal adds a dedicated snapshot for chosen installed bundles. Git can be sufficient when the entire workflow already stays within reviewed commits.
Read-only files or mounts	Whether a process can write to a location.	Seal checks the bytes currently there. Permissions and integrity checks answer different questions and can be used together.
dotagents and other package managers	Declaring, fetching, installing, and synchronizing agent dependencies.	Seal verifies selected installed project-local files against a separately reviewed content baseline.
Dependency and build systems	Resolving and pinning inputs according to their dependency model.	Seal does not resolve dependency graphs or make execution hermetic. It hashes files within configured local roots.

dotagents and agents.lock

Sentry’s dotagents manages agent dependencies and configuration across tools through agents.toml and agents.lock. Its current documented workflow uses install to fetch dependencies and sync to repair local configuration without fetching.

Seal’s workflow starts with files already on disk: review their contents, pin them, and verify them later. It can also cover custom project-local paths such as prompts/review.md, config/agent-hooks/, or tool definitions outside .agents.

The useful distinction is the job each tool performs: dependency management and configuration versus checking an explicit local content baseline. Check the dotagents specification and command reference for its current lockfile and update behavior. For any installer, choose regular-file roots when using Seal v1: Seal rejects symlinks.

What about a pinned script that runs curl to bash?

If a reviewed script later downloads and executes a different remote payload, its local bytes may be unchanged. Seal can still report Verified because the downloaded payload is outside that sealed root.

Seal v1 does not inspect code for dependencies, follow remote references, or pin the complete execution chain. Files under a sealed root are covered, including vendored dependencies; files outside it and remote responses are not covered by that entry. See the threat model.

Where approval comes from

seal.json is the content baseline, and your review process establishes whether to trust it. Protect changes to the bundle files, hashes, discovery, policy, and verification workflow with the appropriate repository review and access controls.

If someone changes a bundle and updates its hashes in the same pull request, verification can pass. The tool cannot tell whether those changes were approved. Review the source changes before re-pinning, then review the lockfile diff as part of the same change.

Why a specification, not a single tool

Seal defines a shared lockfile format and deterministic verification rules. The CLI implements local pinning and verification; agents and harnesses can implement the load-time enforcement described by the specification.

Native integrations must verify bundles immediately before loading and suppress project-external extensions in sealed projects. Those are requirements for an integration, not side effects of installing the CLI. See agent support and for agent authors.