Turn the coding-agent scenario into the flagship security + utility benchmark

[dgenio]

Goal

Use the existing coding-agent scenario as a candidate flagship benchmark, not just a demo that proves Kernel can block things.

The benchmark must answer two questions at the same time:

1. Security: does the mediated boundary prevent actions outside the granted authority?
2. Utility: can the agent still complete the work it was legitimately asked to do without excessive false denials or policy ceremony?

A deny-all policy is not a successful result.

This remains a candidate beachhead. Gate 0 (#278) must validate that coding-agent security is a stronger external wedge than alternative application/workflow-agent use cases before broad promotion.

Canonical problem statement

Give a coding agent exactly the repository, shell and GitHub powers needed for the current step, without silently granting secrets, workflow rewrites, arbitrary network/package operations or merge authority—and leave evidence showing which mediated actions were allowed or denied.

Do not claim that Kernel makes a compromised model safe or provides a sandbox. The precise claim is that an unauthorized action submitted through the Kernel mediation path is rejected before the configured driver executes it.

Capability profile

Keep the public vocabulary small and concrete, for example:

• repo.read.files
• repo.write.files
• path-scoped write constraints
• shell.run.tests
• shell.run.package_manager
• shell.run.networked_command
• github.read.*
• github.create_pr
• github.merge_pr
• secrets.read — denied unless deliberately granted

The benchmark should prove constraints, not merely capability names. Examples:

• writes only under approved source/test paths;
• .github/workflows/** remains denied;
• approved test commands run, arbitrary shell/network commands do not;
• PR creation can require explicit escalation;
• merge remains unavailable after PR-create approval unless separately granted.

Reproducible scenario

Use a hermetic/local fixture so the core benchmark requires no LLM API key or external account.

review phase
  ALLOW repo.read + github.read
  DENY repo.write, shell/network, secrets

edit/test phase
  ALLOW bounded repo.write + shell.run.tests
  DENY workflows, secrets, arbitrary shell/network, publish

publish phase
  request github.create_pr
  → explicit approval / capability escalation
  → ALLOW create PR
  → still DENY merge

Visible evidence should include:

1. allowed repository read;
2. successful bounded edit;
3. successful test execution;
4. denied secret/environment access;
5. denied out-of-scope path write;
6. denied arbitrary/networked command;
7. approval-required PR creation;
8. approved PR creation succeeding;
9. merge still denied;
10. kernel.explain() / ActionTrace tying each mediated action to principal, capability/constraint, decision/reason and outcome.

Benchmark dimensions

Report both protected and useful behavior:

Metric	Purpose
unauthorized-action success rate	core security failure rate; target 0 for covered cases
authorized-task completion rate	ensures policy does not make the agent useless
false-deny rate	adoption/usability cost
unmediated / bypass surfaces	makes coverage honest
policy/classification effort	setup cost
p50 / p95 enforcement latency	runtime cost
audit completeness	whether every covered allow/deny is explainable
scope-constraint correctness	path/command/resource constraints cannot widen
approval usability	escalation works without granting future/adjacent authority

Where a native framework control or another authorization approach can run the same fixture, include it as a neutral comparison. The goal is to identify the incremental value of Kernel, not to construct a benchmark that competitors cannot participate in.

Framework coverage

If this scenario is later wired into OpenAI/LangChain/other agent frameworks, publish a surface-by-surface mediation table. Do not write “framework X is secured by Kernel” when only custom function tools cross the wrapper.

The offline fixture remains the canonical benchmark because it measures Kernel semantics independently of model quality or framework behavior.

Adoption artifacts

Only after the benchmark and Gate 0 evidence support the coding-agent wedge:

• <60-second terminal cast: useful read/edit/test → denied forbidden action → approved bounded escalation → trace;
• copy/paste released-package quickstart;
• three minimal policy examples: review-only, edit+test, create-PR;
• explicit “when not to use Kernel” and mediation-boundary box;
• machine-readable benchmark results committed with enough metadata to reproduce them.

Acceptance criteria

• Minimal coding-agent capability/constraint vocabulary is defined.
• Existing offline scenario covers useful ALLOW + security DENY + bounded escalation.
• Path-scoped writes and command-category restrictions are demonstrated.
• Approval does not implicitly grant adjacent authority (e.g. create PR ≠ merge).
• Benchmark reports security and utility metrics above.
• Every benchmark decision has inspectable ActionTrace / explanation evidence.
• Explicit non-claims match docs/security-contract.md.
• Any framework-backed variant publishes a mediation coverage matrix.
• Results are reproducible from the released weaver-kernel package or clearly identify unreleased commit SHA.
• Validate the execution-enforcement wedge against native guardrails and existing authz #278 validates coding agents as a worthwhile external wedge before broad launch/content promotion.

Dependencies / sequencing

• Security-contract and roadmap foundation: merged PR docs: define security contract and adoption-gated roadmap #276.
• Easy-path semantics: dx: framework middleware / drop-in mode (wrap an existing tool loop, don't rebuild the agent) #104.
• Product falsification / independent-user evidence: Validate the execution-enforcement wedge against native guardrails and existing authz #278.
• Known supported-path hardening remains higher priority than marketing artifacts.

Non-goals

• Proving prompt-injection resistance in general.
• Claiming a VM/container sandbox.
• Making the coding-agent vocabulary a universal standard before external use demonstrates portability.
• Growing a generic capability taxonomy before the concrete benchmark is excellent.

[dgenio]

I would avoid a coarse github.write.issues capability. For coding agents, authority to mutate a repository is different from authority to create organizational obligations.

A useful vocabulary split would distinguish at least:

• issue create/update;
• PR create/update/merge;
• review submit/request-changes;
• reviewer request;
• assignment/priority mutation;
• release publication.

These should be grantable independently from repo.write.files and from each other. In particular, issue/PR/review/reviewer/assignment actions are often technically reversible but consume human attention and carry positional weight.

For those actions, the capability envelope should support task-bound, one-shot grants (and optionally a small action budget), with the audit record binding the mutation to the task/plan that justified externalizing the work.

This complements the existing least-privilege model: permission to produce code should not imply permission to produce work for other people.

[dgenio]

The concrete coding-agent least-privilege beachhead is now on main via #273 (9cacdbdcc8f072de457f4e62c0ac9599db4b1a71). It adds a small built-in coding-agent capability policy, explicit write/test/network/secrets/merge authority, task-bound PR approval, path-scoped writes, a hermetic ALLOW/DENY/escalation demo, stable expected receipt, docs, and CI execution.

The key invariant is stronger than a grant-time path check: the exact approved path/command-class/task is bound into the signed token constraints and enforce_coding_agent_constraints() fails closed if a driver invocation swaps those arguments after grant. Copilot review also caught and we fixed preservation of the repository-wide WRITE/DESTRUCTIVE justification minimum, top-level secrets/**, consistent role errors, and denial-message contract tests before merge.

Keep #253 open for the broader design ideas already raised here rather than pretending this beachhead exhausts the problem: richer action/session envelopes and budgets, more explicit org/repository authority separation, real host/framework driver integrations, and a published-package-only first-run surface that does not rely on checking out the examples directory.

[dgenio]

The package-first adoption gap is now fixed on main via #274 (fa24e6797ca5f3f981d1b335ee2485ee4ff3d877).

The maintained first-success command is now:

python -m pip install weaver-kernel
python -m weaver_kernel.coding_agent_demo

The module is hermetic and verifies the complete semantic receipt before printing: bounded read/edit/test; denied workflow and secret access with stable reason codes; denied task publication; explicit one-task escalation; the signed task-bound policy grant; successful execution; denial and invoke records retrieved through kernel.explain(); and post-grant scope-substitution denial. The source example is now only a wrapper that byte-compares the package result with the committed fixture.

Exact pre-merge head a1341f93fcc46eb4c0bc1c15462d6fa22611dcb3 passed CI run 31439268912 (Python 3.10–3.14, floor dependencies, dependency audit, bare install/no extras including the module command, and Weaver-spec conformance) plus CodeQL run 31439268926. The single review thread was fixed by refusing optimized python -O execution before any output and adding a regression test.

Keep #253 open: the next release must publish this module to PyPI before the documented pip install path is true for outsiders, and the <60-second recording still remains before broad launch. Richer one-shot budgets/session envelopes and real host integrations remain follow-up design work, not prerequisites for the beachhead.