Governed actions around the model.

Why a harness matters

IEVA runs on written contracts: a pipeline, reviewable memory, skills, approval gates, privacy boundaries. Today those contracts are instructions. A capable agent follows them. Nothing checks that it did.

• Nothing records what the agent actually read, sent to a model provider, called, or wrote.
• Nothing stops a write that bypasses a rule, apart from the model’s own compliance.
• An approval gate is only a sentence when no person is watching, as in a scheduled briefing.
• No trace exists to show why a skill failed, or whether a change to it made things better.

The existing health check validates structure. It does not validate behavior. The harness closes that gap, and it is how governance becomes demonstrable rather than aspirational.

One design stance guides the scope: keep the tool surface small and well governed. The harness stays thin, and IEVA’s tool set stays narrow.

What the harness does

Six parts, each one a plain module with a clear seam. Every part is direction or concept today, and labelled as such.

• 01 · Record

  Session log

  An append-only event log per session: context sent, tool calls, policy decisions, approvals, file writes, usage. Redacted as it is written. Local only.

  Product direction

• 02 · Decide

  Policy and presets

  Your permission and privacy notes compile into a policy. Every tool call is classified and allowed, asked, or denied. There is no full-access preset.

  Product direction

• 03 · Ask

  Approvals as Markdown

  An approval request names the exact action, target, and payload, and it expires. Approving covers that action once, never a class of actions.

  Product direction

• 04 · Run

  Governed headless runs

  A job is a Markdown file. A run snapshots the vault, launches the agent with a narrow tool list, audits the diff, and reverts writes outside policy.

  Concept workflow

• 05 · Delegate

  Bounded delegation

  A subagent starts only from a written contract with allowed paths and a budget. It can be steered and stopped. Its handoff is reviewed, never absorbed. Advanced edition.

  Concept workflow

• 06 · Learn

  Reviewable learning

  Traces become pattern notes, pattern notes become skill proposals, and a proposal changes a skill only after your approval and a clean regression check.

  Concept workflow

Architecture, in plain language

Markdown stays durable and authoritative. The harness adds two machine-readable stores that are never canon: raw session logs, and generated policy and usage rollups. Everything a person must review or approve remains a note.

Product direction

One governed run

A job is a Markdown file. Its frontmatter names the skill, preset, agent, budget, and the only places it may write. The body is the task.

1. Check gatesSetup healthy, profile approved, preset allowed
2. SnapshotHashes of every path the preset may write
3. Assemble contextStable first, volatile last; every file recorded
4. Launch agentIsolated configuration, narrow tool list
5. Log and redactEvents streamed into the session log
6. Never blockAn ask becomes a deny plus an approval request
7. Diff auditWrites outside policy reverted and flagged
8. Deliver as draftProvenance attached, review pending, run report written

---
job: briefing
skill: session-start
preset: draft
adapter: claude-code
model: ""          # empty = agent default; an explicit value always wins
effort: default    # expensive settings are never the default
outputs:
  - "briefings/{{date}} Briefing.md"
budget:
  max-turns: 20
  max-minutes: 10
---
Produce today’s briefing as a draft. Cite a source note for every signal.
Do not modify any file other than the output.

What is logged, and why

The principle is simple: anything the model saw should be reconstructable from the log. That is the same standard IEVA already applies to memory — reviewable, never hidden — extended to runtime.

Product direction

What left the machine

Before a run, the harness records every file placed in context, with a hash and the provider it went to. Sending context to a model provider is a transfer. This is the ledger of it.

Tool calls and results

Each call is logged with its action class and the paths it touched. Large results are truncated and stored with a content hash, so notes are not duplicated into logs.

Policy decisions and approvals

Allow, ask, or deny, with the rule that produced it. Approval requests and their outcomes are events too.

File writes and deliveries

Before and after hashes for every write, whether it was within policy, and which files were delivered for review.

Usage

Tokens, cache reads where the agent reports them, latency, and model. Rollups are counts and ratios only. Cost estimates use a price table you maintain; we do not ship authoritative prices.

How a session ended

Completed, needs approval, stopped, over budget, or launch failure. A run with zero tool calls and no deliverable is reported as a failure, not a success.

{"v":1,"seq":1,"type":"context/assembled","data":{"provider_destination":"<provider> via <agent>",
  "files":[{"path":"AGENTS.md","sha256":"…","bytes":29758,"sensitivity":"normal"}]}}
{"v":1,"seq":9,"type":"tool/call","data":{"call_id":"t7","tool":"Write",
  "paths":["wiki/Pricing lessons.md"],"action_class":"reversible-write"}}
{"v":1,"seq":10,"type":"policy/decision","data":{"call_id":"t7",
  "decision":"deny","rule":"wiki-guard","preset":"draft"}}
{"v":1,"seq":20,"type":"session/end","data":{"status":"completed","tool_call_count":11}}

