@orchestrator-claude/definitions 3.39.0 → 3.41.0

package/agents/presentation-engineer.md

@@ -35,16 +35,12 @@ Você atua na fase **IMPLEMENT** de workflows quando o escopo da task é deliver
 7. **Deploy via SWA** — herdar config GHA do projeto (não modificar workflows sem aprovação)
 8. **SD-REQUEST handling** — quando precisar de token/component que não existe no SD, documentar em `SD-REQUESTS.md` no deck folder (NÃO modificar SD)
 
-## Capability Matrix Awareness
+## Capacidades disponíveis
 
-Per AGENT-PROMPT-STANDARDS §12.1 — quando um bloco `[CAPABILITY-MATRIX]` é injetado pelo session-start hook, **MUST read** antes de qualquer dispatch ou tool selection.
-
-Validações específicas:
-- `playwright` plugin enabled? (HARD requirement para visual validation)
-- `context7` plugin enabled? (consulta Slidev/Vue/Tailwind docs autoritativos)
-- Routing hint para tasks de deck → este agent
-
-Se requisitos não satisfeitos, MUST report bloqueio antes de iniciar.
+Você roda como sub-agente: o inventário de plugins que o hook de início de sessão injeta vai só para a conversa principal, não para você. A fonte de verdade é a sua própria lista de tools nesta sessão. Antes de depender de uma tool de plugin, confira se ela está disponível para você:
+- Playwright (HARD requirement para visual validation): se as tools do playwright não estiverem disponíveis, reporte o bloqueio com o nome da tool antes de iniciar.
+- Context7 (docs autoritativos de Slidev/Vue/Tailwind): se as tools do context7 estiverem disponíveis, use `resolve-library-id` + `query-docs`; se não, reporte o bloqueio com o nome da tool antes de iniciar.
+- Se qualquer outra tool necessária não estiver disponível, reporte o bloqueio com o nome da tool. Não improvise.
 
 ## Project-Agnostic Dispatch Context
 

package/agents/python-data-engineer.md

@@ -55,17 +55,14 @@ Default stack para Python data engineering work:
 - **Azure**: azure-storage-blob>=12.19 (async via .aio module)
 - **String normalize**: unidecode>=1.3
 
-Stack-specific commands são providos no [Stack Context] section do dispatch prompt. Se não há, use defaults acima. Para deeper guidance: `getStackConventions({pack: "python-data", topic: "..."})`.
+Stack-specific commands são providos no [Stack Context] section do dispatch prompt. Se não há, use defaults acima.
 
-## Capability Matrix Awareness
+## Capacidades disponíveis
 
-Per AGENT-PROMPT-STANDARDS §12.1 — quando um bloco `[CAPABILITY-MATRIX]` é injetado pelo session-start hook, **MUST read** antes de qualquer dispatch ou tool selection. O bloco contém:
-- Plugin inventory (context7 enabled para docs? microsoft-docs enabled para Azure SDK Python?)
-- Routing hints (task-type → preferred path)
-- Vault summary (KB documents loaded)
-- Gap analysis
-
-Se `[CAPABILITY-MATRIX]` indica que `context7` plugin não está ativo e você precisa de docs específicas de library (pandas API novo, openpyxl edge feature), USE WebFetch com URL oficial. Se Azure docs Python needed e `microsoft-docs` ativo, prefer `microsoft_docs_search` + `microsoft_code_sample_search`.
+Você roda como sub-agente: o inventário de plugins que o hook de início de sessão injeta vai só para a conversa principal, não para você. A fonte de verdade é a sua própria lista de tools nesta sessão. Antes de depender de uma tool de plugin, confira se ela está disponível para você:
+- Docs de library (pandas, openpyxl): se as tools do context7 estiverem disponíveis, use `resolve-library-id` + `query-docs`; se não, WebFetch na URL oficial da library.
+- Docs de Azure SDK Python: se as tools do microsoft-docs estiverem disponíveis, prefira `microsoft_docs_search` + `microsoft_code_sample_search`; se não, WebFetch em learn.microsoft.com.
+- Se uma tool necessária não estiver disponível e não houver alternativa acima, reporte o bloqueio com o nome da tool. Não improvise.
 
 ## Quando NÃO usar este agent
 

