@jjanczur/tyran 0.1.42 → 0.1.43

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.
@@ -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.42",
14
+ "version": "0.1.43",
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.42",
3
+ "version": "0.1.43",
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,111 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.43 — 2026-08-18
4
+
5
+ ### One switch that opens the gate, and four things it cannot reach
6
+
7
+ Tyran refuses things a less-technical operator cannot reason about: a `.env`
8
+ read, a path outside the repository, a `GATED` write from a subagent, a push
9
+ past the deployment class. Every one of those refusals is defensible and every
10
+ one of them is a wall, and until now there was no way to turn any of it down.
11
+ The knobs that existed — `autonomy:` and `main_writable_paths:` — are narrow,
12
+ and neither is the switch people were asking for.
13
+
14
+ `boundaries:` in `.tyran/config.yaml` is that switch. Five flags and a preset:
15
+
16
+ ```yaml
17
+ boundaries:
18
+ preset: open
19
+ ```
20
+
21
+ `outside_repo` stops refusing paths outside the repo, for **every** actor
22
+ rather than the main thread only — which is the difference between this and
23
+ `main_writable_paths:`, and it is deliberate: a flag that says agents may work
24
+ outside the repository is useless if it excludes the agent that does the work.
25
+ `credentials` lets `.env` and friends be read on `Read`, `Grep` and in shell
26
+ text. `path_classes` makes your own `GATED`/`KERNEL` rules advisory for writes.
27
+ `push` skips the deployment-class analysis whole — refspec and alias refusals
28
+ included, because with no destination left to judge, refusing a command for
29
+ being unreadable to a check that is switched off is noise, not safety.
30
+ `prompts: skip` is the one people mean by "skip permissions".
31
+
32
+ **An explicit key beats the preset in both directions**, so `preset: open` with
33
+ `credentials: refuse` is a repo that wants room to work but not its own keys
34
+ read, and `preset: strict` with `outside_repo: allow` is one door.
35
+
36
+ ### `permissionDecision: "allow"` became sayable, and stayed unreachable by accident
37
+
38
+ `prompts: skip` needed something the hook runtime deliberately did not have.
39
+ The old invariant was *"there is no way to emit `allow` from this runtime, and
40
+ a test pins that"* — sound, because `allow` does not mean "this gate is
41
+ satisfied", it means "approve this call and skip the prompt", and a gate
42
+ emitting it for everything it did not object to would be approving the session.
43
+
44
+ The invariant is now narrower and strictly harder to hold: **`PASS` never
45
+ becomes `allow`, and no failure mode does either.** Auto-approval requires a
46
+ handler to return `{decision: 'allow'}` on purpose. A throw, a timeout, an
47
+ overrun budget, a malformed input and an unrecognised verdict are all still
48
+ refusals, and the test that used to assert unreachability now asserts that
49
+ list — including the case that actually bites, a handler that overruns and
50
+ *then* returns an approval, whose verdict is discarded.
51
+
52
+ In the gate it is one line in one place. `handle()` rewrites a verdict only
53
+ when it was already `PASS`; a `deny`, an `ask` and a `PolicyFailure` are
54
+ returned untouched. A gate that could not complete its check must not
55
+ auto-approve, whatever the config says.
56
+
57
+ ### The floor, which is the part that makes the rest safe to ship
58
+
59
+ `.tyran/config.yaml` is class `AUTO`, so an agent can widen these itself. That
60
+ is the trade `autonomy:` already made and it is recorded as one declared limit
61
+ rather than two, because it is one fact. What makes it acceptable is that the
62
+ floor is mechanical:
63
+
64
+ - **Secret scanning is untouched.** `gitleaks` runs from the secrets gate, a
65
+ different hook that never learns the word `boundaries`, and `deny` from any
66
+ hook beats `allow` from another. Pinned twice: a source assertion that the
67
+ file never reads the block, and a real scan — a repo configured as
68
+ permissively as the schema allows still refuses a commit carrying a private
69
+ key, with coverage verified.
70
+ - **`BOUNDARY_FLOOR_GLOBS`** is `SHELL_PROTECTED_GLOBS` plus `.tyran/STOP`, and
71
+ `path_classes: allow` consults the floor *before* the flag. The enforcement
72
+ hooks, the policy that classifies them, the hook registry, and the operator's
73
+ brake. A flag the loop can use to clear its own stop signal is not a flag.
74
+ This changes nothing about what a policy file may say — it closes a new door
75
+ rather than reopening an old one.
76
+ - **Every unreadable answer is strict.** A missing config, an unparseable one,
77
+ an oversized one, and any value the schema rejects all resolve to every
78
+ boundary ON. `credentials: yes` is not `allow`. This is `limitsOf`'s doctrine
79
+ with the sign flipped: an out-of-range limit falls back to a default, but a
80
+ security flag must never *relax* on input nobody can read.
81
+
82
+ ### On the dashboard, with the confirmation it already knew how to ask for
83
+
84
+ The Settings tab has a "What agents may touch" section with all six controls.
85
+ Loosening any of them demands the same second, deliberate act that raising
86
+ `autonomy` does, and the token is the new value itself rather than a boolean,
87
+ so a caller cannot satisfy it by sending `confirm: true` alongside whatever
88
+ value it liked. Tightening is one click, always.
89
+
90
+ That took deleting something rather than adding it: `applySetting` had an
91
+ `if (id === 'autonomy')` special case, and every knob added beside it would
92
+ have had to remember to extend that line — which is exactly how a
93
+ boundary-loosening control ships with no confirmation at all. The catalogue
94
+ carries a `widening` descriptor now and the check reads it.
95
+
96
+ The block is written out in full by `scan-repo.mjs` and in
97
+ `templates/config.yaml`, at its strict values, for the same reason `limits:` is:
98
+ `yaml-patch` refuses to invent a key, so an absent block is a section of the
99
+ dashboard nobody can use. `doctor` reports `boundaries-absent` (info) for a
100
+ config written before this release, and `boundaries-relaxed` (warning) whenever
101
+ anything is loose — naming which flags. Relaxing a boundary removes refusals,
102
+ so nothing else in a session will ever mention it again.
103
+
104
+ Documented on both surfaces: `configuration` carries the reference and the
105
+ cost, `policy-gate` gains "Turning the gate down" and extends declared limit 6,
106
+ `hooks` restates the approval contract, `board` covers the new controls, and
107
+ `faq` answers it in the words somebody would actually search for.
108
+
3
109
  ## 0.1.42 — 2026-08-18
