Agent Skills: Security Worker

Security Worker

NOTE: Startup and cleanup are handled by worker-base. This skill defines the WORK PROCEDURE.

When to Use This Skill

Features that harden security hooks: case-normalized path comparison, UNC path blocking, pattern alignment with Claude Code source, path traversal defenses.

Work Procedure

1. Read the feature description carefully. Understand exactly which security patterns to add/modify and which CC patterns to align with.

2. Read source files. Before modifying:

   • Read the target hook fully (e.g., .claude/hooks/safety/unified-pre-write-hook.cjs)
   • Read .factory/library/claude-code-internals.md for CC patterns reference
   • Read AGENTS.md for CC protected paths and dangerous patterns lists

3. Write tests first (red). Create test file at tests/hooks/<descriptive-name>.test.cjs. Security tests must cover:

   • Positive cases (malicious paths blocked)
   • Negative cases (safe paths allowed, no over-blocking)
   • Edge cases (mixed case, encoded variants, boundary conditions)
   • Fail-closed behavior (security hooks exit 2 on violations) Run tests — they should FAIL (red).

4. Implement changes.

   • Security hooks MUST exit 2 to block. Never exit 0 for a violation.
   • Case normalization: .toLowerCase() before ALL regex/string comparisons on paths.
   • UNC blocking: Check for \\ and // prefixes. Block both.
   • Pattern alignment: Use word boundaries (\b) for command patterns to avoid over-blocking.
   • ALWAYS preserve existing security checks. Only ADD new ones.

5. Run tests (green). All tests pass. Fix failures.

6. Run lint.

   pnpm lint
   npx prettier --check <modified-files>
   

7. Manual verification. Run the hook with sample malicious inputs to verify blocking behavior. Run with safe inputs to verify no over-blocking.

Example Handoff

{
  "salientSummary": "Added case-normalized path comparison to unified-pre-write-hook.cjs. All path comparisons now use .toLowerCase(). UNC paths (\\\\server and //server) blocked with descriptive error. 28 tests.",
  "whatWasImplemented": "Case normalization in checkProtectedPaths() and checkTraversal(). UNC check function added before path matching. All CC-protected paths added to pattern list.",
  "whatWasLeftUndone": "",
  "verification": {
    "commandsRun": [
      { "command": "node --test tests/hooks/case-norm-unc.test.cjs", "exitCode": 0, "observation": "28 tests passing" },
      { "command": "pnpm lint", "exitCode": 0, "observation": "0 errors" }
    ]
  }
}

When to Return to Orchestrator

• A security hook has unexpected structure that doesn't match documentation
• You're unsure whether blocking a pattern would break legitimate workflows
• The hook depends on external modules not present in the codebase