Redaction happens at write time

• Built-in secret patterns — API keys, private keys, tokens, card-like numbers — are replaced with a marker and a length. No hash is kept, because hashes of short secrets can be brute-forced.
• Content read from folders you mark restricted is logged as metadata only: path, size, content hash.
• You can add your own redaction patterns in your privacy note.
• A format change writes a new log file beside the untouched original, with hashes of both. Older readers report a newer version clearly instead of failing silently.

Logs are local by default. They sit in a runtime folder that Obsidian does not index, so they stay out of search and graph. Capture is proposed as opt-in at onboarding, with 30-day retention and one command to prune.

Policy and approvals

Policy is compiled from two notes you already own: your agent permissions and your privacy boundaries. The compiled file is derived, never hand-edited. When a decision surprises you, a policy-explain command prints the decision and the Markdown line that produced it.

Product direction

Honest enforcement levels

Not every agent can be governed equally. Each action path carries one of three levels, and every run report states which one applied.

Five presets. No full-access preset.

A preset answers two separate questions: must the user confirm, and what can the action reach. Restricted folders are unreadable in every preset. Until a profile is approved, only read-only and maintain are available.

How a tool call is decided

1. Classify the call: action class, touched paths, network effect.
2. An always-deny rule matches — credentials, restricted folders, a wiki write outside harvest — and the call is denied.
3. A write outside the preset’s destinations is denied when headless, asked when interactive.
4. External actions, deletions, and material changes ask. Headless, the ask becomes a deny plus an approval request.
5. Otherwise the call is allowed.
6. Afterwards the result is redacted before logging, and the write is recorded with hashes.

Approvals are notes

An approval request is a Markdown file with the exact action, the target, a content diff or payload summary, the requesting session, and an expiry. Approving it authorizes one execution of exactly that action. It does not authorize similar future actions. Expired requests are void.

Any tool call with network effect — a web fetch, a connector call, a push, a send — is classified external: asked when interactive, denied when headless. Writes to the wiki are denied unless the harvest skill is active, an approval exists, and the article cites a real output record.

Bounded delegation, clean handoffs

Concept workflowAdvanced edition

A subagent can start only from a delegation contract: objective, definition of done, permitted files and tools, prohibited actions, required sources, uncertainty to surface, handoff format, approval gate. The contract also fixes the preset, the allowed paths, and the budget.

• Steer. Messages join a steering queue in the contract and are delivered between turns, where the agent supports resuming a session. Undelivered messages can be edited or deleted.
• Stop. Stopping ends the process, records the stop, and runs the diff audit.
• Budget. Turns, wall time, and optional spend are enforced by the harness. Over budget, the subagent stops and files a handoff marked incomplete.
• Handoff. The result must fill the handoff template. Its content never becomes memory, output, or wiki automatically.

No teams, rosters, mailboxes, or autonomous swarms. In the local edition the delegation contract remains a manual discipline.

The learning layer

Concept workflow

Agent memory has a known gap: nobody checks whether it remembered the right thing. IEVA’s answer is a loop in which every step is a file you can read, and the only step that changes behavior needs you.

1. TracesSession logs. Immutable.
2. Pattern notesProblem, root cause, fix. Cite their sessions.
3. Skill proposalOne atomic change: create, patch, or no action
4. GateYour approval, plus no regression on saved cases
5. Apply or rejectSnapshot first. Reject leaves the skill untouched.
6. Impact recordAccepted and rejected proposals, kept in full

The rules that keep it honest

• Patterns stay out of the wiki. The wiki holds evergreen lessons about your work, harvested from shipped output. Pattern notes describe how agents perform procedures. They live in their own learning area, and they are not memory either.
• Pattern notes cannot change behavior. Only an approved skill proposal can.
• The gate is you, plus evidence. A proposal is accepted only after your recorded approval and no regression on saved example cases. Deterministic checks gate. Rubric items are shown side by side for your judgment. A model judge, if used at all, is advisory only.
• Snapshot and revert. Proposals are data applied by a deterministic script, not free edits. The skill is snapshotted before any change, and a revert restores it. Git is optional.
• Executing sessions load skills, not the pattern notebook. The proposer reads pattern notes. The agent doing the work does not.
• Facts about you go to memory review. If a pattern is really a fact about the user, it becomes a memory proposal with an evidence label. Your explicit corrections outrank patterns.
• No autonomous overnight self-modification. The advanced edition may prepare notes and proposals on a schedule. Applying always requires the user.

Why keep the notebook away from the agent doing the work? The skill-learning paper this loop adapts (arXiv 2608.27454) reports an ablation: giving the proposer access to pattern notes raised its average from 45.3% to 63.7%, and also giving the executing agent access lowered it to 60.9%. That is the paper’s finding on its own benchmarks, not an IEVA result.

