@tduyng/pi-timbre0.0.2

@tduyng/pi-timbre

Constrains the agent's prose and code before tokens are generated, then measures what still gets through.

For full design rationale, see src/README.md.

What it adds

before_agent_start: injects a constraint block into the system prompt each turn, which is the Never and Code sections of the catalog and nothing else; the five judgment sections are served on demand by timbre_review_guide.

tool_call: records the path a write touched, for the once-per-turn code check below, and notices a prose write once per file per session. It refuses nothing.

There was a preflight here that blocked the write, and this paragraph used to say so. It was removed in `0df54db3` because it repeated the report the result already carried, after `7f69c7ab` had already replaced the refusal with a note for the same reason. A blocked write discards the tool call and costs a full regeneration, which is more than the tell it prevented is worth.

The write is never refused, because refusing it discards the tool call and costs a full regeneration. One note per file per session: the model edits the spans the note names, and that edit is another write, which is another read.

tool_result note: appends a tell report to write and edit results for prose and TypeScript files.

### What the score was worth on `english`, and why the note is gone

It was a label, not a discriminator, on the checkpoint serving, and no reformulation of it fixed that. Seventeen samples, nine written by people and eight of this model's own replies: pi's vendor documentation, this repository's `AGENTS.md`, `GUIDE.md` from its first commit, and assistant replies from real sessions. All seventeen came back level 2. It is not reading length, since 200 characters of `AGENTS.md` scores the same as 3,500, and the argmax is not hiding a usable threshold either: the probability of level 0 separates the two classes at 0.167 AUC and `1 - p(level 2)` at 0.250, where chance is 0.5.

Three question shapes were measured on those same seventeen samples. The one as shipped scored 0.264. Rewriting the criteria so each level describes what it means, rather than naming it, scored 0.250. Replacing the three-level score with a single continuous judgement scored 0.514. None separates, so this is the checkpoint's ceiling and not the wording. `PLAN.md` records the same wall from the other side: making an instruction more precise collapsed its spread from 0.380 to 0.199, and the vaguer phrasing carried more signal than the precise one.

The one place a session does record who wrote a paragraph is the transcript itself: a user message is human and an assistant message is machine. Over eighty real passages from this repository's sessions, forty of each, the score reaches 0.512 AUC, at means 0.706 against 0.764 with the wrong one on top, and the note would have fired on 30 of the 40 machine passages and 26 of the 40 human ones. Scored on markdown files instead, thirteen same-file pairs where the agent had rewritten an earlier version, it reaches 0.500, though both sides of those pairs are agent-written and the test cannot settle much. The note was three quarters true and three quarters false at the same time, which is the worst of both: it spends 110ms of server time per prose write to tell the model to rewrite prose that a person wrote.

So the label is gone, and with it the switch, the shadow records, the turn-end drain and the write-path call. `PLAN.md`'s own rule gives the reason: a question earns a call only when the decision it reads exists in the transcript, and the note was reading a question the transcript does not answer.

message_end: silently records tell density per assistant reply.

timbre_review_guide tool: serves the judgment procedure on request.

/timbre subcommands: on, off, fix <paths>, reset, status, stats.

ctrl+alt+t shortcut: toggles prevention with the same persistence as the command. The status bar shows on or off.

Token costs

The constraint block sits in the system prompt every turn. Pi marks it cacheable, and Anthropic bills cache writes at 1.25x and reads at 0.1x:

• The catalog, 986 tokens, and it is the only standing cost this package has
• Per turn, cache warm: 99 tokens
• Per turn, cache cold: 1,085 tokens

The constraint block is the only part of the rules the model reads before it writes, so it is built whenever prevention is on, . The read judges what landed and fails open, and a rule the model only meets afterwards is a rule it already broke.

Code is checked once per turn, not once per write. An oxlint spawn is about 130ms of fixed cost and a file adds 2-3ms, so a per-write check paid that fixed cost again for every file and still made the write wait for it. Batched at the end of the turn it is one spawn for everything the turn touched, off the write's path. It runs wherever the session runs, so there is no per-project command to remember.

Two arrangements came before this one and both failed. Sent as a follow-up, the note cost a whole model request, and by the time the model read one it had usually finished: sessions show it replying that the reports were stale and described states it had already replaced and committed. Fixing a finding also changes the file's signature, which earned a second follow-up for the tell the fix uncovered, so one file could produce a stream of them. Moved onto the next write or edit result, the note was unambiguous but dropped whenever a turn's last act was the write itself.

