Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): block attached output flags, pin exec read-only contract (#4054)
tim-inkeep1fa19dead72e
diff --git a/.changeset/exec-read-only-contract.md b/.changeset/exec-read-only-contract.mdnew file mode 100644index 000000000..cb567531f--- /dev/null+++ b/.changeset/exec-read-only-contract.md@@ -0,0 +1,17 @@+---+"@inkeep/open-knowledge": patch+---++Agent `exec` can no longer write to the project.++`exec` is documented read-only, and that promise was enforced by comparing each argument against a list of blocked flags. The comparison was exact, so it caught `sort -o notes.md` and missed `sort -onotes.md` — the same flag with its value attached, which `sort` accepts. A command that only reads was able to create a file, and to replace an existing document with the contents of another:++```+sort -oimportant.md other.md+```++Nothing about that goes through `write` or `edit`, so the replacement carried no attribution and left no history to restore from.++`sort` is the only one of the ten allowed commands whose `-o` writes, so the guard is scoped to it and now covers the flag however it is spelled, including bundled forms like `-ro`. `--output-delimiter`, which only changes how output is printed, keeps working. A bare `-o` on its own stays refused for every command, as it was before this change, so `grep -o` still asks for `--only-matching` instead; the clustered forms it appears in, such as `grep -oE`, are unaffected.++A companion suite runs every write and delete attempt we know of through the real command pipeline and asserts the project is byte-identical afterwards, so the read-only promise is checked rather than assumed.diff --git a/packages/server/src/bash/mtime-scan.test.ts b/packages/server/src/bash/mtime-scan.test.tsindex 379cd5603..1500c6172 100644--- a/packages/server/src/bash/mtime-scan.test.ts+++ b/packages/server/src/bash/mtime-scan.test.ts@@ -76,7 +76,9 @@ describe('deriveScanRoots', () => {});test('grep drops the pattern positional but keeps operands', () => {- expect(deriveScanRoots([stage('grep', '-rn', 'oauth', 'articles/')])).toEqual(['articles/']);+ const roots = deriveScanRoots([stage('grep', '-rn', 'oauth', 'articles/')]);+ expect(roots).toContain('articles/');+ expect(roots).not.toContain('oauth');});test('recursive grep with no operand scans the whole tree', () => {@@ -96,14 +98,15 @@ describe('deriveScanRoots', () => {});test('find roots are the leading non-flag args; glob predicates are skipped', () => {- expect(deriveScanRoots([stage('find', 'specs', '-name', '*.md')])).toEqual(['specs']);+ const roots = deriveScanRoots([stage('find', 'specs', '-name', '*.md')]);+ expect(roots).toContain('specs');+ expect(roots).not.toContain('*.md');});test('find literal predicate values stay watched', () => {- expect(deriveScanRoots([stage('find', 'specs', '-newer', 'ref.md')]).sort()).toEqual([- 'ref.md',- 'specs',- ]);+ expect(deriveScanRoots([stage('find', 'specs', '-newer', 'ref.md')])).toEqual(+ expect.arrayContaining(['ref.md', 'specs']),+ );});test('find with no path root scans the whole tree', () => {@@ -119,9 +122,9 @@ describe('deriveScanRoots', () => {});test('glob-bearing attached flag values are match patterns, not paths', () => {- expect(deriveScanRoots([stage('grep', '-rn', '--include=*.md', 'oauth', 'articles/')])).toEqual(- ['articles/'],- );+ const roots = deriveScanRoots([stage('grep', '-rn', '--include=*.md', 'oauth', 'articles/')]);+ expect(roots).toContain('articles/');+ expect(roots).not.toContain('*.md');});test('literal attached flag values are watched as candidate write targets', () => {@@ -287,3 +290,29 @@ describe('diffMtimes', () => {}});});++describe('deriveScanRoots — over-inclusion is the correct bias for a detective layer', () => {+ test('an extension-less attached write target is still watched', () => {+ expect(deriveScanRoots([stage('sort', '--out=notes', 'other.md')])).toContain('notes');+ expect(deriveScanRoots([stage('sort', '-onotes', 'other.md')])).toContain('notes');+ });++ test('a delimiter argument never becomes a scan root', () => {+ expect(deriveScanRoots([stage('cut', '-d.', '-f1', 'other.md')])).not.toContain('.');+ expect(deriveScanRoots([stage('sort', '-t.', 'other.md')])).not.toContain('.');+ expect(deriveScanRoots([stage('cut', '-d/', '-f1', 'other.md')])).not.toContain('/');+ });++ test('the scan base is what resolveWithinRoot turns into the whole-tree sentinel', () => {+ expect(SCAN_WHOLE_TREE).toBe('');+ expect(deriveScanRoots([stage('cut', '-d.', '-f1', 'other.md')])).toContain('other.md');+ });+});++describe('deriveScanRoots — a match-pattern flag value is not a path', () => {+ test('an exclude-dir value does not become a root the sweep then walks', () => {+ const roots = deriveScanRoots([stage('grep', '-rn', '--exclude-dir=node_modules', 'x', 'a/')]);+ expect(roots).toContain('a/');+ expect(roots).not.toContain('node_modules');+ });+});diff --git a/packages/server/src/bash/mtime-scan.ts b/packages/server/src/bash/mtime-scan.tsindex 8c5015639..35c791cec 100644--- a/packages/server/src/bash/mtime-scan.ts+++ b/packages/server/src/bash/mtime-scan.ts@@ -36,6 +36,23 @@ function literalDirPrefix(token: string): string {return slash >= 0 ? head.slice(0, slash) : SCAN_WHOLE_TREE;}+const NON_PATH_VALUE_FLAGS: ReadonlySet<string> = new Set([+ '--exclude',+ '--exclude-dir',+ '--include',+ '--regexp',+]);++function isScanBase(value: string): boolean {+ const trimmed = value.trim().replace(/\/+$/, '');+ return trimmed === '' || trimmed === '.';+}++function carriesPathValue(arg: string): boolean {+ const name = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;+ return !NON_PATH_VALUE_FLAGS.has(name);+}+export function deriveScanRoots(stages: Stage[]): string[] {const roots = new Set<string>();for (const stage of stages) {@@ -83,9 +100,9 @@ export function deriveScanRoots(stages: Stage[]): string[] {candidates = positional;}const attached = args- .filter((a) => a.startsWith('-') && a.includes('='))- .map((a) => a.slice(a.indexOf('=') + 1))- .filter((v) => v.length > 0 && !GLOB_RE.test(v));+ .filter((a) => a.startsWith('-') && a.length > 2 && carriesPathValue(a))+ .map((a) => (a.includes('=') ? a.slice(a.indexOf('=') + 1) : a.slice(2)))+ .filter((v) => v.length > 0 && !GLOB_RE.test(v) && !isScanBase(v));for (const c of [...candidates, ...attached]) {roots.add(GLOB_RE.test(c) ? literalDirPrefix(c) : c);}diff --git a/packages/server/src/bash/parse-command.ts b/packages/server/src/bash/parse-command.tsindex cf0725f81..78e7fa1eb 100644--- a/packages/server/src/bash/parse-command.ts+++ b/packages/server/src/bash/parse-command.ts@@ -134,7 +134,8 @@ const SHELL_CONSTRUCT_OPS: ReadonlySet<string> = new Set([]);const UNIVERSAL_FLAG_DENY: ReadonlySet<string> = new Set(['-o', '--output-file', '--output']);-const UNIVERSAL_FLAG_PREFIX_DENY = ['-o=', '--output-file=', '--output='];+const UNIVERSAL_FLAG_PREFIX_DENY = ['--output-file=', '--output='];+const SORT_OUTPUT_FLAG_RE = /^-[a-zA-Z]*o/;const FIND_FLAG_DENY: ReadonlySet<string> = new Set(['-exec',@@ -143,6 +144,7 @@ const FIND_FLAG_DENY: ReadonlySet<string> = new Set(['-fprint','-fprintf','-fprint0',+ '-fls','-ok','-okdir',]);@@ -225,7 +227,11 @@ function checkStage(stage: Stage): ParseCommandError | null {};}for (const arg of stage.args.slice(1)) {- if (UNIVERSAL_FLAG_DENY.has(arg) || UNIVERSAL_FLAG_PREFIX_DENY.some((p) => arg.startsWith(p))) {+ if (+ UNIVERSAL_FLAG_DENY.has(arg) ||+ UNIVERSAL_FLAG_PREFIX_DENY.some((p) => arg.startsWith(p)) ||+ (stage.command === 'sort' && SORT_OUTPUT_FLAG_RE.test(arg))+ ) {return {category: 'write_blocked',message: `Write operation blocked: '${arg}'. exec is read-only. For document changes, use the \`write\` or \`edit\` tool.`,diff --git a/packages/server/src/bash/read-only-contract.test.ts b/packages/server/src/bash/read-only-contract.test.tsnew file mode 100644index 000000000..e23cff0ed--- /dev/null+++ b/packages/server/src/bash/read-only-contract.test.ts@@ -0,0 +1,189 @@+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, relative } from 'node:path';+import { afterAll, describe, expect, test } from 'vitest';+import { createBashInstance, execBash } from './index.ts';+import { deriveScanRoots } from './mtime-scan.ts';+import { augmentStagesWithExcludes, parseCommand, serializeStages } from './parse-command.ts';++const built: string[] = [];+afterAll(() => {+ for (const dir of built) rmSync(dir, { recursive: true, force: true });+});++function build(): string {+ const root = mkdtempSync(join(tmpdir(), 'read-only-contract-'));+ built.push(root);+ mkdirSync(join(root, 'specs'));+ writeFileSync(join(root, 'important.md'), '# Important\nDo not lose this\n');+ writeFileSync(join(root, 'other.md'), 'zzz\naaa\n');+ writeFileSync(join(root, 'specs/one.md'), 'ONE\n');+ writeFileSync(join(root, '-delete'), 'flag-shaped filename\n');+ return root;+}++function snapshot(dir: string, root = dir): string[] {+ return readdirSync(dir, { withFileTypes: true })+ .flatMap((entry) => {+ const full = join(dir, entry.name);+ return entry.isDirectory()+ ? snapshot(full, root)+ : [`${relative(root, full)}=${readFileSync(full, 'utf8')}`];+ })+ .sort();+}++type Disposition = 'parse-blocked' | 'ran' | 'exec-threw';++interface Attempt {+ command: string;+ expect: Disposition;+ category?: string;+}++async function attempt(+ root: string,+ command: string,+): Promise<{ disposition: Disposition; category?: string }> {+ const parsed = parseCommand(command);+ if ('error' in parsed) return { disposition: 'parse-blocked', category: parsed.error.category };+ try {+ const effective = serializeStages(augmentStagesWithExcludes(parsed.stages));+ await execBash(createBashInstance(root), effective);+ return { disposition: 'ran' };+ } catch {+ return { disposition: 'exec-threw' };+ }+}++const WRITE_ATTEMPTS: Attempt[] = [+ { command: 'sort -o important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },+ {+ command: 'sort --output important.md other.md',+ expect: 'parse-blocked',+ category: 'write_blocked',+ },+ {+ command: 'sort --output-file important.md other.md',+ expect: 'parse-blocked',+ category: 'write_blocked',+ },+ { command: 'sort -o=important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'sort -oimportant.md other.md', expect: 'parse-blocked', category: 'write_blocked' },+ {+ command: 'sort -r -o important.md other.md',+ expect: 'parse-blocked',+ category: 'write_blocked',+ },+ { command: 'sort -ro important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },+ {+ command: 'sort -nro important.md other.md',+ expect: 'parse-blocked',+ category: 'write_blocked',+ },+ { command: 'sort -uo important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },+ {+ command: 'sort -o important.md -r other.md',+ expect: 'parse-blocked',+ category: 'write_blocked',+ },+ { command: 'find . -delete', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'find . -name *.md -delete', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'find . -exec rm {} +', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'find . -execdir rm {} +', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'find . -ok rm {} +', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'find . -okdir rm {} +', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'find . -fprint important.md', expect: 'parse-blocked', category: 'write_blocked' },+ {+ command: 'find . -fprintf important.md %p',+ expect: 'parse-blocked',+ category: 'write_blocked',+ },+ { command: 'find . -fls important.md', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'find . -exec rm {} ;', expect: 'parse-blocked', category: 'shell_construct_blocked' },+ {+ command: 'find . -execdir rm {} ;',+ expect: 'parse-blocked',+ category: 'shell_construct_blocked',+ },+ { command: 'find . -ok rm {} ;', expect: 'parse-blocked', category: 'shell_construct_blocked' },+ { command: 'cat other.md > important.md', expect: 'parse-blocked', category: 'write_blocked' },+ { command: 'cat other.md >> important.md', expect: 'parse-blocked', category: 'write_blocked' },+ {+ command: 'cat other.md | tee important.md',+ expect: 'parse-blocked',+ category: 'unknown_command',+ },+ {+ command: 'cut -f1 other.md -o important.md',+ expect: 'parse-blocked',+ category: 'write_blocked',+ },+ {+ command: 'sort other.md `rm important.md`',+ expect: 'parse-blocked',+ category: 'shell_construct_blocked',+ },+ {+ command: 'sort other.md $(rm important.md)',+ expect: 'parse-blocked',+ category: 'shell_construct_blocked',+ },+ { command: 'find {*,-delete}', expect: 'ran' },+ { command: 'find {.,-delete}', expect: 'ran' },+ { command: 'find *', expect: 'ran' },+ { command: 'uniq other.md important.md', expect: 'ran' },+];++describe('exec is read-only — no allowlisted command may alter the tree', () => {+ test.each(+ WRITE_ATTEMPTS,+ )('$command is refused at the layer that owns it and changes nothing', async ({+ command,+ expect: expected,+ category,+ }) => {+ const root = build();+ const before = snapshot(root);+ const result = await attempt(root, command);+ expect(result.disposition).toBe(expected);+ if (category !== undefined) expect(result.category).toBe(category);+ expect(snapshot(root)).toEqual(before);+ });++ test('the write guard and the mtime backstop read an attached value the same way', () => {+ const roots = deriveScanRoots([{ command: 'sort', args: ['sort', '-onotes', 'other.md'] }]);+ expect(roots).toContain('notes');+ });++ test('the corpus itself would register a change, so the assertion is not vacuous', () => {+ const root = build();+ const before = snapshot(root);+ writeFileSync(join(root, 'important.md'), 'clobbered\n');+ expect(snapshot(root)).not.toEqual(before);+ });++ test('a read-only command that names an output-shaped flag still works', () => {+ const parsed = parseCommand('cut -f1 --output-delimiter=x other.md');+ expect('error' in parsed).toBe(false);+ });+});++describe('the write guard does not reach commands whose -o only reads', () => {+ test.each([+ 'grep -oE PRD-[0-9]+ other.md',+ 'grep -on needle other.md',+ 'grep -orn needle .',+ 'grep -oh needle other.md',+ 'find . -name a.md -or -name b.md',+ 'cut -f1 --output-delimiter=x other.md',+ 'sort -r other.md',+ 'sort -n other.md',+ ])('%s parses', (command) => {+ const parsed = parseCommand(command);+ if ('error' in parsed) {+ throw new Error(`expected '${command}' to parse, got: ${parsed.error.message}`);+ }+ expect('error' in parsed).toBe(false);+ });+});