Building a Change Approval Workflow with Hooks

Why Governance Matters

Without governance, automation can be dangerous. Claude Code running against your production database without safeguards is terrifying. Someone's mistake, a hallucination in the AI, or even a misunderstanding about what's safe could cause data loss. You need explicit governance—clear rules about what's allowed, who can approve it, and an audit trail proving who approved it.

Good governance isn't about slowing everything down. It's about enabling confident automation. When you know that dangerous operations require approval, you can run automation more aggressively elsewhere. When you have audit trails, you can investigate incidents confidently. When you have clear rules, people understand what's expected.

The goal is to make the common case fast and the dangerous case safe. Changing documentation shouldn't require approval. Modifying database schemas should require approval. With the right governance, the system moves quickly without sacrificing safety.

The Approval Workflow Pattern

Here's what we're building: a system where changes are categorized by impact level, and each level requires different approval gates. A syntax fix runs immediately. A database schema change waits for review. A production credential rotation requires manual approval from ops.

This workflow has three key properties. Categorization determines what counts as low/medium/high impact. Routing sends each impact level to appropriate approval gates. Audit trail logs every approval decision for compliance.

Understanding Impact Levels

The concept of impact level is central to approval workflows. A low-impact change is one that, if it goes wrong, affects very few things. A documentation fix is low-impact—worst case, the docs are wrong but your system still works. A utility function change might be medium-impact if it's used in multiple places but they all have tests. A database schema change is high-impact because all downstream code depends on it.

Impact level isn't about whether something is "good" or "bad"—it's about blast radius. A tiny bug fix is low-impact even if the bug was critical, because the fix is so small. A large refactoring is medium-impact even if it's purely cleaning up code, because changes are large. A database migration is high-impact by definition because schema changes are irreversible.

Understanding this distinction prevents over-gatekeeping and under-gatekeeping. If you treat all changes as high-impact, approval becomes a bottleneck. If you treat all changes as low-impact, dangerous changes slip through. Calibrated impact assessment enables the right level of scrutiny for each situation.

Part 1: The Impact Categorizer

First, we need to look at a change and determine its risk level. This happens in a PreToolUse hook that examines what Claude is about to do. The hook categorizes file operations—modifying .env files, secret management, or production configs is HIGH impact. Modifying source code is MEDIUM. Modifying docs and tests is LOW. The hook categorizes bash commands—destructive commands like git push --force, DROP TABLE, or rm -rf are HIGH impact. Infrastructure commands are MEDIUM. Read-only commands are LOW.

The categorization creates clear boundaries. Your team understands what requires approval. Developers know that certain operations will be gated. The system is predictable and fair.

Part 2: The Approval Router

Once we know the impact level, we route the change to the right approval path. Low impact proceeds immediately with no approval needed. Medium impact sends notifications to appropriate reviewers and allows execution to continue—optimistic approval. High impact blocks execution entirely until someone explicitly approves.

The router generates a unique request ID for tracking. It checks if already approved in this session to avoid duplicate approvals. It sends notifications through multiple channels—Slack messages with approve/deny buttons, email notifications to approvers, potentially other channels like Teams or PagerDuty.

For medium impact changes, developers don't have to wait. The change proceeds while notifications are sent. If an approver denies the change, subsequent similar changes within the session are blocked. For high impact, the system blocks immediately and waits for explicit approval.

Part 3: The Approval State Machine

Here's where it gets sophisticated. You need a way to track approval decisions across the execution lifetime. This is called approval state management. The state machine tracks what approvals are needed, who has approved, who has denied, and what the current status is. As approvals come in, the state machine updates. Once you hit the required number of approvals, the change proceeds.

The state machine uses majority rule by default—if you need 3 approvals, 2 approvals triggers proceed. This is configurable by impact level. Critical changes might need unanimous approval. Routine changes might need 50% approval.

Part 4: Integration with Slack Buttons

