> ## Documentation Index > Fetch the complete documentation index at: https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Policy > Every capability, how a request is decided, how to write a rule, and what each built-in profile allows # Policy Every action an agent takes is a **request** for a **capability**, with a **target** (the tool, the path, the host, the server). The policy decides each request: **allow** it, **deny** it, or **ask** a person. An ask pauses the run until someone decides ([durable runs](/docs/core-concepts/durable-runs)); the [security model](/docs/core-concepts/security-model) explains the design. ## How a request is decided 1. A **deny** rule that matches wins. 2. Otherwise an **ask** rule that matches: a person decides. An ask outranks an allow, so adding an allow rule to a profile does not lift that profile's asks; remove the ask rule, or write your own policy. 3. Otherwise an **allow** rule that matches. 4. Otherwise the policy's **mode** decides: `permissive` allows, `interactive` asks (reason `unknown_capability`), `strict` denies. A decision is recorded in the run's trace with its `effect` and `reason_code` (`matched_allow`, `matched_ask`, `matched_deny`, `unknown_capability`, `approved` when a person allowed an ask, and others). Two capabilities are decided when the agent connects, not during a run: `mcp.server.start` and `mcp.server.connect`. There is no run to pause then, so an ask on them fails the connection with `ApprovalRequiredError`; allow the servers you trust. The served agent's policy also decides what an operator asks of OmniServe's background API: `background.task.*` and `background.run.*`. A refusal there is an HTTP `403`. ## Writing a rule ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy policy = build_default_policy("interactive-dev") policy.rules.ask.append( PolicyRule( rule_id="ask_before_refunds", effect=PolicyEffect.ASK, capability="tool.local.call", target={"tool_name": "issue_refund"}, ) ) agent_config = {"governance_config": {"enabled": True, "policy": policy}} ``` Or the whole policy as a dict: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "governance_config": { "enabled": True, "policy": { "name": "support-desk", "mode": "strict", # anything no rule covers is denied "rules": { "allow": [{"rule_id": "tools", "capability": "tool.local.call"}], "ask": [ { "rule_id": "refunds", "capability": "tool.local.call", "target": {"tool_name": "issue_refund"}, } ], }, }, } } ``` | Field | What it is | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rule_id` | Your name for the rule; it is recorded with every decision it makes. | | `effect` | `allow`, `ask` or `deny` (the list it is in, for a dict policy). | | `capability` | A capability below, or a glob: `workspace.files.*`, `network.http.*`, `*`. | | `target` | Optional. Any of `tool_name`, `mcp_server`, `path`, `host`, `resource`; each a glob the request's target must match. | | `conditions` | Optional. `risk_level` (list), `provider`, `execution_surface`, `exclude_execution_surface` (list), `exclude_capability` (list of globs), `mcp_server`, `method`, `host`. | | `constraints` | Optional. `approval_expires_seconds` (how long a person's decision stays valid), `sandbox_required`, `audit_required`. | ## Capabilities | Capability | Allowing it lets the agent | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `background.run.cancel` | Cancel a background run. | | `background.run.start` | Start a background run. | | `background.task.create` | Create a background task. | | `background.task.delete` | Delete a background task. | | `background.task.pause` | Pause a background task. | | `background.task.resume` | Resume a background task. | | `background.task.update` | Update a background task. | | `code.run` | Run a program with run\_code (code mode). Each tool it calls is decided on its own. | | `filesystem.delete` | Delete a file on the host, outside the workspace. Target: path. | | `filesystem.read` | Read a file on the host, outside the workspace. Target: path. | | `filesystem.write` | Write a file on the host, outside the workspace. Target: path. | | `mcp.server.connect` | Connect to a remote (SSE or streamable HTTP) MCP server. Decided when the agent connects, like mcp.server.start. Target: mcp\_server. | | `mcp.server.start` | Start a stdio MCP server process. Decided when the agent connects, outside any run: an ask cannot pause there, so it fails the connection. Target: mcp\_server. | | `network.http.delete` | Make an HTTP DELETE request. Target: host. | | `network.http.get` | Make an HTTP GET request. Target: host. | | `network.http.head` | Make an HTTP HEAD request. Target: host. | | `network.http.patch` | Make an HTTP PATCH request. Target: host. | | `network.http.post` | Make an HTTP POST request. Target: host. | | `network.http.put` | Make an HTTP PUT request. Target: host. | | `package.install` | Install a package. Target: resource (the package), host (the index). | | `process.exec` | Run a command: in the sandbox (execution surface sandbox), or on the host with the local provider (surface host). Target: resource (the command's name). | | `sandbox.environment.set` | Set plain environment variables in the sandbox (their names are in the request, not the target). | | `sandbox.execute` | Call the execute tool. Each command it runs is then decided as process.exec. | | `sandbox.filesystem.configure` | Give the sandbox read, write or deny path rules. Target: path. | | `sandbox.filesystem.cwd` | Run a command in a working directory the manifest or call names. Target: path. | | `sandbox.filesystem.mount` | Mount a host directory into the sandbox. Target: path, resource (the source). | | `sandbox.image.use` | Start the sandbox from an image named in the manifest. Target: resource (the image). | | `sandbox.network.configure` | Turn the sandbox's network on, or allow or deny a host in it. Target: host. | | `sandbox.resources.set` | Set the sandbox's CPU, memory, disk or time limits. | | `secret.read` | Read a secret's value. | | `secret.use` | Use a secret without reading it: brokered into a command, never shown to the model. | | `skill.files.read` | Read a skill's instructions and files. | | `skill.script.run` | Run a skill's script (run\_skill\_script): code runs. | | `subagent.spawn` | Start a sub-agent: delegate\_\ to an agent in sub\_agents, or spawn\_subagents. Target: resource (the agent's name). | | `tool.local.call` | Call one of your Python tools (local\_tools), or a sub-agent's delegate\_\ tool. Target: tool\_name. | | `tool.mcp.call` | Call a tool on an MCP server. Target: mcp\_server, tool\_name. | | `workspace.artifacts.call` | Any other artifact tool. | | `workspace.artifacts.read` | Read a saved tool result: read\_artifact, tail\_artifact, search\_artifact, list\_artifacts. | | `workspace.files.call` | Any other workspace file tool. | | `workspace.files.clear` | Delete every file in the workspace (clear\_files). | | `workspace.files.delete` | Delete a workspace file (delete\_file). Target: path. | | `workspace.files.move` | Move or rename a workspace file (move\_file). Target: path. | | `workspace.files.read` | Read the workspace: ls, read\_file, glob, grep. Target: path. | | `workspace.files.write` | Write in the workspace: write\_file, edit\_file, insert\_file. Target: path. | ## Built-in profiles Each profile below is `build_default_policy(name)`. Start from one and add rules, or write your own policy. ### `permissive-dev` Mode `permissive`. | Effect | Rule | Capability | Target | Conditions | | ------ | ------------------------------------------ | --------------------------- | ------ | --------------------------------------------------- | | deny | `deny_credential_or_system_prompt_flow` | `*` | | `{'data_classes': ['credential', 'system_prompt']}` | | deny | `deny_raw_secret_read` | `secret.read` | | | | deny | `deny_unconfigured_secret_broker_use` | `secret.use` | | | | deny | `deny_unrestricted_process_exec` | `process.exec` | | `{'exclude_execution_surface': ['sandbox']}` | | deny | `deny_unrestricted_host_filesystem_access` | `filesystem.*` | | | | deny | `deny_unrestricted_network_egress` | `network.*` | | | | deny | `deny_unrestricted_package_install` | `package.install` | | | | ask | `ask_sandbox_network` | `sandbox.network.configure` | | | | ask | `ask_sandbox_host_mount` | `sandbox.filesystem.mount` | | | | allow | `allow_sandboxed_execution` | `process.exec` | | `{'execution_surface': 'sandbox'}` | | allow | `allow_sandbox_setup` | `sandbox.*` | | | | allow | `allow_skill_scripts` | `skill.*` | | | | allow | `allow_code_mode` | `code.*` | | | | allow | `allow_local_dev_workspace` | `workspace.*` | | | | allow | `allow_local_tools` | `tool.local.call` | | | | allow | `allow_memory_and_telemetry` | `memory.*` | | | | allow | `allow_telemetry` | `telemetry.*` | | | | allow | `allow_subagent_spawn` | `subagent.*` | | | | allow | `allow_background_execution` | `background.*` | | | ### `interactive-dev` Mode `interactive`. | Effect | Rule | Capability | Target | Conditions | | ------ | --------------------------------------- | --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | | deny | `deny_credential_or_system_prompt_flow` | `*` | | `{'data_classes': ['credential', 'system_prompt']}` | | deny | `deny_raw_secret_read` | `secret.read` | | | | ask | `ask_process_exec` | `process.*` | | `{'exclude_execution_surface': ['sandbox']}` | | ask | `ask_sandbox_network` | `sandbox.network.configure` | | | | ask | `ask_sandbox_host_mount` | `sandbox.filesystem.mount` | | | | ask | `ask_network_egress` | `network.*` | | | | ask | `ask_package_install` | `package.install` | | | | ask | `ask_secret_broker_use` | `secret.use` | | | | ask | `ask_mcp_tool_call` | `tool.mcp.call` | | | | ask | `ask_mcp_server_start` | `mcp.server.*` | | | | ask | `ask_subagent_spawn` | `subagent.*` | | | | ask | `ask_background_execution` | `background.*` | | | | ask | `ask_high_risk` | `*` | | `{'risk_level': ['high', 'critical'], 'exclude_execution_surface': ['sandbox'], 'exclude_capability': ['skill.script.run']}` | | allow | `allow_sandboxed_execution` | `process.exec` | | `{'execution_surface': 'sandbox'}` | | allow | `allow_sandbox_setup` | `sandbox.*` | | | | allow | `allow_skill_scripts` | `skill.*` | | | | allow | `allow_code_mode` | `code.*` | | | | allow | `allow_local_tools` | `tool.local.call` | | | | allow | `allow_workspace` | `workspace.*` | | | | allow | `allow_memory` | `memory.*` | | | | allow | `allow_telemetry` | `telemetry.*` | | | ### `strict-production` Mode `strict`. | Effect | Rule | Capability | Target | Conditions | | ------ | --------------------------------------- | ------------------------ | ------ | --------------------------------------------------- | | deny | `deny_credential_or_system_prompt_flow` | `*` | | `{'data_classes': ['credential', 'system_prompt']}` | | deny | `deny_raw_secret_read` | `secret.read` | | | | allow | `allow_governance_telemetry` | `telemetry.governance.*` | | |