Skip to content

Releases

@nodrail/policy-engine 0.4.0

Choose a tag to compare

@github-actions github-actions released this 18 Nov 15:29
d74805b

Added

  • Setup resources (preview, apf.nodrail.com/v1alpha1): nodrail.yaml may
    say runtime, team, resources and start, and the resources declare
    Agent, Team, Policy and PolicyBinding. resolveProject reads them
    into setup and locks their files. A PolicyBinding renames the roles a
    module or Policy names to the team's agents, in agent, gate requires and
    since, budget step_agent and kind: agent resources. 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.yaml or nodrail.lock.yaml. Both are
    denies, on Claude Code and on Codex. Codex's calls on agents already
    started (wait, send input, close…) are allowed. teamRules and
    SETUP_PLACES are exported.
  • The hook reads Codex's own agent calls: starting one
    (collaborationspawn_agent, spawn_agent) is tool: codex,
    operation: agent on its agent_type, as claude-code agent is for
    Claude Code; the other collaboration calls are tool: codex with their own
    operation, such as wait_agent. Before, Codex handoffs read as unknown
    Claude Code tools.
  • A started Team's rules also deny agents running nodrail,
    nodrail-policy and nodrail-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 codex denies a call that needs a review, with the reason:
    Codex treats an ask answer 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
    like constructor are plain names. An agent's instructions and skills
    can't come from .claude, .codex, .agents or .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', grep on
    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) and ToolSearch.
  • ProjectHost.list, optional, lists a folder's .yaml files for
    resources: ./folder. renameAgents is 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's claude --agent. --agent names
    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

Choose a tag to compare

@github-actions github-actions released this 18 Nov 15:30
d74805b

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

Choose a tag to compare

@github-actions github-actions released this 18 Nov 15:30
d74805b

Added

  • nodrail.yaml may point at setup resources (preview): agents, a team, your
    own policies and the bindings that give a module's roles to your agents.
    policy lock and export --frozen read them, folders included; see
    Give the roles to your agents.
  • nodrail plan (preview) shows what nodrail apply would 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 missing claude or nodrail, a stale lock), and
    exits with 1 then. --json gives 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 next nodrail. 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
    with start: true.
  • nodrail plan and apply set 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
    nodrail can'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, and apply exits with 1 until then.
  • apply writes .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 /hooks after apply.
  • apply never 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.json behind a link, or with disableAllHooks on, 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-only 1.0.1 is the updated read-only pack.
  • apply says 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-pr and @nodrail/merge-reviewed-pr 1.0.1 declare
    the dev role 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 policy is @nodrail/policy-engine 0.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 as cat and rg as the file
    reads they are; and adds --protect-list and --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

Choose a tag to compare

@github-actions github-actions released this 17 Nov 16:09
a99553b

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, bindingsUsed and
    joinPath are exported with it.
  • permissionChanges(before, after) and renderPermissionChanges(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-line exports runPolicyCommandLine(argv, io): nodrail-policy as a function, which nodrail policy runs.
  • 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-only starter pack also denies running nodrail, which can
    approve requests. repo-work protects nodrail.yaml, nodrail.lock.yaml
    and .nodrail like the other control places.
  • nodrail-policy with a rules file it can't read prints the reason and exits
    2, instead of ending with an uncaught error.
  • nodrail-policy --version prints 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 as repo-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

Choose a tag to compare

@github-actions github-actions released this 17 Nov 16:09
a99553b

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

Choose a tag to compare

@github-actions github-actions released this 17 Nov 16:54
a99553b

First release: your Nodrail workspace from the terminal, with a personal API
token (ndp_…).

  • nodrail login, logout and whoami. The token is saved in
    ~/.nodrail/cli.json, readable only by you; NODRAIL_TOKEN always wins.
  • nodrail approvals (with --watch), approve <id> and reject <id>, which
    show exactly what is being decided and ask before deciding unless --yes.
  • nodrail activity, runs, run <id> and insights, with the filters of
    the Activity page.
  • nodrail rules pull and rules 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 lock and nodrail policy export --frozen:
    a repository's policy as nodrail.yaml and nodrail.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-issues and
    @nodrail/dependency-updates.
  • --json on every command, --environment, and NODRAIL_URL or --url for
    self-hosting.
  • @nodrail/cli/api: the typed API client the command uses.

On npm: https://www.npmjs.com/package/@nodrail/cli/v/0.1.0

@nodrail/policy-engine 0.2.1

Choose a tag to compare

@github-actions github-actions released this 14 Nov 13:52
cab2cda

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 add apf and agent-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 runs command 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

Choose a tag to compare

@github-actions github-actions released this 14 Nov 13:52
cab2cda

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
    add tool-permissions.
  • The run-history walkthrough is marked as preview and names the client
    release that has inRun and step.

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

Choose a tag to compare

@github-actions github-actions released this 12 Nov 15:14
c17bacd

Gates, budgets and receipts. Engine level 3.

Breaking

  • Starting a Claude Code subagent (Agent, and Task, its earlier name) is
    described with the subagent's type as resource { kind: agent, id: <type> }
    instead of { kind: tool, id: Agent }. A rule for tool: claude-code,
    operation: agent with resource kind tool is 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. validate reports what the files compiled to, such
    as OK, 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> (the origin
    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 is session:<id>.
  • A budget that covers an action decided with no run applies its otherwise,
    as a gate with no history holds. eval, check and exec decide 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: allow

Added

  • gate entries: an action that matches waits until named steps started and
    finished with accepted verdicts after the last work, otherwise deny or
    require_approval. A gate never allows on its own. Work is anything the
    since agents 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 take change: true. Old events without it are not
    changes.
  • budget entries: 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() and receiptBlock() 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 over MAX_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 hook keeps a run ledger when the rules have gates or
    budgets: steps from SubagentStart and SubagentStop, 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 hook denies any file tool change to the rule files and
    folders it loaded, before reading the rules.
  • nodrail-policy runs, runs show <run> and runs report.
  • @nodrail/policy-engine/hook-runs: runKey(), receiptBlock(),
    MAX_RECEIPT_TEXT and agentName() for hooks that report runs elsewhere,
    with no zod or YAML.
  • Cases files take run and step, so gates and budgets can be tested in CI.
    { action: <agent>, command: <line> } records a command; a finished with
    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 inside requires or resource, at that
    value, a duplicate at its name or id, an unknown list at where it is
    named, required_engine_version at 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. Only line and column change; an issue has just
    file, line, column and message.
  • 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-policy and nodrail-claude-hook
    from the shell. repo-work sends writes to .npmrc to 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

Choose a tag to compare

@github-actions github-actions released this 12 Nov 15:14
c17bacd

Runs and steps for any agent framework, so gates and budgets work outside
Claude Code.

Breaking

  • Starting a subagent in Claude Code (Agent, and Task, its earlier name)
    is now governed, as tool claude-code, operation agent, resource type
    agent with the subagent's type as id. Without a rule that allows it, each
    start waits for a person. Upgrading: add a rule that allows claude-code
    agent for the subagent types you use. Rule files with a rule for the
    earlier resource (type tool, id Agent) 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 the origin remote 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 }), or NODRAIL_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 with receiptOf, or by your own
    function passed as { receipt }.
  • authorize() takes run: { 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
    SubagentStart and SubagentStop as 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 when waitMs passes or its new signal
    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.
    With waitMs: 0 the 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 in receiptOf alike, 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