Now let's complete the loop. When someone clicks "Approve" or "Deny" in Slack, we need to capture that decision and update the hook state. The handler receives the Slack button click, extracts the request ID and decision, looks up the current approval state, updates it with the new decision, persists the updated state back to storage.

When you click a Slack button, it sends feedback back to Slack confirming the decision. The next time the hook runs, it sees the approval and proceeds. This creates a seamless workflow—you see a notification, click a button, and the system continues. No need to manually trigger anything.

Part 5: The Audit Log

For compliance and debugging, every approval decision gets logged. The audit log records timestamp, execution ID, what changed, who approved or denied, why they approved or denied, what impact level was assigned. You can query these logs later: "Who approved the database migration? When? From where?" This is critical for compliance with regulations like SOC 2 and HIPAA.

The audit trail is immutable—once logged, it can't be changed. This creates accountability. If something goes wrong, you can trace exactly who approved it and when. This level of transparency is especially important in highly-regulated industries.

Part 6: Building Approval Analytics Dashboard

To understand your approval patterns, you need visibility into the data. You track total approvals, categorize by impact level, calculate average approval time, analyze approver performance, calculate denial rate, and find top blocked changes. These metrics reveal patterns. You start recognizing that half your incidents involve skipped approvals. Or that approvals consistently bottleneck on certain people.

These insights inform improvements. Maybe you need more approvers. Maybe you're setting impact levels too high. Maybe certain change types don't actually need approval. The analytics tell you.

Part 7: Escalation and Override

Sometimes you need to override the approval workflow. Maybe it's 3 AM and a critical bug needs a hotfix. You need a controlled escalation path. The system allows overrides with an emergency override token, but forces explicit action and logs everything. No silent escalations. No hidden backdoors. Everything is recorded.

This gives you an emergency valve while maintaining audit trails. In a real emergency, you can proceed immediately. But it's tracked, logged, and visible to the compliance team. That transparency is what enables you to use escalation responsibly.

Part 8: Compliance Integration

If your organization needs to comply with regulations, your approval logs are evidence. You generate a compliance report covering a date range, counting total changes, changes requiring approval, approved changes, denied changes, unapproved changes, unique approvers. You calculate metrics like whether all high-impact changes were approved and whether the audit trail is complete.

These logs become your compliance evidence. When an auditor asks "who approved this change?", you have documented answers.

Pattern: Risk-Based Approval Routing

Not all approvers are equal. Some decisions require specialized expertise. You might want different approvers for different change types. A database change goes to the DBA. A security change goes to the security lead. A performance change goes to the performance engineer. Risk-based routing ensures the right experts review the right changes.

This approach routes approvals based on specific risk factors rather than impact level alone. You analyze risks and route to specialized roles. A database change adds risk. Security exposure adds risk. Performance impact adds risk. Multiple critical risks might escalate to the engineering director. Single risks go to specialists.

Putting It All Together: The Full Workflow

Here's what happens when Claude tries to run a high-impact change. Claude says "I'll modify the payment processor schema." Hook 1 categorizes it as HIGH impact and determines ops_lead approval is needed. Hook 2 routes it to ops_lead and blocks execution. Slack message appears with Approve/Deny buttons. Ops lead clicks Approve button. Handler updates state. Hook 3 state machine sees approval is received. Tool executes the database schema change. Hook 4 audit logger records the decision.

This entire flow is observable and reversible. You can see exactly what was approved, who approved it, when, and why. If something goes wrong, you have the audit trail to investigate.

Testing Your Approval Workflow

How do you test this without crashing production? Mock the external systems. Test locally with fake Slack webhooks. Mock the state store with in-memory storage. Write unit tests for each hook. Test the full flow end-to-end by simulating approvals and checking state changes. Verify that high-impact changes actually block and medium-impact changes proceed.

Advanced: Different Approval Thresholds by Type

In production, you'll want to adjust patterns. Approval timeouts prevent indefinite waiting—if no approval within 1 hour, auto-deny. Different approval thresholds mean database changes need 2 approvals, code changes need 1. Integration with deployment pipelines blocks PRs until approvals are recorded, preventing merges of unapproved changes.