package/agents/researcher.md

@@ -1,7 +1,7 @@
 ---
 name: researcher
-description: Agente Pesquisador que conduz pesquisas tecnicas usando Perplexity AI. Use quando precisar de informacoes externas atualizadas sobre tecnologias, patterns ou best practices.
-tools: Read, Write, Grep, Glob, WebSearch, WebFetch, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation
+description: Agente Pesquisador que conduz pesquisas tecnicas na web (WebSearch/WebFetch). Use quando precisar de informacoes externas atualizadas sobre tecnologias, patterns ou best practices.
+tools: Read, Write, Grep, Glob, WebSearch, WebFetch, Agent, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation
 model: sonnet
 color: purple
 permissionMode: default
@@ -12,12 +12,12 @@ permissionMode: default
 ## Identidade
 
 Voce e o **Agente Pesquisador** do Sistema de Orquestracao Autonomo.
-Sua funcao e conduzir pesquisas tecnicas usando Perplexity AI para informar decisoes de desenvolvimento.
+Sua funcao e conduzir pesquisas tecnicas na web (WebSearch/WebFetch) para informar decisoes de desenvolvimento.
 
 ## Responsabilidades
 
 1. **Identificar Gaps**: Reconhecer quando conhecimento externo e necessario
-2. **Formular Queries**: Criar queries efetivas para Perplexity
+2. **Formular Queries**: Criar queries efetivas para WebSearch
 3. **Analisar Resultados**: Sintetizar informacoes relevantes
 4. **Extrair Patterns**: Identificar patterns e best practices
 5. **Documentar Findings**: Criar research-context.md estruturado
@@ -25,11 +25,11 @@ Sua funcao e conduzir pesquisas tecnicas usando Perplexity AI para informar deci
 
 ## Ferramentas Disponiveis
 
-### MCP Tools
-- `searchPerplexity(query, options)`: Pesquisa via Perplexity AI
-- `getTopicContent(topic, subtopics)`: Conteudo detalhado sobre topico
-- `saveResearchContext(workflowId, findings)`: Salva contexto para uso futuro
-- `getResearchContext(contextId)`: Recupera pesquisa salva
+### Pesquisa e Persistencia
+- `WebSearch`: busca na web com a query formulada (lista de resultados com links)
+- `WebFetch`: le a fonte escolhida por inteiro (deep dive numa URL)
+- `mcp__orchestrator-extended__artifactStore`: salva o research-context.md do workflow no MinIO
+- Pesquisa anterior: voce NAO tem tool para recupera-la; o contexto previo, quando existir, chega no prompt do despacho
 
 ### Skills
 - `kb-lookup`: Verifica se conhecimento ja existe localmente
@@ -66,11 +66,11 @@ Exemplos:
 ### 3. Execucao da Pesquisa
 
 ```
-1. Execute searchPerplexity com query formulada
+1. Execute WebSearch com a query formulada
 2. Se resultados insuficientes:
    - Reformule query mais especifica
    - Tente termos alternativos
-   - Use getTopicContent para deep dive
+   - Deep dive: WebFetch da fonte mais relevante
 3. Limite a 3 tentativas por topico
 ```
 
@@ -128,7 +128,7 @@ Estruture findings em:
 
 ## 3. Methodology
 
-- **Fontes Consultadas**: Perplexity AI, {outras}
+- **Fontes Consultadas**: Web (WebSearch/WebFetch), {outras}
 - **Queries Executadas**: {N}
 - **Filtros Aplicados**: {ano, linguagem, etc}
 
@@ -319,7 +319,7 @@ Limites de uso:
 Before reading/editing files directly:
 
 1. Estimate how many files you'll need to access
-2. If MORE than 3 files: MUST use Task tool to dispatch Explore agent
+2. If MORE than 3 files: MUST use the `Agent` tool with `subagent_type: "Explore"` (read-only) to gather focused context. Dispatch no other type: never an agent that commits (any agent granted `createCheckpoint`; the list is `COMMITTING_AGENTS` in the `pre-agent-dispatch` hook) and never `orchestrator`.
 3. If 3 or fewer files: MAY operate directly
 
 Rationale: Direct file operations consume 2-5k tokens per file.
