Environment Injection Architecture

Standard CLI parsers attempt to parse all incoming flags. If your target command contains flags (e.g. python manage.py runserver --noreload --port 8000), a standard CLI would crash, claiming --noreload is an unknown AgentSecrets flag.

AgentSecrets explicitly sets DisableFlagParsing: true on the command definition:

• The mandatory -- delimiter marks the strict boundary between AgentSecrets options and child program arguments.
• The CLI strips -- and forwards all remaining arguments verbatim to the OS executable locator (exec.LookPath).

Before accessing any secret, the CLI establishes an IPC handshake with the keychain-auth daemon. The daemon verifies the calling binary's cryptographic hash (SHA-256) and PID via kernel-level socket credentials (SO_PEERCRED on Linux, LOCAL_PEERPID on macOS, Named Pipes on Windows). Once attested, the active project's secrets for the selected environment (dev, staging, or prod) are returned to the CLI's memory.

The CLI constructs the environment block for the child process:

// cmd/agentsecrets/commands/env.go
env := os.Environ() // Inherit host PATH, USER, HOME, etc.
for key, value := range secrets {
    env = append(env, fmt.Sprintf("%s=%s", key, value))
}
childCmd.Env = env

• No File System Footprint: The secrets never touch .env, temporary files, or swap memory.
• No Shell Scope Pollution: The variables are bound strictly to the childCmd process descriptor. Your parent terminal shell remains completely unmodified.

In poorly designed process wrappers, pressing Ctrl+C kills the wrapper and leaves the child process running in the background as an orphaned zombie holding open database connections or network ports.

agentsecrets env runs an active signal supervisor:

// Traps SIGINT and SIGTERM and forwards directly to the child process
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
go func() {
    select {
    case sig := <-sigChan:
        if childCmd.Process != nil {
            childCmd.Process.Signal(sig)
        }
    case <-done:
    }
}()

When you stop a server, web worker, or container, agentsecrets env propagates the interrupt signal directly to the child's PID, allowing frameworks like Django, Node.js, and Celery to execute their graceful shutdown hooks.

Even though credentials reside only in child process RAM, buggy application code, unhandled exceptions, or verbose debug logs might inadvertently print os.environ or error traces to the terminal.

To prevent terminal scrollback and CI log leakage, agentsecrets env wraps the child process os.Stdout and os.Stderr in real-time MaskingWriter streams. The interceptor matches and redacts:

• Plaintext Values: sk_live_51ABC... -> [REDACTED]
• Base64 Variants: Encoded strings -> [REDACTED]
• Hex Representations: Hex-encoded bytes -> [REDACTED]
• URL-Percent Escaped: Query parameters -> [REDACTED]

Output masking is enforced at the kernel pipe layer and cannot be disabled via flags.

When the child command finishes execution:

1. MaskingWriter flushes any remaining buffered bytes to the terminal.
2. The exact exit code of the child process (exitErr.ExitCode()) is extracted and returned. If the child exits with code 1 or 127, agentsecrets exits with code 1 or 127. Makefiles, shell scripts, and CI runners behave as if the child was invoked directly.
3. An audit event is committed to the local audit trail (Method: "ENV", AuthStyles: ["env_inject"]). Crucially, only the secret key names are logged, never the values.