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
/**
* Harness's own hook blocks recorded as reviewed, where the engine asks a person to review a hook before it
* first runs (facets/hooks.ts `HookReviewRecord`): Codex 0.162 shows "Hooks need review" in the first Codex
* pane, and a person who picks "Continue without trusting" switches Harness's hooks off without knowing it.
*
* The record is the engine's own, written as the engine writes it on "Trust all": a table per hook in its
* config file, keyed by the settings file in the real path of the engine's home, the event, the block and
* the hook, holding the hash the engine computes of the hook. The hash is the engine's: the hook normalized
* (its matcher only where the engine honours one, a timeout always, `async`), every object's keys sorted,
* compact JSON, sha256. It is matched against `codex app-server` `hooks/list` of codex-cli 0.162.0
* (hookReview.spec.ts). Should an engine hash differently, it sees a changed hook and asks again, which is
* where it was before.
*
* Only Harness's own blocks, never another hook in the same file. The config file is edited the way
* folderTrust.ts edits it: through a symlink, atomically, and only where the table cannot end up defined twice.
*/
import { parse as parseToml } from 'smol-toml'
import { createHash } from 'node:crypto'
import { basename, join } from 'node:path'
import type { HookReviewRecord, SessionHook, SessionHookName } from '../facets/hooks.js'
import { codexShellGuardSessionHook } from '../../lib/agentShellGuard.js'
import { HookPreparationHeld, inspectHookFile, runHookPreparation, type HookPreparationAttempt } from './nativeHookFiles.js'
import { isMessagesBlock } from './messagesHook.js'
import { isOurs, type HookBlock, type Settings } from './notifyHooks.js'
/** Harness's own: notify.mjs's blocks, as [platform] reads a hook (a PowerShell line is ours on Windows only), and
* Agent Messages' (kit/messagesHook.ts). */
const harnessOwn = (block: HookBlock, platform: NodeJS.Platform): boolean => isOurs(block, platform) || isMessagesBlock(block)
/** Every object's keys sorted, as the engine sorts them before it hashes. */
function sortedKeys(value: unknown): unknown {
if (Array.isArray(value)) return value.map(sortedKeys)
if (value && typeof value === 'object') {
return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortedKeys((value as Record<string, unknown>)[key])]))
}
return value
}
const identityHash = (identity: unknown): string => `sha256:${createHash('sha256').update(JSON.stringify(sortedKeys(identity))).digest('hex')}`
/** The engine's hash of one command hook, as `hooks/list` reports it in `currentHash`. */
export function reviewHash(record: HookReviewRecord, event: string, matcher: string | undefined, hook: { command: string; timeout?: number; async?: boolean }): string {
return identityHash({
event_name: record.events[event],
...(record.matcherEvents.includes(event) && matcher !== undefined ? { matcher } : {}),
hooks: [{ type: 'command', command: hook.command, timeout: Math.max(1, hook.timeout ?? record.defaultTimeout), async: hook.async === true }],
})
}
/** The engine's hash of a session flag's hook: its matcher counts (codex-cli 0.166.0, `pre_tool_use`, measured). */
export function sessionHookHash(hook: SessionHook): string {
return identityHash({ event_name: hook.label, matcher: hook.matcher, hooks: [{ type: 'command', command: hook.command, timeout: Math.max(1, hook.timeout), async: false }] })
}
/** Each session hook a contract names, built for the platform it launches on. */
const sessionHook: Record<SessionHookName, (platform: NodeJS.Platform) => SessionHook> = { 'shell-guard': codexShellGuardSessionHook }
/** The records the session flags' hooks Harness gives need, as this machine launches them: key → hash. */
export function sessionReviewRecords(record: HookReviewRecord, platform: NodeJS.Platform = process.platform): Map<string, string> {
return new Map((record.sessionHooks ?? []).map((name) => sessionHook[name](platform)).map((hook) => [hook.key, sessionHookHash(hook)]))
}
/** The records Harness's own blocks in `settings` need: key → hash. */
export function reviewRecords(record: HookReviewRecord, settingsFile: string, settings: Settings,
platform: NodeJS.Platform = process.platform): Map<string, string> {
const records = new Map<string, string>()
for (const [event, label] of Object.entries(record.events)) {
const blocks = settings.hooks?.[event]
if (!Array.isArray(blocks)) continue
// An optional Messages block can precede a required notify block. Approving
// only the first would report a prepared launch with SessionStart disabled.
for (const [blockIndex, block] of blocks.entries()) {
if (!harnessOwn(block, platform)) continue
for (const [hookIndex, hook] of block.hooks.entries()) {
if (!harnessOwn({ hooks: [hook] }, platform) || hook.type !== 'command' || typeof hook.command !== 'string') continue
// A hook edited into a shape Harness does not write is one the engine reads its own way: it asks.
if ((hook.timeout !== undefined && typeof hook.timeout !== 'number') || (block.matcher !== undefined && typeof block.matcher !== 'string')) continue
records.set(`${settingsFile}:${label}:${blockIndex}:${hookIndex}`, reviewHash(record, event, block.matcher, hook))
}
}
}
return records
}
const escape = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
/** One key, bare or quoted: `hooks`, `"hooks"` and `'hooks'` name the same table. */
const segment = (key: string): string => `(?:${escape(key)}|"${escape(key)}"|'${escape(key)}')`
/** `hooks.state` as a header path, however its dots are spaced and its keys quoted. */
const tablePath = (table: string): string => table.split('.').map(segment).join(String.raw`[ \t]*\.[ \t]*`)
/** A key in a header: bare, or a one-line string. */
const KEY = String.raw`(?:[A-Za-z0-9_-]+|"(?:[^"\\\r\n]|\\.)*"|'[^'\r\n]*')`
const HEADER = new RegExp(String.raw`^[ \t]*\[\[?[ \t]*${KEY}(?:[ \t]*\.[ \t]*${KEY})*[ \t]*\]\]?[ \t]*(?:#.*)?\r?$`)
/**
* The text as it is read for its structure: multi-line strings and a byte order mark blanked to spaces,
* newlines kept, so that a line inside a string is never taken for a header or a key, and every offset still
* points into the real text. Codex refuses a config.toml that does not parse, every setting in it lost: a
* header appended in the wrong place would cost a person far more than a hook review.
*/
const structure = (text: string): string => text
.replace(/^/, ' ')
.replace(/"""[\s\S]*?"""|'''[\s\S]*?'''/g, (string) => string.replace(/[^\n]/g, ' '))
/** How many arrays and inline tables a line opens, less those it closes; its strings and comment left out. */
const opens = (line: string): number => {
const bare = line.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '').replace(/#.*/, '')
return (bare.match(/[[{]/g)?.length ?? 0) - (bare.match(/[\]}]/g)?.length ?? 0)
}
interface Line { start: number; end: number; text: string }
/** The table headers, in order: a line of an array or inline table that spans lines (`["a"]`) is a value. */
function headers(shape: string): Line[] {
const found: Line[] = []
let depth = 0
let start = 0
for (const text of shape.split('\n')) {
if (depth === 0 && HEADER.test(text)) found.push({ start, end: start + text.length, text })
else depth = Math.max(0, depth + opens(text))
start += text.length + 1
}
return found
}
/** The key a quoted TOML key names; null for an escape JSON does not share. */
function tomlKey(quoted: string): string | null {
if (quoted.startsWith("'")) return quoted.slice(1, -1)
try { return JSON.parse(quoted) as string } catch { return null }
}
/**
* The table, or the table above it, defined in a form a header appended after it could collide with: an
* inline table, dotted keys, an array of tables, or values in the table's own body. Codex writes
* `[hooks.state]` with nothing in it, then a header per hook.
*/
function definedOtherwise(shape: string, table: string): boolean {
const [top, sub] = table.split('.')
const list = headers(shape)
const body = (i: number): string => shape.slice(list[i].end, list[i + 1]?.start ?? shape.length)
const preamble = shape.slice(0, list[0]?.start ?? shape.length)
if (new RegExp(String.raw`^[ \t]*${segment(top)}[ \t]*[.=]`, 'm').test(preamble)) return true
const topHeader = new RegExp(String.raw`^[ \t]*\[[ \t]*${segment(top)}[ \t]*\]`)
const tableHeader = new RegExp(String.raw`^[ \t]*\[[ \t]*${tablePath(table)}[ \t]*\]`)
const arrayOfTables = new RegExp(String.raw`^[ \t]*\[\[[ \t]*${segment(top)}(?:[ \t]*\.[ \t]*${segment(sub)})?[ \t]*\]\]`)
return list.some((line, i) => arrayOfTables.test(line.text)
|| (topHeader.test(line.text) && new RegExp(String.raw`^[ \t]*${segment(sub)}[ \t]*[.=]`, 'm').test(body(i)))
|| (tableHeader.test(line.text) && /^[ \t]*[^\s#]/m.test(body(i))))
}
/**
* The config file's text with each record in place: an existing table's hash replaced when it differs, a
* missing table appended. 'unsafe' when the file defines the table, or a record, in a form this could make
* invalid; the engine then asks the person, as it would anyway.
*/
export function withReviewRecords(text: string, record: HookReviewRecord, records: Map<string, string>): string | 'unchanged' | 'unsafe' {
if (definedOtherwise(structure(text), record.table)) return 'unsafe'
const header = new RegExp(String.raw`^[ \t]*\[[ \t]*${tablePath(record.table)}[ \t]*\.[ \t]*("(?:[^"\\\r\n]|\\.)*"|'[^'\r\n]*')[ \t]*\]`)
const field = new RegExp(String.raw`^([ \t]*${segment(record.key)}[ \t]*=[ \t]*)([^\n]*)$`, 'm')
const value = /^("(?:[^"\\\r\n]|\\.)*"|'[^'\r\n]*')[ \t]*(?:#.*)?\r?$/
let next = text
for (const [key, hash] of records) {
const shape = structure(next)
const list = headers(shape)
const found = list.flatMap((line, i) => {
const match = header.exec(line.text)
return match ? [{ i, key: tomlKey(match[1]) }] : []
})
if (found.some((one) => one.key === null)) return 'unsafe'
const ours = found.filter((one) => one.key === key)
if (ours.length > 1) return 'unsafe'
if (ours.length === 1) {
const at = list[ours[0].i].end
const line = field.exec(shape.slice(at, list[ours[0].i + 1]?.start ?? shape.length))
if (line) {
// Only a one-line string is read and replaced; anything else (a multi-line string, another type) is
// a record this does not understand, and a second key beside it would not parse.
const from = at + line.index + line[1].length
const quoted = value.exec(next.slice(from, at + line.index + line[0].length))
if (!quoted) return 'unsafe'
if (tomlKey(quoted[1]) === hash) continue
next = next.slice(0, from) + JSON.stringify(hash) + next.slice(from + quoted[1].length)
} else {
next = `${next.slice(0, at)}\n${record.key} = ${JSON.stringify(hash)}${next.slice(at)}`
}
continue
}
// A TOML basic string is a JSON string, except that DEL must be escaped too.
const table = `[${record.table}.${JSON.stringify(key).replace(/\x7f/g, '\\u007f')}]`
next = `${next.replace(/\s*$/, '')}${next.trim() ? '\n\n' : ''}${table}\n${record.key} = ${JSON.stringify(hash)}\n`
}
return next === text ? 'unchanged' : next
}
/**
* `harness uninstall`: the config file's text without each record [owned] calls Harness's (its key and hash), in the
* one form Harness, and the engine on "Trust all", writes it: its own table holding the hash and nothing else. The
* table goes with the blank lines after it, up to the next header; every other byte stays. A record with more in its
* table is the engine's or the person's and is kept.
*/
export function withoutReviewRecords(text: string, record: HookReviewRecord, owned: (key: string, hash: string) => boolean): { text: string; removed: number } {
const shape = structure(text)
const list = headers(shape)
const header = new RegExp(String.raw`^[ \t]*\[[ \t]*${tablePath(record.table)}[ \t]*\.[ \t]*("(?:[^"\\\r\n]|\\.)*"|'[^'\r\n]*')[ \t]*\][ \t]*\r?$`)
const only = new RegExp(String.raw`^\r?\n[ \t]*${segment(record.key)}[ \t]*=[ \t]*("(?:[^"\\\r\n]|\\.)*"|'[^'\r\n]*')[ \t]*\r?(?:\n[ \t\r]*)*$`)
const spans: Array<[number, number]> = []
for (const [i, line] of list.entries()) {
const match = header.exec(line.text)
const key = match ? tomlKey(match[1]) : null
if (key === null) continue
const end = list[i + 1]?.start ?? text.length
const body = only.exec(shape.slice(line.end, end))
const hash = body ? tomlKey(body[1]) : null
if (hash !== null && owned(key, hash)) spans.push([line.start, end])
}
let next = text
for (const [start, end] of [...spans].reverse()) next = next.slice(0, start) + next.slice(end)
// The installer appended a record after the text's trailing space, trimmed: taking the last one out ends the
// text where the person's did.
if (spans.at(-1)?.[1] === text.length) next = next.trim() ? next.replace(/\s*$/, '\n') : ''
return { text: next, removed: spans.length }
}
/** Inspect approvals before publishing hooks. An unreadable or conflicting
* config cannot authorize even the first write of the installation. */
export function prepareReviewed(record: HookReviewRecord, home: string, settingsFile: string, settings: Settings,
platform: NodeJS.Platform = process.platform) {
const config = join(home, record.file), observed = inspectHookFile(config, 0o600)
// Codex uses the real home plus the literal hooks filename, even when that
// leaf is an alias. The config's own leaf alias does not change that home.
const records = reviewRecords(record, join(observed.directory, basename(settingsFile)), settings, platform)
if (records.size === 0) throw new HookPreparationHeld('the hooks have no verifiable approval records')
// In the same write as Harness's own, so a Swarm session's guard (lib/agentShellGuard.ts) is trusted in every home
// Harness prepares: the default one at each hook refresh, an agent's own profile before it starts.
for (const [key, hash] of sessionReviewRecords(record, platform)) records.set(key, hash)
const text = observed.content ?? ''
try { parseToml(text, { integersAsBigInt: true, maxDepth: 64 }) }
catch { throw new HookPreparationHeld('the hook review configuration is not complete TOML') }
const next = withReviewRecords(text, record, records)
if (next === 'unsafe') throw new HookPreparationHeld('the hook review configuration cannot be safely updated')
const output = next === 'unchanged' ? text : next
try { parseToml(output, { integersAsBigInt: true, maxDepth: 64 }) }
catch { throw new HookPreparationHeld('the prepared hook reviews are not complete TOML') }
observed.prepare(output)
return {
verify: observed.verify,
commit: async (attempt: HookPreparationAttempt) => {
const published = await observed.replace(next === 'unchanged' ? text : next, attempt)
if (next !== 'unchanged') console.log(record.messages.recorded.replace('{config}', config))
return published
},
}
}
/** Record the exact settings already on disk. Failure is explicit so launch
* remains held until both the hook and its approval are confirmed durable. */
export async function recordReviewed(record: HookReviewRecord, home: string, settingsFile: string): Promise<boolean> {
const config = join(home, record.file)
try { return await runHookPreparation([settingsFile, config], async attempt => {
const source = inspectHookFile(settingsFile)
const settings = JSON.parse(source.content ?? 'null') as Settings
if (!settings || typeof settings !== 'object' || Array.isArray(settings) || !settings.hooks || typeof settings.hooks !== 'object') return false
const prepared = prepareReviewed(record, home, settingsFile, settings)
source.verify(); const published = await prepared.commit(attempt)
source.verify(); published.verify()
return true
}) } catch (err) {
console.error(record.messages.skipped.replace('{config}', config), err)
return false
}
}