What HIPAA Actually Says About AI Tools

HIPAA permits using Claude, Copilot, or any other AI tool. The law predates these tools by decades. What HIPAA requires is that protected health information (PHI) is only disclosed to parties that have a Business Associate Agreement (BAA) in place with the covered entity or business associate.

The question for healthcare engineering teams is precise: does your codebase, or code derived from your codebase, contain PHI or patterns that could be used to identify PHI?

If the answer is yes, you need either a BAA with every AI provider your developers use, or a technical control that keeps PHI away from those providers.

What Constitutes PHI in Source Code

The obvious cases: hard-coded patient names, social security numbers, or medical record numbers. These appear in test fixtures, development databases, and legacy code more often than most teams realize.

The less obvious cases:

• -Data model schemas with identifiers like PatientId, MemberBenefitCode, ClaimAdjudicationResult
• -Variable names derived from HIPAA identifiers (the 18 identifiers defined in the Privacy Rule)
• -Comments referencing specific patients, even in test files
• -Configuration files referencing PHI-bearing endpoints or database tables

The regulatory question reaches past whether a specific patient can be identified from the source code in isolation. It asks whether PHI is present or represented, which includes data structures, identifiers, and schemas that handle PHI.

The BAA Problem for AI Tools

Large AI providers do offer BAAs. Anthropic, Microsoft (for Azure OpenAI), and Google (for Vertex AI) all have enterprise agreements that include HIPAA-aligned BAAs.

The limitations:

1. -

   BAAs are available only on enterprise plans. Developers using standard Claude.ai, GitHub Copilot Individual, or similar consumer-tier plans fall outside BAA coverage.

2. -

   BAAs cover data handling; transmission scope is a separate matter. Even with a BAA in place, you are sending PHI-adjacent code to a third party. The BAA defines how they handle it; the transmission itself still happens.

3. -

   BAA management is complex. If your developers use multiple AI tools, you need a BAA with each provider, renewed annually, with appropriate controls documentation.

For teams that primarily work with one provider at enterprise tier, the BAA approach is workable. For teams with diverse AI tool usage, it becomes operationally complex.

The Alternative: Technical Prevention

The most robust HIPAA approach for source code is keeping PHI patterns away from AI providers entirely. If the identifiers that reference PHI are mutated before transmission, the data that leaves your machine carries only synthetic stand-ins for those patterns.

This is the approach Pretense implements:

// Original code (contains HIPAA-relevant identifiers)
function getPatientRecord(patientId: string): Promise<PatientRecord> {
  return hipaaAuditedDb.query(
    'SELECT * FROM patient_records WHERE id = ?',
    [patientId]
  );
}

// After Pretense mutation (sent to AI API)
function _fn3a7c(_v8d2e: string): Promise<_cls4f1b> {
  return _cls9a3d.query(
    'SELECT * FROM patient_records WHERE id = ?',
    [_v8d2e]
  );
}

The function still makes sense to the LLM. The parameter type, return type, and query structure are all visible. Meanwhile, the identifiers that reference the PHI data model are synthetic, and Pretense swaps them back byte-exact in the model's answer.

Note that the SQL string literal is preserved verbatim. This is a deliberate choice: mutating string literals would break output quality. The table name in a SQL query is metadata about your schema, distinct from PHI itself.

PHI Detection in Pretense

Beyond identifier mutation, Pretense includes a secrets engine that detects PHI patterns in prompts and swaps them for stand-ins before transmission:

Detected patterns include:

• -Social Security Numbers (XXX-XX-XXXX format)
• -Medical Record Numbers (common institutional formats)
• -National Provider Identifiers (NPI)
• -Health plan beneficiary numbers
• -Account numbers and certificate/license numbers
• -Date of birth patterns
• -Geographic identifiers below state level (ZIP codes in certain contexts)
• -Phone and fax numbers (flagged by default, along with email addresses)

If a developer accidentally pastes a code block containing a patient ID or hard-coded SSN into a prompt, Pretense swaps the value for a stand-in before transmission and logs a PHI detection event. The stand-in stays in place in the model's answer by design.

WARN [pretense] PHI pattern detected in outbound request
  Pattern: SSN_FORMAT
  Location: prompt line 47
  Value swapped for stand-in. Logged to audit: event_id=evt_8x3k2p

Review the source file and move PHI into synthetic fixtures.

Building the HIPAA Control Documentation

HIPAA requires covered entities and business associates to implement technical safeguards that control access to electronic PHI. For AI tool usage, the control documentation should include:

Required Documentation

1. -

   Risk Assessment: Document the risk of AI tool usage for code containing PHI patterns. This is required by the Security Rule and must be updated when significant technology changes occur.

2. -

   Technical Safeguard Documentation: Document the control implemented to keep PHI out of transmissions. A proxy audit log is strong technical evidence.

