feat(security): Add credential isolation guidance and enforcement for code-execution tools

[rdwj]

Problem

When agents use code-execution tools (like the code sandbox at https://github.com/fips-agents/code-sandbox), there's a security gap: secrets available to the main agent process (OPENAI_API_KEY, database credentials, etc.) must NOT be accessible inside the code execution container. Currently, there's no explicit guidance or enforcement around this structural separation.

The insight: separating harness and compute helps keep credentials out of environments where model-generated code executes.

Current State

• The project has SecurityConfig with ToolInspector that scans tool call arguments for dangerous patterns
• The two tool planes architecture (plane 1: agent-code, plane 2: LLM-callable) is documented
• The code sandbox section in docs/architecture.md covers AST guardrails and runtime isolation
• Missing: explicit guidance on credential isolation and deployment patterns that enforce it

Proposed Solution

This enhancement should cover four areas:

1. Documentation in architecture.md

Add a "Credential Isolation" subsection under the Code Execution Sandbox section that explains:

• Principle: Secrets flow as explicit arguments from agent to tool, never as ambient environment
• The agent sends code + explicit args to the sandbox; the sandbox never has direct access to the agent's credentials
• This is a structural separation: credential space vs. code execution space
• Why this matters: LLM-generated code should not have any path to exfiltrate secrets

2. Lightweight Enforcement Mechanism

Add a sandboxed: true flag to the @tool decorator:

@tool(visibility="llm_only", sandboxed=True)
async def code_executor(code: str) -> str:
    """Execute Python code in isolated sandbox."""
    ...

When sandboxed=True:

• At setup time, verify that the tool's execution environment does NOT have access to agent-level secrets
• Warn (observe mode) or error (enforce mode) if ambient credentials are detected
• The check should be practical: look for common secret env vars (OPENAI_API_KEY, DATABASE_URL, etc.)

3. OpenShift Deployment Guidance

Add deployment guidance to the Helm chart or deployment documentation:

• Sandbox containers should NOT mount the same Secret objects as the agent container
• Show the pattern: agent container gets secrets as env vars, sandbox container gets empty env
• Link to the broader principle: containers running untrusted code should have minimal ambient authority

4. Integration with Existing Security Infrastructure

Wire this into the existing SecurityConfig:

• tool_inspection.mode: observe → log warnings when sandboxed tools have ambient secrets
• tool_inspection.mode: enforce → fail at startup when sandboxed tools have ambient secrets
• Audit findings should log to fipsagents.security.audit (same pattern as ToolInspector)

References

• Existing SecurityConfig / ToolInspector in BaseAgent (CLAUDE.md line 49)
• Code sandbox repo: https://github.com/fips-agents/code-sandbox
• Two tool planes architecture in docs/architecture.md
• Code Execution Sandbox section in docs/architecture.md (lines 804-832)

Non-Goals

• This is NOT about fixing every possible code execution vulnerability (that's covered by AST guardrails + container constraints in issue feat: Code execution sandbox hardening with OpenShell + DefenseClaw (v2) #26)
• This is NOT about adding new secret scanning tools (ToolInspector already does that for tool arguments)
• This IS about structural guidance: how to deploy agents so that credentials don't leak into code execution environments

Acceptance Criteria

• docs/architecture.md has a "Credential Isolation" subsection under Code Execution Sandbox
• @tool decorator accepts sandboxed: bool parameter
• BaseAgent setup validates sandboxed tools at startup (mode-dependent warn/error)
• Helm chart shows the deployment pattern (agent secrets vs. sandbox secrets)
• SecurityConfig enforcement modes apply to credential isolation checks