registerAuditHook({ name, onEvent, init?, maintain?, shutdown? }) — the
in-process extension seam for future exporters, following the tree's
observer idiom (registerApprovalResolvedHandler et al). Hooks observe
the LOG, not the event stream: onEvent(event, line) fires only after
the event was durably appended to the local day-file, so exported ⊆
written holds by construction — an external system can never know an
event the source of truth doesn't, and a hook that misses events
catches up by reading the day-files (the at-least-once story).
Failures are isolated everywhere: a throwing hook is logged with its
name and never affects the log, other hooks, or the audited action; a
failing append means hooks are not called at all. Lifecycle: init at
boot (throw = refuse to start, same posture as the writability assert),
maintain from the 60s host-sweep (now one maintainAudit() entry point
covering retention prune + hooks), shutdown via the host's graceful-
shutdown registry.
No forwarder, credentials, or transport ships in core — an exporter is
an in-tree or skill-installed module that registers itself; external
services keep the zero-code paths (tail data/audit/*.ndjson, or poll
ncl audit list --format ndjson).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
One canonical SIEM-shaped event per action, appended to NDJSON day-files
under data/audit/. v1 surfaces: every ncl command (both transports,
including scope denials) and every host-routed approval — pending,
decision, and terminal outcome — covering CLI gates, self-mod, a2a
message gates, agent creation (incl. the ungated global-scope door and
the channel-registration name flow), the permissions sender/channel
cards, and OneCLI credential holds.
Emit architecture is wrappers at module edges, zero inline audit calls:
withAudit(dispatch) middleware (trace out-param carries the resolved
command + effective args), a decorated requestApproval (owns pending
events; inner returns the minted hold), an observer on the existing
approval-resolved hook (decision events), a wrapped handler run in the
response handler (terminal events; cli_command's terminal comes from the
replay through the dispatch middleware, correlated via
DispatchOptions.approvalId), and audited() seams for permissions,
OneCLI, and performCreateAgent. Gated chains share correlation_id = the
approval id.
Governance guarantees: off by default (the emitter no-ops and data/audit
is never created); fail-open + loud on append failure; boot writability
assert when enabled (refuse to start over a silent audit gap); recursive
secret-key redaction + ~2KB value truncation at the single emit point;
message-bearing events record shape only (body_chars, attachment names).
Retention (AUDIT_RETENTION_DAYS, default 90, 0 = forever) hard-deletes
day-files at boot + once daily in the host sweep.
Read back with ncl audit list (--actor --action --resource --outcome
--since --until --correlation --limit, --format ndjson) — host + global
scope only; group-scoped agents fail closed via the existing allowlist.
Design docs (requirements + grill-session decisions) live on the team
hub; docs/SECURITY.md carries the operator-facing documentation.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Moshe Krupper