Approval Workflows for Different Industries

Different industries have different compliance and safety requirements. Healthcare needs to track which changes could affect patient data. Financial services needs to ensure no fraud is possible through code changes. E-commerce needs to ensure payment flows are never interrupted.

Your approval system can be customized per industry. Healthcare might require explicit security review for any changes touching personal health information. Financial services might require dual approval for anything touching payment code. E-commerce might require staging validation before any production deployment.

These aren't restrictions—they're safety rails that enable confidence. When your system proves it has safeguards in place, customers and auditors are reassured. The approval system becomes a feature, not a limitation.

Approval Workflows for Different Industries

An approval workflow isn't about bureaucracy. It's about giving you control. You decide which changes need review. You get notifications. You approve once and automation continues. You have an audit trail. Most importantly, dangerous changes never surprise you.

The hooks create a governance layer that enables faster automation while keeping you in control. The impact categorizer defines what matters to your organization. Risk-based routing sends each change to the right specialist. The approval state machine tracks decisions reliably. Slack integration makes approvals frictionless. Analytics give visibility into patterns. Escalation paths provide emergency valves. Audit logging creates accountability.

Once your approval workflow is in place, Claude doesn't need to slow down for most changes. Low-impact changes run immediately. Medium-impact changes get async notifications. Only high-impact changes block. Your humans stay involved without becoming bottlenecks.

This is how teams run Claude Code safely at scale. Not by restricting automation, but by building transparent governance that humans can trust and audit trails that prove safety.

Advanced Approval Patterns

Real approval workflows get sophisticated. Conditional approvals might say "if the change is under 50 lines, 1 approval is enough, but over 100 lines needs 2 approvals." Expertise-based routing routes changes to people with proven expertise in that area—database changes go to whoever has approved most database changes successfully. Time-based policies might say "high-impact changes can't be approved late at night or on weekends to avoid sleepy approvals."

These patterns make approval more intelligent and responsive. Instead of a one-size-fits-all approval process, you have adaptive workflows that match the situation. A junior developer's large database change gets routed to an experienced DBA. A senior developer's small formatting change auto-approves. This builds efficiency while maintaining safety.

Handling Approval Disputes

Sometimes approvers disagree. One person approves while another denies. Your system needs a conflict resolution mechanism. You might require both to explicitly agree (unanimous). You might require majority rules (51% approval wins). You might escalate to a third party. The choice reflects your team's values.

Logging disputes is valuable. If two people consistently disagree about a type of change, that might indicate ambiguous policy. Maybe you need clearer guidelines. Maybe the change type is genuinely risky and both perspectives are valid. These patterns surface organizational issues that need discussion.

Integration with Incident Response

When an incident is traced back to an approved change, the approval audit trail becomes evidence. You can see who approved the change, when, and what their reasoning was. This doesn't assign blame—incidents usually involve multiple factors. But it creates accountability and learning opportunities. If a policy change caused an incident, you can see whether the approval process failed or whether the policy itself was flawed.

This feedback loop improves approval processes over time. If approvals consistently miss patterns that cause incidents, you refine the categorization. If approvers consistently make good decisions on certain types of changes, you can relax approval gates for those types. The incident data informs process improvement.

Compliance and Audit Readiness

Organizations in regulated industries need to prove that changes were properly approved. The audit trail is that proof. You can generate compliance reports showing that all production changes were approved, who approved them, when, and what they changed. You can show that high-risk changes got extra scrutiny. You can show that approval processes were followed consistently.

This audit readiness isn't just about passing annual compliance checks—it's about operational excellence. When you have clear records of who approved what and when, investigations are faster. When you need to understand "who approved this risky change?" you have answers. The transparency enforces discipline.

Approval Analytics and Trends

Analyzing approval patterns reveals insights. Which approval gates are actually preventing bad changes versus just creating friction? Do certain approvers consistently find issues that others miss? Does approval time increase over time, suggesting bottlenecks? Do high-impact changes approved by certain people cause more incidents?

