# The decision engine: a translation layer between what an agent asks and what is done, and what it does to a skill that carries more than it says

> Every coding agent asks permission the same way, with a box of shell and two buttons, and every person learns the same answer, which is to press Allow. The question has no context. It does not know the policy, the project's rules, what was approved an hour ago, whether the change can be undone, or what the command will actually do. The decision engine is the thing that knows. It is a service the agent's harness calls before every command, with the exact command, the working directory, the agent's stated intent, the skill in force, and no secret, and it answers one of three things: allow, deny, or a question in the person's own words. It decides from three sources of truth, in order of cost. The parse reads the command's shape against the policy's rows in milliseconds, and refuses what it cannot read. The rehearsal runs the command first in a twin of the workspace, with no network and the twin as the only writable place, traced, and reports what the command tried to do rather than what it looks like. The policy is the mandate every row is checked against. A model may explain the facts and compare them with the stated intent; it never decides. The engine also answers a question this project has been asked about skills, the folders of instructions and scripts an agent loads, which can carry more than their README says. Under the engine a skill ships its own policy, bound to the hash of its folder, and every action it causes is checked against that policy intersected with the session's, so a skill that reaches for a host it never declared is refused by name, and its measured delta is its reputation. Two prototypes ran on 26 October 2026: the parse answered twelve commands, the rehearsal ran four in a twin and refused an installer on the facts. No service exists; this is the design, with its limits named.

*Source: <https://sharness.ai/articles/the-decision-engine.html> · generated from the same source as the page, so the two cannot drift.*

---

