A governança pré-execução avalia uma operação proposta antes que o efeito sob governança possa ocorrer e exige um ponto de controle capaz de aplicar a decisão resultante àquela operação. Esta é uma definição operacional: o ponto precisa conhecer os destinos e argumentos relevantes enquanto ainda pode impedir o efeito controlado. Aprovar apenas o nome de uma ferramenta não estabelece esse limite.
O valor está na possibilidade de escolha que ainda existe: permitir a operação dentro do escopo, impedi-la, alterar a proposta quando houver suporte ou obter uma aprovação aplicável. A governança de IA em runtime descreve como decisões continuam válidas ao longo de um fluxo. Este guia examina a unidade de trabalho que essas decisões realmente abrangem, especialmente quando uma chamada contém mais de uma operação.
Comece pela solicitação em lote, não pelo nome da ferramenta
Considere uma tarefa hipotética de manutenção: adicionar um rótulo de acompanhamento aos recursos de uma determinada equipe para uma revisão futura. A tarefa autoriza mudanças somente nos recursos dessa equipe. Suponha que o agente proponha uma atualização de rótulos em lote, mas que, ao resolver a seleção, obtenha recursos dessa equipe e de outra. A credencial do executor permite acesso aos recursos das duas equipes.
Essas condições são um exemplo para avaliar o projeto, não uma integração da KonaSense ou um resultado de teste. Não se presume significado específico de plataforma, consequência automática ou comportamento atômico para a atualização de rótulos. A arquitetura precisa estabelecer essas propriedades para a ferramenta real antes de se apoiar nelas.
A ferramenta pode ser permitida para a tarefa enquanto o lote resolvido excede a delegação. Permitir “atualização de rótulos” não responde quais recursos podem mudar, que valor deve ser aplicado ao rótulo ou se o executor usará a mesma seleção que o avaliador examinou. A permissão da credencial estabelece a autoridade disponível; a tarefa define um uso pretendido mais restrito.
Escolha o ponto que consegue observar e ainda impedir o efeito
Um ponto de controle útil combina informação relevante com autoridade para interromper a operação que avalia. Uma verificação antecipada pode conhecer a intenção do usuário, mas não os recursos selecionados. Um componente posterior pode identificar esses recursos e, ainda assim, não ter como impedir uma solicitação já enviada a outro sistema. Avalie as duas condições antes de descrever o mecanismo como preventivo.
| Ponto de inspeção no fluxo hipotético | O que pode estabelecer | Limite que ainda precisa ser verificado |
|---|---|---|
| Instrução inicial da tarefa | Equipe solicitada, rótulo pretendido e finalidade declarada | A seleção final e a identidade executora podem ainda não existir |
| Nome da ferramenta selecionada | Qual interface o agente propõe chamar | Uma interface pode afetar recursos dentro e fora do escopo da tarefa |
| Lote resolvido antes do envio | Conjunto proposto de recursos, argumentos do rótulo e informações relevantes sobre a equipe responsável | O executor precisa usar a proposta avaliada sem ampliá-la silenciosamente |
| Operação no serviço que aplica a mudança | Item ou solicitação que o serviço está prestes a processar | O serviço precisa de autorização própria aplicável e de um meio de impedir aquele efeito |
| Resposta ou observação posterior de estado | O que uma fonte informa depois de uma tentativa | Um efeito que já ocorreu não pode ser impedido por essa observação |
As linhas descrevem posições lógicas, não serviços obrigatórios ou visibilidade garantida. Um sistema pode combiná-las ou repetir uma verificação para cada item. O guia de arquitetura apresenta as responsabilidades dos componentes e as relações de confiança; aqui, o projeto precisa responder qual operação permanece sob controle em cada posição.
Identifique uma proposta concreta e os fatos necessários à autorização
Represente a proposta com precisão suficiente para que o avaliador distinga uma atualização permitida de outra fora do escopo. Neste exemplo, isso significa identificar os recursos no namespace pertinente, o rótulo e o valor propostos, a semântica da atualização e a identidade que a executará. Adicionar um rótulo e substituir um conjunto de rótulos são propostas diferentes, mesmo que a mesma interface ofereça as duas opções.
Mantenha a expressão de seleção separada do resultado obtido ao resolvê-la. “Recursos para a revisão” é uma instrução para encontrar um conjunto, não evidência de que todo recurso retornado pertence à equipe autorizada. Estabeleça de onde vêm as informações sobre a equipe responsável e quais observações a avaliação usa. Se a enumeração estiver incompleta ou não for possível identificar a equipe responsável por um recurso, preserve essa limitação em vez de tratar os itens desconhecidos como autorizados.
O avaliador também precisa conhecer a delegação da tarefa, incluindo as exceções permitidas. Uma credencial de serviço abrangente não fornece essa delegação ausente. A orientação de autorização da OWASP recomenda validar permissões em cada solicitação. Aplique esse princípio às operações e aos recursos reais expostos pela implementação; verificar uma permissão na interface de lote não equivale automaticamente a verificar cada item que ela processa. OWASP Authorization Cheat Sheet.
A análise sobre governança no prompt explica por que aceitar uma solicitação inicial não comprova que o material resolvido depois foi examinado.
Vincule a decisão ao que o executor usará
Uma decisão sobre um conjunto resolvido de recursos só é útil se o executor conseguir estabelecer qual operação ela abrange. Defina como os destinos avaliados, os argumentos relevantes, a identidade executora e o contexto pertinente são associados à solicitação usada na execução. Um identificador de sessão compartilhado localiza trabalhos relacionados, mas não torna duas versões de um lote equivalentes.
Se o avaliador examina uma lista explícita de recursos, mas o executor depois refaz uma seleção dinâmica, o mesmo texto de seleção pode produzir outro conjunto. Quando a interface permite, uma opção de projeto é enviar a lista explícita avaliada e verificar se ela continua aplicável. Outra é avaliar cada operação resolvida no serviço antes do efeito daquela operação. Essas são opções de projeto a avaliar, não garantias intercambiáveis ou capacidades atribuídas à KonaSense.
Especifique o que acontece quando não é possível estabelecer essa correspondência. Uma mudança de destino, argumento de rótulo ou identidade executora pode exigir nova proposta e nova decisão. Não associe uma aprovação antiga à substituta apenas porque o runtime manteve o ID da tarefa. A orientação de autorização de transações da OWASP descreve a proteção de dados relevantes da transação e a verificação da autorização em um ponto final de controle vinculado à execução. Isso sustenta a relação entre a operação aprovada e a realizada; não prescreve esta arquitetura de lote. OWASP Transaction Authorization Cheat Sheet.
Defina com precisão o escopo de Allow e Deny
Allow permite uma tentativa abrangida pelas condições da decisão. Para um lote, indique se essa decisão cobre a solicitação enviada por inteiro ou determinadas operações resolvidas. O executor precisa implementar a granularidade correspondente. Um avaliador que produz conclusões por item não pode presumir que um executor capaz de tratar apenas o lote inteiro as aplicará individualmente.
Deny significa impedir a operação protegida no caminho controlado. Se o ponto de controle tem autoridade para interromper uma solicitação inteira antes do envio, ele pode retê-la. Se o processamento já começou em outro sistema, uma negação posterior pode interromper apenas o trabalho restante. Ela não comprova que os itens anteriores permaneceram inalterados. A descrição útil identifica a operação, o ponto de controle e o que ainda era possível impedir.
No exemplo com recursos de duas equipes, uma política poderia rejeitar a proposta enviada porque ela inclui recursos não autorizados. A possibilidade de rejeitá-la antes de qualquer item mudar depende do ponto de avaliação e do que o executor oferece. Não deduza um comportamento de tudo ou nada da palavra “lote”. Se esse comportamento for necessário, o mecanismo real de execução precisa oferecê-lo e ele precisa ser verificado.
Trate um lote transformado como uma nova proposta
Remover os recursos da outra equipe pode reduzir a autoridade solicitada, mas também mudar o significado da tarefa. A seleção original pode estar errada, a revisão pretendida pode exigir outro conjunto ou o usuário pode precisar saber que parte do trabalho solicitado continua sem resolução. Um lote menor não é automaticamente um resultado correto ou completo.
Quando houver suporte à transformação, identifique a mudança exata e avalie a proposta resultante conforme a política aplicável. Determine se ela ainda atende à tarefa permitida e se suas condições de aprovação mudaram. Preserve a proposta original e a relação com sua substituta. Se o executor não consegue usar a substituta aprovada de forma confiável, retornar parâmetros alterados não basta para comprovar que a solicitação original foi impedida.
Dividir um lote também muda o plano de execução. As novas solicitações precisam de decisões na granularidade adequada e de um meio de distinguir seus resultados. Se alguns itens autorizados forem atualizados e outros continuarem pendentes, informe explicitamente essa conclusão parcial. Não reenvie silenciosamente o restante não resolvido sob a decisão do subconjunto concluído nem presuma rollback e idempotência que a interface não tenha estabelecido.
Peça aprovação para uma operação identificável
Um pedido de aprovação deve apresentar a escolha relevante: quais recursos mudariam, o que mudaria neles e de quem seria a autoridade usada pelo executor. A pessoa que revisa precisa estar autorizada para aquele escopo. Um pedido genérico para “continuar” não estabelece, por si só, aprovação do responsável pelos recursos de outra equipe.
A orientação de autorização de transações da OWASP recomenda permitir que o usuário identifique e confirme os dados significativos da transação. No lote hipotético, isso significa tornar o escopo real proposto passível de revisão, em vez de mostrar apenas o nome da ferramenta. Os métodos de autorização financeira do documento não são requisitos para todo fluxo de agentes. OWASP Transaction Authorization Cheat Sheet.
Uma aprovação pendente precisa manter a proposta à qual se refere. Se a seleção mudar enquanto um revisor a analisa, determine se a aprovação continua aplicável à versão que seria executada. Aprovar não autoriza eliminar a verificação posterior de aplicabilidade. Se não houver revisor autorizado ou mecanismo de aprovação compatível, o sistema não deve tratar uma afirmação do agente como a autorização ausente.
Acompanhe as operações por trás da chamada inicial
Uma ferramenta pode enviar um job que depois descobre recursos, chama outro serviço ou inicia um processo. Uma verificação antes dessa chamada inicial pode governar o envio do job e deixar operações posteriores fora de sua visibilidade. Descreva esse limite explicitamente. Essa verificação não comprova que cada acesso a recurso decorrente da chamada foi inspecionado ou autorizado conforme a tarefa.
No exemplo do lote, um serviço remoto poderia aceitar somente uma expressão de seleção e resolvê-la depois. Um ponto de controle no cliente que não consegue observar o conjunto final não pode fazer a mesma afirmação de controle por item que um serviço que avalia cada destino resolvido. Os controles de acesso do próprio serviço continuam necessários, e uma decisão mais restrita no cliente precisa de um mecanismo compatível para limitar o trabalho que delega.
Quando MCP transporta uma solicitação de ferramenta, sua especificação exige que os servidores validem as entradas e implementem controles de acesso; também recomenda que os clientes mostrem as entradas e solicitem confirmação para operações sensíveis. Essas responsabilidades não significam que todo servidor implemente a autorização de negócio da tarefa ou avalie suboperações não visíveis na chamada. Examine o servidor e o caminho de execução reais. MCP Tools, 2026-07-28.
A mesma pergunta se aplica à permissão para usar um shell ou runner: o que a verificação inspeciona e o que o processo pode fazer depois com seu ambiente e suas permissões? A autorização no destino e o isolamento do processo executor têm papéis próprios. Um hook pré-execução não deve ser descrito como controle completo sobre subprocessos, acesso à rede ou efeitos remotos sem evidências desses limites.
Verifique o limite com casos benignos
Use um ambiente controlado com recursos sintéticos para revisar o projeto. Para o exemplo, proponha um lote inteiramente dentro da equipe abrangida pela delegação, um lote com recursos de duas equipes, uma seleção que muda depois da avaliação, um subconjunto transformado e uma solicitação ainda aguardando aprovação. Esses são casos de validação sugeridos, não testes executados para este guia.
Em cada caso, compare a proposta avaliada com o que o executor usou e o que o destino informou. O resultado deve permitir que um revisor distinga uma solicitação retida antes do envio de outra parcialmente processada, uma proposta substituta da original e o trabalho aceito das atualizações concluídas. Se observações por item não estiverem disponíveis, mantenha esse limite visível em vez de relatar um resultado de lote integralmente verificado.
Inclua na revisão o caminho em que a avaliação fica indisponível. Um sistema que continua nessa condição tem um limite preventivo diferente de outro que impede a operação. Registre o comportamento efetivamente aplicável e a autorização que permanece no destino. O guia de trilha de auditoria explica como especificar as relações e os limites de evidência necessários a essas conclusões.
O que a integração KonaSense analisada permite estabelecer
Na implementação PreToolUse do adaptador Claude Code analisada para o Kona for Agents, o adaptador constrói respostas de negação ou pedido de aprovação a partir de decisões de política e pode retornar argumentos de ferramenta atualizados no ramo Allow aplicável. A resposta com entrada alterada emite uma decisão Allow explícita; ela não deve ser descrita como preservando todo pedido nativo de permissão. A aplicação da resposta depende do host.
Essa implementação retorna Allow quando a avaliação de política falha. Portanto, o código não comprova um controle que sempre bloqueia, governança por item para o lote hipotético ou autoridade sobre operações posteriores de um executor remoto. Verifique o host instalado, a integração e o comportamento da ferramenta para o efeito específico sob governança. O exemplo e as opções de projeto deste guia não são resultados de testes dessa integração.