core/src/permission-rules

The permission policy pi runs under (#446, #496): ENSO_HOME/permissions.json, in @gotgenes/pi-permission-system’s format, never a copy of another tool’s settings.

gotgenes reads its policy from one place only, <agentDir>/extensions/pi-permission-system/ config.json, and there is no setting to point it elsewhere. So preparePermissionPolicy makes that path a symlink to the user’s file. The file stays where #446 put it, and gotgenes’ reload on change still works, since it follows the link and stats the target.

It also writes the mode agent files (permission-modes.ts) beside pi’s other agent files, because gotgenes reads a mode’s preset from there.

⚠ gotgenes reads a file it cannot parse as an EMPTY policy, and an empty policy has no deny rules at all: every call asks. That is why an unreadable file refuses the launch here rather than being passed on. A file the user breaks while a session runs still reaches gotgenes that way; nothing here can stop that.

Only plain JSON is accepted. gotgenes also strips JavaScript-style comments before it parses, so every file this module accepts, it reads the same way. A commented file is refused here even though gotgenes would read it; that is the safe direction.

Permission mode

PermissionPolicyPreparation

PermissionPolicyPreparation = { catchAllAdded: readonly string[]; kind: "kept"; movedAside?: string; path: string; surfaces: number; } | { kind: "seeded"; movedAside?: string; path: string; piccBackup?: string; was: "absent" | "without a permission block" | "a picc rules file"; } | { kind: "unreadable"; path: string; reason: string; }

Defined in: core/src/permission-rules.ts:165

What preparePermissionPolicy found and did with the user’s file.

• kept: the file holds a permission block; it is used as it is.
• seeded: the file now holds ENSO_DEFAULT_PERMISSION_POLICY. It was absent, held no permission block, or was a picc rules file (#496; that file is kept beside it, at piccBackup, and its rules are not carried over).
• unreadable: the file is there but is not a JSON object (or is a link to nothing); nothing was written, and the caller refuses to start.

movedAside names where a regular file found at the engine’s config path was moved to (see linkEngineConfig), so the launch log says so. catchAllAdded names the surfaces of a kept file that got Enso’s catch-all put first (withCatchAllFirst), so the log says that too.

---

ENSO_DEFAULT_PERMISSION_POLICY

const ENSO_DEFAULT_PERMISSION_POLICY: object

Defined in: core/src/permission-rules.ts:79

The policy a fresh ENSO_HOME starts with.

• Tools: reads and searches run, as do Enso’s ask_user and web_search; edits and writes ask; anything unnamed asks ("*"), web_fetch included.
• Catch-alls: every map starts with Enso’s catch-all, ** (ENSO_CATCH_ALL): the one key a mode changes, and the pattern auto may answer. A rule a user adds after it is theirs, and beats every mode (#498, #499).
• Bash: asks, except gotgenes’ documented read-only allowlist (its “Read-Only Bash Command Allowlist” recipe, trimmed of less/more, which can escape to a shell). The allowlist is safe to seed because gotgenes resolves a chain to its most restrictive part and floors wrappers (sh -c, sudo, xargs) to ask.
• Git: the escapes Enso’s guards do not already refuse are denied (force-push is cc-safety-net’s git.push-force).
• .env files: denied for every tool and every bash command, through symlinks too.
• Outside the project: asks.
• auto mode: authorizerChain names Enso’s classifier link. The link defers in every other mode, and a user who removes the name gets prompts in auto, never fewer.

⚠ path_write is allow inside the project on purpose. gotgenes checks a bash path argument against BOTH directions unless the command is one of its pure readers, so ask here made git diff src/a.ts ask (probed). The cost: an allowlisted command’s redirect (cat a > b) writes inside the project without asking. Writes outside still ask through external_directory.

⚠ git commit * -n* is deliberately absent: it would also deny a commit whose MESSAGE contains -n. -n right after commit is still denied.

Type Declaration

authorizerChain

readonly authorizerChain: readonly ["enso-auto"]

permission

readonly permission: object

permission.*

readonly *: "ask" = 'ask'

permission.ask_user

readonly ask_user: "allow" = 'allow'

permission.bash

readonly bash: object

permission.bash.**

readonly **: "ask" = 'ask'

permission.bash.cat *

readonly cat *: "allow" = 'allow'

permission.bash.cmp *

readonly cmp *: "allow" = 'allow'

permission.bash.date

readonly date: "allow" = 'allow'

permission.bash.df *

readonly df *: "allow" = 'allow'

permission.bash.diff *

readonly diff *: "allow" = 'allow'

permission.bash.du *

readonly du *: "allow" = 'allow'

permission.bash.fd *

readonly fd *: "allow" = 'allow'

permission.bash.find *

readonly find *: "allow" = 'allow'

permission.bash.git blame *

readonly git blame *: "allow" = 'allow'

permission.bash.git branch

readonly git branch: "allow" = 'allow'

permission.bash.git commit –no-verify*

readonly git commit –no-verify*: "deny" = 'deny'

permission.bash.git commit -n*

readonly git commit -n*: "deny" = 'deny'

permission.bash.git commit * –no-verify*

readonly git commit * –no-verify*: "deny" = 'deny'

permission.bash.git diff

readonly git diff: "allow" = 'allow'

permission.bash.git diff *

readonly git diff *: "allow" = 'allow'

permission.bash.git log

readonly git log: "allow" = 'allow'

permission.bash.git log *

readonly git log *: "allow" = 'allow'

permission.bash.git ls-files *

readonly git ls-files *: "allow" = 'allow'

permission.bash.git push –delete *

readonly git push –delete *: "deny" = 'deny'

permission.bash.git push * –delete *

readonly git push * –delete *: "deny" = 'deny'

permission.bash.git remote -v

readonly git remote -v: "allow" = 'allow'

permission.bash.git show *

readonly git show *: "allow" = 'allow'

permission.bash.git status

readonly git status: "allow" = 'allow'

permission.bash.git status *

readonly git status *: "allow" = 'allow'

permission.bash.grep *

readonly grep *: "allow" = 'allow'

permission.bash.head *

readonly head *: "allow" = 'allow'

permission.bash.ls

readonly ls: "allow" = 'allow'

permission.bash.ls *

readonly ls *: "allow" = 'allow'

permission.bash.pwd

readonly pwd: "allow" = 'allow'

permission.bash.rg *

readonly rg *: "allow" = 'allow'

permission.bash.sha256sum *

readonly sha256sum *: "allow" = 'allow'

permission.bash.stat *

readonly stat *: "allow" = 'allow'

permission.bash.tail *

readonly tail *: "allow" = 'allow'

permission.bash.tree *

readonly tree *: "allow" = 'allow'

permission.bash.uname *

readonly uname *: "allow" = 'allow'

permission.bash.wc *

readonly wc *: "allow" = 'allow'

permission.bash.which *

readonly which *: "allow" = 'allow'

permission.bash.whoami

readonly whoami: "allow" = 'allow'

permission.edit

readonly edit: object

permission.edit.**

readonly **: "ask" = 'ask'

permission.external_directory

readonly external_directory: object

permission.external_directory.**

readonly **: "ask" = 'ask'

permission.find

readonly find: "allow" = 'allow'

permission.grep

readonly grep: "allow" = 'allow'

permission.ls

readonly ls: "allow" = 'allow'

permission.path_read

readonly path_read: object

permission.path_read.*.env

readonly *.env: "deny" = 'deny'

permission.path_read.*.env.*

readonly *.env.*: "deny" = 'deny'

permission.path_read.*.env.example

readonly *.env.example: "allow" = 'allow'

permission.path_read.**

readonly **: "allow" = 'allow'

permission.path_write

readonly path_write: object

permission.path_write.*.env

readonly *.env: "deny" = 'deny'

permission.path_write.*.env.*

readonly *.env.*: "deny" = 'deny'

permission.path_write.**

readonly **: "allow" = 'allow'

permission.read

readonly read: "allow" = 'allow'

permission.web_search

readonly web_search: "allow" = 'allow'

permission.write

readonly write: object

permission.write.**

readonly **: "ask" = 'ask'

---

describePermissionPolicy()

describePermissionPolicy(preparation): string

Defined in: core/src/permission-rules.ts:445

The line both launch surfaces log for a preparation that did not refuse, in the same words on the web host and the terminal launcher, so a reader finds one in the logs by the other.

Parameters

preparation

{ catchAllAdded: readonly string[]; kind: "kept"; movedAside?: string; path: string; surfaces: number; } | { kind: "seeded"; movedAside?: string; path: string; piccBackup?: string; was: "absent" | "without a permission block" | "a picc rules file"; }

Returns

string

---

permissionEngineConfigPath()

permissionEngineConfigPath(agentDir): string

Defined in: core/src/permission-rules.ts:145

Where gotgenes reads its policy, under pi’s agent directory.

Parameters

agentDir

string

Returns

string

---

preparePermissionPolicy()

preparePermissionPolicy(policyPath, agentDir): PermissionPolicyPreparation

Defined in: core/src/permission-rules.ts:395

Make policyPath a policy gotgenes will use as it is, and put it and the mode presets where gotgenes reads them:

• keep a file that holds a permission block;
• seed one that is absent, holds none, or is a picc rules file;
• refuse one that is not a JSON object, touching nothing.

Seeding keeps every other top-level key the file had, except a picc file, which is replaced whole (its copy is kept beside it; replacePiccRulesFile names it).

Call it before the extension loads, on both launch surfaces.

Parameters

policyPath

string

agentDir

string

Returns

PermissionPolicyPreparation

---

replacePiccRulesFile()

replacePiccRulesFile(policyPath): string | undefined

Defined in: core/src/permission-rules.ts:269

Move a picc rules file aside and write the seed in its place, returning the backup’s path, or undefined when the file was already gone.

⚠ TWO LAUNCHES MAY BOTH DECIDE TO MIGRATE (#497 review): the web host and the terminal, on a home not yet migrated, each read the picc file before either moved it. So this step runs with a decision that may be stale, and whatever it moves, moveAside never overwrites an earlier backup: the user’s rules stay in the first one (.picc-backup), and a late launch’s copy of the seed, or of the same rules, lands in .picc-backup.1. When the file is already gone (the other launch moved it and has not written the seed yet), the caller reads again rather than failing.

Parameters

policyPath

string

Returns

string | undefined