$schema: https://json-schema.org/draft/2020-12/schema
title: Permissions file config
description: |-
  Rules loaded from version 2 `permissions.{yml,yaml}` files.
  A Polytoken permissions file: tool rules and filesystem rules, each grouped
  into `allow`, `ask`, `ask-unless-allowed`, and `deny` buckets.
type: object
properties:
  version:
    description: Schema version. Always `2`.
    const: 2
    default: 2
  allow:
    description: Run matching tool calls without asking.
    type: array
    items:
      $ref: '#/$defs/PermissionRule'
  ask:
    description: Ask before running matching tool calls.
    type: array
    items:
      $ref: '#/$defs/PermissionRule'
  ask-unless-allowed:
    description: |-
      Ask before running matching tool calls, unless an `allow` rule already
      covers them.
    type: array
    items:
      $ref: '#/$defs/PermissionRule'
  deny:
    description: Refuse matching tool calls.
    type: array
    items:
      $ref: '#/$defs/PermissionRule'
  filesystem:
    description: Filesystem path-capability rules, using the same buckets.
    $ref: '#/$defs/FilesystemRuleBuckets'
additionalProperties: false
required:
- version
$defs:
  PermissionRule:
    description: A single permission-file rule.
    type: object
    properties:
      tool:
        description: |-
          Tool name, glob, or `mcp__<server>` shorthand that matches every tool
          from that MCP server.
        type: string
      args:
        description: |-
          Arguments that narrow the match. The keys present determine which
          category of argument narrowing applies: `path` for file tools, `url`
          for web tools, `executable`/`subcommand`/`command_tokens`/`flags_present`
          for shell tools, `pattern`/`include` for search tools, and `model` for
          model-scoped rules. Omit `args` for a name-only rule.
        anyOf:
        - $ref: '#/$defs/PermissionArgs'
        - type: 'null'
      message:
        description: |-
          Optional reminder text shown to the model after a tool call matched by
          this rule completes. Polytoken injects the text as a system reminder
          after the full tool batch finishes, so it never interrupts tool results.
          Use this to give the model context about why a rule exists or what to do
          next when the rule fires. The message only fires when a rule with this
          verdict is the resolved verdict: an allow rule on an allowed call, or a
          deny rule on a denied call. If multiple rules with messages match the
          same call, each one whose verdict matches the resolved outcome fires its
          message. Ask rules never produce a reminder. Bypass mode skips all
          messages.
        type:
        - string
        - 'null'
    additionalProperties: false
    required:
    - tool
  PermissionArgs:
    anyOf:
    - allOf:
      - $ref: '#/$defs/ShellPermissionArgs'
      minProperties: 1
    - allOf:
      - $ref: '#/$defs/SearchPermissionArgs'
      minProperties: 1
    - $ref: '#/$defs/PathPermissionArgs'
    - $ref: '#/$defs/UrlPermissionArgs'
    - $ref: '#/$defs/ModelPermissionArgs'
  ShellPermissionArgs:
    description: Shell command args for `shell_exec` and `shell_monitor`.
    type: object
    properties:
      executable:
        description: The executable name to match (e.g., `git`, `ls`).
        anyOf:
        - $ref: '#/$defs/PermissionValueMatcher'
        - type: 'null'
      command:
        description: A full command string to match.
        anyOf:
        - $ref: '#/$defs/PermissionValueMatcher'
        - type: 'null'
      subcommand:
        description: Ordered subcommand tokens after the executable.
        anyOf:
        - $ref: '#/$defs/SubcommandMatcher'
        - type: 'null'
      command_tokens:
        description: |-
          Command tokens (`[executable, subcommand...]`) up to the first flag or
          path boundary. A trailing `"*"` in the YAML enables prefix matching.
        anyOf:
        - $ref: '#/$defs/CommandTokensMatcher'
        - type: 'null'
      flags_present:
        description: |-
          Flag constraints. An array or single string requires those flags to be
          present. An object with an `excludes` key requires those flags to be
          absent.
        anyOf:
        - $ref: '#/$defs/FlagsPresentMatcher'
        - type: 'null'
    additionalProperties: false
  PermissionValueMatcher:
    oneOf:
    - type: string
    - type: object
      properties:
        exact:
          type: string
      required:
      - exact
      additionalProperties: false
    - type: object
      properties:
        glob:
          type: string
      required:
      - glob
      additionalProperties: false
  SubcommandMatcher:
    oneOf:
    - $ref: '#/$defs/PermissionValueMatcher'
    - type: array
      minItems: 1
      items:
        $ref: '#/$defs/PermissionValueMatcher'
  CommandTokensMatcher:
    description: An array of command token matchers. A trailing "*" enables prefix matching, allowing any additional tokens after the listed prefix.
    type: array
    minItems: 1
    items:
      $ref: '#/$defs/PermissionValueMatcher'
  FlagsPresentMatcher:
    oneOf:
    - type: array
      minItems: 1
      items:
        $ref: '#/$defs/PermissionValueMatcher'
    - $ref: '#/$defs/PermissionValueMatcher'
    - type: object
      properties:
        contains:
          type: array
          minItems: 1
          items:
            $ref: '#/$defs/PermissionValueMatcher'
      required:
      - contains
      additionalProperties: false
    - type: object
      properties:
        excludes:
          type: array
          minItems: 1
          items:
            $ref: '#/$defs/PermissionValueMatcher'
      required:
      - excludes
      additionalProperties: false
  SearchPermissionArgs:
    description: Search tool args with pattern, include, and/or path narrowing.
    type: object
    properties:
      pattern:
        description: Search pattern to match.
        anyOf:
        - $ref: '#/$defs/PermissionValueMatcher'
        - type: 'null'
      include:
        description: File include filter to match.
        anyOf:
        - $ref: '#/$defs/PermissionValueMatcher'
        - type: 'null'
      path:
        description: Path scope for the search.
        anyOf:
        - $ref: '#/$defs/PermissionValueMatcher'
        - type: 'null'
    additionalProperties: false
  PathPermissionArgs:
    description: Path-scoped args for file tools (`file_read`, `file_write`, etc.).
    type: object
    properties:
      path:
        description: |-
          Filesystem path to match. Bare strings with glob metacharacters are
          treated as globs.
        $ref: '#/$defs/PermissionValueMatcher'
    additionalProperties: false
    required:
    - path
  UrlPermissionArgs:
    description: URL-scoped args for web tools (`web_fetch`).
    type: object
    properties:
      url:
        description: |-
          URL to match. Bare strings with glob metacharacters are treated as
          globs.
        $ref: '#/$defs/PermissionValueMatcher'
    additionalProperties: false
    required:
    - url
  ModelPermissionArgs:
    description: Model-scoped args (e.g., for `subagent` model overrides).
    type: object
    properties:
      model:
        description: Model name to match.
        $ref: '#/$defs/PermissionValueMatcher'
    additionalProperties: false
    required:
    - model
  FilesystemRuleBuckets:
    type: object
    properties:
      allow:
        description: Grant the listed path capabilities without asking.
        type: array
        items:
          $ref: '#/$defs/FilesystemRule'
      ask:
        description: Ask before granting the listed path capabilities.
        type: array
        items:
          $ref: '#/$defs/FilesystemRule'
      ask-unless-allowed:
        description: |-
          Ask before granting the listed path capabilities, unless an `allow` rule
          already covers them.
        type: array
        items:
          $ref: '#/$defs/FilesystemRule'
      deny:
        description: Refuse the listed path capabilities.
        type: array
        items:
          $ref: '#/$defs/FilesystemRule'
    additionalProperties: false
  FilesystemRule:
    type: object
    properties:
      access:
        description: 'Path capabilities the rule grants: `read`, `write`, and `chdir`.'
        type: array
        minItems: 1
        uniqueItems: true
        items:
          $ref: '#/$defs/FilesystemCapability'
      path:
        description: |-
          Path the rule applies to. The suffix `{,/**}` means the path and
          anything under it.
        type: string
    additionalProperties: false
    required:
    - access
    - path
  FilesystemCapability:
    oneOf:
    - description: Read file contents or inspect directory contents.
      type: string
      const: read
    - description: |-
        Create or overwrite files, and the write side of edits, deletes, or
        moves. Does not grant read.
      type: string
      const: write
    - description: Change a shell command's working directory to the path.
      type: string
      const: chdir