Files

Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)

Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.

2026-10-06 01:47:40 +02:00

3.2 KiB

Raw Blame History

Monitor de Janela de Contexto

Um hook pós-ferramenta (PostToolUse para o Claude Code, AfterTool para o Antigravity CLI) que avisa o agente quando o uso da janela de contexto está elevado.

Problema

A barra de status exibe o uso de contexto para o usuário, mas o agente não tem consciência dos limites de contexto. Quando o contexto está se esgotando, o agente continua trabalhando até atingir o limite — potencialmente no meio de uma tarefa, sem nenhum estado salvo.

Como Funciona

O hook da barra de status grava métricas de contexto em /tmp/claude-ctx-{session_id}.json
Após cada uso de ferramenta, o monitor de contexto lê essas métricas
Quando o contexto restante cai abaixo dos limiares, ele injeta um aviso como additionalContext
O agente recebe o aviso em sua conversa e pode agir de acordo

Limiares

Nível	Restante	Comportamento do Agente
Normal	> 35%	Sem aviso
ALERTA	<= 35%	Encerrar a tarefa atual, evitar iniciar trabalhos complexos novos
CRÍTICO	<= 25%	Parar imediatamente, salvar estado (`/msd-pause-work`)

Debounce

Para evitar sobrecarregar o agente com avisos repetidos:

O primeiro aviso sempre é disparado imediatamente
Avisos subsequentes exigem 5 usos de ferramenta entre eles
A escalada de severidade (ALERTA -> CRÍTICO) ignora o debounce

Arquitetura

Hook da Barra de Status (msd-statusline.js)
    | escreve
    v
/tmp/claude-ctx-{session_id}.json
    ^ lê
    |
Monitor de Contexto (msd-context-monitor.js, PostToolUse/AfterTool)
    | injeta
    v
additionalContext -> Agente recebe o aviso

O arquivo de ponte é um objeto JSON simples:

{
  "session_id": "abc123",
  "remaining_percentage": 28.5,
  "used_pct": 71,
  "timestamp": 1708200000
}

Integração com o MSD

O comando /msd-pause-work do MSD salva o estado de execução. A mensagem de ALERTA sugere utilizá-lo. A mensagem CRÍTICA instrui o salvamento imediato do estado.

Configuração

Ambos os hooks são registrados automaticamente durante a instalação do npx @golem15/msd-core — nenhuma etapa manual é necessária em circunstâncias normais. Para detalhes de configuração de hooks, substituições de limiares e exemplos de registro manual, consulte Configuração.

Como referência rápida: o hook da barra de status se registra como statusLine em settings.json; o monitor de contexto (msd-context-monitor.js) se registra como um hook PostToolUse (ou AfterTool para o Antigravity CLI). Ambas as entradas utilizam o caminho absoluto do executável Node que executou o instalador. No Windows PowerShell, prefixe caminhos de executáveis entre aspas com &.

Segurança

O hook envolve tudo em try/catch e encerra silenciosamente em caso de erro
Ele nunca bloqueia a execução de ferramentas — um monitor com falha não deve interromper o fluxo de trabalho do agente
Métricas obsoletas (com mais de 60s) são ignoradas
Arquivos de ponte ausentes são tratados de forma elegante (subagentes, sessões novas)

3.2 KiB Raw Blame History