3. -

   Workforce Training Records: Document that developers have been trained on the PHI transmission policy.

4. -

   BAA Status: If using AI tools outside a proxy, document BAA status for each provider.

Audit Log Requirements

HIPAA requires audit logs for systems that access, modify, or transmit electronic PHI. If AI tool API calls could potentially include PHI, those calls need to be in your audit log.

Pretense generates audit logs that map to this requirement:

{
  "event_id": "evt_8x3k2p",
  "timestamp": "2026-04-04T09:14:22Z",
  "developer": "engineer@healthcareorg.com",
  "repository": "claims-processing-service",
  "phi_patterns_detected": 0,
  "phi_patterns_blocked": 0,
  "identifiers_mutated": 18,
  "secrets_detected": 0,
  "model": "claude-3-5-sonnet",
  "audit_event_type": "ai_api_call",
  "hipaa_relevant": true
}

HIPAA-Specific Report Generation

pretense audit --format csv --framework HIPAA --limit 100000 > hipaa-ai-audit.csv

The export lists each PHI and secret detection that maps to HIPAA, with its date. It is evidence for your HIPAA risk assessment. It is not a certification.

Practical Implementation Steps

1. -

   Classify your repositories: Identify which codebases contain PHI-adjacent code (models, schemas, logic that handles patient data).

2. -

   Deploy Pretense on PHI-adjacent repos first: Start with the repositories where HIPAA exposure is real, then expand from there.

3. -

   Run the PHI detection scan: pretense scan path src/ --policy hipaa will identify files containing hard-coded PHI patterns that need to be cleaned up independently of mutation.

4. -

   Generate the initial audit baseline: Run Pretense for 30 days and generate the first audit report. This becomes your evidence of control effectiveness.

5. -

   Update your risk assessment: Document the deployment of technical safeguards in your HIPAA risk assessment.

A Note on Test Data

Test files are a common source of PHI in codebases. Developers create test fixtures with realistic-looking data and sometimes use real patient identifiers from development databases. Pretense detects these patterns during the scan phase, and the underlying issue still requires remediation: replace real PHI in test fixtures with synthetic data that follows the same structural patterns.

# Scan for PHI in test files specifically
pretense scan path tests/ --policy hipaa

Cleaning up PHI in test files is a one-time investment that eliminates a persistent compliance risk, regardless of AI tool usage.

How I run Pretense on my own code

I build Pretense with Claude Code, and my sessions run through it. Here is the setup I give a new engineer, in order.

1. -Run the agent through the proxy. Type pretense run claude where you would type claude. It starts a local proxy on port 9339, points Claude Code at it and stops the proxy when the session ends. Detected secrets and PII leave the laptop as stand-in tokens.
2. -Put hooks on every repo. pretense install adds a pre-commit and a pre-push hook. A key that never lands in git is a key an agent never reads.
3. -Scan before an agent reads the repo. pretense scan path . lists what it finds. In CI, pretense scan ci exits 0 when clean, 2 on findings and 3 when it examined nothing. Treat 3 as a failure.
4. -Preview the swap. pretense review . shows what would be mutated. pretense mutate <file> --preview prints one file mutated and leaves the file on disk as it was.
5. -Round-trip a file you need to share. pretense mutate <file> --map <map> swaps the secrets in place. pretense reverse <file> --map <map> turns it back into the original, byte for byte, from the encrypted map on your machine. We run that round trip on real files before every CLI release and compare sha256 hashes.

One thing I learned the hard way: inside a session the agent sees stand-ins, so a file the agent writes can hold a stand-in where you expected a real value. Grep what the agent wrote before you ship it.

What Pretense will not do is put a secret back into the model's answer. Code identifiers come back byte-exact. Secrets and PII stay as stand-ins in the response. That is deliberate: a prompt-injected model can echo a token into a link, and reversing it there would hand over the real key.

What this means if you own compliance

The outcome: a technical control for AI coding tools that you can show an auditor. Pretense helps with SOC 2, HIPAA, PCI DSS and GDPR evidence. It maps to controls. It does not certify you.

• -Pin the preset you report against. pretense scan path . --policy soc2 applies that framework's detectors. SOC 2 and PCI presets come with Startup. HIPAA, GDPR and NIST presets come with Enterprise.
• -Export the evidence. pretense audit --format csv --framework HIPAA writes the events that map to HIPAA. Attach the file to the control with the date range you sampled.
• -Test detection on your own data. Coverage varies by data type. Run pretense review . on a regulated repo, read the result and record the gaps in your risk assessment.
• -Keep the policy and the control in step. Your AI tool policy says what engineers may send. pretense run claude and the git hooks are how you show it happens.

Try it on your own repo: create a free account, then run npm i -g @pretense/cli and pretense run claude. If you need a security review first, talk to me.