Skip to main content

moai tool-policy Tool Policy

UPDATED 2026-08-13 2 min read EDIT ON GITHUB ↗

moai tool-policy manages the tool/permission policy SSOT. .moai/config/sections/tool-policy.yaml is the single source of truth; from it, the permissions block of settings.json is generated (codegen) and policy entries are queried.

Because a single YAML line decides whether an agent reacts to a terminal command with allow, deny, or ask, breaking this SSOT tears down the harness safety boundary. So this command regenerates the single YAML into the settings.json permissions block that the code reads, giving humans the policy to choose and machines a consistent codegen result to consume. Routing through this command is recommended over editing the JSON directly when adjusting permissions per SPEC.

Subcommands

CommandDescription
moai tool-policy buildRegenerate the settings.json permissions block from tool-policy.yaml
moai tool-policy listList tool-policy entries (thin query)

moai tool-policy build

bash 
moai tool-policy build
moai tool-policy build --local-only

Regenerates the permissions block of the local .claude/settings.json and the template settings.json.tmpl.

FlagDescription
--repo-root <path>Repository root (default: cwd)
--policy <path>tool-policy.yaml path (default: <repo-root>/.moai/config/sections/tool-policy.yaml)
--local-onlyRegenerate only the local .claude/settings.json (skip the template .tmpl)
--template-onlyRegenerate only the template settings.json.tmpl (skip the local)
--default-mode <mode>Override permissions.defaultMode (default: preserve the existing value)
--jsonOutput the result as JSON

moai tool-policy list

bash 
moai tool-policy list
moai tool-policy list --risk-tier irreversible --decision deny
FlagDescription
--risk-tier <read|write|irreversible>Filter by risk tier
--decision <allow|deny|ask>Filter by decision
--tool <name>Filter by tool name (exact match)
--format <text|json>Output format
--repo-root <path>Repository root (default: cwd)
--policy <path>tool-policy.yaml path