@yeison.restrepo.r/code-conductor 1.31.2 → 1.32.0

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/README.md CHANGED
@@ -186,7 +186,7 @@ Fires before `Read`, `Write`, `Edit`, `create_file`, `write_file` and `Bash`. A
186
186
 
187
187
  **Bash scan guard (Guard 3)** - every `Bash` command is matched against twelve mass content-dump patterns before it runs: deep `find` without `-maxdepth 1`, `find -exec` with readers or shells, `xargs` with readers, `cat` or a pager followed by an unquoted glob, command substitution as a reader's argument, `grep -r` with a match-all pattern, `ls -R`, shell loops, `mapfile` and `readarray`, `eval`, `source` and the dot operator, alias remapping to a reader, and obfuscation sequences. Commands over 8192 characters and unclosed quotes are denied fail-closed.
188
188
 
189
- Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry per line, blank lines and `#` comments ignored and whitespace trimmed. An entry ending in `/` covers paths under that prefix, rejecting any suffix that walks up the tree with `..`; any other entry matches a whole command token. **Entries match literally: regex metacharacters carry no special meaning, so `file.ts` matches `file.ts` and nothing else.** The installer never ships or overwrites this file. Every line in it disarms patterns for matching commands, so give each entry a comment saying why it exists; an uncommented entry is a review smell.
189
+ Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry per line, blank lines and `#` comments ignored and whitespace trimmed. An entry ending in `/` covers paths under that prefix, rejecting any suffix that walks up the tree with `..`; any other entry matches a whole command token. **Entries match literally: regex metacharacters carry no special meaning, so `file.ts` matches `file.ts` and nothing else.** The installer ships this file once as a commented template and creates it only when it is absent; it never overwrites an existing one. Every line in it disarms patterns for matching commands, so give each entry a comment saying why it exists; an uncommented entry is a review smell.
190
190
 
191
191
  Hit a block you believe is wrong? Re-run the command with `CC_GUARD3_WARN=1` and the guard asks instead of denying, carrying the same pattern ids. That is a triage aid for reporting a false positive while you keep working, not a configuration mode: the allowlist is the sanctioned permanent exception. The variable affects Guard 3 alone.
192
192
 
@@ -23,15 +23,20 @@ export const GLOBAL_HOST_OWNED = new Map([
23
23
  ['settings.local.json', 'skip'],
24
24
  ]);
25
25
 