The note goes into the session as an entry at the turn's end. It used to ride the next write or edit result, which was unambiguous but dropped the note whenever a turn's last act was the write itself; a live check wrote export function go(): unknown, the scan found it, and the model never heard about it. An entry costs no model request, keeps its own provenance instead of borrowing a command's output, and is always delivered. Nothing else stands in for it, because nothing blocks a write. What remains is the deterministic tell report on the write and edit result, which covers the mechanical tells in the text the model wrote, so what is given up is the code check's end-of-task report rather than the prose report.

A 30-turn session costs about 3k tokens with a 1-hour cache TTL. The same session costs 33k if every turn goes cold, which is what Pi's default 5-minute TTL produces.

What prevention is worth

Two runs, same model, scratch projects, prevention seeded through the extension's own persisted setting, replies scored by the deterministic scan. Counts are raw rather than per 1,000 characters: in the three-arm run the arms wrote within 7 percent of each other per reply, so normalising by length only re-expressed the same ordering.

Mechanical tells are the em dashes, semicolons and invisible characters. Judgment tells are the wall paragraphs and the monotone cadence.

run	arm	replies	mechanical	judgment
1	prevention on	12	1	9
1	prevention off	19	14	22
2	full catalog, prevention on	12	2	8
2	Never and Code only, prevention on	12	3	11
2	prevention off	14	15	7

The mechanical result is established and replicated. Prevention takes them from 14 and 15 down to 1, 2 and 3, and the catalog that does it is the 117-token Never section: the reduced build carries the whole effect, so the other five prose sections are not what suppresses an em dash. These are the rules a machine can state exactly, and the model follows them when told.

The judgment result is not established, and this table contradicts the earlier reading of it. Run 1 put judgment tells at 9 against 22 and looked like a 22 percent improvement per 1,000 characters. Run 2 put them at 8 and 11 against 7, which is no effect in either direction. The first reading came from normalising by length across arms that wrote different amounts; the second does not need that correction, and the honest summary is that the catalog's prose sections have no demonstrated effect on the tells this scanner can count.

That is not evidence they are useless, because the scanner is blind to what they address. Name the actor, Claims, Voice and Register are about attribution, sourcing and register, and none of the 22 patterns looks for any of those. So the 660 tokens they cost, about two thirds of the injected block, are being measured by an instrument that cannot see their subject. Closing that needs either patterns that detect what the sections forbid, or a reader scoring the prose, and neither exists. Until then the number to watch is the mechanical one, which is real.

A reader scoring the prose does not work either

The obvious way to measure the prose sections is to ask the model to read the prose, which is the one thing a regex cannot do. So: score both arms of the A/B with a question about the writing rather than the authorship. Not "was this machine-written", which is flat at chance above, but "how well does this paragraph hold a reader's attention and say something specific", on the scale restsates what the reader already knows to earns every sentence it spends.

Ten replies per arm, 18,660 characters. Prevention on averaged 0.493 on the top criterion, prevention off 0.537. AUC 0.390, against chance at 0.500. The off arm scored slightly higher, which is the same below-chance result the authorship question gave, from a different angle.

That is four attempts on this checkpoint, three question shapes for authorship and a quality read on top, all at or below chance. The boundary is now clear enough to state: this checkpoint does coarse judgements about session state and does not do judgements about prose. The compaction question answers 0.8 or 0.013; the bulk-read relevance answer sits at 0.603 and is not flat. Nothing written about a paragraph has moved off chance.

The relevance is not in question even though the measurement is. Every one of the 500 prose samples this project has recorded is prose over the 40-character floor, and 19 percent of them tripped a pattern, so this agent writes prose constantly and the sections describe prose it is producing. What is missing is any way to know whether it is following them.

So the honest accounting for the 660 tokens is this. They are not measured to help, and the instrument that could measure them is the one thing that does not work. They now sit in the on-demand guide rather than in front of every request, which is the middle option of the three: the rules still exist and still read the same, they just wait for timbre_review_guide. That took the injected block from 986 tokens to 326 and the suite's per-request overhead from about 3,627 to about 2,967.

The 30 patterns that were removed, and why that is not the same gap

The scanner had 52 patterns. 37ec6428 cut 30 that had never fired, leaving the 19 measured ones plus three forensic catchers, and the reasoning at the time was that they cost a regex each per reply while measuring nothing.

That reasoning is weaker than it looks, because prevention was on for every sample behind it: all 500 prose samples this project had recorded were prevented: true, so a pattern for a tell the model had stopped producing could not have fired. Never firing is what a working guard looks like from the inside.

Re-testing them settled it anyway, twice. Scoring both arms of the run above with all 30 restored, across 24 replies and about 20,000 characters of technical prose, not one of them fired in either arm.

