feat: credential injection and offload for agent tool calls (#2481)

[Ricky-G]

Summary

Implements runtime credential offload and injection for agent tool calls so agents reference secrets by opaque {{cred:NAME}} placeholders and never hold raw credential values. Closes #2481.

Problem

Agents currently hold their own API keys, database passwords, and service tokens. A prompt-injected, context-manipulated, or exfiltrating agent leaks every credential it holds. AGT needed a kernel-level surface that holds secrets on behalf of agents and resolves them only inside the trust boundary, after policy evaluation, with a deterministic deny shape and a value-free audit trail.

Design

Agents only ever see CredentialHandle names and {{cred:NAME}} placeholders. The CredentialInjector is the only component that ever holds resolved values, and only long enough to render an outbound payload (HTTP headers, MCP tool args, subprocess env). Resolution requires:

1. The handle name appears in the workflow-supplied �llowed_handles allowlist for this call (MCP/server metadata is treated as untrusted).
2. The optional policy_check callback returns �llow=True (policy runs before any vault read).
3. The agents CredentialProfile binds the action class (e.g. github:read_issues vs github:push_code) to that specific handle.

Any deny -- missing handle, out-of-scope handle, or policy refusal -- returns the same DenyReceipt, so agents cannot probe vault contents through error shape. Audit events record agent DID, handle name, target service, action class, decision, and policy version; they never contain the resolved value.

Encrypted-at-rest persistence uses Fernet from cryptography. If cryptography is unavailable the vault refuses to persist (fails closed) rather than writing plaintext.

Maps to issue acceptance criteria + @kayalopez review

Requirement	Where
Encrypted at-rest store	CredentialVault Fernet persistence
HTTP header / MCP arg / env placeholder substitution	CredentialInjector.inject_headers / inject_tool_args / inject_env
Per-DID scoping	CredentialProfile
Audit log with no secret values	VaultAuditEvent, �udit_digest
�gt cred add/list/rotate CLI	�gent_compliance.cli.cred
Documentation + example	�xamples/credential_vault_example.py, module docstring
Opaque handles only -- agents never see values (#1)	CredentialHandle; resolved value confined to _resolve_internal
Substitution after policy evaluation (#2)	policy_check invoked before any _resolve_internal call
Audit shape includes identity/handle/service/action/decision/policy_version, never values (#3)	VaultAuditEvent.to_dict()
Scoped by action, not only by agent (#4)	CredentialProfile.bindings: action_class -> handle_name
Rotation without prompt/plan changes (#5)	CredentialVault.rotate() keeps handle name; tested in TestRotation
Deterministic deny that does not reveal handle existence (#6)	DenyReceipt; tested in est_out_of_scope_handle_returns_same_deny_as_missing
MCP/server metadata treated as untrusted (#7)	per-call �llowed_handles allowlist; placeholders outside it deny the whole call
Same fixture across headers/args/env retry paths yields same deny (kayalopez launch test)	est_same_deny_across_injection_surfaces

Changes

File	What changed
�gent-governance-python/agent-os/src/agent_os/credential_vault.py	New module: CredentialVault, CredentialInjector, CredentialProfile, CredentialHandle, DenyReceipt, VaultAuditEvent, �udit_digest.
�gent-governance-python/agent-os/src/agent_os/init.py	Re-export public surface.
�gent-governance-python/agent-compliance/src/agent_compliance/cli/cred.py	New �gt cred {genkey,add,list,rotate,remove} Click group.
�gent-governance-python/agent-compliance/src/agent_compliance/cli/agt.py	Register cred group on the �gt CLI.
�gent-governance-python/agent-os/tests/test_credential_vault.py	28 unit tests covering admin surface, scoping, injection across 3 surfaces, deterministic deny equivalence, policy-before-resolution ordering, audit value-freedom, rotation semantics, encrypted persistence round-trip, placeholder regex.
�gent-governance-python/agent-compliance/tests/test_cred_cli.py	5 CLI tests covering keygen, add/list/rotate/remove round-trip, fail-closed missing key, unknown-name errors.
�gent-governance-python/agent-os/examples/credential_vault_example.py	End-to-end runnable example.

Testing

• pytest agent-governance-python/agent-os/tests/test_credential_vault.py -- 28 passed
• pytest agent-governance-python/agent-compliance/tests/test_cred_cli.py -- 5 passed

uff check --select E,F,W --ignore E501 on all changed files -- clean

• Manual smoke: rom agent_os import CredentialVault, CredentialInjector, CredentialProfile, DenyReceipt, audit_digest imports cleanly.

Scope and follow-ups

This PR is Python-only by design. Credentials are a wire-protocol-adjacent primitive and the other AGT SDKs (TypeScript, Rust, .NET, Go) should mirror this contract. I intentionally landed Python first so the placeholder syntax, profile binding shape, audit event schema, and DenyReceipt can absorb review feedback before being ported, rather than maintaining five parallel WIPs.

Planned follow-up issues (will file once this lands):

• TypeScript port in @microsoft/agent-governance-sdk
• Rust port in �gent-governance crate
• .NET port in Microsoft.AgentGovernance
• Go port in �gent-governance-golang
• Cross-language spec: placeholder syntax, audit-event JSON shape, and key/cipher interop (Fernet <-> AES-GCM) so a vault written by one SDK can be read by another

Prior art

Design draws on the original issue #2481 proposal by @imran-siddique and incorporates the seven review points from @kayalopez. Concept is established in secret-management systems generally (HashiCorp Vault response-wrapping, AWS STS GetSessionToken with caller-side caching, OAuth token brokers). No code was borrowed from any external project.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[github-actions]

This PR is quite large. Consider breaking it into smaller PRs for easier review.

[github-actions]

🤖 AI Agent: security-scanner — View details

No security issues found.

[github-actions]

🤖 AI Agent: docs-sync-checker — Docs Sync

Docs Sync

• agent_os/credential_vault.py -- missing docstrings for new public APIs.
• README.md -- update required to include information about the new credential injection and offload feature.
• CHANGELOG.md -- missing entry for the new feature and its behavioral changes.

[github-actions]

🤖 AI Agent: test-generator — `agent-governance-python/agent-os/src/agent_os/credential_vault.py`

agent-governance-python/agent-os/src/agent_os/credential_vault.py

• test_policy_denies_with_invalid_action_class -- Test that the policy denies access when the action class is invalid.
• test_injection_with_empty_allowed_handles -- Validate that injection fails when allowed_handles is empty.
• test_audit_log_includes_policy_version -- Ensure the audit log includes the policy_version field.
• test_encryption_key_rotation -- Test behavior when the encryption key is rotated while the vault contains existing credentials.

agent-governance-python/agent-compliance/src/agent_compliance/cli/cred.py

• test_add_with_invalid_key -- Validate that agt cred add fails when provided with an invalid encryption key.
• test_list_handles_with_no_credentials -- Ensure agt cred list handles an empty vault gracefully.
• test_rotate_with_invalid_key -- Test that agt cred rotate fails when the encryption key is incorrect.

agent-governance-python/agent-os/examples/credential_vault_example.py

• test_example_script_execution -- Verify the example script runs without errors and produces expected output.
• test_audit_log_output_format -- Validate that the audit log output from the example script matches the documented format.

[github-actions]

🤖 AI Agent: breaking-change-detector — API Compatibility

API Compatibility

Severity	Change	Impact
High	Introduction of new CredentialVault class with methods like put, list_handles, rotate, and delete.	Existing code using the same method names in the agent_os module may break due to potential conflicts.
High	Addition of CredentialInjector class with methods like inject_headers, inject_tool_args, and inject_env.	Existing code using the same method names in the agent_os module may break due to potential conflicts.
High	Addition of CredentialProfile class with agent_did and bindings attributes.	Existing code using the same class name in the agent_os module may break due to potential conflicts.
High	Addition of DenyReceipt class.	Existing code using the same class name in the agent_os module may break due to potential conflicts.
High	Addition of VaultAuditEvent class and audit_log method.	Existing code using the same class name or method name in the agent_os module may break due to potential conflicts.
Medium	New CLI commands added under agt cred (e.g., add, list, rotate, remove, genkey).	Potential conflict with existing CLI commands if similar names are already in use.
Medium	New environment variables AGT_VAULT_PATH and AGT_VAULT_KEY introduced.	May conflict with existing environment variables if they are already in use.

[github-actions]

🤖 AI Agent: code-reviewer — Action Items:

TL;DR: 0 blockers, 2 warnings. The PR is well-implemented and meets the issue's requirements, but there are minor follow-up improvements suggested.

#	Sev	Issue	Where
1	Warn	No explicit test for encrypted persistence failure (e.g., invalid key).	test_credential_vault.py
2	Warn	Missing test coverage for CredentialInjector.inject_tool_args and inject_env.	test_credential_vault.py

Action Items:

1. None.

Warnings:

#	Description	Where	Follow-up?
1	Add a test to verify behavior when encrypted persistence fails (e.g., invalid key).	test_credential_vault.py	Yes
2	Add tests for CredentialInjector.inject_tool_args and inject_env methods.	test_credential_vault.py	Yes

[github-actions]

🟡 Contributor Check: MEDIUM

Check	Result
Profile	MEDIUM
Credential	NONE
Overall	MEDIUM

Automated check by AGT Contributor Check.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Warning	See details
🛡️ Security Scan	✅ Passed	No issues found
🔄 Breaking Changes	✅ Completed	Analysis complete
📝 Docs Sync	✅ Completed	Analysis complete
🧪 Test Coverage	✅ Completed	Analysis complete

Verdict: ⚠️ Ready for human review