Skip to main content
O Narya verifica um portão antes de cada chamada de ferramenta. Duas coisas decidem a resposta: se você confia no diretório e o que as regras dizem.

​
A pergunta de confiança

O cliente pergunta Confiar neste repositório? uma ida e volta depois de abrir. Ele pergunta apenas quando o diretório traz algo governado: um arquivo de instruções, um diretório de recursos, um .mcp.json ou um .narya/config.toml. A pergunta nomeia o que chega ao modelo e o que roda nesta máquina. Mova o marcador com as setas e pressione Enter. Enter responde apenas logo depois de uma seta, e letras digitadas não fazem nada. O marcador começa na última resposta. Você tem quatro respostas:
  • load and remember this folder confia nesta pasta.
  • load and remember <parent> and everything under it confia na pasta pai e em tudo abaixo dela. O host calcula a pasta pai, então nenhum cliente pode ampliar o escopo além do que mostrou a você.
  • keep them out é um não duradouro.
  • not this time continua sem confiança. O Narya não guarda nada e pergunta de novo na próxima abertura. esc dá a mesma resposta.
O Narya guarda uma linha por caminho canônico. Uma consulta sobe pela árvore, e o ancestral confiado ou recusado mais próximo decide. Digite /trust para reabrir a pergunta. Para confiar em um diretório sem a pergunta, liste-o em trusted_directories no config.toml. O Narya passa a confiar nesse diretório e em tudo abaixo dele, qualquer que seja a resposta guardada para uma pasta abaixo dele. Cada entrada é um caminho absoluto, e nunca /.

​
O que a confiança decide

A confiança decide qual conjunto de regras roda. Um diretório em que ninguém confia roda sob um conjunto mais restrito, e apenas onde uma pessoa pode responder. Uma execução única mantém o conjunto de fábrica. Leituras dentro do diretório seguem livres, e leituras fora dele perguntam. Ações de shell, escrita, rede e ferramenta perguntam. A confiança coloca o conjunto de fábrica no lugar. Com permission_mode = "custom", uma execução única e um diretório confiado rodam o seu permissions.toml em vez disso. Nesse modo, uma regra ask para leituras no seu arquivo pergunta também em um diretório em que ninguém confia. A confiança também controla o material do próprio repositório: seus arquivos de instruções, seus hooks de .claude/settings.json e .claude/settings.local.json, seus servidores de ferramentas de .mcp.json e seus comandos, skills e agentes em .claude e .narya. O Narya ignora tudo isso em um repositório sem confiança, em qualquer modo. Uma sessão em um contêiner recebe a confiança desse contêiner. Todo contêiner conta como confiável, tenha ele clonado um repositório ou não: o contêiner próprio de uma conversa, conversation-<sessionId>, e um ambiente nomeado.

​
Como uma regra é lida

Uma regra é uma tabela TOML com três chaves.
Existem seis ações, e nada além delas: shell, read, write, network, tool e product. A ação decide o que o Narya compara. Um glob de caminho compara read e write. O texto do comando compara shell, depois que o Narya decompõe a linha nos comandos que ela de fato roda. Um host compara network. Um nome de ferramenta compara tool. product é uma alteração em um produto Lerian feita por uma sessão de produto, e o nome da ferramenta dela é o recurso. Uma regra pode negar uma ação product. Nenhuma regra pode permitir uma, porque só o dono da sessão a libera. Existem três efeitos: allow, ask e deny. Não existe campo de ordem. A posição no arquivo é a precedência. O Narya concatena quatro escopos nesta ordem: seu conjunto de fábrica, suas regras globais, as regras do projeto e a sessão. A última regra que casa vence. No modo custom, uma resposta que você lembrou como allow global não levanta um deny do seu permissions.toml, a menos que uma regra posterior nesse arquivo o permita. Uma resposta que você lembra vira uma regra: uma global, para todo lugar, ou uma de projeto, para este repositório. Um repositório em que você confia também contribui com regras de projeto pelos blocos [[rule]] do seu .narya/config.toml. Defina permission_mode = "custom" no config.toml para trocar o conjunto de fábrica pelo permissions.toml na sua pasta Narya.

​
A postura de fábrica

Comandos de shell rodam. Chamadas de ferramenta rodam. Leituras dentro do diretório da sessão rodam, e leituras fora dele perguntam. Mais de quarenta regras de shell perguntam antes, entre elas rm -r, sudo, git push --force, chmod, dd e kill -9. Escritas dentro do repositório rodam, e escritas fora dele perguntam. Ações de rede perguntam, exceto a busca na web do próprio fornecedor, que deny network ** desliga. Uma escrita que nomeia uma destas entradas da sua pasta Narya pergunta, a menos que uma regra a negue:
  • o armazenamento, o lock do host e o socket
  • o arquivo de registro do host em execução
  • o diretório de identidade e o organisation.json
Em uma sessão em um contêiner, uma escrita que nomeia o .narya/config.toml do repositório também pergunta. O Narya não lembra nenhuma resposta a essas perguntas, e uma execução não assistida as recusa. A ferramenta de leitura recusa arquivos .env, como prod.env e .env.local, e lê o .env.example dentro do diretório. Essas regras governam apenas a ferramenta de leitura. Um grep do diretório devolve o conteúdo deles. Um comando de shell os lê sob as regras de shell. Uma escrita em um deles é permitida. O Narya julga uma linha de shell pelo veredito mais restrito entre tudo o que ela de fato roda. Uma linha que o Narya não consegue analisar pergunta, e o Narya não guarda nada dela. As regras de shell julgam a ferramenta de terminal uma vez, quando ela abre, pelo programa que ela inicia. Nenhuma regra lê o que o modelo digita em um terminal aberto. deny tool terminal remove o terminal.
Uma execução não interativa não pode esperar que uma pessoa responda a uma pergunta de permissão. O narya -p roda nesse modo. Os registros de recusa com escopo de sessão têm os limites de auditoria abaixo. Para deixar uma execução fazer ações nomeadas sem perguntar, passe --allow. Veja Automação e CI.

​
Quando uma mudança de configuração vale

Na sua própria máquina, uma nova versão do config.toml, do permissions.toml, do .narya/config.toml de um repositório confiado ou da seção de hooks de um settings.json do Claude Code vale depois que uma pessoa a permite em uma conversa acompanhada, exceto nos dois casos abaixo. Até lá, a última versão permitida continua valendo. Execuções únicas, agendamentos e sessões desacompanhadas nunca perguntam, então mantêm a última versão permitida. O próximo turno acompanhado pergunta uma vez por arquivo alterado e mostra o que mudou. Um não mantém a versão que vale até o arquivo mudar de novo. A primeira versão de cada arquivo que o Narya lê não precisa de um sim. Um config.toml que você adiciona a uma pasta que rodou sem ele é uma nova versão. Dois casos não precisam de um sim. Um config.toml, um permissions.toml ou os hooks do ~/.claude/settings.json que o usuário do host não pode alterar vale como está escrito. Um mount somente leitura é um exemplo. O .narya/config.toml, o .mcp.json e os hooks do Claude Code de um checkout valem como estão escritos quando o checkout fica abaixo de um diretório de trusted_directories. Um sim ao config.toml vale na hora para os modelos e, a partir da sua próxima mensagem, para o modelo padrão. Todos os outros ajustes nele valem no próximo início do host, como [spend] daily_ceiling_usd e [schedules] ceiling_usd. Um sim ao permissions.toml também vale no próximo início do host. Quando você confia em uma pasta pai, o primeiro repositório abaixo dela carrega os próprios arquivos com essa resposta. Outro repositório abaixo dessa pasta pergunta uma vez antes que o seu .narya/config.toml, os seus hooks ou os seus servidores de .mcp.json passem a valer.

​
Auditoria

O Narya grava uma linha por pergunta e por recusa que pertence a uma sessão, incluindo recusas que não chegaram a nenhuma pessoa. Uma recusa fora de uma sessão, ou uma linha que o armazenamento não consegue gravar, não deixa linha. A recusa continua valendo. Cada linha traz:
  • a ação e o recurso
  • quais regras casaram e o que um allow lembrado concederia
  • o status e quem decidiu
  • o motivo
  • o escopo da resposta
Allows derivados de regra não trazem linha. Leia as linhas de volta com narya permissions denied. Adicione --session <id>, --since <time> ou --until <time> para estreitar o intervalo. Uma página comporta 100 linhas, e o Narya avisa quando corta. A retenção é opcional por classe e guarda tudo por padrão. O ajuste [retention] permission_asks varre as linhas decididas e mantém as pendentes.

​
Sessões acompanhadas e desacompanhadas

Toda sessão é attended ou detached. Uma sessão desacompanhada recusa uma pergunta de permissão e registra o motivo, em vez de esperar por uma resposta. Uma sessão que não registrou postura a recebe do tipo de cliente que a abriu:
  • Um cliente de terminal (inline ou tui) e uma sessão de produto são acompanhados.
  • Um chamador api, uma execução única (oneshot) e uma sessão de tipo desconhecido são desacompanhados.
Rode narya session promote <session-id> para entregar uma sessão ao host como desacompanhada. Uma segunda execução não muda nada. O host recusa isso em um diretório em que ninguém confia. Um cliente que você escreve chama PUT /v1/sessions/{sessionId}/posture com attended para que as perguntas esperem por uma pessoa. Uma sessão que você cria pela API sem clientKind é api, então ninguém a acompanha. Execuções de workflow e importações de transcrição também aceitam um clientKind, e assumem api por padrão. O narya import envia inline. Em um diretório em que ninguém confia, o turno de uma sessão api ou de tipo desconhecido é recusado, e a mensagem diz como confiar no diretório. Uma execução única segue nele sob as suas regras, sem os arquivos do próprio repositório. Uma sessão de terminal registrada como desacompanhada nesse diretório volta para acompanhada na próxima verificação de portão. A leitura de confiança falha fechando.