How it works
Package authority is not just what a package says it needs. It is the authority that exists at runtime after installation, loading, configuration, credential binding, tool registration, and agent delegation have all combined. In an agent harness, that authority often crosses several surfaces: local files, remote APIs, browser state, tool calls, memory stores, hooks, and generated instructions that steer model behavior.
A useful way to model it is as a sequence:
- The package is discovered, selected, and installed from some source.
- Its code, manifest, prompts, schemas, hooks, or adapters are loaded into the harness.
- The harness grants read, write, network, credential, or tool access.
- The agent decides when to invoke the package or follow its embedded instructions.
- The package produces outputs, side effects, state changes, or new context for later steps.
The important detail is composition. A package with read access to a project, access to a shell tool, and a prompt that can influence planning may have more authority than any one permission label suggests. A package that only formats text has narrow authority. A package that can execute code, read secrets, mutate state, or register hooks has operational authority and must be treated as part of the control plane.
Why it matters in an agent harness
Agent harnesses depend on delegation. Packages make that delegation useful because they carry reusable skills, integrations, tool wrappers, and workflow knowledge. They also widen the system. Each installed package becomes another place where authority can enter, expand, or become ambiguous.
The main engineering outcome is control. If the harness cannot answer what a package can read, what it can write, which credentials it can touch, and which agent steps it can influence, then the operator does not have a real permission model. They have a trust model hidden inside installation state.
Package authority also affects reversibility. A package that only proposes a patch is easy to inspect and roll back. A package that edits files, posts to an API, updates a database, or triggers a browser session needs a stronger execution contract. The harness should know whether the action is idempotent, whether a compensating action exists, and whether the operation can be replayed from an execution trace.
Observability is the next pressure point. Package behavior must be visible at the level where risk is introduced. It is not enough to log that an agent used a skill. The harness should record which package version ran, which permissions were active, which credentials were mediated, which tools were invoked, what state changed, and which approval or policy decision allowed it. Without that, debugging becomes archaeology.
Package authority is also a failure-containment problem. A harmless package can become harmful if it is installed into a broad workspace, receives ambient credentials, or can inject instructions into later agent context. A compromised, stale, or poorly scoped package can turn into a confused deputy: the agent thinks it is using a helper, while the helper uses the agent's broader authority to reach something it should not.
The practical boundary is simple. Package authority should be explicit, inspectable, revocable, and proportional to the work. When a package cannot operate under those conditions, it belongs outside autonomous execution or behind a manual approval checkpoint.
Package authority vs tool permission
The distinction matters because tool permission is usually call-level, while package authority is package-level and lifecycle-level. A tool permission answers, "Can this call happen now?" Package authority asks, "What can this installed unit influence while it exists in the harness?"
| Concept | Scope | Design consequence |
|---|---|---|
| Package authority | Installed package, its code, hooks, prompts, schemas, and granted surfaces | Review at install time, load time, and execution time |
| Tool permission | A specific callable operation or API surface | Gate per invocation, argument, credential, and side effect |
| Credential scope | Which secret or token can be used, and where | Mediate access through the harness rather than passing raw credentials |
| Sandbox scope | Runtime containment for files, process, network, and environment | Limit blast radius even when package logic is wrong |
A package can be low risk even if it exposes several tools, provided those tools are read-only, scoped, observable, and mediated. A package can be high risk with only one tool if that tool executes arbitrary code with broad filesystem and credential access.
This is why I avoid treating manifest permissions as the whole answer. They are a useful declaration, not proof. The harness still needs enforcement, runtime logs, and a way to test that the package cannot exceed its declared boundary.
The Rifty take
We treat package authority as a control-boundary problem, not a marketplace or convenience problem. Installed code is part of the harness once it can steer work, touch state, or receive credentials.
The tradeoff we accept is friction at the boundary. A package that wants broad access should have to justify broad access through explicit scope, visible operation records, and revocation paths. Fast installation is less valuable than knowing what authority has entered the system.
Implementation checks
- Require a package manifest that separates declared capability from granted authority.
- Bind credentials through a mediation layer. Do not hand packages ambient secrets when a scoped token or brokered call will do.
- Separate read, write, execute, network, browser, memory, and hook permissions. Do not collapse them into a single trusted flag.
- Record package name, version, source, permissions, invoked tools, inputs, outputs, and side effects in the execution trace.
- Treat prompt files, examples, and tool descriptions as authority-bearing surfaces when they can influence agent planning.
- Make package authority revocable without deleting unrelated harness state.
- Fail closed when a package asks for undeclared access, an unknown credential, or a write path outside its approved scope.
- Test package boundaries with negative cases: denied files, denied network targets, denied credential access, and disallowed tool arguments.
- Re-review authority when a package updates, changes source, adds hooks, or starts participating in a more autonomous workflow.
- Prefer narrow packages that do one operational job over broad packages that mix research, execution, credential use, and publication in one authority bundle.
Frequently asked questions
Is package authority the same as package permissions?
Package authority is broader than package permissions. Permissions are the declared or granted access labels. Authority is the effective runtime power created by those permissions, the package code, credentials, hooks, prompts, loaded context, and the agent's willingness to delegate work to that package.
When should a package require human approval?
A package should require approval when it can create durable side effects, use sensitive credentials, publish externally, execute arbitrary code, mutate shared state, or widen access beyond the current task. Approval should attach to the specific authority and action, not to vague package trust.
How do we reduce package authority without breaking useful skills?
Reduce package authority by splitting capabilities, scoping credentials, separating read and write paths, sandboxing execution, and granting access per workflow. The goal is not to make packages powerless. It is to give each package the smallest authority that still completes its operational job.
What should be logged for package authority?
Log the package identity, version, source, declared permissions, granted permissions, credential mediation events, tool calls, arguments, outputs, state changes, approvals, denials, and errors. The log should let an operator reconstruct what authority was active and what changed because of it.
What is the main failure mode?
The main failure mode is ambient trust. A package is installed for a narrow helper task, then quietly receives broad filesystem, credential, network, or planning influence. The harness later treats package behavior as normal agent behavior, making the real authority boundary hard to see.