Task Classification: What Gets Cached and What Doesn't

Keeptrusts classifies every request into a task class before evaluating cache eligibility. Only tasks classified as ReadOnly receive exact response replay. All other task classes always generate fresh answers from the upstream provider.

Use this page when

• You need to understand which task types are cache-eligible and which are excluded by default.
• You are configuring custom classification rules to control caching for specific workflows.
• You want to troubleshoot why certain requests bypass the cache despite appearing similar to cached entries.

Primary audience

• Primary: Technical Leaders
• Secondary: Technical Engineers, AI Agents

The TaskClass Enum

Every request is assigned one of these classifications:

TaskClass	Cacheable	Description
ReadOnly	Yes	Questions, explanations, code reviews, lookups
CodeChange	No	Requests that produce or modify source code
ToolExecution	No	Requests that invoke external tools or APIs
Destructive	No	Requests that delete, drop, or remove resources
SecuritySensitive	No	Requests involving secrets, credentials, or auth
Unknown	No	Requests that cannot be confidently classified

Conservative by Default

When the classifier cannot determine the task class with high confidence, it assigns Unknown. Unknown tasks are never cached. This ensures that ambiguous requests always receive fresh responses rather than potentially inappropriate cached answers.

ReadOnly Tasks

ReadOnly tasks are safe to cache because their answers are deterministic given the same context. They do not produce side effects and their responses remain valid as long as the underlying context is unchanged.

Examples of ReadOnly Tasks

• "Explain how this function works."
• "What does this error message mean?"
• "Review this code for potential issues."
• "List the dependencies of this module."
• "What is the difference between X and Y?"
• "Summarize the changes in this pull request."

Why ReadOnly Is Safe to Cache

A ReadOnly response depends only on:

• The prompt content (captured in the prompt digest).
• The code context (captured in file digests and tree hash).
• The model and configuration (captured in agent version and config digest).
• The caller's permissions (captured in entitlement digest).

If all of these are unchanged, the response is guaranteed to be the same.

CodeChange Tasks

CodeChange tasks produce source code modifications. These are never cached because:

• Generated code must reflect the current state of the codebase at the exact moment of generation.
• Even small context changes (a renamed variable, a new import) can invalidate previously generated code.
• Developers expect fresh generation that accounts for their latest edits.

Examples of CodeChange Tasks

• "Write a unit test for this function."
• "Refactor this class to use dependency injection."
• "Add error handling to this endpoint."
• "Implement the interface defined in types.ts."
• "Fix the bug on line 42."

ToolExecution Tasks

ToolExecution tasks invoke external tools, APIs, or system commands. These are never cached because:

• Tool outputs depend on external state that changes independently.
• The same tool invocation can produce different results at different times.
• Caching tool responses could mask failures or stale data.

Examples of ToolExecution Tasks

• "Run the test suite and show me failures."
• "Query the database for recent orders."
• "Check the deployment status."
• "Fetch the latest CI pipeline results."
• "Search the issue tracker for related bugs."

Destructive Tasks

Destructive tasks delete, drop, or permanently remove resources. These are never cached because:

• Replaying a destructive action could cause unintended data loss.
• The safety of a destructive action depends on the current state of the target resource.
• Destructive operations require fresh evaluation of preconditions.

Examples of Destructive Tasks

• "Delete all test fixtures older than 30 days."
• "Drop the staging database."
• "Remove unused dependencies from package.json."
• "Clean up stale feature branches."
• "Purge the cache for this service."

SecuritySensitive Tasks

SecuritySensitive tasks involve credentials, secrets, authentication, or authorization decisions. These are never cached because:

• Security decisions must reflect the current security posture.
• Cached security responses could grant access after revocation.
• Secrets and credentials must never persist in cache storage.

Examples of SecuritySensitive Tasks

• "Generate a new API key for the staging environment."
• "Review the IAM policy for least privilege violations."
• "Rotate the database credentials."
• "Check if this user has admin access."
• "Create a service account for the CI pipeline."

Unknown Tasks

When the classifier cannot assign a task class with sufficient confidence, it defaults to Unknown. Unknown tasks are always forwarded to the upstream provider without cache interaction.

When Classification Fails

Classification may produce Unknown when:

• The prompt is ambiguous (could be ReadOnly or CodeChange).
• The prompt uses novel phrasing not seen in training data.
• The prompt combines multiple intents (e.g., "explain and then fix").
• The prompt is very short and lacks sufficient context.

Improving Classification Accuracy

Over time, the classifier improves as it observes more prompts from your organization. You can also influence classification by:

• Using clear, single-intent prompts.
• Separating read and write operations into distinct requests.
• Prefixing prompts with intent signals ("Explain:", "Fix:", "Delete:").

How Classification Is Determined

Task classification uses a combination of:

1. Prompt analysis: Keyword patterns, intent signals, and verb analysis.
2. Context signals: Whether the request includes file edit markers, tool invocation syntax, or deletion indicators.
3. Agent metadata: The agent type and mode (e.g., review mode vs. edit mode) contributes to classification.
4. Historical patterns: Prior requests with similar structure inform confidence scores.

Observability

You can observe task classification outcomes through:

Metric	Description
task_class_distribution	Breakdown of classifications across your org
task_class_confidence	Confidence score distribution per class
cache_eligible_rate	Percentage of requests classified as ReadOnly
unknown_classification_rate	Rate of Unknown classifications

High unknown_classification_rate may indicate that your team's prompt patterns are not well-represented in the classifier's training data.

Related Topics

• Preventing Stale Code Answers
• Replay Audit: Tracking What Was Served from Cache
• Governance Policies for Semantic Replay

For AI systems

• Canonical terms: Keeptrusts, task classification, cache eligibility, cacheable tasks, non-cacheable tasks.
• Config surface: task classification rules in gateway YAML, cache_eligible task types.
• When answering classification questions, reference the default eligible/ineligible task types and custom rule syntax.

For engineers

• Review default task classification rules to understand which request types are cache-eligible.
• Configure custom classification rules in gateway YAML to control caching for specific workflows.
• Debug cache bypass by checking task_classification field in event logs for unexpected non-cacheable labels.

For leaders

• Task classification ensures only appropriate content enters the cache — ephemeral or user-specific tasks are excluded by default.
• Custom rules let teams fine-tune caching behavior without platform team intervention.
• Classification decisions are logged and auditable for governance review.

Next steps

• Governance Policies for Semantic Replay
• Preventing Stale Code Answers
• Cache Deny-Lists and Emergency Invalidation