@tech-leads-club/harness-toolkit 0.2.1

package/docs/providers/claude-code.md

@@ -0,0 +1,118 @@
+---
+type: Provider
+title: "Claude Code provider"
+description: "The Claude Code adapter — capability descriptor, event mapping, and wiring target for the settings.json hooks block in Claude Code's resolved config directory."
+tags: [provider, claude-code]
+timestamp: "2026-07-29"
+---
+
+# Claude Code provider
+
+Source: `src/providers/claude/`.
+
+## Detection
+
+`claude.detect.ts`: a raw hook payload is Claude Code's when `hook_event_name` is PascalCase (e.g.
+`PreToolUse`) and either `cwd` or `transcript_path` is present.
+
+## Capability descriptor
+
+`claude.capabilities.ts`:
+
+| Capability | Value |
+| --- | --- |
+| `enforcesHooks` | `true` |
+| `askSupportedOn` | `["tool.before", "shell.before", "mcp.before", "read.before"]` — includes `tool.before`, unlike Cursor (see [/decisions/ad-009.md](/decisions/ad-009.md), note) |
+| `sessionEnv` | `false` |
+| `nativeLoopCounter` | `false` — `Stop` carries no loop counter; `core/turn` supplies it instead (see [/decisions/ad-014.md](/decisions/ad-014.md)) |
+| `dedicatedShellEvent` | `false` — shell is `PreToolUse`/`PostToolUse` with `tool_name: "Bash"` |
+| `toolInputRewrite` | `true` |
+| `toolOutputRewrite` | `true` |
+| `contextAtToolBefore` | `true` |
+| `contextAtToolAfter` | `true` |
+| `contextAtStop` | `true` — `Stop` accepts `hookSpecificOutput.additionalContext` for feedback that continues the turn |
+| `sessionStartContextReliable` | `true` — `SessionStart` delivers `hookSpecificOutput.additionalContext`, capped at 10,000 characters |
+| `usageInPayload` | `false` — cost comes from the transcript, not the hook payload |
+| `effortSignal` | `true` — `effort.level` (`low\|medium\|high\|xhigh\|max`) |
+| `thoughtEvent` | `false` |
+
+## Policy defaults
+
+`claude.policy-defaults.ts` supplies no model allowlist and no blocked patterns — see
+[/decisions/ad-011.md](/decisions/ad-011.md).
+
+It used to ship three model slugs, and an empty project list fell back to them, so a spawn could be refused by a
+list that appears nowhere in the project. This page named a fourth that the code did not, which is what a shipped
+catalogue does over time. `subagents.allowedModels` is the operator's and has no other source; an empty one
+enforces nothing and `doctor` says so ([/decisions/ad-053.md](/decisions/ad-053.md)).
+
+## Event mapping
+
+`claude.inbound.ts` maps Claude's PascalCase hook names to `HarnessEventKind`. Unlike Cursor, `PreToolUse`
+and `PostToolUse` are single dispatcher hooks that fan out by `tool_name`:
+
+| Claude hook | Fan-out rule | `HarnessEventKind` |
+| --- | --- | --- |
+| `SessionStart` | — | `session.start` |
+| `SessionEnd` | — | `session.end` |
+| `UserPromptSubmit` | — | `prompt.submit` |
+| `PreToolUse` | `tool_name === "Bash"` | `shell.before` |
+| `PreToolUse` | `tool_name` matches `mcp__*` | `mcp.before` |
+| `PreToolUse` | `tool_name === "Read"` | `read.before` |
+| `PreToolUse` | otherwise | `tool.before` |
+| `PostToolUse` | `tool_name === "Bash"` | `shell.after` |
+| `PostToolUse` | `tool_name` matches `mcp__*` | `mcp.after` |
+| `PostToolUse` | `tool_name` is `Edit`/`Write` | `edit.after` |
+| `PostToolUse` | otherwise | `tool.after` |
+| `PostToolUseFailure` | — | `tool.failure` |
+| `SubagentStart` | — | `subagent.start` |
+| `SubagentStop` | — | `subagent.stop` |
+| `Stop` | — | `stop` |
+| `PreCompact` | — | `compact.before` |
+| `MessageDisplay` | — | `response.after` |
+
+Claude has no `thought.after` equivalent (`thoughtEvent: false`).
+
+## Field paths
+
+Exact JSON field paths this adapter reads are pinned in
+[/decisions/ad-014.md](/decisions/ad-014.md) — including the one inferred rather than documented
+(`tool_input.file_path` for Edit/Write/Read).
+
+## Wiring target
+
+`claude.wiring.ts` merges (`strategy: "merge"`) into `~/.claude/settings.json`'s `hooks` block —
+never replacing the file wholesale, since a user's own Claude settings may already exist. Every entry uses
+exec form (`command: "node"`, `args: [launcherPath, handler]`) on every platform, bypassing shell
+tokenization so there is no quoting variant to get wrong. Handler names are the
+`src/entrypoints/<name>.ts` filenames (see [/decisions/ad-015.md](/decisions/ad-015.md)):
+`session-start`, `session-end`, `prompt-submit`, `tool-before`, `tool-after`, `tool-failure`,
+`subagent-start`, `subagent-stop`, `stop`, `compact-before`, `response-after`.
+
+The merge is idempotent and deep-equality-checked per hook group, so re-running it never duplicates an
+already-present entry.
+
+## Lessons view
+
+`claude.lessons-view.ts` appends a single `@.tlc/harness/lessons.md` import line to the project's `CLAUDE.md` when it
+is not already present. It is a pointer, not a copy — the content lives in one file.
+
+It is written under `intelligence.lessons.syncRulesFile: "always"` and **not** under the default `"auto"`, because
+this adapter declares `sessionStartContextReliable: true`: `SessionStart` delivers
+`hookSpecificOutput.additionalContext`, so lessons arrive without a durable file and the pointer would be a second
+copy of a working route. Set `always` to have it anyway — it survives a restart, which the injected context does not
+(see [/decisions/ad-050.md](/decisions/ad-050.md), and [/decisions/ad-011.md](/decisions/ad-011.md) item 4).
+
+Only `hookSpecificOutput.additionalContext` is emitted. Claude Code reads a top-level `additional_context` as well
+and does not deduplicate the two, so emitting both would inject the same text twice.
+
+## Doctor / status
+
+`tlc harness doctor` reports Claude wiring as `wired` when merging the current entries into the existing
+`~/.claude/settings.json` would produce no change, `detected-but-unwired` otherwise, and `not-installed`
+when `~/.claude` does not exist.
+
+## See also
+
+- [/providers/index.md](/providers/index.md)
+- [/providers/cursor.md](/providers/cursor.md)

