DSH familySearch GitHub

hook / EffectTS

ets-hook-dsh-tool-coach

Teaches the model to stop reading files through the terminal

0.2.1 hook EffectTS

Facts

Package
@playform/ets-hook-dsh-tool-coach
Version
0.2.1
Kind
hook
Release
EffectTS
Licence
CC0-1.0
Directory
EffectTS/packages/ets-hook-dsh-tool-coach

What it does

Teaches the model to stop reading files through the terminal.

Read the full description in the README.

Conversation

The turn as a document: the calls every plugin page shares, what this package changes in them, and the order its work happens in.

Conversational

Lane

The same run as time: one row per resource, a bar per span, and the clock every record shares. A wait is drawn as an outline, because nothing is busy.

Session

The tree, the document, and the inspector read one record list. The switch at the top of the document changes the face they read, and the run changes with it.

session 7c41e0a2 | deepseek-v4.1-flash | max | 3 turns | 9 steps | 40 records | simulated

*emit~waterfall=serial>parallel

Add the session view to the trace page. Read the specimens first, then build the lane strip, the tree, the document, and the inspector from one authored run. The family's plugins must be visible on the records they touch, and the page must read the same run with the family off.

Turn 1Read the specimens14 records | 3 steps

Step 12 calls, 265 chars

Step 24 calls, 313 chars

Step 33 calls, 153 chars

Turn 2Write the run13 records | 3 steps

Step 43 calls, 174 chars

Step 52 calls, 258 chars

Step 62 calls, 115 chars

Turn 3Repair the run13 records | 3 steps

Step 72 calls, 143 chars

Step 83 calls, 184 chars

Step 92 calls, 123 chars

The turn

The same 3 calls on every plugin page, so a reader who moves between plugins stays in the same frame.

The 3 calls every plugin page shares, in sequence order
SeqCallOutcome
20bash ls -laok
21write src/index.tsok
22read src/index.tsok

Change

The one line that differs with this package installed, transcribed from its source by the dissection.

  1. Model the fourth cat a.md returns its content
  2. Transcript the result gains Tool-coach note (strike 4, read-class bash pattern)

64 character changed, from 35 to  64.

Property
Tool-use coaching
Knob
strike threshold, documented per rule
Seam
tools/post-execute

Flow

The order this package's work happens in, with the branch that decides it inline, transcribed from the source; the rule it obeys is the last band of Architecture.

  1. 01
    1. seam tools/post-execute
    why

    A terminal call settles; the coach judges bash, pwsh, and the configured judge tools.

  2. 02
    Normalize the command, then classify it: write, read, search, discovery, control
    why

    Heredoc bodies are stripped and substitutions masked before any row is matched.

  3. 03
    branch The head is exempt: a build, a test, git, a package manager, or a file lifecycle
    why

    An exempt head dominates its pipe, so a diff redirected to a file is still exempt.

  4. 04
    pass exempt <tool> <pattern>: one line, and the call is not judged
    why

    An exempt call neither strikes nor escalates, and the ledger is its only trace.

  5. 05
    Tier 0: one offense line, and the strike lands in the window
    why

    The model sees nothing at tier 0; the ledger is the only record.

  6. 06
    branch The class reaches threshold strikes inside window judged calls, past the cooldown
    why

    The note is one per class, not one per call.

  7. 07
    Tier 1: one notice with the live tool line, prepended as additionalContexts
    why

    The tool name, the first sentence of its description, and its primary parameter come from the registry.

  8. 08
    branch escalateThreshold offenses since the last note
    why

    The escalation is a section rather than a louder notice.

  9. 09
    Tier 2: the persistent section, appended at system-prompt/assemble
    why

    The section is rebuilt on its own TTL and again when the tool registry changes.

  10. 10
    branch enforce is on, and the class has enforceThreshold strikes
    why

    Off by default; write is the narrow scope, and all adds read and search.

  11. 11
    fail Tier 3: tools/pre-execute denies the call, with the lesson as the reason
    why

    Discovery and control are never denied, because flagging them hard dilutes the signal.

  12. 12
    store ~/.dsh/playform/ets-hook-dsh-tool-coach.log
    why

    Every tier writes its own line, and the deny is byte-exact.

Harness

The laws the package states, the line it writes when it loads, the seam the harness dispatches with none of the family, and the surface and knobs a run can set.

Default

What the harness does at this package's seam with none of the family installed, so the surface below has something to be a difference from.

The harness dispatches tools/post-execute as a waterfall and already has listeners there: claude-code-mods, hooks-claude-code, hooks-codex, repeat-tool-reminder, spill-policy, tool-fs-search.

A waterfall listener receives the payload and may return a changed one, so the harness's own listeners can already change what the model reads. This package adds another listener to that list.

Surface

Every listener, tool, service, and knob the README documents.

The surfaces ets-hook-dsh-tool-coach registers
KindNameWhat
listenertools/post-executejudges every terminal call; tier-0 ledger + tier-1 notice via additionalContexts (source {kind: 'tool-coach', form: 'notice', summary: '<tool> <class> × <n>'})
listenertools/pre-executetier 3: denies the terminal call with the lesson as the deny reason
listeneragent/pre-stepthe clean-window accounting between judged calls
listenersystem-prompt/assembletier 2: the persistent "Tool discipline" section
listenertools/changerebuilds the cached section when the registry changes
configSCHEME.mdthe full Schemastery schema (see the table below)

