Use this pattern when the agent can call tools and some actions must be constrained.

• file and shell tools
• internal ops assistants
• admin workflows
• any tool-enabled app with side effects

from loom import Agent, Capability, Model, Runtime, tool


@tool(description="Read deployment status", read_only=True)
async def deployment_status(service: str) -> str:
    return f"{service}: healthy"


agent = Agent(
    model=Model.anthropic("claude-sonnet-4"),
    instructions="Help with repository and deployment maintenance.",
    tools=[deployment_status],
    capabilities=[
        Capability.files(read_only=True),
        Capability.shell(require_approval=True),
    ],
    runtime=Runtime.supervised(criteria=["no destructive action without approval"]),
)

Use capabilities for what the agent can reach and runtime governance for how those abilities are constrained.

In practice:

• Capability.files(read_only=True) is the default for analysis
• Capability.shell(require_approval=True) keeps shell access explicit
• Runtime.supervised(...) adds a quality and approval-oriented runtime profile
• custom safety rules and advanced policy objects remain available through loom.config

• use GovernancePolicy directly when the app needs custom approval or rate-limit behavior
• add SignalAdapter when tool work is triggered by gateway, cron, heartbeat, or webhook events

• examples/12_heartbeat_and_safety.py
• examples/15_approval_workflow.py