> 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/boundry.md). # Boundry ## How the boundary works Warrant is a local execution gateway, not a prompt filter. It mediates a small typed operation set and owns the transition from an agent request to a workspace side effect. ``` Claude / Codex / Grok / Hermes / OpenClaw / PicoClaw | managed shim launch | agent-specific tool closure + authenticated MCP | v local Warrant daemon schema -> policy -> approval -> exact action | v workspace actuator | v integrity trace ``` The boundary is valid only for a managed launch. Invoking the original agent binary directly is outside it. ### Setup binds one workspace `warrant setup ` performs a qualification step before installing the shim: 1. It resolves the exact current directory; no repository-root inference occurs. 2. It discovers the real agent outside Warrant's shim directory. 3. It probes the supported version in a sanitized environment. 4. It measures the agent bytes and, for script launchers, the exact interpreter and launcher arguments. 5. It compiles the selected local policy to canonical JSON and a SHA-256 identity. 6. It materializes the agent-specific hook/MCP/configuration contract in owner-private state. 7. It commits those values, Warrant's runner, the workspace, and the managed shim to the installation record. Setup fails instead of guessing when a path, version, policy, configuration, owner authority, or launcher cannot be established safely. ### Launch rechecks the evidence The managed shell command routes through Warrant's native runner. Before starting the agent it rechecks: * the workspace identity; * agent profile and supported version; * agent executable bytes and closed path; * launcher and interpreter bytes where applicable; * Warrant runner and shim bytes; * canonical policy bytes and hash; * generated hook, MCP, and agent configuration; * local owner authority and private state permissions. Warrant then builds a minimal environment, creates isolated profile state where the adapter requires it, opens a time-bounded authenticated local session, and starts the agent with a closed argument grammar. The session seal commits the runner, agent, configuration, MCP route, workspace, policy, operation catalog, actuator, verifier, environment, and known containment gaps. Any mismatch denies launch. Re-running setup after an intentional upgrade creates new evidence; old evidence is not silently carried forward. ### The narrow operation surface The managed MCP route exposes five tools: | Tool | Boundary operation | Result | | ---------------- | ---------------------------------------------------- | ---------------------------------------------------- | | `list_files` | `workspace.list_files` | Bounded recursive metadata for allowed regular files | | `read_file` | `workspace.read_file` | Exact bounded UTF-8 bytes from one allowed file | | `search_text` | `workspace.search_text` | Bounded literal-text matches; no regex or shell | | `request_action` | A closed action proposal, including supported writes | Deny, hold for approval, or execute through Warrant | | `action_status` | Status lookup for the same runtime session | Safe status only; never executes an action | Tool schemas reject unknown fields. Paths are canonical workspace-relative values. Traversal, symlinks, hardlinks, special files, cross-device escape, unsafe file drift, and oversized inputs fail closed at the workspace layer. This CLI release has only a workspace actuator. A request for a shell command, network call, delete, rename, package install, Kubernetes operation, database command, or cloud action is not mapped to a local actuator and cannot become an allowed local side effect. ### Read sequence For an allowed read: ``` agent read_file -> closed MCP validation -> authenticated session identity -> typed workspace proposal -> policy path decision -> descriptor-anchored read -> bounded result returned to the same session ``` Read bytes are returned to the agent because that is the requested operation. Audit records carry commitments and metadata rather than copying the file content into the trace. Once the agent receives content, its configured model provider may also receive it; Warrant is not an inference privacy proxy. ### Write and approval sequence Local policy permits only `approval_required` or `deny` for writes. There is no template that grants an agent autonomous workspace writes. ``` agent request_action + exact artifact -> closed proposal and artifact validation -> policy operation/path decision -> pending owner approval -> local review of path, risk, bytes, and preimage -> approve or reject -> preimage and evidence recheck -> exact workspace actuator call -> terminal result and trace transition ``` The artifact envelope commits the exact content bytes, logical name, media type, and SHA-256. Approval is action-specific and idempotent: retrying one logical action does not create permission for a second write. A changed target preimage, stale session, policy drift, or evidence mismatch denies execution. Automation files are classified separately so policy can deny them even when normal documentation or source writes are approval-gated. The agent cannot lower that classification by changing its summary or claimed risk. Review actions with: ```sh warrant approvals warrant approve warrant reject ``` ### Hook and MCP roles The exact integration differs by agent: * Claude and Codex use hooks to deny native tool paths and use MCP for typed operations. * Hermes selects only the `mcp-warrant` toolset; its non-blocking hooks are not trusted. * OpenClaw and PicoClaw replace native/plugin tool authority with a Warrant-only MCP set. * Grok Build uses an empty current workspace plus a hash-bound Warrant-only agent definition for both interactive and headless modes. MCP authentication proves that a call belongs to the opened local session. MCP alone does not contain the host process; agent-specific tool closure and the managed shim are also required. Even together, they remain an application boundary rather than an OS sandbox. ### Audit and trace integrity Meaningful proposal, decision, approval, execution, and result transitions append to a Merkle-style integrity trace signed from owner-private installation material. Approval results expose the resulting audit root, and action status is available to the managed session. This detects accidental or untrusted trace mutation within the application model; it does not make state immutable against the same host owner who controls Warrant's files and process. The v0.3.0 CLI also does not expose a general user-facing audit-export command, so treat complete local audit export as unfinished product surface. ### Why drift stops execution Policy evaluation and actuation are bound to the same live evidence. If an agent, interpreter, shim, Warrant runtime, policy, generated config, session handle, catalog, or actuator identity changes, Warrant cannot prove that the reviewed operation still matches the executable state. The safe response is denial followed by explicit requalification: ```sh warrant doctor warrant setup --policy warrant doctor ``` That failure direction is the core difference between this boundary and a regex check that merely scans a command string without controlling the operation that executes. --- # 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/boundry.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.