Install

The package as the profile adds it.

Install sh
pnpm add @playform/ets-hook-dsh-tool-coach

Configuration

Every knob this plugin documents, with its default.

Configuration of ets-hook-dsh-tool-coach
FieldTypeDefaultMeaning
logbooleantruevolatile - the shared factory log switch
logFilestring~/.dsh/playform/hook-dsh-tool-coach.logvolatile - the ledger file
enabledbooleantruevolatile - the coach switch
judgeToolsarray["bash", "pwsh"]volatile - the terminal tools that are judged
thresholdnumber3volatile - tier-1 strikes within the window
windownumber8volatile - the sliding judged-call window
cooldownnumber10volatile - judged calls between tier-1 notes
escalateThresholdnumber6volatile - offenses since the last note that turn tier 2 on
cleanWindownumber12volatile - clean calls that turn tier 2 off
enforceunionoffvolatile - off / write / all, the tier-3 deny scope
enforceThresholdnumber4volatile - strikes since the last note that deny
exemptPatternsarrayDEFAULT_EXEMPTSvolatile - the exempt command heads
patternTablearrayDEFAULT_PATTERNSvolatile - { pattern, class, tool, note? } rows
notesobjectfirst / persistent / denied templatesvolatile - the three model-facing note texts
fetchLivebooleantruevolatile - fetch tool data from the live registry
maxSectionToolsnumber5volatile - the tier-2 tool-table row cap
sectionTtlnumber20volatile - judged calls between tier-2 section rebuilds

Family

The neighbours at the same seam, the arms beyond it, the twin in the other release tree, and the packages this one needs.

Neighbours

The behavior map lists 10 answers at tools/post-execute, in the order the family registers them.

The family's answers at tools/post-execute, in the order the behavior map lists them
AnswerEffectPosition
hook-dsh-ccrrewriteneighbour
hook-dsh-comment-filterrewriteneighbour
hook-dsh-convention-suggesteradviseneighbour
hook-dsh-doc-suggesteradviseneighbour
hook-dsh-edit-suggesteradviseneighbour
hook-dsh-graph-suggesteradviseneighbour
hook-dsh-replay-suggesteradviseneighbour
hook-dsh-search-suggesteradviseneighbour
hook-dsh-test-suggesteradviseneighbour
hook-dsh-tool-coachadviseits twin

Arms

The seams its source also registers, beyond the one its README documents.

Twin

The same package in the other release tree, when one exists.

Its twin is hook-dsh-tool-coach.

It registers the same listeners in the same order and composes the same ledger strings; the ledger file's name, which carries the package identity, and the factory base import are the only differences.

Dependencies

The packages this one imports, and whether each one is the family's own.

Dependencies of ets-hook-dsh-tool-coach
PackageRole
@playform/ets-base-dshfamily
@playform/ets-lib-dsh-corefamily
@playform/ets-plugin-dsh-factoryfamily

Person

What the person waits for, reads, and never sees.

The person sees the note arrive as context rather than as content, so the result it is about reads exactly as it did before.

Architecture

This plugin's own structure: the shape the portrait gives it, the facts its source documents, and the rule its flow obeys.

Shape

Plugs into the tools/post-execute and tools/pre-execute waterfalls, the system-prompt/assemble section, and the agent/pre-step reset.

The four-tier ladder that keeps file content out of the terminal.

  • Normalizes the command before matching, so an obfuscated variant still counts
  • Classifies a segment as write, read, search, discovery, or control, and lets an exempt head dominate its pipe
  • Escalates from a silent strike to a notice to a persistent section, and denies last
  • Names the right tool from the live registry, and falls back to a static table when the fetch fails
  • Its flow is the interesting part: the ladder is the hook, and the deny is only its last rung

Its shape machine belongs to Person.

Record

The release line, the source, and the files this page was read from.

Release

The versions the package's own changelog records, newest first.

  • 0.3.0
  • 0.2.1
  • 0.2.0
  • 0.1.0

Source

The package as the repository holds it.

Open the package source

Origin

The files this page was built from, and what each one supplies.

The files this page was read from 5
The files behind https://github.com/PlayForm/DeepSeek/tree/Current/EffectTS/packages/ets-hook-dsh-tool-coach
FileContributedState
package.jsonThe name, the version, the private flag, and the dependencies.read
README.mdThe summary, the surface table, and the configuration table.read
CHANGELOG.mdThe release lines and their versions.read
cordis.patch.ymlActivation: the bundle entry that mounts the plugin.read
Source/Function/Apply.tsThe listeners, their registration order, and the service the flow calls.read
Data
The monorepo, read during the build
Connection
Build-time read; nothing is fetched at runtime
Capture
package.json, README.md, CHANGELOG.md, Source/Function/Apply.ts
Expand provenance source

This page is static. It cannot invoke the plugin, read a ledger, or change a configuration. Every figure comes from those files; a missing README falls back to the manifest's own description, and a package with no surface table shows no surface section.