Harness
The agent harness behind oklm agent: the loop that runs
a task, the tools the model calls, what decides whether a call runs, the
settings and memory files, the terminal UI, sessions, and the ways to
extend it. Each part has its own page; this one lists them and how the
whole is tested. Day-to-day use is in user-guide.md.
Status: implemented: permissions, the audit log, the built-in tools, skills, plans, background jobs, sub-agents, the Linux sandbox and the agent loop.
Parts
- agent-loop.md: the agent loop, the system prompt, loop details, backends and stream events, headless and library use, results on published models, the agent evals.
- agent-tools.md: the built-in tools (the web, notebooks, questions), skills, deferred tools and ToolSearch, sub-agents, git.
- agent-permissions.md: permission rules and modes, dangerous calls, the audit log, the sandbox.
- agent-settings.md: settings files and every setting, usage, the debug log and telemetry, memory files.
- agent-ui.md: slash commands and the terminal UI.
- agent-sessions.md: context and compaction, sessions.
- agent-extensions.md: hooks, plugins, MCP servers.
- processes.md: background jobs, declared services, language servers, integrations.
Verification
tests/harness/test_permissions.c: the splitter on
separators, quoting, escapes, comments, continuations, and the lines it
must refuse (substitutions in and out of double quotes, backquotes,
process substitution, subshells, unbalanced quotes); path normalization
and globs; Bash rules against compound lines, quoted command names,
background separators and substitutions; path rules against
.., repeated slashes and symbolic links; precedence across
sources; managed-only allow rules; every mode, bypass refused without
the sandbox; domains against look-alike hosts and query strings;
malformed rules; the standard settings files and the highest
defaultMode; audit lines parsed back, secrets masked.
tests/harness/test_tools.c: Write, Read (offsets,
limits, binary files, directories), Edit (unique, ambiguous, every
occurrence, missing); Glob and Grep with a Read deny rule hiding a
directory's files and contents, case-insensitive search, file filters;
Bash output and exit codes, the project as working directory, the output
limit, a timeout returning within seconds, a background process killed
when the shell ends; a denied command not run, the user's refusals,
"always" allowing the same commands later in any order, plan mode, the
audit lines.
Skills (test_tools.c): headers with quoted values, a
skill without a header named by its directory, the project's skill over
the user's of the same name, the Skill tool in plan mode, an unknown
name answered with the list. tests/harness/test_skills.c:
precedence across the project's, .agent's, the user's and
the built-in skills; each header error leaving a skill out with its file
named, warnings for smaller faults, the validation function; YAML
blocks, lists, quotes and comments; twenty skills with long descriptions
within the prompt's budget, bodies never in the prompt, a small budget
leaving skills to ToolSearch; the Skill tool's body, directory and
arguments, a user-only skill refused, the built-in skill; additions,
edits and removals noticed; allowed-tools running a command
unasked during the request and asking again after it, a deny rule
winning; deferred tools named but not defined in the prompt, loaded by
ToolSearch, a skill found by words, an unknown name; a backend offered a
tool once loaded; a definition's skills preloaded, a forked skill run as
a sub-agent of its type; the skills loaded named after a compaction.
tests/harness/test_headless.c: stream-json lines parsed
back (init, thinking and text, tool_use with its input, tool_result, the
result with its usage and turns), the single JSON result,
error_max_turns and its status, the text format, user
messages read from JSON lines; a custom tool refused without a rule, run
with one, its call without a required argument stopped before it runs,
names taken refused; a PreToolUse hook as a function blocking Read with
its reason; oklm_agent_cancel() from another thread.
tests/harness/test_probe.c: probes read and refused; a
delay, a log line (and one printed before the wait), a command, all and
any; a job ending first failing the wait at once with its last lines; a
timeout; a port and an HTTP answer (a 503 refused, a 200 accepted, from
a server in the test); the holder of a port named, this process's own; a
job's port held by another process said before waiting; a job listening
found by oklm_job_ports(); WaitFor on a job's line, a
command probe refused without a rule and run with one, the last lines on
a timeout.
tests/harness/test_git.c (scratch repositories, the
user's git configuration kept out): detection and the snapshot; the
branch and HEAD from the files, packed refs too; a merge stopped by a
conflict seen; a push to the default branch, to HEAD:main,
to a protected branch, with -C; an amend and a rebase
dangerous only once HEAD is pushed; a commit read with -am;
a staged AWS key blocking the commit, also through the Bash tool (the
commit count unchanged); a .env told after the commit; a 6
MB file outside LFS; the agent told of a branch switch; a commit on main
asking, not on another branch, a push to release/2.0 (the
default protected list), a switch with an uncommitted file asking, not a
new branch nor a restore; a merge stopped by a conflict resolved by a
scripted model through Bash, Read, Write and a merge commit; a bisect
the model started and left reset when its request ended.
test_permissions.c test_git_classes: reads,
changes and interactive forms; deny rules through global options and
assignments; allow rules only past harmless ones; config writes
dangerous.
tests/harness/test_process.c: a command past its timeout
moved to the background, its output so far shown and not read again, its
end and exit code seen; sleep stopped; the setting keeping
commands in the foreground; Ctrl+B from another thread moving a command
at once; ProcessOutput with a filter, nothing new the second time,
BashOutput; ProcessList with the last lines; ProcessStop on two jobs,
KillShell; an agent starting python3 -m http.server in the
background, WaitFor on its port (told the job listens there), the URL in
its answer, the request's log line read once; a harness killed with
SIGKILL leaving a job whose child ignores SIGTERM, the next session
finding it (and not the finished nor the detached job), stopping it and
writing reaped_by in the dead session's journal; the jobs
running and kept alive counted.
tests/harness/test_events.c: a burst of fourteen lines,
seven errors, coalesced into one event showing the last five; the
monitor's end when its job is stopped; a stop line ending a monitor and
its own job; the rate cap keeping two events of three; a job's end
counted without words; bad patterns and jobs refused; the Monitor tool
refusing without a command or a running job, attached to a job (only the
new line), and the agent told a monitor's event at its next turn.
tests/harness/test_lsp.c (clangd, when installed): Read
opening the files, the server a job of kind lsp; an Edit making
twice("21") getting LSP: 1 new error at
main.c:3; a later edit not repeating it; the diagnostics, a
definition across files, references, hover, the document's symbols, a
rename preview that changes nothing; an unknown operation and a file
without a server refused; the server stopped at the end; a server not
installed told once, no job started.
tests/harness/test_jobs.c: output and exit codes,
reading from an offset, a job killed with the process it started in the
background, owned jobs stopped at close, a detached job outliving the
harness then re-attached and seen finishing, a job of a dead process
recorded as interrupted, an owned job killed when its harness process is
killed, old sessions removed; a job's kind, label, directory, owner,
times and environment markers, read back from the journal; readers with
their own places, escapes and carriage returns, filter, tail and cap; a
log rotated past its cap; a failing job restarted twice with growing
delays; the limit refusing a third job and listing the two; a stop
command, a grace, a grandchild ignoring SIGTERM gone; close in reverse
order, a job kept alive left running; Bash in the background, JobOutput
(offsets), JobKill, and Detach refused by default then allowed by a
rule.
tests/harness/test_sandbox.c (skipped without user
namespaces), by escape attempts: writing next to the project and in the
home directory fails, a file written in /tmp is gone afterwards,
unshare -U fails, the network namespace holds only the
loopback, while the project stays writable, the user's id is kept,
NoNewPrivs is 1 and the seccomp filter is in force; the
command is process 1, sees only its own processes and cannot signal the
test's; a Read deny rule's file reads empty and its directory lists
nothing and takes no file, an Edit deny rule's file stays readable but
not writable, the rest of the project stays writable and the real files
are untouched; the five limits are in force, confined and not, and a
confined command cannot start more processes than allowed; a confined
background job cannot write outside the project.
tests/harness/test_agent.c: a scripted model writing two
tool calls in two turns then an answer: the calls run, their results
(the file written, the command's output) are in the next prompt, the
conversation carries over to the next message and resets; skills listed
in the system prompt; a background job's end told before the next turn;
a sub-agent's report (its reasoning stripped) as the Agent result, the
sub-agent refused an agent of its own, Agent asking by default; a
background sub-agent held until the agent has gone on to its next call,
its report (reasoning stripped) in the agent's last prompt after the
interim answer, its write outside the project refused since it cannot
ask; a second background agent over the limit refused, and an endless
one stopped when the agent is freed; two calls in one turn run in order,
each with its result; a denied command is not run and its refusal
reaches the model; a model that never answers stops at the turn limit.
With a fixture replayed by the mock: reasoning, a Read call and the
answer, the events in order (TOOL_CALL after the turn's STOP, a last
STOP ending the message), usage, the second request carrying the call
with its arguments as a string and its result under its id; a
<think> block in the content reported as reasoning
and kept out of the history; an interrupt after two words (the history
keeps them, the next message runs), an interrupt after the first of two
calls (the second answered "Interrupted by the user" without running);
sleep 20 killed 0.3 s after an interrupt; the HTTP
backend's chunks with two tool calls in fragments.
tests/server/test_server.c: the agent over the HTTP backend
against the server (pieces streamed, the server's usage and finish
reason), and on the in-process model (the turn's token limit as its
stop, the second message reusing the cached prompt, an interrupt
stopping generation after two tokens).
Next
The Windows restricted token and low-integrity ACLs of ADR-0011, and the HTTPS API and GUI over the agent (M8).