26
- // <cwd>/.claude/. Only project.md and context-threshold.txt ship. Every 'skip'
27
- // below is a file the host or a conductor command writes at runtime and the
28
- // template must never start shipping; each is protected today only by its
29
- // absence from the template, which is exactly what this table replaces.
26
+ // <cwd>/.claude/. Every 'skip' below is a file the host or a conductor command writes
27
+ // at runtime and the template must never start shipping; each is protected today only
28
+ // by its absence from the template, which is exactly what this table replaces.
29
+ //
30
+ // bash-scan-allowlist.txt is the exception and the reason the policy is a table: it is
31
+ // host-owned like the skips, but BUG-044 ships a comment-only template for it so the deny
32
+ // message names a path that resolves. hostOwnedFilter excludes it from the copy and
33
+ // seedHostOwned writes it only when absent, so shipping the filename cannot overwrite
34
+ // operator policy the way it could before BUG-039 filtered the copy.
30
35
  export const PROJECT_HOST_OWNED = new Map([
31
36
  ['memory/project.md', 'seed'],
32
37
  ['memory/context-threshold.txt', 'seed'],
33
38
  ['memory/personal.md', 'skip'],
34
- ['memory/bash-scan-allowlist.txt', 'skip'],
39
+ ['memory/bash-scan-allowlist.txt', 'seed'],
35
40
  ['memory/session-snapshot.json', 'skip'],
36
41
  ['memory/session-snapshot.md', 'skip'],
37
42
  ['memory/turn-count.txt', 'skip'],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yeison.restrepo.r/code-conductor",
3
- "version": "1.31.2",
3
+ "version": "1.32.0",
4
4
  "description": "A spec-first, token-efficient Claude Code configuration and installer CLI.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -155,6 +155,7 @@ function g3JoinContinuations(input) {
155
155
  // unclosed quote). "glob" reports whether an unquoted glob character appears, and
156
156
  // treats malformed input as a glob, which is the authority's fail-closed choice.
157
157
  function g3Scan(mode, input) {
158
+ const emit = mode === 'strip' || mode === 'mask';
158
159
  let state = 'UNQUOTED';
159
160
  let result = '';
160
161
  let i = 0;
@@ -163,34 +164,35 @@ function g3Scan(mode, input) {
163
164
  const ch = input[i];
164
165
  const two = input.slice(i, i + 2);
165
166
  if (state === 'UNQUOTED') {
166
- if (two === "$'") { if (mode === 'strip') result += two; i += 2; state = 'ANSI_C_QUOTED'; }
167
- else if (two === '$"') { if (mode === 'strip') result += two; i += 2; state = 'LOCALE_QUOTED'; }
168
- else if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); i += 2; }
169
- else if (ch === "'") { if (mode === 'strip') result += ch; i += 1; state = 'SINGLE_QUOTED'; }
170
- else if (ch === '"') { if (mode === 'strip') result += ch; i += 1; state = 'DOUBLE_QUOTED'; }
167
+ if (two === "$'") { if (emit) result += two; i += 2; state = 'ANSI_C_QUOTED'; }
168
+ else if (two === '$"') { if (emit) result += two; i += 2; state = 'LOCALE_QUOTED'; }
169
+ else if (ch === '\\') { if (emit) result += input.slice(i, i + 2); i += 2; }
170
+ else if (ch === "'") { if (emit) result += ch; i += 1; state = 'SINGLE_QUOTED'; }
171
+ else if (ch === '"') { if (emit) result += ch; i += 1; state = 'DOUBLE_QUOTED'; }
171
172
  else if (ch === '#' && mode === 'strip') { while (i < len && input[i] !== '\n') i += 1; }
172
173
  else {
173
174
  if (mode === 'glob' && (ch === '*' || ch === '?' || ch === '{' || ch === '[')) return { glob: true };
174
- if (mode === 'strip') result += ch;
175
+ if (emit) result += ch;
175
176
  i += 1;
176
177
  }
177
178
  } else if (state === 'SINGLE_QUOTED') {
178
179
  // Backslash is literal here and ANY quote exits: there is no escape mechanism.
179
180
  if (mode === 'strip') result += ch;
181
+ else if (mode === 'mask') result += ch === "'" ? ch : 'x';
180
182
  if (ch === "'") state = 'UNQUOTED';
181
183
  i += 1;
182
184
  } else if (state === 'DOUBLE_QUOTED' || state === 'LOCALE_QUOTED') {
183
- if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); i += 2; }
184
- else if (ch === '"') { if (mode === 'strip') result += ch; i += 1; state = 'UNQUOTED'; }
185
- else { if (mode === 'strip') result += ch; i += 1; }
185
+ if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); else if (mode === 'mask') result += 'xx'; i += 2; }
186
+ else if (ch === '"') { if (emit) result += ch; i += 1; state = 'UNQUOTED'; }
187
+ else { if (mode === 'strip') result += ch; else if (mode === 'mask') result += 'x'; i += 1; }
186
188
  } else {
187
- if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); i += 2; }
188
- else if (ch === "'") { if (mode === 'strip') result += ch; i += 1; state = 'UNQUOTED'; }
189
- else { if (mode === 'strip') result += ch; i += 1; }
189
+ if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); else if (mode === 'mask') result += 'xx'; i += 2; }
190
+ else if (ch === "'") { if (emit) result += ch; i += 1; state = 'UNQUOTED'; }
191
+ else { if (mode === 'strip') result += ch; else if (mode === 'mask') result += 'x'; i += 1; }
190
192
  }
191
193
  }
192
- if (state !== 'UNQUOTED') return mode === 'strip' ? { result, malformed: true } : { glob: true };
193
- return mode === 'strip' ? { result, malformed: false } : { glob: false };
194
+ if (state !== 'UNQUOTED') return emit ? { result, malformed: true } : { glob: true };
195
+ return emit ? { result, malformed: false } : { glob: false };
194
196
  }
195
197
 
196
198
  // Each check returns true when it FIRES (the authority's shell functions returned 1).
@@ -427,14 +429,28 @@ const g3Chomp = (s) => s.replace(/\n+$/, '');
427
429
  // keeps working instead of filing an uninstall. It is documented as triage, not as
428
430
  // configuration: the allowlist is the sanctioned permanent exception. It has no
429
431
  // relationship to CC_HOOK_ALLOW, whose scope stays the two pre-verdict conditions.
