@jjanczur/tyran 0.1.42 → 0.1.44
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +185 -0
- package/README.md +9 -2
- package/hooks/HOOK-CONTRACT-MEASURED.md +6 -1
- package/hooks/scripts/hook-io.mjs +66 -8
- package/hooks/scripts/policy-gate.mjs +141 -9
- package/package.json +1 -1
- package/scripts/board-html.mjs +504 -78
- package/scripts/doctor.mjs +48 -1
- package/scripts/scan-repo.mjs +17 -1
- package/scripts/schema.mjs +88 -1
- package/scripts/settings.mjs +215 -3
- package/skills/setup/SKILL.md +20 -0
- package/templates/config.yaml +28 -0
- package/templates/policies/autonomy.yaml +29 -9
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
{
|
|
12
12
|
"name": "tyran",
|
|
13
13
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
14
|
-
"version": "0.1.
|
|
14
|
+
"version": "0.1.44",
|
|
15
15
|
"source": "./",
|
|
16
16
|
"author": {
|
|
17
17
|
"name": "Jacek Janczura",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.44",
|
|
4
4
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Jacek Janczura",
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,190 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.44 — 2026-08-19
|
|
4
|
+
|
|
5
|
+
### The board follows your OS, and finally has a light mode
|
|
6
|
+
|
|
7
|
+
The board was dark only, by declaration in its own docstring. It now ships
|
|
8
|
+
two renderings of the same warm palette — light is the new default face,
|
|
9
|
+
dark keeps its near-black ground — and follows `prefers-color-scheme` until
|
|
10
|
+
you choose. A three-state switch (**System / Light / Dark**) sits in the
|
|
11
|
+
masthead; the choice is stored per browser and applied in the `<head>`,
|
|
12
|
+
before first paint, so a dark-choosing operator never sees a light flash.
|
|
13
|
+
Dark got its contrast fixed while it was open: `--muted`, which carries most
|
|
14
|
+
of the small mono text on the page, was measured at 5.4:1 and raised to
|
|
15
|
+
6.9:1, and every text role in both palettes now clears WCAG 4.5:1 — computed,
|
|
16
|
+
not eyeballed (the light `--brass` failed at 4.40 and was darkened until it
|
|
17
|
+
did not). Two tokens that had never existed (`--ink`, `--line`) stopped
|
|
18
|
+
silently resolving to nothing.
|
|
19
|
+
|
|
20
|
+
Readability borrowed from a board the operator reads faster than this one:
|
|
21
|
+
one emoji per tab and section label, green/amber/red freshness dots on agent
|
|
22
|
+
chips and stalled cards, a **waiting-time chip** on every open question that
|
|
23
|
+
turns clay after a day, and the recorded DEFAULT promoted from a dl row to a
|
|
24
|
+
bold sentence — "what happens if I never answer" is what the queue is
|
|
25
|
+
actually scanned by. The four headline tiles became buttons that go where
|
|
26
|
+
their number is explained.
|
|
27
|
+
|
|
28
|
+
### Answering is a chat now
|
|
29
|
+
|
|
30
|
+
The reply box under each question is a composer: the two canned moves —
|
|
31
|
+
**⭐ Use the recommendation**, **Take the default** — as chips above, the
|
|
32
|
+
field and a round send on one line, and **Enter sends** (Shift+Enter keeps
|
|
33
|
+
the newline). The modifier-required rule is retired by operator decision;
|
|
34
|
+
the empty-input guard survives it, so a stray Enter on a blank box still
|
|
35
|
+
sends nothing. A ticket standing in `waiting-operator` embeds the same
|
|
36
|
+
composer in its own detail panel — answering never requires finding the
|
|
37
|
+
question a second tab over.
|
|
38
|
+
|
|
39
|
+
The ticket detail also grew a **timeline** — spawned, reported, reviewed,
|
|
40
|
+
merged, oldest first, merge sha one click from the clipboard — assembled
|
|
41
|
+
entirely from lifecycle facts the payload already carried. Initiative
|
|
42
|
+
documents open from tickets as well as initiatives now, and they render as
|
|
43
|
+
documents: headings, lists and code blocks through a renderer that builds
|
|
44
|
+
structure with `createElement`/`textContent` only. The rule the old `<pre>`
|
|
45
|
+
enforced survives restated — nothing out of an agent-written document
|
|
46
|
+
becomes a link, an image, raw HTML or anything that runs.
|
|
47
|
+
|
|
48
|
+
### Every setting explains itself before you touch it
|
|
49
|
+
|
|
50
|
+
Each knob on the Settings tab folds open into **"What does this change?"**:
|
|
51
|
+
what the setting is, what changing it does, how it lands on Tyran — and,
|
|
52
|
+
where loosening is possible, what loosening costs, stated *before* the
|
|
53
|
+
confirm dialog restates it as a question. The prose lives in the settings
|
|
54
|
+
catalogue and travels through `settings.json`, so the terminal and the page
|
|
55
|
+
read the same sentences.
|
|
56
|
+
|
|
57
|
+
### The shipped policy template starts a step looser
|
|
58
|
+
|
|
59
|
+
Operator-decided: new installs got more refusal than they needed. Two dials
|
|
60
|
+
turn, in the template only — an installed policy is KERNEL and no update
|
|
61
|
+
touches it:
|
|
62
|
+
|
|
63
|
+
- `default: GATED` → `AUTO`. The gate is silent outside `.tyran/`,
|
|
64
|
+
`.claude/` and the hooks directory, so the default never protected your
|
|
65
|
+
source tree; it decided only the unnamed paths under those prefixes, where
|
|
66
|
+
an unknown file was denied to every subagent — the exact incident class
|
|
67
|
+
the legacy lease alias records.
|
|
68
|
+
- `.claude/agents/**`: `GATED` → `AUTO`. GATED denies a subagent
|
|
69
|
+
unconditionally, so the retro loop could only ever propose changes to the
|
|
70
|
+
files it exists to maintain. The trade is stated in the rule's own reason.
|
|
71
|
+
|
|
72
|
+
`boundaries:` still ships strict, the KERNEL floors are as unloosenable as
|
|
73
|
+
ever, and tightening either dial back is one word in
|
|
74
|
+
`.tyran/policies/autonomy.yaml`.
|
|
75
|
+
|
|
76
|
+
### And the board signs its work
|
|
77
|
+
|
|
78
|
+
The masthead links to [janczura.com](https://janczura.com/en/), LinkedIn and
|
|
79
|
+
the GitHub repo; the footer says what the docs site already said — *From
|
|
80
|
+
Berlin with ♥ by two buddies — Jacek and Piotr.*
|
|
81
|
+
|
|
82
|
+
## 0.1.43 — 2026-08-18
|
|
83
|
+
|
|
84
|
+
### One switch that opens the gate, and four things it cannot reach
|
|
85
|
+
|
|
86
|
+
Tyran refuses things a less-technical operator cannot reason about: a `.env`
|
|
87
|
+
read, a path outside the repository, a `GATED` write from a subagent, a push
|
|
88
|
+
past the deployment class. Every one of those refusals is defensible and every
|
|
89
|
+
one of them is a wall, and until now there was no way to turn any of it down.
|
|
90
|
+
The knobs that existed — `autonomy:` and `main_writable_paths:` — are narrow,
|
|
91
|
+
and neither is the switch people were asking for.
|
|
92
|
+
|
|
93
|
+
`boundaries:` in `.tyran/config.yaml` is that switch. Five flags and a preset:
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
boundaries:
|
|
97
|
+
preset: open
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`outside_repo` stops refusing paths outside the repo, for **every** actor
|
|
101
|
+
rather than the main thread only — which is the difference between this and
|
|
102
|
+
`main_writable_paths:`, and it is deliberate: a flag that says agents may work
|
|
103
|
+
outside the repository is useless if it excludes the agent that does the work.
|
|
104
|
+
`credentials` lets `.env` and friends be read on `Read`, `Grep` and in shell
|
|
105
|
+
text. `path_classes` makes your own `GATED`/`KERNEL` rules advisory for writes.
|
|
106
|
+
`push` skips the deployment-class analysis whole — refspec and alias refusals
|
|
107
|
+
included, because with no destination left to judge, refusing a command for
|
|
108
|
+
being unreadable to a check that is switched off is noise, not safety.
|
|
109
|
+
`prompts: skip` is the one people mean by "skip permissions".
|
|
110
|
+
|
|
111
|
+
**An explicit key beats the preset in both directions**, so `preset: open` with
|
|
112
|
+
`credentials: refuse` is a repo that wants room to work but not its own keys
|
|
113
|
+
read, and `preset: strict` with `outside_repo: allow` is one door.
|
|
114
|
+
|
|
115
|
+
### `permissionDecision: "allow"` became sayable, and stayed unreachable by accident
|
|
116
|
+
|
|
117
|
+
`prompts: skip` needed something the hook runtime deliberately did not have.
|
|
118
|
+
The old invariant was *"there is no way to emit `allow` from this runtime, and
|
|
119
|
+
a test pins that"* — sound, because `allow` does not mean "this gate is
|
|
120
|
+
satisfied", it means "approve this call and skip the prompt", and a gate
|
|
121
|
+
emitting it for everything it did not object to would be approving the session.
|
|
122
|
+
|
|
123
|
+
The invariant is now narrower and strictly harder to hold: **`PASS` never
|
|
124
|
+
becomes `allow`, and no failure mode does either.** Auto-approval requires a
|
|
125
|
+
handler to return `{decision: 'allow'}` on purpose. A throw, a timeout, an
|
|
126
|
+
overrun budget, a malformed input and an unrecognised verdict are all still
|
|
127
|
+
refusals, and the test that used to assert unreachability now asserts that
|
|
128
|
+
list — including the case that actually bites, a handler that overruns and
|
|
129
|
+
*then* returns an approval, whose verdict is discarded.
|
|
130
|
+
|
|
131
|
+
In the gate it is one line in one place. `handle()` rewrites a verdict only
|
|
132
|
+
when it was already `PASS`; a `deny`, an `ask` and a `PolicyFailure` are
|
|
133
|
+
returned untouched. A gate that could not complete its check must not
|
|
134
|
+
auto-approve, whatever the config says.
|
|
135
|
+
|
|
136
|
+
### The floor, which is the part that makes the rest safe to ship
|
|
137
|
+
|
|
138
|
+
`.tyran/config.yaml` is class `AUTO`, so an agent can widen these itself. That
|
|
139
|
+
is the trade `autonomy:` already made and it is recorded as one declared limit
|
|
140
|
+
rather than two, because it is one fact. What makes it acceptable is that the
|
|
141
|
+
floor is mechanical:
|
|
142
|
+
|
|
143
|
+
- **Secret scanning is untouched.** `gitleaks` runs from the secrets gate, a
|
|
144
|
+
different hook that never learns the word `boundaries`, and `deny` from any
|
|
145
|
+
hook beats `allow` from another. Pinned twice: a source assertion that the
|
|
146
|
+
file never reads the block, and a real scan — a repo configured as
|
|
147
|
+
permissively as the schema allows still refuses a commit carrying a private
|
|
148
|
+
key, with coverage verified.
|
|
149
|
+
- **`BOUNDARY_FLOOR_GLOBS`** is `SHELL_PROTECTED_GLOBS` plus `.tyran/STOP`, and
|
|
150
|
+
`path_classes: allow` consults the floor *before* the flag. The enforcement
|
|
151
|
+
hooks, the policy that classifies them, the hook registry, and the operator's
|
|
152
|
+
brake. A flag the loop can use to clear its own stop signal is not a flag.
|
|
153
|
+
This changes nothing about what a policy file may say — it closes a new door
|
|
154
|
+
rather than reopening an old one.
|
|
155
|
+
- **Every unreadable answer is strict.** A missing config, an unparseable one,
|
|
156
|
+
an oversized one, and any value the schema rejects all resolve to every
|
|
157
|
+
boundary ON. `credentials: yes` is not `allow`. This is `limitsOf`'s doctrine
|
|
158
|
+
with the sign flipped: an out-of-range limit falls back to a default, but a
|
|
159
|
+
security flag must never *relax* on input nobody can read.
|
|
160
|
+
|
|
161
|
+
### On the dashboard, with the confirmation it already knew how to ask for
|
|
162
|
+
|
|
163
|
+
The Settings tab has a "What agents may touch" section with all six controls.
|
|
164
|
+
Loosening any of them demands the same second, deliberate act that raising
|
|
165
|
+
`autonomy` does, and the token is the new value itself rather than a boolean,
|
|
166
|
+
so a caller cannot satisfy it by sending `confirm: true` alongside whatever
|
|
167
|
+
value it liked. Tightening is one click, always.
|
|
168
|
+
|
|
169
|
+
That took deleting something rather than adding it: `applySetting` had an
|
|
170
|
+
`if (id === 'autonomy')` special case, and every knob added beside it would
|
|
171
|
+
have had to remember to extend that line — which is exactly how a
|
|
172
|
+
boundary-loosening control ships with no confirmation at all. The catalogue
|
|
173
|
+
carries a `widening` descriptor now and the check reads it.
|
|
174
|
+
|
|
175
|
+
The block is written out in full by `scan-repo.mjs` and in
|
|
176
|
+
`templates/config.yaml`, at its strict values, for the same reason `limits:` is:
|
|
177
|
+
`yaml-patch` refuses to invent a key, so an absent block is a section of the
|
|
178
|
+
dashboard nobody can use. `doctor` reports `boundaries-absent` (info) for a
|
|
179
|
+
config written before this release, and `boundaries-relaxed` (warning) whenever
|
|
180
|
+
anything is loose — naming which flags. Relaxing a boundary removes refusals,
|
|
181
|
+
so nothing else in a session will ever mention it again.
|
|
182
|
+
|
|
183
|
+
Documented on both surfaces: `configuration` carries the reference and the
|
|
184
|
+
cost, `policy-gate` gains "Turning the gate down" and extends declared limit 6,
|
|
185
|
+
`hooks` restates the approval contract, `board` covers the new controls, and
|
|
186
|
+
`faq` answers it in the words somebody would actually search for.
|
|
187
|
+
|
|
3
188
|
## 0.1.42 — 2026-08-18
|
|
4
189
|
|
|
5
190
|
### The board stopped throwing you off the page you were reading
|
package/README.md
CHANGED
|
@@ -191,6 +191,13 @@ It checks Node, installs the plugin, installs the secrets scanner the write
|
|
|
191
191
|
gate needs, and prints the prompt to paste after you restart — which runs
|
|
192
192
|
setup and opens the dashboard in your browser.
|
|
193
193
|
|
|
194
|
+
Tyran refuses some things by default — reading a `.env`, writing outside the
|
|
195
|
+
repository, pushing past your autonomy class. If you would rather it did not,
|
|
196
|
+
`boundaries: {preset: open}` in `.tyran/config.yaml` relaxes all five at once,
|
|
197
|
+
and the dashboard's Settings tab has the switch. Secret scanning at commit and
|
|
198
|
+
push is not one of the five and cannot be turned off from there. See
|
|
199
|
+
[configuration](https://jjanczur.github.io/tyran/configuration/).
|
|
200
|
+
|
|
194
201
|
Or do it by hand, inside Claude Code:
|
|
195
202
|
|
|
196
203
|
```text
|
|
@@ -322,7 +329,7 @@ enforces the cap (3868 of 5000 characters). What each one assumes, when it
|
|
|
322
329
|
fires and who invokes it, is in
|
|
323
330
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
324
331
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
325
|
-
it:
|
|
332
|
+
it: 1658 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
326
333
|
|
|
327
334
|
## Documentation
|
|
328
335
|
|
|
@@ -334,7 +341,7 @@ Everything below also reads as a site, with search and rendered diagrams:
|
|
|
334
341
|
| [Getting started](https://jjanczur.github.io/tyran/getting-started/) | install, first run, the command line, updating |
|
|
335
342
|
| [Architecture](https://jjanczur.github.io/tyran/architecture/) | the four failures, the three layers, the hooks, the principles, the roadmap |
|
|
336
343
|
| [Skills and agents](https://jjanczur.github.io/tyran/skills/) · [the roster](https://jjanczur.github.io/tyran/agents/) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
|
|
337
|
-
| [Configuration](https://jjanczur.github.io/tyran/configuration/) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
|
|
344
|
+
| [Configuration](https://jjanczur.github.io/tyran/configuration/) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes, `boundaries:` |
|
|
338
345
|
| [Self-improvement](https://jjanczur.github.io/tyran/self-improvement/) | how Tyran learns your repo, and its guardrails |
|
|
339
346
|
| [Journal](https://jjanczur.github.io/tyran/journal/) · [projections](https://jjanczur.github.io/tyran/projections/) | the append-only event schema, and what is generated from it |
|
|
340
347
|
| [The board](https://jjanczur.github.io/tyran/board/) · [the spend ledger](https://jjanczur.github.io/tyran/cost/) | lanes, answering a question, and what a run cost |
|
|
@@ -112,7 +112,12 @@ did not object to would be quietly approving the whole session. `deny` from
|
|
|
112
112
|
any hook wins over `allow` from another, but that is no comfort when ours is
|
|
113
113
|
the only hook.
|
|
114
114
|
|
|
115
|
-
|
|
115
|
+
"No objection" is `{}`, and it always will be. Since 0.1.43 the runtime CAN
|
|
116
|
+
emit `allow`, from `allowPayload`, reached only by a handler returning
|
|
117
|
+
`{decision: 'allow'}` on purpose — the policy gate does so when a repo sets
|
|
118
|
+
`boundaries.prompts: skip`. No failure path reaches it: a throw, a timeout, an
|
|
119
|
+
overrun budget, a malformed input and an unrecognised verdict are all still
|
|
120
|
+
refusals. The sentence above is why that distinction is the whole design.
|
|
116
121
|
|
|
117
122
|
## 5. Matcher syntax — one predicate for every event
|
|
118
123
|
|
|
@@ -210,6 +210,43 @@ export function askPayload(event, reason) {
|
|
|
210
210
|
};
|
|
211
211
|
}
|
|
212
212
|
|
|
213
|
+
/**
|
|
214
|
+
* The allow payload for `event` — an explicit AUTO-APPROVAL.
|
|
215
|
+
*
|
|
216
|
+
* This is the one output in this file that makes a tool call happen without
|
|
217
|
+
* the platform asking anybody. It exists because an operator asked for exactly
|
|
218
|
+
* that and set `boundaries.prompts: skip` in their own config, and it is
|
|
219
|
+
* reachable ONLY from a handler that returns `{decision: 'allow'}` on purpose.
|
|
220
|
+
*
|
|
221
|
+
* Read the invariant carefully, because it is narrower than it looks and the
|
|
222
|
+
* narrowness is the whole safety argument: NO failure mode reaches this
|
|
223
|
+
* function. A throw, a timeout, a malformed input, an unrecognised return
|
|
224
|
+
* value and an overrun budget all still become refusals, exactly as before.
|
|
225
|
+
* What changed is that "allow" is now SAYABLE, not that anything says it by
|
|
226
|
+
* accident — which is the property `PASS` below is about.
|
|
227
|
+
*
|
|
228
|
+
* A refusal from any other hook still wins: `deny` beats `allow` across
|
|
229
|
+
* hooks (measured — HOOK-CONTRACT-MEASURED.md §4). So this cannot approve a
|
|
230
|
+
* command the secrets gate refuses, and that is not politeness between gates,
|
|
231
|
+
* it is the platform's own precedence.
|
|
232
|
+
*/
|
|
233
|
+
export function allowPayload(event, reason) {
|
|
234
|
+
const meta = EVENTS[event];
|
|
235
|
+
if (meta === undefined || meta.refusal === null) {
|
|
236
|
+
throw new GateOnProbeEventError(String(event));
|
|
237
|
+
}
|
|
238
|
+
if (meta.refusal !== 'permissionDecision') {
|
|
239
|
+
throw new Error(`"allow" is only expressible where the platform models permissionDecision, not on ${String(event)}`);
|
|
240
|
+
}
|
|
241
|
+
return {
|
|
242
|
+
hookSpecificOutput: {
|
|
243
|
+
hookEventName: event,
|
|
244
|
+
permissionDecision: 'allow',
|
|
245
|
+
permissionDecisionReason: reason,
|
|
246
|
+
},
|
|
247
|
+
};
|
|
248
|
+
}
|
|
249
|
+
|
|
213
250
|
/** The context-injection payload for `event`, or `{}` where it accepts none. */
|
|
214
251
|
export function contextPayload(event, additionalContext) {
|
|
215
252
|
const meta = EVENTS[event];
|
|
@@ -225,8 +262,16 @@ export function contextPayload(event, additionalContext) {
|
|
|
225
262
|
* gate is satisfied", it means "approve this tool call and skip the
|
|
226
263
|
* permission prompt". A gate whose only job is to look for secrets would
|
|
227
264
|
* then be silently auto-approving every command it happened not to object
|
|
228
|
-
* to.
|
|
229
|
-
*
|
|
265
|
+
* to.
|
|
266
|
+
*
|
|
267
|
+
* `allowPayload` above CAN emit it, and the distinction between the two is
|
|
268
|
+
* the safety property, so state it as a rule rather than as a fact about
|
|
269
|
+
* today's callers: **`PASS` never becomes `allow`, and no failure mode ever
|
|
270
|
+
* does.** Auto-approval requires a handler to return `{decision: 'allow'}`
|
|
271
|
+
* deliberately, which one gate does only when an operator wrote
|
|
272
|
+
* `boundaries.prompts: skip` in their own config. Tests pin both halves —
|
|
273
|
+
* that PASS emits `{}`, and that a throw, a timeout, a malformed input and an
|
|
274
|
+
* unrecognised return value all still refuse.
|
|
230
275
|
*/
|
|
231
276
|
export const PASS = Object.freeze({ decision: 'pass' });
|
|
232
277
|
|
|
@@ -486,11 +531,13 @@ function refusalText({ errorClass, message, fix }) {
|
|
|
486
531
|
* platform's timeout kills the process and DISCARDS its output, so a
|
|
487
532
|
* gate that is merely slow is a gate that approves.
|
|
488
533
|
*
|
|
489
|
-
* `handler(input)` returns `PASS`, `{ decision: 'deny', reason }` or —
|
|
490
|
-
*
|
|
491
|
-
*
|
|
492
|
-
*
|
|
493
|
-
*
|
|
534
|
+
* `handler(input)` returns `PASS`, `{ decision: 'deny', reason }` or — on
|
|
535
|
+
* events that model permissionDecision — `{ decision: 'ask', reason }`, which
|
|
536
|
+
* renders the user's own prompt for exactly this call, or
|
|
537
|
+
* `{ decision: 'allow', reason }`, which AUTO-APPROVES it and skips that
|
|
538
|
+
* prompt. Anything else is treated as a bug and refuses — an unrecognised
|
|
539
|
+
* return value must not be able to mean "allow", which is why allow has to be
|
|
540
|
+
* spelled out and cannot be arrived at.
|
|
494
541
|
*
|
|
495
542
|
* ## What the deadline does and does not promise
|
|
496
543
|
*
|
|
@@ -721,8 +768,19 @@ export async function runGate({ event, handler, deadlineMs, io = defaultIo() })
|
|
|
721
768
|
emit(payload);
|
|
722
769
|
return;
|
|
723
770
|
}
|
|
771
|
+
if (verdict !== null && typeof verdict === 'object' && verdict.decision === 'allow') {
|
|
772
|
+
// Deliberate auto-approval. Reached only from an explicit handler
|
|
773
|
+
// return; every ending that is not one — throw, timeout, overrun,
|
|
774
|
+
// malformed input, unrecognised verdict — is still a refusal.
|
|
775
|
+
const { payload } = clampPayload(
|
|
776
|
+
(reason) => allowPayload(outEvent, reason),
|
|
777
|
+
sanitizeForOutput(String(verdict.reason ?? 'allowed without a stated reason')),
|
|
778
|
+
);
|
|
779
|
+
emit(payload);
|
|
780
|
+
return;
|
|
781
|
+
}
|
|
724
782
|
throw new Error(
|
|
725
|
-
`handler returned ${JSON.stringify(verdict)}; expected PASS or { decision: 'deny' | 'ask', reason }`,
|
|
783
|
+
`handler returned ${JSON.stringify(verdict)}; expected PASS or { decision: 'deny' | 'ask' | 'allow', reason }`,
|
|
726
784
|
);
|
|
727
785
|
} catch (err) {
|
|
728
786
|
refuse(outEvent, describeError(err));
|
|
@@ -84,6 +84,7 @@ import {
|
|
|
84
84
|
} from './secrets-gate.mjs';
|
|
85
85
|
import {
|
|
86
86
|
MANDATORY_KERNEL_PATHS,
|
|
87
|
+
boundariesOf,
|
|
87
88
|
classifyPath,
|
|
88
89
|
globMatches,
|
|
89
90
|
normalizePath,
|
|
@@ -554,6 +555,50 @@ export async function loadDeployClass(root) {
|
|
|
554
555
|
return value;
|
|
555
556
|
}
|
|
556
557
|
|
|
558
|
+
/**
|
|
559
|
+
* How far this repo has turned the gate down (`boundaries:` in config.yaml).
|
|
560
|
+
*
|
|
561
|
+
* Fail-closed at every step, which for THIS loader means something different
|
|
562
|
+
* from the others in this file: a missing config, an unreadable one, a
|
|
563
|
+
* malformed one and a typo in a value all resolve to STRICT, because every
|
|
564
|
+
* failure here would otherwise remove a refusal. `loadDeployClass` refuses
|
|
565
|
+
* outright when it cannot read the class; this one cannot, because it runs on
|
|
566
|
+
* every tool call including the ones in a repo that never adopted Tyran — so
|
|
567
|
+
* its safe answer is "every boundary on", not an error.
|
|
568
|
+
*
|
|
569
|
+
* The resolution rule itself is NOT spelled here. `boundariesOf` in
|
|
570
|
+
* schema.mjs is the one implementation, shared with doctor and the Settings
|
|
571
|
+
* tab, because three spellings of one rule is the defect ADR-21 names and this
|
|
572
|
+
* rule decides whether a refusal happens at all.
|
|
573
|
+
*/
|
|
574
|
+
export async function loadBoundaries(root) {
|
|
575
|
+
// NOT memoized, deliberately. A process-lifetime cache keyed on the root
|
|
576
|
+
// would be correct in production — one process per tool call — and it was
|
|
577
|
+
// tried; what it actually bought was sub-millisecond, and what it cost was
|
|
578
|
+
// module state that survives between calls in every caller that is not the
|
|
579
|
+
// platform. The first thing it broke was a test reusing one root for two
|
|
580
|
+
// configs, which is precisely the shape of "the gate answered from a config
|
|
581
|
+
// that is no longer on disk". A second small read is the cheaper answer.
|
|
582
|
+
let text = null;
|
|
583
|
+
for (const candidate of [root, mainWorktreeOf(root)].filter((r) => r !== null)) {
|
|
584
|
+
try {
|
|
585
|
+
text = await readBounded(join(candidate, CONFIG_PATH), 'the Tyran config');
|
|
586
|
+
} catch {
|
|
587
|
+
// An unreadable or oversized config is a refusal for the callers that
|
|
588
|
+
// need a VALUE out of it. Here it is simply "no relaxations", which is
|
|
589
|
+
// the strictest answer available and never the reason a call proceeds.
|
|
590
|
+
return boundariesOf(null);
|
|
591
|
+
}
|
|
592
|
+
if (text !== null) break;
|
|
593
|
+
}
|
|
594
|
+
if (text === null) return boundariesOf(null);
|
|
595
|
+
try {
|
|
596
|
+
return boundariesOf(parse(text));
|
|
597
|
+
} catch {
|
|
598
|
+
return boundariesOf(null);
|
|
599
|
+
}
|
|
600
|
+
}
|
|
601
|
+
|
|
557
602
|
/**
|
|
558
603
|
* A leading `~` expanded to the home directory; everything else untouched so
|
|
559
604
|
* the `*`/`**` in a glob survive (`resolve` would collapse a trailing `**`).
|
|
@@ -1067,7 +1112,9 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
|
|
|
1067
1112
|
// modes must keep the hard deny — see verdictForClass's matrix.
|
|
1068
1113
|
const askable = actor === 'main' && field(input, 'permission_mode') === 'acceptEdits';
|
|
1069
1114
|
|
|
1070
|
-
|
|
1115
|
+
const boundaries = await loadBoundaries(root);
|
|
1116
|
+
|
|
1117
|
+
if (toolName === 'Bash') return await decideBash({ input, toolInput, root, runner, budget, boundaries });
|
|
1071
1118
|
|
|
1072
1119
|
const targets = pathTargets(toolInput);
|
|
1073
1120
|
const isWriteTool = typeof toolName === 'string' && WRITE_TOOLS.includes(toolName);
|
|
@@ -1101,6 +1148,7 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
|
|
|
1101
1148
|
// exact inversion of this file's own argument that two spellings of one
|
|
1102
1149
|
// location must not resolve to two classes. The cost of skipping it is
|
|
1103
1150
|
// higher here than on the write path, not lower.
|
|
1151
|
+
if (boundaries.credentials === 'allow') continue;
|
|
1104
1152
|
const resolved = canonicalDeepest(target);
|
|
1105
1153
|
const hits = [...new Set([...secretReadRules(target), ...secretReadRules(resolved)])];
|
|
1106
1154
|
if (hits.length === 0) continue;
|
|
@@ -1159,6 +1207,12 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
|
|
|
1159
1207
|
// exempts those built-in locations; `main_writable_paths` in config.yaml adds
|
|
1160
1208
|
// operator-chosen ones. Both are MAIN-thread only: a subagent still falls
|
|
1161
1209
|
// through to KERNEL.
|
|
1210
|
+
// `outside_repo: allow` is the ONE relaxation that is not actor-split.
|
|
1211
|
+
// The narrow exemptions below stay main-thread-only because they are
|
|
1212
|
+
// guesses about the harness; this one is an operator saying, in writing,
|
|
1213
|
+
// that agents may work outside this repository — and a subagent is the
|
|
1214
|
+
// actor that does the work.
|
|
1215
|
+
if (normalized === null && boundaries.outside_repo === 'allow') continue;
|
|
1162
1216
|
if (normalized === null && actor === 'main') {
|
|
1163
1217
|
if (harnessWritable(target, env)) continue;
|
|
1164
1218
|
if (mainWritable === undefined) mainWritable = await loadMainWritablePaths(root);
|
|
@@ -1180,7 +1234,14 @@ export async function decide({ input, runner = runChild, startedAt = Date.now(),
|
|
|
1180
1234
|
if (normalized !== null && decidingRule(policy, normalized) === null && !isGoverned(normalized)) {
|
|
1181
1235
|
continue;
|
|
1182
1236
|
}
|
|
1183
|
-
|
|
1237
|
+
// The floor is consulted BEFORE the flag, so no ordering of settings can
|
|
1238
|
+
// reach the files that enforce every other boundary.
|
|
1239
|
+
const relaxClasses =
|
|
1240
|
+
boundaries.path_classes === 'allow' &&
|
|
1241
|
+
normalized !== null &&
|
|
1242
|
+
boundaryFloorGlobFor(normalized) === null &&
|
|
1243
|
+
protectedGlobFor(normalized) === null;
|
|
1244
|
+
const verdict = relaxClasses ? 'pass' : verdictForClass(cls, unsupervised, askable);
|
|
1184
1245
|
|
|
1185
1246
|
// ADR-21, applied as a check rather than as a refactor: the rule this
|
|
1186
1247
|
// refusal names and the class the resolver returned must agree. They are
|
|
@@ -1384,6 +1445,38 @@ export const SHELL_PROTECTED_GLOBS = Object.freeze([
|
|
|
1384
1445
|
'.claude/settings.local.json',
|
|
1385
1446
|
]);
|
|
1386
1447
|
|
|
1448
|
+
/**
|
|
1449
|
+
* Paths no `boundaries:` setting can reach, checked before `path_classes` is
|
|
1450
|
+
* consulted.
|
|
1451
|
+
*
|
|
1452
|
+
* `SHELL_PROTECTED_GLOBS` is already "the files that switch every gate off":
|
|
1453
|
+
* the enforcement hooks, the policy that classifies them, and the settings
|
|
1454
|
+
* file that registers them. `.tyran/STOP` joins them here for a reason of the
|
|
1455
|
+
* same kind rather than the same shape — it is the operator's brake, and a
|
|
1456
|
+
* flag the loop can use to clear its own stop signal is not a flag, it is the
|
|
1457
|
+
* end of the boundary.
|
|
1458
|
+
*
|
|
1459
|
+
* Note what this does NOT do: it does not change what a policy file may say.
|
|
1460
|
+
* A user can still classify `.claude/settings.json` however they like; what
|
|
1461
|
+
* they cannot do is reach it by turning `path_classes` down, which is a new
|
|
1462
|
+
* door and is therefore closed on the way in.
|
|
1463
|
+
*
|
|
1464
|
+
* It lives HERE, below `SHELL_PROTECTED_GLOBS` rather than beside the loader
|
|
1465
|
+
* that motivates it, because a `const` that reads another `const` declared
|
|
1466
|
+
* later in the file throws on import — which is the whole gate failing to load
|
|
1467
|
+
* rather than one check misbehaving.
|
|
1468
|
+
*/
|
|
1469
|
+
export const BOUNDARY_FLOOR_GLOBS = Object.freeze([...SHELL_PROTECTED_GLOBS, '.tyran/STOP']);
|
|
1470
|
+
|
|
1471
|
+
/** The floor glob covering this path, or null. */
|
|
1472
|
+
export function boundaryFloorGlobFor(normalized) {
|
|
1473
|
+
if (normalized === null || normalized === undefined) return null;
|
|
1474
|
+
for (const glob of BOUNDARY_FLOOR_GLOBS) {
|
|
1475
|
+
if (globMatches(glob, normalized)) return glob;
|
|
1476
|
+
}
|
|
1477
|
+
return null;
|
|
1478
|
+
}
|
|
1479
|
+
|
|
1387
1480
|
/** The shell-protected glob covering this path, or null. */
|
|
1388
1481
|
export function shellProtectedGlobFor(normalized) {
|
|
1389
1482
|
if (normalized === null || normalized === undefined) return null;
|
|
@@ -1756,7 +1849,7 @@ export function shellPathFindings(command, startDir, root) {
|
|
|
1756
1849
|
}
|
|
1757
1850
|
|
|
1758
1851
|
/** The refusal for a protected path named in a shell command. */
|
|
1759
|
-
function refuseShellPaths(findings, command = '') {
|
|
1852
|
+
function refuseShellPaths(findings, command = '', allowCredentials = false) {
|
|
1760
1853
|
const credentials = findings.filter((f) => f.kind === 'credential');
|
|
1761
1854
|
const kernel = findings.filter((f) => f.kind === 'kernel');
|
|
1762
1855
|
// The credential the finding list never saw, because it sat where a message
|
|
@@ -1765,7 +1858,7 @@ function refuseShellPaths(findings, command = '') {
|
|
|
1765
1858
|
// out loud, because otherwise this refusal would offer the "rewrite it as a
|
|
1766
1859
|
// read-only command" way forward for a line whose problem is the secret in it.
|
|
1767
1860
|
// A refusal that states the wrong reason is worse than one that states none.
|
|
1768
|
-
const hidden = credentials.length === 0 ? rawCredentialWords(command) : [];
|
|
1861
|
+
const hidden = credentials.length === 0 && allowCredentials !== true ? rawCredentialWords(command) : [];
|
|
1769
1862
|
// True when the PATHS were all in the readable class, so the command itself
|
|
1770
1863
|
// is the only reason this is a refusal. Worth saying: the reader is one
|
|
1771
1864
|
// rewrite away from an allowed call, and a refusal with no reachable way
|
|
@@ -1831,7 +1924,7 @@ function refuseShellPaths(findings, command = '') {
|
|
|
1831
1924
|
return { decision: 'deny', reason: lines.join('\n') };
|
|
1832
1925
|
}
|
|
1833
1926
|
|
|
1834
|
-
async function decideBash({ input, toolInput, root, runner, budget }) {
|
|
1927
|
+
async function decideBash({ input, toolInput, root, runner, budget, boundaries }) {
|
|
1835
1928
|
const command = field(toolInput, 'command');
|
|
1836
1929
|
if (typeof command !== 'string') {
|
|
1837
1930
|
return {
|
|
@@ -1851,11 +1944,28 @@ async function decideBash({ input, toolInput, root, runner, budget }) {
|
|
|
1851
1944
|
// "the model was refused a Read and reached for Bash in the next call", and a
|
|
1852
1945
|
// check that only runs once a policy loads is a check an unconfigured repo
|
|
1853
1946
|
// does not have.
|
|
1854
|
-
|
|
1947
|
+
// `credentials: allow` drops the CREDENTIAL findings and nothing else. A
|
|
1948
|
+
// kernel finding is a path that protects the gate, and no setting reaches
|
|
1949
|
+
// those — which is why this filters the list rather than skipping the call.
|
|
1950
|
+
const findings = shellPathFindings(command, startDir, root).filter(
|
|
1951
|
+
(f) => !(f.kind === 'credential' && boundaries.credentials === 'allow'),
|
|
1952
|
+
);
|
|
1855
1953
|
// The exemption SKIPS this refusal; it does not return PASS. A `git log` that
|
|
1856
1954
|
// names a protected path still travels the deployment class and every other
|
|
1857
1955
|
// check below, exactly as `git log` on any other path does.
|
|
1858
|
-
if (findings.length > 0 && !shellReadExempt(findings, command))
|
|
1956
|
+
if (findings.length > 0 && !shellReadExempt(findings, command)) {
|
|
1957
|
+
return refuseShellPaths(findings, command, boundaries.credentials === 'allow');
|
|
1958
|
+
}
|
|
1959
|
+
|
|
1960
|
+
// `push: allow` skips the whole push analysis, not just the verdict at the
|
|
1961
|
+
// end of it. The refusals in between — an alias, a refspec the shell would
|
|
1962
|
+
// rewrite, a remote whose default branch cannot be read — all exist to stop
|
|
1963
|
+
// the gate GUESSING a destination it is about to judge. With nothing to
|
|
1964
|
+
// judge there is nothing to guess, and keeping them would refuse commands
|
|
1965
|
+
// for being unreadable to a check that is switched off.
|
|
1966
|
+
//
|
|
1967
|
+
// The path rules above still ran. This is the deployment class only.
|
|
1968
|
+
if (boundaries.push === 'allow') return PASS;
|
|
1859
1969
|
|
|
1860
1970
|
const plan = planCommand(command, startDir);
|
|
1861
1971
|
const pushes = plan.targets.filter((t) => t.scanPush === true && Array.isArray(t.pushArgv));
|
|
@@ -2039,10 +2149,32 @@ const DEPLOY_REMEDY = Object.freeze(Object.assign(Object.create(null), {
|
|
|
2039
2149
|
'What to do instead: push to a branch of your own and open a pull request from it.',
|
|
2040
2150
|
}));
|
|
2041
2151
|
|
|
2042
|
-
/**
|
|
2152
|
+
/**
|
|
2153
|
+
* Turn a PolicyFailure into the refusal it always has to be — and, when the
|
|
2154
|
+
* operator asked for it, turn "no objection" into an auto-approval.
|
|
2155
|
+
*
|
|
2156
|
+
* ONE place, deliberately, rather than a branch at every `return PASS`. The
|
|
2157
|
+
* property that has to hold is "a deny or an ask is never rewritten", and here
|
|
2158
|
+
* that is a single readable line instead of a claim about a dozen return
|
|
2159
|
+
* sites. The catch below is unchanged: a PolicyFailure is still a refusal, and
|
|
2160
|
+
* `boundaries` is not consulted on that path at all — a gate that could not
|
|
2161
|
+
* complete its check must not auto-approve, whatever the config says.
|
|
2162
|
+
*/
|
|
2043
2163
|
export async function handle({ input, runner, startedAt, env }) {
|
|
2044
2164
|
try {
|
|
2045
|
-
|
|
2165
|
+
const verdict = await decide({ input, runner, startedAt, env });
|
|
2166
|
+
const isPass = verdict === PASS || (verdict !== null && typeof verdict === 'object' && verdict.decision === 'pass');
|
|
2167
|
+
if (!isPass) return verdict;
|
|
2168
|
+
const boundaries = await loadBoundaries(repoRootOf(input, env ?? process.env));
|
|
2169
|
+
if (boundaries.prompts !== 'skip') return verdict;
|
|
2170
|
+
return {
|
|
2171
|
+
decision: 'allow',
|
|
2172
|
+
reason:
|
|
2173
|
+
'tyran policy-gate: approved without asking. This repository sets `boundaries.prompts: skip` ' +
|
|
2174
|
+
'in .tyran/config.yaml, so a tool call no gate objects to is auto-approved.\n' +
|
|
2175
|
+
'What this does NOT reach: a refusal from any other gate still wins, so secret scanning at ' +
|
|
2176
|
+
'commit and push is unaffected, and so are the paths that protect the gates themselves.',
|
|
2177
|
+
};
|
|
2046
2178
|
} catch (err) {
|
|
2047
2179
|
if (err instanceof PolicyFailure) {
|
|
2048
2180
|
return {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jjanczur/tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.44",
|
|
4
4
|
"description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|