> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/policies.md). # Policies ## Policies Local policies answer one narrow question: which typed workspace operation may this managed agent request, on which path, and must a write wait for the local owner? They are local JSON documents. There is no tenant URL, hosted policy API, or Warrant account in this flow. ### Built-in templates The v0.3.0 Homebrew package ships five templates. Current source adds the sixth, `privacy-locked`. | Template | Availability | Reads | Standard writes | Automation-file writes | | ----------------------- | -------------- | ----------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------- | | `read-only` | v0.3.0 | Entire workspace | Denied | Denied | | `privacy-locked` | Source preview | Exact `README.md`; list, search, and read under `docs/`, `src/`, and `tests/` | Denied | Denied | | `owner-approved` | v0.3.0 | Entire workspace | Owner approval, entire workspace | Owner approval, entire workspace | | `docs-only` | v0.3.0 | Read `README.md`; list, search, and read under `docs/` | Owner approval for `README.md` and `docs/` | Denied | | `workspace-development` | v0.3.0 | Entire workspace | Owner approval under `docs/`, `src/`, and `tests/` | Denied | | `automation-locked` | v0.3.0 | Entire workspace | Owner approval, entire workspace | Denied | The closed policy operation set cannot express raw shell or unmanaged MCP calls. The agent adapters separately close those native tool surfaces. A template is a starting authority set, not an intent detector or OS sandbox. Inspect the catalog and exact JSON before selecting a policy: ```sh warrant policies list warrant policies show read-only warrant policies show workspace-development ``` ### Select, switch, or lock down Choose a template during initial setup: ```sh cd /absolute/path/to/workspace warrant setup claude --policy read-only ``` Switch the active policy from that same workspace: ```sh warrant policy use owner-approved warrant status claude warrant doctor claude ``` Policy switching recompiles the source, installs canonical bytes, binds the policy ID and SHA-256 into profile evidence, and repeats qualification. It does not loosen an already running session. Return to fail-closed read-only lockdown at any time: ```sh warrant policy disable warrant doctor claude ``` `policy disable` does not turn Warrant off. It keeps the boundary active and changes the selected workspace to read-only. ### Create an editable policy Clone the operation rules from a reviewed template under a new name. The output file must not already exist: ```sh cd /absolute/path/to/workspace warrant policy init docs-only --name my-docs-policy --output warrant-policy.json ``` Edit the file, then validate, compare, and activate it: ```sh warrant policy validate warrant-policy.json warrant policy diff warrant-policy.json warrant policy use warrant-policy.json warrant status claude warrant doctor claude ``` Edits to the source file do not silently change active authority. Run `policy use` again to compile and bind reviewed changes. You can also select the file during setup: ```sh warrant setup claude --policy warrant-policy.json ``` Custom names cannot impersonate a built-in template. If a file uses a built-in name, its semantics must exactly match that built-in policy. ### Closed JSON v2 schema The top-level object has exactly three fields: | Field | Required value | | ---------------- | -------------------------------------------- | | `schema_version` | `warrant.local_policy.v2` | | `name` | Lowercase ASCII letters, digits, and hyphens | | `operations` | Exactly the five operation objects below | The complete operation set is: | Operation | Decisions | | --------------------------------- | --------------------------- | | `workspace.list_files` | `allow`, `deny` | | `workspace.read_file` | `allow`, `deny` | | `workspace.search_text` | `allow`, `deny` | | `workspace.write_file` | `approval_required`, `deny` | | `workspace.write_automation_file` | `approval_required`, `deny` | Every operation object has only `decision` and `paths`. `paths` has exactly two required arrays: nonempty `include` and `exclude`, which may be empty. This is a complete valid custom policy: ```json { "schema_version": "warrant.local_policy.v2", "name": "my-docs-policy", "operations": { "workspace.list_files": { "decision": "allow", "paths": { "include": [{"kind": "subtree", "path": "docs"}], "exclude": [] } }, "workspace.read_file": { "decision": "allow", "paths": { "include": [ {"kind": "exact", "path": "README.md"}, {"kind": "subtree", "path": "docs"} ], "exclude": [] } }, "workspace.search_text": { "decision": "allow", "paths": { "include": [{"kind": "subtree", "path": "docs"}], "exclude": [] } }, "workspace.write_file": { "decision": "approval_required", "paths": { "include": [ {"kind": "exact", "path": "README.md"}, {"kind": "subtree", "path": "docs"} ], "exclude": [] } }, "workspace.write_automation_file": { "decision": "deny", "paths": { "include": [{"kind": "subtree", "path": "."}], "exclude": [] } } } } ``` Unknown fields, missing operations, unsupported decisions, duplicate JSON keys, and invalid paths fail validation. `policy validate` also tells you when deterministic normalization is required. ### Exact and subtree paths Scopes are typed workspace-relative POSIX paths: ```json {"kind": "exact", "path": "README.md"} ``` matches only `README.md`, while: ```json {"kind": "subtree", "path": "docs"} ``` matches `docs` and every descendant. Use `.` for the entire workspace. Absolute paths, backslashes, empty segments, embedded `.` or `..` segments, and trailing slashes are rejected. Regex and glob matching are not supported; metacharacters that are valid path bytes are treated literally. Includes are case-exact. On macOS, exclusions are checked conservatively for case aliases so alternate casing cannot reopen authority. A request must match an include, and any matching exclusion wins. Recursive `workspace.list_files` and `workspace.search_text` includes must be `subtree` scopes because one request can return descendants. The current actuator does not prune excluded descendants out of a larger recursive result. If an exclusion exists below the requested list/search root, the whole ancestor traversal denies. For example, excluding `docs/private/secret.md` makes a search rooted at `docs` deny as one unit. Exact reads of allowed siblings can still succeed. ### `privacy-locked` and secrets `privacy-locked` denies root traversal, root `.git`, root `.env`, root `.github`, and other root configuration by omission. It permits `README.md` and the complete `docs/`, `src/`, and `tests/` subtrees. It is not a secret classifier. A nested file such as `src/.env` is inside an allowed subtree and remains readable. Create a custom policy with an exact or subtree exclusion for every sensitive nested path. Remember that such an exclusion also makes an ancestor list/search deny under the conservative traversal rule. The policy controls only operations routed through Warrant. It cannot stop an unmanaged same-user process from reading the host filesystem or sending data over the network. See Security model. ### Approvals Only write rules can use `approval_required`. Reads are either allowed or denied; the current schema does not approval-gate reads. Review pending writes locally: ```sh warrant approvals warrant approve # Or: warrant reject ``` The review shows the target operation, path parameters, risk, artifact commitment, and preview when available. Approval is scoped to that exact action. It does not grant the agent a reusable write permission or authorize a different path or byte sequence. If the target preimage changes after review, actuation fails closed. High-risk automation writes require the extra confirmation printed by the CLI. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/policies.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.