> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/policies-and-the-pre-push-check.md). # Policies and the pre-push check Policies are configured **on the server**, per repository, not in a file in the repo. The CLI's job is to bring them to the developer in two directions: it injects them into the agent's context so the agent behaves accordingly, and it evaluates the session against them before the code leaves the machine. The policy families are model allowlists, protected paths, token budgets, required tools, and AI-share caps. Which of them are switched on is a property of your deployment, so ask the administrator of your server rather than the CLI. ![The policy list for a repository: what is enforced, and at what severity](https://2686717926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2dUajTQaSdFnN24ip7Qo%2Fuploads%2FPCYnpnOhoEoyNyvb8XiS%2Fpolicies.png?alt=media) ## The agent is told the rules up front Two hooks installed by `tracevault init` handle this, and neither is meant to be run by hand: * `session-start`: exports the session ID and injects the bound repo's policies as additional context at the start of a session * `user-prompt`: re-injects them when the session's effective repo has changed since the last injection, which matters in [workspace mode](/visdom-tracing/user-guide/workspace-mode-headless-and-multi-repo-agents.md) For anything else that needs the same text (a `CLAUDE.md`, an `AGENTS.md`, another harness) `tracevault agent-policies` fetches the rendered, agent-readable instructions for the current repo and prints them to stdout. ## The pre-push check `tracevault check` runs from `.git/hooks/pre-push`. It reads git's pre-push protocol on stdin, works out which sessions are unpushed and which files the pushed refs touch, sends that to the server, and prints the verdict. ``` Checking 3 session(s) against policies... All policy checks passed. ``` There are three outcomes, and the distinction matters when you are deciding how aggressively to configure a first deployment: * **passed**: nothing to say, the push proceeds * **warnings**: findings are printed, the push still proceeds * **blocked**: the check exits non-zero and git refuses the push The file set the check reports is deliberately over-inclusive. A larger set only means less pruning of AI-touched paths; it never means a missed violation. Branch deletions are dropped, since no content is being pushed for them, and malformed lines in git's stdin are skipped rather than treated as an error, because a parse bug must never be the reason a developer cannot push. {% hint style="danger" %} **A blocked push is the most visible thing the component ever does.** Turn policies on after the team can already see its own sessions in the UI. Enforcement introduced before anyone has watched the capture work reads as a tool that broke git, not as governance. {% endhint %} Policies themselves are written on the server, one rule at a time, with the severity that decides whether a push is warned or blocked. ![Creating a policy: family, scope and severity](https://2686717926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2dUajTQaSdFnN24ip7Qo%2Fuploads%2FP10iH857hz7r4GUAKK58%2Fpolicies-create.png?alt=media) ## Verification phases Some policies should only apply to what the agent did **after** it stopped writing code: "the tests were actually run" is a different claim from "the tests exist". `tracevault verify-start` opens a verification phase for the session: it declares that changes are finished and quality checks have begun, and only tool calls made after that point are evaluated by verification-phase-scoped policies. Calling it again resets the phase and discards the earlier verification events, so it is safe to re-run when a check loop starts over. In single-agent setups the session is detected automatically; with several agents running, pass `--session-id` to target the right one. --- # 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://docs.visdom.virtuslab.com/visdom-tracing/user-guide/policies-and-the-pre-push-check.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.