linux-token-efficiency

1import type { EngineInterface, Register } from "claude-code";
2import {
3  GIT_WORKTREE_CHECK_TIMEOUT_MS,
4  INPUT_CAP,
5  RTK_SPAWN_TIMEOUT_MS,
6  buildSteerDeny,
7  buildWebFetchDeny,
8  classifyBashCommand,
9  gitDirs,
10  hasGitOperand,
11  isAutoRewriteEnabled,
12  isSteerEnabled,
13  parseRtkRewrite,
14  resolveManagedRtk,
15  rtkCandidates,
16} from "./rtk-rewrite.mjs";
17
18// The two per-call PreToolUse command hooks (Bash router, WebFetch steer) as in-process tool.call hooks.
19// Fail-open everywhere: every helper turns a failure into "no rewrite", and each hook calls next once, outside any try.
20// Chain composition: another plugin's tool.call rewrite above this one hands its command in as e.command; this hook
21// classifies and rewrites that command, and whatever sits beneath receives this hook's result. rtk answers nothing for
22// a command it already rewrote (`rtk git status`), so an rtk prefix added above is left as it is.
23
24let linux: Promise<boolean> | undefined; // the platform never changes within a process: probed once
25const isLinux = ($: EngineInterface): Promise<boolean> => (linux ??= $.fs.exists("/proc/version").catch(() => false));
26
27// Where a path lands (every link followed), or undefined when it leads nowhere.
28const realPath = async ($: EngineInterface, path: string): Promise<string | undefined> => (await $.fs.stat(path, { resolve: true }).catch(() => undefined))?.realPath;
29
30// Whether cwd is inside a LINKED git worktree; false (rewrite applies) on any failure or outside a repo.
31const isLinkedWorktree = async ($: EngineInterface, cwd: string): Promise<boolean> => {
32  try {
33    const r = await $.process.run(["git", "rev-parse", "--git-dir", "--git-common-dir"], { cwd, timeoutMs: GIT_WORKTREE_CHECK_TIMEOUT_MS });
34    const dirs = gitDirs(r.exitCode, r.stdout, cwd);
35    if (dirs === null) return false;
36    const [gitDir, commonDir] = await Promise.all([realPath($, dirs[0]), realPath($, dirs[1])]);
37    return gitDir !== undefined && commonDir !== undefined && gitDir !== commonDir;
38  } catch {
39    return false;
40  }
41};
42
43// rtk's rewrite of `command`, or null. Preflight: ~/.local/bin/rtk is a regular file (links followed), the first `rtk`
44// a bare word resolves to in the Bash tool is that binary or this plugin's own bin/rtk bridge (a global rtk install owns
45// the rewrite otherwise: never double-wire), then `rtk hook claude` by absolute path with the PreToolUse JSON on stdin.
46const rtkRewrite = async ($: EngineInterface, command: string, toolInput: Record<string, unknown>): Promise<string | null> => {
47  try {
48    const managed = resolveManagedRtk({ HOME: await $.env.get("HOME") });
49    if (managed === null) return null;
50    const own = await $.fs.stat(managed, { resolve: true }).catch(() => undefined);
51    if (own?.kind !== "file" || own.realPath === undefined) return null; // not installed yet, dangling, or no regular file
52    let hit: string | undefined;
53    // shortcut: a candidate counts when it is a regular file; the fs API has no execute bit, so a non-executable `rtk`
54    // ahead on PATH ends the walk where bash would skip it (a no-op, or a failed spawn: fail-open either way).
55    for (const candidate of rtkCandidates(await $.env.get("PATH"), `${$.plugin.root}/bin`)) {
56      const st = await $.fs.stat(candidate, { resolve: true }).catch(() => undefined);
57      if (st?.kind === "file") {
58        hit = st.realPath;
59        break;
60      }
61    }
62    if (hit === undefined) return null;
63    if (hit !== own.realPath && hit !== (await realPath($, `${$.plugin.root}/bin/rtk`))) return null;
64    const cwd = await $.session.cwd(); // read inside the hook: a subagent's own directory
65    const stdin = JSON.stringify({ hook_event_name: "PreToolUse", tool_name: "Bash", cwd, tool_input: toolInput });
66    const r = await $.process.run([managed, "hook", "claude"], { cwd, stdin, timeoutMs: RTK_SPAWN_TIMEOUT_MS });
67    if (r.exitCode !== 0 || r.isStdoutTruncated) return null; // a signal reads as exit 1
68    const rewritten = parseRtkRewrite(r.stdout, command);
69    if (rewritten === null) return null;
70    // In a linked worktree the harness's isolation guard refuses `rtk git …` (it cannot see through the wrapper):
71    // withhold a rewrite that names git there so the original `git …` runs under the guard's own git-aware check.
72    if (hasGitOperand(rewritten) && (await isLinkedWorktree($, cwd))) return null;
73    return rewritten;
74  } catch {
75    return null;
76  }
77};
78
79export const register: Register = (on, options) => {
80  const steerOn = isSteerEnabled(options.steer_enabled);
81  const rewriteOn = isAutoRewriteEnabled(options.auto_rewrite);
82
83  if (steerOn || rewriteOn) {
84    on("tool.call", { tool: "Bash" }, async ($, e, next) => {
85      const { tool: _tool, tool_use_id: _id, consent: _consent, agentId: _agent, requestMeta: _meta, ...toolInput } = e;
86      const command = e.command;
87      if (typeof command !== "string" || command === "" || command.length > INPUT_CAP || !(await isLinux($))) return next(e);
88      // Never steer a backgrounded call: the ctx_* tools cannot background, so a deny would strand the model.
89      if (steerOn && String(e.run_in_background) !== "true") {
90        const deny = buildSteerDeny(classifyBashCommand(command))?.hookSpecificOutput?.permissionDecisionReason;
91        if (deny !== undefined) return { deny };
92      }
93      const rewritten = rewriteOn ? await rtkRewrite($, command, toolInput) : null;
94      return next(rewritten === null ? e : { ...e, command: rewritten });
95    });
96  }
97
98  if (steerOn) {
99    on("tool.call", { tool: "WebFetch" }, async ($, e, next) => {
100      const url = e.url;
101      if (typeof url !== "string" || url === "" || !(await isLinux($))) return next(e);
102      const deny = buildWebFetchDeny(url).hookSpecificOutput?.permissionDecisionReason;
103      return deny === undefined ? next(e) : { deny };
104    });
105  }
106};
107