430
- function g3Blocked(detail) {
432
+ // The three alternatives are the only remedy every denial shares, so they are the
433
+ // message's constant part.
434
+ const G3_ALTERNATIVES =
435
+ 'Authorized alternatives: 1. Grep for targeted content search with file and pattern scope. ' +
436
+ '2. Glob for path listing without file content. 3. Read with an explicit offset and limit.';
437
+
438
+ // The allowlist sentence rides ONLY on a pattern denial. g3AllowlistCovers runs at the end
439
+ // of guard3BashScan; the length and malformed denials return before it, so on those two the
440
+ // allowlist cannot lift the block and naming it would promise a remedy that provably does
441
+ // not apply. It is worded as operator policy because the agent reading it mid-denial is
442
+ // instructed never to bypass this hook: it may propose an entry, never self-serve one.
443
+ // Uptake staying at zero is that instruction working, not a discoverability failure.
444
+ // [BUG-044]
445
+ const G3_OPERATOR_POLICY =
446
+ 'A permanent exception is operator policy, not a self-serve step: entries live in ' +
447
+ '.claude/memory/bash-scan-allowlist.txt, are reviewed in git, and an agent may propose ' +
448
+ 'one but must not add it to clear its own denial.';
449
+
450
+ function g3Blocked(detail, { allowlistApplies = false } = {}) {
431
451
  const decide = process.env.CC_GUARD3_WARN ? ask : deny;
432
- return decide(
433
- `BASH SCAN BLOCKED. ${detail} ` +
434
- 'Authorized alternatives: 1. Grep for targeted content search with file and pattern scope. ' +
435
- '2. Glob for path listing without file content. 3. Read with an explicit offset and limit. ' +
436
- 'To permit a path permanently, add a commented entry to .claude/memory/bash-scan-allowlist.txt.'
437
- );
452
+ const policy = allowlistApplies ? ` ${G3_OPERATOR_POLICY}` : '';
453
+ return decide(`BASH SCAN BLOCKED. ${detail} ${G3_ALTERNATIVES}${policy}`);
438
454
  }
439
455
 
440
456
  // Guard 3: the bash command scanner, ported from tests/fixtures/guard3-reference.sh.
@@ -451,12 +467,21 @@ function guard3BashScan(input) {
451
467
  }
452
468
  // Real newlines become semicolons so a multi-line script reads as a command
453
469
  // sequence to every position-anchored pattern above.
454
- const pre = g3Chomp(scan.result).split('\n').join(';');
470
+ //
471
+ // The mask is built from the STRIPPED string and BEFORE the newline join, so a
472
+ // newline inside a quoted region can never become a command-position anchor.
473
+ // Exactly two checks read quoted content BY DESIGN: P6 reads the grep pattern and
474
+ // P12 reads the alias value. Everything else reads code and gets the mask. The
475
+ // allowlist reads the unmasked string. [BUG-043].
476
+ const chomped = g3Chomp(scan.result);
477
+ const pre = chomped.split('\n').join(';');
478
+ const masked = g3Scan('mask', chomped).result.split('\n').join(';');
479
+ const UNMASKED_CHECKS = new Set(['P6', 'P12']);
455
480
  const ids = [];
456
- for (const { id, check } of G3_CHECKS) if (check(pre)) ids.push(id);
481
+ for (const { id, check } of G3_CHECKS) if (check(UNMASKED_CHECKS.has(id) ? pre : masked)) ids.push(id);
457
482
  if (ids.length === 0) return null;
458
483
  if (g3AllowlistCovers(pre, g3ReadAllowlist())) return null;
459
- return g3Blocked(`The command triggered a mass content-dump pattern. Pattern ids: ${ids.join(' ')}.`);
484
+ return g3Blocked(`The command triggered a mass content-dump pattern. Pattern ids: ${ids.join(' ')}.`, { allowlistApplies: true });
460
485
  }
461
486
 
462
487
  const DISPATCH = {
@@ -0,0 +1,29 @@
1
+ # Guard 3 bash-scan allowlist. OPERATOR POLICY, reviewed in git.
2
+ #
3
+ # This file is empty on purpose. It disarms nothing until you add a line.
4
+ #
5
+ # Format:
6
+ # One entry per line. Blank lines and lines starting with # are ignored, and
7
+ # surrounding whitespace is trimmed.
8
+ #
9
+ # An entry ending in / covers paths under that prefix, and rejects any suffix
10
+ # that walks up the tree with .. so an entry cannot become a traversal gift.
11
+ # Any other entry matches a whole command token.
12
+ #
13
+ # Entries match LITERALLY. Regex metacharacters carry no special meaning, so
14
+ # file.ts matches file.ts and nothing else.
15
+ #
16
+ # Review rule:
17
+ # Every line here disarms Guard 3 patterns for matching commands, so give each
18
+ # entry a comment saying why it exists and ideally the issue it came from. An
19
+ # uncommented entry is a review smell.
20
+ #
21
+ # Example, shown commented out so this file stays inert:
22
+ # # docs/ is a small hand-written tree; bulk reads there are intended [BUG-000]
23
+ # docs/
24
+ #
25
+ # An agent that hits a Guard 3 denial may propose an entry here. It must not add
26
+ # one to clear its own denial: that is the bypass the project forbids. Permanent
27
+ # exceptions are the operator's call, which is why they are reviewed in git.
28
+ #
29
+ # The installer creates this file only when it is absent and never overwrites it.