Files
EJClaw/src/bash-command-classifier.ts
Codex 7f54c47e64 feat: let the owner skip review for change-free explanation answers
The owner may end a TASK_DONE answer with "리뷰 불필요: <reason>". The
host treats it as a request and honors it only when every guard holds:

- workspace content equals the task base (hasCodeChangesSinceRef), the
  working tree is clean, and HEAD did not move during the owner run
- the run used no file-mutating tool (Edit/Write/MultiEdit/NotebookEdit),
  no subagent (Agent/Task) and no state-changing or unknown MCP tool
- every Bash command is classified read-only by a conservative
  quote-aware classifier (src/bash-command-classifier.ts); anything
  unknown counts as mutating
- tool usage was reported and not truncated (agent-runner now reports
  tool names and Bash commands as toolUsage on its terminal output)
- the user did not ask for a review in this task

When honored the task completes as review_skipped with no reviewer or
finalize turn; the answer is delivered with the marker line removed and a
small "-# 검토 생략 …" note. Otherwise the marker is stripped and the
normal review runs. A bare "검토해줘"-style message right after a
review-skipped answer reopens that task for the reviewer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 20:36:53 +09:00

717 lines
18 KiB
TypeScript

/**
* Conservative read-only classifier for shell commands an agent ran.
*
* Used to decide whether an owner turn changed anything. A command counts as
* read-only only when every part of it is clearly read-only; anything unknown,
* unparsable, or ambiguous counts as mutating. False "mutating" results only
* cost a review; a false "read-only" would skip a needed one.
*/
export type BashCommandClass = 'read_only' | 'mutating';
type Token =
| { kind: 'word'; value: string }
| { kind: 'op'; value: string }
| { kind: 'redirect'; target: string | null };
/** Redirect targets that write nothing. */
const HARMLESS_REDIRECT_TARGETS = new Set(['/dev/null', '&1', '&2', '-']);
// Commands that never modify state, whatever their arguments.
const ALWAYS_READ_ONLY = new Set([
':',
'[',
'[[',
'basename',
'cat',
'cd',
'cksum',
'cmp',
'column',
'comm',
'cut',
'date',
'df',
'diff',
'dig',
'dirname',
'du',
'echo',
'egrep',
'expr',
'false',
'fgrep',
'file',
'fold',
'free',
'getent',
'grep',
'groups',
'head',
'hexdump',
'host',
'hostname',
'id',
'jq',
'less',
'ls',
'lsblk',
'lsof',
'md5sum',
'more',
'nl',
'nproc',
'nslookup',
'nvidia-smi',
'od',
'paste',
'pgrep',
'printf',
'ps',
'pwd',
'readlink',
'realpath',
'rev',
'rg',
'sha1sum',
'sha256sum',
'sha512sum',
'sleep',
'ss',
'stat',
'strings',
'tac',
'tail',
'test',
'tr',
'tree',
'true',
'type',
'uname',
'uniq',
'uptime',
'wc',
'whereis',
'which',
'whoami',
'xxd',
]);
// Prefixes that run the following command; classify what they run.
const COMMAND_WRAPPERS = new Set(['sudo', 'timeout', 'nice', 'time', 'env']);
const GIT_READ_ONLY_SUBCOMMANDS = new Set([
'blame',
'cat-file',
'describe',
'diff',
'grep',
'log',
'ls-files',
'ls-remote',
'ls-tree',
'merge-base',
'reflog',
'rev-list',
'rev-parse',
'shortlog',
'show',
'show-ref',
'status',
'whatchanged',
]);
const SYSTEMCTL_READ_ONLY = new Set([
'cat',
'is-active',
'is-enabled',
'is-failed',
'list-dependencies',
'list-timers',
'list-unit-files',
'list-units',
'show',
'status',
]);
const DOCKER_READ_ONLY = new Set([
'images',
'info',
'inspect',
'logs',
'port',
'ps',
'top',
'version',
]);
const SQL_WRITE_PATTERN =
/\b(?:insert|update|delete|drop|create|alter|replace|attach|detach|vacuum|reindex|begin|commit)\b|\.(?:import|restore|save|backup|output|once)\b|pragma\s+\w+\s*=/i;
/** Split a command line into words, operators and redirects (quote-aware). */
function tokenize(command: string): Token[] | null {
const tokens: Token[] = [];
let current = '';
let hasCurrent = false;
let pendingRedirect = false;
const pushWord = () => {
if (!hasCurrent) return;
if (pendingRedirect) {
tokens.push({ kind: 'redirect', target: current });
pendingRedirect = false;
} else {
tokens.push({ kind: 'word', value: current });
}
current = '';
hasCurrent = false;
};
const pushOp = (value: string) => {
pushWord();
if (pendingRedirect) return false;
tokens.push({ kind: 'op', value });
return true;
};
for (let i = 0; i < command.length; i += 1) {
const ch = command[i];
if (ch === "'") {
const end = command.indexOf("'", i + 1);
if (end < 0) return null;
current += command.slice(i + 1, end);
hasCurrent = true;
i = end;
continue;
}
if (ch === '"') {
let j = i + 1;
let value = '';
for (; j < command.length && command[j] !== '"'; j += 1) {
if (command[j] === '\\' && j + 1 < command.length) {
value += command[j + 1];
j += 1;
continue;
}
// Command substitution inside double quotes still runs a command.
if (command[j] === '`' || command.startsWith('$(', j)) return null;
value += command[j];
}
if (j >= command.length) return null;
current += value;
hasCurrent = true;
i = j;
continue;
}
if (ch === '\\' && i + 1 < command.length) {
if (command[i + 1] !== '\n') {
current += command[i + 1];
hasCurrent = true;
}
i += 1;
continue;
}
if (
ch === '`' ||
command.startsWith('$(', i) ||
command.startsWith('<(', i)
)
return null;
if (ch === ' ' || ch === '\t') {
pushWord();
continue;
}
if (ch === '\n' || ch === ';') {
if (!pushOp(';')) return null;
continue;
}
if (ch === '&') {
if (command[i + 1] === '&') {
if (!pushOp('&&')) return null;
i += 1;
continue;
}
if (command[i + 1] === '>') {
// &> / &>> redirect stdout+stderr.
pushWord();
pendingRedirect = true;
i += command[i + 2] === '>' ? 2 : 1;
continue;
}
// A trailing/background "&" — treat like a separator.
if (!pushOp(';')) return null;
continue;
}
if (ch === '|') {
if (command[i + 1] === '|') {
if (!pushOp('||')) return null;
i += 1;
continue;
}
if (!pushOp('|')) return null;
continue;
}
if (ch === '>') {
// An fd number glued to the operator ("2>") is part of the redirect.
if (/^\d+$/.test(current)) {
current = '';
hasCurrent = false;
}
pushWord();
pendingRedirect = true;
if (command[i + 1] === '>' || command[i + 1] === '|') i += 1;
if (command[i + 1] === '&') {
// 2>&1 style: the target is the fd that follows.
let j = i + 2;
let fd = '&';
while (j < command.length && /[\d-]/.test(command[j])) {
fd += command[j];
j += 1;
}
tokens.push({ kind: 'redirect', target: fd });
pendingRedirect = false;
i = j - 1;
}
continue;
}
if (ch === '<') {
// Input redirects and here-docs read only; the following word is input.
pushWord();
if (command[i + 1] === '<') return null; // here-doc bodies are opaque
continue;
}
if (ch === '(' || ch === ')' || ch === '{' || ch === '}') {
if (!hasCurrent) return null; // subshells / groups
current += ch;
continue;
}
current += ch;
hasCurrent = true;
}
pushWord();
if (pendingRedirect) tokens.push({ kind: 'redirect', target: null });
return tokens;
}
function hasFlag(args: string[], ...flags: string[]): boolean {
return args.some((arg) =>
flags.some(
(flag) =>
arg === flag ||
(flag.startsWith('--') && arg.startsWith(`${flag}=`)) ||
// Bundled short flags like "-iE" for "-i".
(flag.length === 2 &&
flag.startsWith('-') &&
/^-[a-zA-Z]+$/.test(arg) &&
arg.includes(flag[1])),
),
);
}
function positional(args: string[]): string[] {
return args.filter((arg) => !arg.startsWith('-'));
}
/** First non-option argument, skipping the values of options that take one. */
function firstPositional(
args: string[],
optionsWithValue: ReadonlySet<string>,
): string | undefined {
for (let i = 0; i < args.length; i += 1) {
const arg = args[i];
if (!arg.startsWith('-')) return arg;
if (optionsWithValue.has(arg)) i += 1;
}
return undefined;
}
const SYSTEMCTL_OPTIONS_WITH_VALUE = new Set([
'-p',
'--property',
'-n',
'--lines',
'-o',
'--output',
'-t',
'--type',
'-H',
'--host',
'-M',
'--machine',
'--state',
]);
const COMPOSE_OPTIONS_WITH_VALUE = new Set([
'-f',
'--file',
'-p',
'--project-name',
'--project-directory',
'--env-file',
'--profile',
]);
function isReadOnlyGit(args: string[]): boolean {
const rest = [...args];
// Global options before the subcommand.
while (rest.length > 0 && rest[0].startsWith('-')) {
const option = rest.shift()!;
if (option === '-c') return false; // config overrides can run hooks/aliases
if (option === '-C') {
rest.shift();
continue;
}
if (option !== '--no-pager' && option !== '-P') return false;
}
const [sub, ...subArgs] = rest;
if (!sub) return true;
if (GIT_READ_ONLY_SUBCOMMANDS.has(sub)) {
if (sub === 'diff' && hasFlag(subArgs, '--output')) return false;
return true;
}
if (sub === 'branch') {
if (
hasFlag(
subArgs,
'-d',
'-D',
'-m',
'-M',
'-c',
'-C',
'-f',
'-u',
'--delete',
'--move',
'--copy',
'--force',
'--set-upstream-to',
'--unset-upstream',
'--edit-description',
)
) {
return false;
}
// "git branch <name>" creates a branch; only listing forms are read-only.
const listing = hasFlag(subArgs, '--list', '-l', '--contains', '--merged');
return listing || positional(subArgs).length === 0;
}
if (sub === 'tag') {
return hasFlag(subArgs, '-l', '--list') || subArgs.length === 0;
}
if (sub === 'remote') {
return (
subArgs.length === 0 ||
(subArgs.length === 1 && subArgs[0] === '-v') ||
subArgs[0] === 'show' ||
subArgs[0] === 'get-url'
);
}
if (sub === 'stash') {
return subArgs[0] === 'list' || subArgs[0] === 'show';
}
if (sub === 'worktree') return subArgs[0] === 'list';
if (sub === 'config') {
return hasFlag(subArgs, '--get', '--get-all', '--list', '-l');
}
return false;
}
function isReadOnlySystemctl(args: string[]): boolean {
const sub = firstPositional(args, SYSTEMCTL_OPTIONS_WITH_VALUE);
return sub !== undefined && SYSTEMCTL_READ_ONLY.has(sub);
}
function isReadOnlyDocker(args: string[]): boolean {
const rest = [...args];
while (rest.length > 0 && rest[0].startsWith('-')) {
const option = rest.shift()!;
if (option === '--context' || option === '-c' || option === '-H') {
rest.shift();
} else if (!option.startsWith('--context=')) {
return false;
}
}
const [sub, ...subArgs] = rest;
if (!sub) return false;
if (DOCKER_READ_ONLY.has(sub)) return true;
if (sub === 'stats') return hasFlag(subArgs, '--no-stream');
if (sub === 'context') return subArgs[0] === 'ls' || subArgs[0] === 'show';
if (sub === 'compose') {
const composeSub = firstPositional(subArgs, COMPOSE_OPTIONS_WITH_VALUE);
return (
composeSub === 'ps' ||
composeSub === 'logs' ||
composeSub === 'config' ||
composeSub === 'ls'
);
}
return false;
}
function isReadOnlyCurl(args: string[]): boolean {
if (
hasFlag(
args,
'-d',
'-F',
'-T',
'-o',
'-O',
'-K',
'--data',
'--data-raw',
'--data-binary',
'--data-urlencode',
'--json',
'--form',
'--upload-file',
'--output',
'--remote-name',
'--remote-name-all',
'--config',
'--cookie-jar',
'-c',
)
) {
return false;
}
for (let i = 0; i < args.length; i += 1) {
const arg = args[i];
let method: string | undefined;
if (arg === '-X' || arg === '--request') method = args[i + 1];
else if (arg.startsWith('--request=')) method = arg.slice(10);
else if (/^-X[A-Za-z]+$/.test(arg)) method = arg.slice(2);
if (method !== undefined && !/^(?:GET|HEAD|OPTIONS)$/i.test(method)) {
return false;
}
}
return true;
}
function isReadOnlyWget(args: string[]): boolean {
if (hasFlag(args, '--post-data', '--post-file', '--method', '--body-data')) {
return false;
}
if (hasFlag(args, '--spider')) return true;
// Only "print to stdout" forms: -O - / -qO- / --output-document=-.
return args.some(
(arg, i) =>
((arg === '-O' || arg === '--output-document') && args[i + 1] === '-') ||
/^-[a-zA-Z]*O-$/.test(arg) ||
arg === '--output-document=-',
);
}
function isReadOnlySqlite(args: string[]): boolean {
const readonly =
hasFlag(args, '-readonly', '--readonly') ||
args.some((arg) => /^file:.*[?&]mode=ro\b/.test(arg));
if (!readonly) return false;
return !args.some((arg) => SQL_WRITE_PATTERN.test(arg));
}
function isReadOnlyFind(args: string[]): boolean {
return !args.some((arg) =>
/^-(?:delete|exec|execdir|ok|okdir|fprint|fprint0|fprintf|fls)$/.test(arg),
);
}
function isReadOnlySed(args: string[]): boolean {
if (hasFlag(args, '-i', '--in-place')) return false;
// The "w file" / "W file" commands write files.
return !args.some((arg) => /(?:^|[;/}\s])[wW]\s+\S/.test(arg));
}
function isReadOnlyGh(args: string[]): boolean {
const [group, action, ...rest] = args;
if (group === 'api') {
const apiArgs = [action, ...rest].filter((a): a is string => !!a);
if (
hasFlag(apiArgs, '-f', '-F', '--field', '--raw-field', '--input') ||
apiArgs.some((arg, i) => {
const method =
arg === '-X' || arg === '--method'
? apiArgs[i + 1]
: arg.startsWith('--method=')
? arg.slice(9)
: undefined;
return method !== undefined && !/^GET$/i.test(method);
})
) {
return false;
}
return true;
}
const readActions = new Set([
'list',
'view',
'status',
'diff',
'checks',
'watch',
]);
return (
['pr', 'run', 'issue', 'release', 'repo', 'workflow'].includes(group) &&
readActions.has(action)
);
}
function isReadOnlyKill(args: string[]): boolean {
// "kill -0 <pid>" only checks that the process exists; "kill -l" lists signals.
return args[0] === '-0' || args[0] === '-l';
}
/** Strip wrapper commands (sudo, timeout, env, ...) and variable assignments. */
function unwrapCommand(words: string[]): string[] {
let rest = words;
for (;;) {
while (rest.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(rest[0])) {
rest = rest.slice(1);
}
const [head, ...tail] = rest;
if (!head || !COMMAND_WRAPPERS.has(head)) return rest;
let next = tail;
if (head === 'sudo') {
while (next.length > 0 && next[0].startsWith('-')) {
const option = next[0];
next = next.slice(1);
if (option === '-u' || option === '-g') next = next.slice(1);
}
} else if (head === 'timeout') {
while (next.length > 0 && next[0].startsWith('-')) {
const option = next[0];
next = next.slice(1);
if (option === '-s' || option === '-k') next = next.slice(1);
}
next = next.slice(1); // duration
} else if (head === 'nice') {
if (next[0] === '-n') next = next.slice(2);
else if (next[0]?.startsWith('-')) next = next.slice(1);
} else if (head === 'env') {
while (next.length > 0 && next[0].startsWith('-')) next = next.slice(1);
} else if (head === 'time') {
while (next.length > 0 && next[0].startsWith('-')) next = next.slice(1);
}
if (next.length === 0) return head === 'env' ? ['env'] : [];
rest = next;
}
}
function isReadOnlySimpleCommand(words: string[]): boolean {
const unwrapped = unwrapCommand(words);
if (unwrapped.length === 0) return true; // bare assignment
const [rawCommand, ...args] = unwrapped;
const command = rawCommand.split('/').at(-1) ?? rawCommand;
if (ALWAYS_READ_ONLY.has(command)) return true;
switch (command) {
case 'env':
case 'printenv':
return args.length === 0 || command === 'printenv';
case 'export':
case 'unset':
case 'local':
case 'set':
return true; // shell-local state only
case 'git':
return isReadOnlyGit(args);
case 'systemctl':
return isReadOnlySystemctl(args);
case 'journalctl':
return !hasFlag(
args,
'--rotate',
'--flush',
'--sync',
'--vacuum-size',
'--vacuum-time',
'--vacuum-files',
);
case 'docker':
return isReadOnlyDocker(args);
case 'curl':
return isReadOnlyCurl(args);
case 'wget':
return isReadOnlyWget(args);
case 'sqlite3':
return isReadOnlySqlite(args);
case 'find':
return isReadOnlyFind(args);
case 'sed':
return isReadOnlySed(args);
case 'sort':
return !hasFlag(args, '-o', '--output');
case 'awk':
case 'gawk':
return !args.some((arg) =>
/\bsystem\s*\(|\bprint[^;]*>|getline/.test(arg),
);
case 'gh':
return isReadOnlyGh(args);
case 'kill':
return isReadOnlyKill(args);
case 'crontab':
return args.length === 1 && args[0] === '-l';
case 'tsc':
return hasFlag(args, '--noEmit');
case 'ip':
return (
args.length > 0 &&
['addr', 'a', 'route', 'r', 'link', 'l', 'neigh'].includes(args[0]) &&
(args.length === 1 || args[1] === 'show' || args[1] === 'list')
);
case 'ping':
return hasFlag(args, '-c');
case 'top':
return hasFlag(args, '-b');
default:
return false;
}
}
/**
* Classify one shell command line. Read-only only when every pipeline segment
* is a known read-only command and nothing is redirected into a file.
*/
export function classifyBashCommand(command: string): BashCommandClass {
const trimmed = command.trim();
if (!trimmed) return 'read_only';
const tokens = tokenize(trimmed);
if (!tokens) return 'mutating';
let words: string[] = [];
const segments: string[][] = [];
for (const token of tokens) {
if (token.kind === 'redirect') {
if (!token.target || !HARMLESS_REDIRECT_TARGETS.has(token.target)) {
return 'mutating';
}
continue;
}
if (token.kind === 'op') {
if (words.length > 0) segments.push(words);
words = [];
continue;
}
words.push(token.value);
}
if (words.length > 0) segments.push(words);
for (const segment of segments) {
if (segment[0] === 'xargs') {
// xargs runs the command that follows its own options.
let rest = segment.slice(1);
while (rest.length > 0 && rest[0].startsWith('-')) {
const option = rest[0];
rest = rest.slice(1);
if (/^-[IdEsLnP]$/.test(option)) rest = rest.slice(1);
}
if (rest.length === 0 || !isReadOnlySimpleCommand(rest)) {
return 'mutating';
}
continue;
}
if (!isReadOnlySimpleCommand(segment)) return 'mutating';
}
return 'read_only';
}