These insights are sensitive but valuable. You don't want to publicly shame an approver who misses issues. But internally, you might provide coaching. You might adjust approval policies based on effectiveness data. Over time, approval processes should get better at catching real problems while reducing friction for low-risk changes.

Progressive Relaxation of Controls

A sophisticated approval system learns over time. When a team consistently submits low-risk changes that all pass, you might relax approval requirements for that team. When an engineer proves sound judgment across 100 approvals, you might trust their solo decisions for certain categories.

This progression needs safeguards. You don't want to relax controls so much that safety is compromised. But you do want to avoid over-control of trusted teams. A policy might state: "Teams with 95%+ approval rate over the last quarter can self-approve changes under 100 lines in non-critical paths."

This creates incentive alignment. Teams that are responsible and thoughtful get more autonomy. Teams that need oversight get structured guidance. The system is fair and meritocratic.

Handling False Positives in Categorization

The impact categorizer will sometimes mis-categorize changes. A change you think is medium-impact turns out to be high-impact. Or vice versa. These mis-categorizations are valuable signals.

When approvers consistently override the categorizer on certain types of changes, that's a signal to update the categorization rules. If database changes are always categorized as medium but approvers always want high impact approval, update the rules. If documentation changes are categorized as low but never appear in PRs (because nobody documents), that rule isn't useful.

Over time, your categorization rules become calibrated to your team's actual risk tolerance and priorities. The rules evolve as the team learns and as the codebase changes.

Building Approval Culture

The most important aspect of approval workflows is building a culture of care around them. Approvers should understand that their role is to help, not to block. They should explain their decisions so developers understand expectations. They should look for ways to approve requests safely rather than default to denial. This mindset makes approval a collaborative process rather than an adversarial gate.

When developers see that approval is reasonable and helpful, they embrace it. They don't see it as bureaucracy slowing them down—they see it as expertise helping them avoid mistakes. They ask approvers for feedback and learn from the process. The approval workflow becomes a teaching tool, not just a control mechanism.

Audit Trail Requirements and Compliance

Different compliance regimes have different audit trail requirements. SOC 2 requires you to prove that access controls are in place and working. HIPAA requires you to prove that health data is protected. PCI DSS requires you to prove that payment data is not stored. Your approval workflow generates the evidence for these compliance requirements.

The audit trail captures who approved what, when, and from where. You can generate reports proving "all production database changes were approved" or "all security-sensitive changes were reviewed by security personnel." You can answer auditor questions about your change management process with concrete data.

This compliance benefit is often overlooked. But for regulated organizations, it's huge. The approval workflow isn't just good engineering practice—it's required by law. Building this right becomes a competitive advantage because competitors might be struggling with compliance and you have it systemized.

Building Organizational Discipline Around Approval Workflows

The technical implementation of an approval workflow is one thing. Building your organization's culture around using it effectively is another. When your team understands that the approval system protects them and the organization, they embrace it. When they see it as bureaucracy, they work around it.

This cultural shift starts with transparency. Show your team the data—how many incidents were caused by changes that should have been approved? How many customer issues could have been prevented? Make the business case explicit. When someone says "approval slows us down," show data that proves proper approval actually saves time by preventing incidents.

Communication is critical during rollout. Explain not just the rules but the reasoning. "Database changes require approval because we've had 3 incidents in the past year from schema migrations that broke applications." Developers understand the rule when they understand why it exists. They stop seeing approval as arbitrary bureaucracy and start seeing it as learned wisdom.

Celebrate approvers who provide good feedback. When an approver catches a real issue and helps the developer improve their change, highlight this. Let the developer know their approver provided great guidance. Let the approver know they're making a real impact. This reinforces that approval is collaborative, not adversarial.

Make it easy to appeal decisions. If a developer disagrees with an approval denial, they should be able to escalate to a manager or principal engineer. This prevents approvers from being gatekeepers who can arbitrarily block everything. When developers know they can appeal, they're more likely to accept initial denials.

