@alessandroraffa/tangyr 0.21.5 → 1.0.0

package/mappings/README.md

@@ -44,3 +44,24 @@ Each entry in `models` requires:
 **Fail-closed validation**: a `custom_provider` declaration that omits `context_limit` or `output_limit` on any model entry, or that declares an empty `models` array, causes `loadMappings` to throw immediately with a descriptive error message beginning `custom-provider-limits-missing:`.
 
 **`wire_api` semantics**: `"responses"` enables Codex `[model_providers.<id>]` TOML emission and selects `@ai-sdk/openai` as the npm package for OpenCode. When `wire_api` is absent or non-`"responses"`, Codex records a `provider-wire-protocol` loss and OpenCode uses `@ai-sdk/openai-compatible`.
+
+## hook-events.yaml — the six-target hook contract
+
+`hook-events.yaml` is the declarative hook contract: for each of the six targets it declares a **delivery mode** and one entry per source event. It is the file the hook compilers quote when a hook does not reach a target intact.
+
+`source_events` is the set the canonical kit registers, plus `SessionStart`: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PreCompact`, `SubagentStart`, `SubagentStop`, `Stop`.
+
+| Target        | `delivery`                | What the target receives                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `claude-code` | `native-merge`            | Every source event under its own name, merged into the target's settings file.                                                                                                                                                                                                                                                                                                                   |
+| `copilot`     | `mapped`                  | Every source event has a camelCase equivalent (`sessionStart`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `preCompact`, `subagentStart`, `subagentStop`, `agentStop`). Copilot accepts Claude Code's nested `matcher`/`hooks` shape verbatim. Measured 2026-09-07 against Copilot CLI 1.0.83, whose `schemas/api.schema.json` (`HookType`) enumerates the events. |
+| `codex`       | `partial`                 | Five events map by name. `PostToolUseFailure` is a measured `drop` — Codex fires `PostToolUse` on a failed command instead — and `PreCompact`, `SubagentStart`, `SubagentStop` are `probe`: registered in the 2026-09-04 run but never exercised, so inconclusive rather than negative. `supported_platforms` records macOS/Linux only.                                                          |
+| `cursor`      | `native-versioned-object` | Every source event maps to a camelCase step in `hooks.json`; a step holds an **array** of commands, all of which run, so nothing is collapsed. Measured 2026-09-06 against cursor-agent 2026.09.02-c22c1a3.                                                                                                                                                                                      |
+| `opencode`    | `plugin-only`             | Nothing. OpenCode exposes hooks only as plugin code, so every event is a `drop` with a `hook-as-plugin` loss and a warning.                                                                                                                                                                                                                                                                      |
+| `cline`       | `plugin-only`             | Nothing. Hooks exist only as `@cline/sdk` `AgentPlugin` code installed with `cline plugin install`, which does not apply to the extension target; every event drops the same way.                                                                                                                                                                                                                |
+
+A per-event entry is either a bare target name (claude-code's shorthand) or an object with `status` (`mapped` \| `drop` \| `probe`), an optional `target_event`, and — for `drop` and `probe` — a `severity` and a written `reason`. The `probe` status is deliberately distinct from `drop`: it records an unsettled measurement together with the experiment that would settle it.
+
+**An unmapped event is reported, never silently dropped.** An event a kit registers that this file says nothing about is synthesized by the compilers as a fourth status, `unmapped` (see `HookEventRule` in `src/mappings/loader.ts`), and reported naming this file — so "we decided not to carry this" and "nobody has considered this event" stop producing the same output. Keeping the kit's registered events and this file in step is the purpose of that report.
+
+**Scope limit.** This file maps event _names_ only. Translating the tool names inside a hook's `matcher` to a target's own vocabulary is done in code — `CURSOR_TOOL_NAMES` and `COPILOT_TOOL_NAMES` in `src/compiler/hooks.ts` — because those are measured target literals (`Bash` → `Shell`, `Bash` → `bash`), not the capability classes `tool-names.yaml` deals in. A matcher left untranslated produces the worst failure mode in this area: a valid, accepted hook file whose hooks never run.

package/mappings/loss-severity.yaml

@@ -1,6 +1,23 @@
 version: 1
 status: active
-active_targets: [claude-code, copilot, codex]
+active_targets:
+  - claude-code
+  - copilot
+  - codex
+  - opencode
+  - cursor
+  - cline
+
+notes:
+  - Widened from three targets to six on 2026-09-07. The entry-type vocabulary below is
+    emitted for every target, not only the original three - `hook-as-plugin` is recorded
+    exclusively for opencode and cline (adapters/opencode.ts, adapters/cline.ts),
+    `persona-not-representable` exclusively for cline, and `permission-coarsening` for
+    opencode and cursor (compiler/agents.ts). A three-target list described a file that was
+    already governing six.
+  - Severity is resolved per entry type, not per target - `resolveLossSeverity`
+    (compiler/loss-report.ts) keys only on the entry type, with an explicit severity from
+    hook-events.yaml overriding it.
 
 entry_types:
   command-as-skill: info

package/mappings/permission-modes.yaml

@@ -6,6 +6,13 @@ notes:
   - No current agent file in projects/tangyr/agent-coding/agents/ declares `permissionMode`.
   - This file exists because the target-state design expects permission intent to become an explicit canonical field later.
   - Until that field exists in source artifacts, adapters must treat this file as reserved mapping policy rather than active input.
+  - active_targets stays at three because this file is reserved, not because coverage stops
+    at codex. No code path reads `canonical_permission_modes` at all (the loader exposes it;
+    nothing consumes it). Where `permissionMode` does appear on an agent, compiler/agents.ts
+    handles it directly for opencode (coarsened to an allow|ask|deny map) and cursor
+    (coarsened to a `readonly` boolean), recording `permission-coarsening` loss in both
+    cases - without consulting this file. Widening the list would imply an active
+    six-target policy that does not exist.
 
 canonical_permission_modes:
   read-only:

package/mappings/platform-paths.yaml

@@ -67,6 +67,18 @@ targets:
       instructions: ~/.codex/AGENTS.md
       agents: ~/.codex/agents
       rules: ~/.codex/rules
+      # Not a typo, and not the odd one out by accident. Codex reads USER-scope
+      # skills from ~/.agents/skills, not from ~/.codex/skills alongside its
+      # other config. That is the only USER location OpenAI documents
+      # (https://learn.chatgpt.com/docs/build-skills: repo `.agents/skills`,
+      # user `$HOME/.agents/skills`, admin `/etc/codex/skills`), and it was
+      # measured on 2026-09-07 against Codex CLI 0.142.2 with
+      # `codex debug prompt-input`: marker skills planted in ~/.agents/skills
+      # and behind a wholesale relative symlink at that path both came back in
+      # the rendered <skills_instructions> block. ~/.codex/skills is read too,
+      # but it is a real directory Codex populates itself (it preinstalls its
+      # own skills under .system/), so it is not a wholesale-symlink target.
+      # Pinned by tests/unit/adapters/codex-skills-location.test.ts.
       skills: ~/.agents/skills
       hooks_shared_file: ~/.codex/hooks.json
       hook_scripts: ~/.agents/hooks

package/mappings/rule-modes.yaml

@@ -5,6 +5,19 @@ active_targets: [claude-code, copilot, codex]
 notes:
   - Codex requires an explicit separation between behavioral guidance and execution-policy rules.
   - This file gives the classification vocabulary for that split.
+  - >-
+    active_targets stays at three, but the `guidance` / `exec-policy` vocabulary is applied
+    beyond them by compiler/rules.ts, which reads the source `mode` field directly rather
+    than this table (no code path reads `canonical_rule_modes`). Measured behaviour of the
+    other three - opencode folds every rule into AGENTS.md as guidance and records
+    `rule-path-scoping`; cline emits a per-rule .md file and downgrades `exec-policy` to
+    guidance with a `rule-mode-downgrade` loss; cursor emits .mdc files keyed on
+    `alwaysApply`/`globs`/`description` and does not consult `mode` at all, so an
+    `exec-policy` rule reaches Cursor as ordinary guidance with no loss recorded.
+  - >-
+    Adding those three as columns is a behaviour-and-test change, not a documentation one.
+    tests/unit/mappings/declarations.test.ts asserts this file's active_targets length is
+    exactly 3. The cursor gap named above is the item worth filing separately.
 
 canonical_rule_modes:
   guidance:

package/mappings/tool-names.yaml

@@ -13,6 +13,18 @@ mapping_modes:
 notes:
   - The canonical tool names below are observed in current agent frontmatter.
   - Copilot and Codex adapters should not assume that every canonical tool name has a stable one-to-one emitted literal.
+  - >-
+    active_targets stays at three deliberately. `canonical_tools` is read in exactly one
+    place - compiler/agents.ts (`mapToolsToCapabilities`, `deriveCodexSandbox`) - and only
+    for copilot capability names and codex sandbox derivation. The opencode, cursor and
+    cline agent compilers never consult it; they carry canonical tool names through
+    verbatim. Listing them here would claim a translation that does not happen.
+  - >-
+    This file translates a tool name to a capability class for agent frontmatter. It is not
+    the hook-matcher table. Rewriting a hook matcher to a target's literal tool spelling is
+    done by CURSOR_TOOL_NAMES and COPILOT_TOOL_NAMES in compiler/hooks.ts, which hold
+    measured target literals (`Bash` -> `Shell`, `Bash` -> `bash`) rather than capability
+    classes. See the "Scope limit" note under `hook-events.yaml` in mappings/README.md.
 
 canonical_tools:
   Read:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alessandroraffa/tangyr",
-  "version": "0.21.5",
+  "version": "1.0.0",
   "description": "CLI for the Tangyr discipline — install and manage operating kits for AI coding tools",
   "license": "MIT",
   "engines": {