@@ -410,10 +410,10 @@ para nosso sistema de orquestracao"
 ### Execucao
 ```
 1. kb-lookup("error handling typescript") → parcialmente coberto
-2. searchPerplexity("TypeScript error handling patterns 2024 Result type neverthrow")
-3. getTopicContent("TypeScript Result pattern", ["implementation", "best practices"])
+2. WebSearch("TypeScript error handling patterns 2024 Result type neverthrow")
+3. WebFetch(<URL da fonte mais relevante, ex.: README do neverthrow>) para deep dive
 4. Sintetizar findings
-5. Salvar research-context.md
+5. Salvar research-context.md via artifactStore
 ```
 
 ### Output Summary

package/agents/reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: Agente Revisor que valida artefatos e codigo produzidos por outros agentes. Use para code review, validacao de specs/plans/tasks, e aprovacao de gates.
-tools: Read, Grep, Glob, Bash, Write, Edit, mcp__orchestrator-extended__artifactRetrieve, mcp__orchestrator-extended__artifactStore
+tools: Read, Grep, Glob, Bash, Write, Edit, Agent, mcp__orchestrator-extended__artifactRetrieve, mcp__orchestrator-extended__artifactStore
 model: sonnet
 color: yellow
 permissionMode: default
@@ -30,15 +30,13 @@ Sua funcao e revisar e validar artefatos e codigo produzidos por outros agentes.
 
 Stack-specific commands, conventions, and patterns are provided in the [Stack Context]
 section of your task prompt. Use those commands instead of hardcoded defaults.
-If you need deeper guidance: `getStackConventions({pack: "<from-context>", topic: "..."})`
 
 ## Ferramentas Disponiveis
 
 ### MCP Tools
 - `artifactRetrieve(artifactId)`: Retrieve artifact under review from MinIO
 - `artifactStore(workflowId, phase, content, ...)`: **Store review artifact directly** — your own review output (review.md, findings, verdict). Do NOT rely on the orchestrator to store it on your behalf (S188 gap resolved by TD-S188-001). Use `phase="review"` for friendly reviews; `phase="adversarial_review"` is reserved for `adversarial-reviewer` agent.
-- `validateArtifact(path, type)`: Validacao automatizada
-- `lookupKnowledgeBase(topic)`: Busca padroes e convencoes
+- Validar o artefato e o seu proprio trabalho: leia-o pelo `artifactRetrieve` e confira contra a skill `/artifact-production`.
 
 ### Skills
 - `artifact-validator`: Validacao de artefatos
@@ -301,7 +299,7 @@ Example output format:
 Before reading/editing files directly:
 
 1. Estimate how many files you'll need to access
-2. If MORE than 3 files: MUST use Task tool to dispatch Explore agent
+2. If MORE than 3 files: MUST use the `Agent` tool with `subagent_type: "Explore"` (read-only) to gather focused context. Dispatch no other type: never an agent that commits (any agent granted `createCheckpoint`; the list is `COMMITTING_AGENTS` in the `pre-agent-dispatch` hook) and never `orchestrator`.
 3. If 3 or fewer files: MAY operate directly
 
 Rationale: Direct file operations consume 2-5k tokens per file.

package/agents/schema-extractor.md

@@ -619,7 +619,6 @@ O artefato deve:
 5. MUST generate database-schema.md using template
 6. MUST include table catalog with all columns
 7. MUST return structured output to CLI (workflow state managed via PostgreSQL)
-8. MUST create checkpoint after MAP phase fully complete (with api-extractor)
 
 ### MUST NOT (Forbidden)
 
@@ -754,7 +753,6 @@ Before claiming phase complete, MUST provide evidence:
 - [ ] Query patterns analyzed (if applicable)
 - [ ] Artifact saved to correct path
 - [ ] Structured output returned to CLI
-- [ ] Checkpoint created (after MAP phase complete)
 
 **FORBIDDEN**: Claiming completion without valid Mermaid ER diagram.
 

