Repository navigation
Releases
@nodrail/policy-engine 0.4.0
Added
- Setup resources (preview,
apf.nodrail.com/v1alpha1):nodrail.yamlmay
sayruntime,team,resourcesandstart, and the resources declare
Agent,Team,PolicyandPolicyBinding.resolveProjectreads them
intosetupand locks their files. APolicyBindingrenames the roles a
module or Policy names to the team's agents, inagent, gaterequiresand
since, budgetstep_agentandkind: agentresources. It refuses a name
nobody plays, a role the policy doesn't name, two roles for one agent, and an
agent off the team. A project without resources resolves as before. - A started Team adds its own rules, last: each member may start only the
members it hands off to, and no agent may change.claude,.codex,
.agents,.nodrail,nodrail.yamlornodrail.lock.yaml. Both are
denies, on Claude Code and on Codex. Codex's calls on agents already
started (wait, send input, close…) are allowed.teamRulesand
SETUP_PLACESare exported. - The hook reads Codex's own agent calls: starting one
(collaborationspawn_agent,spawn_agent) istool: codex,
operation: agenton itsagent_type, asclaude-codeagentis for
Claude Code; the other collaboration calls aretool: codexwith their own
operation, such aswait_agent. Before, Codex handoffs read as unknown
Claude Code tools. - A started Team's rules also deny agents running
nodrail,
nodrail-policyandnodrail-claude-hook, so none can lock and apply a
setup it changed. hook --protect-list <file>protects the files a list names, as it
protects its rule files: any file tool that would change one is denied,
and a list that can't be read blocks.- With
--protect-list, the hook also denies shell commands naming a setup
file, the list,~/.nodrail, or Nodrail itself by any path, whatever the
rules allow. hook --host codexdenies a call that needs a review, with the reason:
Codex treats anaskanswer as a failed hook and runs the call.- A binding is refused when two names its policy uses would be one agent,
including a role mapped onto an agent the policy already names. Role names
likeconstructorare plain names. An agent's instructions and skills
can't come from.claude,.codex,.agentsor.nodrail. - The hook also judges a shell command that only reads one file or searches
a folder (cat,head,tail,nl,wc,sed -n '<lines>p',grepon
one file,ls,rg) as that file read or search, and the stricter
decision holds. The file rules, secrets included, decide reads made through
a shell as they decide the Read and Grep tools, and rules about commands
keep their meaning. Paths the shell would expand, hidden-file searches and
recursive grep stay commands. This is how Codex reads files. - The read-only and repo-work packs allow Claude Code's task tools
(TaskCreate,TaskUpdate,TaskList,TaskGet) andToolSearch. ProjectHost.list, optional, lists a folder's.yamlfiles for
resources: ./folder.renameAgentsis exported.
Changed
- The local hook judges each call as the agent Claude Code or Codex says made
it: a subagent's type, or the session'sclaude --agent.--agentnames
the entry agent, for calls the host doesn't label. Before, every call in a
session was judged as--agent. A rule for that agent no longer covers its
subagents' calls; give them their own rules.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/policy-engine/v/0.4.0
@nodrail/client 0.4.0
Released with @nodrail/policy-engine 0.4.0, which it uses. The hook
describes Codex's agent calls as that version does: starting one
(collaborationspawn_agent, spawn_agent) is tool: codex,
operation: agent on its agent_type, and the other collaboration calls are
tool: codex with their own operation. Before, they read as unknown Claude
Code tools. Otherwise the client and its hook behave as in 0.3.0.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/client/v/0.4.0
@nodrail/cli 0.2.0
Added
nodrail.yamlmay point at setup resources (preview): agents, a team, your
own policies and the bindings that give a module's roles to your agents.
policy lockandexport --frozenread them, folders included; see
Give the roles to your agents.nodrail plan(preview) shows whatnodrail applywould set up for the
team on Claude Code: agent files, skills, the effective policy and the
settings that start the entry agent behind the policy hook. It only reads,
marks with!anything apply would refuse (a file it didn't write, one
edited since, a link, a missingclaudeornodrail, a stale lock), and
exits with 1 then.--jsongives the same for scripts.nodrail apply(preview) makes that plan, after showing it and asking (or
--yes). It refuses anything marked!, re-plans as the project's only
writer and stops if anything changed since you saw it, and journals every
change so that a stop partway is finished by the nextnodrail. It
changes and removes only the files it wrote and that still hold what it
wrote, records them in.nodrail/setup-state.json, and opens Claude Code
withstart: true.nodrail planandapplyset up Codex too (runtime: codex): the entry
agent in.codex/config.toml, the other members in.codex/agents/, skills
in.agents/skills/and the hook in.codex/hooks.json, which denies when
nodrailcan't run. Codex runs a project's hooks only once the person
trusts the folder and the hook; nodrail asks Codex, read-only, whether it
does, says which step is missing, andapplyexits with 1 until then.applywrites.nodrail/protected.txt, every file the setup is made from,
and both hooks pass it with--protect-list, so no agent can edit the
resources, policies, instructions or skills and apply them. On Codex the
hook's command changed: trust it again in/hooksafterapply.applynever takes a file that merely matches what it would write: only
files it created or updated are its own, so it never removes yours..claude/settings.jsonbehind a link, or withdisableAllHookson, is a
conflict. The Codex hook runs with--host codex. The write lock is
claimed whole, so two nodrail processes can't both hold it.@nodrail/read-only1.0.1 is the updated read-only pack.applysays what an open session picks up: a new session for changed
agent files, skills or settings; the policy from the next tool call.@nodrail/open-reviewed-prand@nodrail/merge-reviewed-pr1.0.1 declare
thedevrole their gates already use, so a binding names every role it
must map. A project locked at 1.0.0 stays there until it adds 1.0.1.
Changed
nodrail policyis@nodrail/policy-engine0.4.0's. Its hook judges each
call as the agent the host says made it, not always as--agent; reads
Codex's agent calls; judges shell reads such ascatandrgas the file
reads they are; and adds--protect-listand--host codex. See the
engine's changelog.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/cli/v/0.2.0
@nodrail/policy-engine 0.3.0
Project manifests, a permission diff, and a safer reading of file paths.
Added
resolveProject(@nodrail/policy-engine/yaml) composes a project's
nodrail.yaml(kind: nodrail.project/v1): ordered imports of local rules
files, nested manifests and catalog modules with typed values (with: { repository: owner/name }). A file shared by two imports is applied once.
Cycles, paths or links that leave the project folder, unknown publishers,
versions in the manifest and conflicting values are refused, each naming the
reference. It reads only what its host gives it, so it runs in a browser too.
catalogEntry,canonicalId,parseModuleRef,bindingsUsedand
joinPathare exported with it.permissionChanges(before, after)andrenderPermissionChanges(changes)
(also from the package root): what an edit does to permissions, grouped by
agent, operation and resource, as granted, revoked, tightened, loosened,
changed or needs review. A change that weakens a deny, a gate or a budget is
marked!. Checked against the evaluator with generated policies.@nodrail/policy-engine/command-lineexportsrunPolicyCommandLine(argv, io):nodrail-policyas a function, whichnodrail policyruns.- File calls carry
file_name, the file's own name, so a rule can allow files
by name without matching folders that share it.
Changed
- The
read-onlystarter pack also denies runningnodrail, which can
approve requests.repo-workprotectsnodrail.yaml,nodrail.lock.yaml
and.nodraillike the other control places. nodrail-policywith a rules file it can't read prints the reason and exits
2, instead of ending with an uncaught error.nodrail-policy --versionprints the engine's own version when bundled into
another command.
Fixed
- A link to a file that doesn't exist yet is judged by its target. Writing
through it creates the target, which could otherwise pass a rule that
protects that place, such asrepo-work's shell startup files.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/policy-engine/v/0.3.0
@nodrail/client 0.3.0
Released with @nodrail/policy-engine 0.3.0, which it uses; the client and its
hook behave as in 0.2.1. Its dependencies are updated.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/client/v/0.3.0
@nodrail/cli 0.1.0
First release: your Nodrail workspace from the terminal, with a personal API
token (ndp_…).
nodrail login,logoutandwhoami. The token is saved in
~/.nodrail/cli.json, readable only by you;NODRAIL_TOKENalways wins.nodrail approvals(with--watch),approve <id>andreject <id>, which
show exactly what is being decided and ask before deciding unless--yes.nodrail activity,runs,run <id>andinsights, with the filters of
the Activity page.nodrail rules pullandrules push, which previews, shows the diff and
publishes exactly what was previewed.nodrail policy: the policy engine's offline commands (init,validate,
compile,eval,test,check,exec,hook,runs), the same as
nodrail-policy, with no account.nodrail add,nodrail policy lockandnodrail policy export --frozen:
a repository's policy asnodrail.yamlandnodrail.lock.yaml, offline.
Lock shows the permission changes since the last committed lock; frozen
export prints one APF file only when every file, version and value matches
the lock. Writes are staged in your home and can't be left half done.- A catalog shipped in the package:
@nodrail/read-only,
@nodrail/open-reviewed-pr(also@nodrail/pr_policy.yaml),
@nodrail/merge-reviewed-pr,@nodrail/triage-issuesand
@nodrail/dependency-updates. --jsonon every command,--environment, andNODRAIL_URLor--urlfor
self-hosting.@nodrail/cli/api: the typed API client the command uses.
@nodrail/policy-engine 0.2.1
Package metadata and documentation only; the engine, CLI and hook behave
as in 0.2.0.
- npm description: "Compile, test and evaluate Agent Policy Format (APF)
rules locally. Includes the CLI, TypeScript evaluator and local Claude Code
hook." Keywords addapfandagent-policy-format. - The quickstart starts in an empty folder with a two-rule policy, three
proposed commands (allow, deny, none) and three CI cases. - Gates, budgets and the
runscommand are marked as preview and name the
engine release that has them.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/policy-engine/v/0.2.1
@nodrail/client 0.2.1
Package metadata and documentation only; the client and its hook behave
as in 0.2.0.
- npm description: "TypeScript client for Nodrail Cloud. Check supported tool
calls against workspace policies and coordinate human approvals." Keywords
addtool-permissions. - The run-history walkthrough is marked as preview and names the client
release that hasinRunandstep.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/client/v/0.2.1
@nodrail/policy-engine 0.2.0
Gates, budgets and receipts. Engine level 3.
Breaking
- Starting a Claude Code subagent (
Agent, andTask, its earlier name) is
described with the subagent's type as resource{ kind: agent, id: <type> }
instead of{ kind: tool, id: Agent }. A rule fortool: claude-code,
operation: agentwith resource kindtoolis now a compile error that
points to
Upgrading rules for subagents,
instead of quietly never matching. - A file with gates or budgets compiles to document
version: 2, which
earlier engines reject.validatereports what the files compiled to, such
asOK, compiled to 150 rules, 2 gates and 1 budget., instead of
OK: N rules.The counts are compiled entries: a command prefix rule
compiles to two. - The hook's run key is
NODRAIL_RUN, else<repo>/<branch>(theorigin
remote as host/owner/name, with no credentials, or the repository folder's
name), pinned to the Claude Code session by its first event, so switching
branch doesn't change the run. On the default branch, a detached HEAD or
outside git it issession:<id>. - A budget that covers an action decided with no run applies its
otherwise,
as a gate with no history holds.eval,checkandexecdecide with no
run, so they hold too.
Upgrading: change rules for starting a subagent to the new resource.
# Before
- rule: Start subagents
tool: claude-code
operation: agent
resource: { kind: tool, match: exact, value: Agent }
effect: allow
# After: any subagent, or match: exact, value: qa for one type
- rule: Start subagents
tool: claude-code
operation: agent
resource: { kind: agent, match: any }
effect: allowAdded
gateentries: an action that matches waits until named steps started and
finished with accepted verdicts after the last work, otherwisedenyor
require_approval. A gate never allows on its own. Work is anything the
sinceagents did, and any change by another agent than the one required:
files written, edited, patched or deleted, and shell commands other than
the read-only pack's look-around ones.isChange(descriptor)from the main entry says whether an action is such a
change; action events takechange: true. Old events without it are not
changes.budgetentries: tool calls per step or run, tokens and dollars per run,
with a warning level.simulate()takes the run's history and reports gates, budgets and
warnings with every decision.parseReceipt()andreceiptBlock()in@nodrail/policy-engine/receipts
read the receipt an agent ends its step with. They read only the last 16 KB
of a message, and a block overMAX_RECEIPT_TEXT(8192 characters) is no
receipt, as in Cloud.legacySubagentRuleProblem()from the main entry, the compile check above
for a rule form.renderPolicies()keeps gates and budgets.nodrail-policy hookkeeps a run ledger when the rules have gates or
budgets: steps fromSubagentStartandSubagentStop, receipts from the
last message, every decided action. One JSON Lines file per run in the
repository's git folder, with session pins next to it. Each decision reads,
decides and records under a lock file; a call that waits over 5 seconds is
blocked. A last line cut off mid-write is left out. Rules without gates or
budgets never touch it.nodrail-policy hookdenies any file tool change to the rule files and
folders it loaded, before reading the rules.nodrail-policy runs,runs show <run>andruns report.@nodrail/policy-engine/hook-runs:runKey(),receiptBlock(),
MAX_RECEIPT_TEXTandagentName()for hooks that report runs elsewhere,
with no zod or YAML.- Cases files take
runandstep, so gates and budgets can be tested in CI.
{ action: <agent>, command: <line> }records a command; afinishedwith
no open step records a whole step. - A decision held by a used-up budget says so: "Budget … is at 61 of 60 tool
calls. Over the limit, …".
Changed
- Problems in rule files point at what is wrong: an unknown key (
efect:)
at that key, a bad value, also insiderequiresorresource, at that
value, a duplicate at its name orid, an unknown list at where it is
named,required_engine_versionat its value, and an item appended by an
override in the file that appended it. They were at the start of the entry,
some at column 1. Onlylineandcolumnchange; an issue has just
file,line,columnandmessage. - Gates and budgets only make the rules' decision stricter. An action no
rule covers stays blocked when an unmet gate or used-up budget only asks
for a review. - Both starter packs allow starting a Claude Code subagent. What it then does
is still decided call by call. - Both starter packs deny running
nodrail-policyandnodrail-claude-hook
from the shell.repo-worksends writes to.npmrcto a person.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/policy-engine/v/0.2.0
@nodrail/client 0.2.0
Runs and steps for any agent framework, so gates and budgets work outside
Claude Code.
Breaking
- Starting a subagent in Claude Code (
Agent, andTask, its earlier name)
is now governed, as toolclaude-code, operationagent, resource type
agentwith the subagent's type as id. Without a rule that allows it, each
start waits for a person. Upgrading: add a rule that allowsclaude-code
agentfor the subagent types you use. Rule files with a rule for the
earlier resource (typetool, idAgent) no longer compile. - The Claude Code hook's run key is
NODRAIL_RUN, else<repo>/<branch>
pinned to the session by its first event, so switching branch doesn't
change the run. On the default branch, a detached HEAD or outside git it is
session:<id>. The repository is theoriginremote as host/owner/name,
with no credentials. Pins are kept in.git/nodrail/sessions.
Added
- A block says why when Cloud does: a gate tells the agent to run the steps
it waits for (such as QA or review) after the last change and try again; a
used-up budget and a paused agent are named too. createNodrail({ run }), orNODRAIL_RUN, sets the run calls belong to;
nodrail.inRun(key, work)sets it for one piece of work.nodrail.step(agent, work)records a step around an agent's work. Calls
made while it runs belong to it, through a framework's tool loop too, and
the verdict is read from the result withreceiptOf, or by your own
function passed as{ receipt }.authorize()takesrun: { key, step? }and sends it with the intent, so
the server can decide gates and budgets on the run's history. The run is not
part of the descriptor digest.client.step()records a step starting or
finishing.- The Claude Code hook sends each intent's run and step, and records
SubagentStartandSubagentStopas steps with the receipt block. Recording
a step never blocks the agent. - The Codex hook sends the run with each call. Codex doesn't say which
subagent makes a call, so every call is the main agent's. - A call that stops waiting for a person withdraws its request, so it leaves
Approvals instead of waiting there for someone to approve a call that will
never run.authorize()does it whenwaitMspasses or its newsignal
aborts, and the Claude Code and Codex hooks at their own deadline too. It is
best effort and takes at most 3 seconds; the call is blocked either way.
WithwaitMs: 0the request stays open, to be decided later.
client.withdraw(actionId)sends it by hand; it never allows anything.
Changed
- Receipts are read from the last 16 KB of a message only, and a block over
8 KB is no receipt, in the hook and inreceiptOfalike, as in Cloud.
Staged on npm with provenance. It installs once a maintainer approves it: https://www.npmjs.com/package/@nodrail/client/v/0.2.0