gstack Safety: Using Careful, Freeze, and Guard

There's a paradox in AI-assisted development: the same power that makes AI agents so productive also makes them capable of causing significant damage if they operate without appropriate constraints.

An AI agent that can execute code, run database migrations, push to git, and deploy to production needs guardrails — not because the AI is malicious, but because mistakes are possible and some mistakes are very hard to undo.

gstack's safety tools — careful, freeze, guard, and unfreeze — are those guardrails. They're not just for beginners. They're for anyone operating in a system where the cost of a mistake is high.

The Philosophy Behind Safety Tools#

Before the mechanics, the philosophy.

In traditional software development, safety comes from access controls: developers don't have production database access, deploying requires multiple approvals, deleting records requires admin privileges. These controls work through restriction.

In AI-assisted development, you often want the agent to have broad access (because capability is the point), but you need safety to come from explicit awareness and confirmation, not restriction.

The gstack safety tools implement this: they don't prevent actions — they create intentional checkpoints that force you to confirm that a potentially destructive action is truly intended.

This is good engineering practice regardless of AI involvement. The careful/guard/freeze pattern is useful any time a developer is working in an unfamiliar part of the codebase, on a time-sensitive task, or with access to systems where mistakes are expensive.

careful: The Confirmation Gate#

careful mode activates warnings before potentially destructive operations.

When careful is active, the agent pauses before executing:

• rm -rf or any bulk file deletion
• DROP TABLE, TRUNCATE, or bulk DELETE SQL
• Force pushes (git push --force)
• Destructive database migrations
• Unrecoverable data transformations
• Bulk production data updates

The pause includes:

• What operation is about to execute
• What the effects will be
• A confirmation prompt before proceeding

In DenchClaw's gstack workflow, careful mode is active by default in any session that has access to production data or the main branch.

When to Use careful#

• Always, when working with production databases
• When executing a script that touches real customer data
• When running a migration on a live database
• When the consequences of an error are hard to reverse
• When you're tired, rushed, or context-switching frequently

careful adds seconds to destructive operations. It prevents irreversible mistakes.

The careful Prompt#

When careful catches a potentially destructive operation:

⚠️  CAREFUL MODE — Confirmation Required

Operation: DELETE FROM entries WHERE object_id = 'legacy_contacts'
Effect: This will permanently delete 2,847 records
Table: entries (production)
Reversibility: LOW — no automatic backup

Are you sure you want to proceed?
Type 'yes, delete 2847 records' to confirm, or press Ctrl+C to cancel.

The confirmation is intentionally specific — you have to type the exact number of records to confirm. This prevents the lazy "yes" that happens when the confirmation prompt is just "y/n."

freeze: The Boundary Setter#

freeze restricts the agent to operating only within a specified directory.

When freeze is active, any operation that touches files outside the frozen boundary fails with a clear error:

🔒 FROZEN — Operation blocked

Attempted to modify: /Users/me/project/src/services/payments.ts
Frozen to: /Users/me/project/src/components/

This operation is outside the frozen boundary. Use 'unfreeze' to remove
the boundary before operating outside /src/components/.

When to Use freeze#

• When working on a specific component and you don't want to accidentally touch shared utilities
• When onboarding a new contributor who should only work in their assigned area
• When doing a focused refactor that should stay within specific bounds
• When an AI agent is working autonomously and you want to limit its scope

freeze is most valuable when running autonomous multi-step operations. If you ask gstack to "refactor all the dashboard components for consistency," freezing to /src/components/dashboard/ ensures the refactor stays within scope and doesn't accidentally touch other components with similar names.

The freeze Command#

# Freeze to a specific directory
gstack freeze /src/components/dashboard
 
# Check current freeze status
gstack freeze --status
 
# Remove the freeze
gstack unfreeze

guard: The Combined Safeguard#

guard combines careful and freeze into a single command — maximum safety for high-stakes operations.

With guard active:

• You must confirm before any destructive operation (careful behavior)
• Operations are restricted to the specified boundary (freeze behavior)

# Guard a session to the components directory
gstack guard /src/components/dashboard

This is the mode for autonomous operations that are time-consuming and touch potentially sensitive areas. You want the agent to have broad permissions within a bounded scope, with confirmation required for anything destructive.

When to Use guard#

• Long-running autonomous refactors
• Any time the agent is operating with minimal human supervision
• Database cleanup operations with a specific scope
• Deployment scripts that should only touch certain files

unfreeze: Lifting the Boundary#

unfreeze removes an active freeze or guard boundary, restoring full operation scope.

gstack unfreeze

Always unfreeze explicitly when you're done with the bounded operation. Don't rely on the freeze expiring automatically — the explicit unfreeze is part of the workflow consciousness that makes safety tools useful.

Safety Tools and Trust#

There's a tempting shortcut: "I trust the AI, I'll skip the safety confirmation."

This logic fails because trust isn't the issue. The issue is that mistakes happen in AI-assisted development just as they do in human development. An AI that confidently executes a destructive command based on a misunderstood requirement is the classic problem — not malice, but mistake.

The safety tools create a forcing function for human confirmation at the moments when mistakes are most costly. They're most useful precisely when you trust the AI — because trust without verification is how expensive mistakes get made.

Real-World Safety Scenarios#

Scenario 1: Database migration on production

You're running a schema migration that drops a column. careful mode:

1. Shows you the exact migration SQL
2. Shows you how many rows will be affected
3. Shows you that the column still has data (maybe you thought it was empty)
4. Asks for explicit confirmation

You realize the column isn't actually empty. You fix the migration to archive the data before dropping the column. careful prevented data loss.

Scenario 2: Refactoring a shared utility

gstack is refactoring your authentication utilities. You want it to update the utility functions but not change how they're called in the application code (that's a separate PR). freeze to the src/utils/auth/ directory ensures the refactor stays in bounds.

Scenario 3: Bulk data update

Updating all lead records to add a missing field. careful prompts with the count (2,400 records) and the exact SQL. You notice the WHERE clause is slightly off — it would update ALL records, not just leads. You fix it before executing. Data integrity preserved.

Frequently Asked Questions#

Should careful always be active?#

In sessions with production data access: yes. In development-only environments: optional. The overhead is minimal (a few seconds per destructive operation) and the protection is real.

What's the difference between freeze and standard file permissions?#

File permissions work at the OS level and persist across processes. freeze works at the gstack agent level and applies to the current session. freeze is for behavioral scoping (this session should stay within these files) rather than access control (this user should never touch these files). Both have their place.

Can guard be bypassed?#

Yes — you can unfreeze at any time. The safety tools are designed to create intentional friction, not to be unbreakable. The goal is that bypassing requires a deliberate action, which creates awareness. If the right action is to unfreeze, that's a valid choice — you're just making it consciously.

Should safety tools be used in CI/CD pipelines?#

careful mode in a CI pipeline would break automated workflows (it requires human confirmation). freeze in CI can be useful for limiting the scope of automated agents. Use safety tools for human-in-the-loop workflows; use proper access controls for fully automated systems.

How do safety tools interact with git?#

careful mode adds confirmation before force pushes, deleting branches, or operations that rewrite history. It doesn't add friction to normal git operations (commit, push, pull, merge). The threshold is operations that are difficult to reverse.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →