Capítulo 10 — Ferramentas, permissões e harness

Saber não é poder

No capítulo anterior, o repositório foi tratado como ambiente legível.

Agora surge outra pergunta:

que capacidades o agente deve possuir — e quais não deve possuir?

Contexto define o que o agente sabe.

Ferramentas definem o que ele consegue fazer.

A diferença é decisiva.

Um agente pode conhecer:

• a arquitetura;
• o schema do banco;
• o processo de deploy;
• o endereço da API;
• o nome de uma credencial.

Nada disso significa que ele deva poder:

• alterar produção;
• apagar dados;
• ler secrets;
• enviar mensagens externas;
• modificar CI;
• promover releases.

Tool use transforma raciocínio em ação

García descreve ferramentas como mecanismos que conectam o modelo a sistemas externos e permitem executar ações, consultar dados, manipular arquivos e observar resultados. Function calling, CLI e MCP aparecem como superfícies complementares desse acesso; definições e resultados das ferramentas passam a compor o contexto operacional do agente. ¹

Isso cria um loop:

Reason
  ↓
Select capability
  ↓
Act
  ↓
Observe
  ↓
Update contexto
  ↓
Reason again

Esse loop é mais poderoso que geração de texto.

Também é mais perigoso.

Uma resposta errada pode ser corrigida.

Uma operação errada pode produzir efeito externo antes que alguém perceba.

Por isso, ferramenta design e permission design precisam ser tratados como arquitetura.

Três superfícies de ação

Para software, três superfícies aparecem com frequência.

Function calling

Uma capacidade pré-definida possui nome, descrição e schema de argumentos.

Vantagens:

• interface explícita;
• validação estrutural;
• superfície menor;
• comportamento mais previsível;
• logs mais fáceis de interpretar.

O custo é que a capacidade precisa ser modelada antes.

CLI

A CLI expõe o ambiente por comandos, flags, stdin, paths e executáveis.

É extremamente flexível.

Também é ampla.

Um shell pode:

• ler;
• escrever;
• apagar;
• instalar;
• iniciar processos;
• acessar rede;
• manipular Git;
• alterar configuração.

CLI não é uma ferramenta.

É uma superfície que pode alcançar muitas ferramentas.

Por isso, permissões de shell precisam considerar comando, diretório, usuário, rede e credenciais — não apenas “terminal permitido”.

MCP

MCP permite que servidores exponham ferramentas, recursos e outras capacidades para aplicações com agentes.

Isso torna descoberta e integração mais modulares.

Mas disponibilidade não implica autorização.

O fato de uma ferramenta existir no servidor não significa que deva ser apresentada ao agente em toda tarefa.

No método deste livro:

descoberta é uma coisa; concessão de capacidade é outra.

Capabilities precisam ser task-scoped

O princípio de least privilege determina que pessoas, sistemas e automações recebam apenas o acesso necessário para cumprir sua função. ²

Para agentes, isso significa evitar o padrão:

“habilite tudo; o modelo decide o que usar.” O modelo deste livro prefere:

“comece negado; expanda capacidade quando a tarefa justificar.”

Isso é método deste livro.

A unidade prática de permissão não é “o agente”.

É:

agente + tarefa + capacidade + recurso + duração.

Exemplos:

• revisor + PR atual + read repository + branch específica + sessão;
• agente de testes + run tests + workspace local + duração da tarefa;
• deployer + inspect release + staging + janela de mudança;
• agente de migração + prepare SQL + snapshot local + sem execução em produção.

Quanto mais ampla a combinação, maior o blast radius potencial.

Permission & Risk Matrix

O artefato deste capítulo é a Permission & Risk Matrix.

Ela responde quatro perguntas:

1. o que o agente pode fazer?
2. sobre qual recurso?
3. com qual consequência?
4. quem precisa autorizar?

Estrutura mínima:

Capability	Resource	Mode	Reversible?	External impact?	Approval	Evidence
read files	workspace	allow	yes	no	none	access log
edit files	feature branch	allow	yes	no	revisão	diff
open PR	repository	bounded	yes	medium	policy	PR
merge PR	main	gated	partial	high	human	CI + approval
deploy	production	gated	partial	high	human	release evidência
drop table	production DB	deny/default	no	critical	explicit exception	backup + approval
A matriz é método deste livro.

Ela não tenta substituir IAM, RBAC ou políticas de infraestrutura.

Sua função é tornar visível o contrato de delegação.

Reversibilidade muda o nível de autonomia

Tantithamthavorn distingue ações reversíveis em ambientes controlados de ações irreversíveis ou com impacto externo significativo e recomenda confirmação humana explícita para estas últimas. ³

Isso permite uma regra simples:

quanto mais fácil recuperar, maior pode ser a autonomia.

Exemplos de baixo custo de recuperação:

• editar arquivo versionado;
• criar teste;
• gerar documentação;
• preparar migration;
• abrir branch.

Exemplos de maior custo:

• apagar dados;
• publicar pacote;
• enviar comunicação externa;
• alterar pipeline;
• promover produção;
• rotacionar credencial;
• modificar DNS.

A fronteira não depende apenas de “permissão de escrita”.

Depende da consequência.

Confirmação deve acontecer no ponto de ação

Um erro de UX operacional é pedir autorização cedo demais.

Exemplo:

“Posso trabalhar neste deploy?”

Essa pergunta é vaga.

O usuário pode autorizar análise, preparação e teste sem autorizar promoção.

No método deste livro, a confirmação deve ficar próxima da ação de alto impacto. Exemplo:

• analisar release → automático;
• construir artefato → automático;
• testar staging → automático;
• preparar plano de rollback → automático;
• promover produção → confirmação explícita.

Assim, a autorização corresponde ao efeito real.

Write boundaries

Nem toda escrita tem o mesmo risco.

Podemos separar:

Workspace write

Arquivos temporários, builds e caches.

Branch write

Alterações versionadas em branch isolada.

Repository control write

Issues, PRs, labels, workflows e settings.

Shared-state write

Banco, storage, filas, APIs externas.

Production write

Estado que afeta usuários reais.

Essa classificação é método deste livro.

Ela impede que “write access” seja tratado como uma única permissão booleana.

Sandbox

Sandbox reduz alcance.

Ela pode limitar:

• filesystem;
• usuário do processo;
• rede;
• variáveis de ambiente;
• processos filhos;
• credenciais;
• dispositivos;
• tempo;
• CPU/memória.

Sandbox não transforma comportamento probabilístico em comportamento seguro por si só.

Ela reduz o que um erro consegue atingir.

Essa diferença importa.

Controle de modelo tenta melhorar a decisão.

Controle de ambiente limita a consequência. Os dois são necessários.

Secrets não pertencem ao contexto por padrão

Um agente não precisa receber o valor de uma credencial só porque precisa executar uma operação autenticada.

Melhores superfícies podem fornecer:

• token de curta duração;
• capability específica;
• secret injection no processo;
• broker;
• identidade de workload;
• comando que usa a credencial sem revelá-la.

No método deste livro:

use secret sem transformar secret em texto quando houver alternativa.

Isso reduz exposição em:

• contexto;
• logs;
• commits;
• mensagens;
• ferramenta outputs.

MCP também é uma trust boundary

Um MCP server amplia o conjunto de capacidades disponíveis.

Portanto, ele deve ser tratado como dependência e como boundary.

Perguntas úteis:

• quem opera o servidor?
• qual versão está ativa?
• quais ferramentas ele expõe?
• quais recursos acessa?
• qual rede alcança?
• quais credenciais recebe?
• quais resultados entram no contexto?
• existe logging?
• existe forma de revogar?

A presença de MCP não elimina a necessidade de autorização.

Ela torna a autorização ainda mais explícita.

Agent skills não são permissões

Skill descreve procedimento.

Tool executa capacidade.

Permission decide se aquela capacidade está disponível.

Misturar essas três coisas cria confusão. Um arquivo pode dizer:

“faça deploy depois dos testes.”

Isso não deveria conceder automaticamente acesso de produção.

A skill pode:

• descrever a sequência;
• chamar ferramentas permitidas;
• preparar evidência;
• parar no gate humano.

O runtime continua responsável por impor limites.

Harness: controles em torno da capability

Neste livro, harness é método deste livro para o conjunto de controles que transforma capability genérica em execução limitada e verificável.

Ele pode envolver instruções, ferramenta registry, permissions, sandbox, schemas, hooks, validators, tests, logs, approval gates, timeouts, quotas e recovery mechanisms.

O harness atua em três momentos:

Antes da ação

• selecionar Context;
• limitar ferramentas;
• validar input;
• definir branch/sandbox;
• carregar policy.

Durante a ação

• validar argumentos;
• impor timeout;
• restringir rede;
• registrar ferramenta calls;
• bloquear operações fora do envelope.

Depois da ação

• validar resultado;
• produzir Evidence;
• verificar estado;
• registrar provenance;
• preservar rollback/recovery path.

O ponto importante é que capability não é apenas acesso a uma ferramenta. É ferramenta + boundary + observabilidade + recovery.

Auditabilidade é requisito de operação

Tantithamthavorn propõe registrar cada ferramenta call com ferramenta, parâmetros, resultado, agente e momento, permitindo detectar padrões anômalos e reconstruir incidentes. ⁴

Essa propriedade muda a pergunta de:

“o agente fez algo errado?”

para:

“qual ação foi executada, com quais argumentos, sob qual permissão e qual resultado retornou?”

Isso é muito mais útil.

Sem audit trail, falhas agênticas viram narrativas.

Com audit trail, podem virar evidência.

Log não deve virar vazamento

Auditabilidade não autoriza registrar tudo.

Logs podem conter:

• tokens;
• paths sensíveis;
• payloads privados;
• dados pessoais;
• comandos com secrets;
• respostas de APIs.

O harness precisa de política de redaction.

No método deste livro:

registre decisão e consequência; sanitize conteúdo sensível.

Falha típica: agente com credenciais permanentes

Um agente local recebe:

• token GitHub amplo;
• acesso cloud;
• chave SSH;
• banco de produção;
• shell irrestrito.

A tarefa é apenas corrigir CSS.

Esse desenho possui muito mais autoridade que necessidade.

Mesmo que o agente aja corretamente, o contrato é ruim.

Least privilege não é resposta a uma falha.

É prevenção de blast radius.

Falha típica: confirmação para tudo

O extremo oposto também falha.

Se cada:

• leitura;
• teste;
• busca;
• edição;
• comando;

exige confirmação, a pessoa aprende a clicar “sim”.

O gate perde significado.

Approval fatigue transforma controle em ritual.

Por isso, confirmação deve se concentrar em:

• irreversibilidade;
• impacto externo;
• elevação de privilégio;
• acesso sensível;
• mudança de boundary;
• custo significativo.

Falha típica: ferramenta invisível

Uma automação pode executar comandos por trás de uma interface amigável.

Se o usuário não sabe:

• qual ferramenta foi chamada;
• qual recurso mudou;
• qual identidade foi usada;
• qual evidência ficou;

o sistema dificulta responsabilização.

Boa UX agêntica precisa tornar ações relevantes observáveis.

Não necessariamente com ruído constante.

Mas com trilha recuperável.

Capability escalation

Às vezes a tarefa começa read-only e descobre necessidade legítima de escrita.

O método usa escalation explícita:

1. agente identifica a capacidade ausente;
2. explica por que ela é necessária;
3. delimita recurso e duração;
4. informa consequência;
5. solicita elevação;
6. executa dentro do novo envelope;
7. encerra ou revoga a capacidade. Isso é preferível a conceder autoridade ampla antecipadamente.

De capability design à coordenação

Capability design responde o que um agente pode fazer.

Coordination design responde como múltiplas unidades de trabalho compartilham estado, contexto, responsabilidade e ordem sem destruir essas boundaries.

Com um agente, task-scoped ferramentas e permissions já são suficientes para muitos fluxos. Ao introduzir mais agentes, surgem novos problemas: herança de permissões, escrita concorrente, shared state, handoffs e consolidação de Evidence.

O próximo capítulo começa, portanto, com um princípio conservador: multiagente só é justificável quando o ganho de distribuição supera o custo de coordenação.

Fronteira de confiança

Cada ferramenta call cruza uma fronteira entre raciocínio e efeito externo. Function calling, CLI e MCP devem operar sob permissões explícitas; ferramenta outputs externos entram como dados potencialmente não confiáveis. Secrets e credenciais não devem ganhar exposição adicional apenas para facilitar o uso do agente.

Evidência exigida

Toda ação material deve deixar evidência proporcional ao risco. Para mudanças de código: diff, testes e commit. Para operações: comando/ferramenta, resultado, identidade, timestamp e estado observado. Para ações de alto impacto: aprovação e prova de recovery readiness.

Rollback e recuperação

A matriz de permissão deve considerar reversibilidade antes da concessão. Mudanças versionadas podem usar revert/reset/rollback; operações de dados precisam de backup ou estratégia equivalente; produção exige plano de retorno verificável antes da promoção.

Proveniência das fontes

Rastreabilidade deste capítulo:

• CLM-006 — Adkins et al., least privilege como acesso mínimo necessário também para automação;
• CLM-038 — García, ferramentas como superfície de ação/contexto por function calling, CLI e MCP;
• CLM-039 — Tantithamthavorn, confirmação humana explícita para ações irreversíveis ou de impacto externo significativo;
• CLM-040 — Tantithamthavorn, audit logging de ferramenta calls para detecção e reconstrução.

A Permission & Risk Matrix, classificação de write boundaries, capability escalation e definição transversal de harness são método deste livro.

Fontes de acesso limitado não foram usadas como autoridade factual neste capítulo.

Recursos complementares

Recursos relacionados:

• Permission & Risk Matrix;
• capability manifest;
• ferramenta inventory;
• approval-gate template;
• sandbox checklist;
• audit-log schema;
• futura simulação reversible vs irreversible;
• futura visualização de capability escalation em Change Episodes.

---

Footnotes

1. Boni García, Context Engineering (MEAP, 2026), 4.1 Tools, pp. 96–97. Rastreabilidade interna: CLM-038. ↩

2. Adkins et al., Building Secure & Reliable Systems (2020), Chapter 5. Design for Least Privilege, pp. 97–98. Rastreabilidade interna: CLM-006. ↩

3. Kla Tantithamthavorn, Agentic Software Engineering (2026), 9.6.2 Human-in-the-Loop for Irreversible Actions, p. 145. Rastreabilidade interna: CLM-039. ↩

4. Kla Tantithamthavorn, Agentic Software Engineering (2026), 9.6.4 Audit Logging, p. 146. Rastreabilidade interna: CLM-040. ↩