Real-World Failure Modes and How to Handle Them

Approval systems can fail in subtle ways. An approver gets too strict and blocks everything, killing team velocity. An approver gets too lenient and misses real issues. Approvals become a bottleneck with a single person in the loop. These failure modes need active management.

When approval becomes a bottleneck, the solution is redundancy. Multiple approvers can approve the same change type. Add more approvers to the rotation. Reduce the approval threshold—maybe 2 out of 3 approvers need to agree instead of unanimous. These changes prevent single points of failure.

When an approver is consistently too strict or too lenient, address it directly. If someone blocks 99% of changes, maybe they need coaching or maybe they have legitimate concerns about risk. Either way, it's a conversation you need to have. If someone approves 99% of changes, they're not providing value. Address this performance issue.

When approvals become slow, investigate. Is there a process bottleneck? Do approvers need reminders to check their queue? Is email notification not reaching them? Maybe you need in-app notifications with Slack integration. Speed matters—an approval that takes 8 hours is better than one that takes 3 days, but one that takes 15 minutes is better than 8 hours.

Approval Workflows for Different Risk Appetites

Not all organizations have the same risk tolerance. A startup might allow developers to provision production resources with minimal approval. An enterprise with strict SOC 2 requirements might require multiple approvals for any production change. A financial services company might require compliance approval for any change touching payment code. Your approval workflow should match your organization's risk appetite.

The way to implement this is through configuration. Define your organization's risk appetite at the top level—are you conservative, moderate, or aggressive? Then size your approval gates to match. Conservative organizations have high approval thresholds and broad veto power. Moderate organizations require approvals for high-risk changes only. Aggressive organizations trust developers and require approval only for critical systems.

Over time, your risk appetite might evolve. As your organization matures and gains confidence in your processes, you might become slightly less conservative. As you scale and incidents increase, you might become more conservative. Your approval workflow configuration should evolve with your organization.

The Future of Approval Workflows

As AI systems become more capable, approval workflows will become smarter. Machine learning could identify which approvers are most thorough. Natural language processing could extract decision reasoning and improve categorization. Blockchain-based audit trails could provide tamper-proof compliance evidence.

But the core principle remains: give humans visibility and control. Automation handles routine decisions. Complex decisions go to humans. Decisions are logged and auditable. This remains true whether you're using simple rules or advanced AI.

The future is not about removing humans from the process—it's about making the human decisions count. When humans only review genuinely complex or risky changes, their judgment is valuable. When they're reviewing routine changes, they're wasting time. The approval system's job is to distinguish between the two.

A well-designed approval workflow is invisible for most changes but crystal clear for important ones. That's the architecture that scales.

When you implement approval workflows correctly, something magical happens. People stop fighting the system. They understand that approvals protect them and their colleagues. They become advocates for the system rather than working around it. Developers realize that thoughtful review catches issues before they reach users. Approvers realize they're preventing real problems. The entire organization recognizes approval workflows as a safety feature, not a constraint. That shared understanding is what makes approval systems sustainable at scale.

The approval workflow is the backbone of safe automation. Without it, you're flying blind. With it, you can confidently deploy intelligent agents that handle complex operations. The governance layer enables the automation layer. This two-tier approach—governance enabling automation—is the future of enterprise systems. Get this right, and you unlock tremendous value.

When you implement approval workflows thoughtfully, they become invisible. Most changes flow through automatically. Important changes get human review. Everyone trusts the system. That trust is worth more than any technology. Build systems people trust. Invest in governance. Enable safe automation. That's how you scale.

Your approval workflow is a statement of your organization's values. What you require approval for shows what you care about. What you allow automatically shows what you trust. Design these workflows to reflect your actual priorities, not imagined risks. Then enforce them consistently. That discipline builds the trust that makes automation possible at scale. This is governance done right. Build it today. Your organization's future depends on getting this right.

---

-iNet