The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { afterEach, describe, expect, it, vi } from 'vitest'
import { existsSync, lstatSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { hooks } from '../codex/hookContract.js'
import { installHookSettings } from './hookSettings.js'
import { CODEX_SHELL_GUARD } from '../../lib/agentShellGuard.js'
import { recordReviewed, reviewHash, reviewRecords, sessionHookHash, sessionReviewRecords, withoutReviewRecords, withReviewRecords } from './hookReview.js'
const record = hooks.settings.reviewed!
const roots: string[] = []
afterEach(() => {
vi.restoreAllMocks()
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
})
const home = (): string => {
const root = realpathSync(mkdtempSync(join(tmpdir(), 'hook-review-')))
roots.push(root)
return root
}
// What `codex app-server` `hooks/list` of codex-cli 0.162.0 reported as `currentHash` for a hooks.json with
// these two blocks (2026-10-09). Harness's hash must be Codex's, or Codex asks about the hooks anyway.
const COMMAND = "'/opt/harness/runtime/node' '/home/person/.harness/cli/hook/notify.mjs' 18473 codex"
const CODEX_0_162 = {
session_start: 'sha256:7d719f8e2849620d0d2d81085877e79793c61d8b46ee15cc6251d2e0c69a1b41',
user_prompt_submit: 'sha256:2aeba9ad1676fa3124e519bbcbb7602380bae087ba5345ce604bb12f5bb76199',
}
describe('Harness’s own Codex hooks, recorded as reviewed', () => {
it('hashes a hook exactly as codex-cli 0.162.0 does', () => {
expect(reviewHash(record, 'SessionStart', 'startup|resume|clear|compact', { command: COMMAND, timeout: 5 })).toBe(CODEX_0_162.session_start)
// Codex ignores a UserPromptSubmit matcher, so it is not part of the hash either.
expect(reviewHash(record, 'UserPromptSubmit', 'anything', { command: COMMAND, timeout: 5 })).toBe(CODEX_0_162.user_prompt_submit)
expect(reviewHash(record, 'UserPromptSubmit', undefined, { command: COMMAND })).not.toBe(CODEX_0_162.user_prompt_submit)
expect(reviewHash(record, 'UserPromptSubmit', undefined, { command: COMMAND })).toBe(reviewHash(record, 'UserPromptSubmit', undefined, { command: COMMAND, timeout: 600 }))
})
it('keys only Harness’s blocks, at their place in the file, past the person’s own', () => {
const settings = { hooks: {
SessionStart: [{ matcher: 'mine', hooks: [{ type: 'command', command: 'echo theirs' }] }, { matcher: 'startup|resume|clear|compact', hooks: [{ type: 'command', command: COMMAND, timeout: 5 }] }],
UserPromptSubmit: [{ hooks: [{ type: 'command', command: COMMAND, timeout: 5 }] }],
Stop: [{ hooks: [{ type: 'command', command: COMMAND }] }],
} }
expect([...reviewRecords(record, '/home/person/.codex/hooks.json', settings)]).toEqual([
['/home/person/.codex/hooks.json:session_start:1:0', CODEX_0_162.session_start],
['/home/person/.codex/hooks.json:user_prompt_submit:0:0', CODEX_0_162.user_prompt_submit],
])
})
it('installs the hooks and records them, so Codex runs them without asking; a second start changes nothing', async () => {
const codexHome = home()
vi.spyOn(console, 'log').mockImplementation(() => {})
await installHookSettings('codex', hooks.settings, 19473, codexHome)
const installed = JSON.parse(readFileSync(join(codexHome, 'hooks.json'), 'utf8'))
const config = readFileSync(join(codexHome, 'config.toml'), 'utf8')
for (const [key, hash] of reviewRecords(record, join(codexHome, 'hooks.json'), installed)) {
expect(config).toContain(`[hooks.state.${JSON.stringify(key)}]\ntrusted_hash = ${JSON.stringify(hash)}\n`)
}
expect(lstatSync(join(codexHome, 'config.toml')).mode & 0o777).toBe(0o600)
await installHookSettings('codex', hooks.settings, 19473, codexHome)
expect(readFileSync(join(codexHome, 'config.toml'), 'utf8')).toBe(config)
})
it('records them for hooks an earlier start installed, and again when Harness’s command changes', async () => {
const codexHome = home()
vi.spyOn(console, 'log').mockImplementation(() => {})
await installHookSettings('codex', hooks.settings, 19473, codexHome)
writeFileSync(join(codexHome, 'config.toml'), 'model = "gpt-6"\n')
await installHookSettings('codex', hooks.settings, 19473, codexHome)
const first = readFileSync(join(codexHome, 'config.toml'), 'utf8')
expect(first.startsWith('model = "gpt-6"\n\n[hooks.state.')).toBe(true)
// Another port: another command, so another hash, in the same tables.
await installHookSettings('codex', hooks.settings, 18999, codexHome)
const second = readFileSync(join(codexHome, 'config.toml'), 'utf8')
// Agent Messages' block makes three: notify.mjs's two, and its one; the Swarm's shell guard a fourth (task #3596).
expect(second.match(/^\[hooks\.state\./gm)).toHaveLength(4)
expect(second).not.toBe(first)
const installed = JSON.parse(readFileSync(join(codexHome, 'hooks.json'), 'utf8'))
for (const [, hash] of reviewRecords(record, join(codexHome, 'hooks.json'), installed)) expect(second).toContain(hash)
})
it('keeps what Codex wrote itself: its empty table, the person’s other records, a record already right', () => {
const records = new Map([['/h/hooks.json:session_start:0:0', 'sha256:new']])
const codex = '[hooks.state]\n\n[hooks.state."/h/hooks.json:stop:0:0"]\ntrusted_hash = "sha256:theirs"\n'
expect(withReviewRecords(codex, record, records)).toBe(`${codex}\n[hooks.state."/h/hooks.json:session_start:0:0"]\ntrusted_hash = "sha256:new"\n`)
const stale = '[hooks.state."/h/hooks.json:session_start:0:0"]\nenabled = true\ntrusted_hash = "sha256:old"\n\n[other]\nx = 1\n'
expect(withReviewRecords(stale, record, records)).toBe(stale.replace('sha256:old', 'sha256:new'))
expect(withReviewRecords(stale.replace('sha256:old', 'sha256:new'), record, records)).toBe('unchanged')
const noHash = "[hooks.state.'/h/hooks.json:session_start:0:0']\nenabled = true\n"
expect(withReviewRecords(noHash, record, records)).toBe("[hooks.state.'/h/hooks.json:session_start:0:0']\ntrusted_hash = \"sha256:new\"\nenabled = true\n")
})
it('reads a config’s structure past what only looks like it: strings, CRLF, comments', () => {
const records = new Map([['/h/hooks.json:session_start:0:0', 'sha256:new']])
const prompt = 'instructions = """\n[hooks.state."/h/hooks.json:session_start:0:0"]\ntrusted_hash = "x"\n"""\n'
expect(withReviewRecords(prompt, record, records)).toBe(`${prompt}\n[hooks.state."/h/hooks.json:session_start:0:0"]\ntrusted_hash = "sha256:new"\n`)
const crlf = '[hooks.state."/h/hooks.json:session_start:0:0"] # Codex\r\ntrusted_hash = "sha256:old" # was\r\n'
expect(withReviewRecords(crlf, record, records)).toBe(crlf.replace('sha256:old', 'sha256:new'))
})
it('records what hooks.json holds on disk: a block of the person’s before Harness’s, another timeout', async () => {
const codexHome = home()
vi.spyOn(console, 'log').mockImplementation(() => {})
await installHookSettings('codex', hooks.settings, 19473, codexHome)
const installed = JSON.parse(readFileSync(join(codexHome, 'hooks.json'), 'utf8'))
// Harness's block first, the person's added after it, and a timeout of their own: current, so not rewritten.
installed.hooks.UserPromptSubmit = [{ hooks: [{ ...installed.hooks.UserPromptSubmit[0].hooks[0], timeout: 30 }] }, { hooks: [{ type: 'command', command: 'echo theirs' }] }]
writeFileSync(join(codexHome, 'hooks.json'), JSON.stringify(installed))
rmSync(join(codexHome, 'config.toml'))
await installHookSettings('codex', hooks.settings, 19473, codexHome)
expect(readFileSync(join(codexHome, 'hooks.json'), 'utf8')).toBe(JSON.stringify(installed))
const config = readFileSync(join(codexHome, 'config.toml'), 'utf8')
const hook = installed.hooks.UserPromptSubmit[0].hooks[0]
expect(config).toContain(`[hooks.state.${JSON.stringify(`${codexHome}/hooks.json:user_prompt_submit:0:0`)}]\ntrusted_hash = ${JSON.stringify(reviewHash(record, 'UserPromptSubmit', undefined, hook))}\n`)
expect(config).not.toContain('user_prompt_submit:1:0')
})
it('records nothing for hooks that never reached the file', async () => {
const codexHome = home()
writeFileSync(join(codexHome, 'hooks.json'), '[]\n')
vi.spyOn(console, 'log').mockImplementation(() => {})
await recordReviewed(record, codexHome, join(codexHome, 'hooks.json'))
expect(existsSync(join(codexHome, 'config.toml'))).toBe(false)
})
it('leaves a config alone that defines the table in a form an appended table could collide with', async () => {
const records = new Map([['/h/hooks.json:session_start:0:0', 'sha256:new']])
for (const text of [
'hooks = { state = {} }\n',
'hooks.state."/h/hooks.json:session_start:0:0".trusted_hash = "x"\n',
'[hooks]\nstate = {}\n',
'[hooks.state]\n"/h/hooks.json:session_start:0:0" = { trusted_hash = "x" }\n',
'[hooks.state."/h/hooks.json:session_start:0:0"]\nx = 1\n\n[hooks.state."/h/hooks.json:session_start:0:0"]\ny = 1\n',
// Spelled with quotes, it is the same table.
'["hooks"]\nstate = {}\n',
'"hooks" = {}\n',
'[hooks."state"."/h/hooks.json:session_start:0:0"]\nx = 1\n\n[hooks.state."/h/hooks.json:session_start:0:0"]\ny = 1\n',
// A line of an array is not a header: the root key after it is still in the root table.
'paths = [\n["a"]\n]\nhooks = {}\n',
'\uFEFFhooks = {}\n',
// A record this does not read: a second key beside it would not parse.
'[hooks.state."/h/hooks.json:session_start:0:0"]\ntrusted_hash = """sha256:old"""\n',
]) expect(withReviewRecords(text, record, records), text).toBe('unsafe')
const codexHome = home()
writeFileSync(join(codexHome, 'config.toml'), '[hooks]\nstate = {}\n')
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(await installHookSettings('codex', hooks.settings, 19473, codexHome)).toBe(false)
expect(readFileSync(join(codexHome, 'config.toml'), 'utf8')).toBe('[hooks]\nstate = {}\n')
expect(existsSync(join(codexHome, 'hooks.json'))).toBe(false)
expect(error).toHaveBeenCalledWith(hooks.settings.messages.failed, expect.objectContaining({ name: 'HookPreparationHeld' }))
})
it('keys a symlinked hooks.json by its own name in CODEX_HOME, not its target, as Codex does', async () => {
const codexHome = home()
const dotfiles = home()
writeFileSync(join(dotfiles, 'hooks.json'), '{}\n')
symlinkSync(join(dotfiles, 'hooks.json'), join(codexHome, 'hooks.json'))
vi.spyOn(console, 'log').mockImplementation(() => {})
await installHookSettings('codex', hooks.settings, 19473, codexHome)
const config = readFileSync(join(codexHome, 'config.toml'), 'utf8')
expect(config).toContain(`[hooks.state.${JSON.stringify(`${codexHome}/hooks.json:session_start:0:0`)}]`)
expect(config).not.toContain(dotfiles)
})
it('keys by the real path of a symlinked CODEX_HOME, as Codex does, and writes through a symlinked config', async () => {
const real = home()
const link = `${real}-link`
symlinkSync(real, link)
roots.push(link)
const dotfiles = home()
writeFileSync(join(dotfiles, 'config.toml'), 'model = "gpt-6"\n')
symlinkSync(join(dotfiles, 'config.toml'), join(real, 'config.toml'))
vi.spyOn(console, 'log').mockImplementation(() => {})
await installHookSettings('codex', hooks.settings, 19473, link)
expect(lstatSync(join(real, 'config.toml')).isSymbolicLink()).toBe(true)
const config = readFileSync(join(dotfiles, 'config.toml'), 'utf8')
expect(config).toContain(`[hooks.state.${JSON.stringify(`${real}/hooks.json:session_start:0:0`)}]`)
expect(config).not.toContain(link)
})
it('never throws: an unreadable settings path is a hook Codex asks about, as before', async () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
expect(await recordReviewed(record, '/nonexistent-home', '/nonexistent-home/hooks.json')).toBe(false)
expect(error).toHaveBeenCalled()
})
})
describe('Harness’s review records, taken out for harness uninstall', () => {
const map = new Map([['/h/hooks.json:session_start:0:0', 'sha256:ours']])
const records = (key: string, hash: string) => map.get(key) === hash
const ours = '[hooks.state."/h/hooks.json:session_start:0:0"]\ntrusted_hash = "sha256:ours"\n'
it('takes out the table Harness appended, leaving the text as it was before it', () => {
const before = 'model = "o3"\r\n[hooks.state]\n'
const after = withReviewRecords(before, record, map) as string
expect(withoutReviewRecords(after, record, records)).toEqual({ text: before.replace(/\s*$/, '\n'), removed: 1 })
expect(withoutReviewRecords(ours, record, records)).toEqual({ text: '', removed: 1 })
})
it('reads a single-quoted key and spaced dots as the same table, and leaves a header inside a string', () => {
const spaced = "[ hooks . state . '/h/hooks.json:session_start:0:0' ]\ntrusted_hash = 'sha256:ours'\n\n[x]\ny = 1\n"
expect(withoutReviewRecords(spaced, record, records)).toEqual({ text: '[x]\ny = 1\n', removed: 1 })
const quoted = `note = """\n${ours}"""\n`
expect(withoutReviewRecords(quoted, record, records)).toEqual({ text: quoted, removed: 0 })
})
it('keeps a record with a comment, another field or another hash, and another hook’s', () => {
for (const text of [
ours.replace('\n', ' # mine\n'),
`${ours}enabled = false\n`,
ours.replace('sha256:ours', 'sha256:theirs'),
ours.replace(':0:0', ':1:0'),
]) expect(withoutReviewRecords(text, record, records)).toEqual({ text, removed: 0 })
})
})
// What `codex app-server` `hooks/list` of codex-cli 0.166.0 reported (2026-11-06) for the Swarm's shell guard given as a
// session flag (task #3596): `-c hooks.PreToolUse=[{matcher="*",hooks=[{type="command",command=GUARD,timeout=30}]}]`,
// keyed `/<session-flags>/config.toml:pre_tool_use:0:0`, `untrusted` until the home's config.toml records this hash and
// `trusted` once it does. A `hooks.state` given by `-c` as well is ignored ("unrecognized configuration setting").
const GUARD = "'/opt/harness/runtime/node' '/opt/harness/cli/superTabs/shellGuardHook.js'"
const GUARD_0_166 = 'sha256:e1f9e0b5b2f45f3edb26336eedc79c1fca60a8b4c6ecfc8e36ed4e61ab13592c'
describe('the Swarm shell guard, a Codex session flag, recorded as reviewed (task #3596)', () => {
it('hashes it as codex-cli 0.166.0 does', () => {
expect(sessionHookHash({ key: CODEX_SHELL_GUARD.key, label: 'pre_tool_use', matcher: '*', command: GUARD, timeout: 30 })).toBe(GUARD_0_166)
})
it('records the guard as this machine launches it, under the key Codex reads', () => {
expect([...sessionReviewRecords(record, 'darwin')]).toEqual([[CODEX_SHELL_GUARD.key, sessionHookHash({
key: CODEX_SHELL_GUARD.key, label: 'pre_tool_use', matcher: '*', command: CODEX_SHELL_GUARD.command('darwin'), timeout: 30 })]])
})
it('writes it beside Harness\'s own records at each install, so a Swarm Codex session runs it without asking', async () => {
const codexHome = home()
vi.spyOn(console, 'log').mockImplementation(() => {})
await installHookSettings('codex', hooks.settings, 19473, codexHome)
const config = readFileSync(join(codexHome, 'config.toml'), 'utf8')
for (const [key, hash] of sessionReviewRecords(record)) {
expect(config).toContain(`[hooks.state.${JSON.stringify(key)}]\ntrusted_hash = ${JSON.stringify(hash)}\n`)
}
// The hooks file itself holds no guard: a person's own Codex session never runs it.
expect(readFileSync(join(codexHome, 'hooks.json'), 'utf8')).not.toContain('shellGuardHook')
})
})