use_secret

use_secret is the unified runtime tool. Pick a mode by providing exactly one target field: itemId for single-item injection, or profileId to bulk-inject every env-shaped item in a profile.

Subprocess stdout/stderr text is never forwarded to the model. The model receives only the exit code, duration, output-line count, and a truncation flag. If the model needs to read subprocess output, route it through a separate audited channel (write to a file via mount_secret, then read it explicitly). This prevents the full set of semantic-leakage vectors (base64, hex, URL-encoded, nth-char, byte-split) that string-based redaction cannot catch.

Targets

Provide exactly one. They are mutually exclusive:

Field	Mode	Selects
`itemId`	single-item	one item by id
`profileId`	bulk	every env-shaped item in the profile, by profile id

Input

Field	Type	Required	Description
`itemId`	string	one of	Run with a single item by id. Mutually exclusive with `profileId`.
`profileId`	string	one of	Run with every env-shaped item in this profile. Trust boundary — items in other profiles are never injected.
`command`	string	yes	Command to run
`args`	string[]	no	Command arguments
`purpose`	string	no	Caller-declared purpose. Audited.
`field`	string	no	Named field (single-item mode only)
`envVarName`	string	no	Env var name for single-item mode. Default `ABADGE_SECRET`.

Output

{
  "exitCode": 0,
  "durationMs": 73,
  "outputLineCount": { "stdout": 5, "stderr": 0 },
  "truncated": false,
  "injectedCount": 7
}

injectedCount appears only in bulk mode. On a failed run (exitCode !== 0) that produced withheld output, the result also carries a static, secret-free hint string. It explains that stdout/stderr were suppressed to prevent secret leakage (RED1) and points at mount_secret for output inspection. The hint is a fixed constant containing no subprocess output, and is omitted on success.

Bulk-mode rules

Only single-string-field items participate; multi-field items (logins, certs, ssh_keys) are silently skipped.
Labels are normalized to POSIX env-var names (openai-api-key → OPENAI_API_KEY).
Two items normalizing to the same env var name fail the call with both offending IDs.
A label normalizing to a reserved env key (LD_PRELOAD, NODE_OPTIONS, PATH, …) fails the call with the offending item ID.
Per-secret 4 KB size cap; oversize secrets are refused before spawn — use mount_secret instead.
Each included item produces its own access.use audit row.
use is local-only — remote agents cannot use bulk mode.

Errors

Returned as JSON text content. Local validation failures (e.g. supplying neither or both targets, an invalid envVarName, or an oversize secret) surface as a bare error field:

{
  "error": "Provide exactly one of itemId or profileId. They are mutually exclusive."
}

Failures from the control-plane API (AbadgeApiError) also carry code, and — when present — hint and meta:

{
  "error": "Agent lacks the required capability for this item.",
  "code": "PERMISSION_DENIED",
  "hint": "Grant the agent a `use` permission on this item."
}

Getting started

Tools

Security

Targets

Input

Output

Bulk-mode rules

Errors

​Targets

​Input

​Output

​Bulk-mode rules

​Errors

Targets

Input

Output

Bulk-mode rules

Errors