You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(#2802): standardize tier terminology with descriptive prefixes
Replace bare "Tier N" references across documentation, ADRs, problem
docs, and agent prompts/skills with descriptive-prefix forms to
eliminate ambiguity between the three distinct tier systems in this
codebase:
- "credential delivery tier" for the ADR 0025 four-tier credential
model (tiers 1-4: prefetch, providers, REST server, host files)
- "intent authorization tier" for the intent-representation.md
four-tier change authorization model (tiers 0-3: standing rules,
tactical, strategic, organizational)
- "configuration tier" for the three-tier config inheritance model
(upstream defaults, org config, per-repo overrides)
Add a terminology convention entry to AGENTS.md documenting the
three tier systems and the requirement to always use a descriptive
prefix.
Files updated across 28 docs, ADRs, problem docs, skills, and
agent prompts. External tier references (e.g. "GitLab Free tier")
are left unchanged. Plan docs with already-contextual "fallback
tier" references are also unchanged.
Note: pre-commit and make lint could not run due to sandbox
network restrictions preventing shellcheck installation. The
post-script runs an authoritative pre-commit check on the runner.
Closes#2802
Copy file name to clipboardExpand all lines: AGENTS.md
+12Lines changed: 12 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -144,3 +144,15 @@ least-frequently-run agents.
144
144
-**CODEOWNERS files are always human-owned.** Agents cannot modify their own guardrails.
145
145
-**The repo is the coordinator.** No coordinator agent — branch protection, CODEOWNERS, and status checks are the coordination layer.
146
146
-**Organization-specific content is cordoned.** Core problem docs are general; applied considerations live in `docs/problems/applied/`.
147
+
148
+
## Terminology: tier conventions
149
+
150
+
The term "tier" is used in multiple distinct contexts across this codebase. Always use a descriptive prefix to avoid ambiguity:
151
+
152
+
| Prefix | Meaning | Defined in |
153
+
|---|---|---|
154
+
|**credential delivery tier**| The four-tier model for how agents receive credentials: (1) prefetch + post-process, (2) providers + L7, (3) host-side REST server, (4) host files |[ADR 0025](docs/ADRs/0025-provider-credential-delivery-for-sandboxed-agents.md)|
155
+
|**intent authorization tier**| The four-tier model for change authorization: (0) standing rules, (1) tactical/issue, (2) strategic, (3) organizational |[intent-representation.md](docs/problems/intent-representation.md)|
156
+
|**configuration tier**| The three-tier inheritance model for agent configuration: upstream defaults → org config → per-repo overrides |[ADR 0035](docs/ADRs/0035-layered-content-resolution.md)|
157
+
158
+
**Do not** use bare "Tier N" or "tier" without a prefix — the same number means different things in different contexts (e.g., "Tier 2" could be provider-based credential delivery or strategic intent authorization). External tier references (e.g., "GitLab Free tier", "GitHub plan tiers") are exempt from this convention.
[ADR 0017](0017-credential-isolation-for-sandboxed-agents.md) established a two-tier credential isolation model: prefetch + post-process as the default, and a host-side REST server with L7 enforcement as the fallback. The REST server requires per-endpoint proxy code, input validation, response sanitization, and server lifecycle management — cost that scales linearly with each new external service. Two problems motivate extending the model: reducing the proxy maintenance burden for services where it is unnecessary, and formalizing how agents get fine-grained operation control over external APIs — not just credential isolation, but capability scoping.
26
26
27
-
OpenShell's native provider system addresses the first problem. Providers inject credentials as opaque placeholder tokens that the gateway proxy swaps for real values at the HTTP layer, so credentials never enter the sandbox. The `fullsend run` command already supports providers: the harness layer loads provider definitions from the agent's `providers/` directory, creates them on the gateway via `openshell provider create`, and passes them to sandbox creation — so the infrastructure for tiers 2 and 4 is operational today. Tier 3 (host-side REST server) is not yet implemented. L7 egress policies add two enforcement axes: HTTP method + path restrictions, and binary-level restrictions — the proxy identifies the calling binary via `/proc/pid/exe` and walks the process tree, so policies can restrict which executables may reach each endpoint (see [openshell-policy-bypass experiment](https://github.com/fullsend-ai/experiments/pull/5) for validation). Together, providers and L7 policies replace the REST server for services with static API key/token auth, with no custom proxy code.
27
+
OpenShell's native provider system addresses the first problem. Providers inject credentials as opaque placeholder tokens that the gateway proxy swaps for real values at the HTTP layer, so credentials never enter the sandbox. The `fullsend run` command already supports providers: the harness layer loads provider definitions from the agent's `providers/` directory, creates them on the gateway via `openshell provider create`, and passes them to sandbox creation — so the infrastructure for credential delivery tiers 2 and 4 is operational today. Credential delivery tier 3 (host-side REST server) is not yet implemented. L7 egress policies add two enforcement axes: HTTP method + path restrictions, and binary-level restrictions — the proxy identifies the calling binary via `/proc/pid/exe` and walks the process tree, so policies can restrict which executables may reach each endpoint (see [openshell-policy-bypass experiment](https://github.com/fullsend-ai/experiments/pull/5) for validation). Together, providers and L7 policies replace the REST server for services with static API key/token auth, with no custom proxy code.
28
28
29
29
For fine-grained operation control beyond what L7 path filtering can express, two mechanisms complement providers. First, custom wrapper binaries baked into the OpenShell sandbox image (e.g. a `safe-push` that wraps `git push` and rejects force pushes) — placed on a read-only path via Landlock so the agent cannot modify them, with L7 binary filtering ensuring only the wrapper can reach the upstream service. Second, the host-side REST server from ADR 0017, which can inspect request bodies, restrict GraphQL operations, or transform responses. Both mechanisms provide operation-level control that providers and L7 path matching alone cannot.
30
30
@@ -34,7 +34,7 @@ Not all services fit the provider model. Providers cannot inject credentials int
1.**Prefetch + post-process** (unchanged from ADR 0017). Agent runs with zero credential access. Use for agents with fully enumerable inputs. This remains the default — the first question for any new agent is whether it can run without runtime credential access.
40
40
@@ -44,14 +44,14 @@ Adopt a four-tier credential delivery model, extending ADR 0017's two-tier model
44
44
45
45
4.**Host files + L7 egress policies** (new explicit tier). Credential files are copied into the sandbox via the harness `host_files` mechanism. L7 policies restrict egress to only the necessary endpoints and binaries. Use when the provider placeholder model and REST server cannot work: services with file-based auth, multi-step OAuth2 flows, or in-sandbox cryptographic operations (e.g. GCP Vertex AI, where `google-auth-library` must read a service account JSON to sign JWTs locally). The security boundary is the network policy, not credential isolation — real credentials exist on the sandbox filesystem. This makes the single-responsibility agent model ([ADR 0020](0020-composable-single-responsibility-agents-with-individual-sandboxes.md)) especially important: the narrower the agent's responsibility and the fewer endpoints its policy permits, the smaller the attack surface if the agent is compromised.
46
46
47
-
Agent definitions should use the highest tier possible: prefer providers over REST servers, REST servers over host files. The decision tree for a new integration: can prefetch handle it, and is a deterministic input set sufficient (or does the agent need to explore dynamically at runtime)? → if prefetch suffices, use tier 1. Does the service use static token auth in headers? → use tier 2. Do credentials need to appear in request bodies or responses need transformation? → use tier 3. Does auth require credential files or in-sandbox cryptographic ops? → use tier 4.
47
+
Agent definitions should use the highest credential delivery tier possible: prefer providers over REST servers, REST servers over host files. The decision tree for a new integration: can prefetch handle it, and is a deterministic input set sufficient (or does the agent need to explore dynamically at runtime)? → if prefetch suffices, use credential delivery tier 1. Does the service use static token auth in headers? → use credential delivery tier 2. Do credentials need to appear in request bodies or responses need transformation? → use credential delivery tier 3. Does auth require credential files or in-sandbox cryptographic ops? → use credential delivery tier 4.
48
48
49
49
## Consequences
50
50
51
51
- Services with static token auth (GitHub, OpenAI, Anthropic) no longer require custom proxy endpoints, reducing per-service maintenance to provider YAML and L7 policy definitions.
52
-
- The host-side REST server from ADR 0017 is retained for cases requiring request body credential injection or response transformation — its role narrows from "default fallback" to a specific tier.
52
+
- The host-side REST server from ADR 0017 is retained for cases requiring request body credential injection or response transformation — its role narrows from "default fallback" to a specific credential delivery tier.
53
53
- The `host_files` mechanism is formalized as the explicit fallback for file-based auth flows (GCP Vertex AI), documenting a pattern already present in the scaffold harness files.
54
-
- L7 policy authoring remains security-critical across all tiers — providers reduce proxy code but do not reduce the need for correct path patterns, and a path pattern typo can over-permit access.
55
-
- Custom wrapper binaries used for operation-level control (tier 2) must be placed on read-only paths enforced by Landlock; if the agent can modify the wrapper, the restriction is bypassed.
56
-
- Agents using host files (tier 4) have real credentials on the sandbox filesystem; per-agent documentation must explicitly state that the security boundary is network-only.
57
-
- Fullsend should provide validation tooling that checks agent harness definitions for compliance with this model — auditing L7 policies for free-text endpoints that could carry placeholders, verifying wrapper binaries are on read-only paths, and flagging tier mismatches — for both internal development and for users crafting new agents.
54
+
- L7 policy authoring remains security-critical across all credential delivery tiers — providers reduce proxy code but do not reduce the need for correct path patterns, and a path pattern typo can over-permit access.
55
+
- Custom wrapper binaries used for operation-level control (credential delivery tier 2) must be placed on read-only paths enforced by Landlock; if the agent can modify the wrapper, the restriction is bypassed.
56
+
- Agents using host files (credential delivery tier 4) have real credentials on the sandbox filesystem; per-agent documentation must explicitly state that the security boundary is network-only.
57
+
- Fullsend should provide validation tooling that checks agent harness definitions for compliance with this model — auditing L7 policies for free-text endpoints that could carry placeholders, verifying wrapper binaries are on read-only paths, and flagging credential delivery tier mismatches — for both internal development and for users crafting new agents.
![fullsend-ai-coder[bot]](https://avatars.githubusercontent.com/in/3478495?v=4&size=40){kind=avatar}
0 commit comments