package/docs/providers/cursor.md

@@ -0,0 +1,110 @@
+---
+type: Provider
+title: "Cursor provider"
+description: "The Cursor adapter — capability descriptor, event mapping, and wiring target for Cursor's hooks.json."
+tags: [provider, cursor]
+timestamp: "2026-07-29"
+---
+
+# Cursor provider
+
+Source: `src/providers/cursor/`.
+
+## Detection
+
+`cursor.detect.ts`: a raw hook payload is Cursor's when `hook_event_name` is camelCase (e.g.
+`beforeShellExecution`) and `workspace_roots` is an array.
+
+## Capability descriptor
+
+`cursor.capabilities.ts`:
+
+| Capability | Value |
+| --- | --- |
+| `enforcesHooks` | `true` |
+| `askSupportedOn` | `["shell.before", "mcp.before"]` — **not** `tool.before` (see [/decisions/ad-009.md](/decisions/ad-009.md), note) |
+| `sessionEnv` | `true` |
+| `nativeLoopCounter` | `true` |
+| `dedicatedShellEvent` | `true` |
+| `toolInputRewrite` | `true` |
+| `toolOutputRewrite` | `true` |
+| `contextAtToolBefore` | `false` |
+| `contextAtToolAfter` | `true` |
+| `contextAtStop` | `false` — the `stop` output schema carries `followup_message` and nothing else |
+| `sessionStartContextReliable` | `false` — Cursor accepts `additional_context` at `sessionStart`, logs it as merged, and drops it (see [Lessons view](#lessons-view)) |
+| `usageInPayload` | `true` |
+| `effortSignal` | `false` |
+| `thoughtEvent` | `true` |
+
+## Policy defaults
+
+`cursor.policy-defaults.ts` supplies the blocked-pattern list (`-fast(?:$|[^a-z0-9])`, `/fast(?:$|[^a-z0-9])`,
+`composer-2\.5-fast`) — see [/decisions/ad-011.md](/decisions/ad-011.md).
+
+**It supplies no model allowlist.** It used to, and an empty project list fell back to it, so a spawn could be
+refused by five slugs that appear nowhere in the project and had already gone stale. `subagents.allowedModels` is
+the operator's and has no other source; an empty one enforces nothing and `doctor` says so
+([/decisions/ad-053.md](/decisions/ad-053.md)). The blocked patterns stay because they are **added** to the
+project's rather than replacing them.
+
+## Event mapping
+
+`cursor.inbound.ts` maps Cursor's own camelCase hook names to the shared `HarnessEventKind`:
+
+| Cursor hook | `HarnessEventKind` |
+| --- | --- |
+| `sessionStart` | `session.start` |
+| `sessionEnd` | `session.end` |
+| `beforeSubmitPrompt` | `prompt.submit` |
+| `preToolUse` | `tool.before` |
+| `postToolUse` | `tool.after` |
+| `postToolUseFailure` | `tool.failure` |
+| `beforeShellExecution` | `shell.before` |
+| `afterShellExecution` | `shell.after` |
+| `beforeMCPExecution` | `mcp.before` |
+| `afterMCPExecution` | `mcp.after` |
+| `beforeReadFile` | `read.before` |
+| `afterFileEdit` | `edit.after` |
+| `subagentStart` | `subagent.start` |
+| `subagentStop` | `subagent.stop` |
+| `stop` | `stop` |
+| `preCompact` | `compact.before` |
+| `afterAgentResponse` | `response.after` |
+| `afterAgentThought` | `thought.after` |
+
+Cursor has a dedicated event per tool class (`beforeShellExecution`, `beforeMCPExecution`,
+`beforeReadFile`), unlike Claude's single `PreToolUse`/`PostToolUse` fan-out.
+
+## Wiring target
+
+`cursor.wiring.ts` writes (`strategy: "replace"`) the user-level `~/.cursor/hooks.json`, one entry per
+`(hookEvent, handler)` pair, dispatching through the launcher: `node <launcherPath> <handler>` on
+Unix/macOS, `cmd /c node <launcherPath> <handler>` on Windows. Handler names are the
+`src/entrypoints/<name>.ts` filenames (see [/decisions/ad-015.md](/decisions/ad-015.md)):
+`session-bootstrap`, `persist-handoff`, `obs-session-end`, `obs-passive`, `guard-subagent`,
+`pre-tool-use`, `guard-shell`, `audit-event`, `guard-mcp`, `guard-read`, `format`, `verify-gates`,
+`obs-stop`, `track-response`.
+
+## Lessons view
+
+`cursor.lessons-view.ts` renders `.tlc/harness/lessons.md` into `.cursor/rules/harness-lessons.mdc`
+(`alwaysApply: true`). This is not a second copy of a working route — it is **the** route on this host. Cursor
+accepts `additional_context` returned from `sessionStart`, logs it as merged, and drops it; its own staff called that
+"a bug on our side… a timing issue between when the hook runs and when the composer handle is created" (forum thread
+158452, 2026-04-20), and it was reported again against 3.14.7 on 2026-08-02. `env` on the same payload arrives,
+because that is a different code path — which is why `HARNESS_ACTIVE` works while the prose does not.
+
+The adapter therefore declares `sessionStartContextReliable: false`, and the default `syncRulesFile: "auto"` writes
+the view here for that reason rather than because an operator guessed. `never` declines it; `always` forces it (see
+[/decisions/ad-050.md](/decisions/ad-050.md), and [/decisions/ad-011.md](/decisions/ad-011.md) item 4 for the
+original reasoning).
+
+## Doctor / status
+
+`tlc harness doctor` reports Cursor wiring as `wired`, `detected-but-unwired`, or `not-installed` by
+diffing the live `~/.cursor/hooks.json` against the entries this adapter would write.
+
+## See also
+
+- [/providers/index.md](/providers/index.md)
+- [/providers/claude-code.md](/providers/claude-code.md)

package/docs/providers/index.md

@@ -0,0 +1,71 @@
+---
+type: Aggregate
+title: "Providers index"
+description: "Index of the provider adapters — Cursor and Claude Code — and the port they both implement."
+tags: [providers, index, architecture]
+timestamp: "2026-07-29"
+---
+
+# Providers
+
+Core steering logic never imports a provider adapter and never reads a provider name. Each provider is an
+anti-corruption-layer adapter implementing `ProviderPort`
+(`src/providers/provider.port.ts`):
+
+```ts
+type ProviderPort = {
+  readonly name: string;
+  detect(raw: unknown): boolean;
+  capabilities(): ProviderCapabilities;
+  policyDefaults(): ProviderPolicyDefaults;
+  toEvent(raw: Record<string, unknown>): HarnessEvent | null;
+  render(decision: Decision, event: HarnessEvent): Rendered;
+  wiring(runtime: RuntimePaths): ProviderWiring;
+};
+```
+
+- `detect` — does this raw hook payload belong to this provider?
+- `capabilities` — a declarative `ProviderCapabilities` descriptor (see
+  [/architecture.md](/architecture.md)); core degrades on this data, never on `name`.
+- `policyDefaults` — this provider's own model allowlist / blocked patterns / minimum effort (see
+  [/decisions/ad-011.md](/decisions/ad-011.md)).
+- `toEvent` — parses a raw hook payload into the shared `HarnessEvent` shape.
+- `render` — turns a core `Decision` back into this provider's wire format.
+- `wiring` — describes which hooks this provider needs registered, and where.
+
+## Registered providers
+
+Detection runs in registry order (`src/providers/provider.registry.ts`), first match wins, and multiple
+matches are reported as ambiguous rather than silently resolved:
+
+| Provider | Detected by | Docs |
+| --- | --- | --- |
+| Cursor | camelCase `hook_event_name` + `workspace_roots` array | [/providers/cursor.md](/providers/cursor.md) |
+| Claude Code | PascalCase `hook_event_name` + `cwd` or `transcript_path` | [/providers/claude-code.md](/providers/claude-code.md) |
+
+## Event kinds
+
+Both adapters translate into the same 18-member `HarnessEventKind` union (see
+[/decisions/ad-009.md](/decisions/ad-009.md) item 1): `session.start`, `session.end`, `prompt.submit`,
+`tool.before`, `tool.after`, `tool.failure`, `shell.before`, `shell.after`, `mcp.before`, `mcp.after`,
+`read.before`, `edit.after`, `subagent.start`, `subagent.stop`, `stop`, `compact.before`, `response.after`,
+`thought.after`. A provider that cannot produce a kind is gated by its capability descriptor, not by the
+kind's absence.
+
+## Caller identity vs. spawn target
+
+`HarnessEvent` splits two fields that an earlier design conflated (see
+[/decisions/ad-016.md](/decisions/ad-016.md) item 1):
+
+| Field | Meaning |
+| --- | --- |
+| `subagentType` | the identity of the agent **currently running** (the caller) |
+| `spawnSubagentType` | the type of subagent a Task/spawn call **targets** |
+| `model` | the current/parent model |
+| `spawnModel` | the model of the child being spawned |
+
+## Adding a provider
+
+A new provider is a new directory under `src/providers/<name>/` plus one line in
+`src/providers/provider.registry.ts` (see [/decisions/ad-004.md](/decisions/ad-004.md) and
+[/decisions/ad-009.md](/decisions/ad-009.md) item 7) — never a change to `core/`.

package/docs/troubleshooting.md

@@ -0,0 +1,138 @@
+---
+type: Runbook
+title: "Was that the harness?"
+description: "How to tell a harness decision from model behaviour, in the moment and after the fact: the one command that answers it, what each rule name means, and the four symptoms that are not the harness at all."
+tags: [troubleshooting, rules, observability]
+timestamp: "2026-08-12"
+---
+
+# Was that the harness?
+
+> "eu to meio perdido tentando entender o que é comportamento do harness toolkit, o que é loucura do modelo"
+
+Hooks are invisible by construction: the harness answers the editor, and the editor decides whether to show
+you. This page is how you find out anyway.
+
+## The one command
+
+```bash
+tlc harness why
+```
+
+The last ten decisions the tool made, newest first, each with the rule behind it:
+
+```
+Last 4 harness decision(s), newest first:
+
+19:23:05  shell          deny    rule=policy-surface-write
+          python3 -c "open('.tlc/harness/config.json','w')"
+19:23:05  shell          ask     rule=shell-catastrophic
+          dd if=/dev/zero of=/dev/sda
+19:23:05  tool.before    deny    rule=subagent-allowlist
+          Task
+19:23:05  session start  context rule=unattributed
+          4210 chars injected
+```
+
+**And when it was not the harness, it says so:**
+
+```
+No harness decision in this window.
+Whatever you just saw was the model, not a rail — the harness allowed everything it was asked about.
+```
+
+That sentence is the point of the command. `tlc harness why 30` widens the window; `--json` gives the same
+records as data.
+
+## The rule names
+
+Every refusal names one. The name is the pointer — the reasoning lives in the decision record it cites.
+
+| Rule | What refused, and why |
+| --- | --- |
+| `outside-project-destruction` | a destructive command aimed outside the repo and outside the temp directory |
+| `unprovable-destruction` | a destructive verb whose target is built at runtime, so the harness cannot see what it would delete |
+| `unprovable-execution` | a program fetched over the network and handed to a shell, so the harness cannot read what would run |
+| `secret-access` | a read that would copy credentials into the transcript, from a file **or** from the instance metadata service |
+| `history-rewrite` | `git push --force`. `--force-with-lease` is allowed |
+| `machine-control` | `shutdown`, `reboot`, `halt`, `poweroff` |
+| `policy-surface-write` | any route an agent has to harness policy or state |
+| `policy-baseline-divergence` | a policy file changed mid-session with no `tlc harness` command behind it |
+| `untrusted-command` | a shell command that appears verbatim in content this session fetched — put to you before it runs |
+| `edit-collision` | another live session touched this file recently |
+| `shell-catastrophic` | a shell command that can destroy data outside the workspace |
+| `shell-posture-paired` | the `paired` posture asks before a command that leaves the machine or can overwrite a path |
+| `shell-stall` | the same shell command repeated past the threshold |
+| `subagent-allowlist` | the model is not on `subagents.allowedModels` |
+| `subagent-parent-fast` | the parent chat is in Fast mode |
+| `subagent-blocked-pattern` | the model matched a blocked shape, `*-fast` by default |
+| `subagent-model-required` | the spawn named no model and `requireModel` is on |
+| `subagent-min-effort` | the spawn's effort is below `minEffort` |
+| `subagent-read-only` | a read-only subagent type reached for a writing tool |
+| `rewrite-unavailable` | the provider cannot rewrite tool input, so the harness asked instead |
+| `unattributed` | a record written before rules were required. It will not appear for new decisions |
+
+## Four things that are **not** the harness
+
+**A message with no `rule=`, no `BLOCKED:` and no `FLOOR:`.** Every harness decision carries one of the three.
+
+**A subagent model changing.** The harness does not change models. It refuses a spawn, with
+`rule=subagent-allowlist`, and the refusal goes to the model as `agent_message` and to you as `user_message`.
+If your editor renders neither, `tlc harness why` still shows it.
+
+**A gate failing here but passing in your terminal.** From the second attempt the follow-up says so itself, and
+names the variables the hook set. It is usually the project's gate command differing from the one your suite
+needs — which only you can change:
+
+```bash
+tlc harness gate test-command <your real test command>
+```
+
+**Everything, when the harness is off for this repo.** `tlc harness doctor` lists which rails are on.
+
+## After the fact
+
+| Command | Answers |
+| --- | --- |
+| `tlc harness why [n]` | the last n decisions, with rules — **start here** |
+| `tlc harness obs report` | this session: gate outcomes, refusals by rule, interruptions by rule, cost |
+| `tlc harness obs live` | the same signal as it happens |
+| `tlc harness doctor` | which rails are on, and which are on but enforcing nothing |
+| `tlc harness handoff` | what the last turn left open |
+| `tlc harness attest` | one hash-chained record per session, for a reviewer |
+
+## When a refusal is wrong
+
+Say so in your reply and let the operator decide. Working around a floor rule is not a fix — the six of them
+read no configuration precisely so that nothing in a session can clear them
+([/decisions/ad-016.md](/decisions/ad-016.md)).
+
+For a rail, the operator changes it from their own terminal, outside the agent session
+([/decisions/ad-022.md](/decisions/ad-022.md)):
+
+```bash
+tlc harness mode solo          # leave the paired posture
+tlc harness pause              # disable stop checks while exploring
+tlc harness policy accept --all  # after you edited config mid-session
+```
+
+## When you want it off entirely
+
+```bash
+tlc harness uninstall          # the plan, and nothing else
+tlc harness uninstall --yes    # apply it
+```
+
+It un-merges the hook groups out of `settings.json` and leaves every other key alone, so this is the
+supported alternative to editing that file by hand. `config.json` and `state/` survive unless you add
+`--purge`.
+
+**An agent cannot do this for you**, and the refusal is not a defect. The runtime home sits outside any
+project and `state/` is a policy surface, so a delegated uninstall meets `outside-project-destruction` or
+`policy-surface-write` ([/decisions/ad-066.md](/decisions/ad-066.md)). Run it from your own terminal.
+
+## See also
+
+- [/concepts.md](/concepts.md) — every rail from the operator's side
+- [/diagnose.md](/diagnose.md) — hooks not firing, stale runtime, cost showing null
+- [/decisions/index.md](/decisions/index.md) — why each rule exists

package/model-aliases.json

@@ -0,0 +1,12 @@
+{
+  "composer-2.5": "composer-2.5",
+  "cursor-grok-4.5-high": "grok-4.5",
+  "cursor-grok-4.5": "grok-4.5",
+  "glm-5.2-high": "glm-5.2",
+  "glm-5.2": "glm-5.2",
+  "kimi-k2.7-code": "kimi-k2.7-code",
+  "gpt-5.3-codex-high": "gpt-5.3-codex",
+  "gpt-5.3-codex": "gpt-5.3-codex",
+  "auto": "auto-cost",
+  "auto-cost": "auto-cost"
+}