Hooks

The plugin installs a PreToolUse and a PostToolUse hook that run tw.py hook pre and tw.py hook post. They do nothing until TOKENWRIGHT_HOOKS is set.

TOKENWRIGHT_HOOKS	Effect
unset or anything else	nothing, no output
warn (also 1 or on)	a note to the agent
block	the pre hook denies the read; the post hook still only warns

What triggers them

The pre hook fires on a Read with no offset and no limit of a file larger than 24,000 bytes. The post hook warns on any tool except Read whose response, as JSON, is 20,000 characters or more (a big read was already warned about before it ran). Since 0.2.7 it also runs after Read and Glob and keeps a session meter: each time the session's tool output passes another 25,000 tokens it adds a note such as tokenwright meter: ~50k tokens of tool output so far this session (most from Read, ~31k). Every later turn carries it until /compact or /clear. tw.py meter prints the same count.

What the agent sees

With warn, a whole read of a 30,000-byte file:

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": "tokenwright: huge.txt is ~7500 tokens. If you need a few lines, Grep -n for them and Read with offset/limit instead."}}

With block, the same read:

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "tokenwright: huge.txt is ~7500 tokens. If you need a few lines, Grep -n for them and Read with offset/limit instead."}}

A Bash call that returned 25,000 characters:

{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": "tokenwright: that Bash output was ~6254 tokens. Next time trim at the source (head, --stat, -q, head_limit) or hand the sweep to a subagent."}}

Turn them on

Set the variable where Claude Code starts, for example in your shell profile or the env block of settings.json. Start with warn; use block once you trust it.