coding_tools/cli/
ct_steer.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 Jonathan Shook
3
4//! The `ct-steer` command grammar (see [`crate::cli`]). Like `ct-okf`, this
5//! tool is **subcommand**-shaped (`ct steer hook`, `ct steer install`, …)
6//! because its surface spans the runtime hook, settings installation, and a
7//! dry-run check. The `ct-steer` bin is a parse-and-dispatch wrapper over this
8//! `Cli`.
9//!
10//! Global flags (`--json`, `--quiet`, `--timeout`, the heartbeat, `--explain`)
11//! are declared `global` so they may appear before or after the subcommand;
12//! per-verb flags live on each subcommand's args struct.
13
14use clap::{Args, Parser, Subcommand};
15
16use crate::explain::Format;
17use crate::pulse::HeartbeatOpts;
18
19#[derive(Parser, Debug)]
20#[command(
21    name = "ct-steer",
22    version,
23    about = "Steer ad-hoc shell commands to the ct tool that serves them; install the PreToolUse hook.",
24    long_about = "ct-steer recognises the shell idioms a ct tool serves better (find | xargs grep, \
25                  sed -i, cat | head, for-loops, && / || chains) and, as a Claude Code PreToolUse \
26                  hook, steers the agent to the ct equivalent instead. Also reachable as `ct steer`. \
27                  Subcommands: `hook` is the runtime hook (reads a PreToolUse envelope on stdin); \
28                  `install`/`uninstall` wire it into .claude/settings.json; `check` shows what the \
29                  hook would decide for a command. See `ct-steer --explain` for agent docs."
30)]
31pub struct Cli {
32    #[command(subcommand)]
33    pub command: Option<Command>,
34
35    /// Emit a structured JSON result instead of text (where applicable).
36    #[arg(long, global = true)]
37    pub json: bool,
38
39    /// Suppress informational output (exit status still reports).
40    #[arg(long, global = true)]
41    pub quiet: bool,
42
43    /// Abort with exit 2 if the run exceeds SECS seconds (fractional allowed).
44    #[arg(long, value_name = "SECS", global = true)]
45    pub timeout: Option<f64>,
46
47    #[command(flatten)]
48    pub heartbeat: HeartbeatOpts,
49
50    /// Print agent usage docs (md or json) and exit.
51    #[arg(long, value_enum, num_args = 0..=1, default_missing_value = "md")]
52    pub explain: Option<Format>,
53}
54
55/// The `ct-steer` verbs.
56#[derive(Subcommand, Debug)]
57pub enum Command {
58    /// Runtime PreToolUse hook: read a tool-call envelope on stdin, emit a decision.
59    Hook(HookArgs),
60    /// Merge the steering hook into a Claude Code settings file.
61    Install(InstallArgs),
62    /// Remove the steering hook from a Claude Code settings file.
63    Uninstall(InstallArgs),
64    /// Show (and exit-code) what the hook would decide for a command string.
65    Check(CheckArgs),
66}
67
68/// How the hook steers a matched command.
69#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
70pub enum Mode {
71    /// Block the call and feed the ct suggestion back to the agent (default).
72    Deny,
73    /// Surface a confirmation prompt naming the ct suggestion.
74    Ask,
75    /// Allow the call, but inject the ct suggestion as context.
76    Warn,
77}
78
79impl Mode {
80    /// Bridge to the library's mode.
81    pub fn to_lib(self) -> crate::steer::Mode {
82        match self {
83            Mode::Deny => crate::steer::Mode::Deny,
84            Mode::Ask => crate::steer::Mode::Ask,
85            Mode::Warn => crate::steer::Mode::Warn,
86        }
87    }
88}
89
90/// Which settings file `install`/`uninstall` target.
91#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
92pub enum Scope {
93    /// .claude/settings.json (shared, committed).
94    Project,
95    /// .claude/settings.local.json (personal, gitignored).
96    Local,
97    /// ~/.claude/settings.json (all projects).
98    User,
99}
100
101impl Scope {
102    /// Bridge to the library's scope.
103    pub fn to_lib(self) -> crate::steer::install::Scope {
104        match self {
105            Scope::Project => crate::steer::install::Scope::Project,
106            Scope::Local => crate::steer::install::Scope::Local,
107            Scope::User => crate::steer::install::Scope::User,
108        }
109    }
110}
111
112#[derive(Args, Debug)]
113pub struct HookArgs {
114    /// Steering action on a match: deny (default), ask, or warn.
115    #[arg(long, value_enum, default_value_t = Mode::Deny)]
116    pub mode: Mode,
117}
118
119#[derive(Args, Debug)]
120pub struct InstallArgs {
121    /// Which settings file to write: project (default), local, or user.
122    #[arg(long, value_enum, default_value_t = Scope::Project)]
123    pub scope: Scope,
124
125    /// The steering action baked into the installed hook command.
126    #[arg(long, value_enum, default_value_t = Mode::Deny)]
127    pub mode: Mode,
128
129    /// Show the resulting settings file without writing it.
130    #[arg(long)]
131    pub dry_run: bool,
132
133    /// Print just the hook snippet (for manual paste) and exit.
134    #[arg(long)]
135    pub print: bool,
136}
137
138#[derive(Args, Debug)]
139pub struct CheckArgs {
140    /// The shell command to classify.
141    #[arg(value_name = "COMMAND", required = true)]
142    pub command: String,
143
144    /// The steering action to report (affects the printed decision only).
145    #[arg(long, value_enum, default_value_t = Mode::Deny)]
146    pub mode: Mode,
147}
coding_tools/cli/ct_steer.rs

coding_tools/cli/
ct_steer.rs