Saved example cases are made by you from a real session. Each holds a frozen, redacted copy of the notes involved, the task, and the checks. Replay runs in a temporary copy, never the live vault. Pattern notes are marked stale after a review date and duplicates are merged, but none is deleted without approval.

Security posture

Design principle

The harness is a governance aid, not a security boundary. Policy hooks and approval prompts do not guarantee isolation or prevent all damage. We say so here, and the product documentation will say the same.

No telemetry

Nothing is sent to Ækora. A test asserts that harness modules contain no network code. Adapters hand off to your agent, which talks to its provider under your account.

No runtime dependencies

Node built-ins only. No third-party packages at runtime means a small attack surface and no supply chain to watch.

Secrets stay out

The harness never reads, stores, or logs credentials. Agents use their own sign-in. API adapters, in the advanced edition, read keys from the environment or the OS keychain, never from the vault. Isolated agent configuration lives in OS temp and is deleted after the run.

Restricted means unreadable

Folders you mark restricted are unreadable in every preset. With no approved profile, only read-only and maintenance presets exist.

Labelled enforcement

Enforced, hook-mediated, or contract-only. Every run report states which applied.

Step back

“IEVA, step back” disables scheduled jobs and learning suggestions, and creates no inferred patterns. Headless jobs check the flag before they start.

For the principles that govern the whole product, see security and governance.

What we adopted, adapted, and skipped

The harness adapts ideas from published agent-harness and skill-learning research. We borrowed concepts, not code, and we left most of it out. The rule was one line: adopt whatever makes actions recorded, reviewable, and gated; skip whatever serves coding benchmarks, teams, marketplaces, or a second interface.

Features by edition

The local edition keeps the harness simple and entirely manual: you start each run. The advanced edition adds scheduling, replay, supervised subagents, and direct API adapters. How the advanced edition is packaged is not decided, and no prices are published.

Product direction

Roadmap, honestly staged

This is a plan, not a progress report. No stage below is shipped, and no dates are promised. Each stage has an acceptance test, stated in advance, so “done” means something.

1. 00

   Spikes and decisions

   Synthetic transcripts captured from each supported agent. Every adapter assumption confirmed or changed. Log schema frozen. Threat model written.

   Done when every assumption about a third-party agent is marked confirmed or changed.

   Local editionProduct direction

2. 01

   Raw layer

   Session store, importers for both agents and manual import, redaction, the migration framework, run and usage commands.

   Done when seeded secrets are fully redacted in the test corpus, migrations leave originals byte-identical, a malformed line never corrupts a log, and the no-network test passes.

   Local editionProduct direction

3. 02

   Policy and approvals

   Policy compiler, presets, policy explanation, the pre-tool hook, approval requests, audit with snapshot diff and revert, the wiki guard.

   Done when red-team fixtures pass: a wiki write outside harvest is denied, network commands are asked or denied, an out-of-scope headless write is reverted, an unconfigured profile allows only read-only.

   Local editionProduct direction

4. 03

   Headless jobs and delivery

   The run command, three built-in jobs, isolated agent configuration, launch-failure detection, provenance frontmatter, Control Deck panels with a Markdown fallback.

   Done when a job never writes outside its destination and an approval need ends the run as needs-approval with a request file.

   Local editionProduct direction

5. 04a

   Learning layer, manual

   Pattern-note and proposal templates, the learning-review skill, propose, apply, reject and revert, snapshots, the impact record, saved cases with deterministic checks.

   Done when applying requires a recorded approval, rejecting leaves the skill byte-identical, and rejected proposals appear in full in the impact record.

   Local editionProduct direction

6. —

   Local edition harness release

   Documentation, changelog, third-party notices, clean-install and merge tests. Planned as a later release of the local edition; it does not hold up the first vault package.

   Done when nothing changes for a user who never enables the harness.

   Local editionProduct direction

7. 04b

   Case replay runner

   Sandbox fixture copies, replay, a current-versus-candidate report, optional repeated-run comparison.

   Done when replay never touches the live vault.

   Advanced editionProduct direction

8. 05

   Supervised subagents

   The delegation-contract runtime: steering queue, stop, budgets, handoff validation.

   Done when stop ends the whole process tree and audits, and a handoff never writes memory or wiki on its own.

   Advanced editionProduct direction

9. 06

   API adapters and cache-aware assembly

   Direct API adapters with a tool loop limited to IEVA tools, appended instruction events, keys from the environment or the OS keychain, a scheduler bridge.

   Done when the same policy tests pass through the API loop and no key ever appears in the vault or a log.

   Advanced editionProduct direction

10. 07

    Optional local web view

    A read-only view of runs, approvals, and usage, bound to this machine, with no remote assets. Deferred until there is evidence of demand.

    Built only if buyers without Obsidian need it.

    Advanced editionProduct direction

Questions