New features: Route Stickness, Handoff, Clarification, Read-Only/Transactional, Long Term Memory

libs/agent_framework/docs/MCP_CACHE.md

@@ -202,3 +202,6 @@ IC.TOOL_CALLED cached=true
 ```
 
 Quando houver `IC.MCP_CACHE_HIT`, não deve aparecer `IC.MCP_TOOL_EXECUTING` nem `IC.MCP_TOOL_EXECUTED`, porque o MCP Server não foi chamado.
+# Relação com políticas de execução
+
+Cache e política operacional são independentes. Classifique consultas e transações no arquivo opcional `config/tool_policies.yaml` do backend; mantenha `cache` no catálogo `tools.yaml`. Operações transacionais não devem ser cacheadas. Se o arquivo novo não existir, os campos legados de execução em `tools.yaml` continuam válidos.

libs/agent_framework/docs/MCP_PARAMETER_EXTRACTION.md

@@ -173,3 +173,39 @@ O framework deve executar extração somente quando:
 ```
 
 Sem `extract` declarado, nada é extraído.
+
+## Precedência dos valores
+
+A partir desta correção, a precedência efetiva é:
+
+```text
+1. argumento explícito já presente na tool call;
+2. valor extraído da mensagem pelo bloco extract;
+3. valor proveniente do Business Context via map;
+4. defaults globais ou específicos da tool.
+```
+
+O Business Context nunca sobrescreve um argumento explícito ou extraído. Para
+identificadores que obrigatoriamente vêm da mensagem, como `order_id`, não
+configure `contract_key: order_id`.
+
+Exemplo recomendado:
+
+```yaml
+consultar_pedido:
+  map:
+    customer_key: customer_id
+    session_key: session_id
+  extract:
+    order_id:
+      from: message
+      type: string
+      strategy: llm
+      description: >
+        Extraia somente o identificador do pedido informado explicitamente pelo
+        usuário. Retorne null quando não houver identificador.
+```
+
+A extração usa a generation `llm.mcp_parameter_extraction` e o profile
+`mcp_parameter_extraction`. Identificadores devem preferencialmente usar
+`type: string` para preservar zeros à esquerda, hífens e prefixos.