4
110
 
5
111
  ### 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: 1620 unit tests, run with `node --test "tests/**/*.test.mjs"`.
332
+ it: 1646 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
- This runtime has no way to emit it. "No objection" is `{}`.
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. There is no way to emit `allow` from this runtime, and a test pins
229
- * that.
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
- * on events that model permissionDecision — `{ decision: 'ask', reason }`,
491
- * which renders the user's own prompt for exactly this call. Anything else
492
- * is treated as a bug and refuses — an unrecognised return value must not
493
- * be able to mean "allow".
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
- if (toolName === 'Bash') return await decideBash({ input, toolInput, root, runner, budget });
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
- const verdict = verdictForClass(cls, unsupervised, askable);
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
- const findings = shellPathFindings(command, startDir, root);
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)) return refuseShellPaths(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
- /** Turn a PolicyFailure into the refusal it always has to be. */
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
- return await decide({ input, runner, startedAt, env });
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.42",
3
+ "version": "0.1.43",
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": {
@@ -61,7 +61,15 @@ import {
61
61
  PROGRESS_FILE,
62
62
  STATE_FILE,
63
63
  } from './project.mjs';
64
- import { classifyPath, normalizePath, validateFile, knowledgeWarnings, MANDATORY_KERNEL_PATHS } from './schema.mjs';
64
+ import {
65
+ boundariesOf,
66
+ classifyPath,
67
+ normalizePath,
68
+ relaxedBoundaries,
69
+ validateFile,
70
+ knowledgeWarnings,
71
+ MANDATORY_KERNEL_PATHS,
72
+ } from './schema.mjs';
65
73
  import { auditEntries, loadEntries as loadKnowledgeEntries } from './knowledge.mjs';
66
74
  import { readPlatformUsage } from './usage-source.mjs';
67
75
  import { gitRunner } from './scan-repo.mjs';
@@ -204,6 +212,11 @@ export const SEVERITY_BY_CODE = Object.freeze(
204
212
  'config-missing': 'info',
205
213
  'config-invalid': 'error',
206
214
  'config-unreadable': 'error',
215
+ // Not an error: an operator chose this. `warning` because it is the one
216
+ // setting whose whole effect is that refusals stop being printed, so
217
+ // nothing else will ever tell you it is on.
218
+ 'boundaries-relaxed': 'warning',
219
+ 'boundaries-absent': 'info',
207
220
  'knowledge-invalid': 'error',
208
221
  'knowledge-duplicate-id': 'error',
209
222
  'knowledge-unreadable': 'error',
@@ -1915,6 +1928,40 @@ export function runStateChecks({
1915
1928
  checked.push('config.yaml: absent');
1916
1929
  }
1917
1930
 
1931
+ // How open this repo is, STATED rather than left to be discovered. A relaxed
1932
+ // boundary is not a defect — somebody chose it — but it is the one setting
1933
+ // whose effect is that refusals stop appearing, so nothing else in a session
1934
+ // will ever mention it. An operator who inherits a repo, or comes back to one
1935
+ // after a month, finds out here or not at all.
1936
+ if (configDoc !== null) {
1937
+ const relaxed = relaxedBoundaries(boundariesOf(configDoc));
1938
+ if (relaxed.length > 0) {
1939
+ findings.push(
1940
+ finding(
1941
+ 'boundaries-relaxed',
1942
+ show(configPath),
1943
+ `boundaries: ${relaxed.join(', ')} ${relaxed.length === 1 ? 'is' : 'are'} turned down, so the policy gate ` +
1944
+ 'no longer refuses what they cover. Secret scanning at commit and push, the enforcement hooks, ' +
1945
+ '.claude/settings.json and .tyran/STOP are unaffected — no setting reaches those',
1946
+ `node scripts/schema.mjs validate config ${sq(configPath)} # then edit boundaries: to tighten`,
1947
+ ),
1948
+ );
1949
+ }
1950
+ checked.push(`boundaries: ${relaxed.length === 0 ? 'all strict' : `relaxed (${relaxed.join(', ')})`}`);
1951
+ if (!('boundaries' in configDoc)) {
1952
+ findings.push(
1953
+ finding(
1954
+ 'boundaries-absent',
1955
+ show(configPath),
1956
+ 'no boundaries: block — the strict default applies, which is correct, but the Settings tab patches ' +
1957
+ 'keys that already exist and will not invent them, so that whole section of the dashboard is ' +
1958
+ 'unusable in this repo',
1959
+ `node scripts/scan-repo.mjs --write ${sq(configPath)} # rewrites the config with the block in it`,
1960
+ ),
1961
+ );
1962
+ }
1963
+ }
1964
+
1918
1965
  const gitRun = run ?? gitRunner(repoRoot);
1919
1966
  const untracked = untrackedTyranDir(repoRoot, gitRun, basename(root));
1920
1967
  if (untracked === true) {
@@ -33,7 +33,7 @@ import { execFileSync } from 'node:child_process';
33
33
  import { join, resolve, dirname, extname, relative } from 'node:path';
34
34
  import { fileURLToPath } from 'node:url';
35
35
  import { parse, stringify } from './yaml-lite.mjs';
36
- import { validatePolicy } from './schema.mjs';
36
+ import { BOUNDARIES_STRICT, validatePolicy } from './schema.mjs';
37
37
  import { escapeInvisible } from './invisible.mjs';
38
38
  import { handleArgs } from './cli-args.mjs';
39
39
 
@@ -356,6 +356,15 @@ export function scanRepo(dir, { run = gitRunner(dir) } = {}) {
356
356
  tiers: { cheap: 'haiku', work: 'sonnet', deep: 'opus', top: 'fable' },
357
357
  validation,
358
358
  shared_zones: [],
359
+ // Every boundary ON, written out in full for the same reason `limits:` is
360
+ // below: the Settings tab patches keys that exist and refuses to invent
361
+ // them, so an absent block is a section of the dashboard nobody can use.
362
+ //
363
+ // Nothing here is inferred and nothing here is ever inferred. A scanner
364
+ // that could conclude "this repo looks like it wants its credentials
365
+ // readable" is a scanner that opens a boundary on evidence, and the
366
+ // evidence for opening one is a person deciding to.
367
+ boundaries: { preset: 'strict', ...BOUNDARIES_STRICT },
359
368
  // Written out in full, every value at its shipped default, with the
360
369
  // feature OFF. Nothing here enables anything — `mode: 'off'` is the same
361
370
  // inert state as omitting the block entirely.
@@ -548,6 +557,13 @@ export function renderConfig(config) {
548
557
  '# autonomy class at all, which is the boundary silently missing exactly\n' +
549
558
  '# where the most agents run.\n' +
550
559
  '#\n' +
560
+ '# GIVING AGENTS MORE ROOM: `boundaries:` below is the one place the policy\n' +
561
+ '# gate can be turned down. `preset: open` relaxes all five at once — the\n' +
562
+ '# closest thing to running with permissions skipped. Secret scanning at\n' +
563
+ '# commit and push, the enforcement hooks, `.claude/settings.json` and\n' +
564
+ '# `.tyran/STOP` are NOT reachable from it, whatever it is set to.\n' +
565
+ '# See docs/configuration.md.\n' +
566
+ '#\n' +
551
567
  '# Validate: node scripts/schema.mjs validate config .tyran/config.yaml\n' +
552
568
  '# Resolve a role to a model: node scripts/tiers.mjs --role reviewer\n' +
553
569
  '\n' +
@@ -34,6 +34,35 @@ export const TIER_KEYS = Object.freeze(['cheap', 'work', 'deep', 'top']);
34
34
  export const ARTIFACT_CLASSES = Object.freeze(['AUTO', 'GATED', 'KERNEL']);
35
35
  export const KNOWLEDGE_KINDS = Object.freeze(['fact', 'convention', 'gotcha', 'command', 'decision']);
36
36
 
37
+ /**
38
+ * `boundaries:` — how far down the policy gate's refusals may be turned.
39
+ *
40
+ * One block, because the alternative measured badly on real installs: an
41
+ * operator who wants agents to read a neighbouring project's files has no
42
+ * business learning what `main_writable_paths` is, and the answer to "let it
43
+ * do everything" must not be five unrelated edits in four files.
44
+ *
45
+ * Every flag is spelled the same way — the strict value first, so a reader
46
+ * scanning the list knows which column is the default without consulting a
47
+ * table. `prompts` is the odd one because it is not a refusal knob at all: it
48
+ * decides whether a call this gate has NO objection to still renders the
49
+ * platform's own permission prompt.
50
+ */
51
+ export const BOUNDARY_PRESETS = Object.freeze(['strict', 'open']);
52
+ export const BOUNDARY_VALUES = Object.freeze(['refuse', 'allow']);
53
+ export const BOUNDARY_PROMPTS = Object.freeze(['ask', 'skip']);
54
+ /** The four refusal flags, in the order they are documented. */
55
+ export const BOUNDARY_FLAGS = Object.freeze(['outside_repo', 'credentials', 'path_classes', 'push']);
56
+ /** Every key legal inside the block. */
57
+ export const BOUNDARY_KEYS = Object.freeze(['preset', ...BOUNDARY_FLAGS, 'prompts']);
58
+ /** What each preset resolves to before per-key overrides are applied. */
59
+ const BOUNDARY_BY_PRESET = Object.freeze({
60
+ strict: Object.freeze({ outside_repo: 'refuse', credentials: 'refuse', path_classes: 'refuse', push: 'refuse', prompts: 'ask' }),
61
+ open: Object.freeze({ outside_repo: 'allow', credentials: 'allow', path_classes: 'allow', push: 'allow', prompts: 'skip' }),
62
+ });
63
+ /** The safe answer, used for an absent block and for every value the schema rejects. */
64
+ export const BOUNDARIES_STRICT = BOUNDARY_BY_PRESET.strict;
65
+
37
66
  const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
38
67
  const isNonEmptyString = (v) => typeof v === 'string' && v.trim() !== '';
39
68
 
@@ -69,7 +98,7 @@ export function validateConfig(doc) {
69
98
  const errors = [];
70
99
  if (!isPlainObject(doc)) return ['config must be a mapping'];
71
100
 
72
- const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'limits', 'pricing', 'spend', 'board'];
101
+ const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'boundaries', 'limits', 'pricing', 'spend', 'board'];
73
102
  for (const key of Object.keys(doc)) {
74
103
  if (!known.includes(key)) errors.push(`${key}: unknown top-level key`);
75
104
  }
@@ -146,6 +175,30 @@ export function validateConfig(doc) {
146
175
  }
147
176
  }
148
177
 
178
+ // How far the policy gate's refusals may be turned down. Optional; absent
179
+ // means strict, which is what every install had before this block existed.
180
+ // Operator-written policy, never scanner-inferred — no provenance wrapper.
181
+ if ('boundaries' in doc) {
182
+ if (!isPlainObject(doc.boundaries)) errors.push('boundaries: must be a mapping');
183
+ else {
184
+ const boundaries = doc.boundaries;
185
+ if ('preset' in boundaries && !BOUNDARY_PRESETS.includes(boundaries.preset)) {
186
+ errors.push(`boundaries.preset: must be one of ${BOUNDARY_PRESETS.join(' | ')}`);
187
+ }
188
+ for (const flag of BOUNDARY_FLAGS) {
189
+ if (flag in boundaries && !BOUNDARY_VALUES.includes(boundaries[flag])) {
190
+ errors.push(`boundaries.${flag}: must be one of ${BOUNDARY_VALUES.join(' | ')}`);
191
+ }
192
+ }
193
+ if ('prompts' in boundaries && !BOUNDARY_PROMPTS.includes(boundaries.prompts)) {
194
+ errors.push(`boundaries.prompts: must be one of ${BOUNDARY_PROMPTS.join(' | ')}`);
195
+ }
196
+ for (const key of Object.keys(boundaries)) {
197
+ if (!BOUNDARY_KEYS.includes(key)) errors.push(`boundaries.${key}: unknown key`);
198
+ }
199
+ }
200
+ }
201
+
149
202
  // Overnight mode: usage-limit pause/resume. Optional; absent = feature off.
150
203
  // Operator-written policy, never scanner-inferred — no provenance wrapper.
151
204
  if ('limits' in doc) {
@@ -313,6 +366,40 @@ export function boardSettings(doc) {
313
366
  };
314
367
  }
315
368
 
369
+ /**
370
+ * The boundaries block with the preset expanded and overrides applied — the
371
+ * ONE place the resolution rule lives, called by the policy gate, doctor, the
372
+ * Settings tab and anything else that needs to know how open this repo is.
373
+ *
374
+ * Two properties, and both are the security-critical direction of `limitsOf`'s
375
+ * doctrine rather than a copy of it:
376
+ *
377
+ * - an absent block is STRICT, so every install written before this existed
378
+ * keeps exactly the behaviour it had;
379
+ * - a value the validator rejects is treated as absent, which for a knob
380
+ * whose looser setting removes a refusal means it must never RELAX on
381
+ * input nobody can read. `credentials: yes` is not `allow`, and guessing
382
+ * that it is would open the secret-read rule on a typo.
383
+ *
384
+ * An explicit key beats the preset, in both directions: `preset: open` with
385
+ * `credentials: refuse` is a repo that wants everything except its own keys.
386
+ */
387
+ export function boundariesOf(doc) {
388
+ const raw = isPlainObject(doc) && isPlainObject(doc.boundaries) ? doc.boundaries : {};
389
+ const base = BOUNDARY_BY_PRESET[raw.preset] ?? BOUNDARIES_STRICT;
390
+ const resolved = { ...base };
391
+ for (const flag of BOUNDARY_FLAGS) {
392
+ if (BOUNDARY_VALUES.includes(raw[flag])) resolved[flag] = raw[flag];
393
+ }
394
+ if (BOUNDARY_PROMPTS.includes(raw.prompts)) resolved.prompts = raw.prompts;
395
+ return Object.freeze(resolved);
396
+ }
397
+
398
+ /** Which flags are looser than strict — what a doctor finding and the board report. */
399
+ export function relaxedBoundaries(resolved) {
400
+ return Object.keys(BOUNDARIES_STRICT).filter((key) => resolved[key] !== BOUNDARIES_STRICT[key]);
401
+ }
402
+
316
403
  export const LIMITS_MODES = Object.freeze(['off', 'warn', 'pause']);
317
404
  export const LIMITS_LONG_WAIT = Object.freeze(['hold', 'resume']);
318
405
 
@@ -38,6 +38,9 @@ import { join } from 'node:path';
38
38
  import {
39
39
  ARTIFACT_CLASSES,
40
40
  AUTONOMY_CLASSES,
41
+ BOUNDARY_PRESETS,
42
+ BOUNDARY_PROMPTS,
43
+ BOUNDARY_VALUES,
41
44
  LIMITS_LONG_WAIT,
42
45
  LIMITS_MODES,
43
46
  MANDATORY_KERNEL_PATHS,
@@ -95,6 +98,11 @@ export const GROUPS = Object.freeze([
95
98
  path: ['autonomy'],
96
99
  label: 'Deployment autonomy',
97
100
  help: 'How far a finished piece of work may travel without you. The gate enforces this downward — it will not stop someone who edits this file from raising it, which is why the policy below decides who may.',
101
+ widening: {
102
+ scale: 'autonomy',
103
+ consequence:
104
+ 'A higher deployment class lets finished work travel further without you — P2 reaches staging, P3 merges to the default branch.',
105
+ },
98
106
  ...choice(AUTONOMY_CLASSES, {
99
107
  P1: 'Branch only. Agents commit and push a branch; you open and merge the PR.',
100
108
  P2: 'Through to staging. Agents may merge and deploy to a non-production environment.',
@@ -103,6 +111,101 @@ export const GROUPS = Object.freeze([
103
111
  },
104
112
  ],
105
113
  },
114
+ {
115
+ id: 'boundaries',
116
+ title: 'What agents may touch',
117
+ blurb:
118
+ 'How far the policy gate turns its refusals down. Everything here starts at the strict setting, and every move toward the looser one asks you to confirm it a second time. Four things are NOT on this screen because no setting reaches them: secret scanning at commit and push, the enforcement hooks themselves, the file that registers them, and the STOP brake.',
119
+ settings: [
120
+ {
121
+ id: 'boundaries.preset',
122
+ path: ['boundaries', 'preset'],
123
+ label: 'Preset',
124
+ help: 'The one switch. "Open" turns every boundary below to its loose setting at once — the closest thing Tyran has to running Claude Code with permissions skipped. Anything you set individually below wins over the preset.',
125
+ widening: {
126
+ scale: 'preset',
127
+ consequence:
128
+ 'OPEN lets agents read your credentials, work outside this repository, write paths your own policy gates, push anywhere, and act without a permission prompt. Secret scanning and the gate\'s own files are unaffected.',
129
+ },
130
+ ...choice(BOUNDARY_PRESETS, {
131
+ strict: 'Every boundary on. This is what Tyran has always done.',
132
+ open: 'Every boundary below turned down at once.',
133
+ }),
134
+ },
135
+ {
136
+ id: 'boundaries.outside_repo',
137
+ path: ['boundaries', 'outside_repo'],
138
+ label: 'Files outside this repository',
139
+ help: 'Today a path outside the repo root is refused for every agent. Allowing it lets them read and write anywhere on this machine — another project, your home directory, system files.',
140
+ widening: {
141
+ scale: 'boundary',
142
+ consequence: 'Agents will be able to write files anywhere on this machine, not only inside this repository.',
143
+ },
144
+ ...choice(BOUNDARY_VALUES, {
145
+ refuse: 'Agents stay inside this repository.',
146
+ allow: 'Agents may read and write anywhere on this machine.',
147
+ }),
148
+ },
149
+ {
150
+ id: 'boundaries.credentials',
151
+ path: ['boundaries', 'credentials'],
152
+ label: 'Credential files',
153
+ help: 'Today .env files, private keys, ~/.ssh, ~/.aws and their relatives are refused before they can reach the model — a transcript is storage. Allowing it also removes the false refusal where a word merely ENDING in .key or .pem is treated as a file.',
154
+ widening: {
155
+ scale: 'boundary',
156
+ consequence:
157
+ 'Agents will be able to read your secrets into the conversation. What stops those bytes being COMMITTED or PUSHED is the secrets gate, which this setting does not reach.',
158
+ },
159
+ ...choice(BOUNDARY_VALUES, {
160
+ refuse: 'Credential-shaped files never enter the conversation.',
161
+ allow: 'Agents may read .env files, keys and credential stores.',
162
+ }),
163
+ },
164
+ {
165
+ id: 'boundaries.path_classes',
166
+ path: ['boundaries', 'path_classes'],
167
+ label: 'Your own path rules',
168
+ help: 'The AUTO / GATED / KERNEL rules in the policy below. Allowing this makes them advisory: a subagent may write a path you gated. The four paths that protect the gate itself stay refused whatever this says.',
169
+ widening: {
170
+ scale: 'boundary',
171
+ consequence: 'The GATED and KERNEL rules in your own policy stop being enforced for writes.',
172
+ },
173
+ ...choice(BOUNDARY_VALUES, {
174
+ refuse: 'The classes in your policy are enforced.',
175
+ allow: 'Agents may write paths your policy gates.',
176
+ }),
177
+ },
178
+ {
179
+ id: 'boundaries.push',
180
+ path: ['boundaries', 'push'],
181
+ label: 'Where work may be pushed',
182
+ help: 'Turns off the deployment-class check on git push entirely, including the rules that gate the pushes nothing can undo — a force push to main, a deleted remote branch, a mirror push.',
183
+ widening: {
184
+ scale: 'boundary',
185
+ consequence:
186
+ 'The deployment class stops being checked. Agents may force-push, delete remote branches and mirror-push, none of which can be undone.',
187
+ },
188
+ ...choice(BOUNDARY_VALUES, {
189
+ refuse: 'Pushes are checked against the deployment autonomy above.',
190
+ allow: 'Any push is allowed, including the irreversible ones.',
191
+ }),
192
+ },
193
+ {
194
+ id: 'boundaries.prompts',
195
+ path: ['boundaries', 'prompts'],
196
+ label: 'Permission prompts',
197
+ help: 'Whether Claude Code still asks you before a tool call this gate has no objection to. "Skip" auto-approves those calls, which is what people mean by skipping permissions — a refusal from any gate still wins, so this cannot approve something another gate denied.',
198
+ widening: {
199
+ scale: 'prompts',
200
+ consequence: 'Claude Code will stop asking before it edits files or runs commands that no gate objects to.',
201
+ },
202
+ ...choice(BOUNDARY_PROMPTS, {
203
+ ask: 'Claude Code prompts you as it normally would.',
204
+ skip: 'Calls no gate objects to are approved without asking.',
205
+ }),
206
+ },
207
+ ],
208
+ },
106
209
  {
107
210
  id: 'tiers',
108
211
  title: 'Model tiers',
@@ -246,6 +349,11 @@ const BY_ID = new Map(GROUPS.flatMap((g) => g.settings.map((s) => [s.id, s])));
246
349
  const LOOSER_FIRST = Object.freeze({
247
350
  class: Object.freeze(['AUTO', 'GATED', 'KERNEL']),
248
351
  autonomy: Object.freeze(['P3', 'P2', 'P1']),
352
+ // The `boundaries:` block. Each of these turns a REFUSAL off, so the
353
+ // direction that needs the second act is the one that removes a check.
354
+ boundary: Object.freeze([...BOUNDARY_VALUES].reverse()),
355
+ prompts: Object.freeze([...BOUNDARY_PROMPTS].reverse()),
356
+ preset: Object.freeze([...BOUNDARY_PRESETS].reverse()),
249
357
  });
250
358
 
251
359
  function widens(scale, before, after) {
@@ -462,9 +570,12 @@ export function applySetting(tyranDir, id, value, confirm = null) {
462
570
  );
463
571
  }
464
572
  const next = coerce(setting, value);
465
- if (id === 'autonomy') {
466
- requireConfirm('autonomy', before, next, confirm,
467
- 'A higher deployment class lets finished work travel further without you — P2 reaches staging, P3 merges to the default branch.');
573
+ // Driven by the catalogue rather than by a list of ids here. The `autonomy`
574
+ // check used to be an `if (id === ...)`, and every knob added beside it since
575
+ // would have had to remember to extend that line — which is exactly how a
576
+ // boundary-loosening control ships with no confirmation at all.
577
+ if (setting.widening) {
578
+ requireConfirm(setting.widening.scale, before, next, confirm, setting.widening.consequence);
468
579
  }
469
580
 
470
581
  let text;
@@ -248,6 +248,26 @@ agent that runs `git add -A` on a story branch sweeps the untracked `.tyran/`
248
248
  into that branch, and a four-way parallel run ends with four conflicting
249
249
  copies of the config. Stage explicit paths until this commit exists.
250
250
 
251
+ ## 6b. Say that `boundaries:` exists, once, and do not sell it
252
+
253
+ The scan writes the block at its strict setting. Tell the operator, in one or
254
+ two sentences, that `.tyran/config.yaml` has a `boundaries:` block and that
255
+ `preset: open` relaxes all five at once — files outside the repo, credential
256
+ files, their own path rules, the deployment class on `git push`, and the
257
+ permission prompt. The Settings tab edits it, and every move toward the loose
258
+ value asks for a confirmation.
259
+
260
+ Say the floor in the same breath, because it is what makes the offer safe to
261
+ make: secret scanning at commit and push, the enforcement hooks,
262
+ `.claude/settings.json` and `.tyran/STOP` are unreachable from it at any
263
+ setting.
264
+
265
+ **Do not recommend a value, and do not ask which they want.** Strict is
266
+ already written and already correct; this is a pointer for the operator who
267
+ comes back later having hit a refusal they did not want, not a decision to
268
+ extract during setup. An agent that talks somebody into opening a boundary
269
+ during onboarding is the failure this step exists to avoid.
270
+
251
271
  ## 7. Offer overnight mode — and say plainly what the operator must do
252
272
 
253
273
  Overnight mode (https://jjanczur.github.io/tyran/overnight/) pauses autonomous work near the
@@ -43,6 +43,34 @@ validation:
43
43
  # Files multiple agents may touch: append-only, serialized by the conductor.
44
44
  shared_zones: []
45
45
 
46
+ # How far the policy gate turns its refusals DOWN. Every value here is the
47
+ # strict one, which is what Tyran did before this block existed — nothing is
48
+ # relaxed by having it in the file, only made editable from the Settings tab.
49
+ #
50
+ # preset: strict | open one switch. `open` sets all five below at once and
51
+ # is the closest thing to running with permissions
52
+ # skipped. Anything you set explicitly wins over it.
53
+ # outside_repo refuse | allow — files outside this repository
54
+ # credentials refuse | allow — .env, keys, ~/.ssh, ~/.aws
55
+ # path_classes refuse | allow — the GATED/KERNEL rules you wrote
56
+ # push refuse | allow — the deployment class on git push
57
+ # prompts ask | skip — skip Claude Code's own prompts
58
+ #
59
+ # FOUR THINGS NO SETTING HERE REACHES, whatever it says: secret scanning at
60
+ # commit and push, the enforcement hooks, `.claude/settings.json`, and
61
+ # `.tyran/STOP`. A refusal from any gate still wins over an auto-approval.
62
+ #
63
+ # This file is class AUTO, so an agent can widen these itself — the same trade
64
+ # `autonomy:` above already makes, and the reason the four exceptions are
65
+ # mechanical rather than a matter of policy. See docs/policy-gate.md.
66
+ boundaries:
67
+ preset: strict
68
+ outside_repo: refuse
69
+ credentials: refuse
70
+ path_classes: refuse
71
+ push: refuse
72
+ prompts: ask
73
+
46
74
  # Overnight mode — pause autonomous work near the subscription usage limits
47
75
  # and resume after the window resets (https://jjanczur.github.io/tyran/overnight/). Requires the
48
76
  # operator-installed statusline helper (scripts/statusline.mjs), which is the