Permissões

O Dropstone usa a configuração permission para decidir se uma determinada ação deve ser executada automaticamente, solicitar sua aprovação ou ser bloqueada.

A configuração legada tools (booleana) está obsoleta; ela foi incorporada à permission. A configuração antiga tools ainda é suportada para compatibilidade com versões anteriores.

Ações

Cada regra de permissão é resolvida para um dos seguintes valores:

• "allow": executa sem aprovação
• "ask": solicita aprovação
• "deny": bloqueia a ação

Configuração

Você pode definir permissões globalmente (com *) e sobrescrever ferramentas específicas.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

Você também pode definir todas as permissões de uma só vez:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": "allow"
}

Regras Granulares (Sintaxe de Objeto)

Para a maioria das permissões, você pode usar um objeto para aplicar diferentes ações com base na entrada da ferramenta.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

As regras são avaliadas por correspondência de padrão, com a última regra correspondente vencendo. Um padrão comum é colocar a regra abrangente "*" primeiro e as regras mais específicas depois dela.

Curingas

Os padrões de permissão usam correspondência curinga simples:

• * corresponde a zero ou mais de qualquer caractere
• ? corresponde exatamente a um caractere
• Todos os outros caracteres correspondem literalmente

Expansão do Diretório Inicial

Você pode usar ~ ou $HOME no início de um padrão para referenciar seu diretório inicial. Isso é particularmente útil para regras de external_directory.

• ~/projects/* -> /Users/username/projects/*
• $HOME/projects/* -> /Users/username/projects/*
• ~ -> /Users/username

Diretórios Externos

Use external_directory para permitir chamadas de ferramentas que tocam caminhos fora do diretório de trabalho onde o Dropstone foi iniciado. Isso se aplica a qualquer ferramenta que receba um caminho como entrada (por exemplo, read, edit, glob, grep e muitos comandos bash).

A expansão do diretório inicial (como ~/...) afeta apenas como um padrão é escrito. Ela não torna um caminho externo parte do espaço de trabalho atual, portanto, caminhos fora do diretório de trabalho ainda devem ser permitidos via external_directory.

Por exemplo, isso permite acesso a tudo sob ~/projects/personal/:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

Qualquer diretório permitido aqui herda os mesmos padrões do espaço de trabalho atual. Como read tem como padrão allow, leituras também são permitidas para entradas sob external_directory, a menos que sejam sobrescritas. Adicione regras explícitas quando uma ferramenta deve ser restrita nesses caminhos, como bloquear edições enquanto mantém leituras:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

Mantenha a lista focada em caminhos confiáveis e adicione regras extras de permitir ou negar conforme necessário para outras ferramentas (por exemplo, bash).

Permissões Disponíveis

As permissões do Dropstone são chaveadas pelo nome da ferramenta, além de alguns guardas de segurança:

• read: leitura de um arquivo (corresponde ao caminho do arquivo)
• edit: todas as modificações de arquivo (cobre edit, write, patch)
• glob: globbing de arquivos (corresponde ao padrão glob)
• grep: busca de conteúdo (corresponde ao padrão regex)
• bash: execução de comandos de shell (corresponde a comandos analisados como git status --porcelain)
• task: lançamento de subagentes (corresponde ao tipo de subagente)
• skill: carregamento de uma skill (corresponde ao nome da skill)
• lsp: execução de consultas LSP (atualmente não granular)
• question: fazer perguntas ao usuário durante a execução
• webfetch: busca de uma URL (corresponde à URL)
• websearch: busca na web (corresponde à consulta)
• external_directory: acionado quando uma ferramenta toca caminhos fora do diretório de trabalho do projeto
• doom_loop: acionado quando a mesma chamada de ferramenta se repete 3 vezes com entrada idêntica

Padrões

Se você não especificar nada, o agente build padrão pergunta antes de tudo. A aprovação é o padrão, não uma exceção:

{
  "permission": {
    "*": "ask",
    "read": {
      "*": "ask",
      "*.env": "ask",
      "*.env.*": "ask",
      "*.env.example": "ask"
    },
    "external_directory": { "*": "ask" },
    "question": "deny",
    "plan_enter": "deny",
    "plan_exit": "deny",
    "mode_switch": "deny"
  }
}

Diretórios que você já aprovou são adicionados a external_directory como "allow" pelo restante da sessão.

Sua configuração é mesclada sobre esses padrões, e suas regras vencem. Ela não os substitui: definir edit como "allow" deixa read em "ask", então nomeie cada permissão que você pretende alterar.

O agente accept all começa com "*": "allow" em vez disso, com external_directory totalmente permitido. Leituras de .env e .env.* ainda perguntam, com o raciocínio de que aprovar automaticamente uma execução não é o mesmo que consentir em entregar segredos.

Modo headless e servidor

Interativamente, "ask" é inofensivo: você recebe um prompt e aprova. Sob dropstone serve, em CI ou em qualquer outro lugar sem uma pessoa no teclado, não há ninguém para perguntar, então a chamada fica em "status": "running" e a solicitação fica pendurada em vez de falhar. Não há timeout e nenhum erro para capturar.

Como o agente build pergunta antes de tudo, esse é o resultado padrão, não um caso extremo. Uma configuração parcial também não o salva: permitir edit deixa read em "ask", e a execução fica pendurada na primeira vez que o agente abre um arquivo.

Duas maneiras de corrigir. Ou execute o agente accept all, que começa com "*": "allow":

curl -X POST ".../session/$SID/message" -d '{ "agent": "accept all", ... }'

Ou permaneça no build e declare a lista completa de permissões, negando por padrão para que uma ferramenta adicionada em uma versão posterior não comece silenciosamente a pendurar suas execuções:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "*": "deny",
    "read": "allow",
    "edit": "allow",
    "glob": "allow",
    "grep": "allow",
    "bash": "allow"
  }
}

Reduza ao que o trabalho realmente precisa. Um agente que apenas lê e relata não tem motivo para manter edit ou bash.

Observe que accept all ainda pergunta antes de ler .env e .env.*. Se uma execução não supervisionada precisar ler um deles, permita-o explicitamente e seja deliberado sobre isso.

O que "Ask" faz

Quando o Dropstone solicita aprovação, a interface oferece três resultados:

• once: aprova apenas esta solicitação
• always: aprova solicitações futuras que correspondam aos padrões sugeridos (pelo restante da sessão atual do Dropstone)
• reject: nega a solicitação

O conjunto de padrões que always aprovaria é fornecido pela ferramenta (por exemplo, aprovações de bash normalmente incluem na lista de permissões um prefixo de comando seguro como git status*).

Agentes

Você pode sobrescrever permissões por agente. As permissões do agente são mescladas com a configuração global, e as regras do agente têm precedência. Saiba mais sobre permissões de agente.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

Você também pode configurar permissões de agente em Markdown:

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

Only analyze code and suggest changes.