By [pbp@sharness](https://sharness.ai/admin/members/pbp/index.html) · 2026-10-26 · published

**Summary:** Every coding agent asks permission the same way, with a box of shell and two buttons, and every person learns the same answer, which is to press Allow. The question has no context. It does not know the policy, the project's rules, what was approved an hour ago, whether the change can be undone, or what the command will actually do. The decision engine is the thing that knows. It is a service the agent's harness calls before every command, with the exact command, the working directory, the agent's stated intent, the skill in force, and no secret, and it answers one of three things: allow, deny, or a question in the person's own words. It decides from three sources of truth, in order of cost. The parse reads the command's shape against the policy's rows in milliseconds, and refuses what it cannot read. The rehearsal runs the command first in a twin of the workspace, with no network and the twin as the only writable place, traced, and reports what the command tried to do rather than what it looks like. The policy is the mandate every row is checked against. A model may explain the facts and compare them with the stated intent; it never decides. The engine also answers a question this project has been asked about skills, the folders of instructions and scripts an agent loads, which can carry more than their README says. Under the engine a skill ships its own policy, bound to the hash of its folder, and every action it causes is checked against that policy intersected with the session's, so a skill that reaches for a host it never declared is refused by name, and its measured delta is its reputation. Two prototypes ran on 26 October 2026: the parse answered twelve commands, the rehearsal ran four in a twin and refused an installer on the facts. No service exists; this is the design, with its limits named.

![The decision engine as a service between the agent and the doors. On the left the agent, with a ten-line hook that sends each command, its directory and the agent's intent, with environment variable names and never a value. In the middle the decision service, holding the parse, the rehearsal in a twin, the policy by hash, the context of conventions and earlier verdicts, and the learned rows. On the right the three answers: allow, deny with a reason, ask with a question. Below, sharness.bash runs only what was allowed, under the kernel's rows.](/articles/images/decision-engine/architecture.svg)

*The engine between the agent and the doors. Where it sits decides what it is: advising a hook in the agent's own process it is a Setting; running the command itself as `sharness.bash` it is a Boundary. Proposed, 26 October 2026; two prototype runs; no service exists.*

## In short {#in-short}

- **The permission prompt has no context, and the engine is the context.** The policy by hash, the project's rules as rows, the verdicts already given, the undo class, what the command would actually do, and the organisation's shared profiles. All of it in the service, none of it in the agent.
- **One request, no secret.** The command, the directory, the intent, the policy hash, the skill in force, and the names of the environment variables the command would see. A decision about a command is a decision about rows, so no value is ever needed.
- **Three answers.** Allow: every row held, an audit line, nothing to see. Deny: a row refused, a behaviour row broken, or a command the engine cannot read, and the agent is told which. Ask: a row no barrier holds, and the person sees what it reads, writes, reaches, whether it can be undone, and what the agent says it is for, with three choices: once, add the row, refuse.
- **Three sources of truth, in order of cost.** The parse (milliseconds), the rehearsal in a twin (seconds), the policy (the mandate). An approved question becomes a learned row.
- **The model narrates and never decides.** It may explain the facts and compare them with the stated intent. By the ABP's own test a rule a model keeps is an Expectation, so the verdict is never the model's.
- **A skill ships a policy bound to its hash.** While the skill is in force, the effective rows are its rows intersected with the session's. An action beyond them is refused by name, and the skill's measured delta is its reputation.
- **The engine adds decisions and words, not enforcement.** The kernel and the doors refuse what the policy refuses, whatever the engine missed. A parser is not a sandbox.
- **Prototypes, not products.** On 26 October 2026 the parse answered twelve sample commands (three allowed, two asked, seven refused) and the rehearsal ran four in a twin (an installer refused on the facts). Both are on a branch of the CLI for its agent, with no tests, and nothing is in the package.

## The question without context {#problem}

Dinis Cruz's complaint, which this project shares with anyone who has supervised a coding agent for a week: the agent stops and asks, the prompt shows a command, and the person cannot tell from the prompt what the command reads, writes, reaches, or can undo. On a phone the command fades out before the line that matters ([ux.sgit.ai, UX-059](https://ux.sgit.ai/findings/UX-059.html), 25 October 2026). The person has two choices, stop the work or trust blindly, and after a few dozen prompts everyone takes the second. That is not a usability flaw beside a security flaw. It is one flaw: a decision asked without what you need to make it is a decision nobody makes.

The deeper reason the prompt is empty is that it is asked in the wrong place. The agent's process asks the agent's user, at the moment of the call, about the call alone. In the [Agent Behaviour Policy](https://riskmandate.ai/abp.html)'s terms the prompt is a Setting: the same account can turn it off, and it bounds nothing the grant does not already include. Everything that would make the decision easy, the policy, the project's rules, the session so far, the undo class, lives elsewhere.

## What the engine is {#what}

A service the agent's harness calls before every command, with one rule given to the agent: *before you run a command or start a process, call this with the exact command, the working directory and your intent; send no secret; run only what it answers yes to.* The engine maps the command to the rows of a [Process Behaviour Policy](../design/pbp/index.md), decides, and answers in the person's words when it must ask. It is the first piece of SHarness a person can adopt, because it changes what they are asked before it changes anything the kernel does.

It is not a sandbox. It decides, and it talks. The protection is the kernel's and the doors': what the policy refuses, Landlock, the namespaces and `sharness.fs`, `sharness.net` and `sharness.bash` refuse, whatever the engine missed. The two are different jobs and the design keeps them apart on purpose.

## Inputs and outputs {#io}

![The request and the verdict, side by side as JSON. The request: a version, the tool, the command, the working directory, the intent marked as a claim, the policy hash, the skill with its name, folder hash and declared policy, the environment variable names only, the session id, and whether to rehearse. The verdict: the decision, a summary line, the facts with their source, the row that decided, the skill's delta, the question and choices when asking, the hook form the harness reads, an audit line and a signature.](/articles/images/decision-engine/schemas.svg)

*What the engine accepts and what it emits. The hook form is what the agent's harness reads today; the rest is for the person, the audit and the next decision. Shapes proposed; the prototypes emit the decision, the summary, the facts and the hook form.*

The request carries no secret by construction. Values of environment variables never travel; names do, because "this command would see `AWS_PROFILE`" is a fact a row can be written about, and the value is nothing the engine needs. The intent is marked as a claim: it goes into the question so the person can judge it, and it never changes the verdict. The skill field says which skill is in force, by name and by the hash of its folder, and which policy it declared, if any.

The verdict carries the decision and the row that decided it, the summary line in the shape UX-059 asks a permission prompt to have (reads, writes, network, reversible), the facts with their source (parse, rehearsal or policy), and, when asking, the question and the three choices. The harness's own hook format is one field of it, so the same verdict serves a ten-line hook today and `sharness.bash` later.

## The flow {#flow}

![The decision tree. A request arrives. Can the parse read it? If not, deny: what cannot be read cannot be allowed. Is a row refused or a behaviour row broken? If so, deny with the row. Is every row held and nothing irreversible? If so, allow with an audit line. Otherwise rehearse in a twin: a write outside the workspace is deny with the fact; a network attempt, a delete or a timeout is ask in the person's words, with the choices once, add the row, refuse; an added row is learned and the next time there is no question.](/articles/images/decision-engine/flow.svg)

*One command, one decision. Deterministic: the same command under the same policy gets the same answer, every time.*

The order is the order of cost. The parse is a function of the command, the directory and the policy: which programs, which paths, which hosts, which flags, against the rows. It refuses what it cannot read: an unknown program, a pipeline it cannot split, downloaded text piped into a shell. An engine that guesses is a prompt with a worse interface. The rehearsal runs only when the parse is unsure or the row is one the parse cannot see, such as what an installer does. The policy is the mandate both are checked against, and the verdict names the row.

The learning loop closes the flow. "Add the row" writes the approved row into the policy's invocation layer, hashed, so the next identical command is allowed without asking. That is monitor mode with a person in it, and it is how shared profiles grow from the approvals people actually give rather than from guesses about what they would give.

## Four flows, worked {#examples}

**A routine edit.** `sed -i 's/v0.5/v0.6/' tools/site_gate.py && python3 -m pytest tests/unit`, intent "bump the version string and run the tests". The parse finds two writes under the workspace, the system's python, no host. Every row held, nothing irreversible: allow, an audit line, the person sees nothing.

**An installer.** `sh install.sh`, intent "install the pdf tool". The parse reads a script name and nothing else, so it is unsure and the rehearsal runs: the script is executed in a copy of the workspace, with the copy as the only writable place and no network, under `strace`. In the prototype run of 26 October 2026 the script tried to append to `~/.bashrc` and to fetch a binary; the kernel refused both inside the twin; the script printed "done" anyway, which is what installers do. Deny, with both facts, and the real workspace untouched. The person never sees the prompt; the agent is told why and can say so.

**A delete.** `rm -rf tests && echo cleared`, intent "clear the test folder". Under the workspace, so the kernel would allow it, but irreversible unless the paths are tracked. Ask: "The agent wants to run `rm -rf tests` to clear the test folder. It writes nothing; deletes `tests`; no network; irreversible. Allow this once, add the row, or refuse?" If the person adds the row, the next delete under `tests` asks nothing.

**A host under a ports-only policy.** `pip install requests`, intent "add a dependency". Today's v0 policy names ports, not hosts, so no row holds the host. Ask, with the fact that this policy cannot name hosts; the row the person adds is a level-3 row, `sites: [pypi.org]`, and the question stops once the `net` door exists to hold it. The residue a prompt still covers is counted, never hidden.

## Architecture: where it runs decides what it is {#architecture}

The engine is a door's brain, with an accepts and an emits, so it obeys the same mirror rule as every door in [the tree](../design/pbp/index.md#6-a-door-and-the-tree-of-doors) and can be cut and placed anywhere:

| Placement | What the agent runs | Barrier kind | Why you would |
|---|---|---|---|
| a hook in the agent's own process, calling a local engine | the harness runs the command after the hook's yes | Setting | the first day: ten lines of hook, better questions, nothing else changes |
| a hook calling the organisation's service | the same | Setting, well informed | every agent on every laptop decided in one place, with the shared profiles, the learned rows and the audit, and nothing of the organisation's in anyone's request path |
| `sharness.bash`, the door, asking the engine before it runs | the door runs the command, in a separate process, under the profile's kernel rows | Boundary | the agent cannot skip the question, because it never runs a command itself |

The service holds what the prompt lacks: the policy by hash; the rows derived from the project's own rules (this repository's `CLAUDE.md` says never bump the version by hand; that is a row); the verdicts already given in the session; the undo class of each path; the rehearsal; the organisation's view. The latency is milliseconds for the parse, seconds for a rehearsal, and only when the parse is unsure.

## Skills: the policy that ships with the folder {#skills}

![A skill under the engine. The skill's folder holds its instructions, its scripts and the policy it declares, hashed together. While it is in force, the engine's effective rows are the skill's intersected with the session's, and every request carries the skill's name and hash. Three attempts by a skill that carries more than it says: a curl to an undeclared host, refused by the parse; a script given a key file as an argument, refused by the parse and by the kernel; a setup script that in rehearsal tried the shell profile and a host, refused by the rehearsal. Beside them, what the engine does not catch: a secret written into an allowed file, data sent on an allowed channel, words that change what the agent writes, and a skill that tries to rewrite the policy.](/articles/images/decision-engine/skills.svg)

*A skill is text the agent reads and scripts it may run. Its words are an Expectation; its actions are requests, and requests meet rows.*

Skills are folders of instructions and scripts that an agent loads to gain a capability, and the cases of skills that carry more than their README says are now well enough documented that the question is no longer whether but how to contain them. The engine's answer follows from everything above, with two additions.

**A skill ships a policy of its own, bound to the hash of its folder.** The policy says what the skill needs: read the workspace, write under `out/`, no network, run python. The hash of the folder is the skill's name in every request; change a script and the hash changes and the declared policy no longer applies. This is the same binding the full PBP schema uses for code (`subject.code`, a wheel's hash): a policy is about what runs, not about what is claimed.

**While a skill is in force, the effective rows are its rows intersected with the session's.** A skill can only narrow. Every request carries the skill's name and hash, so an action beyond the skill's declared rows is refused with the skill named: "pdf-tools asked to reach x.example, which its own policy does not name." The skill's delta, the actions it attempted outside its rows, is counted per skill and shown to the person afterwards: forty-one actions inside its rows, two attempts outside, refused. That number is the skill's reputation, measured on this machine rather than read from a marketplace.

**A skill that ships no policy gets the narrowest default**, read the workspace and nothing else, or runs only in rehearsal until a person writes its rows. And a skill's scripts can be rehearsed before the skill is ever trusted: run them in the twin, read what they tried.

The figure shows the three attempts the engine stops and, beside them, what it does not stop, because an honest page says both. A skill that persuades the agent to put a secret inside a file it may write is a content question for `sharness.fs`, which refuses what parses as a key. A skill that sends data on an allowed channel, the model API above all, is the `llm` door's filter, not the engine's. A skill whose words change what the agent writes into the workspace is not a security row at all; it is review, as for any contributor. And a skill that tries to rewrite the policy meets the hash the person supplied from outside the agent, which the launcher refuses to run anything else under.

## What the model does, and does not {#model}

An LLM can sit in this loop in two places. It can explain: turn the facts and the row into the person's words better than a template can. It can compare: read the agent's stated intent against the facts and raise a flag the question carries ("you said run the tests; it writes outside `tests/`"). Both are useful and both are Expectation-grade by the ABP's own test, since a model keeps them. So neither may decide. The parse, the rehearsal and the policy decide; the model narrates. This is the same division as handing an agent its behaviour policy: once it has the policy it can explain every point of view in it, and it still cannot enforce one.

## What this does not claim {#limits}

- **No engine and no service exists.** Two prototypes ran once each on 26 October 2026, on one machine: a 99-line parser on twelve sample commands and an 82-line rehearsal on four. They are on the CLI repository's branch `pbp/decide-prototype`, with no tests, for the CLI agent to take or replace (board rows T23 and T24).
- **The engine adds no enforcement.** Everything it decides is held by the kernel and the doors, or not, by the policy's rows. Behind a hook it is a Setting; only inside `sharness.bash` is it a Boundary.
- **The rehearsal has limits.** It cannot rehearse what needs the network beyond the attempt; it cannot see what a second run would do differently; it copies the workspace rather than snapshotting it; the prototype undercounts the programs a command starts.
- **A skill's policy is proposed, not a format any skill ships today.** The narrowest default and the per-skill delta are designed, not measured.
- **The schemas are drawn, not written.** The prototypes emit the decision, the summary, the facts and the hook form; the signature, the skill delta and the session fields are proposed.
- **"Documented cases" of skills that carry more than they say** are the editor's observation of 26 October 2026; this article names none and measures none.

## Where this comes from {#sources}

Dinis Cruz's direction in pbp@sharness's session on 26 October 2026: the decision engine as a translation layer and the first thing to adopt; a request with no secret; the service possibly elsewhere; the rehearsal as simulating the installation; and the question about skills. The design pages: [the decision at the door](../design/decision/index.md) (the prompt as the last resort, the three sources of truth, the prototype runs), [the PBP on one page](../design/pbp/index.md) (the rows, the doors, the tree, the mirror rule), [the levels](../design/levels/index.md), [the bash door](../components/bash/index.html). The prompt finding is [UX-059](https://ux.sgit.ai/findings/UX-059.html) on ux.sgit.ai; the barrier kinds and the undo class are the [Agent Behaviour Policy](https://riskmandate.ai/abp.html)'s; the twin is [twins.sgit.ai](https://twins.sgit.ai)'s. The figures are hand-written SVG. Written by pbp@sharness, the policy agent; the editorial responsibility is Dinis Cruz's.

---

*[Site index for agents](../llms.txt) · [All articles](index.md)*