feat(aft): add aft_check command for on-demand type checker validation

Adds a new aft_check tool that runs the configured type checker
(ruff, tsc, pyright, etc.) on a single file and returns validation
errors. Intended for use after completing a batch of edits, not after
every intermediate edit.

Changes:
- commands/check.rs: new command handler calling validate_full
- subc_translate.rs: translate_check maps filePath to file
- subc_format.rs: format_check_response renders check results
- config.rs + config_resolve.rs: CheckConfig with check.enabled
  (default false); tool is only registered when enabled and checker
  config is non-empty
- opencode-plugin: tool definition, config schema, registration

Author: tobwen

crates/aft/src/commands/check.rs

@@ -0,0 +1,56 @@
+//! Handler for the `check` command: on-demand type checker validation.
+
+use std::path::Path;
+
+use crate::context::AppContext;
+use crate::format;
+use crate::protocol::{RawRequest, Response};
+
+/// Handle a `check` request.
+///
+/// Params:
+///   - `file` (string, required) - absolute path to the file to check
+///
+/// Returns: `{ file, error_count, errors?, skipped_reason? }`
+pub fn handle_check(req: &RawRequest, ctx: &AppContext) -> Response {
+    let file = match req.params.get("file").and_then(|v| v.as_str()) {
+        Some(f) => f,
+        None => {
+            return Response::error(
+                &req.id,
+                "invalid_request",
+                "check: missing required param 'file'",
+            );
+        }
+    };
+
+    let path = match ctx.validate_path(&req.id, Path::new(file)) {
+        Ok(p) => p,
+        Err(resp) => return resp,
+    };
+
+    if !path.is_file() {
+        return Response::error(
+            &req.id,
+            "invalid_request",
+            format!("check: path must be a file: {}", path.display()),
+        );
+    }
+
+    let config = ctx.config();
+    let (errors, skip_reason) = format::validate_full(&path, &config);
+
+    let mut result = serde_json::json!({
+        "file": file,
+        "error_count": errors.len(),
+    });
+
+    if !errors.is_empty() {
+        result["errors"] = serde_json::json!(errors);
+    }
+    if let Some(reason) = skip_reason {
+        result["skipped_reason"] = serde_json::json!(reason);
+    }
+
+    Response::success(&req.id, result)
+}

crates/aft/src/commands/mod.rs

@@ -14,6 +14,7 @@ pub mod bash_status;
 pub mod bash_wait_detach;
 pub mod bash_write;
 pub mod batch;
+pub mod check;
 pub mod call_tree;
 pub mod callers;
 pub mod callgraph_store_adapter;

crates/aft/src/config.rs

