@lovrozagar/grunt 0.7.0 → 0.8.0

package/.agents/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: 'Short status update: done, next, and blockers or on-track ETA.'
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/.claude/settings.json

@@ -73,6 +73,17 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   },
   "enableAllProjectMcpServers": false,

package/.claude/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: 'Short status update: done, next, and blockers or on-track ETA.'
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/.codex/hooks.json

@@ -64,6 +64,17 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/.grok/hooks/orchestrate-parent.js

@@ -87,7 +87,6 @@ function preToolUse(data) {
       });
       return 0;
     }
-    emit({ decision: "allow" });
     return 0;
   }
   if (WRITE_TOOLS.has(toolKey)) {
@@ -96,7 +95,6 @@ function preToolUse(data) {
   }
   const fatCode = emitFat(data);
   if (fatCode !== null) return fatCode;
-  emit({ decision: "allow" });
   return 0;
 }
 
@@ -162,7 +160,7 @@ export function isUnderTmp(filePath, workspaceRoot) {
 
 function parentWrite(data, toolInput) {
   if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) {
-    emit({ decision: "deny", reason: DENY_REASON });
+    emit(denyResponse(DENY_REASON));
     return 0;
   }
   const ws = workspaceRootOf(data);
@@ -200,7 +198,7 @@ function parentWrite(data, toolInput) {
       if (!isFullImplementationBody(content)) return null;
       const errors = validateImplementation(path.basename(abs), content);
       if (errors.length) {
-        emit({ decision: "deny", reason: errors.join("; ") || invalid });
+        emit(denyResponse(errors.join("; ") || invalid));
         return 0;
       }
       const next = Object.assign({}, toolInput, {
@@ -224,10 +222,7 @@ function parentWrite(data, toolInput) {
   const content = typeof toolInput.content === "string" ? toolInput.content : "";
   const result = persist({ workspaceRoot: ws, content });
   if (!result.ok) {
-    emit({
-      decision: "deny",
-      reason: result.error || invalid,
-    });
+    emit(denyResponse(result.error || invalid));
     return 0;
   }
   const next = Object.assign({}, toolInput, {

package/.grok/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: 'Short status update: done, next, and blockers or on-track ETA.'
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/.rulesync/hooks.jsonc

@@ -25,6 +25,14 @@
         "timeout": 5
       }
     ],
+    "sessionStart": [
+      {
+        // Code-only folder map as additionalContext (hooks-union keeps it first).
+        "type": "command",
+        "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs\"",
+        "timeout": 5
+      }
+    ],
     "beforeSubmitPrompt": [
       {
         "type": "command",

package/.rulesync/reference/INDEX.md

@@ -6,7 +6,7 @@ Protocol stays overview; domain fills this.
 
 ## Skills naming
 
-Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `tmp` `write-plan`.
+Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `su` `tmp` `write-plan`.
 
 Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init / `grunt upgrade` force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
 
@@ -32,6 +32,7 @@ Upgrade copies the current package trees and product scripts, then deletes cumul
 | listen | local | Speech-to-text via node scripts/listen.mjs (ffmpeg mic + local whisper.cpp, OpenAI fallback). Input only. |  |  |  |
 | pickup | local | Continue a handoff under .tmp/grunt/handoffs/. |  |  |  |
 | speak | local | Text-to-speech via node scripts/speak.mjs (ElevenLabs or OpenAI). Output only. |  |  |  |
+| su | local | Short status update: done, next, and blockers or on-track ETA. |  |  |  |
 | tmp | local | Dump a one-off convo artifact under .tmp/grunt/. |  |  |  |
 | write-plan | local | Write a local checklist under .tmp/grunt/plans/. Then /implement-plan {n}. |  |  |  |
 
@@ -43,7 +44,7 @@ Upgrade copies the current package trees and product scripts, then deletes cumul
 | .rulesync/reference/cascade.md | Protocol | cascade | The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `scripts/grunt-job.mjs` (squeez + stash). Isolat… |
 | .rulesync/reference/clasp.md | Clasp | clasp | Low-level Apps Script CLI. Optional. Doctor reports it. |
 | .rulesync/reference/google-workspace.md | google-workspace | google-workspace | Create and edit Google Sheets, Docs, Slides, Calendar events, and Gmail from the session. |
-| .rulesync/reference/hooks.md | Hooks | hooks | SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `../../.grok/h… |
+| .rulesync/reference/hooks.md | Hooks | hooks | SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-on… |
 | .rulesync/reference/implementation-format.md | Implementation format (SSOT) |  | Local session journal for `/implement-plan`. Not a plan, handoff, or git commit. |
 | .rulesync/reference/law.md | Law |  | Protocol stays overview; domain fills this. |
 | .rulesync/reference/listen.md | Listen | listen | Speech-to-text from the session. Input only. Not TTS. Not a live voice agent. Not MCP. |

package/.rulesync/reference/hooks.md

@@ -4,7 +4,7 @@ tags: [hooks]
 
 # Hooks
 
-SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `../../.grok/hooks/orchestrate-parent.json`.
+SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-only map from `../../scripts/folder-map.mjs` as `additionalContext` (budget 5k tokens, cache-stable, fail-open) and logs `{rows, tokens}` to `.tmp/grunt/sessions/<sid>/map.json`. Inject nothing else at SessionStart. Antigravity has no rulesync sessionStart. Do not register a SessionStart hook on `../../.grok/hooks/orchestrate-parent.json`.
 
 Grok PostToolUse / SessionStart are observe-only — do not attempt output scrub; compress via RTK / spawn / isolation facts only. Do not add PostToolUse scrub hooks. Grok UserPromptSubmit may emit a one-line `sessionGate=auto|ask` plus session receipt (`hookSpecificOutput.additionalContext`). Skip host Stop banners. `/ask` exact-match slash stamps `session-gate-{sid}` to `ask`. `/auto` unlinks. Sid-less: no stamp. Default: `auto`.
 

package/.rulesync/reference/law.md

@@ -4,7 +4,7 @@ Protocol stays overview; domain fills this.
 
 ## Skills naming
 
-Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `tmp` `write-plan`.
+Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `su` `tmp` `write-plan`.
 
 Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init / `grunt upgrade` force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
 

package/.rulesync/reference/refs-map.md

@@ -8,7 +8,7 @@
 | .rulesync/reference/cascade.md | Protocol | cascade | The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `scripts/grunt-job.mjs` (squeez + stash). Isolat… |
 | .rulesync/reference/clasp.md | Clasp | clasp | Low-level Apps Script CLI. Optional. Doctor reports it. |
 | .rulesync/reference/google-workspace.md | google-workspace | google-workspace | Create and edit Google Sheets, Docs, Slides, Calendar events, and Gmail from the session. |
-| .rulesync/reference/hooks.md | Hooks | hooks | SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `../../.grok/h… |
+| .rulesync/reference/hooks.md | Hooks | hooks | SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-on… |
 | .rulesync/reference/implementation-format.md | Implementation format (SSOT) |  | Local session journal for `/implement-plan`. Not a plan, handoff, or git commit. |
 | .rulesync/reference/law.md | Law |  | Protocol stays overview; domain fills this. |
 | .rulesync/reference/listen.md | Listen | listen | Speech-to-text from the session. Input only. Not TTS. Not a live voice agent. Not MCP. |

package/.rulesync/reference/skills-map.md

@@ -20,5 +20,6 @@
 | listen | local | Speech-to-text via node scripts/listen.mjs (ffmpeg mic + local whisper.cpp, OpenAI fallback). Input only. |  |  |  |
 | pickup | local | Continue a handoff under .tmp/grunt/handoffs/. |  |  |  |
 | speak | local | Text-to-speech via node scripts/speak.mjs (ElevenLabs or OpenAI). Output only. |  |  |  |
+| su | local | Short status update: done, next, and blockers or on-track ETA. |  |  |  |
 | tmp | local | Dump a one-off convo artifact under .tmp/grunt/. |  |  |  |
 | write-plan | local | Write a local checklist under .tmp/grunt/plans/. Then /implement-plan {n}. |  |  |  |

package/.rulesync/rules/overview.md

@@ -12,8 +12,10 @@ You are the session agent. Do the work. Use en-US unless asked. Write concise co
 
 Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
 Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.
+Ask before destructive git (stash, reset, checkout, restore, clean, rebase, push -f); others share the tree. In a loop, skip it and edit code instead.
 
 Read `.rulesync/reference/INDEX.md` once. When a row matches the work, read that reference in full.
+Use the folder map in session context to find code. Run `node scripts/folder-map.mjs <dir>` for depth before `ls` or `find`.
 
 Large dumps are compressed (search, test logs, snaps). Scratch and dumps live in `.tmp/grunt/` (gitignored). After a write, recap the path; edit with an offset slice when you need lines.
 Fat dumps: `node scripts/grunt-job.mjs --job search|exec|slice|fetch|test` first; spawn grunt only when the dump needs judgment.

package/.rulesync/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: "Short status update: done, next, and blockers or on-track ETA."
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/AGENTS.md

@@ -3,8 +3,10 @@ You are the session agent. Do the work. Use en-US unless asked. Write concise co
 
 Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
 Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.
+Ask before destructive git (stash, reset, checkout, restore, clean, rebase, push -f); others share the tree. In a loop, skip it and edit code instead.
 
 Read `.rulesync/reference/INDEX.md` once. When a row matches the work, read that reference in full.
+Use the folder map in session context to find code. Run `node scripts/folder-map.mjs <dir>` for depth before `ls` or `find`.
 
 Large dumps are compressed (search, test logs, snaps). Scratch and dumps live in `.tmp/grunt/` (gitignored). After a write, recap the path; edit with an offset slice when you need lines.
 Fat dumps: `node scripts/grunt-job.mjs --job search|exec|slice|fetch|test` first; spawn grunt only when the dump needs judgment.

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-03
+
+### Added
+
+- `grunt map [dir]` / `node scripts/folder-map.mjs [dir]`: code-only folder map (folders only, git-tracked, gitignore applied). Package rows show name and full path; pass-through chains collapse; 12+ leaf dirs fold; 5k-token breadth-first budget with fair share; depth cap counts from package roots. Optional `.rulesync/grunt.map.jsonc`
+- Claude / Codex SessionStart hook `scripts/session-map.mjs` injects the folder map and logs `{rows, tokens}` per session
+- `/su` skill: short status update (done, next, blockers or on-track ETA)
+- Root rule: ask before destructive git; in a loop, skip it and edit code instead
+
+### Fixed
+
+- PreToolUse hooks no longer print top-level `decision: "allow"` / `"deny"`, which Claude rejected on every tool call; allow is empty stdout and deny is `block` plus `permissionDecision: "deny"`, so denies are enforced
+- Fat-tool gate no longer rewrites compound shell (`|`, `;`, `&&`, heredocs) into grunt-job, which never ran them; rewritten queries are single-quoted so backticks and `$` stay literal
+- Re-init replaces a grunt-owned SessionStart group instead of duplicating it
+
 ## [0.7.0] - 2026-09-30
 
 ### Added

package/README.md

@@ -85,6 +85,7 @@ Rulesync schema doctor is separate: `grunt:rulesync:doctor` (or SoT `rulesync:do
 - `doctor` → run `grunt:doctor` (`grunt doctor` / `node scripts/doctor.mjs` stay). Rulesync schema: `grunt:rulesync:doctor`
 - `setup` → run `grunt:setup` (`node scripts/setup.mjs`) — handheld speak / listen / google-workspace / browser. TTY walks each; flags for non-TTY keys/`--creds`
 - `upgrade` → same merge as init for an already-inited repo: copy owned trees/scripts, prune retired grunt-owned names, print reserved skill names
+- `map [dir]` → code-only folder map (`scripts/folder-map.mjs`); no package manager needed. See [Folder map](#folder-map)
 - `help`
 - `version`
 
@@ -144,7 +145,7 @@ Lightpanda-first session CLI: `node scripts/browser.mjs`. Zero MCP. Zero env kno
 
 Present under `.claude` / `.rulesync` / `.agents` / `.grok` (`rulesync -f skills` mirrors SSOT):
 
-- `ask` `auto` `browser` `clasp` `commit` `commit-and-push` (1-release alias → `commit-push`) `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `tmp` `write-plan`
+- `ask` `auto` `browser` `clasp` `commit` `commit-and-push` (1-release alias → `commit-push`) `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `su` `tmp` `write-plan`
 
 `/auto` (default) keeps going and asks on blockers. `/ask` finishes one step, recaps, then asks. `/auto` returns the session to auto.
 
@@ -176,6 +177,29 @@ Emit writes other-CLI trees from `.rulesync` for the **next** process of that CL
 - `sync-globals` / `purge-mcps`: dry-run default; `--apply` writes
 - Hosts: grok claude codex gemini antigravity
 
+### Folder map
+
+Claude and Codex get a folder map at SessionStart (`scripts/session-map.mjs`), so agents skip `ls`/`find` loops. Agents run `node scripts/folder-map.mjs <dir>` (same as `grunt map <dir>`) for depth. Grok and Antigravity get the `AGENTS.md` line only.
+
+- Folders only, never files. Source: `git ls-files --cached --others --exclude-standard`, so gitignored paths never show
+- A folder shows when it or a descendant holds a code file (`codeExt`) and no path segment is a dot dir or in `skip`
+- Package roots (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`) show `# name  repo/relative/path`
+- Pass-through single-child chains collapse (`a/b/c/`). 12+ plain leaf dirs under one parent fold into one row
+- Budget (chars ÷ 4): breadth-first per top-level subtree; on overflow, cheapest subtrees first with an equal share; cut dirs end in `…` (the header names the command). Depth cap counts from the nearest package root
+- Size per session: `.tmp/grunt/sessions/<sid>/map.json`
+
+Optional `.rulesync/grunt.map.jsonc` (missing or invalid → defaults):
+
+| key | default | |
+|---|---|---|
+| `budget` | `5000` | tokens |
+| `depthCap` | `6` | levels below a package root |
+| `foldAt` | `12` | leaf dirs before folding |
+| `codeExt` | `ts tsx js jsx mjs cjs py go rs sql vue svelte astro` | |
+| `skip` | `_gen gen generated dist build assets static public fixtures __fixtures__ __snapshots__ __mocks__ testdata vendor migrations locales i18n` | segment names |
+| `include` | `[]` | globs always shown (`*` one segment, `**` any) |
+| `exclude` | `[]` | globs never shown |
+
 ### Secrets (machine)
 
 Not git. Not `sync-globals`.

package/cli/grunt.mjs

@@ -12,6 +12,7 @@ import {
   isPackageManager,
   runScriptArgs,
 } from "../scripts/package-manager.mjs"
+import { mapCommand } from "../scripts/folder-map.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 
@@ -28,6 +29,7 @@ Commands:
   doctor        run grunt:doctor
   setup         run grunt:setup — handheld keys/OAuth (speak, listen, google-workspace, browser)
   upgrade       Re-init: copy owned files, prune retired grunt-owned names, print reserved skills
+  map [dir]     Code-only folder map (git-tracked, no files); dir for depth
   help          Show this help
   version       Print package version
 
@@ -231,6 +233,10 @@ async function dispatch(cmd, flags, interactive, pm) {
     runScript(pm, toGruntScriptName("setup"), flags.args)
     return
   }
+  if (cmd === "map") {
+    process.stdout.write(mapCommand(process.cwd(), flags.args[0] || ""))
+    return
+  }
   if (cmd === "upgrade") {
     await runInit(process.cwd(), {
       skipGlobals: flags.skipGlobals,

package/cli/grunt.test.ts

@@ -19,6 +19,7 @@ const spinner = vi.hoisted(() =>
   vi.fn(() => ({ start: vi.fn(), stop: vi.fn() })),
 );
 const bailIfCancel = vi.hoisted(() => vi.fn((v) => v));
+const mapCommand = vi.hoisted(() => vi.fn((_cwd: string, dir: string) => `map:${dir}\n`));
 
 vi.mock("./init.mjs", () => ({
   init,
@@ -29,6 +30,7 @@ vi.mock("./init.mjs", () => ({
   GRUNT_NPM_PREFIX: "grunt:",
 }));
 vi.mock("node:child_process", () => ({ execFileSync }));
+vi.mock("../scripts/folder-map.mjs", () => ({ mapCommand }));
 vi.mock("../scripts/package-manager.mjs", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../scripts/package-manager.mjs")>();
   actualDetect.fn = actual.detectPackageManager;
@@ -66,6 +68,7 @@ Commands:
   doctor        run grunt:doctor
   setup         run grunt:setup — handheld keys/OAuth (speak, listen, google-workspace, browser)
   upgrade       Re-init: copy owned files, prune retired grunt-owned names, print reserved skills
+  map [dir]     Code-only folder map (git-tracked, no files); dir for depth
   help          Show this help
   version       Print package version
 
@@ -321,6 +324,22 @@ describe("start", () => {
     expect(select).not.toHaveBeenCalled();
   });
 
+  it("map prints the folder map without a package manager", async () => {
+    process.argv = ["node", "grunt", "map"];
+    await start();
+    expect(mapCommand).toHaveBeenLastCalledWith(process.cwd(), "");
+    expect(chunks.join("")).toBe("map:\n");
+    expect(detectPackageManager).not.toHaveBeenCalled();
+    expect(execFileSync).not.toHaveBeenCalled();
+  });
+
+  it("map <dir> scopes the folder map", async () => {
+    process.argv = ["node", "grunt", "map", "packages/web"];
+    await start();
+    expect(mapCommand).toHaveBeenLastCalledWith(process.cwd(), "packages/web");
+    expect(chunks.join("")).toBe("map:packages/web\n");
+  });
+
   it("unknown writes usage and exitCode 1", async () => {
     process.argv = ["node", "grunt", "nope"];
     await start();

package/cli/init.mjs

@@ -53,6 +53,7 @@ export const PRODUCT_SCRIPTS = [
   "guarded-md.mjs",
   "guarded-roots.mjs",
   "emit-mcp-policy.mjs",
+  "folder-map.mjs",
   "gate-fat-tools.mjs",
   "hooks-union.mjs",
   "pipeline.mjs",
@@ -66,6 +67,7 @@ export const PRODUCT_SCRIPTS = [
   "purge-global-mcps.mjs",
   "scrub-spawn-prompt.mjs",
   "scrub-text-lib.mjs",
+  "session-map.mjs",
   "sync-global-settings.mjs",
   "browser.mjs",
   "speak.mjs",
@@ -112,6 +114,7 @@ export const RESERVED_SKILLS = [
   "listen",
   "pickup",
   "speak",
+  "su",
   "tmp",
   "write-plan",
 ]
@@ -143,7 +146,12 @@ export const LAUNCH_SCRIPTS = {
   gemini: "gemini --yolo",
   grok: "grok --yolo",
 }
-const OWNED_HOOK_FILES = ["scrub-spawn-prompt.mjs", "gate-fat-tools.mjs", "orchestrate-parent.js"]
+const OWNED_HOOK_FILES = [
+  "scrub-spawn-prompt.mjs",
+  "gate-fat-tools.mjs",
+  "orchestrate-parent.js",
+  "session-map.mjs",
+]
 
 function sortKeys(obj) {
   return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, obj[k]]))

package/cli/init.test.ts

@@ -82,6 +82,17 @@ const SRC_CLAUDE_SETTINGS = {
     deny: ["Agent(Explore)", "Agent(orchestrator)", "mcp__*"],
   },
   hooks: {
+    SessionStart: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/scripts/session-map.mjs"',
+            timeout: 5,
+          },
+        ],
+      },
+    ],
     PreToolUse: [
       {
         matcher: "spawn",
@@ -1728,6 +1739,24 @@ describe("init", () => {
     expect(settings.permissions.deny).toContain("mcp__*");
   });
 
+  it("re-init replaces a prior grunt session-map SessionStart group instead of duplicating it", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-rerun-map-");
+    fs.mkdirSync(path.join(dest, ".claude"), { recursive: true });
+    const mapGroup = {
+      hooks: [{ type: "command", command: 'node "$X/scripts/session-map.mjs"', timeout: 5 }],
+    };
+    fs.writeFileSync(
+      path.join(dest, ".claude", "settings.json"),
+      JSON.stringify({ permissions: {}, hooks: { SessionStart: [mapGroup] } }),
+    );
+    init(dest, { pkgRoot, execFileSync: vi.fn() });
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings.hooks.SessionStart).toEqual(SRC_CLAUDE_SETTINGS.hooks.SessionStart);
+  });
+
   it("omitted execFileSync uses default; self-skip never invokes it", () => {
     const pkgRoot = stubPkgRoot();
     init(pkgRoot, { pkgRoot });
@@ -1772,6 +1801,7 @@ describe("init", () => {
       "listen",
       "pickup",
       "speak",
+      "su",
       "tmp",
       "write-plan",
     ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",
@@ -31,6 +31,7 @@
     "scripts/guarded-md.mjs",
     "scripts/guarded-roots.mjs",
     "scripts/emit-mcp-policy.mjs",
+    "scripts/folder-map.mjs",
     "scripts/gate-fat-tools.mjs",
     "scripts/hooks-union.mjs",
     "scripts/pipeline.mjs",
@@ -44,6 +45,7 @@
     "scripts/purge-global-mcps.mjs",
     "scripts/scrub-spawn-prompt.mjs",
     "scripts/scrub-text-lib.mjs",
+    "scripts/session-map.mjs",
     "scripts/sync-global-settings.mjs",
     "scripts/browser.mjs",
     "scripts/speak.mjs",

package/scripts/folder-map.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * Code-only folder map for agents. Folders, never files.
+ *
+ * Source: git ls-files (tracked + untracked, gitignore applied). A folder is
+ * shown when it or a descendant holds a code file and no segment is skipped.
+ * Package roots (package.json, go.mod, Cargo.toml, pyproject.toml) carry
+ * `# name  path`. Single-child chains collapse; plain leaf dirs fold at foldAt.
+ *
+ *   node scripts/folder-map.mjs [dir]
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { stripJsonc } from "./emit-mcp-policy.mjs";
+
+export const DEFAULTS = Object.freeze({
+  budget: 5000,
+  depthCap: 6,
+  foldAt: 12,
+  codeExt: ["ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "go", "rs", "sql", "vue", "svelte", "astro"],
+  skip: [
+    "_gen", "gen", "generated", "dist", "build", "assets", "static", "public",
+    "fixtures", "__fixtures__", "__snapshots__", "__mocks__", "testdata",
+    "vendor", "migrations", "locales", "i18n",
+  ],
+  include: [],
+  exclude: [],
+});
+
+export const CONFIG_REL = ".rulesync/grunt.map.jsonc";
+const MANIFESTS = ["package.json", "go.mod", "Cargo.toml", "pyproject.toml"];
+
+/** DEFAULTS merged with known keys from CONFIG_REL; bad file → defaults + warn. */
+export function loadMapConfig(root, warn = (m) => process.stderr.write(`${m}\n`)) {
+  const abs = path.join(root, CONFIG_REL);
+  if (!fs.existsSync(abs)) return { ...DEFAULTS };
+  let raw;
+  try {
+    raw = JSON.parse(stripJsonc(fs.readFileSync(abs, "utf8")));
+  } catch (err) {
+    warn(`grunt map: ignoring ${CONFIG_REL}: ${err.message}`);
+    return { ...DEFAULTS };
+  }
+  const out = { ...DEFAULTS };
+  for (const [k, v] of Object.entries(raw || {})) {
+    if (!(k in DEFAULTS)) continue;
+    const ok = Array.isArray(DEFAULTS[k])
+      ? Array.isArray(v) && v.every((x) => typeof x === "string")
+      : Number.isFinite(v) && v > 0;
+    if (ok) out[k] = v;
+    else warn(`grunt map: ignoring ${CONFIG_REL} key ${k}`);
+  }
+  return out;
+}
+
+function git(args, cwd) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : null;
+}
+
+/** Repo top and cwd-relative prefix, or null outside git. */
+export function repoRoot(cwd) {
+  const top = git(["rev-parse", "--show-toplevel"], cwd);
+  return top ? top.trim() : null;
+}
+
+/** Tracked + untracked-unignored files, repo-relative, posix. */
+export function listFiles(root) {
+  const out = git(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], root);
+  if (out == null) return null;
+  return [...new Set(out.split("\0").filter(Boolean))];
+}
+
+/** `*` = one segment, `**` = any depth; matches the dir and everything under it. */
+function globRe(glob) {
+  const body = String(glob)
+    .replace(/\/+$/, "")
+    .split("**")
+    .map((part) => part.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*"))
+    .join(".*");
+  return new RegExp(`^${body}(/|$)`);
+}
+
+function packageName(root, dir, manifest) {
+  try {
+    const text = fs.readFileSync(path.join(root, dir, manifest), "utf8");
+    if (manifest === "package.json") return JSON.parse(text).name || "";
+    if (manifest === "go.mod") return (text.match(/^module\s+(\S+)/m) || [])[1] || "";
+    return (text.match(/^name\s*=\s*"([^"]+)"/m) || [])[1] || "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Raw tree from file paths. Node: { name, path, kids: Map, own, pkg }.
+ * `own` = holds a kept file directly. `pkg` is the package name ("" when
+ * unnamed) on package roots, else null.
+ */
+export function buildTree(root, files, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  const code = new RegExp(`\\.(${o.codeExt.join("|")})$`);
+  const skip = new Set(o.skip);
+  const include = o.include.map(globRe);
+  const exclude = o.exclude.map(globRe);
+  const manifests = new Map();
+  for (const f of files) {
+    const base = path.posix.basename(f);
+    if (MANIFESTS.includes(base) && !manifests.has(path.posix.dirname(f))) {
+      manifests.set(path.posix.dirname(f), base);
+    }
+  }
+  const top = { name: "", path: "", kids: new Map(), own: false, pkg: null };
+  for (const f of files) {
+    const dir = path.posix.dirname(f);
+    if (dir === ".") continue;
+    if (exclude.some((re) => re.test(dir))) continue;
+    const forced = include.some((re) => re.test(dir));
+    const segs = dir.split("/");
+    if (!forced) {
+      if (!code.test(f)) continue;
+      if (segs.some((s) => s.startsWith(".") || skip.has(s))) continue;
+    }
+    let node = top;
+    for (const s of segs) {
+      let next = node.kids.get(s);
+      if (!next) {
+        const p = node.path ? `${node.path}/${s}` : s;
+        const m = manifests.get(p);
+        next = { name: s, path: p, kids: new Map(), own: false, pkg: m ? packageName(root, p, m) : null };
+        node.kids.set(s, next);
+      }
+      node = next;
+    }
+    node.own = true;
+  }
+  return top;
+}
+
+/**
+ * Display tree: chains collapsed, leaf dirs folded.
+ * Row: { kind: "dir"|"fold", label, path, pkg, kids: Row[] }.
+ */
+export function displayRows(node, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  const names = [...node.kids.keys()].sort();
+  const leaves = names.filter((n) => {
+    const k = node.kids.get(n);
+    return k.kids.size === 0 && k.pkg == null;
+  });
+  const folded = leaves.length >= o.foldAt ? new Set(leaves) : new Set();
+  const rows = [];
+  if (folded.size) {
+    rows.push({ kind: "fold", label: leaves, path: node.path, pkg: null, kids: [] });
+  }
+  for (const n of names) {
+    if (folded.has(n)) continue;
+    let k = node.kids.get(n);
+    let label = n;
+    // Collapse pass-through dirs only; a dir with its own code stays a row.
+    while (k.kids.size === 1 && k.pkg == null && !k.own) {
+      const [only] = k.kids.values();
+      label = `${label}/${only.name}`;
+      k = only;
+    }
+    rows.push({ kind: "dir", label, path: k.path, pkg: k.pkg, kids: displayRows(k, o) });
+  }
+  return rows;
+}
+
+export function rowText(row, depth, { more = false, base = "" } = {}) {
+  const pad = "  ".repeat(depth);
+  if (row.kind === "fold") {
+    const shown = row.label.slice(0, 6).join(", ");
+    return `${pad}(${row.label.length} leaf dirs: ${shown}${row.label.length > 6 ? ", …" : ""})`;
+  }
+  const full = base ? `${base}/${row.path}` : row.path;
+  let line = `${pad}${row.label}/`;
+  if (row.pkg != null) line += row.pkg ? `  # ${row.pkg}  ${full}` : `  # ${full}`;
+  if (more) line += "  …";
+  return line;
+}
+
+export function tokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Pick rows under the budget, breadth-first by display level.
+ *
+ * Level 0 always shows. Each deeper level is one unit per top-level subtree:
+ * a subtree's rows at that level show together or not at all, so a parent's
+ * kids are never half-listed. Cost is exact in chars: a row with kids is
+ * charged its `…` marker until its kids land. When a level does
+ * not fit, cheapest subtrees take an equal share first; a subtree that misses
+ * its share stops expanding. Rows past depthCap (from the nearest package
+ * root) never expand.
+ */
+function selectRows(rows, o, base) {
+  const levels = [];
+  const visit = (list, depth, top, pkgDepth) => {
+    for (const row of list) {
+      const rel = row.pkg != null ? 0 : pkgDepth;
+      row.top = top ?? row;
+      row.capped = row.kids.length > 0 && rel >= o.depthCap;
+      row.shown = false;
+      (levels[depth] ||= []).push(row);
+      if (!row.capped) visit(row.kids, depth + 1, row.top, rel + 1);
+    }
+  };
+  visit(rows, 0, null, 1);
+  const cost = (row, depth, more) => rowText(row, depth, { more, base }).length + 1;
+  const pointer = (row, depth) => cost(row, depth, true) - cost(row, depth, false);
+  const charge = (row, depth) => cost(row, depth, row.kids.length > 0);
+
+  let used = 0;
+  for (const row of levels[0] || []) {
+    row.shown = true;
+    used += charge(row, 0);
+  }
+  const limit = o.budget * 4;
+  let active = new Set(levels[0] || []);
+  for (let d = 1; d < levels.length && active.size; d++) {
+    const units = new Map();
+    for (const row of levels[d]) {
+      if (!active.has(row.top)) continue;
+      const u = units.get(row.top) || { rows: [], parents: new Set(), cost: 0 };
+      u.rows.push(row);
+      u.cost += charge(row, d);
+      units.set(row.top, u);
+    }
+    for (const row of levels[d - 1]) {
+      const u = units.get(row.top);
+      if (u && row.shown && row.kids.length && !row.capped) u.cost -= pointer(row, d - 1);
+    }
+    const next = new Set();
+    let left = limit - used;
+    const order = [...units.entries()].sort((a, b) => a[1].cost - b[1].cost);
+    order.forEach(([top, u], i) => {
+      const share = left / (order.length - i);
+      if (u.cost > share) return;
+      for (const row of u.rows) row.shown = true;
+      left -= u.cost;
+      used += u.cost;
+      next.add(top);
+    });
+    active = next;
+  }
+  const lines = [];
+  const walk = (list, depth) => {
+    for (const row of list) {
+      if (!row.shown) continue;
+      const open = row.kids.length > 0 && row.kids.some((k) => k.shown);
+      lines.push(rowText(row, depth, { more: row.kids.length > 0 && !open, base }));
+      if (open) walk(row.kids, depth + 1);
+    }
+  };
+  walk(rows, 0);
+  return lines;
+}
+
+/**
+ * Map text for `root` (any dir inside a git repo), scoped to `dir` when set.
+ * Returns { text, rows, tokens } or null outside git.
+ */
+export function folderMap({ root, dir = "", ...opts } = {}) {
+  const top = repoRoot(root);
+  if (!top) return null;
+  const files = listFiles(top);
+  if (!files) return null;
+  const o = { ...loadMapConfig(top), ...opts };
+  const scope = dir ? path.relative(top, path.resolve(root, dir)).split(path.sep).join("/") : "";
+  const scoped = scope
+    ? files.filter((f) => f.startsWith(`${scope}/`)).map((f) => f.slice(scope.length + 1))
+    : files;
+  const tree = buildTree(scope ? path.join(top, scope) : top, scoped, o);
+  const lines = selectRows(displayRows(tree, o), o, scope);
+  const text = lines.length ? `${lines.join("\n")}\n` : "";
+  return { text, rows: lines.length, tokens: tokens(text) };
+}
+
+/** Text for `grunt map [dir]` / `node scripts/folder-map.mjs [dir]` run from `cwd`. */
+export function mapCommand(cwd, dir = "") {
+  const out = folderMap({ root: cwd, dir });
+  if (!out) return "grunt map: not a git repository\n";
+  return out.text || "grunt map: no code folders\n";
+}
+
+function main() {
+  process.stdout.write(mapCommand(process.cwd(), process.argv[2] || ""));
+  return 0;
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (invoked === thisFile || import.meta.url === pathToFileURL(invoked).href) {
+  process.exit(main());
+}

package/scripts/gate-fat-tools.mjs

@@ -190,9 +190,10 @@ export function pathIsDenied(p) {
   return n.split("/").some((seg) => DENY_PATH_SEGMENTS.has(seg));
 }
 
+/** Top-level "block" is the only legacy deny Claude/Codex validate; allow = empty stdout. */
 export function denyResponse(reason) {
   return {
-    decision: "deny",
+    decision: "block",
     reason,
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
@@ -341,8 +342,9 @@ export function rewriteScratchWrite(filePath, workspaceRoot) {
   return null;
 }
 
-function quoteQuery(q) {
-  return `"${String(q).replace(/"/g, '\\"')}"`;
+/** POSIX single-quote so `, $, and \ stay literal. */
+export function quoteQuery(q) {
+  return `'${String(q).replace(/'/g, "'\\''")}'`;
 }
 
 export function gruntJobCommand(workspaceRoot, args) {
@@ -702,13 +704,15 @@ export function processFatTools(data) {
       }
       return { type: "deny", reason: REASON_DENYLIST };
     }
-    if (BASH_DUMP_CMDS.test(cmd) && !alreadyRtk(cmd)) {
+    // grunt-job and rtk take one plain command; compound shell passes through.
+    const compound = SHELL_META.test(cmd);
+    if (BASH_DUMP_CMDS.test(cmd) && !alreadyRtk(cmd) && !compound) {
       const job = BASH_SEARCH.test(cmd) ? "search" : "exec";
       const q = cmd.replace(/^\s*(rtk\s+)?/, "").trim();
       next.command = gruntJobCommand(ws, `--job ${job} --query ${quoteQuery(q)}`);
       return { type: "rewrite", updatedInput: next };
     }
-    if (BASH_TREE.test(cmd) && !alreadyRtk(cmd)) {
+    if (BASH_TREE.test(cmd) && !alreadyRtk(cmd) && !compound) {
       next.command = `rtk ${cmd.trim()}`;
       return { type: "rewrite", updatedInput: next };
     }

package/scripts/hooks-union.mjs

@@ -6,6 +6,8 @@
  * Claude/Codex native event is UserPromptSubmit (mapped from SoT beforeSubmitPrompt).
  * Antigravity has neither beforeSubmitPrompt nor subagentStop.
  * Grok SessionStart stays empty on orchestrate-parent.json.
+ * Grunt SessionStart: session-map.mjs (folder map) when shipped, first in the group;
+ * Claude/Codex only (rulesync emits no Antigravity sessionStart).
  *
  * Consumer extras (if those scripts exist): SessionStart, check-behind,
  * validate+sim. Path deny from consumer `.rulesync/permissions.json`.
@@ -30,6 +32,9 @@ export const SCRUB =
   'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/scrub-spawn-prompt.mjs"';
 export const GATE_FAT =
   'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/gate-fat-tools.mjs"';
+export const MAP =
+  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs"';
+const MAP_NEEDLE = "session-map.mjs";
 
 export const AUTORUN_NEEDLES = [
   "daily-pull-check.mjs",
@@ -173,8 +178,14 @@ function desiredPre(root) {
   return pre;
 }
 
-function desiredSession(root) {
+function mapNeedles(root) {
+  return hasScript(root, MAP_NEEDLE) ? [MAP_NEEDLE] : [];
+}
+
+/** `map: false` for hosts rulesync emits no sessionStart for (Antigravity). */
+function desiredSession(root, { map = true } = {}) {
   const hooks = [];
+  if (map && hasScript(root, MAP_NEEDLE)) hooks.push(hookCmd(MAP, 5));
   if (hasScript(root, "daily-pull-check.mjs")) hooks.push(hookCmd(PULL));
   if (hasScript(root, "rtk-check.mjs")) hooks.push(hookCmd(RTK));
   if (hasScript(root, "daily-fleet-check.mjs")) hooks.push(hookCmd(FLEET));
@@ -264,7 +275,7 @@ function applyAgents(root) {
   const live = loadJson(abs);
   const rulesync = isPlainObject(live.rulesync) ? { ...live.rulesync } : {};
   rulesync.PreToolUse = upsertGroups(rulesync.PreToolUse, desiredPre(root));
-  const session = desiredSession(root);
+  const session = desiredSession(root, { map: false });
   if (session) {
     rulesync.SessionStart = [{ matcher: ".*", hooks: session[0].hooks }];
   }
@@ -320,12 +331,12 @@ export function checkUnion(opts = {}) {
     {
       id: "claude",
       path: ".claude/settings.json",
-      needles: [...GRUNT_NEEDLES, ...autorun, ...loadConsumerDeny(root)],
+      needles: [...GRUNT_NEEDLES, ...mapNeedles(root), ...autorun, ...loadConsumerDeny(root)],
     },
     {
       id: "codex",
       path: ".codex/hooks.json",
-      needles: [...GRUNT_NEEDLES, ...autorun],
+      needles: [...GRUNT_NEEDLES, ...mapNeedles(root), ...autorun],
     },
     {
       id: "agents",

package/scripts/scrub-spawn-prompt.mjs

@@ -170,7 +170,7 @@ function main() {
     const data = readJsonValue();
     const updated = processHookPayload(data);
     if (!updated) return 0;
-    if (updated.decision === "deny") {
+    if (updated.decision === "block") {
       process.stdout.write(JSON.stringify(updated));
       return 0;
     }

package/scripts/session-map.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook: inject the code-only folder map as additionalContext.
+ * Logs { rows, tokens } to .tmp/grunt/sessions/<sid>/map.json for tuning.
+ * Fail-open: any error, no git, or an empty map → empty stdout, exit 0.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { folderMap } from "./folder-map.mjs";
+
+export const HEADER =
+  "Folder map (code folders only; `…` = more inside, run `node scripts/folder-map.mjs <dir>`):";
+
+function readStdin() {
+  try {
+    const v = JSON.parse(fs.readFileSync(0, "utf8"));
+    return v && typeof v === "object" ? v : {};
+  } catch {
+    return {};
+  }
+}
+
+function workspaceRootOf(data) {
+  return (
+    process.env.GROK_WORKSPACE_ROOT ||
+    data.workspaceRoot ||
+    data.workspace_root ||
+    data.cwd ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.cwd()
+  );
+}
+
+function logSize(root, data, out) {
+  const sid = String(data.session_id || data.sessionId || "").replace(/[^\w-]/g, "");
+  if (!sid) return;
+  const dir = path.join(root, ".tmp", "grunt", "sessions", sid);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "map.json"), `${JSON.stringify({ rows: out.rows, tokens: out.tokens })}\n`);
+}
+
+function main() {
+  try {
+    const data = readStdin();
+    const root = workspaceRootOf(data);
+    const out = folderMap({ root });
+    if (!out || !out.text) return 0;
+    try {
+      logSize(root, data, out);
+    } catch {
+      // Logging is best-effort; the map still ships.
+    }
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: `${HEADER}\n${out.text}`,
+        },
+      }),
+    );
+  } catch {
+    // Fail open.
+  }
+  return 0;
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (invoked === thisFile || import.meta.url === pathToFileURL(invoked).href) {
+  process.exit(main());
+}