1// hooks/rtk-rewrite.mjs — linux-token-efficiency plugin: the pure policy behind the
2// mods hooks module's PreToolUse-equivalent `tool.call` hooks (hooks/register.ts).
3// Zero-dep, no `node:` import and never the mods `$`: the engine refuses passing `$`
4// into an imported function, and a mods module is not known to load node built-ins.
5// Every file system, environment and process access lives in register.ts.
6//
7// The Bash hook is a router with two exits, in this order:
8//
9// 1. STEER (context-mode): a conservatively classified read-only gather command —
10//    a bare curl GET, a >=3-segment chain of text tools, or a >=3-stage text
11//    pipeline — is denied with a copy-ready replacement call on context-mode's
12//    ctx_fetch_and_index / ctx_batch_execute / ctx_execute. Gated by steer_enabled.
13// 2. REWRITE (rtk): everything else is piped into the managed binary's own
14//    `rtk hook claude` protocol (spawned by ABSOLUTE path) and rtk's rewritten command
15//    replaces `command`. The command keeps rtk's bare `rtk …` word — no path
16//    rewriting, no PATH prefix. Gated by auto_rewrite.
17//
18// The split is the deliberate rtk/context-mode balance: git/gh and other side-effect
19// or single commands STAY in Bash under rtk compression (the measured winner for that
20// class); only the read-only gather class rtk does not rewrite is steered into the
21// context-mode sandbox, where output is indexed instead of entering context.
22
23/** Same cap the command hook applied to its stdin: a larger command is left alone. */
24export const INPUT_CAP = 1024 * 1024;
25/** `rtk hook claude` round-trip bound; a slower rtk means no rewrite. */
26export const RTK_SPAWN_TIMEOUT_MS = 5000;
27/** One `git rev-parse --git-dir --git-common-dir` call. */
28export const GIT_WORKTREE_CHECK_TIMEOUT_MS = 2000;
29
30/**
31 * auto_rewrite toggle, fail-open per .claude/rules/plugin-userconfig.md: unset, empty,
32 * true/"true" and an uninterpolated `${user_config.auto_rewrite}` placeholder all count
33 * as enabled; only false / the literal string "false" disables.
34 * @param {unknown} value
35 * @returns {boolean}
36 */
37export function isAutoRewriteEnabled(value) {
38  return String(value ?? "").trim() !== "false";
39}
40
41/**
42 * steer_enabled toggle, same fail-open semantics as auto_rewrite: only false / the
43 * literal string "false" disables the context-mode steering.
44 * @param {unknown} value
45 * @returns {boolean}
46 */
47export function isSteerEnabled(value) {
48  return String(value ?? "").trim() !== "false";
49}
50// Full MCP tool-name prefix for the plugin-bundled context-mode server. Deny reasons
51// spell it out once so the model can call the tool without guessing the namespace.
52const CTX_TOOL_PREFIX = "mcp__plugin_linux-token-efficiency_context-mode__";
53
54// Heads that make a pipe stage / chain segment steerable: read-only text/gather tools
55// whose raw output floods context and that rtk has no rewrite for. Anything not listed
56// (git, gh, rm, sed, xargs, echo, unknown binaries, …) keeps the command in Bash —
57// conservative by construction: an unknown head means "do not steer".
58const READ_ONLY_HEADS = new Set([
59  "grep",
60  "egrep",
61  "fgrep",
62  "rg",
63  "find",
64  "cat",
65  "head",
66  "tail",
67  "awk",
68  "sort",
69  "uniq",
70  "wc",
71  "cut",
72  "tr",
73  "jq",
74  "ls",
75  "stat",
76  "du",
77  "df",
78  "diff",
79  "comm",
80  "column",
81  "nl",
82  "file",
83  "basename",
84  "dirname",
85  "realpath",
86]);
87
88/**
89 * Split a command into top-level segments (on `&&`, `||`, `;`) and each segment into
90 * pipe stages, honoring single/double quotes and backslash escapes. Returns null —
91 * meaning "too complex, do not steer" — on anything beyond that flat shape: command
92 * substitution, subshells/brace groups, redirects/heredocs, background `&`, comments,
93 * or newlines. Null is always safe: the command simply stays in Bash.
94 * @param {string} command
95 * @returns {{text: string, stages: string[]}[]|null}
96 */
97export function splitTopLevel(command) {
98  /** @type {{text: string, stages: string[]}[]} */
99  const segments = [];
100  /** @type {string[]} */
101  let stages = [];
102  let stage = "";
103  let text = "";
104  let inSingle = false;
105  let inDouble = false;
106  const endStage = () => {
107    const t = stage.trim();
108    if (t === "") return false;
109    stages.push(t);
110    stage = "";
111    return true;
112  };
113  const endSegment = () => {
114    if (!endStage()) return false;
115    const t = text.trim();
116    if (t === "") return false;
117    segments.push({ text: t, stages });
118    stages = [];
119    text = "";
120    return true;
121  };
122  for (let i = 0; i < command.length; i++) {
123    const ch = command[i];
124    if (inSingle) {
125      if (ch === "'") inSingle = false;
126      stage += ch;
127      text += ch;
128      continue;
129    }
130    if (ch === "\\") {
131      const next = command[i + 1] ?? "";
132      stage += ch + next;
133      text += ch + next;
134      i++;
135      continue;
136    }
137    if (inDouble) {
138      if (ch === '"') inDouble = false;
139      else if (ch === "`" || (ch === "$" && command[i + 1] === "(")) return null;
140      stage += ch;
141      text += ch;
142      continue;
143    }
144    if (ch === "'") inSingle = true;
145    else if (ch === '"') inDouble = true;
146    else if (ch === "`" || ch === ">" || ch === "<" || ch === "(" || ch === ")" || ch === "#" || ch === "\n") return null;
147    else if (ch === "$" && command[i + 1] === "(") return null;
148    else if ((ch === "{" || ch === "}") && command[i - 1] !== "$" && !/[{,]/.test(command[i - 1] ?? "")) return null;
149    else if (ch === "&") {
150      if (command[i + 1] !== "&") return null; // background job / fd duplication
151      if (!endSegment()) return null;
152      i++;
153      continue;
154    } else if (ch === ";") {
155      if (!endSegment()) return null;
156      continue;
157    } else if (ch === "|") {
158      if (command[i + 1] === "|") {
159        if (!endSegment()) return null;
160        i++;
161      } else if (!endStage()) {
162        return null;
163      } else {
164        text += ch;
165      }
166      continue;
167    }
168    stage += ch;
169    text += ch;
170  }
171  if (inSingle || inDouble) return null;
172  if (stage.trim() !== "" || stages.length > 0) {
173    if (!endSegment()) return null;
174  }
175  return segments.length > 0 ? segments : null;
176}
177
178/**
179 * The executable word of one pipe stage, skipping leading VAR=VALUE assignments and a
180 * leading `command`. Empty string when none is found.
181 * @param {string} stage
182 * @returns {string}
183 */
184export function commandHead(stage) {
185  for (const token of stage.trim().split(/\s+/)) {
186    if (token === "command") continue;
187    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) continue;
188    return token;
189  }
190  return "";
191}
192
193/**
194 * True when a curl token indicates an upload, an explicit method, or a file
195 * write — those fetches legitimately stay in Bash. Combined short flags (-sSo) are
196 * caught by the character test.
197 * @param {string} token
198 * @returns {boolean}
199 */
200function isFetchWriteFlag(token) {
201  if (/^--(data|form|upload-file|output|remote-name|method|post-data|post-file|json|request)/.test(token)) return true;
202  return /^-[A-Za-z]+$/.test(token) && /[odOFTXD]/.test(token);
203}
204
205/**
206 * Conservative steer classifier. Steers ONLY three shapes, everything else stays:
207 * - fetch: a single bare curl GET of an http(s) URL -> ctx_fetch_and_index (wget
208 *   stays: its default is a file download, a side effect the steer cannot replicate)
209 * - batch: >=3 chained segments whose every stage head is a read-only text tool -> ctx_batch_execute
210 * - pipeline: a >=3-stage all-read-only pipe (<=2 segments) -> ctx_execute
211 * @param {string} command
212 * @returns {{kind: "stay"}|{kind: "fetch", url: string}|{kind: "batch", commands: string[]}|{kind: "pipeline", command: string}}
213 */
214export function classifyBashCommand(command) {
215  /** @type {{kind: "stay"}} */
216  const stay = { kind: "stay" };
217  const segments = splitTopLevel(command);
218  if (!segments) return stay;
219  const heads = segments.map((seg) => seg.stages.map(commandHead));
220  if (heads.some((seg) => seg.some((h) => h === ""))) return stay;
221  if (segments.length === 1 && segments[0].stages.length === 1) {
222    // curl only: a bare curl prints the response to stdout (pure context flood), while
223    // wget's default is a file download — a side effect ctx_fetch_and_index cannot
224    // replicate, so wget always stays in Bash.
225    const head = heads[0][0];
226    if (head === "curl") {
227      const tokens = segments[0].stages[0].split(/\s+/).map((t) => t.replace(/^["']|["']$/g, ""));
228      const url = tokens.find((t) => /^https?:\/\//.test(t));
229      if (url !== undefined && !tokens.some(isFetchWriteFlag)) return { kind: "fetch", url };
230      return stay;
231    }
232  }
233  if (!heads.every((seg) => seg.every((h) => READ_ONLY_HEADS.has(h)))) return stay;
234  if (segments.length >= 3) return { kind: "batch", commands: segments.map((s) => s.text) };
235  if (segments.some((s) => s.stages.length >= 3)) return { kind: "pipeline", command: command.trim() };
236  return stay;
237}
238
239/**
240 * The PreToolUse deny result steering a classified command to context-mode, or null
241 * for kind "stay". The reason is a complete, copy-ready replacement call plus an
242 * explicit "do not retry via Bash" so the model cannot loop on the denial.
243 * @param {ReturnType<typeof classifyBashCommand>} classification
244 * @returns {HookResult|null}
245 */
246export function buildSteerDeny(classification) {
247  let reason;
248  if (classification.kind === "fetch") {
249    let source = "web";
250    try {
251      source = new URL(classification.url).hostname || "web";
252    } catch {
253      /* keep the fallback label */
254    }
255    reason =
256      `context-mode steer: do not fetch URLs through Bash and do not retry this command. ` +
257      `Call ctx_fetch_and_index (${CTX_TOOL_PREFIX}ctx_fetch_and_index) with ` +
258      `{"url": ${JSON.stringify(classification.url)}, "source": ${JSON.stringify(source)}}, ` +
259      `then ctx_search(queries: [...]) to read the indexed content — the raw response never enters the context window.`;
260  } else if (classification.kind === "batch") {
261    const commands = classification.commands.map((c, i) => ({ label: `${i + 1}: ${commandHead(c) || "cmd"}`, command: c }));
262    reason =
263      `context-mode steer: this read-only multi-command gather floods the context window via Bash. ` +
264      `Do not retry it as a Bash call. Call ctx_batch_execute (${CTX_TOOL_PREFIX}ctx_batch_execute) with ` +
265      `commands: ${JSON.stringify(commands)} and queries for what you actually need — ` +
266      `output is indexed and only search results enter context.`;
267  } else if (classification.kind === "pipeline") {
268    reason =
269      `context-mode steer: this read-only pipeline floods the context window via Bash. ` +
270      `Do not retry it as a Bash call. Call ctx_execute (${CTX_TOOL_PREFIX}ctx_execute) with ` +
271      `{"language": "shell", "code": ${JSON.stringify(classification.command)}} — only stdout you print enters context.`;
272  } else {
273    return null;
274  }
275  reason += " (Set the linux-token-efficiency plugin option steer_enabled to false to disable this routing.)";
276  return {
277    hookSpecificOutput: {
278      hookEventName: "PreToolUse",
279      permissionDecision: "deny",
280      permissionDecisionReason: reason,
281    },
282  };
283}
284
285/**
286 * True when a rtk-rewritten command still carries a bare `git` token among its
287 * operands (e.g. `rtk git status`) -- the exact shape the harness's own
288 * worktree-isolation guard refuses outright in a linked worktree, because it cannot
289 * verify cwd/root through the opaque rtk wrapper the way it can for a direct
290 * `git ...` invocation. Whitespace-token match only, matching this file's other
291 * simple lexing (commandHead) rather than a full shell parse.
292 * @param {string} command
293 * @returns {boolean}
294 */
295export function hasGitOperand(command) {
296  return command.split(/\s+/).includes("git");
297}
298
299/**
300 * The git dir and the common dir from one `git rev-parse --git-dir --git-common-dir`
301 * run in `cwd`, each made absolute against `cwd` (git prints a relative `.git` from
302 * a worktree root). Null unless git exited 0 with exactly those two lines. register.ts
303 * resolves both through the file system: a linked worktree is a checkout whose
304 * resolved git dir differs from its resolved common dir — the same `-ef` comparison
305 * coding-toolbox's fresh-pr/finish-pr git-context blocks use in shell form.
306 * @param {number} exitCode
307 * @param {string} stdout
308 * @param {string} cwd absolute
309 * @returns {[string, string]|null}
310 */
311export function gitDirs(exitCode, stdout, cwd) {
312  if (exitCode !== 0) return null;
313  const lines = stdout.trim().split("\n");
314  if (lines.length !== 2 || lines.some((l) => l.trim() === "")) return null;
315  const abs = (/** @type {string} */ p) => (p.startsWith("/") ? p : `${cwd.replace(/\/+$/, "")}/${p}`);
316  return [abs(lines[0].trim()), abs(lines[1].trim())];
317}
318
319/**
320 * A string is usable as a home directory only when non-empty and free of an
321 * uninterpolated `${` placeholder.
322 * @param {string|undefined} value
323 * @returns {boolean}
324 */
325function usableHome(value) {
326  return typeof value === "string" && value.trim() !== "" && !value.includes("${");
327}
328
329/**
330 * The plugin-managed rtk install path (${HOME}/.local/bin/rtk), or null when HOME is
331 * unusable (unset, blank, or a `${`-bearing placeholder). Never returns a `${`-bearing
332 * path. shortcut: no os.homedir() passwd fallback (a mods module has no such API), so
333 * an unset HOME means no rewrite; upgrade if a host without HOME ever matters.
334 * @param {{HOME?: string}} env
335 * @returns {string|null}
336 */
337export function resolveManagedRtk(env) {
338  if (!usableHome(env.HOME)) return null;
339  return `${String(env.HOME).trim()}/.local/bin/rtk`;
340}
341
342/**
343 * Where a bare `rtk` can resolve in the Bash tool, in lookup order: `<dir>/rtk` for
344 * every non-empty PATH entry, then this plugin's own `bin/rtk` PATH bridge — Claude
345 * Code appends each enabled plugin's `bin/` to the Bash PATH, not to its own.
346 * @param {string|undefined} pathEnv
347 * @param {string} pluginBin absolute `<plugin root>/bin`
348 * @returns {string[]}
349 */
350export function rtkCandidates(pathEnv, pluginBin) {
351  return [...(pathEnv || "").split(":").filter((d) => d !== ""), pluginBin].map((d) => `${d.replace(/\/+$/, "")}/rtk`);
352}
353
354/**
355 * rtk's rewritten command from `rtk hook claude` stdout, or null when there is none to
356 * apply: empty output (no rewrite for this command), unparseable output, any shape
357 * other than a plain `hookSpecificOutput.updatedInput.command` string (e.g. rtk's own
358 * permissionDecision — never forwarded), or a command identical to the original.
359 * @param {string} stdout
360 * @param {string} original
361 * @returns {string|null}
362 */
363export function parseRtkRewrite(stdout, original) {
364  const out = stdout.trim();
365  if (out === "") return null;
366  /** @type {any} */
367  let parsed;
368  try {
369    parsed = JSON.parse(out);
370  } catch {
371    return null;
372  }
373  const rewritten = parsed?.hookSpecificOutput?.updatedInput?.command;
374  if (typeof rewritten !== "string" || rewritten === original) return null;
375  return rewritten;
376}
377
378/**
379 * The deny steering one WebFetch URL to ctx_fetch_and_index. The reason is a complete
380 * replacement call plus an explicit "do not retry WebFetch" so the model cannot loop on
381 * the denial. Every URL steers: WebFetch has no comparable non-context-mode equivalent.
382 * @param {string} url
383 * @returns {HookResult}
384 */
385export function buildWebFetchDeny(url) {
386  let source = "web";
387  try {
388    source = new URL(url).hostname || "web";
389  } catch {
390    /* keep the fallback label */
391  }
392  const reason =
393    `context-mode steer: WebFetch is routed through the context-mode MCP server. ` +
394    `Do not retry WebFetch for this URL. Call ctx_fetch_and_index (${CTX_TOOL_PREFIX}ctx_fetch_and_index) with ` +
395    `{"url": ${JSON.stringify(url)}, "source": ${JSON.stringify(source)}}, then ctx_search(queries: [...]) ` +
396    `to read the indexed content — the raw page never enters the context window. ` +
397    `(Set the linux-token-efficiency plugin option steer_enabled to false to disable this routing.)`;
398  return {
399    hookSpecificOutput: {
400      hookEventName: "PreToolUse",
401      permissionDecision: "deny",
402      permissionDecisionReason: reason,
403    },
404  };
405}
406