The obvious objection is that this workload never writes an essay, so of course the essay patterns are quiet, and this repository does have a prose skill for exactly that. So the second test asked for the genre directly: five article-shaped prompts per arm, a blog post arguing for deletion, an opinion piece on estimates, a reflective post on trunk-based development, an article opening against on-call heroics, and a piece on error messages. Ten replies, about 14,000 characters, prevention on and off. Zero of the 30 fired again. The only patterns that fired were em-dash and semicolon, both of which are still in the set.

That is two independent corpora and 10,703 recorded samples with the same answer. They target essayistic tells: rhetorical-hook, stock-opener, upbeat-closer, strawman-objection, fractal-summary, question-heading. Ten replies is a thin sample on its own, but asking for the genre and getting silence is a stronger signal than never asking. The removal stands, and the honest reason is narrower than "they measure nothing": they measure a genre that does not appear here even when requested.

So the blindness above is real but it is not a broken instrument. The two claims are different. The 660 tokens teach rules for prose this agent does not write, which is a question about the catalog, and it is why they moved to the guide. The scanner's missing patterns would detect those rules in a genre that does not appear here, which is a question about nothing.

Configuration

Variable	Default	Meaning
TIMBRE	1	Master switch
TIMBRE_PREVENT	1	Layer 0. 0 measures without injecting
TIMBRE_WATCH_CHAT	1	Measure assistant replies, silently

Set PI_CACHE_RETENTION=long in your environment. Pi's default cache TTL is 5 minutes. Any pause longer than that forces a full prefix rewrite on the next turn.

Memory and adaptation

One JSON file per project lives under $XDG_STATE_HOME/timbre/, keyed by a hash of the project path. The file holds a rolling window of up to 500 samples plus any live overrides set by /timbre. Writes are atomic (temp file, then rename), and two sessions in one repository merge rather than lock: a simultaneous write can still drop one sample, which is cheap next to a lock file that strands the extension.

A persisted setting outlives the session that set it. On session start, timbre reads the state file, loads any carried-over overrides, and announces the ones that differ from the env default. A subagent shares no memory with its parent session, only this file, so the state file is the only channel a /timbre off toggle has to reach it.

The prevention block is computed once per project and frozen for the session. Memory changes on every reply and every file write, so the block would shift mid-session. One changed word in the system prompt invalidates the entire cached prefix. Frozen, timbre adapts across sessions, which is the timescale a writing habit moves on.

Register classification

A commit message, an API reference, and a blog post do not share a correct voice. Path classifies the register, with no model call:

Path pattern	Register	Terse is correct	Voice allowed
blog/, posts/, essays/, drafts/	narrative	no	yes
CHANGELOG.md, HISTORY.md, RELEASE_NOTES.md, COMMIT_EDITMSG	changelog	yes	no
adr/, rfc/, spec/, reference/, api/, docs/, README.md, CONTRIBUTING.md	reference	yes	no
anything else	unknown	no	no

The register determines how the rhythm signal is interpreted. A flat cadence in a changelog is correct. The same cadence in a blog post is a tell.

Rhythm detection

Layer 2 adds two signals the regex patterns cannot see:

• Monotone cadence: uniform sentence lengths across the whole piece. Fires only when fewer than 30% of non-empty lines are structured (lists, headings) and the piece has at least one blank line, so technical docs stay quiet.
• Staccato run: four or more short sentences in a row. One short sentence is emphasis. A run is engineering.

Both are suppressed for registers where terse and even cadence is correct (reference, changelog, chat).

What it does not do

• Does not rewrite text after generation (prevention replaces cleanup).
• Does not use a corpus or model call for detection (deterministic regex). A local model asked which of two passages reads more machine-generated picked the same one in both orderings, and one asked to label a whole file read human and machine text at chance over 80 passages, so nothing here is blocked or detected on one.
• Does not recompute the prompt block per turn (frozen once, adapts across sessions).

Everything fails open: a broken scan or unwritable state leaves the turn untouched, and /timbre names a missing guidance/ directory rather than reporting "prevention on" over an empty block.

The code check needed the same treatment and did not have it. Both its inputs live outside this package: the oxlint binary is a dependency, but the rules are read from ~/.agents/tools/oxlint/anti-slop.config.ts by absolute path, and they are not in files. A spawn whose config is missing returns null, which is indistinguishable from a clean file, so on any machine without that directory the check reported nothing and said nothing. /timbre now names a missing binary or a missing rule config, which is the only reason to notice. A published install still has no rules of its own: it degrades to the prompt block and says so.

Install

pi install npm:@tduyng/pi-timbre

Local checkout: pi install /path/to/dotfiles/pi/agent/extensions/pi-timbre