@@ -86,6 +86,12 @@ pub struct InspectConfig {
     pub duplicates: InspectDuplicatesConfig,
 }
 
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct CheckConfig {
+    pub enabled: bool,
+}
+
 #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(default)]
 pub struct InspectDuplicatesConfig {
@@ -193,6 +199,7 @@ pub struct Config {
     pub search_index_max_file_size: u64,
     pub semantic: SemanticBackendConfig,
     pub inspect: InspectConfig,
+    pub check: CheckConfig,
     pub backup: BackupConfig,
     /// Enable Astral ty as an experimental Python LSP server (default: false).
     pub experimental_lsp_ty: bool,
@@ -275,6 +282,7 @@ impl Default for Config {
             search_index_max_file_size: 1_048_576,
             semantic: SemanticBackendConfig::default(),
             inspect: InspectConfig::default(),
+            check: CheckConfig::default(),
             backup: BackupConfig::default(),
             experimental_lsp_ty: false,
             lsp_servers: Vec::new(),

crates/aft/src/config_resolve.rs

@@ -12,7 +12,7 @@ use serde::{Deserialize, Deserializer};
 use serde_json::{Map, Value};
 
 use crate::config::{
-    BackupConfig, Config, InspectConfig, SemanticBackend, SemanticBackendConfig, UserServerDef,
+    BackupConfig, CheckConfig, Config, InspectConfig, SemanticBackend, SemanticBackendConfig, UserServerDef,
 };
 use crate::jsonc::strip_jsonc;
 
@@ -90,6 +90,7 @@ pub struct RawAftConfig {
     #[serde(deserialize_with = "deserialize_opt_usize")]
     pub callgraph_chunk_size: Option<usize>,
     pub inspect: Option<RawInspect>,
+    pub check: Option<RawCheck>,
     pub backup: Option<RawBackup>,
     pub bash: Option<RawBash>,
     pub experimental: Option<RawExperimental>,
@@ -364,6 +365,18 @@ impl RawInspect {
     }
 }
 
+#[derive(Debug, Clone, Default, Deserialize, PartialEq)]
+#[serde(default)]
+pub struct RawCheck {
+    pub enabled: Option<bool>,
+}
+
+impl RawCheck {
+    fn is_empty(&self) -> bool {
+        self.enabled.is_none()
+    }
+}
+
 /// Only `expected_mirrors` survives here: `lower_bound`, `discard_cost`, and
 /// `anonymize` were accepted-but-never-read knobs (the scanner hardcodes its
 /// cost bounds and anonymization rules), so they were removed from the schema
@@ -569,6 +582,9 @@ fn merge_trusted_config(base: &mut RawAftConfig, override_config: RawAftConfig)
     if override_config.inspect.is_some() {
         base.inspect = override_config.inspect;
     }
+    if override_config.check.is_some() {
+        base.check = override_config.check;
+    }
     if override_config.backup.is_some() {
         base.backup = override_config.backup;
     }
@@ -636,6 +652,7 @@ fn merge_project_config(base: &mut RawAftConfig, project: RawAftConfig) {
     base.experimental = merge_experimental_config(base.experimental.clone(), project.experimental);
     base.bash = merge_bash_config(base.bash.clone(), project.bash);
     base.inspect = merge_inspect_config(base.inspect.clone(), project.inspect);
+    base.check = merge_check_config(base.check.clone(), project.check);
 }
 
 fn merge_formatter_map(
@@ -850,6 +867,18 @@ fn merge_inspect_config(
     (!inspect.is_empty()).then_some(inspect)
 }
 
+fn merge_check_config(
+    base: Option<RawCheck>,
+    override_check: Option<RawCheck>,
+) -> Option<RawCheck> {
+    let Some(override_check) = override_check else {
+        return base;
+    };
+    let mut check = base.unwrap_or_default();
+    check.enabled = override_check.enabled.or(check.enabled);
+    (!check.is_empty()).then_some(check)
+}
+
 fn merge_inspect_duplicates(
     base: Option<RawInspectDuplicates>,
     override_duplicates: Option<RawInspectDuplicates>,
@@ -990,6 +1019,7 @@ fn apply_resolved_config(raw: &RawAftConfig, config: &mut Config) {
     }
     config.semantic = resolve_semantic_config(raw.semantic.as_ref());
     config.inspect = resolve_inspect_config(raw.inspect.as_ref());
+    config.check = resolve_check_config(raw.check.as_ref());
     config.backup = resolve_backup_config(raw.backup.as_ref());
     resolve_lsp_config(raw, config);
     resolve_bash_fields(raw, config);
@@ -1044,6 +1074,16 @@ fn resolve_inspect_config(raw: Option<&RawInspect>) -> InspectConfig {
     inspect
 }
 
+fn resolve_check_config(raw: Option<&RawCheck>) -> CheckConfig {
+    let mut check = CheckConfig::default();
+    if let Some(raw) = raw {
+        if let Some(enabled) = raw.enabled {
+            check.enabled = enabled;
+        }
+    }
+    check
+}
+
 fn resolve_backup_config(raw: Option<&RawBackup>) -> BackupConfig {
     let mut backup = BackupConfig::default();
     if let Some(raw) = raw {
@@ -1996,4 +2036,28 @@ mod tests {
             Some("rustfmt")
         );
     }
+
+    #[test]
+    fn check_config_defaults_to_disabled() {
+        let result = resolve_config(&[tier("user", r#"{ "tool_surface": "all" }"#)]);
+        assert!(!result.config.check.enabled);
+    }
+
+    #[test]
+    fn check_config_enabled_via_user_tier() {
+        let result = resolve_config(&[tier(
+            "user",
+            r#"{ "check": { "enabled": true } }"#,
+        )]);
+        assert!(result.config.check.enabled);
+    }
+
+    #[test]
+    fn check_config_project_tier_overrides_user() {
+        let result = resolve_config(&[
+            tier("user", r#"{ "check": { "enabled": true } }"#),
+            tier("project", r#"{ "check": { "enabled": false } }"#),
+        ]);
+        assert!(!result.config.check.enabled);
+    }
 }

crates/aft/src/main.rs

@@ -702,6 +702,7 @@ fn dispatch(req: RawRequest, ctx: &AppContext) -> Response {
         "inline_symbol" => aft::commands::inline_symbol::handle_inline_symbol(&req, ctx),
         "inspect" => aft::commands::inspect::handle_inspect(&req, ctx),
         "inspect_tier2_run" => aft::commands::inspect::handle_inspect_tier2_run(&req, ctx),
+        "check" => aft::commands::check::handle_check(&req, ctx),
         "git_conflicts" => aft::commands::conflicts::handle_git_conflicts(ctx, &req),
         "ast_search" => aft::commands::ast_search::handle_ast_search(&req, ctx),
         "ast_replace" => aft::commands::ast_replace::handle_ast_replace(&req, ctx),

crates/aft/src/subc_format.rs

@@ -257,6 +257,7 @@ fn is_core_agent_tool(bare_name: &str) -> bool {
             | "import"
             | "refactor"
             | "safety"
+            | "check"
     )
 }
 
@@ -314,6 +315,7 @@ pub fn format_response_with_context(
         "import" => format_import(data, ctx),
         "refactor" => format_refactor(data, ctx),
         "safety" => format_safety(data, ctx),
+        "check" => format_check_response(data),
         _ => unreachable!("core agent tools are exhaustive"),
     }
 }
@@ -913,6 +915,31 @@ fn format_edit_response(data: &Value) -> String {
     result
 }
 
+fn format_check_response(data: &Value) -> String {
+    let file = data
+        .get("file")
+        .and_then(Value::as_str)
+        .unwrap_or("(unknown)");
+    let count = data
+        .get("error_count")
+        .and_then(Value::as_u64)
+        .unwrap_or(0) as usize;
+
+    if let Some(reason) = data.get("skipped_reason").and_then(Value::as_str) {
+        return format!("Checked {file} - validation skipped ({reason}).");
+    }
+
+    if count == 0 {
+        return format!("Checked {file} - no errors found.");
+    }
+
+    let mut output = format!("Checked {file} - {count} error(s):\n");
+    if let Some(errors) = data.get("errors").and_then(Value::as_array) {
+        output.push_str(&format_error_lines(errors));
+    }
+    output
+}
+
 fn format_glob_skip_reasons_note(reasons: Option<&Value>) -> Option<String> {
     let actionable = reasons?
         .as_array()?
@@ -989,6 +1016,25 @@ fn append_lsp_server_notes(output: &mut String, data: &Value) {
     }
 }
 
+fn format_error_lines(errors: &[Value]) -> String {
+    errors
+        .iter()
+        .map(|e| {
+            let line = e
+                .get("line")
+                .and_then(Value::as_u64)
+                .map(|n| n.to_string())
+                .unwrap_or_else(|| "undefined".to_string());
+            let message = e
+                .get("message")
+                .and_then(Value::as_str)
+                .unwrap_or("undefined");
+            format!("  Line {line}: {message}")
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
 // Mirrors packages/aft-bridge/src/edit-summary.ts formatEditSummary.
 fn format_edit_summary(data: &Value) -> String {
     if data.get("rolled_back").and_then(Value::as_bool) == Some(true) {
@@ -2776,3 +2822,53 @@ mod status_memory_tests {
         assert!(!rendered.contains("\"memory\""));
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn temp_file(name: &str) -> String {
+        let dir = tempfile::tempdir().expect("tempdir");
+        dir.path().join(name).to_string_lossy().into_owned()
+    }
+
+    #[test]
+    fn format_check_response_with_errors() {
+        let file = temp_file("check_test.py");
+        let data = json!({
+            "file": file,
+            "error_count": 2,
+            "errors": [
+                { "line": 1, "message": "F401: `os` imported but unused" },
+                { "line": 2, "message": "F401: `sys` imported but unused" }
+            ]
+        });
+        let text = format_check_response(&data);
+        assert!(text.contains("check_test.py"));
+        assert!(text.contains("2 error(s)"));
+        assert!(text.contains("Line 1: F401"));
+        assert!(text.contains("Line 2: F401"));
+    }
+
+    #[test]
+    fn format_check_response_no_errors() {
+        let file = temp_file("check_test.py");
+        let data = json!({ "file": file, "error_count": 0 });
+        let text = format_check_response(&data);
+        assert!(text.contains("no errors found"));
+    }
+
+    #[test]
+    fn format_check_response_skipped() {
+        let file = temp_file("check_test.py");
+        let data = json!({
+            "file": file,
+            "error_count": 0,
+            "skipped_reason": "no_checker_configured"
+        });
+        let text = format_check_response(&data);
+        assert!(text.contains("validation skipped"));
+        assert!(text.contains("no_checker_configured"));
+    }
+}

crates/aft/src/subc_translate.rs

@@ -195,6 +195,7 @@ pub fn subc_translate_with_context(
         "outline" => translate_outline(agent_args, project_root),
         "zoom" => translate_zoom(agent_args, project_root),
         "inspect" => translate_inspect(agent_args, project_root),
+        "check" => translate_check(agent_args, project_root),
         "callgraph" => translate_callgraph(agent_args, project_root),
         "conflicts" => translate_conflicts(agent_args),
         "ast_search" => translate_ast_search(agent_args),
@@ -1585,3 +1586,20 @@ fn translate_inspect(args: &Value, project_root: &Path) -> Result<Translated, Tr
         args: out,
     })
 }
+
+fn translate_check(args: &Value, project_root: &Path) -> Result<Translated, TranslateError> {
+    let map_in = agent_args_map(args);
+    let file_path = map_in
+        .get("filePath")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| invalid_request("'filePath' is required"))?;
+
+    let mut out = Map::new();
+    insert_resolved_file(&mut out, project_root, file_path);
+
+    Ok(Translated {
+        command: "check".into(),
+        args: out,
+    })
+}

packages/opencode-plugin/src/config.ts

@@ -325,6 +325,8 @@ export const AftConfigSchema = z.preprocess(
       callgraph_chunk_size: z.number().optional(),
       /** Codebase health inspection config. Enabled by default; set inspect.enabled=false to hide aft_inspect. */
       inspect: InspectConfigSchema.optional(),
+      /** On-demand type checker validation. Disabled by default; set check.enabled=true to expose aft_check. */
+      check: z.object({ enabled: z.boolean().optional() }).optional(),
       /** Undo backup config. User-only: project config cannot disable or shrink a user's safety net. */
       backup: BackupConfigSchema.optional(),
       /**