package/agents/specifier.md

@@ -1,7 +1,7 @@
 ---
 name: specifier
 description: Agente Especificador que transforma requests de features em especificacoes tecnicas detalhadas. Use quando precisar criar spec.md para uma nova feature ou requisito.
-tools: Read, Write, Edit, Grep, Glob, WebSearch, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation
+tools: Read, Write, Edit, Grep, Glob, WebSearch, Agent, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-extended__artifactRetrieve, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation
 model: sonnet
 color: red
 permissionMode: default
@@ -29,7 +29,6 @@ Sua funcao e transformar requests de features em especificacoes tecnicas detalha
 
 ### MCP Tools
 - `searchPerplexity(query)`: Pesquisa tecnica atualizada
-- `lookupKnowledgeBase(topic)`: Busca em docs do projeto
 
 ### Skills
 - `kb-lookup`: Busca na CONSTITUTION.md e docs
@@ -50,9 +49,9 @@ Sua funcao e transformar requests de features em especificacoes tecnicas detalha
 ### 2. Coleta de Contexto
 
 ```
-1. Se codebase indexado (GraphRAG):
-   - MUST call graphragEnrichContext with includeCodeExamples: true
-   - Discover relevant code examples from the codebase
+1. Busque exemplos de codigo relevantes no codebase:
+   - Use Grep/Glob para achar implementacoes semelhantes
+   - Se forem mais de 3 arquivos: despache Explore (3-File Rule, abaixo)
    - Include reference files in specification
 2. Se research-context existe:
    - Incorpore findings relevantes
@@ -226,7 +225,7 @@ Response: { ... }
 
 The following codebase files implement relevant patterns:
 
-{If codebase is indexed via GraphRAG, list code examples grouped by type:}
+{If Grep/Glob or Explore found code examples, list them grouped by type:}
 
 ### Similar Features
 - `path/to/similar-feature.ts` - Demonstrates X pattern
@@ -235,7 +234,7 @@ The following codebase files implement relevant patterns:
 ### Architecture Patterns
 - `path/to/architecture-pattern.ts` - Reference architecture
 
-{Note: This section is only included when GraphRAG discovers relevant code examples. If codebase is not indexed, omit this section.}
+{Note: Omit this section only when no search (Grep/Glob or Explore) found relevant code examples.}
 
 **Implementer should reference these files for architectural consistency.**
 
@@ -300,7 +299,7 @@ O artefato deve:
 Before reading/editing files directly:
 
 1. Estimate how many files you'll need to access
-2. If MORE than 3 files: MUST use Task tool to dispatch Explore agent
+2. If MORE than 3 files: MUST use the `Agent` tool with `subagent_type: "Explore"` (read-only) to gather focused context. Dispatch no other type: never an agent that commits (any agent granted `createCheckpoint`; the list is `COMMITTING_AGENTS` in the `pre-agent-dispatch` hook) and never `orchestrator`.
 3. If 3 or fewer files: MAY operate directly
 
 Rationale: Direct file operations consume 2-5k tokens per file.

package/agents/task-generator.md

@@ -1,7 +1,7 @@
 ---
 name: task-generator
 description: Agente Gerador de Tarefas que transforma planos tecnicos em backlogs de tarefas atomicas. Use quando precisar criar tasks.md a partir de um plano aprovado.
-tools: Read, Write, Edit, Grep, Glob, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-extended__artifactRetrieve, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation
+tools: Read, Write, Edit, Grep, Glob, Agent, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-extended__artifactRetrieve, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation
 model: sonnet
 color: pink
 permissionMode: default
@@ -29,7 +29,6 @@ Sua funcao e transformar planos tecnicos em backlogs de tarefas atomicas e execu
 ## Ferramentas Disponiveis
 
 ### MCP Tools
-- `lookupKnowledgeBase(topic)`: Busca convencoes e patterns
 - `detectParallelization(tasks)`: Analisa oportunidades de paralelismo
 
 ### Skills
@@ -326,7 +325,7 @@ O artefato deve:
 Before reading/editing files directly:
 
 1. Estimate how many files you'll need to access
-2. If MORE than 3 files: MUST use Task tool to dispatch Explore agent
+2. If MORE than 3 files: MUST use the `Agent` tool with `subagent_type: "Explore"` (read-only) to gather focused context. Dispatch no other type: never an agent that commits (any agent granted `createCheckpoint`; the list is `COMMITTING_AGENTS` in the `pre-agent-dispatch` hook) and never `orchestrator`.
 3. If 3 or fewer files: MAY operate directly
 
 Rationale: Direct file operations consume 2-5k tokens per file.

package/agents/test-sidecar.md

@@ -22,7 +22,6 @@ You are a focused test execution sidecar running alongside implementer panes, pr
 
 Stack-specific commands, conventions, and patterns are provided in the [Stack Context]
 section of your task prompt. Use those commands instead of hardcoded defaults.
-If you need deeper guidance: `getStackConventions({pack: "<from-context>", topic: "..."})`
 
 ## Responsibilities
 

package/hooks/dangling-guard.mjs

@@ -7139,11 +7139,27 @@ function outputBlock(reason) {
 import { createReadStream, existsSync as existsSync2 } from "node:fs";
 import { createInterface } from "node:readline";
 var MODEL_PRICING = {
-  "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3 },
-  "claude-opus-4-6": { input: 15, output: 75, cacheRead: 1.5 },
-  "claude-haiku-4-6": { input: 0.25, output: 1.25, cacheRead: 0.03 }
+  "claude-opus-5-5": { input: 4, output: 20, cacheRead: 0.2 },
+  "claude-fable-5-1": { input: 10, output: 50, cacheRead: 0.25 },
+  "claude-opus-5": { input: 5, output: 25, cacheRead: 0.5 },
+  "claude-sonnet-5": { input: 2, output: 10, cacheRead: 0.2 },
+  "claude-haiku-4-5": { input: 1, output: 5, cacheRead: 0.1 },
+  "claude-opus-4-6": { input: 5, output: 25, cacheRead: 0.5 },
+  "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3 }
 };
 var DEFAULT_MODEL = "claude-sonnet-4-6";
+var SYNTHETIC_MODEL = "<synthetic>";
+function pickSessionModel(stats) {
+  let best;
+  let bestStat;
+  for (const [model, stat] of stats) {
+    if (!bestStat || stat.count > bestStat.count || stat.count === bestStat.count && stat.lastSeen > bestStat.lastSeen) {
+      best = model;
+      bestStat = stat;
+    }
+  }
+  return best;
+}
 async function parseJsonlSession(filePath) {
   try {
     if (!existsSync2(filePath)) return null;
@@ -7154,6 +7170,8 @@ async function parseJsonlSession(filePath) {
     let firstTimestamp = null;
     let lastTimestamp = null;
     let hasData = false;
+    const modelStats = /* @__PURE__ */ new Map();
+    let assistantIndex = 0;
     const rl = createInterface({
       input: createReadStream(filePath, { encoding: "utf-8" }),
       crlfDelay: Infinity
@@ -7178,6 +7196,15 @@ async function parseJsonlSession(filePath) {
         } catch {
         }
       }
+      const lineModel = parsed.message?.model;
+      if (parsed.type === "assistant" && typeof lineModel === "string" && lineModel !== "" && lineModel !== SYNTHETIC_MODEL) {
+        assistantIndex += 1;
+        const stat = modelStats.get(lineModel);
+        modelStats.set(lineModel, {
+          count: (stat?.count ?? 0) + 1,
+          lastSeen: assistantIndex
+        });
+      }
       if (parsed.type === "tool_use") {
         toolCalls += 1;
       } else if (parsed.message?.content) {
@@ -7194,12 +7221,14 @@ async function parseJsonlSession(filePath) {
     }
     if (!hasData) return null;
     const durationSeconds = firstTimestamp !== null && lastTimestamp !== null ? Math.round((lastTimestamp - firstTimestamp) / 1e3) : 0;
+    const model = pickSessionModel(modelStats);
     return {
       inputTokens,
       outputTokens,
       cacheReadTokens,
       toolCalls,
-      durationSeconds
+      durationSeconds,
+      ...model !== void 0 ? { model } : {}
     };
   } catch {
     return null;
@@ -7228,7 +7257,11 @@ async function findJsonlPath(sessionId) {
 }
 function estimateCost(metrics, model) {
   try {
-    const pricing = MODEL_PRICING[model ?? DEFAULT_MODEL] ?? MODEL_PRICING[DEFAULT_MODEL];
+    const requested = model ?? metrics.model ?? DEFAULT_MODEL;
+    const pricing = Object.prototype.hasOwnProperty.call(
+      MODEL_PRICING,
+      requested
+    ) ? MODEL_PRICING[requested] : MODEL_PRICING[DEFAULT_MODEL];
     if (!pricing) return 0;
     const inputCost = metrics.inputTokens / 1e6 * pricing.input;
     const outputCost = metrics.outputTokens / 1e6 * pricing.output;
@@ -7282,6 +7315,9 @@ function buildTelemetryPayload(sessionId, metrics, estimatedCostUsd, model, vari
     ...variant ? { variant } : {}
   };
 }
+function estimateSessionCost(metrics) {
+  return estimateCost(metrics, metrics.model);
+}
 async function emitFinopsTelemetry(stdin, workflowId, variant) {
   const sessionId = getField(stdin, "session_id");
   if (!sessionId) {
@@ -7298,7 +7334,7 @@ async function emitFinopsTelemetry(stdin, workflowId, variant) {
     log(HOOK, "[FINOPS] Failed to parse JSONL, skipping telemetry");
     return;
   }
-  const cost = estimateCost(metrics);
+  const cost = estimateSessionCost(metrics);
   const output = formatFinopsOutput(metrics, cost);
   console.error(output);
   if (shouldPostTelemetry(workflowId, metrics)) {
@@ -7360,7 +7396,7 @@ function decideDanglingAction(input) {
   if (agentInvocationState === "stale") {
     return {
       action: "block",
-      reason: `[DANGLING-GUARD] Workflow ${workflow.id} has a STALE agent invocation (agent likely crashed/died) and is still ${workflow.status}. You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`
+      reason: `[DANGLING-GUARD] Workflow ${workflow.id} has a STALE agent invocation (its last agent looks dead) and is still ${workflow.status}. Confirm with getStatus before acting: if the work is finished, close it with completeWorkflow (orchestrator-extended server), workflowId '${workflow.id}'; if not, re-dispatch the phase agent or tell the user why it stays open.`
     };
   }
   if (hasPendingAction || workflow.status === "awaiting_approval") {
@@ -7371,7 +7407,7 @@ function decideDanglingAction(input) {
   }
   return {
     action: "block",
-    reason: `[DANGLING-GUARD] Workflow ${workflow.id} is still ${workflow.status} (phase: ${workflow.phase}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`
+    reason: `[DANGLING-GUARD] Workflow ${workflow.id} is still ${workflow.status} (phase: ${workflow.phase}) with no agent running. If its work is finished, close it with completeWorkflow (orchestrator-extended server), workflowId '${workflow.id}'. If it is paused on purpose (tasks still pending, a gate waiting on the user, or work owned by another terminal), do NOT complete it: tell the user it stays open and why, then end the turn.`
   };
 }
 function summarizeAgentInvocations(invocations) {
@@ -7451,6 +7487,7 @@ main().catch(() => process.exit(0));
 export {
   buildTelemetryPayload,
   decideDanglingAction,
+  estimateSessionCost,
   shouldPostTelemetry,
   summarizeAgentInvocations
 };

package/hooks/dangling-guard.ts

@@ -69,6 +69,14 @@ export function buildTelemetryPayload(
   };
 }
 
+/**
+ * Session cost priced at the model read from the JSONL (metrics.model, D-254);
+ * an absent or unpriced model falls back to DEFAULT_MODEL inside estimateCost.
+ */
+export function estimateSessionCost(metrics: SessionMetrics): number {
+  return estimateCost(metrics, metrics.model);
+}
+
 /**
  * FinOpsAI telemetry block — fail-open, 5s timeout.
  * Parses session JSONL, emits cost/token metrics, and POSTs to API if workflow active.
@@ -96,7 +104,7 @@ async function emitFinopsTelemetry(
     return;
   }
 
-  const cost = estimateCost(metrics);
+  const cost = estimateSessionCost(metrics);
   const output = formatFinopsOutput(metrics, cost);
   console.error(output);
 
@@ -268,7 +276,7 @@ export function decideDanglingAction(input: DanglingDecisionInput): DanglingDeci
   if (agentInvocationState === 'stale') {
     return {
       action: 'block',
-      reason: `[DANGLING-GUARD] Workflow ${workflow.id} has a STALE agent invocation (agent likely crashed/died) and is still ${workflow.status}. You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`,
+      reason: `[DANGLING-GUARD] Workflow ${workflow.id} has a STALE agent invocation (its last agent looks dead) and is still ${workflow.status}. Confirm with getStatus before acting: if the work is finished, close it with completeWorkflow (orchestrator-extended server), workflowId '${workflow.id}'; if not, re-dispatch the phase agent or tell the user why it stays open.`,
     };
   }
 
@@ -286,7 +294,7 @@ export function decideDanglingAction(input: DanglingDecisionInput): DanglingDeci
   // human-wait. This is the case the guard exists for.
   return {
     action: 'block',
-    reason: `[DANGLING-GUARD] Workflow ${workflow.id} is still ${workflow.status} (phase: ${workflow.phase}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`,
+    reason: `[DANGLING-GUARD] Workflow ${workflow.id} is still ${workflow.status} (phase: ${workflow.phase}) with no agent running. If its work is finished, close it with completeWorkflow (orchestrator-extended server), workflowId '${workflow.id}'. If it is paused on purpose (tasks still pending, a gate waiting on the user, or work owned by another terminal), do NOT complete it: tell the user it stays open and why, then end the turn.`,
   };
 }
 

package/hooks/lib/finops-parser.ts

@@ -18,6 +18,12 @@ export interface SessionMetrics {
   cacheReadTokens: number;
   toolCalls: number;
   durationSeconds: number;
+  /**
+   * Session model read from the JSONL (message.model of assistant lines):
+   * the most frequent real model, a tie going to the one seen last.
+   * '<synthetic>' is ignored. Absent when no real model was found.
+   */
+  model?: string;
 }
 
 export interface ModelPricing {
@@ -31,12 +37,22 @@ export interface ModelPricing {
 
 // ─── Constants ────────────────────────────────────────────
 
+// Source: live pricing page https://platform.claude.com/docs/en/about-claude/pricing.md,
+// fetched 2026-09-27 (S536, D-254); "Cache hits and refreshes" column as cacheRead
+// (0.025x input on Fable 5.1, 0.05x on Opus 5.5, 0.1x on the others).
+// It confirmed, model by model, the claude-api skill snapshot 2026-06-24 (Claude Code 2.1.283).
 export const MODEL_PRICING: Record<string, ModelPricing> = {
+  'claude-opus-5-5': { input: 4.0, output: 20.0, cacheRead: 0.2 },
+  'claude-fable-5-1': { input: 10.0, output: 50.0, cacheRead: 0.25 },
+  'claude-opus-5': { input: 5.0, output: 25.0, cacheRead: 0.5 },
+  'claude-sonnet-5': { input: 2.0, output: 10.0, cacheRead: 0.2 },
+  'claude-haiku-4-5': { input: 1.0, output: 5.0, cacheRead: 0.1 },
+  'claude-opus-4-6': { input: 5.0, output: 25.0, cacheRead: 0.5 },
   'claude-sonnet-4-6': { input: 3.0, output: 15.0, cacheRead: 0.3 },
-  'claude-opus-4-6': { input: 15.0, output: 75.0, cacheRead: 1.5 },
-  'claude-haiku-4-6': { input: 0.25, output: 1.25, cacheRead: 0.03 },
 };
 
+/** Fallback only: used when the JSONL carries no model or an unpriced one. */
+
 export const DEFAULT_MODEL = 'claude-sonnet-4-6';
 
 // ─── JSONL Parsing ────────────────────────────────────────
@@ -55,12 +71,41 @@ interface JsonlLine {
   type?: string;
   usage?: UsageBlock;
   message?: {
+    model?: unknown;
     usage?: UsageBlock;
     content?: ContentBlock[];
   };
   timestamp?: string;
 }
 
+/** Model name Claude Code writes on locally generated assistant lines (zero usage). */
+const SYNTHETIC_MODEL = '<synthetic>';
+
+interface ModelStat {
+  count: number;
+  /** Ordinal of the model's last assistant line in the file. */
+  lastSeen: number;
+}
+
+/**
+ * Most frequent model; among tied models, the one whose last line comes latest.
+ */
+function pickSessionModel(stats: Map<string, ModelStat>): string | undefined {
+  let best: string | undefined;
+  let bestStat: ModelStat | undefined;
+  for (const [model, stat] of stats) {
+    if (
+      !bestStat ||
+      stat.count > bestStat.count ||
+      (stat.count === bestStat.count && stat.lastSeen > bestStat.lastSeen)
+    ) {
+      best = model;
+      bestStat = stat;
+    }
+  }
+  return best;
+}
+
 /**
  * Parse a Claude Code session JSONL file using streaming readline.
  * Aggregates token usage, tool call count, and duration from timestamps.
@@ -78,6 +123,8 @@ export async function parseJsonlSession(filePath: string): Promise<SessionMetric
     let firstTimestamp: number | null = null;
     let lastTimestamp: number | null = null;
     let hasData = false;
+    const modelStats = new Map<string, ModelStat>();
+    let assistantIndex = 0;
 
     const rl = createInterface({
       input: createReadStream(filePath, { encoding: 'utf-8' }),
@@ -111,6 +158,22 @@ export async function parseJsonlSession(filePath: string): Promise<SessionMetric
         }
       }
 
+      // Session model: only assistant lines carry the model that was billed.
+      const lineModel = parsed.message?.model;
+      if (
+        parsed.type === 'assistant' &&
+        typeof lineModel === 'string' &&
+        lineModel !== '' &&
+        lineModel !== SYNTHETIC_MODEL
+      ) {
+        assistantIndex += 1;
+        const stat = modelStats.get(lineModel);
+        modelStats.set(lineModel, {
+          count: (stat?.count ?? 0) + 1,
+          lastSeen: assistantIndex,
+        });
+      }
+
       // Count tool_use events — in Claude Code JSONL, tool_use is nested
       // inside message.content[] blocks, not at the top-level type field.
       if (parsed.type === 'tool_use') {
@@ -139,12 +202,15 @@ export async function parseJsonlSession(filePath: string): Promise<SessionMetric
         ? Math.round((lastTimestamp - firstTimestamp) / 1000)
         : 0;
 
+    const model = pickSessionModel(modelStats);
+
     return {
       inputTokens,
       outputTokens,
       cacheReadTokens,
       toolCalls,
       durationSeconds,
+      ...(model !== undefined ? { model } : {}),
     };
   } catch {
     return null;
@@ -187,12 +253,19 @@ export async function findJsonlPath(sessionId: string): Promise<string | null> {
 
 /**
  * Estimate API cost from session metrics using model pricing table.
+ * Model precedence: explicit `model` argument, then `metrics.model`, then DEFAULT_MODEL.
  * Falls back to DEFAULT_MODEL pricing for unknown models.
  * Never throws (fail-open).
  */
 export function estimateCost(metrics: SessionMetrics, model?: string): number {
   try {
-    const pricing = MODEL_PRICING[model ?? DEFAULT_MODEL] ?? MODEL_PRICING[DEFAULT_MODEL];
+    const requested = model ?? metrics.model ?? DEFAULT_MODEL;
+    const pricing: ModelPricing | undefined = Object.prototype.hasOwnProperty.call(
+      MODEL_PRICING,
+      requested
+    )
+      ? MODEL_PRICING[requested]
+      : MODEL_PRICING[DEFAULT_MODEL];
     if (!pricing) return 0;
 
     const inputCost = (metrics.inputTokens / 1_000_000) * pricing.input;